1QEMU-QMP-REF(7) QEMU QEMU-QMP-REF(7)
2
6 qemu-qmp-ref - QEMU QMP Reference Manual
7 Contents
9 • QEMU QMP Reference Manual
10 • Introduction
12 • This document describes all commands currently supported by QMP.
14 • Stability Considerations
16 • The current QMP command set (described in this file) may be use‐
18 ful for a number of use cases, however it's limited and several
19 commands have bad defined semantics, specially with regard to
20 command completion.
21 • QMP errors
23 • QapiErrorClass (Enum)
25 • Common data types
27 • IoOperationType (Enum)
29 • OnOffAuto (Enum)
31 • OnOffSplit (Enum)
33 • String (Object)
35 • StrOrNull (Alternate)
37 • OffAutoPCIBAR (Enum)
39 • PCIELinkSpeed (Enum)
41 • PCIELinkWidth (Enum)
43 • HostMemPolicy (Enum)
45 • NetFilterDirection (Enum)
47 • GrabToggleKeys (Enum)
49 • Socket data types
51 • NetworkAddressFamily (Enum)
53 • InetSocketAddressBase (Object)
55 • InetSocketAddress (Object)
57 • UnixSocketAddress (Object)
59 • VsockSocketAddress (Object)
61 • SocketAddressLegacy (Object)
63 • SocketAddressType (Enum)
65 • SocketAddress (Object)
67 • VM run state
69 • RunState (Enum)
71 • ShutdownCause (Enum)
73 • StatusInfo (Object)
75 • query-status (Command)
77 • SHUTDOWN (Event)
79 • POWERDOWN (Event)
81 • RESET (Event)
83 • STOP (Event)
85 • RESUME (Event)
87 • SUSPEND (Event)
89 • SUSPEND_DISK (Event)
91 • WAKEUP (Event)
93 • WATCHDOG (Event)
95 • WatchdogAction (Enum)
97 • RebootAction (Enum)
99 • ShutdownAction (Enum)
101 • PanicAction (Enum)
103 • watchdog-set-action (Command)
105 • set-action (Command)
107 • GUEST_PANICKED (Event)
109 • GUEST_CRASHLOADED (Event)
111 • GuestPanicAction (Enum)
113 • GuestPanicInformationType (Enum)
115 • GuestPanicInformation (Object)
117 • GuestPanicInformationHyperV (Object)
119 • S390CrashReason (Enum)
121 • GuestPanicInformationS390 (Object)
123 • MEMORY_FAILURE (Event)
125 • MemoryFailureRecipient (Enum)
127 • MemoryFailureAction (Enum)
129 • MemoryFailureFlags (Object)
131 • Cryptography
133 • QCryptoTLSCredsEndpoint (Enum)
135 • QCryptoSecretFormat (Enum)
137 • QCryptoHashAlgorithm (Enum)
139 • QCryptoCipherAlgorithm (Enum)
141 • QCryptoCipherMode (Enum)
143 • QCryptoIVGenAlgorithm (Enum)
145 • QCryptoBlockFormat (Enum)
147 • QCryptoBlockOptionsBase (Object)
149 • QCryptoBlockOptionsQCow (Object)
151 • QCryptoBlockOptionsLUKS (Object)
153 • QCryptoBlockCreateOptionsLUKS (Object)
155 • QCryptoBlockOpenOptions (Object)
157 • QCryptoBlockCreateOptions (Object)
159 • QCryptoBlockInfoBase (Object)
161 • QCryptoBlockInfoLUKSSlot (Object)
163 • QCryptoBlockInfoLUKS (Object)
165 • QCryptoBlockInfo (Object)
167 • QCryptoBlockLUKSKeyslotState (Enum)
169 • QCryptoBlockAmendOptionsLUKS (Object)
171 • QCryptoBlockAmendOptions (Object)
173 • SecretCommonProperties (Object)
175 • SecretProperties (Object)
177 • SecretKeyringProperties (Object)
179 • TlsCredsProperties (Object)
181 • TlsCredsAnonProperties (Object)
183 • TlsCredsPskProperties (Object)
185 • TlsCredsX509Properties (Object)
187 • Block devices
189 • Block core (VM unrelated)
191 • Background jobs
193 • Additional block stuff (VM related)
195 • Block device exports
197 • Character devices
199 • ChardevInfo (Object)
201 • query-chardev (Command)
203 • ChardevBackendInfo (Object)
205 • query-chardev-backends (Command)
207 • DataFormat (Enum)
209 • ringbuf-write (Command)
211 • ringbuf-read (Command)
213 • ChardevCommon (Object)
215 • ChardevFile (Object)
217 • ChardevHostdev (Object)
219 • ChardevSocket (Object)
221 • ChardevUdp (Object)
223 • ChardevMux (Object)
225 • ChardevStdio (Object)
227 • ChardevSpiceChannel (Object)
229 • ChardevSpicePort (Object)
231 • ChardevVC (Object)
233 • ChardevRingbuf (Object)
235 • ChardevQemuVDAgent (Object)
237 • ChardevBackend (Object)
239 • ChardevReturn (Object)
241 • chardev-add (Command)
243 • chardev-change (Command)
245 • chardev-remove (Command)
247 • chardev-send-break (Command)
249 • VSERPORT_CHANGE (Event)
251 • Dump guest memory
253 • DumpGuestMemoryFormat (Enum)
255 • dump-guest-memory (Command)
257 • DumpStatus (Enum)
259 • DumpQueryResult (Object)
261 • query-dump (Command)
263 • DUMP_COMPLETED (Event)
265 • DumpGuestMemoryCapability (Object)
267 • query-dump-guest-memory-capability (Command)
269 • Net devices
271 • set_link (Command)
273 • netdev_add (Command)
275 • netdev_del (Command)
277 • NetLegacyNicOptions (Object)
279 • NetdevUserOptions (Object)
281 • NetdevTapOptions (Object)
283 • NetdevSocketOptions (Object)
285 • NetdevL2TPv3Options (Object)
287 • NetdevVdeOptions (Object)
289 • NetdevBridgeOptions (Object)
291 • NetdevHubPortOptions (Object)
293 • NetdevNetmapOptions (Object)
295 • NetdevVhostUserOptions (Object)
297 • NetdevVhostVDPAOptions (Object)
299 • NetClientDriver (Enum)
301 • Netdev (Object)
303 • RxState (Enum)
305 • RxFilterInfo (Object)
307 • query-rx-filter (Command)
309 • NIC_RX_FILTER_CHANGED (Event)
311 • AnnounceParameters (Object)
313 • announce-self (Command)
315 • FAILOVER_NEGOTIATED (Event)
317 • RDMA device
319 • RDMA_GID_STATUS_CHANGED (Event)
321 • Rocker switch device
323 • RockerSwitch (Object)
325 • query-rocker (Command)
327 • RockerPortDuplex (Enum)
329 • RockerPortAutoneg (Enum)
331 • RockerPort (Object)
333 • query-rocker-ports (Command)
335 • RockerOfDpaFlowKey (Object)
337 • RockerOfDpaFlowMask (Object)
339 • RockerOfDpaFlowAction (Object)
341 • RockerOfDpaFlow (Object)
343 • query-rocker-of-dpa-flows (Command)
345 • RockerOfDpaGroup (Object)
347 • query-rocker-of-dpa-groups (Command)
349 • TPM (trusted platform module) devices
351 • TpmModel (Enum)
353 • query-tpm-models (Command)
355 • TpmType (Enum)
357 • query-tpm-types (Command)
359 • TPMPassthroughOptions (Object)
361 • TPMEmulatorOptions (Object)
363 • TpmTypeOptions (Object)
365 • TPMInfo (Object)
367 • query-tpm (Command)
369 • Remote desktop
371 • set_password (Command)
373 • expire_password (Command)
375 • screendump (Command)
377 • Spice
379 • VNC
381 • Input
383 • MouseInfo (Object)
385 • query-mice (Command)
387 • QKeyCode (Enum)
389 • KeyValue (Object)
391 • send-key (Command)
393 • InputButton (Enum)
395 • InputAxis (Enum)
397 • InputKeyEvent (Object)
399 • InputBtnEvent (Object)
401 • InputMoveEvent (Object)
403 • InputEvent (Object)
405 • input-send-event (Command)
407 • DisplayGTK (Object)
409 • DisplayEGLHeadless (Object)
411 • DisplayGLMode (Enum)
413 • DisplayCurses (Object)
415 • DisplayType (Enum)
417 • DisplayOptions (Object)
419 • query-display-options (Command)
421 • DisplayReloadType (Enum)
423 • DisplayReloadOptionsVNC (Object)
425 • DisplayReloadOptions (Object)
427 • display-reload (Command)
429 • User authorization
431 • QAuthZListPolicy (Enum)
433 • QAuthZListFormat (Enum)
435 • QAuthZListRule (Object)
437 • AuthZListProperties (Object)
439 • AuthZListFileProperties (Object)
441 • AuthZPAMProperties (Object)
443 • AuthZSimpleProperties (Object)
445 • Migration
447 • MigrationStats (Object)
449 • XBZRLECacheStats (Object)
451 • CompressionStats (Object)
453 • MigrationStatus (Enum)
455 • VfioStats (Object)
457 • MigrationInfo (Object)
459 • query-migrate (Command)
461 • MigrationCapability (Enum)
463 • MigrationCapabilityStatus (Object)
465 • migrate-set-capabilities (Command)
467 • query-migrate-capabilities (Command)
469 • MultiFDCompression (Enum)
471 • BitmapMigrationBitmapAliasTransform (Object)
473 • BitmapMigrationBitmapAlias (Object)
475 • BitmapMigrationNodeAlias (Object)
477 • MigrationParameter (Enum)
479 • MigrateSetParameters (Object)
481 • migrate-set-parameters (Command)
483 • MigrationParameters (Object)
485 • query-migrate-parameters (Command)
487 • client_migrate_info (Command)
489 • migrate-start-postcopy (Command)
491 • MIGRATION (Event)
493 • MIGRATION_PASS (Event)
495 • COLOMessage (Enum)
497 • COLOMode (Enum)
499 • FailoverStatus (Enum)
501 • COLO_EXIT (Event)
503 • COLOExitReason (Enum)
505 • x-colo-lost-heartbeat (Command)
507 • migrate_cancel (Command)
509 • migrate-continue (Command)
511 • migrate (Command)
513 • migrate-incoming (Command)
515 • xen-save-devices-state (Command)
517 • xen-set-global-dirty-log (Command)
519 • xen-load-devices-state (Command)
521 • xen-set-replication (Command)
523 • ReplicationStatus (Object)
525 • query-xen-replication-status (Command)
527 • xen-colo-do-checkpoint (Command)
529 • COLOStatus (Object)
531 • query-colo-status (Command)
533 • migrate-recover (Command)
535 • migrate-pause (Command)
537 • UNPLUG_PRIMARY (Event)
539 • DirtyRateStatus (Enum)
541 • DirtyRateInfo (Object)
543 • calc-dirty-rate (Command)
545 • query-dirty-rate (Command)
547 • snapshot-save (Command)
549 • snapshot-load (Command)
551 • snapshot-delete (Command)
553 • Transactions
555 • Abort (Object)
557 • ActionCompletionMode (Enum)
559 • TransactionAction (Object)
561 • TransactionProperties (Object)
563 • transaction (Command)
565 • Tracing
567 • TraceEventState (Enum)
569 • TraceEventInfo (Object)
571 • trace-event-get-state (Command)
573 • trace-event-set-state (Command)
575 • Compatibility policy
577 • CompatPolicyInput (Enum)
579 • CompatPolicyOutput (Enum)
581 • CompatPolicy (Object)
583 • QMP monitor control
585 • qmp_capabilities (Command)
587 • QMPCapability (Enum)
589 • VersionTriple (Object)
591 • VersionInfo (Object)
593 • query-version (Command)
595 • CommandInfo (Object)
597 • query-commands (Command)
599 • quit (Command)
601 • MonitorMode (Enum)
603 • MonitorOptions (Object)
605 • QMP introspection
607 • query-qmp-schema (Command)
609 • SchemaMetaType (Enum)
611 • SchemaInfo (Object)
613 • SchemaInfoBuiltin (Object)
615 • JSONType (Enum)
617 • SchemaInfoEnum (Object)
619 • SchemaInfoArray (Object)
621 • SchemaInfoObject (Object)
623 • SchemaInfoObjectMember (Object)
625 • SchemaInfoObjectVariant (Object)
627 • SchemaInfoAlternate (Object)
629 • SchemaInfoAlternateMember (Object)
631 • SchemaInfoCommand (Object)
633 • SchemaInfoEvent (Object)
635 • QEMU Object Model (QOM)
637 • ObjectPropertyInfo (Object)
639 • qom-list (Command)
641 • qom-get (Command)
643 • qom-set (Command)
645 • ObjectTypeInfo (Object)
647 • qom-list-types (Command)
649 • qom-list-properties (Command)
651 • CanHostSocketcanProperties (Object)
653 • ColoCompareProperties (Object)
655 • CryptodevBackendProperties (Object)
657 • CryptodevVhostUserProperties (Object)
659 • DBusVMStateProperties (Object)
661 • NetfilterInsert (Enum)
663 • NetfilterProperties (Object)
665 • FilterBufferProperties (Object)
667 • FilterDumpProperties (Object)
669 • FilterMirrorProperties (Object)
671 • FilterRedirectorProperties (Object)
673 • FilterRewriterProperties (Object)
675 • InputBarrierProperties (Object)
677 • InputLinuxProperties (Object)
679 • IothreadProperties (Object)
681 • MemoryBackendProperties (Object)
683 • MemoryBackendFileProperties (Object)
685 • MemoryBackendMemfdProperties (Object)
687 • PrManagerHelperProperties (Object)
689 • QtestProperties (Object)
691 • RemoteObjectProperties (Object)
693 • RngProperties (Object)
695 • RngEgdProperties (Object)
697 • RngRandomProperties (Object)
699 • SevGuestProperties (Object)
701 • ObjectType (Enum)
703 • ObjectOptions (Object)
705 • object-add (Command)
707 • object-del (Command)
709 • Device infrastructure (qdev)
711 • device-list-properties (Command)
713 • device_add (Command)
715 • device_del (Command)
717 • DEVICE_DELETED (Event)
719 • Machines
721 • SysEmuTarget (Enum)
723 • CpuS390State (Enum)
725 • CpuInfoS390 (Object)
727 • CpuInfoFast (Object)
729 • query-cpus-fast (Command)
731 • MachineInfo (Object)
733 • query-machines (Command)
735 • CurrentMachineParams (Object)
737 • query-current-machine (Command)
739 • TargetInfo (Object)
741 • query-target (Command)
743 • UuidInfo (Object)
745 • query-uuid (Command)
747 • GuidInfo (Object)
749 • query-vm-generation-id (Command)
751 • system_reset (Command)
753 • system_powerdown (Command)
755 • system_wakeup (Command)
757 • LostTickPolicy (Enum)
759 • inject-nmi (Command)
761 • KvmInfo (Object)
763 • query-kvm (Command)
765 • NumaOptionsType (Enum)
767 • NumaOptions (Object)
769 • NumaNodeOptions (Object)
771 • NumaDistOptions (Object)
773 • X86CPURegister32 (Enum)
775 • X86CPUFeatureWordInfo (Object)
777 • DummyForceArrays (Object)
779 • NumaCpuOptions (Object)
781 • HmatLBMemoryHierarchy (Enum)
783 • HmatLBDataType (Enum)
785 • NumaHmatLBOptions (Object)
787 • HmatCacheAssociativity (Enum)
789 • HmatCacheWritePolicy (Enum)
791 • NumaHmatCacheOptions (Object)
793 • memsave (Command)
795 • pmemsave (Command)
797 • Memdev (Object)
799 • query-memdev (Command)
801 • CpuInstanceProperties (Object)
803 • HotpluggableCPU (Object)
805 • query-hotpluggable-cpus (Command)
807 • set-numa-node (Command)
809 • balloon (Command)
811 • BalloonInfo (Object)
813 • query-balloon (Command)
815 • BALLOON_CHANGE (Event)
817 • MemoryInfo (Object)
819 • query-memory-size-summary (Command)
821 • PCDIMMDeviceInfo (Object)
823 • VirtioPMEMDeviceInfo (Object)
825 • VirtioMEMDeviceInfo (Object)
827 • MemoryDeviceInfo (Object)
829 • query-memory-devices (Command)
831 • MEMORY_DEVICE_SIZE_CHANGE (Event)
833 • MEM_UNPLUG_ERROR (Event)
835 • SMPConfiguration (Object)
837 • CpuModelInfo (Object)
839 • CpuModelExpansionType (Enum)
841 • CpuModelCompareResult (Enum)
843 • CpuModelBaselineInfo (Object)
845 • CpuModelCompareInfo (Object)
847 • query-cpu-model-comparison (Command)
849 • query-cpu-model-baseline (Command)
851 • CpuModelExpansionInfo (Object)
853 • query-cpu-model-expansion (Command)
855 • CpuDefinitionInfo (Object)
857 • query-cpu-definitions (Command)
859 • Record/replay
861 • ReplayMode (Enum)
863 • ReplayInfo (Object)
865 • query-replay (Command)
867 • replay-break (Command)
869 • replay-delete-break (Command)
871 • replay-seek (Command)
873 • Yank feature
875 • YankInstanceType (Enum)
877 • YankInstanceBlockNode (Object)
879 • YankInstanceChardev (Object)
881 • YankInstance (Object)
883 • yank (Command)
885 • query-yank (Command)
887 • Miscellanea
889 • add_client (Command)
891 • NameInfo (Object)
893 • query-name (Command)
895 • IOThreadInfo (Object)
897 • query-iothreads (Command)
899 • stop (Command)
901 • cont (Command)
903 • x-exit-preconfig (Command)
905 • human-monitor-command (Command)
907 • getfd (Command)
909 • closefd (Command)
911 • AddfdInfo (Object)
913 • add-fd (Command)
915 • remove-fd (Command)
917 • FdsetFdInfo (Object)
919 • FdsetInfo (Object)
921 • query-fdsets (Command)
923 • CommandLineParameterType (Enum)
925 • CommandLineParameterInfo (Object)
927 • CommandLineOptionInfo (Object)
929 • query-command-line-options (Command)
931 • RTC_CHANGE (Event)
933 • rtc-reset-reinjection (Command)
935 • SevState (Enum)
937 • SevInfo (Object)
939 • query-sev (Command)
941 • SevLaunchMeasureInfo (Object)
943 • query-sev-launch-measure (Command)
945 • SevCapability (Object)
947 • query-sev-capabilities (Command)
949 • sev-inject-launch-secret (Command)
951 • dump-skeys (Command)
953 • GICCapability (Object)
955 • query-gic-capabilities (Command)
957 • SevAttestationReport (Object)
959 • query-sev-attestation-report (Command)
961 • Audio
963 • AudiodevPerDirectionOptions (Object)
965 • AudiodevGenericOptions (Object)
967 • AudiodevAlsaPerDirectionOptions (Object)
969 • AudiodevAlsaOptions (Object)
971 • AudiodevCoreaudioPerDirectionOptions (Object)
973 • AudiodevCoreaudioOptions (Object)
975 • AudiodevDsoundOptions (Object)
977 • AudiodevJackPerDirectionOptions (Object)
979 • AudiodevJackOptions (Object)
981 • AudiodevOssPerDirectionOptions (Object)
983 • AudiodevOssOptions (Object)
985 • AudiodevPaPerDirectionOptions (Object)
987 • AudiodevPaOptions (Object)
989 • AudiodevSdlPerDirectionOptions (Object)
991 • AudiodevSdlOptions (Object)
993 • AudiodevWavOptions (Object)
995 • AudioFormat (Enum)
997 • AudiodevDriver (Enum)
999 • Audiodev (Object)
1001 • ACPI
1003 • AcpiTableOptions (Object)
1005 • ACPISlotType (Enum)
1007 • ACPIOSTInfo (Object)
1009 • query-acpi-ospm-status (Command)
1011 • ACPI_DEVICE_OST (Event)
1013 • PCI
1015 • PciMemoryRange (Object)
1017 • PciMemoryRegion (Object)
1019 • PciBusInfo (Object)
1021 • PciBridgeInfo (Object)
1023 • PciDeviceClass (Object)
1025 • PciDeviceId (Object)
1027 • PciDeviceInfo (Object)
1029 • PciInfo (Object)
1031 • query-pci (Command)
1033
1035 This document describes all commands currently supported by QMP.
1036 Most of the time their usage is exactly the same as in the user Moni‐
1038 tor, this means that any other document which also describe commands
1039 (the manpage, QEMU's manual, etc) can and should be consulted.
1040 QMP has two types of commands: regular and query commands. Regular com‐
1042 mands usually change the Virtual Machine's state someway, while query
1043 commands just return information. The sections below are divided ac‐
1044 cordingly.
1045 It's important to observe that all communication examples are formatted
1047 in a reader-friendly way, so that they're easier to understand. How‐
1048 ever, in real protocol usage, they're emitted as a single line.
1049 Also, the following notation is used to denote data flow:
1051 Example:
1053 -> data issued by the Client
1055 <- Server data response
1056 Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
1058 detailed information on the Server command and response formats.
1059
1061 The current QMP command set (described in this file) may be useful for
1062 a number of use cases, however it's limited and several commands have
1063 bad defined semantics, specially with regard to command completion.
1064 These problems are going to be solved incrementally in the next QEMU
1066 releases and we're going to establish a deprecation policy for badly
1067 defined commands.
1068 If you're planning to adopt QMP, please observe the following:
1070 1. The deprecation policy will take effect and be documented soon,
1072 please check the documentation of each used command as soon as a
1073 new release of QEMU is available
1074 2. DO NOT rely on anything which is not explicit documented
1076 3. Errors, in special, are not documented. Applications should NOT
1078 check for specific errors classes or data (it's strongly recom‐
1079 mended to only check for the "error" key)
1080
1082 QapiErrorClass (Enum)
1083 QEMU error classes
1084 Values
1086 GenericError
1087 this is used for errors that don't require a specific error
1088 class. This should be the default case for most errors
1089 CommandNotFound
1091 the requested command has not been found
1092 DeviceNotActive
1094 a device has failed to be become active
1095 DeviceNotFound
1097 the requested device has not been found
1098 KVMMissingCap
1100 the requested operation can't be fulfilled because a required
1101 KVM capability is missing
1102 Since
1104 1.2
1105
1107 IoOperationType (Enum)
1108 An enumeration of the I/O operation types
1109 Values
1111 read read operation
1112 write write operation
1114 Since
1116 2.1
1117 OnOffAuto (Enum)
1119 An enumeration of three options: on, off, and auto
1120 Values
1122 auto QEMU selects the value between on and off
1123 on Enabled
1125 off Disabled
1127 Since
1129 2.2
1130 OnOffSplit (Enum)
1132 An enumeration of three values: on, off, and split
1133 Values
1135 on Enabled
1136 off Disabled
1138 split Mixed
1140 Since
1142 2.6
1143 String (Object)
1145 A fat type wrapping 'str', to be embedded in lists.
1146 Members
1148 str: string
1149 Not documented
1150 Since
1152 1.2
1153 StrOrNull (Alternate)
1155 This is a string value or the explicit lack of a string (null pointer
1156 in C). Intended for cases when 'optional absent' already has a differ‐
1157 ent meaning.
1158 Members
1160 s: string
1161 the string value
1162 n: null
1164 no string value
1165 Since
1167 2.10
1168 OffAutoPCIBAR (Enum)
1170 An enumeration of options for specifying a PCI BAR
1171 Values
1173 off The specified feature is disabled
1174 auto The PCI BAR for the feature is automatically selected
1176 bar0 PCI BAR0 is used for the feature
1178 bar1 PCI BAR1 is used for the feature
1180 bar2 PCI BAR2 is used for the feature
1182 bar3 PCI BAR3 is used for the feature
1184 bar4 PCI BAR4 is used for the feature
1186 bar5 PCI BAR5 is used for the feature
1188 Since
1190 2.12
1191 PCIELinkSpeed (Enum)
1193 An enumeration of PCIe link speeds in units of GT/s
1194 Values
1196 2_5 2.5GT/s
1197 5 5.0GT/s
1199 8 8.0GT/s
1201 16 16.0GT/s
1203 Since
1205 4.0
1206 PCIELinkWidth (Enum)
1208 An enumeration of PCIe link width
1209 Values
1211 1 x1
1212 2 x2
1214 4 x4
1216 8 x8
1218 12 x12
1220 16 x16
1222 32 x32
1224 Since
1226 4.0
1227 HostMemPolicy (Enum)
1229 Host memory policy types
1230 Values
1232 default
1233 restore default policy, remove any nondefault policy
1234 preferred
1236 set the preferred host nodes for allocation
1237 bind a strict policy that restricts memory allocation to the host
1239 nodes specified
1240 interleave
1242 memory allocations are interleaved across the set of host nodes
1243 specified
1244 Since
1246 2.1
1247 NetFilterDirection (Enum)
1249 Indicates whether a netfilter is attached to a netdev's transmit queue
1250 or receive queue or both.
1251 Values
1253 all the filter is attached both to the receive and the transmit
1254 queue of the netdev (default).
1255 rx the filter is attached to the receive queue of the netdev, where
1257 it will receive packets sent to the netdev.
1258 tx the filter is attached to the transmit queue of the netdev,
1260 where it will receive packets sent by the netdev.
1261 Since
1263 2.5
1264 GrabToggleKeys (Enum)
1266 Keys to toggle input-linux between host and guest.
1267 Values
1269 ctrl-ctrl
1270 Not documented
1271 alt-alt
1273 Not documented
1274 shift-shift
1276 Not documented
1277 meta-meta
1279 Not documented
1280 scrolllock
1282 Not documented
1283 ctrl-scrolllock
1285 Not documented
1286 Since
1288 4.0
1289
1291 NetworkAddressFamily (Enum)
1292 The network address family
1293 Values
1295 ipv4 IPV4 family
1296 ipv6 IPV6 family
1298 unix unix socket
1300 vsock vsock family (since 2.8)
1302 unknown
1304 otherwise
1305 Since
1307 2.1
1308 InetSocketAddressBase (Object)
1310 Members
1311 host: string
1312 host part of the address
1313 port: string
1315 port part of the address
1316 InetSocketAddress (Object)
1318 Captures a socket address or address range in the Internet namespace.
1319 Members
1321 numeric: boolean (optional)
1322 true if the host/port are guaranteed to be numeric, false if
1323 name resolution should be attempted. Defaults to false. (Since
1324 2.9)
1325 to: int (optional)
1327 If present, this is range of possible addresses, with port be‐
1328 tween port and to.
1329 ipv4: boolean (optional)
1331 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1332 ipv6: boolean (optional)
1334 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1335 keep-alive: boolean (optional)
1337 enable keep-alive when connecting to this socket. Not supported
1338 for passive sockets. (Since 4.2)
1339 mptcp: boolean (optional) (If: defined(IPPROTO_MPTCP))
1341 enable multi-path TCP. (Since 6.1)
1342 The members of InetSocketAddressBase
1344 Since
1346 1.3
1347 UnixSocketAddress (Object)
1349 Captures a socket address in the local ("Unix socket") namespace.
1350 Members
1352 path: string
1353 filesystem path to use
1354 abstract: boolean (optional) (If: defined(CONFIG_LINUX))
1356 if true, this is a Linux abstract socket address. path will be
1357 prefixed by a null byte, and optionally padded with null bytes.
1358 Defaults to false. (Since 5.1)
1359 tight: boolean (optional) (If: defined(CONFIG_LINUX))
1361 if false, pad an abstract socket address with enough null bytes
1362 to make it fill struct sockaddr_un member sun_path. Defaults to
1363 true. (Since 5.1)
1364 Since
1366 1.3
1367 VsockSocketAddress (Object)
1369 Captures a socket address in the vsock namespace.
1370 Members
1372 cid: string
1373 unique host identifier
1374 port: string
1376 port
1377 Note
1379 string types are used to allow for possible future hostname or service
1380 resolution support.
1381 Since
1383 2.8
1384 SocketAddressLegacy (Object)
1386 Captures the address of a socket, which could also be a named file de‐
1387 scriptor
1388 Members
1390 type One of inet, unix, vsock, fd
1391 data: InetSocketAddress when type is "inet"
1393 data: UnixSocketAddress when type is "unix"
1395 data: VsockSocketAddress when type is "vsock"
1397 data: String when type is "fd"
1399 Note
1401 This type is deprecated in favor of SocketAddress. The difference be‐
1402 tween SocketAddressLegacy and SocketAddress is that the latter is a
1403 flat union rather than a simple union. Flat is nicer because it avoids
1404 nesting on the wire, i.e. that form has fewer {}.
1405 Since
1407 1.3
1408 SocketAddressType (Enum)
1410 Available SocketAddress types
1411 Values
1413 inet Internet address
1414 unix Unix domain socket
1416 vsock VMCI address
1418 fd decimal is for file descriptor number, otherwise a file descrip‐
1420 tor name. Named file descriptors are permitted in monitor com‐
1421 mands, in combination with the 'getfd' command. Decimal file de‐
1422 scriptors are permitted at startup or other contexts where no
1423 monitor context is active.
1424 Since
1426 2.9
1427 SocketAddress (Object)
1429 Captures the address of a socket, which could also be a named file de‐
1430 scriptor
1431 Members
1433 type: SocketAddressType
1434 Transport type
1435 The members of InetSocketAddress when type is "inet"
1437 The members of UnixSocketAddress when type is "unix"
1439 The members of VsockSocketAddress when type is "vsock"
1441 The members of String when type is "fd"
1443 Since
1445 2.9
1446
1448 RunState (Enum)
1449 An enumeration of VM run states.
1450 Values
1452 debug QEMU is running on a debugger
1453 finish-migrate
1455 guest is paused to finish the migration process
1456 inmigrate
1458 guest is paused waiting for an incoming migration. Note that
1459 this state does not tell whether the machine will start at the
1460 end of the migration. This depends on the command-line -S op‐
1461 tion and any invocation of 'stop' or 'cont' that has happened
1462 since QEMU was started.
1463 internal-error
1465 An internal error that prevents further guest execution has oc‐
1466 curred
1467 io-error
1469 the last IOP has failed and the device is configured to pause on
1470 I/O errors
1471 paused guest has been paused via the 'stop' command
1473 postmigrate
1475 guest is paused following a successful 'migrate'
1476 prelaunch
1478 QEMU was started with -S and guest has not started
1479 restore-vm
1481 guest is paused to restore VM state
1482 running
1484 guest is actively running
1485 save-vm
1487 guest is paused to save the VM state
1488 shutdown
1490 guest is shut down (and -no-shutdown is in use)
1491 suspended
1493 guest is suspended (ACPI S3)
1494 watchdog
1496 the watchdog action is configured to pause and has been trig‐
1497 gered
1498 guest-panicked
1500 guest has been panicked as a result of guest OS panic
1501 colo guest is paused to save/restore VM state under colo checkpoint,
1503 VM can not get into this state unless colo capability is enabled
1504 for migration. (since 2.8)
1505 ShutdownCause (Enum)
1507 An enumeration of reasons for a Shutdown.
1508 Values
1510 none No shutdown request pending
1511 host-error
1513 An error prevents further use of guest
1514 host-qmp-quit
1516 Reaction to the QMP command 'quit'
1517 host-qmp-system-reset
1519 Reaction to the QMP command 'system_reset'
1520 host-signal
1522 Reaction to a signal, such as SIGINT
1523 host-ui
1525 Reaction to a UI event, like window close
1526 guest-shutdown
1528 Guest shutdown/suspend request, via ACPI or other hardware-spe‐
1529 cific means
1530 guest-reset
1532 Guest reset request, and command line turns that into a shutdown
1533 guest-panic
1535 Guest panicked, and command line turns that into a shutdown
1536 subsystem-reset
1538 Partial guest reset that does not trigger QMP events and ignores
1539 --no-reboot. This is useful for sanitizing hypercalls on s390
1540 that are used during kexec/kdump/boot
1541 StatusInfo (Object)
1543 Information about VCPU run state
1544 Members
1546 running: boolean
1547 true if all VCPUs are runnable, false if not runnable
1548 singlestep: boolean
1550 true if VCPUs are in single-step mode
1551 status: RunState
1553 the virtual machine RunState
1554 Since
1556 0.14
1557 Notes
1559 singlestep is enabled through the GDB stub
1560 query-status (Command)
1562 Query the run status of all VCPUs
1563 Returns
1565 StatusInfo reflecting all VCPUs
1566 Since
1568 0.14
1569 Example
1571 -> { "execute": "query-status" }
1572 <- { "return": { "running": true,
1573 "singlestep": false,
1574 "status": "running" } }
1575 SHUTDOWN (Event)
1577 Emitted when the virtual machine has shut down, indicating that qemu is
1578 about to exit.
1579 Arguments
1581 guest: boolean
1582 If true, the shutdown was triggered by a guest request (such as
1583 a guest-initiated ACPI shutdown request or other hardware-spe‐
1584 cific action) rather than a host request (such as sending qemu a
1585 SIGINT). (since 2.10)
1586 reason: ShutdownCause
1588 The ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
1589 Note
1591 If the command-line option "-no-shutdown" has been specified, qemu will
1592 not exit, and a STOP event will eventually follow the SHUTDOWN event
1593 Since
1595 0.12
1596 Example
1598 <- { "event": "SHUTDOWN", "data": { "guest": true },
1599 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1600 POWERDOWN (Event)
1602 Emitted when the virtual machine is powered down through the power con‐
1603 trol system, such as via ACPI.
1604 Since
1606 0.12
1607 Example
1609 <- { "event": "POWERDOWN",
1610 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1611 RESET (Event)
1613 Emitted when the virtual machine is reset
1614 Arguments
1616 guest: boolean
1617 If true, the reset was triggered by a guest request (such as a
1618 guest-initiated ACPI reboot request or other hardware-specific
1619 action) rather than a host request (such as the QMP command sys‐
1620 tem_reset). (since 2.10)
1621 reason: ShutdownCause
1623 The ShutdownCause of the RESET. (since 4.0)
1624 Since
1626 0.12
1627 Example
1629 <- { "event": "RESET", "data": { "guest": false },
1630 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
1631 STOP (Event)
1633 Emitted when the virtual machine is stopped
1634 Since
1636 0.12
1637 Example
1639 <- { "event": "STOP",
1640 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
1641 RESUME (Event)
1643 Emitted when the virtual machine resumes execution
1644 Since
1646 0.12
1647 Example
1649 <- { "event": "RESUME",
1650 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
1651 SUSPEND (Event)
1653 Emitted when guest enters a hardware suspension state, for example, S3
1654 state, which is sometimes called standby state
1655 Since
1657 1.1
1658 Example
1660 <- { "event": "SUSPEND",
1661 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
1662 SUSPEND_DISK (Event)
1664 Emitted when guest enters a hardware suspension state with data saved
1665 on disk, for example, S4 state, which is sometimes called hibernate
1666 state
1667 Note
1669 QEMU shuts down (similar to event SHUTDOWN) when entering this state
1670 Since
1672 1.2
1673 Example
1675 <- { "event": "SUSPEND_DISK",
1676 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
1677 WAKEUP (Event)
1679 Emitted when the guest has woken up from suspend state and is running
1680 Since
1682 1.1
1683 Example
1685 <- { "event": "WAKEUP",
1686 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
1687 WATCHDOG (Event)
1689 Emitted when the watchdog device's timer is expired
1690 Arguments
1692 action: WatchdogAction
1693 action that has been taken
1694 Note
1696 If action is "reset", "shutdown", or "pause" the WATCHDOG event is fol‐
1697 lowed respectively by the RESET, SHUTDOWN, or STOP events
1698 Note
1700 This event is rate-limited.
1701 Since
1703 0.13
1704 Example
1706 <- { "event": "WATCHDOG",
1707 "data": { "action": "reset" },
1708 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
1709 WatchdogAction (Enum)
1711 An enumeration of the actions taken when the watchdog device's timer is
1712 expired
1713 Values
1715 reset system resets
1716 shutdown
1718 system shutdown, note that it is similar to powerdown, which
1719 tries to set to system status and notify guest
1720 poweroff
1722 system poweroff, the emulator program exits
1723 pause system pauses, similar to stop
1725 debug system enters debug state
1727 none nothing is done
1729 inject-nmi
1731 a non-maskable interrupt is injected into the first VCPU (all
1732 VCPUS on x86) (since 2.4)
1733 Since
1735 2.1
1736 RebootAction (Enum)
1738 Possible QEMU actions upon guest reboot
1739 Values
1741 reset Reset the VM
1742 shutdown
1744 Shutdown the VM and exit, according to the shutdown action
1745 Since
1747 6.0
1748 ShutdownAction (Enum)
1750 Possible QEMU actions upon guest shutdown
1751 Values
1753 poweroff
1754 Shutdown the VM and exit
1755 pause pause the VM#
1757 Since
1759 6.0
1760 PanicAction (Enum)
1762 Values
1763 none Continue VM execution
1764 pause Pause the VM
1766 shutdown
1768 Shutdown the VM and exit, according to the shutdown action
1769 Since
1771 6.0
1772 watchdog-set-action (Command)
1774 Set watchdog action
1775 Arguments
1777 action: WatchdogAction
1778 Not documented
1779 Since
1781 2.11
1782 set-action (Command)
1784 Set the actions that will be taken by the emulator in response to guest
1785 events.
1786 Arguments
1788 reboot: RebootAction (optional)
1789 RebootAction action taken on guest reboot.
1790 shutdown: ShutdownAction (optional)
1792 ShutdownAction action taken on guest shutdown.
1793 panic: PanicAction (optional)
1795 PanicAction action taken on guest panic.
1796 watchdog: WatchdogAction (optional)
1798 WatchdogAction action taken when watchdog timer expires .
1799 Returns
1801 Nothing on success.
1802 Since
1804 6.0
1805 Example
1807 -> { "execute": "set-action",
1808 "arguments": { "reboot": "shutdown",
1809 "shutdown" : "pause",
1810 "panic": "pause",
1811 "watchdog": "inject-nmi" } }
1812 <- { "return": {} }
1813 GUEST_PANICKED (Event)
1815 Emitted when guest OS panic is detected
1816 Arguments
1818 action: GuestPanicAction
1819 action that has been taken, currently always "pause"
1820 info: GuestPanicInformation (optional)
1822 information about a panic (since 2.9)
1823 Since
1825 1.5
1826 Example
1828 <- { "event": "GUEST_PANICKED",
1829 "data": { "action": "pause" } }
1830 GUEST_CRASHLOADED (Event)
1832 Emitted when guest OS crash loaded is detected
1833 Arguments
1835 action: GuestPanicAction
1836 action that has been taken, currently always "run"
1837 info: GuestPanicInformation (optional)
1839 information about a panic
1840 Since
1842 5.0
1843 Example
1845 <- { "event": "GUEST_CRASHLOADED",
1846 "data": { "action": "run" } }
1847 GuestPanicAction (Enum)
1849 An enumeration of the actions taken when guest OS panic is detected
1850 Values
1852 pause system pauses
1853 poweroff
1855 Not documented
1856 run Not documented
1858 Since
1860 2.1 (poweroff since 2.8, run since 5.0)
1861 GuestPanicInformationType (Enum)
1863 An enumeration of the guest panic information types
1864 Values
1866 hyper-v
1867 hyper-v guest panic information type
1868 s390 s390 guest panic information type (Since: 2.12)
1870 Since
1872 2.9
1873 GuestPanicInformation (Object)
1875 Information about a guest panic
1876 Members
1878 type: GuestPanicInformationType
1879 Crash type that defines the hypervisor specific information
1880 The members of GuestPanicInformationHyperV when type is "hyper-v"
1882 The members of GuestPanicInformationS390 when type is "s390"
1884 Since
1886 2.9
1887 GuestPanicInformationHyperV (Object)
1889 Hyper-V specific guest panic information (HV crash MSRs)
1890 Members
1892 arg1: int
1893 Not documented
1894 arg2: int
1896 Not documented
1897 arg3: int
1899 Not documented
1900 arg4: int
1902 Not documented
1903 arg5: int
1905 Not documented
1906 Since
1908 2.9
1909 S390CrashReason (Enum)
1911 Reason why the CPU is in a crashed state.
1912 Values
1914 unknown
1915 no crash reason was set
1916 disabled-wait
1918 the CPU has entered a disabled wait state
1919 extint-loop
1921 clock comparator or cpu timer interrupt with new PSW enabled for
1922 external interrupts
1923 pgmint-loop
1925 program interrupt with BAD new PSW
1926 opint-loop
1928 operation exception interrupt with invalid code at the program
1929 interrupt new PSW
1930 Since
1932 2.12
1933 GuestPanicInformationS390 (Object)
1935 S390 specific guest panic information (PSW)
1936 Members
1938 core: int
1939 core id of the CPU that crashed
1940 psw-mask: int
1942 control fields of guest PSW
1943 psw-addr: int
1945 guest instruction address
1946 reason: S390CrashReason
1948 guest crash reason
1949 Since
1951 2.12
1952 MEMORY_FAILURE (Event)
1954 Emitted when a memory failure occurs on host side.
1955 Arguments
1957 recipient: MemoryFailureRecipient
1958 recipient is defined as MemoryFailureRecipient.
1959 action: MemoryFailureAction
1961 action that has been taken. action is defined as MemoryFailure‐
1962 Action.
1963 flags: MemoryFailureFlags
1965 flags for MemoryFailureAction. action is defined as MemoryFail‐
1966 ureFlags.
1967 Since
1969 5.2
1970 Example
1972 <- { "event": "MEMORY_FAILURE",
1973 "data": { "recipient": "hypervisor",
1974 "action": "fatal",
1975 "flags": { 'action-required': false } }
1976 MemoryFailureRecipient (Enum)
1978 Hardware memory failure occurs, handled by recipient.
1979 Values
1981 hypervisor
1982 memory failure at QEMU process address space. (none guest mem‐
1983 ory, but used by QEMU itself).
1984 guest memory failure at guest memory,
1986 Since
1988 5.2
1989 MemoryFailureAction (Enum)
1991 Actions taken by QEMU in response to a hardware memory failure.
1992 Values
1994 ignore the memory failure could be ignored. This will only be the case
1995 for action-optional failures.
1996 inject memory failure occurred in guest memory, the guest enabled MCE
1998 handling mechanism, and QEMU could inject the MCE into the guest
1999 successfully.
2000 fatal the failure is unrecoverable. This occurs for action-required
2002 failures if the recipient is the hypervisor; QEMU will exit.
2003 reset the failure is unrecoverable but confined to the guest. This
2005 occurs if the recipient is a guest guest which is not ready to
2006 handle memory failures.
2007 Since
2009 5.2
2010 MemoryFailureFlags (Object)
2012 Additional information on memory failures.
2013 Members
2015 action-required: boolean
2016 whether a memory failure event is action-required or action-op‐
2017 tional (e.g. a failure during memory scrub).
2018 recursive: boolean
2020 whether the failure occurred while the previous failure was
2021 still in progress.
2022 Since
2024 5.2
2025
2027 QCryptoTLSCredsEndpoint (Enum)
2028 The type of network endpoint that will be using the credentials. Most
2029 types of credential require different setup / structures depending on
2030 whether they will be used in a server versus a client.
2031 Values
2033 client the network endpoint is acting as the client
2034 server the network endpoint is acting as the server
2036 Since
2038 2.5
2039 QCryptoSecretFormat (Enum)
2041 The data format that the secret is provided in
2042 Values
2044 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
2045 be used
2046 base64 arbitrary base64 encoded binary data
2048 Since
2050 2.6
2051 QCryptoHashAlgorithm (Enum)
2053 The supported algorithms for computing content digests
2054 Values
2056 md5 MD5. Should not be used in any new code, legacy compat only
2057 sha1 SHA-1. Should not be used in any new code, legacy compat only
2059 sha224 SHA-224. (since 2.7)
2061 sha256 SHA-256. Current recommended strong hash.
2063 sha384 SHA-384. (since 2.7)
2065 sha512 SHA-512. (since 2.7)
2067 ripemd160
2069 RIPEMD-160. (since 2.7)
2070 Since
2072 2.6
2073 QCryptoCipherAlgorithm (Enum)
2075 The supported algorithms for content encryption ciphers
2076 Values
2078 aes-128
2079 AES with 128 bit / 16 byte keys
2080 aes-192
2082 AES with 192 bit / 24 byte keys
2083 aes-256
2085 AES with 256 bit / 32 byte keys
2086 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
2088 6.1)
2089 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
2091 cast5-128
2093 Cast5 with 128 bit / 16 byte keys
2094 serpent-128
2096 Serpent with 128 bit / 16 byte keys
2097 serpent-192
2099 Serpent with 192 bit / 24 byte keys
2100 serpent-256
2102 Serpent with 256 bit / 32 byte keys
2103 twofish-128
2105 Twofish with 128 bit / 16 byte keys
2106 twofish-192
2108 Twofish with 192 bit / 24 byte keys
2109 twofish-256
2111 Twofish with 256 bit / 32 byte keys
2112 Since
2114 2.6
2115 QCryptoCipherMode (Enum)
2117 The supported modes for content encryption ciphers
2118 Values
2120 ecb Electronic Code Book
2121 cbc Cipher Block Chaining
2123 xts XEX with tweaked code book and ciphertext stealing
2125 ctr Counter (Since 2.8)
2127 Since
2129 2.6
2130 QCryptoIVGenAlgorithm (Enum)
2132 The supported algorithms for generating initialization vectors for full
2133 disk encryption. The 'plain' generator should not be used for disks
2134 with sector numbers larger than 2^32, except where compatibility with
2135 pre-existing Linux dm-crypt volumes is required.
2136 Values
2138 plain 64-bit sector number truncated to 32-bits
2139 plain64
2141 64-bit sector number
2142 essiv 64-bit sector number encrypted with a hash of the encryption key
2144 Since
2146 2.6
2147 QCryptoBlockFormat (Enum)
2149 The supported full disk encryption formats
2150 Values
2152 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
2153 data from old images.
2154 luks LUKS encryption format. Recommended for new images
2156 Since
2158 2.6
2159 QCryptoBlockOptionsBase (Object)
2161 The common options that apply to all full disk encryption formats
2162 Members
2164 format: QCryptoBlockFormat
2165 the encryption format
2166 Since
2168 2.6
2169 QCryptoBlockOptionsQCow (Object)
2171 The options that apply to QCow/QCow2 AES-CBC encryption format
2172 Members
2174 key-secret: string (optional)
2175 the ID of a QCryptoSecret object providing the decryption key.
2176 Mandatory except when probing image for metadata only.
2177 Since
2179 2.6
2180 QCryptoBlockOptionsLUKS (Object)
2182 The options that apply to LUKS encryption format
2183 Members
2185 key-secret: string (optional)
2186 the ID of a QCryptoSecret object providing the decryption key.
2187 Mandatory except when probing image for metadata only.
2188 Since
2190 2.6
2191 QCryptoBlockCreateOptionsLUKS (Object)
2193 The options that apply to LUKS encryption format initialization
2194 Members
2196 cipher-alg: QCryptoCipherAlgorithm (optional)
2197 the cipher algorithm for data encryption Currently defaults to
2198 'aes-256'.
2199 cipher-mode: QCryptoCipherMode (optional)
2201 the cipher mode for data encryption Currently defaults to 'xts'
2202 ivgen-alg: QCryptoIVGenAlgorithm (optional)
2204 the initialization vector generator Currently defaults to
2205 'plain64'
2206 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2208 the initialization vector generator hash Currently defaults to
2209 'sha256'
2210 hash-alg: QCryptoHashAlgorithm (optional)
2212 the master key hash algorithm Currently defaults to 'sha256'
2213 iter-time: int (optional)
2215 number of milliseconds to spend in PBKDF passphrase processing.
2216 Currently defaults to 2000. (since 2.8)
2217 The members of QCryptoBlockOptionsLUKS
2219 Since
2221 2.6
2222 QCryptoBlockOpenOptions (Object)
2224 The options that are available for all encryption formats when opening
2225 an existing volume
2226 Members
2228 The members of QCryptoBlockOptionsBase
2229 The members of QCryptoBlockOptionsQCow when format is "qcow"
2231 The members of QCryptoBlockOptionsLUKS when format is "luks"
2233 Since
2235 2.6
2236 QCryptoBlockCreateOptions (Object)
2238 The options that are available for all encryption formats when initial‐
2239 izing a new volume
2240 Members
2242 The members of QCryptoBlockOptionsBase
2243 The members of QCryptoBlockOptionsQCow when format is "qcow"
2245 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
2247 Since
2249 2.6
2250 QCryptoBlockInfoBase (Object)
2252 The common information that applies to all full disk encryption formats
2253 Members
2255 format: QCryptoBlockFormat
2256 the encryption format
2257 Since
2259 2.7
2260 QCryptoBlockInfoLUKSSlot (Object)
2262 Information about the LUKS block encryption key slot options
2263 Members
2265 active: boolean
2266 whether the key slot is currently in use
2267 key-offset: int
2269 offset to the key material in bytes
2270 iters: int (optional)
2272 number of PBKDF2 iterations for key material
2273 stripes: int (optional)
2275 number of stripes for splitting key material
2276 Since
2278 2.7
2279 QCryptoBlockInfoLUKS (Object)
2281 Information about the LUKS block encryption options
2282 Members
2284 cipher-alg: QCryptoCipherAlgorithm
2285 the cipher algorithm for data encryption
2286 cipher-mode: QCryptoCipherMode
2288 the cipher mode for data encryption
2289 ivgen-alg: QCryptoIVGenAlgorithm
2291 the initialization vector generator
2292 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2294 the initialization vector generator hash
2295 hash-alg: QCryptoHashAlgorithm
2297 the master key hash algorithm
2298 payload-offset: int
2300 offset to the payload data in bytes
2301 master-key-iters: int
2303 number of PBKDF2 iterations for key material
2304 uuid: string
2306 unique identifier for the volume
2307 slots: array of QCryptoBlockInfoLUKSSlot
2309 information about each key slot
2310 Since
2312 2.7
2313 QCryptoBlockInfo (Object)
2315 Information about the block encryption options
2316 Members
2318 The members of QCryptoBlockInfoBase
2319 The members of QCryptoBlockInfoLUKS when format is "luks"
2321 Since
2323 2.7
2324 QCryptoBlockLUKSKeyslotState (Enum)
2326 Defines state of keyslots that are affected by the update
2327 Values
2329 active The slots contain the given password and marked as active
2330 inactive
2332 The slots are erased (contain garbage) and marked as inactive
2333 Since
2335 5.1
2336 QCryptoBlockAmendOptionsLUKS (Object)
2338 This struct defines the update parameters that activate/de-activate set
2339 of keyslots
2340 Members
2342 state: QCryptoBlockLUKSKeyslotState
2343 the desired state of the keyslots
2344 new-secret: string (optional)
2346 The ID of a QCryptoSecret object providing the password to be
2347 written into added active keyslots
2348 old-secret: string (optional)
2350 Optional (for deactivation only) If given will deactivate all
2351 keyslots that match password located in QCryptoSecret with this
2352 ID
2353 iter-time: int (optional)
2355 Optional (for activation only) Number of milliseconds to spend
2356 in PBKDF passphrase processing for the newly activated keyslot.
2357 Currently defaults to 2000.
2358 keyslot: int (optional)
2360 Optional. ID of the keyslot to activate/deactivate. For keyslot
2361 activation, keyslot should not be active already (this is unsafe
2362 to update an active keyslot), but possible if 'force' parameter
2363 is given. If keyslot is not given, first free keyslot will be
2364 written.
2365 For keyslot deactivation, this parameter specifies the exact
2367 keyslot to deactivate
2368 secret: string (optional)
2370 Optional. The ID of a QCryptoSecret object providing the pass‐
2371 word to use to retrieve current master key. Defaults to the
2372 same secret that was used to open the image
2373 Since 5.1
2374 QCryptoBlockAmendOptions (Object)
2376 The options that are available for all encryption formats when amending
2377 encryption settings
2378 Members
2380 The members of QCryptoBlockOptionsBase
2381 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
2383 Since
2385 5.1
2386 SecretCommonProperties (Object)
2388 Properties for objects of classes derived from secret-common.
2389 Members
2391 loaded: boolean (optional)
2392 if true, the secret is loaded immediately when applying this op‐
2393 tion and will probably fail when processing the next option.
2394 Don't use; only provided for compatibility. (default: false)
2395 format: QCryptoSecretFormat (optional)
2397 the data format that the secret is provided in (default: raw)
2398 keyid: string (optional)
2400 the name of another secret that should be used to decrypt the
2401 provided data. If not present, the data is assumed to be unen‐
2402 crypted.
2403 iv: string (optional)
2405 the random initialization vector used for encryption of this
2406 particular secret. Should be a base64 encrypted string of the
2407 16-byte IV. Mandatory if keyid is given. Ignored if keyid is ab‐
2408 sent.
2409 Features
2411 deprecated
2412 Member loaded is deprecated. Setting true doesn't make sense,
2413 and false is already the default.
2414 Since
2416 2.6
2417 SecretProperties (Object)
2419 Properties for secret objects.
2420 Either data or file must be provided, but not both.
2422 Members
2424 data: string (optional)
2425 the associated with the secret from
2426 file: string (optional)
2428 the filename to load the data associated with the secret from
2429 The members of SecretCommonProperties
2431 Since
2433 2.6
2434 SecretKeyringProperties (Object)
2436 Properties for secret_keyring objects.
2437 Members
2439 serial: int
2440 serial number that identifies a key to get from the kernel
2441 The members of SecretCommonProperties
2443 Since
2445 5.1
2446 TlsCredsProperties (Object)
2448 Properties for objects of classes derived from tls-creds.
2449 Members
2451 verify-peer: boolean (optional)
2452 if true the peer credentials will be verified once the handshake
2453 is completed. This is a no-op for anonymous credentials. (de‐
2454 fault: true)
2455 dir: string (optional)
2457 the path of the directory that contains the credential files
2458 endpoint: QCryptoTLSCredsEndpoint (optional)
2460 whether the QEMU network backend that uses the credentials will
2461 be acting as a client or as a server (default: client)
2462 priority: string (optional)
2464 a gnutls priority string as described at
2465 https://gnutls.org/manual/html_node/Priority-Strings.html
2466 Since
2468 2.5
2469 TlsCredsAnonProperties (Object)
2471 Properties for tls-creds-anon objects.
2472 Members
2474 loaded: boolean (optional)
2475 if true, the credentials are loaded immediately when applying
2476 this option and will ignore options that are processed later.
2477 Don't use; only provided for compatibility. (default: false)
2478 The members of TlsCredsProperties
2480 Features
2482 deprecated
2483 Member loaded is deprecated. Setting true doesn't make sense,
2484 and false is already the default.
2485 Since
2487 2.5
2488 TlsCredsPskProperties (Object)
2490 Properties for tls-creds-psk objects.
2491 Members
2493 loaded: boolean (optional)
2494 if true, the credentials are loaded immediately when applying
2495 this option and will ignore options that are processed later.
2496 Don't use; only provided for compatibility. (default: false)
2497 username: string (optional)
2499 the username which will be sent to the server. For clients
2500 only. If absent, "qemu" is sent and the property will read back
2501 as an empty string.
2502 The members of TlsCredsProperties
2504 Features
2506 deprecated
2507 Member loaded is deprecated. Setting true doesn't make sense,
2508 and false is already the default.
2509 Since
2511 3.0
2512 TlsCredsX509Properties (Object)
2514 Properties for tls-creds-x509 objects.
2515 Members
2517 loaded: boolean (optional)
2518 if true, the credentials are loaded immediately when applying
2519 this option and will ignore options that are processed later.
2520 Don't use; only provided for compatibility. (default: false)
2521 sanity-check: boolean (optional)
2523 if true, perform some sanity checks before using the credentials
2524 (default: true)
2525 passwordid: string (optional)
2527 For the server-key.pem and client-key.pem files which contain
2528 sensitive private keys, it is possible to use an encrypted ver‐
2529 sion by providing the passwordid parameter. This provides the
2530 ID of a previously created secret object containing the password
2531 for decryption.
2532 The members of TlsCredsProperties
2534 Features
2536 deprecated
2537 Member loaded is deprecated. Setting true doesn't make sense,
2538 and false is already the default.
2539 Since
2541 2.5
2542
2544 Block core (VM unrelated)
2545 Background jobs
2546 JobType (Enum)
2547 Type of a background job.
2548 Values
2550 commit block commit job type, see "block-commit"
2551 stream block stream job type, see "block-stream"
2553 mirror drive mirror job type, see "drive-mirror"
2555 backup drive backup job type, see "drive-backup"
2557 create image creation job type, see "blockdev-create" (since 3.0)
2559 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
2561 snapshot-load
2563 snapshot load job type, see "snapshot-load" (since 6.0)
2564 snapshot-save
2566 snapshot save job type, see "snapshot-save" (since 6.0)
2567 snapshot-delete
2569 snapshot delete job type, see "snapshot-delete" (since 6.0)
2570 Since
2572 1.7
2573 JobStatus (Enum)
2575 Indicates the present state of a given job in its lifetime.
2576 Values
2578 undefined
2579 Erroneous, default state. Should not ever be visible.
2580 created
2582 The job has been created, but not yet started.
2583 running
2585 The job is currently running.
2586 paused The job is running, but paused. The pause may be requested by
2588 either the QMP user or by internal processes.
2589 ready The job is running, but is ready for the user to signal comple‐
2591 tion. This is used for long-running jobs like mirror that are
2592 designed to run indefinitely.
2593 standby
2595 The job is ready, but paused. This is nearly identical to
2596 paused. The job may return to ready or otherwise be canceled.
2597 waiting
2599 The job is waiting for other jobs in the transaction to converge
2600 to the waiting state. This status will likely not be visible for
2601 the last job in a transaction.
2602 pending
2604 The job has finished its work, but has finalization steps that
2605 it needs to make prior to completing. These changes will require
2606 manual intervention via job-finalize if auto-finalize was set to
2607 false. These pending changes may still fail.
2608 aborting
2610 The job is in the process of being aborted, and will finish with
2611 an error. The job will afterwards report that it is concluded.
2612 This status may not be visible to the management process.
2613 concluded
2615 The job has finished all work. If auto-dismiss was set to false,
2616 the job will remain in the query list until it is dismissed via
2617 job-dismiss.
2618 null The job is in the process of being dismantled. This state should
2620 not ever be visible externally.
2621 Since
2623 2.12
2624 JobVerb (Enum)
2626 Represents command verbs that can be applied to a job.
2627 Values
2629 cancel see job-cancel
2630 pause see job-pause
2632 resume see job-resume
2634 set-speed
2636 see block-job-set-speed
2637 complete
2639 see job-complete
2640 dismiss
2642 see job-dismiss
2643 finalize
2645 see job-finalize
2646 Since
2648 2.12
2649 JOB_STATUS_CHANGE (Event)
2651 Emitted when a job transitions to a different status.
2652 Arguments
2654 id: string
2655 The job identifier
2656 status: JobStatus
2658 The new job status
2659 Since
2661 3.0
2662 job-pause (Command)
2664 Pause an active job.
2665 This command returns immediately after marking the active job for paus‐
2667 ing. Pausing an already paused job is an error.
2668 The job will pause as soon as possible, which means transitioning into
2670 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
2671 The corresponding JOB_STATUS_CHANGE event will be emitted.
2672 Cancelling a paused job automatically resumes it.
2674 Arguments
2676 id: string
2677 The job identifier.
2678 Since
2680 3.0
2681 job-resume (Command)
2683 Resume a paused job.
2684 This command returns immediately after resuming a paused job. Resuming
2686 an already running job is an error.
2687 id : The job identifier.
2689 Arguments
2691 id: string
2692 Not documented
2693 Since
2695 3.0
2696 job-cancel (Command)
2698 Instruct an active background job to cancel at the next opportunity.
2699 This command returns immediately after marking the active job for can‐
2700 cellation.
2701 The job will cancel as soon as possible and then emit a JOB_STA‐
2703 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
2704 is possible that a job successfully completes (e.g. because it was al‐
2705 most done and there was no opportunity to cancel earlier than complet‐
2706 ing the job) and transitions to PENDING instead.
2707 Arguments
2709 id: string
2710 The job identifier.
2711 Since
2713 3.0
2714 job-complete (Command)
2716 Manually trigger completion of an active job in the READY state.
2717 Arguments
2719 id: string
2720 The job identifier.
2721 Since
2723 3.0
2724 job-dismiss (Command)
2726 Deletes a job that is in the CONCLUDED state. This command only needs
2727 to be run explicitly for jobs that don't have automatic dismiss en‐
2728 abled.
2729 This command will refuse to operate on any job that has not yet reached
2731 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
2732 JOB_READY event, job-cancel or job-complete will still need to be used
2733 as appropriate.
2734 Arguments
2736 id: string
2737 The job identifier.
2738 Since
2740 3.0
2741 job-finalize (Command)
2743 Instructs all jobs in a transaction (or a single job if it is not part
2744 of any transaction) to finalize any graph changes and do any necessary
2745 cleanup. This command requires that all involved jobs are in the PEND‐
2746 ING state.
2747 For jobs in a transaction, instructing one job to finalize will force
2749 ALL jobs in the transaction to finalize, so it is only necessary to in‐
2750 struct a single member job to finalize.
2751 Arguments
2753 id: string
2754 The identifier of any job in the transaction, or of a job that
2755 is not part of any transaction.
2756 Since
2758 3.0
2759 JobInfo (Object)
2761 Information about a job.
2762 Members
2764 id: string
2765 The job identifier
2766 type: JobType
2768 The kind of job that is being performed
2769 status: JobStatus
2771 Current job state/status
2772 current-progress: int
2774 Progress made until now. The unit is arbitrary and the value can
2775 only meaningfully be used for the ratio of current-progress to
2776 total-progress. The value is monotonically increasing.
2777 total-progress: int
2779 Estimated current-progress value at the completion of the job.
2780 This value can arbitrarily change while the job is running, in
2781 both directions.
2782 error: string (optional)
2784 If this field is present, the job failed; if it is still missing
2785 in the CONCLUDED state, this indicates successful completion.
2786 The value is a human-readable error message to describe the rea‐
2788 son for the job failure. It should not be parsed by applica‐
2789 tions.
2790 Since
2792 3.0
2793 query-jobs (Command)
2795 Return information about jobs.
2796 Returns
2798 a list with a JobInfo for each active job
2799 Since
2801 3.0
2802 SnapshotInfo (Object)
2804 Members
2805 id: string
2806 unique snapshot id
2807 name: string
2809 user chosen name
2810 vm-state-size: int
2812 size of the VM state
2813 date-sec: int
2815 UTC date of the snapshot in seconds
2816 date-nsec: int
2818 fractional part in nano seconds to be used with date-sec
2819 vm-clock-sec: int
2821 VM clock relative to boot in seconds
2822 vm-clock-nsec: int
2824 fractional part in nano seconds to be used with vm-clock-sec
2825 icount: int (optional)
2827 Current instruction count. Appears when execution record/replay
2828 is enabled. Used for "time-traveling" to match the moment in the
2829 recorded execution with the snapshots. This counter may be ob‐
2830 tained through query-replay command (since 5.2)
2831 Since
2833 1.3
2834 ImageInfoSpecificQCow2EncryptionBase (Object)
2836 Members
2837 format: BlockdevQcow2EncryptionFormat
2838 The encryption format
2839 Since
2841 2.10
2842 ImageInfoSpecificQCow2Encryption (Object)
2844 Members
2845 The members of ImageInfoSpecificQCow2EncryptionBase
2846 The members of QCryptoBlockInfoLUKS when format is "luks"
2848 Since
2850 2.10
2851 ImageInfoSpecificQCow2 (Object)
2853 Members
2854 compat: string
2855 compatibility level
2856 data-file: string (optional)
2858 the filename of the external data file that is stored in the im‐
2859 age and used as a default for opening the image (since: 4.0)
2860 data-file-raw: boolean (optional)
2862 True if the external data file must stay valid as a standalone
2863 (read-only) raw image without looking at qcow2 metadata (since:
2864 4.0)
2865 extended-l2: boolean (optional)
2867 true if the image has extended L2 entries; only valid for compat
2868 >= 1.1 (since 5.2)
2869 lazy-refcounts: boolean (optional)
2871 on or off; only valid for compat >= 1.1
2872 corrupt: boolean (optional)
2874 true if the image has been marked corrupt; only valid for compat
2875 >= 1.1 (since 2.2)
2876 refcount-bits: int
2878 width of a refcount entry in bits (since 2.3)
2879 encrypt: ImageInfoSpecificQCow2Encryption (optional)
2881 details about encryption parameters; only set if image is en‐
2882 crypted (since 2.10)
2883 bitmaps: array of Qcow2BitmapInfo (optional)
2885 A list of qcow2 bitmap details (since 4.0)
2886 compression-type: Qcow2CompressionType
2888 the image cluster compression method (since 5.1)
2889 Since
2891 1.7
2892 ImageInfoSpecificVmdk (Object)
2894 Members
2895 create-type: string
2896 The create type of VMDK image
2897 cid: int
2899 Content id of image
2900 parent-cid: int
2902 Parent VMDK image's cid
2903 extents: array of ImageInfo
2905 List of extent files
2906 Since
2908 1.7
2909 ImageInfoSpecificRbd (Object)
2911 Members
2912 encryption-format: RbdImageEncryptionFormat (optional)
2913 Image encryption format
2914 Since
2916 6.1
2917 ImageInfoSpecific (Object)
2919 A discriminated record of image format specific information structures.
2920 Members
2922 type One of qcow2, vmdk, luks, rbd
2923 data: ImageInfoSpecificQCow2 when type is "qcow2"
2925 data: ImageInfoSpecificVmdk when type is "vmdk"
2927 data: QCryptoBlockInfoLUKS when type is "luks"
2929 data: ImageInfoSpecificRbd when type is "rbd"
2931 Since
2933 1.7
2934 ImageInfo (Object)
2936 Information about a QEMU image file
2937 Members
2939 filename: string
2940 name of the image file
2941 format: string
2943 format of the image file
2944 virtual-size: int
2946 maximum capacity in bytes of the image
2947 actual-size: int (optional)
2949 actual size on disk in bytes of the image
2950 dirty-flag: boolean (optional)
2952 true if image is not cleanly closed
2953 cluster-size: int (optional)
2955 size of a cluster in bytes
2956 encrypted: boolean (optional)
2958 true if the image is encrypted
2959 compressed: boolean (optional)
2961 true if the image is compressed (Since 1.7)
2962 backing-filename: string (optional)
2964 name of the backing file
2965 full-backing-filename: string (optional)
2967 full path of the backing file
2968 backing-filename-format: string (optional)
2970 the format of the backing file
2971 snapshots: array of SnapshotInfo (optional)
2973 list of VM snapshots
2974 backing-image: ImageInfo (optional)
2976 info of the backing image (since 1.6)
2977 format-specific: ImageInfoSpecific (optional)
2979 structure supplying additional format-specific information
2980 (since 1.7)
2981 Since
2983 1.3
2984 ImageCheck (Object)
2986 Information about a QEMU image file check
2987 Members
2989 filename: string
2990 name of the image file checked
2991 format: string
2993 format of the image file checked
2994 check-errors: int
2996 number of unexpected errors occurred during check
2997 image-end-offset: int (optional)
2999 offset (in bytes) where the image ends, this field is present if
3000 the driver for the image format supports it
3001 corruptions: int (optional)
3003 number of corruptions found during the check if any
3004 leaks: int (optional)
3006 number of leaks found during the check if any
3007 corruptions-fixed: int (optional)
3009 number of corruptions fixed during the check if any
3010 leaks-fixed: int (optional)
3012 number of leaks fixed during the check if any
3013 total-clusters: int (optional)
3015 total number of clusters, this field is present if the driver
3016 for the image format supports it
3017 allocated-clusters: int (optional)
3019 total number of allocated clusters, this field is present if the
3020 driver for the image format supports it
3021 fragmented-clusters: int (optional)
3023 total number of fragmented clusters, this field is present if
3024 the driver for the image format supports it
3025 compressed-clusters: int (optional)
3027 total number of compressed clusters, this field is present if
3028 the driver for the image format supports it
3029 Since
3031 1.4
3032 MapEntry (Object)
3034 Mapping information from a virtual block range to a host file range
3035 Members
3037 start: int
3038 virtual (guest) offset of the first byte described by this entry
3039 length: int
3041 the number of bytes of the mapped virtual range
3042 data: boolean
3044 reading the image will actually read data from a file (in par‐
3045 ticular, if offset is present this means that the sectors are
3046 not simply preallocated, but contain actual data in raw format)
3047 zero: boolean
3049 whether the virtual blocks read as zeroes
3050 depth: int
3052 number of layers (0 = top image, 1 = top image's backing file,
3053 ..., n - 1 = bottom image (where n is the number of images in
3054 the chain)) before reaching one for which the range is allocated
3055 present: boolean
3057 true if this layer provides the data, false if adding a backing
3058 layer could impact this region (since 6.1)
3059 offset: int (optional)
3061 if present, the image file stores the data for this range in raw
3062 format at the given (host) offset
3063 filename: string (optional)
3065 filename that is referred to by offset
3066 Since
3068 2.6
3069 BlockdevCacheInfo (Object)
3071 Cache mode information for a block device
3072 Members
3074 writeback: boolean
3075 true if writeback mode is enabled
3076 direct: boolean
3078 true if the host page cache is bypassed (O_DIRECT)
3079 no-flush: boolean
3081 true if flush requests are ignored for the device
3082 Since
3084 2.3
3085 BlockDeviceInfo (Object)
3087 Information about the backing device for a block device.
3088 Members
3090 file: string
3091 the filename of the backing device
3092 node-name: string (optional)
3094 the name of the block driver node (Since 2.0)
3095 ro: boolean
3097 true if the backing device was open read-only
3098 drv: string
3100 the name of the block format used to open the backing device. As
3101 of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
3102 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
3103 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2',
3104 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added,
3105 'cow' dropped 2.3: 'host_floppy' deprecated 2.5: 'host_floppy'
3106 dropped 2.6: 'luks' added 2.8: 'replication' added, 'tftp'
3107 dropped 2.9: 'archipelago' dropped
3108 backing_file: string (optional)
3110 the name of the backing file (for copy-on-write)
3111 backing_file_depth: int
3113 number of files in the backing file chain (since: 1.2)
3114 encrypted: boolean
3116 true if the backing device is encrypted
3117 detect_zeroes: BlockdevDetectZeroesOptions
3119 detect and optimize zero writes (Since 2.1)
3120 bps: int
3122 total throughput limit in bytes per second is specified
3123 bps_rd: int
3125 read throughput limit in bytes per second is specified
3126 bps_wr: int
3128 write throughput limit in bytes per second is specified
3129 iops: int
3131 total I/O operations per second is specified
3132 iops_rd: int
3134 read I/O operations per second is specified
3135 iops_wr: int
3137 write I/O operations per second is specified
3138 image: ImageInfo
3140 the info of image used (since: 1.6)
3141 bps_max: int (optional)
3143 total throughput limit during bursts,
3145 in bytes (Since 1.7)
3146 bps_rd_max: int (optional)
3148 read throughput limit during bursts,
3150 in bytes (Since 1.7)
3151 bps_wr_max: int (optional)
3153 write throughput limit during bursts,
3155 in bytes (Since 1.7)
3156 iops_max: int (optional)
3158 total I/O operations per second during bursts,
3160 in bytes (Since 1.7)
3161 iops_rd_max: int (optional)
3163 read I/O operations per second during bursts,
3165 in bytes (Since 1.7)
3166 iops_wr_max: int (optional)
3168 write I/O operations per second during bursts,
3170 in bytes (Since 1.7)
3171 bps_max_length: int (optional)
3173 maximum length of the bps_max burst
3175 period, in seconds. (Since 2.6)
3176 bps_rd_max_length: int (optional)
3178 maximum length of the bps_rd_max
3180 burst period, in seconds. (Since 2.6)
3181 bps_wr_max_length: int (optional)
3183 maximum length of the bps_wr_max
3185 burst period, in seconds. (Since 2.6)
3186 iops_max_length: int (optional)
3188 maximum length of the iops burst
3190 period, in seconds. (Since 2.6)
3191 iops_rd_max_length: int (optional)
3193 maximum length of the iops_rd_max
3195 burst period, in seconds. (Since 2.6)
3196 iops_wr_max_length: int (optional)
3198 maximum length of the iops_wr_max
3200 burst period, in seconds. (Since 2.6)
3201 iops_size: int (optional)
3203 an I/O size in bytes (Since 1.7)
3204 group: string (optional)
3206 throttle group name (Since 2.4)
3207 cache: BlockdevCacheInfo
3209 the cache mode used for the block device (since: 2.3)
3210 write_threshold: int
3212 configured write threshold for the device. 0 if disabled.
3213 (Since 2.3)
3214 dirty-bitmaps: array of BlockDirtyInfo (optional)
3216 dirty bitmaps information (only present if node has one or more
3217 dirty bitmaps) (Since 4.2)
3218 Since
3220 0.14
3221 BlockDeviceIoStatus (Enum)
3223 An enumeration of block device I/O status.
3224 Values
3226 ok The last I/O operation has succeeded
3227 failed The last I/O operation has failed
3229 nospace
3231 The last I/O operation has failed due to a no-space condition
3232 Since
3234 1.0
3235 BlockDirtyInfo (Object)
3237 Block dirty bitmap information.
3238 Members
3240 name: string (optional)
3241 the name of the dirty bitmap (Since 2.4)
3242 count: int
3244 number of dirty bytes according to the dirty bitmap
3245 granularity: int
3247 granularity of the dirty bitmap in bytes (since 1.4)
3248 recording: boolean
3250 true if the bitmap is recording new writes from the guest. Re‐
3251 places active and disabled statuses. (since 4.0)
3252 busy: boolean
3254 true if the bitmap is in-use by some operation (NBD or jobs) and
3255 cannot be modified via QMP or used by another operation. Re‐
3256 places locked and frozen statuses. (since 4.0)
3257 persistent: boolean
3259 true if the bitmap was stored on disk, is scheduled to be stored
3260 on disk, or both. (since 4.0)
3261 inconsistent: boolean (optional)
3263 true if this is a persistent bitmap that was improperly stored.
3264 Implies persistent to be true; recording and busy to be false.
3265 This bitmap cannot be used. To remove it, use block-dirty-bit‐
3266 map-remove. (Since 4.0)
3267 Since
3269 1.3
3270 Qcow2BitmapInfoFlags (Enum)
3272 An enumeration of flags that a bitmap can report to the user.
3273 Values
3275 in-use This flag is set by any process actively modifying the qcow2
3276 file, and cleared when the updated bitmap is flushed to the
3277 qcow2 image. The presence of this flag in an offline image
3278 means that the bitmap was not saved correctly after its last us‐
3279 age, and may contain inconsistent data.
3280 auto The bitmap must reflect all changes of the virtual disk by any
3282 application that would write to this qcow2 file.
3283 Since
3285 4.0
3286 Qcow2BitmapInfo (Object)
3288 Qcow2 bitmap information.
3289 Members
3291 name: string
3292 the name of the bitmap
3293 granularity: int
3295 granularity of the bitmap in bytes
3296 flags: array of Qcow2BitmapInfoFlags
3298 flags of the bitmap
3299 Since
3301 4.0
3302 BlockLatencyHistogramInfo (Object)
3304 Block latency histogram.
3305 Members
3307 boundaries: array of int
3308 list of interval boundary values in nanoseconds, all greater
3309 than zero and in ascending order. For example, the list [10,
3310 50, 100] produces the following histogram intervals: [0, 10),
3311 [10, 50), [50, 100), [100, +inf).
3312 bins: array of int
3314 list of io request counts corresponding to histogram intervals.
3315 len(bins) = len(boundaries) + 1 For the example above, bins may
3316 be something like [3, 1, 5, 2], and corresponding histogram
3317 looks like:
3318 5| *
3320 4| *
3321 3| * *
3322 2| * * *
3323 1| * * * *
3324 +------------------
3325 10 50 100
3326 Since
3328 4.0
3329 BlockInfo (Object)
3331 Block device information. This structure describes a virtual device
3332 and the backing device associated with it.
3333 Members
3335 device: string
3336 The device name associated with the virtual device.
3337 qdev: string (optional)
3339 The qdev ID, or if no ID is assigned, the QOM path of the block
3340 device. (since 2.10)
3341 type: string
3343 This field is returned only for compatibility reasons, it should
3344 not be used (always returns 'unknown')
3345 removable: boolean
3347 True if the device supports removable media.
3348 locked: boolean
3350 True if the guest has locked this device from having its media
3351 removed
3352 tray_open: boolean (optional)
3354 True if the device's tray is open (only present if it has a
3355 tray)
3356 io-status: BlockDeviceIoStatus (optional)
3358 BlockDeviceIoStatus. Only present if the device supports it and
3359 the VM is configured to stop on errors (supported device models:
3360 virtio-blk, IDE, SCSI except scsi-generic)
3361 inserted: BlockDeviceInfo (optional)
3363 BlockDeviceInfo describing the device if media is present
3364 Since
3366 0.14
3367 BlockMeasureInfo (Object)
3369 Image file size calculation information. This structure describes the
3370 size requirements for creating a new image file.
3371 The size requirements depend on the new image file format. File size
3373 always equals virtual disk size for the 'raw' format, even for sparse
3374 POSIX files. Compact formats such as 'qcow2' represent unallocated and
3375 zero regions efficiently so file size may be smaller than virtual disk
3376 size.
3377 The values are upper bounds that are guaranteed to fit the new image
3379 file. Subsequent modification, such as internal snapshot or further
3380 bitmap creation, may require additional space and is not covered here.
3381 Members
3383 required: int
3384 Size required for a new image file, in bytes, when copying just
3385 allocated guest-visible contents.
3386 fully-allocated: int
3388 Image file size, in bytes, once data has been written to all
3389 sectors, when copying just guest-visible contents.
3390 bitmaps: int (optional)
3392 Additional size required if all the top-level bitmap metadata in
3393 the source image were to be copied to the destination, present
3394 only when source and destination both support persistent bit‐
3395 maps. (since 5.1)
3396 Since
3398 2.10
3399 query-block (Command)
3401 Get a list of BlockInfo for all virtual block devices.
3402 Returns
3404 a list of BlockInfo describing each virtual block device. Filter nodes
3405 that were created implicitly are skipped over.
3406 Since
3408 0.14
3409 Example
3411 -> { "execute": "query-block" }
3412 <- {
3413 "return":[
3414 {
3415 "io-status": "ok",
3416 "device":"ide0-hd0",
3417 "locked":false,
3418 "removable":false,
3419 "inserted":{
3420 "ro":false,
3421 "drv":"qcow2",
3422 "encrypted":false,
3423 "file":"disks/test.qcow2",
3424 "backing_file_depth":1,
3425 "bps":1000000,
3426 "bps_rd":0,
3427 "bps_wr":0,
3428 "iops":1000000,
3429 "iops_rd":0,
3430 "iops_wr":0,
3431 "bps_max": 8000000,
3432 "bps_rd_max": 0,
3433 "bps_wr_max": 0,
3434 "iops_max": 0,
3435 "iops_rd_max": 0,
3436 "iops_wr_max": 0,
3437 "iops_size": 0,
3438 "detect_zeroes": "on",
3439 "write_threshold": 0,
3440 "image":{
3441 "filename":"disks/test.qcow2",
3442 "format":"qcow2",
3443 "virtual-size":2048000,
3444 "backing_file":"base.qcow2",
3445 "full-backing-filename":"disks/base.qcow2",
3446 "backing-filename-format":"qcow2",
3447 "snapshots":[
3448 {
3449 "id": "1",
3450 "name": "snapshot1",
3451 "vm-state-size": 0,
3452 "date-sec": 10000200,
3453 "date-nsec": 12,
3454 "vm-clock-sec": 206,
3455 "vm-clock-nsec": 30
3456 }
3457 ],
3458 "backing-image":{
3459 "filename":"disks/base.qcow2",
3460 "format":"qcow2",
3461 "virtual-size":2048000
3462 }
3463 }
3464 },
3465 "qdev": "ide_disk",
3466 "type":"unknown"
3467 },
3468 {
3469 "io-status": "ok",
3470 "device":"ide1-cd0",
3471 "locked":false,
3472 "removable":true,
3473 "qdev": "/machine/unattached/device[23]",
3474 "tray_open": false,
3475 "type":"unknown"
3476 },
3477 {
3478 "device":"floppy0",
3479 "locked":false,
3480 "removable":true,
3481 "qdev": "/machine/unattached/device[20]",
3482 "type":"unknown"
3483 },
3484 {
3485 "device":"sd0",
3486 "locked":false,
3487 "removable":true,
3488 "type":"unknown"
3489 }
3490 ]
3491 }
3492 BlockDeviceTimedStats (Object)
3494 Statistics of a block device during a given interval of time.
3495 Members
3497 interval_length: int
3498 Interval used for calculating the statistics, in seconds.
3499 min_rd_latency_ns: int
3501 Minimum latency of read operations in the defined interval, in
3502 nanoseconds.
3503 min_wr_latency_ns: int
3505 Minimum latency of write operations in the defined interval, in
3506 nanoseconds.
3507 min_flush_latency_ns: int
3509 Minimum latency of flush operations in the defined interval, in
3510 nanoseconds.
3511 max_rd_latency_ns: int
3513 Maximum latency of read operations in the defined interval, in
3514 nanoseconds.
3515 max_wr_latency_ns: int
3517 Maximum latency of write operations in the defined interval, in
3518 nanoseconds.
3519 max_flush_latency_ns: int
3521 Maximum latency of flush operations in the defined interval, in
3522 nanoseconds.
3523 avg_rd_latency_ns: int
3525 Average latency of read operations in the defined interval, in
3526 nanoseconds.
3527 avg_wr_latency_ns: int
3529 Average latency of write operations in the defined interval, in
3530 nanoseconds.
3531 avg_flush_latency_ns: int
3533 Average latency of flush operations in the defined interval, in
3534 nanoseconds.
3535 avg_rd_queue_depth: number
3537 Average number of pending read operations in the defined inter‐
3538 val.
3539 avg_wr_queue_depth: number
3541 Average number of pending write operations in the defined inter‐
3542 val.
3543 Since
3545 2.5
3546 BlockDeviceStats (Object)
3548 Statistics of a virtual block device or a block backing device.
3549 Members
3551 rd_bytes: int
3552 The number of bytes read by the device.
3553 wr_bytes: int
3555 The number of bytes written by the device.
3556 unmap_bytes: int
3558 The number of bytes unmapped by the device (Since 4.2)
3559 rd_operations: int
3561 The number of read operations performed by the device.
3562 wr_operations: int
3564 The number of write operations performed by the device.
3565 flush_operations: int
3567 The number of cache flush operations performed by the device
3568 (since 0.15)
3569 unmap_operations: int
3571 The number of unmap operations performed by the device (Since
3572 4.2)
3573 rd_total_time_ns: int
3575 Total time spent on reads in nanoseconds (since 0.15).
3576 wr_total_time_ns: int
3578 Total time spent on writes in nanoseconds (since 0.15).
3579 flush_total_time_ns: int
3581 Total time spent on cache flushes in nanoseconds (since 0.15).
3582 unmap_total_time_ns: int
3584 Total time spent on unmap operations in nanoseconds (Since 4.2)
3585 wr_highest_offset: int
3587 The offset after the greatest byte written to the device. The
3588 intended use of this information is for growable sparse files
3589 (like qcow2) that are used on top of a physical device.
3590 rd_merged: int
3592 Number of read requests that have been merged into another re‐
3593 quest (Since 2.3).
3594 wr_merged: int
3596 Number of write requests that have been merged into another re‐
3597 quest (Since 2.3).
3598 unmap_merged: int
3600 Number of unmap requests that have been merged into another re‐
3601 quest (Since 4.2)
3602 idle_time_ns: int (optional)
3604 Time since the last I/O operation, in nanoseconds. If the field
3605 is absent it means that there haven't been any operations yet
3606 (Since 2.5).
3607 failed_rd_operations: int
3609 The number of failed read operations performed by the device
3610 (Since 2.5)
3611 failed_wr_operations: int
3613 The number of failed write operations performed by the device
3614 (Since 2.5)
3615 failed_flush_operations: int
3617 The number of failed flush operations performed by the device
3618 (Since 2.5)
3619 failed_unmap_operations: int
3621 The number of failed unmap operations performed by the device
3622 (Since 4.2)
3623 invalid_rd_operations: int
3625 The number of invalid read operations
3627 performed by the device (Since 2.5)
3628 invalid_wr_operations: int
3630 The number of invalid write operations performed by the device
3631 (Since 2.5)
3632 invalid_flush_operations: int
3634 The number of invalid flush operations performed by the device
3635 (Since 2.5)
3636 invalid_unmap_operations: int
3638 The number of invalid unmap operations performed by the device
3639 (Since 4.2)
3640 account_invalid: boolean
3642 Whether invalid operations are included in the last access sta‐
3643 tistics (Since 2.5)
3644 account_failed: boolean
3646 Whether failed operations are included in the latency and last
3647 access statistics (Since 2.5)
3648 timed_stats: array of BlockDeviceTimedStats
3650 Statistics specific to the set of previously defined intervals
3651 of time (Since 2.5)
3652 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
3654 BlockLatencyHistogramInfo. (Since 4.0)
3655 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
3657 BlockLatencyHistogramInfo. (Since 4.0)
3658 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
3660 BlockLatencyHistogramInfo. (Since 4.0)
3661 Since
3663 0.14
3664 BlockStatsSpecificFile (Object)
3666 File driver statistics
3667 Members
3669 discard-nb-ok: int
3670 The number of successful discard operations performed by the
3671 driver.
3672 discard-nb-failed: int
3674 The number of failed discard operations performed by the driver.
3675 discard-bytes-ok: int
3677 The number of bytes discarded by the driver.
3678 Since
3680 4.2
3681 BlockStatsSpecificNvme (Object)
3683 NVMe driver statistics
3684 Members
3686 completion-errors: int
3687 The number of completion errors.
3688 aligned-accesses: int
3690 The number of aligned accesses performed by the driver.
3691 unaligned-accesses: int
3693 The number of unaligned accesses performed by the driver.
3694 Since
3696 5.2
3697 BlockStatsSpecific (Object)
3699 Block driver specific statistics
3700 Members
3702 driver: BlockdevDriver
3703 Not documented
3704 The members of BlockStatsSpecificFile when driver is "file"
3706 The members of BlockStatsSpecificFile when driver is "host_device" (If:
3708 defined(HAVE_HOST_BLOCK_DEVICE))
3709 The members of BlockStatsSpecificNvme when driver is "nvme"
3711 Since
3713 4.2
3714 BlockStats (Object)
3716 Statistics of a virtual block device or a block backing device.
3717 Members
3719 device: string (optional)
3720 If the stats are for a virtual block device, the name corre‐
3721 sponding to the virtual block device.
3722 node-name: string (optional)
3724 The node name of the device. (Since 2.3)
3725 qdev: string (optional)
3727 The qdev ID, or if no ID is assigned, the QOM path of the block
3728 device. (since 3.0)
3729 stats: BlockDeviceStats
3731 A BlockDeviceStats for the device.
3732 driver-specific: BlockStatsSpecific (optional)
3734 Optional driver-specific stats. (Since 4.2)
3735 parent: BlockStats (optional)
3737 This describes the file block device if it has one. Contains
3738 recursively the statistics of the underlying protocol (e.g. the
3739 host file for a qcow2 image). If there is no underlying proto‐
3740 col, this field is omitted
3741 backing: BlockStats (optional)
3743 This describes the backing block device if it has one. (Since
3744 2.0)
3745 Since
3747 0.14
3748 query-blockstats (Command)
3750 Query the BlockStats for all virtual block devices.
3751 Arguments
3753 query-nodes: boolean (optional)
3754 If true, the command will query all the block nodes that have a
3755 node name, in a list which will include "parent" information,
3756 but not "backing". If false or omitted, the behavior is as be‐
3757 fore - query all the device backends, recursively including
3758 their "parent" and "backing". Filter nodes that were created im‐
3759 plicitly are skipped over in this mode. (Since 2.3)
3760 Returns
3762 A list of BlockStats for each virtual block devices.
3763 Since
3765 0.14
3766 Example
3768 -> { "execute": "query-blockstats" }
3769 <- {
3770 "return":[
3771 {
3772 "device":"ide0-hd0",
3773 "parent":{
3774 "stats":{
3775 "wr_highest_offset":3686448128,
3776 "wr_bytes":9786368,
3777 "wr_operations":751,
3778 "rd_bytes":122567168,
3779 "rd_operations":36772
3780 "wr_total_times_ns":313253456
3781 "rd_total_times_ns":3465673657
3782 "flush_total_times_ns":49653
3783 "flush_operations":61,
3784 "rd_merged":0,
3785 "wr_merged":0,
3786 "idle_time_ns":2953431879,
3787 "account_invalid":true,
3788 "account_failed":false
3789 }
3790 },
3791 "stats":{
3792 "wr_highest_offset":2821110784,
3793 "wr_bytes":9786368,
3794 "wr_operations":692,
3795 "rd_bytes":122739200,
3796 "rd_operations":36604
3797 "flush_operations":51,
3798 "wr_total_times_ns":313253456
3799 "rd_total_times_ns":3465673657
3800 "flush_total_times_ns":49653,
3801 "rd_merged":0,
3802 "wr_merged":0,
3803 "idle_time_ns":2953431879,
3804 "account_invalid":true,
3805 "account_failed":false
3806 },
3807 "qdev": "/machine/unattached/device[23]"
3808 },
3809 {
3810 "device":"ide1-cd0",
3811 "stats":{
3812 "wr_highest_offset":0,
3813 "wr_bytes":0,
3814 "wr_operations":0,
3815 "rd_bytes":0,
3816 "rd_operations":0
3817 "flush_operations":0,
3818 "wr_total_times_ns":0
3819 "rd_total_times_ns":0
3820 "flush_total_times_ns":0,
3821 "rd_merged":0,
3822 "wr_merged":0,
3823 "account_invalid":false,
3824 "account_failed":false
3825 },
3826 "qdev": "/machine/unattached/device[24]"
3827 },
3828 {
3829 "device":"floppy0",
3830 "stats":{
3831 "wr_highest_offset":0,
3832 "wr_bytes":0,
3833 "wr_operations":0,
3834 "rd_bytes":0,
3835 "rd_operations":0
3836 "flush_operations":0,
3837 "wr_total_times_ns":0
3838 "rd_total_times_ns":0
3839 "flush_total_times_ns":0,
3840 "rd_merged":0,
3841 "wr_merged":0,
3842 "account_invalid":false,
3843 "account_failed":false
3844 },
3845 "qdev": "/machine/unattached/device[16]"
3846 },
3847 {
3848 "device":"sd0",
3849 "stats":{
3850 "wr_highest_offset":0,
3851 "wr_bytes":0,
3852 "wr_operations":0,
3853 "rd_bytes":0,
3854 "rd_operations":0
3855 "flush_operations":0,
3856 "wr_total_times_ns":0
3857 "rd_total_times_ns":0
3858 "flush_total_times_ns":0,
3859 "rd_merged":0,
3860 "wr_merged":0,
3861 "account_invalid":false,
3862 "account_failed":false
3863 }
3864 }
3865 ]
3866 }
3867 BlockdevOnError (Enum)
3869 An enumeration of possible behaviors for errors on I/O operations. The
3870 exact meaning depends on whether the I/O was initiated by a guest or by
3871 a block job
3872 Values
3874 report for guest operations, report the error to the guest; for jobs,
3875 cancel the job
3876 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
3878 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
3879 the failing request later and may still complete successfully.
3880 The stream block job continues to stream and will complete with
3881 an error.
3882 enospc same as stop on ENOSPC, same as report otherwise.
3884 stop for guest operations, stop the virtual machine; for jobs, pause
3886 the job
3887 auto inherit the error handling policy of the backend (since: 2.7)
3889 Since
3891 1.3
3892 MirrorSyncMode (Enum)
3894 An enumeration of possible behaviors for the initial synchronization
3895 phase of storage mirroring.
3896 Values
3898 top copies data in the topmost image to the destination
3899 full copies data from all images to the destination
3901 none only copy data written from now on
3903 incremental
3905 only copy data described by the dirty bitmap. (since: 2.4)
3906 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
3908 havior on completion is determined by the BitmapSyncMode.
3909 Since
3911 1.3
3912 BitmapSyncMode (Enum)
3914 An enumeration of possible behaviors for the synchronization of a bit‐
3915 map when used for data copy operations.
3916 Values
3918 on-success
3919 The bitmap is only synced when the operation is successful.
3920 This is the behavior always used for 'INCREMENTAL' backups.
3921 never The bitmap is never synchronized with the operation, and is
3923 treated solely as a read-only manifest of blocks to copy.
3924 always The bitmap is always synchronized with the operation, regardless
3926 of whether or not the operation was successful.
3927 Since
3929 4.2
3930 MirrorCopyMode (Enum)
3932 An enumeration whose values tell the mirror block job when to trigger
3933 writes to the target.
3934 Values
3936 background
3937 copy data in background only.
3938 write-blocking
3940 when data is written to the source, write it (synchronously) to
3941 the target as well. In addition, data is copied in background
3942 just like in background mode.
3943 Since
3945 3.0
3946 BlockJobInfo (Object)
3948 Information about a long-running block device operation.
3949 Members
3951 type: string
3952 the job type ('stream' for image streaming)
3953 device: string
3955 The job identifier. Originally the device name but other values
3956 are allowed since QEMU 2.7
3957 len: int
3959 Estimated offset value at the completion of the job. This value
3960 can arbitrarily change while the job is running, in both direc‐
3961 tions.
3962 offset: int
3964 Progress made until now. The unit is arbitrary and the value can
3965 only meaningfully be used for the ratio of offset to len. The
3966 value is monotonically increasing.
3967 busy: boolean
3969 false if the job is known to be in a quiescent state, with no
3970 pending I/O. Since 1.3.
3971 paused: boolean
3973 whether the job is paused or, if busy is true, will pause itself
3974 as soon as possible. Since 1.3.
3975 speed: int
3977 the rate limit, bytes per second
3978 io-status: BlockDeviceIoStatus
3980 the status of the job (since 1.3)
3981 ready: boolean
3983 true if the job may be completed (since 2.2)
3984 status: JobStatus
3986 Current job state/status (since 2.12)
3987 auto-finalize: boolean
3989 Job will finalize itself when PENDING, moving to the CONCLUDED
3990 state. (since 2.12)
3991 auto-dismiss: boolean
3993 Job will dismiss itself when CONCLUDED, moving to the NULL state
3994 and disappearing from the query list. (since 2.12)
3995 error: string (optional)
3997 Error information if the job did not complete successfully. Not
3998 set if the job completed successfully. (since 2.12.1)
3999 Since
4001 1.1
4002 query-block-jobs (Command)
4004 Return information about long-running block device operations.
4005 Returns
4007 a list of BlockJobInfo for each active block job
4008 Since
4010 1.1
4011 block_resize (Command)
4013 Resize a block image while a guest is running.
4014 Either device or node-name must be set but not both.
4016 Arguments
4018 device: string (optional)
4019 the name of the device to get the image resized
4020 node-name: string (optional)
4022 graph node name to get the image resized (Since 2.0)
4023 size: int
4025 new image size in bytes
4026 Returns
4028 • nothing on success
4029 • If device is not a valid block device, DeviceNotFound
4031 Since
4033 0.14
4034 Example
4036 -> { "execute": "block_resize",
4037 "arguments": { "device": "scratch", "size": 1073741824 } }
4038 <- { "return": {} }
4039 NewImageMode (Enum)
4041 An enumeration that tells QEMU how to set the backing file path in a
4042 new image file.
4043 Values
4045 existing
4046 QEMU should look for an existing image file.
4047 absolute-paths
4049 QEMU should create a new image with absolute paths for the back‐
4050 ing file. If there is no backing file available, the new image
4051 will not be backed either.
4052 Since
4054 1.1
4055 BlockdevSnapshotSync (Object)
4057 Either device or node-name must be set but not both.
4058 Members
4060 device: string (optional)
4061 the name of the device to take a snapshot of.
4062 node-name: string (optional)
4064 graph node name to generate the snapshot from (Since 2.0)
4065 snapshot-file: string
4067 the target of the new overlay image. If the file exists, or if
4068 it is a device, the overlay will be created in the existing
4069 file/device. Otherwise, a new file will be created.
4070 snapshot-node-name: string (optional)
4072 the graph node name of the new image (Since 2.0)
4073 format: string (optional)
4075 the format of the overlay image, default is 'qcow2'.
4076 mode: NewImageMode (optional)
4078 whether and how QEMU should create a new image, default is 'ab‐
4079 solute-paths'.
4080 BlockdevSnapshot (Object)
4082 Members
4083 node: string
4084 device or node name that will have a snapshot taken.
4085 overlay: string
4087 reference to the existing block device that will become the
4088 overlay of node, as part of taking the snapshot. It must not
4089 have a current backing file (this can be achieved by passing
4090 "backing": null to blockdev-add).
4091 Since
4093 2.5
4094 BackupPerf (Object)
4096 Optional parameters for backup. These parameters don't affect function‐
4097 ality, but may significantly affect performance.
4098 Members
4100 use-copy-range: boolean (optional)
4101 Use copy offloading. Default false.
4102 max-workers: int (optional)
4104 Maximum number of parallel requests for the sustained background
4105 copying process. Doesn't influence copy-before-write operations.
4106 Default 64.
4107 max-chunk: int (optional)
4109 Maximum request length for the sustained background copying
4110 process. Doesn't influence copy-before-write operations. 0
4111 means unlimited. If max-chunk is non-zero then it should not be
4112 less than job cluster size which is calculated as maximum of
4113 target image cluster size and 64k. Default 0.
4114 Since
4116 6.0
4117 BackupCommon (Object)
4119 Members
4120 job-id: string (optional)
4121 identifier for the newly-created block job. If omitted, the de‐
4122 vice name will be used. (Since 2.7)
4123 device: string
4125 the device name or node-name of a root node which should be
4126 copied.
4127 sync: MirrorSyncMode
4129 what parts of the disk image should be copied to the destination
4130 (all the disk, only the sectors allocated in the topmost image,
4131 from a dirty bitmap, or only new I/O).
4132 speed: int (optional)
4134 the maximum speed, in bytes per second. The default is 0, for
4135 unlimited.
4136 bitmap: string (optional)
4138 The name of a dirty bitmap to use. Must be present if sync is
4139 "bitmap" or "incremental". Can be present if sync is "full" or
4140 "top". Must not be present otherwise. (Since 2.4
4141 (drive-backup), 3.1 (blockdev-backup))
4142 bitmap-mode: BitmapSyncMode (optional)
4144 Specifies the type of data the bitmap should contain after the
4145 operation concludes. Must be present if a bitmap was provided,
4146 Must NOT be present otherwise. (Since 4.2)
4147 compress: boolean (optional)
4149 true to compress data, if the target format supports it. (de‐
4150 fault: false) (since 2.8)
4151 on-source-error: BlockdevOnError (optional)
4153 the action to take on an error on the source, default 'report'.
4154 'stop' and 'enospc' can only be used if the block device sup‐
4155 ports io-status (see BlockInfo).
4156 on-target-error: BlockdevOnError (optional)
4158 the action to take on an error on the target, default 'report'
4159 (no limitations, since this applies to a different block device
4160 than device).
4161 auto-finalize: boolean (optional)
4163 When false, this job will wait in a PENDING state after it has
4164 finished its work, waiting for block-job-finalize before making
4165 any block graph changes. When true, this job will automatically
4166 perform its abort or commit actions. Defaults to true. (Since
4167 2.12)
4168 auto-dismiss: boolean (optional)
4170 When false, this job will wait in a CONCLUDED state after it has
4171 completely ceased all work, and awaits block-job-dismiss. When
4172 true, this job will automatically disappear from the query list
4173 without user intervention. Defaults to true. (Since 2.12)
4174 filter-node-name: string (optional)
4176 the node name that should be assigned to the filter driver that
4177 the backup job inserts into the graph above node specified by
4178 drive. If this option is not given, a node name is autogener‐
4179 ated. (Since: 4.2)
4180 x-perf: BackupPerf (optional)
4182 Performance options. (Since 6.0)
4183 Note
4185 on-source-error and on-target-error only affect background I/O. If an
4186 error occurs during a guest write request, the device's rerror/werror
4187 actions will be used.
4188 Since
4190 4.2
4191 DriveBackup (Object)
4193 Members
4194 target: string
4195 the target of the new image. If the file exists, or if it is a
4196 device, the existing file/device will be used as the new desti‐
4197 nation. If it does not exist, a new file will be created.
4198 format: string (optional)
4200 the format of the new destination, default is to probe if mode
4201 is 'existing', else the format of the source
4202 mode: NewImageMode (optional)
4204 whether and how QEMU should create a new image, default is 'ab‐
4205 solute-paths'.
4206 The members of BackupCommon
4208 Since
4210 1.6
4211 BlockdevBackup (Object)
4213 Members
4214 target: string
4215 the device name or node-name of the backup target node.
4216 The members of BackupCommon
4218 Since
4220 2.3
4221 blockdev-snapshot-sync (Command)
4223 Takes a synchronous snapshot of a block device.
4224 For the arguments, see the documentation of BlockdevSnapshotSync.
4226 Returns
4228 • nothing on success
4229 • If device is not a valid block device, DeviceNotFound
4231 Since
4233 0.14
4234 Example
4236 -> { "execute": "blockdev-snapshot-sync",
4237 "arguments": { "device": "ide-hd0",
4238 "snapshot-file":
4239 "/some/place/my-image",
4240 "format": "qcow2" } }
4241 <- { "return": {} }
4242 blockdev-snapshot (Command)
4244 Takes a snapshot of a block device.
4245 Take a snapshot, by installing 'node' as the backing image of 'over‐
4247 lay'. Additionally, if 'node' is associated with a block device, the
4248 block device changes to using 'overlay' as its new active image.
4249 For the arguments, see the documentation of BlockdevSnapshot.
4251 Features
4253 allow-write-only-overlay
4254 If present, the check whether this operation is safe was relaxed
4255 so that it can be used to change backing file of a destination
4256 of a blockdev-mirror. (since 5.0)
4257 Since
4259 2.5
4260 Example
4262 -> { "execute": "blockdev-add",
4263 "arguments": { "driver": "qcow2",
4264 "node-name": "node1534",
4265 "file": { "driver": "file",
4266 "filename": "hd1.qcow2" },
4267 "backing": null } }
4268 <- { "return": {} }
4270 -> { "execute": "blockdev-snapshot",
4272 "arguments": { "node": "ide-hd0",
4273 "overlay": "node1534" } }
4274 <- { "return": {} }
4275 change-backing-file (Command)
4277 Change the backing file in the image file metadata. This does not
4278 cause QEMU to reopen the image file to reparse the backing filename (it
4279 may, however, perform a reopen to change permissions from r/o -> r/w ->
4280 r/o, if needed). The new backing file string is written into the image
4281 file metadata, and the QEMU internal strings are updated.
4282 Arguments
4284 image-node-name: string
4285 The name of the block driver state node of the image to modify.
4286 The "device" argument is used to verify "image-node-name" is in
4287 the chain described by "device".
4288 device: string
4290 The device name or node-name of the root node that owns im‐
4291 age-node-name.
4292 backing-file: string
4294 The string to write as the backing file. This string is not
4295 validated, so care should be taken when specifying the string or
4296 the image chain may not be able to be reopened again.
4297 Returns
4299 • Nothing on success
4300 • If "device" does not exist or cannot be determined, DeviceNotFound
4302 Since
4304 2.1
4305 block-commit (Command)
4307 Live commit of data from overlay image nodes into backing nodes - i.e.,
4308 writes data between 'top' and 'base' into 'base'.
4309 If top == base, that is an error. If top has no overlays on top of it,
4311 or if it is in use by a writer, the job will not be completed by it‐
4312 self. The user needs to complete the job with the block-job-complete
4313 command after getting the ready event. (Since 2.0)
4314 If the base image is smaller than top, then the base image will be re‐
4316 sized to be the same size as top. If top is smaller than the base im‐
4317 age, the base will not be truncated. If you want the base image size
4318 to match the size of the smaller top, you can safely truncate it your‐
4319 self once the commit operation successfully completes.
4320 Arguments
4322 job-id: string (optional)
4323 identifier for the newly-created block job. If omitted, the de‐
4324 vice name will be used. (Since 2.7)
4325 device: string
4327 the device name or node-name of a root node
4328 base-node: string (optional)
4330 The node name of the backing image to write data into. If not
4331 specified, this is the deepest backing image. (since: 3.1)
4332 base: string (optional)
4334 Same as base-node, except that it is a file name rather than a
4335 node name. This must be the exact filename string that was used
4336 to open the node; other strings, even if addressing the same
4337 file, are not accepted
4338 top-node: string (optional)
4340 The node name of the backing image within the image chain which
4341 contains the topmost data to be committed down. If not speci‐
4342 fied, this is the active layer. (since: 3.1)
4343 top: string (optional)
4345 Same as top-node, except that it is a file name rather than a
4346 node name. This must be the exact filename string that was used
4347 to open the node; other strings, even if addressing the same
4348 file, are not accepted
4349 backing-file: string (optional)
4351 The backing file string to write into the overlay image of
4352 'top'. If 'top' does not have an overlay image, or if 'top' is
4353 in use by a writer, specifying a backing file string is an er‐
4354 ror.
4355 This filename is not validated. If a pathname string is such
4357 that it cannot be resolved by QEMU, that means that subsequent
4358 QMP or HMP commands must use node-names for the image in ques‐
4359 tion, as filename lookup methods will fail.
4360 If not specified, QEMU will automatically determine the backing
4362 file string to use, or error out if there is no obvious choice.
4363 Care should be taken when specifying the string, to specify a
4364 valid filename or protocol. (Since 2.1)
4365 speed: int (optional)
4367 the maximum speed, in bytes per second
4368 on-error: BlockdevOnError (optional)
4370 the action to take on an error. 'ignore' means that the request
4371 should be retried. (default: report; Since: 5.0)
4372 filter-node-name: string (optional)
4374 the node name that should be assigned to the filter driver that
4375 the commit job inserts into the graph above top. If this option
4376 is not given, a node name is autogenerated. (Since: 2.9)
4377 auto-finalize: boolean (optional)
4379 When false, this job will wait in a PENDING state after it has
4380 finished its work, waiting for block-job-finalize before making
4381 any block graph changes. When true, this job will automatically
4382 perform its abort or commit actions. Defaults to true. (Since
4383 3.1)
4384 auto-dismiss: boolean (optional)
4386 When false, this job will wait in a CONCLUDED state after it has
4387 completely ceased all work, and awaits block-job-dismiss. When
4388 true, this job will automatically disappear from the query list
4389 without user intervention. Defaults to true. (Since 3.1)
4390 Features
4392 deprecated
4393 Members base and top are deprecated. Use base-node and top-node
4394 instead.
4395 Returns
4397 • Nothing on success
4398 • If device does not exist, DeviceNotFound
4400 • Any other error returns a GenericError.
4402 Since
4404 1.3
4405 Example
4407 -> { "execute": "block-commit",
4408 "arguments": { "device": "virtio0",
4409 "top": "/tmp/snap1.qcow2" } }
4410 <- { "return": {} }
4411 drive-backup (Command)
4413 Start a point-in-time copy of a block device to a new destination. The
4414 status of ongoing drive-backup operations can be checked with
4415 query-block-jobs where the BlockJobInfo.type field has the value
4416 'backup'. The operation can be stopped before it has completed using
4417 the block-job-cancel command.
4418 Arguments
4420 The members of DriveBackup
4421 Returns
4423 • nothing on success
4424 • If device is not a valid block device, GenericError
4426 Since
4428 1.6
4429 Example
4431 -> { "execute": "drive-backup",
4432 "arguments": { "device": "drive0",
4433 "sync": "full",
4434 "target": "backup.img" } }
4435 <- { "return": {} }
4436 blockdev-backup (Command)
4438 Start a point-in-time copy of a block device to a new destination. The
4439 status of ongoing blockdev-backup operations can be checked with
4440 query-block-jobs where the BlockJobInfo.type field has the value
4441 'backup'. The operation can be stopped before it has completed using
4442 the block-job-cancel command.
4443 Arguments
4445 The members of BlockdevBackup
4446 Returns
4448 • nothing on success
4449 • If device is not a valid block device, DeviceNotFound
4451 Since
4453 2.3
4454 Example
4456 -> { "execute": "blockdev-backup",
4457 "arguments": { "device": "src-id",
4458 "sync": "full",
4459 "target": "tgt-id" } }
4460 <- { "return": {} }
4461 query-named-block-nodes (Command)
4463 Get the named block driver list
4464 Arguments
4466 flat: boolean (optional)
4467 Omit the nested data about backing image ("backing-image" key)
4468 if true. Default is false (Since 5.0)
4469 Returns
4471 the list of BlockDeviceInfo
4472 Since
4474 2.0
4475 Example
4477 -> { "execute": "query-named-block-nodes" }
4478 <- { "return": [ { "ro":false,
4479 "drv":"qcow2",
4480 "encrypted":false,
4481 "file":"disks/test.qcow2",
4482 "node-name": "my-node",
4483 "backing_file_depth":1,
4484 "bps":1000000,
4485 "bps_rd":0,
4486 "bps_wr":0,
4487 "iops":1000000,
4488 "iops_rd":0,
4489 "iops_wr":0,
4490 "bps_max": 8000000,
4491 "bps_rd_max": 0,
4492 "bps_wr_max": 0,
4493 "iops_max": 0,
4494 "iops_rd_max": 0,
4495 "iops_wr_max": 0,
4496 "iops_size": 0,
4497 "write_threshold": 0,
4498 "image":{
4499 "filename":"disks/test.qcow2",
4500 "format":"qcow2",
4501 "virtual-size":2048000,
4502 "backing_file":"base.qcow2",
4503 "full-backing-filename":"disks/base.qcow2",
4504 "backing-filename-format":"qcow2",
4505 "snapshots":[
4506 {
4507 "id": "1",
4508 "name": "snapshot1",
4509 "vm-state-size": 0,
4510 "date-sec": 10000200,
4511 "date-nsec": 12,
4512 "vm-clock-sec": 206,
4513 "vm-clock-nsec": 30
4514 }
4515 ],
4516 "backing-image":{
4517 "filename":"disks/base.qcow2",
4518 "format":"qcow2",
4519 "virtual-size":2048000
4520 }
4521 } } ] }
4522 XDbgBlockGraphNodeType (Enum)
4524 Values
4525 block-backend
4526 corresponds to BlockBackend
4527 block-job
4529 corresponds to BlockJob
4530 block-driver
4532 corresponds to BlockDriverState
4533 Since
4535 4.0
4536 XDbgBlockGraphNode (Object)
4538 Members
4539 id: int
4540 Block graph node identifier. This id is generated only for x-de‐
4541 bug-query-block-graph and does not relate to any other identi‐
4542 fiers in Qemu.
4543 type: XDbgBlockGraphNodeType
4545 Type of graph node. Can be one of block-backend, block-job or
4546 block-driver-state.
4547 name: string
4549 Human readable name of the node. Corresponds to node-name for
4550 block-driver-state nodes; is not guaranteed to be unique in the
4551 whole graph (with block-jobs and block-backends).
4552 Since
4554 4.0
4555 BlockPermission (Enum)
4557 Enum of base block permissions.
4558 Values
4560 consistent-read
4561 A user that has the "permission" of consistent reads is guaran‐
4562 teed that their view of the contents of the block device is com‐
4563 plete and self-consistent, representing the contents of a disk
4564 at a specific point. For most block devices (including their
4565 backing files) this is true, but the property cannot be main‐
4566 tained in a few situations like for intermediate nodes of a com‐
4567 mit block job.
4568 write This permission is required to change the visible disk contents.
4570 write-unchanged
4572 This permission (which is weaker than BLK_PERM_WRITE) is both
4573 enough and required for writes to the block node when the caller
4574 promises that the visible disk content doesn't change. As the
4575 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
4576 cient to perform an unchanging write.
4577 resize This permission is required to change the size of a block node.
4579 graph-mod
4581 This permission is required to change the node that this
4582 BdrvChild points to.
4583 Since
4585 4.0
4586 XDbgBlockGraphEdge (Object)
4588 Block Graph edge description for x-debug-query-block-graph.
4589 Members
4591 parent: int
4592 parent id
4593 child: int
4595 child id
4596 name: string
4598 name of the relation (examples are 'file' and 'backing')
4599 perm: array of BlockPermission
4601 granted permissions for the parent operating on the child
4602 shared-perm: array of BlockPermission
4604 permissions that can still be granted to other users of the
4605 child while it is still attached to this parent
4606 Since
4608 4.0
4609 XDbgBlockGraph (Object)
4611 Block Graph - list of nodes and list of edges.
4612 Members
4614 nodes: array of XDbgBlockGraphNode
4615 Not documented
4616 edges: array of XDbgBlockGraphEdge
4618 Not documented
4619 Since
4621 4.0
4622 x-debug-query-block-graph (Command)
4624 Get the block graph.
4625 Since
4627 4.0
4628 drive-mirror (Command)
4630 Start mirroring a block device's writes to a new destination. target
4631 specifies the target of the new image. If the file exists, or if it is
4632 a device, it will be used as the new destination for writes. If it does
4633 not exist, a new file will be created. format specifies the format of
4634 the mirror image, default is to probe if mode='existing', else the for‐
4635 mat of the source.
4636 Arguments
4638 The members of DriveMirror
4639 Returns
4641 • nothing on success
4642 • If device is not a valid block device, GenericError
4644 Since
4646 1.3
4647 Example
4649 -> { "execute": "drive-mirror",
4650 "arguments": { "device": "ide-hd0",
4651 "target": "/some/place/my-image",
4652 "sync": "full",
4653 "format": "qcow2" } }
4654 <- { "return": {} }
4655 DriveMirror (Object)
4657 A set of parameters describing drive mirror setup.
4658 Members
4660 job-id: string (optional)
4661 identifier for the newly-created block job. If omitted, the de‐
4662 vice name will be used. (Since 2.7)
4663 device: string
4665 the device name or node-name of a root node whose writes should
4666 be mirrored.
4667 target: string
4669 the target of the new image. If the file exists, or if it is a
4670 device, the existing file/device will be used as the new desti‐
4671 nation. If it does not exist, a new file will be created.
4672 format: string (optional)
4674 the format of the new destination, default is to probe if mode
4675 is 'existing', else the format of the source
4676 node-name: string (optional)
4678 the new block driver state node name in the graph (Since 2.1)
4679 replaces: string (optional)
4681 with sync=full graph node name to be replaced by the new image
4682 when a whole image copy is done. This can be used to repair bro‐
4683 ken Quorum files. By default, device is replaced, although im‐
4684 plicitly created filters on it are kept. (Since 2.1)
4685 mode: NewImageMode (optional)
4687 whether and how QEMU should create a new image, default is 'ab‐
4688 solute-paths'.
4689 speed: int (optional)
4691 the maximum speed, in bytes per second
4692 sync: MirrorSyncMode
4694 what parts of the disk image should be copied to the destination
4695 (all the disk, only the sectors allocated in the topmost image,
4696 or only new I/O).
4697 granularity: int (optional)
4699 granularity of the dirty bitmap, default is 64K if the image
4700 format doesn't have clusters, 4K if the clusters are smaller
4701 than that, else the cluster size. Must be a power of 2 between
4702 512 and 64M (since 1.4).
4703 buf-size: int (optional)
4705 maximum amount of data in flight from source to target (since
4706 1.4).
4707 on-source-error: BlockdevOnError (optional)
4709 the action to take on an error on the source, default 'report'.
4710 'stop' and 'enospc' can only be used if the block device sup‐
4711 ports io-status (see BlockInfo).
4712 on-target-error: BlockdevOnError (optional)
4714 the action to take on an error on the target, default 'report'
4715 (no limitations, since this applies to a different block device
4716 than device).
4717 unmap: boolean (optional)
4719 Whether to try to unmap target sectors where source has only
4720 zero. If true, and target unallocated sectors will read as zero,
4721 target image sectors will be unmapped; otherwise, zeroes will be
4722 written. Both will result in identical contents. Default is
4723 true. (Since 2.4)
4724 copy-mode: MirrorCopyMode (optional)
4726 when to copy data to the destination; defaults to 'background'
4727 (Since: 3.0)
4728 auto-finalize: boolean (optional)
4730 When false, this job will wait in a PENDING state after it has
4731 finished its work, waiting for block-job-finalize before making
4732 any block graph changes. When true, this job will automatically
4733 perform its abort or commit actions. Defaults to true. (Since
4734 3.1)
4735 auto-dismiss: boolean (optional)
4737 When false, this job will wait in a CONCLUDED state after it has
4738 completely ceased all work, and awaits block-job-dismiss. When
4739 true, this job will automatically disappear from the query list
4740 without user intervention. Defaults to true. (Since 3.1)
4741 Since
4743 1.3
4744 BlockDirtyBitmap (Object)
4746 Members
4747 node: string
4748 name of device/node which the bitmap is tracking
4749 name: string
4751 name of the dirty bitmap
4752 Since
4754 2.4
4755 BlockDirtyBitmapAdd (Object)
4757 Members
4758 node: string
4759 name of device/node which the bitmap is tracking
4760 name: string
4762 name of the dirty bitmap (must be less than 1024 bytes)
4763 granularity: int (optional)
4765 the bitmap granularity, default is 64k for block-dirty-bit‐
4766 map-add
4767 persistent: boolean (optional)
4769 the bitmap is persistent, i.e. it will be saved to the corre‐
4770 sponding block device image file on its close. For now only
4771 Qcow2 disks support persistent bitmaps. Default is false for
4772 block-dirty-bitmap-add. (Since: 2.10)
4773 disabled: boolean (optional)
4775 the bitmap is created in the disabled state, which means that it
4776 will not track drive changes. The bitmap may be enabled with
4777 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
4778 Since
4780 2.4
4781 BlockDirtyBitmapMergeSource (Alternate)
4783 Members
4784 local: string
4785 name of the bitmap, attached to the same node as target bitmap.
4786 external: BlockDirtyBitmap
4788 bitmap with specified node
4789 Since
4791 4.1
4792 BlockDirtyBitmapMerge (Object)
4794 Members
4795 node: string
4796 name of device/node which the target bitmap is tracking
4797 target: string
4799 name of the destination dirty bitmap
4800 bitmaps: array of BlockDirtyBitmapMergeSource
4802 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
4803 ified BlockDirtyBitmap elements. The latter are supported since
4804 4.1.
4805 Since
4807 4.0
4808 block-dirty-bitmap-add (Command)
4810 Create a dirty bitmap with a name on the node, and start tracking the
4811 writes.
4812 Returns
4814 • nothing on success
4815 • If node is not a valid block device or node, DeviceNotFound
4817 • If name is already taken, GenericError with an explanation
4819 Since
4821 2.4
4822 Example
4824 -> { "execute": "block-dirty-bitmap-add",
4825 "arguments": { "node": "drive0", "name": "bitmap0" } }
4826 <- { "return": {} }
4827 block-dirty-bitmap-remove (Command)
4829 Stop write tracking and remove the dirty bitmap that was created with
4830 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
4831 storage too.
4832 Returns
4834 • nothing on success
4835 • If node is not a valid block device or node, DeviceNotFound
4837 • If name is not found, GenericError with an explanation
4839 • if name is frozen by an operation, GenericError
4841 Since
4843 2.4
4844 Example
4846 -> { "execute": "block-dirty-bitmap-remove",
4847 "arguments": { "node": "drive0", "name": "bitmap0" } }
4848 <- { "return": {} }
4849 block-dirty-bitmap-clear (Command)
4851 Clear (reset) a dirty bitmap on the device, so that an incremental
4852 backup from this point in time forward will only backup clusters modi‐
4853 fied after this clear operation.
4854 Returns
4856 • nothing on success
4857 • If node is not a valid block device, DeviceNotFound
4859 • If name is not found, GenericError with an explanation
4861 Since
4863 2.4
4864 Example
4866 -> { "execute": "block-dirty-bitmap-clear",
4867 "arguments": { "node": "drive0", "name": "bitmap0" } }
4868 <- { "return": {} }
4869 block-dirty-bitmap-enable (Command)
4871 Enables a dirty bitmap so that it will begin tracking disk changes.
4872 Returns
4874 • nothing on success
4875 • If node is not a valid block device, DeviceNotFound
4877 • If name is not found, GenericError with an explanation
4879 Since
4881 4.0
4882 Example
4884 -> { "execute": "block-dirty-bitmap-enable",
4885 "arguments": { "node": "drive0", "name": "bitmap0" } }
4886 <- { "return": {} }
4887 block-dirty-bitmap-disable (Command)
4889 Disables a dirty bitmap so that it will stop tracking disk changes.
4890 Returns
4892 • nothing on success
4893 • If node is not a valid block device, DeviceNotFound
4895 • If name is not found, GenericError with an explanation
4897 Since
4899 4.0
4900 Example
4902 -> { "execute": "block-dirty-bitmap-disable",
4903 "arguments": { "node": "drive0", "name": "bitmap0" } }
4904 <- { "return": {} }
4905 block-dirty-bitmap-merge (Command)
4907 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
4908 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
4909 as the target bitmap. Any bits already set in target will still be set
4910 after the merge, i.e., this operation does not clear the target. On
4911 error, target is unchanged.
4912 The resulting bitmap will count as dirty any clusters that were dirty
4914 in any of the source bitmaps. This can be used to achieve backup check‐
4915 points, or in simpler usages, to copy bitmaps.
4916 Returns
4918 • nothing on success
4919 • If node is not a valid block device, DeviceNotFound
4921 • If any bitmap in bitmaps or target is not found, GenericError
4923 • If any of the bitmaps have different sizes or granularities, Gener‐
4925 icError
4926 Since
4928 4.0
4929 Example
4931 -> { "execute": "block-dirty-bitmap-merge",
4932 "arguments": { "node": "drive0", "target": "bitmap0",
4933 "bitmaps": ["bitmap1"] } }
4934 <- { "return": {} }
4935 BlockDirtyBitmapSha256 (Object)
4937 SHA256 hash of dirty bitmap data
4938 Members
4940 sha256: string
4941 ASCII representation of SHA256 bitmap hash
4942 Since
4944 2.10
4945 x-debug-block-dirty-bitmap-sha256 (Command)
4947 Get bitmap SHA256.
4948 Returns
4950 • BlockDirtyBitmapSha256 on success
4951 • If node is not a valid block device, DeviceNotFound
4953 • If name is not found or if hashing has failed, GenericError with an
4955 explanation
4956 Since
4958 2.10
4959 blockdev-mirror (Command)
4961 Start mirroring a block device's writes to a new destination.
4962 Arguments
4964 job-id: string (optional)
4965 identifier for the newly-created block job. If omitted, the de‐
4966 vice name will be used. (Since 2.7)
4967 device: string
4969 The device name or node-name of a root node whose writes should
4970 be mirrored.
4971 target: string
4973 the id or node-name of the block device to mirror to. This
4974 mustn't be attached to guest.
4975 replaces: string (optional)
4977 with sync=full graph node name to be replaced by the new image
4978 when a whole image copy is done. This can be used to repair bro‐
4979 ken Quorum files. By default, device is replaced, although im‐
4980 plicitly created filters on it are kept.
4981 speed: int (optional)
4983 the maximum speed, in bytes per second
4984 sync: MirrorSyncMode
4986 what parts of the disk image should be copied to the destination
4987 (all the disk, only the sectors allocated in the topmost image,
4988 or only new I/O).
4989 granularity: int (optional)
4991 granularity of the dirty bitmap, default is 64K if the image
4992 format doesn't have clusters, 4K if the clusters are smaller
4993 than that, else the cluster size. Must be a power of 2 between
4994 512 and 64M
4995 buf-size: int (optional)
4997 maximum amount of data in flight from source to target
4998 on-source-error: BlockdevOnError (optional)
5000 the action to take on an error on the source, default 'report'.
5001 'stop' and 'enospc' can only be used if the block device sup‐
5002 ports io-status (see BlockInfo).
5003 on-target-error: BlockdevOnError (optional)
5005 the action to take on an error on the target, default 'report'
5006 (no limitations, since this applies to a different block device
5007 than device).
5008 filter-node-name: string (optional)
5010 the node name that should be assigned to the filter driver that
5011 the mirror job inserts into the graph above device. If this op‐
5012 tion is not given, a node name is autogenerated. (Since: 2.9)
5013 copy-mode: MirrorCopyMode (optional)
5015 when to copy data to the destination; defaults to 'background'
5016 (Since: 3.0)
5017 auto-finalize: boolean (optional)
5019 When false, this job will wait in a PENDING state after it has
5020 finished its work, waiting for block-job-finalize before making
5021 any block graph changes. When true, this job will automatically
5022 perform its abort or commit actions. Defaults to true. (Since
5023 3.1)
5024 auto-dismiss: boolean (optional)
5026 When false, this job will wait in a CONCLUDED state after it has
5027 completely ceased all work, and awaits block-job-dismiss. When
5028 true, this job will automatically disappear from the query list
5029 without user intervention. Defaults to true. (Since 3.1)
5030 Returns
5032 nothing on success.
5033 Since
5035 2.6
5036 Example
5038 -> { "execute": "blockdev-mirror",
5039 "arguments": { "device": "ide-hd0",
5040 "target": "target0",
5041 "sync": "full" } }
5042 <- { "return": {} }
5043 BlockIOThrottle (Object)
5045 A set of parameters describing block throttling.
5046 Members
5048 device: string (optional)
5049 Block device name
5050 id: string (optional)
5052 The name or QOM path of the guest device (since: 2.8)
5053 bps: int
5055 total throughput limit in bytes per second
5056 bps_rd: int
5058 read throughput limit in bytes per second
5059 bps_wr: int
5061 write throughput limit in bytes per second
5062 iops: int
5064 total I/O operations per second
5065 iops_rd: int
5067 read I/O operations per second
5068 iops_wr: int
5070 write I/O operations per second
5071 bps_max: int (optional)
5073 total throughput limit during bursts, in bytes (Since 1.7)
5074 bps_rd_max: int (optional)
5076 read throughput limit during bursts, in bytes (Since 1.7)
5077 bps_wr_max: int (optional)
5079 write throughput limit during bursts, in bytes (Since 1.7)
5080 iops_max: int (optional)
5082 total I/O operations per second during bursts, in bytes (Since
5083 1.7)
5084 iops_rd_max: int (optional)
5086 read I/O operations per second during bursts, in bytes (Since
5087 1.7)
5088 iops_wr_max: int (optional)
5090 write I/O operations per second during bursts, in bytes (Since
5091 1.7)
5092 bps_max_length: int (optional)
5094 maximum length of the bps_max burst period, in seconds. It must
5095 only be set if bps_max is set as well. Defaults to 1. (Since
5096 2.6)
5097 bps_rd_max_length: int (optional)
5099 maximum length of the bps_rd_max burst period, in seconds. It
5100 must only be set if bps_rd_max is set as well. Defaults to 1.
5101 (Since 2.6)
5102 bps_wr_max_length: int (optional)
5104 maximum length of the bps_wr_max burst period, in seconds. It
5105 must only be set if bps_wr_max is set as well. Defaults to 1.
5106 (Since 2.6)
5107 iops_max_length: int (optional)
5109 maximum length of the iops burst period, in seconds. It must
5110 only be set if iops_max is set as well. Defaults to 1. (Since
5111 2.6)
5112 iops_rd_max_length: int (optional)
5114 maximum length of the iops_rd_max burst period, in seconds. It
5115 must only be set if iops_rd_max is set as well. Defaults to 1.
5116 (Since 2.6)
5117 iops_wr_max_length: int (optional)
5119 maximum length of the iops_wr_max burst period, in seconds. It
5120 must only be set if iops_wr_max is set as well. Defaults to 1.
5121 (Since 2.6)
5122 iops_size: int (optional)
5124 an I/O size in bytes (Since 1.7)
5125 group: string (optional)
5127 throttle group name (Since 2.4)
5128 Features
5130 deprecated
5131 Member device is deprecated. Use id instead.
5132 Since
5134 1.1
5135 ThrottleLimits (Object)
5137 Limit parameters for throttling. Since some limit combinations are il‐
5138 legal, limits should always be set in one transaction. All fields are
5139 optional. When setting limits, if a field is missing the current value
5140 is not changed.
5141 Members
5143 iops-total: int (optional)
5144 limit total I/O operations per second
5145 iops-total-max: int (optional)
5147 I/O operations burst
5148 iops-total-max-length: int (optional)
5150 length of the iops-total-max burst period, in seconds It must
5151 only be set if iops-total-max is set as well.
5152 iops-read: int (optional)
5154 limit read operations per second
5155 iops-read-max: int (optional)
5157 I/O operations read burst
5158 iops-read-max-length: int (optional)
5160 length of the iops-read-max burst period, in seconds It must
5161 only be set if iops-read-max is set as well.
5162 iops-write: int (optional)
5164 limit write operations per second
5165 iops-write-max: int (optional)
5167 I/O operations write burst
5168 iops-write-max-length: int (optional)
5170 length of the iops-write-max burst period, in seconds It must
5171 only be set if iops-write-max is set as well.
5172 bps-total: int (optional)
5174 limit total bytes per second
5175 bps-total-max: int (optional)
5177 total bytes burst
5178 bps-total-max-length: int (optional)
5180 length of the bps-total-max burst period, in seconds. It must
5181 only be set if bps-total-max is set as well.
5182 bps-read: int (optional)
5184 limit read bytes per second
5185 bps-read-max: int (optional)
5187 total bytes read burst
5188 bps-read-max-length: int (optional)
5190 length of the bps-read-max burst period, in seconds It must only
5191 be set if bps-read-max is set as well.
5192 bps-write: int (optional)
5194 limit write bytes per second
5195 bps-write-max: int (optional)
5197 total bytes write burst
5198 bps-write-max-length: int (optional)
5200 length of the bps-write-max burst period, in seconds It must
5201 only be set if bps-write-max is set as well.
5202 iops-size: int (optional)
5204 when limiting by iops max size of an I/O in bytes
5205 Since
5207 2.11
5208 ThrottleGroupProperties (Object)
5210 Properties for throttle-group objects.
5211 The options starting with x- are aliases for the same key without x- in
5213 the limits object. As indicated by the x- prefix, this is not a stable
5214 interface and may be removed or changed incompatibly in the future. Use
5215 limits for a supported stable interface.
5216 Members
5218 limits: ThrottleLimits (optional)
5219 limits to apply for this throttle group
5220 x-iops-total: int (optional)
5222 Not documented
5223 x-iops-total-max: int (optional)
5225 Not documented
5226 x-iops-total-max-length: int (optional)
5228 Not documented
5229 x-iops-read: int (optional)
5231 Not documented
5232 x-iops-read-max: int (optional)
5234 Not documented
5235 x-iops-read-max-length: int (optional)
5237 Not documented
5238 x-iops-write: int (optional)
5240 Not documented
5241 x-iops-write-max: int (optional)
5243 Not documented
5244 x-iops-write-max-length: int (optional)
5246 Not documented
5247 x-bps-total: int (optional)
5249 Not documented
5250 x-bps-total-max: int (optional)
5252 Not documented
5253 x-bps-total-max-length: int (optional)
5255 Not documented
5256 x-bps-read: int (optional)
5258 Not documented
5259 x-bps-read-max: int (optional)
5261 Not documented
5262 x-bps-read-max-length: int (optional)
5264 Not documented
5265 x-bps-write: int (optional)
5267 Not documented
5268 x-bps-write-max: int (optional)
5270 Not documented
5271 x-bps-write-max-length: int (optional)
5273 Not documented
5274 x-iops-size: int (optional)
5276 Not documented
5277 Since
5279 2.11
5280 block-stream (Command)
5282 Copy data from a backing file into a block device.
5283 The block streaming operation is performed in the background until the
5285 entire backing file has been copied. This command returns immediately
5286 once streaming has started. The status of ongoing block streaming op‐
5287 erations can be checked with query-block-jobs. The operation can be
5288 stopped before it has completed using the block-job-cancel command.
5289 The node that receives the data is called the top image, can be located
5291 in any part of the chain (but always above the base image; see below)
5292 and can be specified using its device or node name. Earlier qemu ver‐
5293 sions only allowed 'device' to name the top level node; presence of the
5294 'base-node' parameter during introspection can be used as a witness of
5295 the enhanced semantics of 'device'.
5296 If a base file is specified then sectors are not copied from that base
5298 file and its backing chain. This can be used to stream a subset of the
5299 backing file chain instead of flattening the entire image. When
5300 streaming completes the image file will have the base file as its back‐
5301 ing file, unless that node was changed while the job was running. In
5302 that case, base's parent's backing (or filtered, whichever exists)
5303 child (i.e., base at the beginning of the job) will be the new backing
5304 file.
5305 On successful completion the image file is updated to drop the backing
5307 file and the BLOCK_JOB_COMPLETED event is emitted.
5308 In case device is a filter node, block-stream modifies the first
5310 non-filter overlay node below it to point to the new backing node in‐
5311 stead of modifying device itself.
5312 Arguments
5314 job-id: string (optional)
5315 identifier for the newly-created block job. If omitted, the de‐
5316 vice name will be used. (Since 2.7)
5317 device: string
5319 the device or node name of the top image
5320 base: string (optional)
5322 the common backing file name. It cannot be set if base-node or
5323 bottom is also set.
5324 base-node: string (optional)
5326 the node name of the backing file. It cannot be set if base or
5327 bottom is also set. (Since 2.8)
5328 bottom: string (optional)
5330 the last node in the chain that should be streamed into top. It
5331 cannot be set if base or base-node is also set. It cannot be
5332 filter node. (Since 6.0)
5333 backing-file: string (optional)
5335 The backing file string to write into the top image. This file‐
5336 name is not validated.
5337 If a pathname string is such that it cannot be resolved by QEMU,
5339 that means that subsequent QMP or HMP commands must use
5340 node-names for the image in question, as filename lookup methods
5341 will fail.
5342 If not specified, QEMU will automatically determine the backing
5344 file string to use, or error out if there is no obvious choice.
5345 Care should be taken when specifying the string, to specify a
5346 valid filename or protocol. (Since 2.1)
5347 speed: int (optional)
5349 the maximum speed, in bytes per second
5350 on-error: BlockdevOnError (optional)
5352 the action to take on an error (default report). 'stop' and
5353 'enospc' can only be used if the block device supports io-status
5354 (see BlockInfo). Since 1.3.
5355 filter-node-name: string (optional)
5357 the node name that should be assigned to the filter driver that
5358 the stream job inserts into the graph above device. If this op‐
5359 tion is not given, a node name is autogenerated. (Since: 6.0)
5360 auto-finalize: boolean (optional)
5362 When false, this job will wait in a PENDING state after it has
5363 finished its work, waiting for block-job-finalize before making
5364 any block graph changes. When true, this job will automatically
5365 perform its abort or commit actions. Defaults to true. (Since
5366 3.1)
5367 auto-dismiss: boolean (optional)
5369 When false, this job will wait in a CONCLUDED state after it has
5370 completely ceased all work, and awaits block-job-dismiss. When
5371 true, this job will automatically disappear from the query list
5372 without user intervention. Defaults to true. (Since 3.1)
5373 Returns
5375 • Nothing on success.
5376 • If device does not exist, DeviceNotFound.
5378 Since
5380 1.1
5381 Example
5383 -> { "execute": "block-stream",
5384 "arguments": { "device": "virtio0",
5385 "base": "/tmp/master.qcow2" } }
5386 <- { "return": {} }
5387 block-job-set-speed (Command)
5389 Set maximum speed for a background block operation.
5390 This command can only be issued when there is an active block job.
5392 Throttling can be disabled by setting the speed to 0.
5394 Arguments
5396 device: string
5397 The job identifier. This used to be a device name (hence the
5398 name of the parameter), but since QEMU 2.7 it can have other
5399 values.
5400 speed: int
5402 the maximum speed, in bytes per second, or 0 for unlimited. De‐
5403 faults to 0.
5404 Returns
5406 • Nothing on success
5407 • If no background operation is active on this device, DeviceNotActive
5409 Since
5411 1.1
5412 block-job-cancel (Command)
5414 Stop an active background block operation.
5415 This command returns immediately after marking the active background
5417 block operation for cancellation. It is an error to call this command
5418 if no operation is in progress.
5419 The operation will cancel as soon as possible and then emit the
5421 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
5422 ble when enumerated using query-block-jobs.
5423 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
5425 dicated (via the event BLOCK_JOB_READY) that the source and destination
5426 are synchronized, then the event triggered by this command changes to
5427 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
5428 destination now has a point-in-time copy tied to the time of the can‐
5429 cellation.
5430 For streaming, the image file retains its backing file unless the
5432 streaming operation happens to complete just as it is being cancelled.
5433 A new streaming operation can be started at a later time to finish
5434 copying all data from the backing file.
5435 Arguments
5437 device: string
5438 The job identifier. This used to be a device name (hence the
5439 name of the parameter), but since QEMU 2.7 it can have other
5440 values.
5441 force: boolean (optional)
5443 If true, and the job has already emitted the event
5444 BLOCK_JOB_READY, abandon the job immediately (even if it is
5445 paused) instead of waiting for the destination to complete its
5446 final synchronization (since 1.3)
5447 Returns
5449 • Nothing on success
5450 • If no background operation is active on this device, DeviceNotActive
5452 Since
5454 1.1
5455 block-job-pause (Command)
5457 Pause an active background block operation.
5458 This command returns immediately after marking the active background
5460 block operation for pausing. It is an error to call this command if no
5461 operation is in progress or if the job is already paused.
5462 The operation will pause as soon as possible. No event is emitted when
5464 the operation is actually paused. Cancelling a paused job automati‐
5465 cally resumes it.
5466 Arguments
5468 device: string
5469 The job identifier. This used to be a device name (hence the
5470 name of the parameter), but since QEMU 2.7 it can have other
5471 values.
5472 Returns
5474 • Nothing on success
5475 • If no background operation is active on this device, DeviceNotActive
5477 Since
5479 1.3
5480 block-job-resume (Command)
5482 Resume an active background block operation.
5483 This command returns immediately after resuming a paused background
5485 block operation. It is an error to call this command if no operation
5486 is in progress or if the job is not paused.
5487 This command also clears the error status of the job.
5489 Arguments
5491 device: string
5492 The job identifier. This used to be a device name (hence the
5493 name of the parameter), but since QEMU 2.7 it can have other
5494 values.
5495 Returns
5497 • Nothing on success
5498 • If no background operation is active on this device, DeviceNotActive
5500 Since
5502 1.3
5503 block-job-complete (Command)
5505 Manually trigger completion of an active background block operation.
5506 This is supported for drive mirroring, where it also switches the de‐
5507 vice to write to the target path only. The ability to complete is sig‐
5508 naled with a BLOCK_JOB_READY event.
5509 This command completes an active background block operation syn‐
5511 chronously. The ordering of this command's return with the
5512 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
5513 occurs during the processing of this command: 1) the command itself
5514 will fail; 2) the error will be processed according to the rerror/wer‐
5515 ror arguments that were specified when starting the operation.
5516 A cancelled or paused job cannot be completed.
5518 Arguments
5520 device: string
5521 The job identifier. This used to be a device name (hence the
5522 name of the parameter), but since QEMU 2.7 it can have other
5523 values.
5524 Returns
5526 • Nothing on success
5527 • If no background operation is active on this device, DeviceNotActive
5529 Since
5531 1.3
5532 block-job-dismiss (Command)
5534 For jobs that have already concluded, remove them from the
5535 block-job-query list. This command only needs to be run for jobs which
5536 were started with QEMU 2.12+ job lifetime management semantics.
5537 This command will refuse to operate on any job that has not yet reached
5539 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
5540 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
5541 still need to be used as appropriate.
5542 Arguments
5544 id: string
5545 The job identifier.
5546 Returns
5548 Nothing on success
5549 Since
5551 2.12
5552 block-job-finalize (Command)
5554 Once a job that has manual=true reaches the pending state, it can be
5555 instructed to finalize any graph changes and do any necessary cleanup
5556 via this command. For jobs in a transaction, instructing one job to
5557 finalize will force ALL jobs in the transaction to finalize, so it is
5558 only necessary to instruct a single member job to finalize.
5559 Arguments
5561 id: string
5562 The job identifier.
5563 Returns
5565 Nothing on success
5566 Since
5568 2.12
5569 BlockdevDiscardOptions (Enum)
5571 Determines how to handle discard requests.
5572 Values
5574 ignore Ignore the request
5575 unmap Forward as an unmap request
5577 Since
5579 2.9
5580 BlockdevDetectZeroesOptions (Enum)
5582 Describes the operation mode for the automatic conversion of plain zero
5583 writes by the OS to driver specific optimized zero write commands.
5584 Values
5586 off Disabled (default)
5587 on Enabled
5589 unmap Enabled and even try to unmap blocks if possible. This requires
5591 also that BlockdevDiscardOptions is set to unmap for this de‐
5592 vice.
5593 Since
5595 2.1
5596 BlockdevAioOptions (Enum)
5598 Selects the AIO backend to handle I/O requests
5599 Values
5601 threads
5602 Use qemu's thread pool
5603 native Use native AIO backend (only Linux and Windows)
5605 io_uring (If: defined(CONFIG_LINUX_IO_URING))
5607 Use linux io_uring (since 5.0)
5608 Since
5610 2.9
5611 BlockdevCacheOptions (Object)
5613 Includes cache-related options for block devices
5614 Members
5616 direct: boolean (optional)
5617 enables use of O_DIRECT (bypass the host page cache; default:
5618 false)
5619 no-flush: boolean (optional)
5621 ignore any flush requests for the device (default: false)
5622 Since
5624 2.9
5625 BlockdevDriver (Enum)
5627 Drivers that are supported in block device operations.
5628 Values
5630 throttle
5631 Since 2.11
5632 nvme Since 2.12
5634 copy-on-read
5636 Since 3.0
5637 blklogwrites
5639 Since 3.0
5640 blkreplay
5642 Since 4.2
5643 compress
5645 Since 5.0
5646 blkdebug
5648 Not documented
5649 blkverify
5651 Not documented
5652 bochs Not documented
5654 cloop Not documented
5656 dmg Not documented
5658 file Not documented
5660 ftp Not documented
5662 ftps Not documented
5664 gluster
5666 Not documented
5667 host_cdrom (If: defined(HAVE_HOST_BLOCK_DEVICE))
5669 Not documented
5670 host_device (If: defined(HAVE_HOST_BLOCK_DEVICE))
5672 Not documented
5673 http Not documented
5675 https Not documented
5677 iscsi Not documented
5679 luks Not documented
5681 nbd Not documented
5683 nfs Not documented
5685 null-aio
5687 Not documented
5688 null-co
5690 Not documented
5691 parallels
5693 Not documented
5694 preallocate
5696 Not documented
5697 qcow Not documented
5699 qcow2 Not documented
5701 qed Not documented
5703 quorum Not documented
5705 raw Not documented
5707 rbd Not documented
5709 replication (If: defined(CONFIG_REPLICATION))
5711 Not documented
5712 ssh Not documented
5714 vdi Not documented
5716 vhdx Not documented
5718 vmdk Not documented
5720 vpc Not documented
5722 vvfat Not documented
5724 Since
5726 2.9
5727 BlockdevOptionsFile (Object)
5729 Driver specific block device options for the file backend.
5730 Members
5732 filename: string
5733 path to the image file
5734 pr-manager: string (optional)
5736 the id for the object that will handle persistent reservations
5737 for this device (default: none, forward the commands via SG_IO;
5738 since 2.11)
5739 aio: BlockdevAioOptions (optional)
5741 AIO backend (default: threads) (since: 2.8)
5742 locking: OnOffAuto (optional)
5744 whether to enable file locking. If set to 'auto', only enable
5745 when Open File Descriptor (OFD) locking API is available (de‐
5746 fault: auto, since 2.10)
5747 drop-cache: boolean (optional) (If: defined(CONFIG_LINUX))
5749 invalidate page cache during live migration. This prevents
5750 stale data on the migration destination with cache.direct=off.
5751 Currently only supported on Linux hosts. (default: on, since:
5752 4.0)
5753 x-check-cache-dropped: boolean (optional)
5755 whether to check that page cache was dropped on live migration.
5756 May cause noticeable delays if the image file is large, do not
5757 use in production. (default: off) (since: 3.0)
5758 Features
5760 dynamic-auto-read-only
5761 If present, enabled auto-read-only means that the driver will
5762 open the image read-only at first, dynamically reopen the image
5763 file read-write when the first writer is attached to the node
5764 and reopen read-only when the last writer is detached. This al‐
5765 lows giving QEMU write permissions only on demand when an opera‐
5766 tion actually needs write access.
5767 Since
5769 2.9
5770 BlockdevOptionsNull (Object)
5772 Driver specific block device options for the null backend.
5773 Members
5775 size: int (optional)
5776 size of the device in bytes.
5777 latency-ns: int (optional)
5779 emulated latency (in nanoseconds) in processing requests. De‐
5780 fault to zero which completes requests immediately. (Since 2.4)
5781 read-zeroes: boolean (optional)
5783 if true, reads from the device produce zeroes; if false, the
5784 buffer is left unchanged. (default: false; since: 4.1)
5785 Since
5787 2.9
5788 BlockdevOptionsNVMe (Object)
5790 Driver specific block device options for the NVMe backend.
5791 Members
5793 device: string
5794 PCI controller address of the NVMe device in format hhhh:bb:ss.f
5795 (host:bus:slot.function)
5796 namespace: int
5798 namespace number of the device, starting from 1.
5799 Note that the PCI device must have been unbound from any host kernel
5800 driver before instructing QEMU to add the blockdev.
5801 Since
5803 2.12
5804 BlockdevOptionsVVFAT (Object)
5806 Driver specific block device options for the vvfat protocol.
5807 Members
5809 dir: string
5810 directory to be exported as FAT image
5811 fat-type: int (optional)
5813 FAT type: 12, 16 or 32
5814 floppy: boolean (optional)
5816 whether to export a floppy image (true) or partitioned hard disk
5817 (false; default)
5818 label: string (optional)
5820 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
5821 ditionally have some restrictions on labels, which are ignored
5822 by most operating systems. Defaults to "QEMU VVFAT". (since
5823 2.4)
5824 rw: boolean (optional)
5826 whether to allow write operations (default: false)
5827 Since
5829 2.9
5830 BlockdevOptionsGenericFormat (Object)
5832 Driver specific block device options for image format that have no op‐
5833 tion besides their data source.
5834 Members
5836 file: BlockdevRef
5837 reference to or definition of the data source block device
5838 Since
5840 2.9
5841 BlockdevOptionsLUKS (Object)
5843 Driver specific block device options for LUKS.
5844 Members
5846 key-secret: string (optional)
5847 the ID of a QCryptoSecret object providing the decryption key
5848 (since 2.6). Mandatory except when doing a metadata-only probe
5849 of the image.
5850 The members of BlockdevOptionsGenericFormat
5852 Since
5854 2.9
5855 BlockdevOptionsGenericCOWFormat (Object)
5857 Driver specific block device options for image format that have no op‐
5858 tion besides their data source and an optional backing file.
5859 Members
5861 backing: BlockdevRefOrNull (optional)
5862 reference to or definition of the backing file block device,
5863 null disables the backing file entirely. Defaults to the back‐
5864 ing file stored the image file.
5865 The members of BlockdevOptionsGenericFormat
5867 Since
5869 2.9
5870 Qcow2OverlapCheckMode (Enum)
5872 General overlap check modes.
5873 Values
5875 none Do not perform any checks
5876 constant
5878 Perform only checks which can be done in constant time and with‐
5879 out reading anything from disk
5880 cached Perform only checks which can be done without reading anything
5882 from disk
5883 all Perform all available overlap checks
5885 Since
5887 2.9
5888 Qcow2OverlapCheckFlags (Object)
5890 Structure of flags for each metadata structure. Setting a field to
5891 'true' makes qemu guard that structure against unintended overwriting.
5892 The default value is chosen according to the template given.
5893 Members
5895 template: Qcow2OverlapCheckMode (optional)
5896 Specifies a template mode which can be adjusted using the other
5897 flags, defaults to 'cached'
5898 bitmap-directory: boolean (optional)
5900 since 3.0
5901 main-header: boolean (optional)
5903 Not documented
5904 active-l1: boolean (optional)
5906 Not documented
5907 active-l2: boolean (optional)
5909 Not documented
5910 refcount-table: boolean (optional)
5912 Not documented
5913 refcount-block: boolean (optional)
5915 Not documented
5916 snapshot-table: boolean (optional)
5918 Not documented
5919 inactive-l1: boolean (optional)
5921 Not documented
5922 inactive-l2: boolean (optional)
5924 Not documented
5925 Since
5927 2.9
5928 Qcow2OverlapChecks (Alternate)
5930 Specifies which metadata structures should be guarded against unin‐
5931 tended overwriting.
5932 Members
5934 flags: Qcow2OverlapCheckFlags
5935 set of flags for separate specification of each metadata struc‐
5936 ture type
5937 mode: Qcow2OverlapCheckMode
5939 named mode which chooses a specific set of flags
5940 Since
5942 2.9
5943 BlockdevQcowEncryptionFormat (Enum)
5945 Values
5946 aes AES-CBC with plain64 initialization vectors
5947 Since
5949 2.10
5950 BlockdevQcowEncryption (Object)
5952 Members
5953 format: BlockdevQcowEncryptionFormat
5954 Not documented
5955 The members of QCryptoBlockOptionsQCow when format is "aes"
5957 Since
5959 2.10
5960 BlockdevOptionsQcow (Object)
5962 Driver specific block device options for qcow.
5963 Members
5965 encrypt: BlockdevQcowEncryption (optional)
5966 Image decryption options. Mandatory for encrypted images, except
5967 when doing a metadata-only probe of the image.
5968 The members of BlockdevOptionsGenericCOWFormat
5970 Since
5972 2.10
5973 BlockdevQcow2EncryptionFormat (Enum)
5975 Values
5976 aes AES-CBC with plain64 initialization vectors
5977 luks Not documented
5979 Since
5981 2.10
5982 BlockdevQcow2Encryption (Object)
5984 Members
5985 format: BlockdevQcow2EncryptionFormat
5986 Not documented
5987 The members of QCryptoBlockOptionsQCow when format is "aes"
5989 The members of QCryptoBlockOptionsLUKS when format is "luks"
5991 Since
5993 2.10
5994 BlockdevOptionsPreallocate (Object)
5996 Filter driver intended to be inserted between format and protocol node
5997 and do preallocation in protocol node on write.
5998 Members
6000 prealloc-align: int (optional)
6001 on preallocation, align file length to this number, default
6002 1048576 (1M)
6003 prealloc-size: int (optional)
6005 how much to preallocate, default 134217728 (128M)
6006 The members of BlockdevOptionsGenericFormat
6008 Since
6010 6.0
6011 BlockdevOptionsQcow2 (Object)
6013 Driver specific block device options for qcow2.
6014 Members
6016 lazy-refcounts: boolean (optional)
6017 whether to enable the lazy refcounts feature (default is taken
6018 from the image file)
6019 pass-discard-request: boolean (optional)
6021 whether discard requests to the qcow2 device should be forwarded
6022 to the data source
6023 pass-discard-snapshot: boolean (optional)
6025 whether discard requests for the data source should be issued
6026 when a snapshot operation (e.g. deleting a snapshot) frees
6027 clusters in the qcow2 file
6028 pass-discard-other: boolean (optional)
6030 whether discard requests for the data source should be issued on
6031 other occasions where a cluster gets freed
6032 overlap-check: Qcow2OverlapChecks (optional)
6034 which overlap checks to perform for writes to the image, de‐
6035 faults to 'cached' (since 2.2)
6036 cache-size: int (optional)
6038 the maximum total size of the L2 table and refcount block caches
6039 in bytes (since 2.2)
6040 l2-cache-size: int (optional)
6042 the maximum size of the L2 table cache in bytes (since 2.2)
6043 l2-cache-entry-size: int (optional)
6045 the size of each entry in the L2 cache in bytes. It must be a
6046 power of two between 512 and the cluster size. The default value
6047 is the cluster size (since 2.12)
6048 refcount-cache-size: int (optional)
6050 the maximum size of the refcount block cache in bytes (since
6051 2.2)
6052 cache-clean-interval: int (optional)
6054 clean unused entries in the L2 and refcount caches. The interval
6055 is in seconds. The default value is 600 on supporting platforms,
6056 and 0 on other platforms. 0 disables this feature. (since 2.5)
6057 encrypt: BlockdevQcow2Encryption (optional)
6059 Image decryption options. Mandatory for encrypted images, except
6060 when doing a metadata-only probe of the image. (since 2.10)
6061 data-file: BlockdevRef (optional)
6063 reference to or definition of the external data file. This may
6064 only be specified for images that require an external data file.
6065 If it is not specified for such an image, the data file name is
6066 loaded from the image file. (since 4.0)
6067 The members of BlockdevOptionsGenericCOWFormat
6069 Since
6071 2.9
6072 SshHostKeyCheckMode (Enum)
6074 Values
6075 none Don't check the host key at all
6076 hash Compare the host key with a given hash
6078 known_hosts
6080 Check the host key against the known_hosts file
6081 Since
6083 2.12
6084 SshHostKeyCheckHashType (Enum)
6086 Values
6087 md5 The given hash is an md5 hash
6088 sha1 The given hash is an sha1 hash
6090 sha256 The given hash is an sha256 hash
6092 Since
6094 2.12
6095 SshHostKeyHash (Object)
6097 Members
6098 type: SshHostKeyCheckHashType
6099 The hash algorithm used for the hash
6100 hash: string
6102 The expected hash value
6103 Since
6105 2.12
6106 SshHostKeyCheck (Object)
6108 Members
6109 mode: SshHostKeyCheckMode
6110 Not documented
6111 The members of SshHostKeyHash when mode is "hash"
6113 Since
6115 2.12
6116 BlockdevOptionsSsh (Object)
6118 Members
6119 server: InetSocketAddress
6120 host address
6121 path: string
6123 path to the image on the host
6124 user: string (optional)
6126 user as which to connect, defaults to current local user name
6127 host-key-check: SshHostKeyCheck (optional)
6129 Defines how and what to check the host key against (default:
6130 known_hosts)
6131 Since
6133 2.9
6134 BlkdebugEvent (Enum)
6136 Trigger events supported by blkdebug.
6137 Values
6139 l1_shrink_write_table
6140 write zeros to the l1 table to shrink image. (since 2.11)
6141 l1_shrink_free_l2_clusters
6143 discard the l2 tables. (since 2.11)
6144 cor_write
6146 a write due to copy-on-read (since 2.11)
6147 cluster_alloc_space
6149 an allocation of file space for a cluster (since 4.1)
6150 none triggers once at creation of the blkdebug node (since 4.1)
6152 l1_update
6154 Not documented
6155 l1_grow_alloc_table
6157 Not documented
6158 l1_grow_write_table
6160 Not documented
6161 l1_grow_activate_table
6163 Not documented
6164 l2_load
6166 Not documented
6167 l2_update
6169 Not documented
6170 l2_update_compressed
6172 Not documented
6173 l2_alloc_cow_read
6175 Not documented
6176 l2_alloc_write
6178 Not documented
6179 read_aio
6181 Not documented
6182 read_backing_aio
6184 Not documented
6185 read_compressed
6187 Not documented
6188 write_aio
6190 Not documented
6191 write_compressed
6193 Not documented
6194 vmstate_load
6196 Not documented
6197 vmstate_save
6199 Not documented
6200 cow_read
6202 Not documented
6203 cow_write
6205 Not documented
6206 reftable_load
6208 Not documented
6209 reftable_grow
6211 Not documented
6212 reftable_update
6214 Not documented
6215 refblock_load
6217 Not documented
6218 refblock_update
6220 Not documented
6221 refblock_update_part
6223 Not documented
6224 refblock_alloc
6226 Not documented
6227 refblock_alloc_hookup
6229 Not documented
6230 refblock_alloc_write
6232 Not documented
6233 refblock_alloc_write_blocks
6235 Not documented
6236 refblock_alloc_write_table
6238 Not documented
6239 refblock_alloc_switch_table
6241 Not documented
6242 cluster_alloc
6244 Not documented
6245 cluster_alloc_bytes
6247 Not documented
6248 cluster_free
6250 Not documented
6251 flush_to_os
6253 Not documented
6254 flush_to_disk
6256 Not documented
6257 pwritev_rmw_head
6259 Not documented
6260 pwritev_rmw_after_head
6262 Not documented
6263 pwritev_rmw_tail
6265 Not documented
6266 pwritev_rmw_after_tail
6268 Not documented
6269 pwritev
6271 Not documented
6272 pwritev_zero
6274 Not documented
6275 pwritev_done
6277 Not documented
6278 empty_image_prepare
6280 Not documented
6281 Since
6283 2.9
6284 BlkdebugIOType (Enum)
6286 Kinds of I/O that blkdebug can inject errors in.
6287 Values
6289 read .bdrv_co_preadv()
6290 write .bdrv_co_pwritev()
6292 write-zeroes
6294 .bdrv_co_pwrite_zeroes()
6295 discard
6297 .bdrv_co_pdiscard()
6298 flush .bdrv_co_flush_to_disk()
6300 block-status
6302 .bdrv_co_block_status()
6303 Since
6305 4.1
6306 BlkdebugInjectErrorOptions (Object)
6308 Describes a single error injection for blkdebug.
6309 Members
6311 event: BlkdebugEvent
6312 trigger event
6313 state: int (optional)
6315 the state identifier blkdebug needs to be in to actually trigger
6316 the event; defaults to "any"
6317 iotype: BlkdebugIOType (optional)
6319 the type of I/O operations on which this error should be in‐
6320 jected; defaults to "all read, write, write-zeroes, discard, and
6321 flush operations" (since: 4.1)
6322 errno: int (optional)
6324 error identifier (errno) to be returned; defaults to EIO
6325 sector: int (optional)
6327 specifies the sector index which has to be affected in order to
6328 actually trigger the event; defaults to "any sector"
6329 once: boolean (optional)
6331 disables further events after this one has been triggered; de‐
6332 faults to false
6333 immediately: boolean (optional)
6335 fail immediately; defaults to false
6336 Since
6338 2.9
6339 BlkdebugSetStateOptions (Object)
6341 Describes a single state-change event for blkdebug.
6342 Members
6344 event: BlkdebugEvent
6345 trigger event
6346 state: int (optional)
6348 the current state identifier blkdebug needs to be in; defaults
6349 to "any"
6350 new_state: int
6352 the state identifier blkdebug is supposed to assume if this
6353 event is triggered
6354 Since
6356 2.9
6357 BlockdevOptionsBlkdebug (Object)
6359 Driver specific block device options for blkdebug.
6360 Members
6362 image: BlockdevRef
6363 underlying raw block device (or image file)
6364 config: string (optional)
6366 filename of the configuration file
6367 align: int (optional)
6369 required alignment for requests in bytes, must be positive power
6370 of 2, or 0 for default
6371 max-transfer: int (optional)
6373 maximum size for I/O transfers in bytes, must be positive multi‐
6374 ple of align and of the underlying file's request alignment (but
6375 need not be a power of 2), or 0 for default (since 2.10)
6376 opt-write-zero: int (optional)
6378 preferred alignment for write zero requests in bytes, must be
6379 positive multiple of align and of the underlying file's request
6380 alignment (but need not be a power of 2), or 0 for default
6381 (since 2.10)
6382 max-write-zero: int (optional)
6384 maximum size for write zero requests in bytes, must be positive
6385 multiple of align, of opt-write-zero, and of the underlying
6386 file's request alignment (but need not be a power of 2), or 0
6387 for default (since 2.10)
6388 opt-discard: int (optional)
6390 preferred alignment for discard requests in bytes, must be posi‐
6391 tive multiple of align and of the underlying file's request
6392 alignment (but need not be a power of 2), or 0 for default
6393 (since 2.10)
6394 max-discard: int (optional)
6396 maximum size for discard requests in bytes, must be positive
6397 multiple of align, of opt-discard, and of the underlying file's
6398 request alignment (but need not be a power of 2), or 0 for de‐
6399 fault (since 2.10)
6400 inject-error: array of BlkdebugInjectErrorOptions (optional)
6402 array of error injection descriptions
6403 set-state: array of BlkdebugSetStateOptions (optional)
6405 array of state-change descriptions
6406 take-child-perms: array of BlockPermission (optional)
6408 Permissions to take on image in addition to what is necessary
6409 anyway (which depends on how the blkdebug node is used). De‐
6410 faults to none. (since 5.0)
6411 unshare-child-perms: array of BlockPermission (optional)
6413 Permissions not to share on image in addition to what cannot be
6414 shared anyway (which depends on how the blkdebug node is used).
6415 Defaults to none. (since 5.0)
6416 Since
6418 2.9
6419 BlockdevOptionsBlklogwrites (Object)
6421 Driver specific block device options for blklogwrites.
6422 Members
6424 file: BlockdevRef
6425 block device
6426 log: BlockdevRef
6428 block device used to log writes to file
6429 log-sector-size: int (optional)
6431 sector size used in logging writes to file, determines granular‐
6432 ity of offsets and sizes of writes (default: 512)
6433 log-append: boolean (optional)
6435 append to an existing log (default: false)
6436 log-super-update-interval: int (optional)
6438 interval of write requests after which the log super block is
6439 updated to disk (default: 4096)
6440 Since
6442 3.0
6443 BlockdevOptionsBlkverify (Object)
6445 Driver specific block device options for blkverify.
6446 Members
6448 test: BlockdevRef
6449 block device to be tested
6450 raw: BlockdevRef
6452 raw image used for verification
6453 Since
6455 2.9
6456 BlockdevOptionsBlkreplay (Object)
6458 Driver specific block device options for blkreplay.
6459 Members
6461 image: BlockdevRef
6462 disk image which should be controlled with blkreplay
6463 Since
6465 4.2
6466 QuorumReadPattern (Enum)
6468 An enumeration of quorum read patterns.
6469 Values
6471 quorum read all the children and do a quorum vote on reads
6472 fifo read only from the first child that has not failed
6474 Since
6476 2.9
6477 BlockdevOptionsQuorum (Object)
6479 Driver specific block device options for Quorum
6480 Members
6482 blkverify: boolean (optional)
6483 true if the driver must print content mismatch
6485 set to false by default
6486 children: array of BlockdevRef
6488 the children block devices to use
6489 vote-threshold: int
6491 the vote limit under which a read will fail
6492 rewrite-corrupted: boolean (optional)
6494 rewrite corrupted data when quorum is reached (Since 2.1)
6495 read-pattern: QuorumReadPattern (optional)
6497 choose read pattern and set to quorum by default (Since 2.2)
6498 Since
6500 2.9
6501 BlockdevOptionsGluster (Object)
6503 Driver specific block device options for Gluster
6504 Members
6506 volume: string
6507 name of gluster volume where VM image resides
6508 path: string
6510 absolute path to image file in gluster volume
6511 server: array of SocketAddress
6513 gluster servers description
6514 debug: int (optional)
6516 libgfapi log level (default '4' which is Error) (Since 2.8)
6517 logfile: string (optional)
6519 libgfapi log file (default /dev/stderr) (Since 2.8)
6520 Since
6522 2.9
6523 IscsiTransport (Enum)
6525 An enumeration of libiscsi transport types
6526 Values
6528 tcp Not documented
6529 iser Not documented
6531 Since
6533 2.9
6534 IscsiHeaderDigest (Enum)
6536 An enumeration of header digests supported by libiscsi
6537 Values
6539 crc32c Not documented
6540 none Not documented
6542 crc32c-none
6544 Not documented
6545 none-crc32c
6547 Not documented
6548 Since
6550 2.9
6551 BlockdevOptionsIscsi (Object)
6553 Members
6554 transport: IscsiTransport
6555 The iscsi transport type
6556 portal: string
6558 The address of the iscsi portal
6559 target: string
6561 The target iqn name
6562 lun: int (optional)
6564 LUN to connect to. Defaults to 0.
6565 user: string (optional)
6567 User name to log in with. If omitted, no CHAP authentication is
6568 performed.
6569 password-secret: string (optional)
6571 The ID of a QCryptoSecret object providing the password for the
6572 login. This option is required if user is specified.
6573 initiator-name: string (optional)
6575 The iqn name we want to identify to the target as. If this op‐
6576 tion is not specified, an initiator name is generated automati‐
6577 cally.
6578 header-digest: IscsiHeaderDigest (optional)
6580 The desired header digest. Defaults to none-crc32c.
6581 timeout: int (optional)
6583 Timeout in seconds after which a request will timeout. 0 means
6584 no timeout and is the default.
6585 Driver specific block device options for iscsi
6586 Since
6588 2.9
6589 RbdAuthMode (Enum)
6591 Values
6592 cephx Not documented
6593 none Not documented
6595 Since
6597 3.0
6598 RbdImageEncryptionFormat (Enum)
6600 Values
6601 luks Not documented
6602 luks2 Not documented
6604 Since
6606 6.1
6607 RbdEncryptionOptionsLUKSBase (Object)
6609 Members
6610 key-secret: string
6611 ID of a QCryptoSecret object providing a passphrase for unlock‐
6612 ing the encryption
6613 Since
6615 6.1
6616 RbdEncryptionCreateOptionsLUKSBase (Object)
6618 Members
6619 cipher-alg: QCryptoCipherAlgorithm (optional)
6620 The encryption algorithm
6621 The members of RbdEncryptionOptionsLUKSBase
6623 Since
6625 6.1
6626 RbdEncryptionOptionsLUKS (Object)
6628 Members
6629 The members of RbdEncryptionOptionsLUKSBase
6630 Since
6632 6.1
6633 RbdEncryptionOptionsLUKS2 (Object)
6635 Members
6636 The members of RbdEncryptionOptionsLUKSBase
6637 Since
6639 6.1
6640 RbdEncryptionCreateOptionsLUKS (Object)
6642 Members
6643 The members of RbdEncryptionCreateOptionsLUKSBase
6644 Since
6646 6.1
6647 RbdEncryptionCreateOptionsLUKS2 (Object)
6649 Members
6650 The members of RbdEncryptionCreateOptionsLUKSBase
6651 Since
6653 6.1
6654 RbdEncryptionOptions (Object)
6656 Members
6657 format: RbdImageEncryptionFormat
6658 Not documented
6659 The members of RbdEncryptionOptionsLUKS when format is "luks"
6661 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
6663 Since
6665 6.1
6666 RbdEncryptionCreateOptions (Object)
6668 Members
6669 format: RbdImageEncryptionFormat
6670 Not documented
6671 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
6673 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
6675 Since
6677 6.1
6678 BlockdevOptionsRbd (Object)
6680 Members
6681 pool: string
6682 Ceph pool name.
6683 namespace: string (optional)
6685 Rados namespace name in the Ceph pool. (Since 5.0)
6686 image: string
6688 Image name in the Ceph pool.
6689 conf: string (optional)
6691 path to Ceph configuration file. Values in the configuration
6692 file will be overridden by options specified via QAPI.
6693 snapshot: string (optional)
6695 Ceph snapshot name.
6696 encrypt: RbdEncryptionOptions (optional)
6698 Image encryption options. (Since 6.1)
6699 user: string (optional)
6701 Ceph id name.
6702 auth-client-required: array of RbdAuthMode (optional)
6704 Acceptable authentication modes. This maps to Ceph configura‐
6705 tion option "auth_client_required". (Since 3.0)
6706 key-secret: string (optional)
6708 ID of a QCryptoSecret object providing a key for cephx authenti‐
6709 cation. This maps to Ceph configuration option "key". (Since
6710 3.0)
6711 server: array of InetSocketAddressBase (optional)
6713 Monitor host address and port. This maps to the "mon_host" Ceph
6714 option.
6715 Since
6717 2.9
6718 ReplicationMode (Enum)
6720 An enumeration of replication modes.
6721 Values
6723 primary
6724 Primary mode, the vm's state will be sent to secondary QEMU.
6725 secondary
6727 Secondary mode, receive the vm's state from primary QEMU.
6728 Since
6730 2.9
6731 If
6733 defined(CONFIG_REPLICATION)
6734 BlockdevOptionsReplication (Object)
6736 Driver specific block device options for replication
6737 Members
6739 mode: ReplicationMode
6740 the replication mode
6741 top-id: string (optional)
6743 In secondary mode, node name or device ID of the root node who
6744 owns the replication node chain. Must not be given in primary
6745 mode.
6746 The members of BlockdevOptionsGenericFormat
6748 Since
6750 2.9
6751 If
6753 defined(CONFIG_REPLICATION)
6754 NFSTransport (Enum)
6756 An enumeration of NFS transport types
6757 Values
6759 inet TCP transport
6760 Since
6762 2.9
6763 NFSServer (Object)
6765 Captures the address of the socket
6766 Members
6768 type: NFSTransport
6769 transport type used for NFS (only TCP supported)
6770 host: string
6772 host address for NFS server
6773 Since
6775 2.9
6776 BlockdevOptionsNfs (Object)
6778 Driver specific block device option for NFS
6779 Members
6781 server: NFSServer
6782 host address
6783 path: string
6785 path of the image on the host
6786 user: int (optional)
6788 UID value to use when talking to the server (defaults to 65534
6789 on Windows and getuid() on unix)
6790 group: int (optional)
6792 GID value to use when talking to the server (defaults to 65534
6793 on Windows and getgid() in unix)
6794 tcp-syn-count: int (optional)
6796 number of SYNs during the session establishment (defaults to
6797 libnfs default)
6798 readahead-size: int (optional)
6800 set the readahead size in bytes (defaults to libnfs default)
6801 page-cache-size: int (optional)
6803 set the pagecache size in bytes (defaults to libnfs default)
6804 debug: int (optional)
6806 set the NFS debug level (max 2) (defaults to libnfs default)
6807 Since
6809 2.9
6810 BlockdevOptionsCurlBase (Object)
6812 Driver specific block device options shared by all protocols supported
6813 by the curl backend.
6814 Members
6816 url: string
6817 URL of the image file
6818 readahead: int (optional)
6820 Size of the read-ahead cache; must be a multiple of 512 (de‐
6821 faults to 256 kB)
6822 timeout: int (optional)
6824 Timeout for connections, in seconds (defaults to 5)
6825 username: string (optional)
6827 Username for authentication (defaults to none)
6828 password-secret: string (optional)
6830 ID of a QCryptoSecret object providing a password for authenti‐
6831 cation (defaults to no password)
6832 proxy-username: string (optional)
6834 Username for proxy authentication (defaults to none)
6835 proxy-password-secret: string (optional)
6837 ID of a QCryptoSecret object providing a password for proxy au‐
6838 thentication (defaults to no password)
6839 Since
6841 2.9
6842 BlockdevOptionsCurlHttp (Object)
6844 Driver specific block device options for HTTP connections over the curl
6845 backend. URLs must start with "http://".
6846 Members
6848 cookie: string (optional)
6849 List of cookies to set; format is "name1=content1; name2=con‐
6850 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6851 ies.
6852 cookie-secret: string (optional)
6854 ID of a QCryptoSecret object providing the cookie data in a se‐
6855 cure way. See cookie for the format. (since 2.10)
6856 The members of BlockdevOptionsCurlBase
6858 Since
6860 2.9
6861 BlockdevOptionsCurlHttps (Object)
6863 Driver specific block device options for HTTPS connections over the
6864 curl backend. URLs must start with "https://".
6865 Members
6867 cookie: string (optional)
6868 List of cookies to set; format is "name1=content1; name2=con‐
6869 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6870 ies.
6871 sslverify: boolean (optional)
6873 Whether to verify the SSL certificate's validity (defaults to
6874 true)
6875 cookie-secret: string (optional)
6877 ID of a QCryptoSecret object providing the cookie data in a se‐
6878 cure way. See cookie for the format. (since 2.10)
6879 The members of BlockdevOptionsCurlBase
6881 Since
6883 2.9
6884 BlockdevOptionsCurlFtp (Object)
6886 Driver specific block device options for FTP connections over the curl
6887 backend. URLs must start with "ftp://".
6888 Members
6890 The members of BlockdevOptionsCurlBase
6891 Since
6893 2.9
6894 BlockdevOptionsCurlFtps (Object)
6896 Driver specific block device options for FTPS connections over the curl
6897 backend. URLs must start with "ftps://".
6898 Members
6900 sslverify: boolean (optional)
6901 Whether to verify the SSL certificate's validity (defaults to
6902 true)
6903 The members of BlockdevOptionsCurlBase
6905 Since
6907 2.9
6908 BlockdevOptionsNbd (Object)
6910 Driver specific block device options for NBD.
6911 Members
6913 server: SocketAddress
6914 NBD server address
6915 export: string (optional)
6917 export name
6918 tls-creds: string (optional)
6920 TLS credentials ID
6921 x-dirty-bitmap: string (optional)
6923 A metadata context name such as "qemu:dirty-bitmap:NAME" or
6924 "qemu:allocation-depth" to query in place of the traditional
6925 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
6926 the NBD protocol; and yes, naming this option x-context would
6927 have made more sense) (since 3.0)
6928 reconnect-delay: int (optional)
6930 On an unexpected disconnect, the nbd client tries to connect
6931 again until succeeding or encountering a serious error. During
6932 the first reconnect-delay seconds, all requests are paused and
6933 will be rerun on a successful reconnect. After that time, any
6934 delayed requests and all future requests before a successful re‐
6935 connect will immediately fail. Default 0 (Since 4.2)
6936 Since
6938 2.9
6939 BlockdevOptionsRaw (Object)
6941 Driver specific block device options for the raw driver.
6942 Members
6944 offset: int (optional)
6945 position where the block device starts
6946 size: int (optional)
6948 the assumed size of the device
6949 The members of BlockdevOptionsGenericFormat
6951 Since
6953 2.9
6954 BlockdevOptionsThrottle (Object)
6956 Driver specific block device options for the throttle driver
6957 Members
6959 throttle-group: string
6960 the name of the throttle-group object to use. It must already
6961 exist.
6962 file: BlockdevRef
6964 reference to or definition of the data source block device
6965 Since
6967 2.11
6968 BlockdevOptionsCor (Object)
6970 Driver specific block device options for the copy-on-read driver.
6971 Members
6973 bottom: string (optional)
6974 The name of a non-filter node (allocation-bearing layer) that
6975 limits the COR operations in the backing chain (inclusive), so
6976 that no data below this node will be copied by this filter. If
6977 option is absent, the limit is not applied, so that data from
6978 all backing layers may be copied.
6979 The members of BlockdevOptionsGenericFormat
6981 Since
6983 6.0
6984 BlockdevOptions (Object)
6986 Options for creating a block device. Many options are available for
6987 all block devices, independent of the block driver:
6988 Members
6990 driver: BlockdevDriver
6991 block driver name
6992 node-name: string (optional)
6994 the node name of the new node (Since 2.0). This option is re‐
6995 quired on the top level of blockdev-add. Valid node names start
6996 with an alphabetic character and may contain only alphanumeric
6997 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
6998 ters.
6999 discard: BlockdevDiscardOptions (optional)
7001 discard-related options (default: ignore)
7002 cache: BlockdevCacheOptions (optional)
7004 cache-related options
7005 read-only: boolean (optional)
7007 whether the block device should be read-only (default: false).
7008 Note that some block drivers support only read-only access, ei‐
7009 ther generally or in certain configurations. In this case, the
7010 default value does not work and the option must be specified ex‐
7011 plicitly.
7012 auto-read-only: boolean (optional)
7014 if true and read-only is false, QEMU may automatically decide
7015 not to open the image read-write as requested, but fall back to
7016 read-only instead (and switch between the modes later), e.g. de‐
7017 pending on whether the image file is writable or whether a writ‐
7018 ing user is attached to the node (default: false, since 3.1)
7019 detect-zeroes: BlockdevDetectZeroesOptions (optional)
7021 detect and optimize zero writes (Since 2.1) (default: off)
7022 force-share: boolean (optional)
7024 force share all permission on added nodes. Requires
7025 read-only=true. (Since 2.10)
7026 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
7028 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
7030 writes"
7031 The members of BlockdevOptionsBlkverify when driver is "blkverify"
7033 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
7035 The members of BlockdevOptionsGenericFormat when driver is "bochs"
7037 The members of BlockdevOptionsGenericFormat when driver is "cloop"
7039 The members of BlockdevOptionsGenericFormat when driver is "compress"
7041 The members of BlockdevOptionsCor when driver is "copy-on-read"
7043 The members of BlockdevOptionsGenericFormat when driver is "dmg"
7045 The members of BlockdevOptionsFile when driver is "file"
7047 The members of BlockdevOptionsCurlFtp when driver is "ftp"
7049 The members of BlockdevOptionsCurlFtps when driver is "ftps"
7051 The members of BlockdevOptionsGluster when driver is "gluster"
7053 The members of BlockdevOptionsFile when driver is "host_cdrom" (If: de‐
7055 fined(HAVE_HOST_BLOCK_DEVICE))
7056 The members of BlockdevOptionsFile when driver is "host_device" (If:
7058 defined(HAVE_HOST_BLOCK_DEVICE))
7059 The members of BlockdevOptionsCurlHttp when driver is "http"
7061 The members of BlockdevOptionsCurlHttps when driver is "https"
7063 The members of BlockdevOptionsIscsi when driver is "iscsi"
7065 The members of BlockdevOptionsLUKS when driver is "luks"
7067 The members of BlockdevOptionsNbd when driver is "nbd"
7069 The members of BlockdevOptionsNfs when driver is "nfs"
7071 The members of BlockdevOptionsNull when driver is "null-aio"
7073 The members of BlockdevOptionsNull when driver is "null-co"
7075 The members of BlockdevOptionsNVMe when driver is "nvme"
7077 The members of BlockdevOptionsGenericFormat when driver is "parallels"
7079 The members of BlockdevOptionsPreallocate when driver is "preallocate"
7081 The members of BlockdevOptionsQcow2 when driver is "qcow2"
7083 The members of BlockdevOptionsQcow when driver is "qcow"
7085 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
7087 The members of BlockdevOptionsQuorum when driver is "quorum"
7089 The members of BlockdevOptionsRaw when driver is "raw"
7091 The members of BlockdevOptionsRbd when driver is "rbd"
7093 The members of BlockdevOptionsReplication when driver is "replication"
7095 (If: defined(CONFIG_REPLICATION))
7096 The members of BlockdevOptionsSsh when driver is "ssh"
7098 The members of BlockdevOptionsThrottle when driver is "throttle"
7100 The members of BlockdevOptionsGenericFormat when driver is "vdi"
7102 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
7104 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
7106 The members of BlockdevOptionsGenericFormat when driver is "vpc"
7108 The members of BlockdevOptionsVVFAT when driver is "vvfat"
7110 Remaining options are determined by the block driver.
7111 Since
7113 2.9
7114 BlockdevRef (Alternate)
7116 Reference to a block device.
7117 Members
7119 definition: BlockdevOptions
7120 defines a new block device inline
7121 reference: string
7123 references the ID of an existing block device
7124 Since
7126 2.9
7127 BlockdevRefOrNull (Alternate)
7129 Reference to a block device.
7130 Members
7132 definition: BlockdevOptions
7133 defines a new block device inline
7134 reference: string
7136 references the ID of an existing block device. An empty string
7137 means that no block device should be referenced. Deprecated;
7138 use null instead.
7139 null: null
7141 No block device should be referenced (since 2.10)
7142 Since
7144 2.9
7145 blockdev-add (Command)
7147 Creates a new block device.
7148 Arguments
7150 The members of BlockdevOptions
7151 Since
7153 2.9
7154 Example
7156 1.
7157 -> { "execute": "blockdev-add",
7158 "arguments": {
7159 "driver": "qcow2",
7160 "node-name": "test1",
7161 "file": {
7162 "driver": "file",
7163 "filename": "test.qcow2"
7164 }
7165 }
7166 }
7167 <- { "return": {} }
7168 2.
7170 -> { "execute": "blockdev-add",
7171 "arguments": {
7172 "driver": "qcow2",
7173 "node-name": "node0",
7174 "discard": "unmap",
7175 "cache": {
7176 "direct": true
7177 },
7178 "file": {
7179 "driver": "file",
7180 "filename": "/tmp/test.qcow2"
7181 },
7182 "backing": {
7183 "driver": "raw",
7184 "file": {
7185 "driver": "file",
7186 "filename": "/dev/fdset/4"
7187 }
7188 }
7189 }
7190 }
7191 <- { "return": {} }
7193 blockdev-reopen (Command)
7195 Reopens one or more block devices using the given set of options. Any
7196 option not specified will be reset to its default value regardless of
7197 its previous status. If an option cannot be changed or a particular
7198 driver does not support reopening then the command will return an er‐
7199 ror. All devices in the list are reopened in one transaction, so if one
7200 of them fails then the whole transaction is cancelled.
7201 The command receives a list of block devices to reopen. For each one of
7203 them, the top-level node-name option (from BlockdevOptions) must be
7204 specified and is used to select the block device to be reopened. Other
7205 node-name options must be either omitted or set to the current name of
7206 the appropriate node. This command won't change any node name and any
7207 attempt to do it will result in an error.
7208 In the case of options that refer to child nodes, the behavior of this
7210 command depends on the value:
7211 1. A set of options (BlockdevOptions): the child is reopened with
7213 the specified set of options.
7214 2. A reference to the current child: the child is reopened using its
7216 existing set of options.
7217 3. A reference to a different node: the current child is replaced
7219 with the specified one.
7220 4. NULL: the current child (if any) is detached.
7222 Options (1) and (2) are supported in all cases. Option (3) is supported
7224 for file and backing, and option (4) for backing only.
7225 Unlike with blockdev-add, the backing option must always be present un‐
7227 less the node being reopened does not have a backing file and its image
7228 does not have a default backing file name as part of its metadata.
7229 Arguments
7231 options: array of BlockdevOptions
7232 Not documented
7233 Since
7235 6.1
7236 blockdev-del (Command)
7238 Deletes a block device that has been added using blockdev-add. The
7239 command will fail if the node is attached to a device or is otherwise
7240 being used.
7241 Arguments
7243 node-name: string
7244 Name of the graph node to delete.
7245 Since
7247 2.9
7248 Example
7250 -> { "execute": "blockdev-add",
7251 "arguments": {
7252 "driver": "qcow2",
7253 "node-name": "node0",
7254 "file": {
7255 "driver": "file",
7256 "filename": "test.qcow2"
7257 }
7258 }
7259 }
7260 <- { "return": {} }
7261 -> { "execute": "blockdev-del",
7263 "arguments": { "node-name": "node0" }
7264 }
7265 <- { "return": {} }
7266 BlockdevCreateOptionsFile (Object)
7268 Driver specific image creation options for file.
7269 Members
7271 filename: string
7272 Filename for the new image file
7273 size: int
7275 Size of the virtual disk in bytes
7276 preallocation: PreallocMode (optional)
7278 Preallocation mode for the new image (default: off; allowed val‐
7279 ues: off, falloc (if defined CONFIG_POSIX_FALLOCATE), full (if
7280 defined CONFIG_POSIX))
7281 nocow: boolean (optional)
7283 Turn off copy-on-write (valid only on btrfs; default: off)
7284 extent-size-hint: int (optional)
7286 Extent size hint to add to the image file; 0 for not adding an
7287 extent size hint (default: 1 MB, since 5.1)
7288 Since
7290 2.12
7291 BlockdevCreateOptionsGluster (Object)
7293 Driver specific image creation options for gluster.
7294 Members
7296 location: BlockdevOptionsGluster
7297 Where to store the new image file
7298 size: int
7300 Size of the virtual disk in bytes
7301 preallocation: PreallocMode (optional)
7303 Preallocation mode for the new image (default: off; allowed val‐
7304 ues: off, falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), full
7305 (if defined CONFIG_GLUSTERFS_ZEROFILL))
7306 Since
7308 2.12
7309 BlockdevCreateOptionsLUKS (Object)
7311 Driver specific image creation options for LUKS.
7312 Members
7314 file: BlockdevRef
7315 Node to create the image format on
7316 size: int
7318 Size of the virtual disk in bytes
7319 preallocation: PreallocMode (optional)
7321 Preallocation mode for the new image (since: 4.2) (default: off;
7322 allowed values: off, metadata, falloc, full)
7323 The members of QCryptoBlockCreateOptionsLUKS
7325 Since
7327 2.12
7328 BlockdevCreateOptionsNfs (Object)
7330 Driver specific image creation options for NFS.
7331 Members
7333 location: BlockdevOptionsNfs
7334 Where to store the new image file
7335 size: int
7337 Size of the virtual disk in bytes
7338 Since
7340 2.12
7341 BlockdevCreateOptionsParallels (Object)
7343 Driver specific image creation options for parallels.
7344 Members
7346 file: BlockdevRef
7347 Node to create the image format on
7348 size: int
7350 Size of the virtual disk in bytes
7351 cluster-size: int (optional)
7353 Cluster size in bytes (default: 1 MB)
7354 Since
7356 2.12
7357 BlockdevCreateOptionsQcow (Object)
7359 Driver specific image creation options for qcow.
7360 Members
7362 file: BlockdevRef
7363 Node to create the image format on
7364 size: int
7366 Size of the virtual disk in bytes
7367 backing-file: string (optional)
7369 File name of the backing file if a backing file should be used
7370 encrypt: QCryptoBlockCreateOptions (optional)
7372 Encryption options if the image should be encrypted
7373 Since
7375 2.12
7376 BlockdevQcow2Version (Enum)
7378 Values
7379 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
7380 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
7382 Since
7384 2.12
7385 Qcow2CompressionType (Enum)
7387 Compression type used in qcow2 image file
7388 Values
7390 zlib zlib compression, see <http://zlib.net/>
7391 zstd (If: defined(CONFIG_ZSTD))
7393 zstd compression, see <http://github.com/facebook/zstd>
7394 Since
7396 5.1
7397 BlockdevCreateOptionsQcow2 (Object)
7399 Driver specific image creation options for qcow2.
7400 Members
7402 file: BlockdevRef
7403 Node to create the image format on
7404 data-file: BlockdevRef (optional)
7406 Node to use as an external data file in which all guest data is
7407 stored so that only metadata remains in the qcow2 file (since:
7408 4.0)
7409 data-file-raw: boolean (optional)
7411 True if the external data file must stay valid as a standalone
7412 (read-only) raw image without looking at qcow2 metadata (de‐
7413 fault: false; since: 4.0)
7414 extended-l2: boolean (optional)
7416 True to make the image have extended L2 entries (default: false;
7417 since 5.2)
7418 size: int
7420 Size of the virtual disk in bytes
7421 version: BlockdevQcow2Version (optional)
7423 Compatibility level (default: v3)
7424 backing-file: string (optional)
7426 File name of the backing file if a backing file should be used
7427 backing-fmt: BlockdevDriver (optional)
7429 Name of the block driver to use for the backing file
7430 encrypt: QCryptoBlockCreateOptions (optional)
7432 Encryption options if the image should be encrypted
7433 cluster-size: int (optional)
7435 qcow2 cluster size in bytes (default: 65536)
7436 preallocation: PreallocMode (optional)
7438 Preallocation mode for the new image (default: off; allowed val‐
7439 ues: off, falloc, full, metadata)
7440 lazy-refcounts: boolean (optional)
7442 True if refcounts may be updated lazily (default: off)
7443 refcount-bits: int (optional)
7445 Width of reference counts in bits (default: 16)
7446 compression-type: Qcow2CompressionType (optional)
7448 The image cluster compression method (default: zlib, since 5.1)
7449 Since
7451 2.12
7452 BlockdevCreateOptionsQed (Object)
7454 Driver specific image creation options for qed.
7455 Members
7457 file: BlockdevRef
7458 Node to create the image format on
7459 size: int
7461 Size of the virtual disk in bytes
7462 backing-file: string (optional)
7464 File name of the backing file if a backing file should be used
7465 backing-fmt: BlockdevDriver (optional)
7467 Name of the block driver to use for the backing file
7468 cluster-size: int (optional)
7470 Cluster size in bytes (default: 65536)
7471 table-size: int (optional)
7473 L1/L2 table size (in clusters)
7474 Since
7476 2.12
7477 BlockdevCreateOptionsRbd (Object)
7479 Driver specific image creation options for rbd/Ceph.
7480 Members
7482 location: BlockdevOptionsRbd
7483 Where to store the new image file. This location cannot point to
7484 a snapshot.
7485 size: int
7487 Size of the virtual disk in bytes
7488 cluster-size: int (optional)
7490 RBD object size
7491 encrypt: RbdEncryptionCreateOptions (optional)
7493 Image encryption options. (Since 6.1)
7494 Since
7496 2.12
7497 BlockdevVmdkSubformat (Enum)
7499 Subformat options for VMDK images
7500 Values
7502 monolithicSparse
7503 Single file image with sparse cluster allocation
7504 monolithicFlat
7506 Single flat data image and a descriptor file
7507 twoGbMaxExtentSparse
7509 Data is split into 2GB (per virtual LBA) sparse extent files, in
7510 addition to a descriptor file
7511 twoGbMaxExtentFlat
7513 Data is split into 2GB (per virtual LBA) flat extent files, in
7514 addition to a descriptor file
7515 streamOptimized
7517 Single file image sparse cluster allocation, optimized for
7518 streaming over network.
7519 Since
7521 4.0
7522 BlockdevVmdkAdapterType (Enum)
7524 Adapter type info for VMDK images
7525 Values
7527 ide Not documented
7528 buslogic
7530 Not documented
7531 lsilogic
7533 Not documented
7534 legacyESX
7536 Not documented
7537 Since
7539 4.0
7540 BlockdevCreateOptionsVmdk (Object)
7542 Driver specific image creation options for VMDK.
7543 Members
7545 file: BlockdevRef
7546 Where to store the new image file. This refers to the image file
7547 for monolithcSparse and streamOptimized format, or the descrip‐
7548 tor file for other formats.
7549 size: int
7551 Size of the virtual disk in bytes
7552 extents: array of BlockdevRef (optional)
7554 Where to store the data extents. Required for monolithcFlat,
7555 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
7556 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
7557 mats, the number of entries required is calculated as ex‐
7558 tent_number = virtual_size / 2GB. Providing more extents than
7559 will be used is an error.
7560 subformat: BlockdevVmdkSubformat (optional)
7562 The subformat of the VMDK image. Default: "monolithicSparse".
7563 backing-file: string (optional)
7565 The path of backing file. Default: no backing file is used.
7566 adapter-type: BlockdevVmdkAdapterType (optional)
7568 The adapter type used to fill in the descriptor. Default: ide.
7569 hwversion: string (optional)
7571 Hardware version. The meaningful options are "4" or "6". De‐
7572 fault: "4".
7573 zeroed-grain: boolean (optional)
7575 Whether to enable zeroed-grain feature for sparse subformats.
7576 Default: false.
7577 Since
7579 4.0
7580 BlockdevCreateOptionsSsh (Object)
7582 Driver specific image creation options for SSH.
7583 Members
7585 location: BlockdevOptionsSsh
7586 Where to store the new image file
7587 size: int
7589 Size of the virtual disk in bytes
7590 Since
7592 2.12
7593 BlockdevCreateOptionsVdi (Object)
7595 Driver specific image creation options for VDI.
7596 Members
7598 file: BlockdevRef
7599 Node to create the image format on
7600 size: int
7602 Size of the virtual disk in bytes
7603 preallocation: PreallocMode (optional)
7605 Preallocation mode for the new image (default: off; allowed val‐
7606 ues: off, metadata)
7607 Since
7609 2.12
7610 BlockdevVhdxSubformat (Enum)
7612 Values
7613 dynamic
7614 Growing image file
7615 fixed Preallocated fixed-size image file
7617 Since
7619 2.12
7620 BlockdevCreateOptionsVhdx (Object)
7622 Driver specific image creation options for vhdx.
7623 Members
7625 file: BlockdevRef
7626 Node to create the image format on
7627 size: int
7629 Size of the virtual disk in bytes
7630 log-size: int (optional)
7632 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
7633 block-size: int (optional)
7635 Block size in bytes, must be a multiple of 1 MB and not larger
7636 than 256 MB (default: automatically choose a block size depend‐
7637 ing on the image size)
7638 subformat: BlockdevVhdxSubformat (optional)
7640 vhdx subformat (default: dynamic)
7641 block-state-zero: boolean (optional)
7643 Force use of payload blocks of type 'ZERO'. Non-standard, but
7644 default. Do not set to 'off' when using 'qemu-img convert' with
7645 subformat=dynamic.
7646 Since
7648 2.12
7649 BlockdevVpcSubformat (Enum)
7651 Values
7652 dynamic
7653 Growing image file
7654 fixed Preallocated fixed-size image file
7656 Since
7658 2.12
7659 BlockdevCreateOptionsVpc (Object)
7661 Driver specific image creation options for vpc (VHD).
7662 Members
7664 file: BlockdevRef
7665 Node to create the image format on
7666 size: int
7668 Size of the virtual disk in bytes
7669 subformat: BlockdevVpcSubformat (optional)
7671 vhdx subformat (default: dynamic)
7672 force-size: boolean (optional)
7674 Force use of the exact byte size instead of rounding to the next
7675 size that can be represented in CHS geometry (default: false)
7676 Since
7678 2.12
7679 BlockdevCreateOptions (Object)
7681 Options for creating an image format on a given node.
7682 Members
7684 driver: BlockdevDriver
7685 block driver to create the image format
7686 The members of BlockdevCreateOptionsFile when driver is "file"
7688 The members of BlockdevCreateOptionsGluster when driver is "gluster"
7690 The members of BlockdevCreateOptionsLUKS when driver is "luks"
7692 The members of BlockdevCreateOptionsNfs when driver is "nfs"
7694 The members of BlockdevCreateOptionsParallels when driver is "paral‐
7696 lels"
7697 The members of BlockdevCreateOptionsQcow when driver is "qcow"
7699 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
7701 The members of BlockdevCreateOptionsQed when driver is "qed"
7703 The members of BlockdevCreateOptionsRbd when driver is "rbd"
7705 The members of BlockdevCreateOptionsSsh when driver is "ssh"
7707 The members of BlockdevCreateOptionsVdi when driver is "vdi"
7709 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
7711 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
7713 The members of BlockdevCreateOptionsVpc when driver is "vpc"
7715 Since
7717 2.12
7718 blockdev-create (Command)
7720 Starts a job to create an image format on a given node. The job is au‐
7721 tomatically finalized, but a manual job-dismiss is required.
7722 Arguments
7724 job-id: string
7725 Identifier for the newly created job.
7726 options: BlockdevCreateOptions
7728 Options for the image creation.
7729 Since
7731 3.0
7732 BlockdevAmendOptionsLUKS (Object)
7734 Driver specific image amend options for LUKS.
7735 Members
7737 The members of QCryptoBlockAmendOptionsLUKS
7738 Since
7740 5.1
7741 BlockdevAmendOptionsQcow2 (Object)
7743 Driver specific image amend options for qcow2. For now, only encryp‐
7744 tion options can be amended
7745 encrypt Encryption options to be amended
7747 Members
7749 encrypt: QCryptoBlockAmendOptions (optional)
7750 Not documented
7751 Since
7753 5.1
7754 BlockdevAmendOptions (Object)
7756 Options for amending an image format
7757 Members
7759 driver: BlockdevDriver
7760 Block driver of the node to amend.
7761 The members of BlockdevAmendOptionsLUKS when driver is "luks"
7763 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
7765 Since
7767 5.1
7768 x-blockdev-amend (Command)
7770 Starts a job to amend format specific options of an existing open block
7771 device The job is automatically finalized, but a manual job-dismiss is
7772 required.
7773 Arguments
7775 job-id: string
7776 Identifier for the newly created job.
7777 node-name: string
7779 Name of the block node to work on
7780 options: BlockdevAmendOptions
7782 Options (driver specific)
7783 force: boolean (optional)
7785 Allow unsafe operations, format specific For luks that allows
7786 erase of the last active keyslot (permanent loss of data), and
7787 replacement of an active keyslot (possible loss of data if IO
7788 error happens)
7789 Since
7791 5.1
7792 BlockErrorAction (Enum)
7794 An enumeration of action that has been taken when a DISK I/O occurs
7795 Values
7797 ignore error has been ignored
7798 report error has been reported to the device
7800 stop error caused VM to be stopped
7802 Since
7804 2.1
7805 BLOCK_IMAGE_CORRUPTED (Event)
7807 Emitted when a disk image is being marked corrupt. The image can be
7808 identified by its device or node name. The 'device' field is always
7809 present for compatibility reasons, but it can be empty ("") if the im‐
7810 age does not have a device name associated.
7811 Arguments
7813 device: string
7814 device name. This is always present for compatibility reasons,
7815 but it can be empty ("") if the image does not have a device
7816 name associated.
7817 node-name: string (optional)
7819 node name (Since: 2.4)
7820 msg: string
7822 informative message for human consumption, such as the kind of
7823 corruption being detected. It should not be parsed by machine as
7824 it is not guaranteed to be stable
7825 offset: int (optional)
7827 if the corruption resulted from an image access, this is the
7828 host's access offset into the image
7829 size: int (optional)
7831 if the corruption resulted from an image access, this is the ac‐
7832 cess size
7833 fatal: boolean
7835 if set, the image is marked corrupt and therefore unusable after
7836 this event and must be repaired (Since 2.2; before, every
7837 BLOCK_IMAGE_CORRUPTED event was fatal)
7838 Note
7840 If action is "stop", a STOP event will eventually follow the
7841 BLOCK_IO_ERROR event.
7842 Example
7844 <- { "event": "BLOCK_IMAGE_CORRUPTED",
7845 "data": { "device": "ide0-hd0", "node-name": "node0",
7846 "msg": "Prevented active L1 table overwrite", "offset": 196608,
7847 "size": 65536 },
7848 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
7849 Since
7851 1.7
7852 BLOCK_IO_ERROR (Event)
7854 Emitted when a disk I/O error occurs
7855 Arguments
7857 device: string
7858 device name. This is always present for compatibility reasons,
7859 but it can be empty ("") if the image does not have a device
7860 name associated.
7861 node-name: string (optional)
7863 node name. Note that errors may be reported for the root node
7864 that is directly attached to a guest device rather than for the
7865 node where the error occurred. The node name is not present if
7866 the drive is empty. (Since: 2.8)
7867 operation: IoOperationType
7869 I/O operation
7870 action: BlockErrorAction
7872 action that has been taken
7873 nospace: boolean (optional)
7875 true if I/O error was caused due to a no-space condition. This
7876 key is only present if query-block's io-status is present,
7877 please see query-block documentation for more information
7878 (since: 2.2)
7879 reason: string
7881 human readable string describing the error cause. (This field
7882 is a debugging aid for humans, it should not be parsed by appli‐
7883 cations) (since: 2.2)
7884 Note
7886 If action is "stop", a STOP event will eventually follow the
7887 BLOCK_IO_ERROR event
7888 Since
7890 0.13
7891 Example
7893 <- { "event": "BLOCK_IO_ERROR",
7894 "data": { "device": "ide0-hd1",
7895 "node-name": "#block212",
7896 "operation": "write",
7897 "action": "stop" },
7898 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7899 BLOCK_JOB_COMPLETED (Event)
7901 Emitted when a block job has completed
7902 Arguments
7904 type: JobType
7905 job type
7906 device: string
7908 The job identifier. Originally the device name but other values
7909 are allowed since QEMU 2.7
7910 len: int
7912 maximum progress value
7913 offset: int
7915 current progress value. On success this is equal to len. On
7916 failure this is less than len
7917 speed: int
7919 rate limit, bytes per second
7920 error: string (optional)
7922 error message. Only present on failure. This field contains a
7923 human-readable error message. There are no semantics other than
7924 that streaming has failed and clients should not try to inter‐
7925 pret the error string
7926 Since
7928 1.1
7929 Example
7931 <- { "event": "BLOCK_JOB_COMPLETED",
7932 "data": { "type": "stream", "device": "virtio-disk0",
7933 "len": 10737418240, "offset": 10737418240,
7934 "speed": 0 },
7935 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7936 BLOCK_JOB_CANCELLED (Event)
7938 Emitted when a block job has been cancelled
7939 Arguments
7941 type: JobType
7942 job type
7943 device: string
7945 The job identifier. Originally the device name but other values
7946 are allowed since QEMU 2.7
7947 len: int
7949 maximum progress value
7950 offset: int
7952 current progress value. On success this is equal to len. On
7953 failure this is less than len
7954 speed: int
7956 rate limit, bytes per second
7957 Since
7959 1.1
7960 Example
7962 <- { "event": "BLOCK_JOB_CANCELLED",
7963 "data": { "type": "stream", "device": "virtio-disk0",
7964 "len": 10737418240, "offset": 134217728,
7965 "speed": 0 },
7966 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7967 BLOCK_JOB_ERROR (Event)
7969 Emitted when a block job encounters an error
7970 Arguments
7972 device: string
7973 The job identifier. Originally the device name but other values
7974 are allowed since QEMU 2.7
7975 operation: IoOperationType
7977 I/O operation
7978 action: BlockErrorAction
7980 action that has been taken
7981 Since
7983 1.3
7984 Example
7986 <- { "event": "BLOCK_JOB_ERROR",
7987 "data": { "device": "ide0-hd1",
7988 "operation": "write",
7989 "action": "stop" },
7990 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7991 BLOCK_JOB_READY (Event)
7993 Emitted when a block job is ready to complete
7994 Arguments
7996 type: JobType
7997 job type
7998 device: string
8000 The job identifier. Originally the device name but other values
8001 are allowed since QEMU 2.7
8002 len: int
8004 maximum progress value
8005 offset: int
8007 current progress value. On success this is equal to len. On
8008 failure this is less than len
8009 speed: int
8011 rate limit, bytes per second
8012 Note
8014 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
8015 event
8016 Since
8018 1.3
8019 Example
8021 <- { "event": "BLOCK_JOB_READY",
8022 "data": { "device": "drive0", "type": "mirror", "speed": 0,
8023 "len": 2097152, "offset": 2097152 }
8024 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8025 BLOCK_JOB_PENDING (Event)
8027 Emitted when a block job is awaiting explicit authorization to finalize
8028 graph changes via block-job-finalize. If this job is part of a transac‐
8029 tion, it will not emit this event until the transaction has converged
8030 first.
8031 Arguments
8033 type: JobType
8034 job type
8035 id: string
8037 The job identifier.
8038 Since
8040 2.12
8041 Example
8043 <- { "event": "BLOCK_JOB_WAITING",
8044 "data": { "device": "drive0", "type": "mirror" },
8045 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8046 PreallocMode (Enum)
8048 Preallocation mode of QEMU image file
8049 Values
8051 off no preallocation
8052 metadata
8054 preallocate only for metadata
8055 falloc like full preallocation but allocate disk space by posix_fallo‐
8057 cate() rather than writing data.
8058 full preallocate all data by writing it to the device to ensure disk
8060 space is really available. This data may or may not be zero, de‐
8061 pending on the image format and storage. full preallocation
8062 also sets up metadata correctly.
8063 Since
8065 2.2
8066 BLOCK_WRITE_THRESHOLD (Event)
8068 Emitted when writes on block device reaches or exceeds the configured
8069 write threshold. For thin-provisioned devices, this means the device
8070 should be extended to avoid pausing for disk exhaustion. The event is
8071 one shot. Once triggered, it needs to be re-registered with another
8072 block-set-write-threshold command.
8073 Arguments
8075 node-name: string
8076 graph node name on which the threshold was exceeded.
8077 amount-exceeded: int
8079 amount of data which exceeded the threshold, in bytes.
8080 write-threshold: int
8082 last configured threshold, in bytes.
8083 Since
8085 2.3
8086 block-set-write-threshold (Command)
8088 Change the write threshold for a block drive. An event will be deliv‐
8089 ered if a write to this block drive crosses the configured threshold.
8090 The threshold is an offset, thus must be non-negative. Default is no
8091 write threshold. Setting the threshold to zero disables it.
8092 This is useful to transparently resize thin-provisioned drives without
8094 the guest OS noticing.
8095 Arguments
8097 node-name: string
8098 graph node name on which the threshold must be set.
8099 write-threshold: int
8101 configured threshold for the block device, bytes. Use 0 to dis‐
8102 able the threshold.
8103 Since
8105 2.3
8106 Example
8108 -> { "execute": "block-set-write-threshold",
8109 "arguments": { "node-name": "mydev",
8110 "write-threshold": 17179869184 } }
8111 <- { "return": {} }
8112 x-blockdev-change (Command)
8114 Dynamically reconfigure the block driver state graph. It can be used to
8115 add, remove, insert or replace a graph node. Currently only the Quorum
8116 driver implements this feature to add or remove its child. This is use‐
8117 ful to fix a broken quorum child.
8118 If node is specified, it will be inserted under parent. child may not
8120 be specified in this case. If both parent and child are specified but
8121 node is not, child will be detached from parent.
8122 Arguments
8124 parent: string
8125 the id or name of the parent node.
8126 child: string (optional)
8128 the name of a child under the given parent node.
8129 node: string (optional)
8131 the name of the node that will be added.
8132 Note
8134 this command is experimental, and its API is not stable. It does not
8135 support all kinds of operations, all kinds of children, nor all block
8136 drivers.
8137 FIXME Removing children from a quorum node means introducing gaps in
8139 the child indices. This cannot be represented in the 'children' list of
8140 BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
8141 Warning: The data in a new quorum child MUST be consistent with that of
8143 the rest of the array.
8144 Since
8146 2.7
8147 Example
8149 1. Add a new node to a quorum
8150 -> { "execute": "blockdev-add",
8151 "arguments": {
8152 "driver": "raw",
8153 "node-name": "new_node",
8154 "file": { "driver": "file",
8155 "filename": "test.raw" } } }
8156 <- { "return": {} }
8157 -> { "execute": "x-blockdev-change",
8158 "arguments": { "parent": "disk1",
8159 "node": "new_node" } }
8160 <- { "return": {} }
8161 2. Delete a quorum's node
8163 -> { "execute": "x-blockdev-change",
8164 "arguments": { "parent": "disk1",
8165 "child": "children.1" } }
8166 <- { "return": {} }
8167 x-blockdev-set-iothread (Command)
8169 Move node and its children into the iothread. If iothread is null then
8170 move node and its children into the main loop.
8171 The node must not be attached to a BlockBackend.
8173 Arguments
8175 node-name: string
8176 the name of the block driver node
8177 iothread: StrOrNull
8179 the name of the IOThread object or null for the main loop
8180 force: boolean (optional)
8182 true if the node and its children should be moved when a Block‐
8183 Backend is already attached
8184 Note
8186 this command is experimental and intended for test cases that need con‐
8187 trol over IOThreads only.
8188 Since
8190 2.12
8191 Example
8193 1. Move a node into an IOThread
8194 -> { "execute": "x-blockdev-set-iothread",
8195 "arguments": { "node-name": "disk1",
8196 "iothread": "iothread0" } }
8197 <- { "return": {} }
8198 2. Move a node into the main loop
8200 -> { "execute": "x-blockdev-set-iothread",
8201 "arguments": { "node-name": "disk1",
8202 "iothread": null } }
8203 <- { "return": {} }
8204 QuorumOpType (Enum)
8206 An enumeration of the quorum operation types
8207 Values
8209 read read operation
8210 write write operation
8212 flush flush operation
8214 Since
8216 2.6
8217 QUORUM_FAILURE (Event)
8219 Emitted by the Quorum block driver if it fails to establish a quorum
8220 Arguments
8222 reference: string
8223 device name if defined else node name
8224 sector-num: int
8226 number of the first sector of the failed read operation
8227 sectors-count: int
8229 failed read operation sector count
8230 Note
8232 This event is rate-limited.
8233 Since
8235 2.0
8236 Example
8238 <- { "event": "QUORUM_FAILURE",
8239 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
8240 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
8241 QUORUM_REPORT_BAD (Event)
8243 Emitted to report a corruption of a Quorum file
8244 Arguments
8246 type: QuorumOpType
8247 quorum operation type (Since 2.6)
8248 error: string (optional)
8250 error message. Only present on failure. This field contains a
8251 human-readable error message. There are no semantics other than
8252 that the block layer reported an error and clients should not
8253 try to interpret the error string.
8254 node-name: string
8256 the graph node name of the block driver state
8257 sector-num: int
8259 number of the first sector of the failed read operation
8260 sectors-count: int
8262 failed read operation sector count
8263 Note
8265 This event is rate-limited.
8266 Since
8268 2.0
8269 Example
8271 1. Read operation
8272 { "event": "QUORUM_REPORT_BAD",
8274 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
8275 "type": "read" },
8276 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
8277 2. Flush operation
8279 { "event": "QUORUM_REPORT_BAD",
8281 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
8282 "type": "flush", "error": "Broken pipe" },
8283 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
8284 BlockdevSnapshotInternal (Object)
8286 Members
8287 device: string
8288 the device name or node-name of a root node to generate the
8289 snapshot from
8290 name: string
8292 the name of the internal snapshot to be created
8293 Notes
8295 In transaction, if name is empty, or any snapshot matching name exists,
8296 the operation will fail. Only some image formats support it, for exam‐
8297 ple, qcow2, and rbd.
8298 Since
8300 1.7
8301 blockdev-snapshot-internal-sync (Command)
8303 Synchronously take an internal snapshot of a block device, when the
8304 format of the image used supports it. If the name is an empty string,
8305 or a snapshot with name already exists, the operation will fail.
8306 For the arguments, see the documentation of BlockdevSnapshotInternal.
8308 Returns
8310 • nothing on success
8311 • If device is not a valid block device, GenericError
8313 • If any snapshot matching name exists, or name is empty, GenericError
8315 • If the format of the image used does not support it, BlockFormatFea‐
8317 tureNotSupported
8318 Since
8320 1.7
8321 Example
8323 -> { "execute": "blockdev-snapshot-internal-sync",
8324 "arguments": { "device": "ide-hd0",
8325 "name": "snapshot0" }
8326 }
8327 <- { "return": {} }
8328 blockdev-snapshot-delete-internal-sync (Command)
8330 Synchronously delete an internal snapshot of a block device, when the
8331 format of the image used support it. The snapshot is identified by name
8332 or id or both. One of the name or id is required. Return SnapshotInfo
8333 for the successfully deleted snapshot.
8334 Arguments
8336 device: string
8337 the device name or node-name of a root node to delete the snap‐
8338 shot from
8339 id: string (optional)
8341 optional the snapshot's ID to be deleted
8342 name: string (optional)
8344 optional the snapshot's name to be deleted
8345 Returns
8347 • SnapshotInfo on success
8348 • If device is not a valid block device, GenericError
8350 • If snapshot not found, GenericError
8352 • If the format of the image used does not support it, BlockFormatFea‐
8354 tureNotSupported
8355 • If id and name are both not specified, GenericError
8357 Since
8359 1.7
8360 Example
8362 -> { "execute": "blockdev-snapshot-delete-internal-sync",
8363 "arguments": { "device": "ide-hd0",
8364 "name": "snapshot0" }
8365 }
8366 <- { "return": {
8367 "id": "1",
8368 "name": "snapshot0",
8369 "vm-state-size": 0,
8370 "date-sec": 1000012,
8371 "date-nsec": 10,
8372 "vm-clock-sec": 100,
8373 "vm-clock-nsec": 20,
8374 "icount": 220414
8375 }
8376 }
8377 Additional block stuff (VM related)
8379 BiosAtaTranslation (Enum)
8380 Policy that BIOS should use to interpret cylinder/head/sector ad‐
8381 dresses. Note that Bochs BIOS and SeaBIOS will not actually translate
8382 logical CHS to physical; instead, they will use logical block address‐
8383 ing.
8384 Values
8386 auto If cylinder/heads/sizes are passed, choose between none and LBA
8387 depending on the size of the disk. If they are not passed,
8388 choose none if QEMU can guess that the disk had 16 or fewer
8389 heads, large if QEMU can guess that the disk had 131072 or fewer
8390 tracks across all heads (i.e. cylinders*heads<131072), otherwise
8391 LBA.
8392 none The physical disk geometry is equal to the logical geometry.
8394 lba Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
8396 heads (if fewer than 255 are enough to cover the whole disk with
8397 1024 cylinders/head). The number of cylinders/head is then com‐
8398 puted based on the number of sectors and heads.
8399 large The number of cylinders per head is scaled down to 1024 by cor‐
8401 respondingly scaling up the number of heads.
8402 rechs Same as large, but first convert a 16-head geometry to 15-head,
8404 by proportionally scaling up the number of cylinders/head.
8405 Since
8407 2.0
8408 FloppyDriveType (Enum)
8410 Type of Floppy drive to be emulated by the Floppy Disk Controller.
8411 Values
8413 144 1.44MB 3.5" drive
8414 288 2.88MB 3.5" drive
8416 120 1.2MB 5.25" drive
8418 none No drive connected
8420 auto Automatically determined by inserted media at boot
8422 Since
8424 2.6
8425 PRManagerInfo (Object)
8427 Information about a persistent reservation manager
8428 Members
8430 id: string
8431 the identifier of the persistent reservation manager
8432 connected: boolean
8434 true if the persistent reservation manager is connected to the
8435 underlying storage or helper
8436 Since
8438 3.0
8439 query-pr-managers (Command)
8441 Returns a list of information about each persistent reservation man‐
8442 ager.
8443 Returns
8445 a list of PRManagerInfo for each persistent reservation manager
8446 Since
8448 3.0
8449 eject (Command)
8451 Ejects the medium from a removable drive.
8452 Arguments
8454 device: string (optional)
8455 Block device name
8456 id: string (optional)
8458 The name or QOM path of the guest device (since: 2.8)
8459 force: boolean (optional)
8461 If true, eject regardless of whether the drive is locked. If
8462 not specified, the default value is false.
8463 Features
8465 deprecated
8466 Member device is deprecated. Use id instead.
8467 Returns
8469 • Nothing on success
8470 • If device is not a valid block device, DeviceNotFound
8472 Notes
8474 Ejecting a device with no media results in success
8475 Since
8477 0.14
8478 Example
8480 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
8481 <- { "return": {} }
8482 blockdev-open-tray (Command)
8484 Opens a block device's tray. If there is a block driver state tree in‐
8485 serted as a medium, it will become inaccessible to the guest (but it
8486 will remain associated to the block device, so closing the tray will
8487 make it accessible again).
8488 If the tray was already open before, this will be a no-op.
8490 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
8492 cases in which no such event will be generated, these include:
8493 • if the guest has locked the tray, force is false and the guest does
8495 not respond to the eject request
8496 • if the BlockBackend denoted by device does not have a guest device
8498 attached to it
8499 • if the guest device does not have an actual tray
8501 Arguments
8503 device: string (optional)
8504 Block device name
8505 id: string (optional)
8507 The name or QOM path of the guest device (since: 2.8)
8508 force: boolean (optional)
8510 if false (the default), an eject request will be sent to the
8511 guest if it has locked the tray (and the tray will not be opened
8512 immediately); if true, the tray will be opened regardless of
8513 whether it is locked
8514 Features
8516 deprecated
8517 Member device is deprecated. Use id instead.
8518 Since
8520 2.5
8521 Example
8523 -> { "execute": "blockdev-open-tray",
8524 "arguments": { "id": "ide0-1-0" } }
8525 <- { "timestamp": { "seconds": 1418751016,
8527 "microseconds": 716996 },
8528 "event": "DEVICE_TRAY_MOVED",
8529 "data": { "device": "ide1-cd0",
8530 "id": "ide0-1-0",
8531 "tray-open": true } }
8532 <- { "return": {} }
8534 blockdev-close-tray (Command)
8536 Closes a block device's tray. If there is a block driver state tree as‐
8537 sociated with the block device (which is currently ejected), that tree
8538 will be loaded as the medium.
8539 If the tray was already closed before, this will be a no-op.
8541 Arguments
8543 device: string (optional)
8544 Block device name
8545 id: string (optional)
8547 The name or QOM path of the guest device (since: 2.8)
8548 Features
8550 deprecated
8551 Member device is deprecated. Use id instead.
8552 Since
8554 2.5
8555 Example
8557 -> { "execute": "blockdev-close-tray",
8558 "arguments": { "id": "ide0-1-0" } }
8559 <- { "timestamp": { "seconds": 1418751345,
8561 "microseconds": 272147 },
8562 "event": "DEVICE_TRAY_MOVED",
8563 "data": { "device": "ide1-cd0",
8564 "id": "ide0-1-0",
8565 "tray-open": false } }
8566 <- { "return": {} }
8568 blockdev-remove-medium (Command)
8570 Removes a medium (a block driver state tree) from a block device. That
8571 block device's tray must currently be open (unless there is no attached
8572 guest device).
8573 If the tray is open and there is no medium inserted, this will be a
8575 no-op.
8576 Arguments
8578 id: string
8579 The name or QOM path of the guest device
8580 Since
8582 2.12
8583 Example
8585 -> { "execute": "blockdev-remove-medium",
8586 "arguments": { "id": "ide0-1-0" } }
8587 <- { "error": { "class": "GenericError",
8589 "desc": "Tray of device 'ide0-1-0' is not open" } }
8590 -> { "execute": "blockdev-open-tray",
8592 "arguments": { "id": "ide0-1-0" } }
8593 <- { "timestamp": { "seconds": 1418751627,
8595 "microseconds": 549958 },
8596 "event": "DEVICE_TRAY_MOVED",
8597 "data": { "device": "ide1-cd0",
8598 "id": "ide0-1-0",
8599 "tray-open": true } }
8600 <- { "return": {} }
8602 -> { "execute": "blockdev-remove-medium",
8604 "arguments": { "id": "ide0-1-0" } }
8605 <- { "return": {} }
8607 blockdev-insert-medium (Command)
8609 Inserts a medium (a block driver state tree) into a block device. That
8610 block device's tray must currently be open (unless there is no attached
8611 guest device) and there must be no medium inserted already.
8612 Arguments
8614 id: string
8615 The name or QOM path of the guest device
8616 node-name: string
8618 name of a node in the block driver state graph
8619 Since
8621 2.12
8622 Example
8624 -> { "execute": "blockdev-add",
8625 "arguments": {
8626 "node-name": "node0",
8627 "driver": "raw",
8628 "file": { "driver": "file",
8629 "filename": "fedora.iso" } } }
8630 <- { "return": {} }
8631 -> { "execute": "blockdev-insert-medium",
8633 "arguments": { "id": "ide0-1-0",
8634 "node-name": "node0" } }
8635 <- { "return": {} }
8637 BlockdevChangeReadOnlyMode (Enum)
8639 Specifies the new read-only mode of a block device subject to the
8640 blockdev-change-medium command.
8641 Values
8643 retain Retains the current read-only mode
8644 read-only
8646 Makes the device read-only
8647 read-write
8649 Makes the device writable
8650 Since
8652 2.3
8653 blockdev-change-medium (Command)
8655 Changes the medium inserted into a block device by ejecting the current
8656 medium and loading a new image file which is inserted as the new medium
8657 (this command combines blockdev-open-tray, blockdev-remove-medium,
8658 blockdev-insert-medium and blockdev-close-tray).
8659 Arguments
8661 device: string (optional)
8662 Block device name
8663 id: string (optional)
8665 The name or QOM path of the guest device (since: 2.8)
8666 filename: string
8668 filename of the new image to be loaded
8669 format: string (optional)
8671 format to open the new image with (defaults to the probed for‐
8672 mat)
8673 read-only-mode: BlockdevChangeReadOnlyMode (optional)
8675 change the read-only mode of the device; defaults to 'retain'
8676 Features
8678 deprecated
8679 Member device is deprecated. Use id instead.
8680 Since
8682 2.5
8683 Examples
8685 1. Change a removable medium
8686 -> { "execute": "blockdev-change-medium",
8688 "arguments": { "id": "ide0-1-0",
8689 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
8690 "format": "raw" } }
8691 <- { "return": {} }
8692 2. Load a read-only medium into a writable drive
8694 -> { "execute": "blockdev-change-medium",
8696 "arguments": { "id": "floppyA",
8697 "filename": "/srv/images/ro.img",
8698 "format": "raw",
8699 "read-only-mode": "retain" } }
8700 <- { "error":
8702 { "class": "GenericError",
8703 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
8704 -> { "execute": "blockdev-change-medium",
8706 "arguments": { "id": "floppyA",
8707 "filename": "/srv/images/ro.img",
8708 "format": "raw",
8709 "read-only-mode": "read-only" } }
8710 <- { "return": {} }
8712 DEVICE_TRAY_MOVED (Event)
8714 Emitted whenever the tray of a removable device is moved by the guest
8715 or by HMP/QMP commands
8716 Arguments
8718 device: string
8719 Block device name. This is always present for compatibility rea‐
8720 sons, but it can be empty ("") if the image does not have a de‐
8721 vice name associated.
8722 id: string
8724 The name or QOM path of the guest device (since 2.8)
8725 tray-open: boolean
8727 true if the tray has been opened or false if it has been closed
8728 Since
8730 1.1
8731 Example
8733 <- { "event": "DEVICE_TRAY_MOVED",
8734 "data": { "device": "ide1-cd0",
8735 "id": "/machine/unattached/device[22]",
8736 "tray-open": true
8737 },
8738 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8739 PR_MANAGER_STATUS_CHANGED (Event)
8741 Emitted whenever the connected status of a persistent reservation man‐
8742 ager changes.
8743 Arguments
8745 id: string
8746 The id of the PR manager object
8747 connected: boolean
8749 true if the PR manager is connected to a backend
8750 Since
8752 3.0
8753 Example
8755 <- { "event": "PR_MANAGER_STATUS_CHANGED",
8756 "data": { "id": "pr-helper0",
8757 "connected": true
8758 },
8759 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
8760 block_set_io_throttle (Command)
8762 Change I/O throttle limits for a block drive.
8763 Since QEMU 2.4, each device with I/O limits is member of a throttle
8765 group.
8766 If two or more devices are members of the same group, the limits will
8768 apply to the combined I/O of the whole group in a round-robin fashion.
8769 Therefore, setting new I/O limits to a device will affect the whole
8770 group.
8771 The name of the group can be specified using the 'group' parameter. If
8773 the parameter is unset, it is assumed to be the current group of that
8774 device. If it's not in any group yet, the name of the device will be
8775 used as the name for its group.
8776 The 'group' parameter can also be used to move a device to a different
8778 group. In this case the limits specified in the parameters will be ap‐
8779 plied to the new group only.
8780 I/O limits can be disabled by setting all of them to 0. In this case
8782 the device will be removed from its group and the rest of its members
8783 will not be affected. The 'group' parameter is ignored.
8784 Arguments
8786 The members of BlockIOThrottle
8787 Returns
8789 • Nothing on success
8790 • If device is not a valid block device, DeviceNotFound
8792 Since
8794 1.1
8795 Example
8797 -> { "execute": "block_set_io_throttle",
8798 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
8799 "bps": 0,
8800 "bps_rd": 0,
8801 "bps_wr": 0,
8802 "iops": 512,
8803 "iops_rd": 0,
8804 "iops_wr": 0,
8805 "bps_max": 0,
8806 "bps_rd_max": 0,
8807 "bps_wr_max": 0,
8808 "iops_max": 0,
8809 "iops_rd_max": 0,
8810 "iops_wr_max": 0,
8811 "bps_max_length": 0,
8812 "iops_size": 0 } }
8813 <- { "return": {} }
8814 -> { "execute": "block_set_io_throttle",
8816 "arguments": { "id": "ide0-1-0",
8817 "bps": 1000000,
8818 "bps_rd": 0,
8819 "bps_wr": 0,
8820 "iops": 0,
8821 "iops_rd": 0,
8822 "iops_wr": 0,
8823 "bps_max": 8000000,
8824 "bps_rd_max": 0,
8825 "bps_wr_max": 0,
8826 "iops_max": 0,
8827 "iops_rd_max": 0,
8828 "iops_wr_max": 0,
8829 "bps_max_length": 60,
8830 "iops_size": 0 } }
8831 <- { "return": {} }
8832 block-latency-histogram-set (Command)
8834 Manage read, write and flush latency histograms for the device.
8835 If only id parameter is specified, remove all present latency his‐
8837 tograms for the device. Otherwise, add/reset some of (or all) latency
8838 histograms.
8839 Arguments
8841 id: string
8842 The name or QOM path of the guest device.
8843 boundaries: array of int (optional)
8845 list of interval boundary values (see description in BlockLaten‐
8846 cyHistogramInfo definition). If specified, all latency his‐
8847 tograms are removed, and empty ones created for all io types
8848 with intervals corresponding to boundaries (except for io types,
8849 for which specific boundaries are set through the following pa‐
8850 rameters).
8851 boundaries-read: array of int (optional)
8853 list of interval boundary values for read latency histogram. If
8854 specified, old read latency histogram is removed, and empty one
8855 created with intervals corresponding to boundaries-read. The pa‐
8856 rameter has higher priority then boundaries.
8857 boundaries-write: array of int (optional)
8859 list of interval boundary values for write latency histogram.
8860 boundaries-flush: array of int (optional)
8862 list of interval boundary values for flush latency histogram.
8863 Returns
8865 error if device is not found or any boundary arrays are invalid.
8866 Since
8868 4.0
8869 Example
8871 set new histograms for all io types with intervals
8872 [0, 10), [10, 50), [50, 100), [100, +inf):
8873 -> { "execute": "block-latency-histogram-set",
8875 "arguments": { "id": "drive0",
8876 "boundaries": [10, 50, 100] } }
8877 <- { "return": {} }
8878 Example
8880 set new histogram only for write, other histograms will remain
8881 not changed (or not created):
8882 -> { "execute": "block-latency-histogram-set",
8884 "arguments": { "id": "drive0",
8885 "boundaries-write": [10, 50, 100] } }
8886 <- { "return": {} }
8887 Example
8889 set new histograms with the following intervals:
8890 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
8891 write: [0, 1000), [1000, 5000), [5000, +inf)
8892 -> { "execute": "block-latency-histogram-set",
8894 "arguments": { "id": "drive0",
8895 "boundaries": [10, 50, 100],
8896 "boundaries-write": [1000, 5000] } }
8897 <- { "return": {} }
8898 Example
8900 remove all latency histograms:
8901 -> { "execute": "block-latency-histogram-set",
8903 "arguments": { "id": "drive0" } }
8904 <- { "return": {} }
8905 Block device exports
8907 NbdServerOptions (Object)
8908 Keep this type consistent with the nbd-server-start arguments. The only
8909 intended difference is using SocketAddress instead of SocketAddressLe‐
8910 gacy.
8911 Members
8913 addr: SocketAddress
8914 Address on which to listen.
8915 tls-creds: string (optional)
8917 ID of the TLS credentials object (since 2.6).
8918 tls-authz: string (optional)
8920 ID of the QAuthZ authorization object used to validate the
8921 client's x509 distinguished name. This object is is only re‐
8922 solved at time of use, so can be deleted and recreated on the
8923 fly while the NBD server is active. If missing, it will default
8924 to denying access (since 4.0).
8925 max-connections: int (optional)
8927 The maximum number of connections to allow at the same time, 0
8928 for unlimited. (since 5.2; default: 0)
8929 Since
8931 4.2
8932 nbd-server-start (Command)
8934 Start an NBD server listening on the given host and port. Block de‐
8935 vices can then be exported using nbd-server-add. The NBD server will
8936 present them as named exports; for example, another QEMU instance could
8937 refer to them as "nbd:HOST:PORT:exportname=NAME".
8938 Keep this type consistent with the NbdServerOptions type. The only in‐
8940 tended difference is using SocketAddressLegacy instead of SocketAd‐
8941 dress.
8942 Arguments
8944 addr: SocketAddressLegacy
8945 Address on which to listen.
8946 tls-creds: string (optional)
8948 ID of the TLS credentials object (since 2.6).
8949 tls-authz: string (optional)
8951 ID of the QAuthZ authorization object used to validate the
8952 client's x509 distinguished name. This object is is only re‐
8953 solved at time of use, so can be deleted and recreated on the
8954 fly while the NBD server is active. If missing, it will default
8955 to denying access (since 4.0).
8956 max-connections: int (optional)
8958 The maximum number of connections to allow at the same time, 0
8959 for unlimited. (since 5.2; default: 0)
8960 Returns
8962 error if the server is already running.
8963 Since
8965 1.3
8966 BlockExportOptionsNbdBase (Object)
8968 An NBD block export (common options shared between nbd-server-add and
8969 the NBD branch of block-export-add).
8970 Members
8972 name: string (optional)
8973 Export name. If unspecified, the device parameter is used as the
8974 export name. (Since 2.12)
8975 description: string (optional)
8977 Free-form description of the export, up to 4096 bytes. (Since
8978 5.0)
8979 Since
8981 5.0
8982 BlockExportOptionsNbd (Object)
8984 An NBD block export (distinct options used in the NBD branch of
8985 block-export-add).
8986 Members
8988 bitmaps: array of string (optional)
8989 Also export each of the named dirty bitmaps reachable from de‐
8990 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
8991 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
8992 each bitmap.
8993 allocation-depth: boolean (optional)
8995 Also export the allocation depth map for device, so the NBD
8996 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
8997 text name "qemu:allocation-depth" to inspect allocation details.
8998 (since 5.2)
8999 The members of BlockExportOptionsNbdBase
9001 Since
9003 5.2
9004 BlockExportOptionsVhostUserBlk (Object)
9006 A vhost-user-blk block export.
9007 Members
9009 addr: SocketAddress
9010 The vhost-user socket on which to listen. Both 'unix' and 'fd'
9011 SocketAddress types are supported. Passed fds must be UNIX do‐
9012 main sockets.
9013 logical-block-size: int (optional)
9015 Logical block size in bytes. Defaults to 512 bytes.
9016 num-queues: int (optional)
9018 Number of request virtqueues. Must be greater than 0. Defaults
9019 to 1.
9020 Since
9022 5.2
9023 FuseExportAllowOther (Enum)
9025 Possible allow_other modes for FUSE exports.
9026 Values
9028 off Do not pass allow_other as a mount option.
9029 on Pass allow_other as a mount option.
9031 auto Try mounting with allow_other first, and if that fails, retry
9033 without allow_other.
9034 Since
9036 6.1
9037 BlockExportOptionsFuse (Object)
9039 Options for exporting a block graph node on some (file) mountpoint as a
9040 raw image.
9041 Members
9043 mountpoint: string
9044 Path on which to export the block device via FUSE. This must
9045 point to an existing regular file.
9046 growable: boolean (optional)
9048 Whether writes beyond the EOF should grow the block node accord‐
9049 ingly. (default: false)
9050 allow-other: FuseExportAllowOther (optional)
9052 If this is off, only qemu's user is allowed access to this ex‐
9053 port. That cannot be changed even with chmod or chown. En‐
9054 abling this option will allow other users access to the export
9055 with the FUSE mount option "allow_other". Note that using al‐
9056 low_other as a non-root user requires user_allow_other to be en‐
9057 abled in the global fuse.conf configuration file. In auto mode
9058 (the default), the FUSE export driver will first attempt to
9059 mount the export with allow_other, and if that fails, try again
9060 without. (since 6.1; default: auto)
9061 Since
9063 6.0
9064 If
9066 defined(CONFIG_FUSE)
9067 NbdServerAddOptions (Object)
9069 An NBD block export, per legacy nbd-server-add command.
9070 Members
9072 device: string
9073 The device name or node name of the node to be exported
9074 writable: boolean (optional)
9076 Whether clients should be able to write to the device via the
9077 NBD connection (default false).
9078 bitmap: string (optional)
9080 Also export a single dirty bitmap reachable from device, so the
9081 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
9082 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
9083 (since 4.0).
9084 The members of BlockExportOptionsNbdBase
9086 Since
9088 5.0
9089 nbd-server-add (Command)
9091 Export a block node to QEMU's embedded NBD server.
9092 The export name will be used as the id for the resulting block export.
9094 Arguments
9096 The members of NbdServerAddOptions
9097 Features
9099 deprecated
9100 This command is deprecated. Use block-export-add instead.
9101 Returns
9103 error if the server is not running, or export with the same name al‐
9104 ready exists.
9105 Since
9107 1.3
9108 BlockExportRemoveMode (Enum)
9110 Mode for removing a block export.
9111 Values
9113 safe Remove export if there are no existing connections, fail other‐
9114 wise.
9115 hard Drop all connections immediately and remove export.
9117 Potential additional modes to be added in the future:
9118 hide: Just hide export from new clients, leave existing connections as
9120 is. Remove export after all clients are disconnected.
9121 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
9123 ther requests from existing clients.
9124 Since
9126 2.12
9127 nbd-server-remove (Command)
9129 Remove NBD export by name.
9130 Arguments
9132 name: string
9133 Block export id.
9134 mode: BlockExportRemoveMode (optional)
9136 Mode of command operation. See BlockExportRemoveMode descrip‐
9137 tion. Default is 'safe'.
9138 Features
9140 deprecated
9141 This command is deprecated. Use block-export-del instead.
9142 Returns
9144 error if
9145 • the server is not running
9147 • export is not found
9149 • mode is 'safe' and there are existing connections
9151 Since
9153 2.12
9154 nbd-server-stop (Command)
9156 Stop QEMU's embedded NBD server, and unregister all devices previously
9157 added via nbd-server-add.
9158 Since
9160 1.3
9161 BlockExportType (Enum)
9163 An enumeration of block export types
9164 Values
9166 nbd NBD export
9167 vhost-user-blk
9169 vhost-user-blk export (since 5.2)
9170 fuse (If: defined(CONFIG_FUSE))
9172 FUSE export (since: 6.0)
9173 Since
9175 4.2
9176 BlockExportOptions (Object)
9178 Describes a block export, i.e. how single node should be exported on an
9179 external interface.
9180 Members
9182 id: string
9183 A unique identifier for the block export (across all export
9184 types)
9185 node-name: string
9187 The node name of the block node to be exported (since: 5.2)
9188 writable: boolean (optional)
9190 True if clients should be able to write to the export (default
9191 false)
9192 writethrough: boolean (optional)
9194 If true, caches are flushed after every write request to the ex‐
9195 port before completion is signalled. (since: 5.2; default:
9196 false)
9197 iothread: string (optional)
9199 The name of the iothread object where the export will run. The
9200 default is to use the thread currently associated with the block
9201 node. (since: 5.2)
9202 fixed-iothread: boolean (optional)
9204 True prevents the block node from being moved to another thread
9205 while the export is active. If true and iothread is given, ex‐
9206 port creation fails if the block node cannot be moved to the io‐
9207 thread. The default is false. (since: 5.2)
9208 type: BlockExportType
9210 Not documented
9211 The members of BlockExportOptionsNbd when type is "nbd"
9213 The members of BlockExportOptionsVhostUserBlk when type is
9215 "vhost-user-blk"
9216 The members of BlockExportOptionsFuse when type is "fuse" (If: de‐
9218 fined(CONFIG_FUSE))
9219 Since
9221 4.2
9222 block-export-add (Command)
9224 Creates a new block export.
9225 Arguments
9227 The members of BlockExportOptions
9228 Since
9230 5.2
9231 block-export-del (Command)
9233 Request to remove a block export. This drops the user's reference to
9234 the export, but the export may still stay around after this command re‐
9235 turns until the shutdown of the export has completed.
9236 Arguments
9238 id: string
9239 Block export id.
9240 mode: BlockExportRemoveMode (optional)
9242 Mode of command operation. See BlockExportRemoveMode descrip‐
9243 tion. Default is 'safe'.
9244 Returns
9246 Error if the export is not found or mode is 'safe' and the export is
9247 still in use (e.g. by existing client connections)
9248 Since
9250 5.2
9251 BLOCK_EXPORT_DELETED (Event)
9253 Emitted when a block export is removed and its id can be reused.
9254 Arguments
9256 id: string
9257 Block export id.
9258 Since
9260 5.2
9261 BlockExportInfo (Object)
9263 Information about a single block export.
9264 Members
9266 id: string
9267 The unique identifier for the block export
9268 type: BlockExportType
9270 The block export type
9271 node-name: string
9273 The node name of the block node that is exported
9274 shutting-down: boolean
9276 True if the export is shutting down (e.g. after a block-ex‐
9277 port-del command, but before the shutdown has completed)
9278 Since
9280 5.2
9281 query-block-exports (Command)
9283 Returns
9284 A list of BlockExportInfo describing all block exports
9285 Since
9287 5.2
9288
9290 ChardevInfo (Object)
9291 Information about a character device.
9292 Members
9294 label: string
9295 the label of the character device
9296 filename: string
9298 the filename of the character device
9299 frontend-open: boolean
9301 shows whether the frontend device attached to this backend (eg.
9302 with the chardev=... option) is in open or closed state (since
9303 2.1)
9304 Notes
9306 filename is encoded using the QEMU command line character device encod‐
9307 ing. See the QEMU man page for details.
9308 Since
9310 0.14
9311 query-chardev (Command)
9313 Returns information about current character devices.
9314 Returns
9316 a list of ChardevInfo
9317 Since
9319 0.14
9320 Example
9322 -> { "execute": "query-chardev" }
9323 <- {
9324 "return": [
9325 {
9326 "label": "charchannel0",
9327 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
9328 "frontend-open": false
9329 },
9330 {
9331 "label": "charmonitor",
9332 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
9333 "frontend-open": true
9334 },
9335 {
9336 "label": "charserial0",
9337 "filename": "pty:/dev/pts/2",
9338 "frontend-open": true
9339 }
9340 ]
9341 }
9342 ChardevBackendInfo (Object)
9344 Information about a character device backend
9345 Members
9347 name: string
9348 The backend name
9349 Since
9351 2.0
9352 query-chardev-backends (Command)
9354 Returns information about character device backends.
9355 Returns
9357 a list of ChardevBackendInfo
9358 Since
9360 2.0
9361 Example
9363 -> { "execute": "query-chardev-backends" }
9364 <- {
9365 "return":[
9366 {
9367 "name":"udp"
9368 },
9369 {
9370 "name":"tcp"
9371 },
9372 {
9373 "name":"unix"
9374 },
9375 {
9376 "name":"spiceport"
9377 }
9378 ]
9379 }
9380 DataFormat (Enum)
9382 An enumeration of data format.
9383 Values
9385 utf8 Data is a UTF-8 string (RFC 3629)
9386 base64 Data is Base64 encoded binary (RFC 3548)
9388 Since
9390 1.4
9391 ringbuf-write (Command)
9393 Write to a ring buffer character device.
9394 Arguments
9396 device: string
9397 the ring buffer character device name
9398 data: string
9400 data to write
9401 format: DataFormat (optional)
9403 data encoding (default 'utf8').
9404 • base64: data must be base64 encoded text. Its binary decoding
9406 gets written.
9407 • utf8: data's UTF-8 encoding is written
9409 • data itself is always Unicode regardless of format, like any
9411 other string.
9412 Returns
9414 Nothing on success
9415 Since
9417 1.4
9418 Example
9420 -> { "execute": "ringbuf-write",
9421 "arguments": { "device": "foo",
9422 "data": "abcdefgh",
9423 "format": "utf8" } }
9424 <- { "return": {} }
9425 ringbuf-read (Command)
9427 Read from a ring buffer character device.
9428 Arguments
9430 device: string
9431 the ring buffer character device name
9432 size: int
9434 how many bytes to read at most
9435 format: DataFormat (optional)
9437 data encoding (default 'utf8').
9438 • base64: the data read is returned in base64 encoding.
9440 • utf8: the data read is interpreted as UTF-8. Bug: can screw
9442 up when the buffer contains invalid UTF-8 sequences, NUL char‐
9443 acters, after the ring buffer lost data, and when reading
9444 stops because the size limit is reached.
9445 • The return value is always Unicode regardless of format, like
9447 any other string.
9448 Returns
9450 data read from the device
9451 Since
9453 1.4
9454 Example
9456 -> { "execute": "ringbuf-read",
9457 "arguments": { "device": "foo",
9458 "size": 1000,
9459 "format": "utf8" } }
9460 <- { "return": "abcdefgh" }
9461 ChardevCommon (Object)
9463 Configuration shared across all chardev backends
9464 Members
9466 logfile: string (optional)
9467 The name of a logfile to save output
9468 logappend: boolean (optional)
9470 true to append instead of truncate (default to false to trun‐
9471 cate)
9472 Since
9474 2.6
9475 ChardevFile (Object)
9477 Configuration info for file chardevs.
9478 Members
9480 in: string (optional)
9481 The name of the input file
9482 out: string
9484 The name of the output file
9485 append: boolean (optional)
9487 Open the file in append mode (default false to truncate) (Since
9488 2.6)
9489 The members of ChardevCommon
9491 Since
9493 1.4
9494 ChardevHostdev (Object)
9496 Configuration info for device and pipe chardevs.
9497 Members
9499 device: string
9500 The name of the special file for the device, i.e. /dev/ttyS0 on
9501 Unix or COM1: on Windows
9502 The members of ChardevCommon
9504 Since
9506 1.4
9507 ChardevSocket (Object)
9509 Configuration info for (stream) socket chardevs.
9510 Members
9512 addr: SocketAddressLegacy
9513 socket address to listen on (server=true) or connect to
9514 (server=false)
9515 tls-creds: string (optional)
9517 the ID of the TLS credentials object (since 2.6)
9518 tls-authz: string (optional)
9520 the ID of the QAuthZ authorization object against which the
9521 client's x509 distinguished name will be validated. This object
9522 is only resolved at time of use, so can be deleted and recreated
9523 on the fly while the chardev server is active. If missing, it
9524 will default to denying access (since 4.0)
9525 server: boolean (optional)
9527 create server socket (default: true)
9528 wait: boolean (optional)
9530 wait for incoming connection on server sockets (default: false).
9531 Silently ignored with server: false. This use is deprecated.
9532 nodelay: boolean (optional)
9534 set TCP_NODELAY socket option (default: false)
9535 telnet: boolean (optional)
9537 enable telnet protocol on server sockets (default: false)
9538 tn3270: boolean (optional)
9540 enable tn3270 protocol on server sockets (default: false)
9541 (Since: 2.10)
9542 websocket: boolean (optional)
9544 enable websocket protocol on server sockets (default: false)
9545 (Since: 3.1)
9546 reconnect: int (optional)
9548 For a client socket, if a socket is disconnected, then attempt a
9549 reconnect after the given number of seconds. Setting this to
9550 zero disables this function. (default: 0) (Since: 2.2)
9551 The members of ChardevCommon
9553 Since
9555 1.4
9556 ChardevUdp (Object)
9558 Configuration info for datagram socket chardevs.
9559 Members
9561 remote: SocketAddressLegacy
9562 remote address
9563 local: SocketAddressLegacy (optional)
9565 local address
9566 The members of ChardevCommon
9568 Since
9570 1.5
9571 ChardevMux (Object)
9573 Configuration info for mux chardevs.
9574 Members
9576 chardev: string
9577 name of the base chardev.
9578 The members of ChardevCommon
9580 Since
9582 1.5
9583 ChardevStdio (Object)
9585 Configuration info for stdio chardevs.
9586 Members
9588 signal: boolean (optional)
9589 Allow signals (such as SIGINT triggered by ^C) be delivered to
9590 qemu. Default: true.
9591 The members of ChardevCommon
9593 Since
9595 1.5
9596 ChardevSpiceChannel (Object)
9598 Configuration info for spice vm channel chardevs.
9599 Members
9601 type: string
9602 kind of channel (for example vdagent).
9603 The members of ChardevCommon
9605 Since
9607 1.5
9608 If
9610 defined(CONFIG_SPICE)
9611 ChardevSpicePort (Object)
9613 Configuration info for spice port chardevs.
9614 Members
9616 fqdn: string
9617 name of the channel (see docs/spice-port-fqdn.txt)
9618 The members of ChardevCommon
9620 Since
9622 1.5
9623 If
9625 defined(CONFIG_SPICE)
9626 ChardevVC (Object)
9628 Configuration info for virtual console chardevs.
9629 Members
9631 width: int (optional)
9632 console width, in pixels
9633 height: int (optional)
9635 console height, in pixels
9636 cols: int (optional)
9638 console width, in chars
9639 rows: int (optional)
9641 console height, in chars
9642 The members of ChardevCommon
9644 Since
9646 1.5
9647 ChardevRingbuf (Object)
9649 Configuration info for ring buffer chardevs.
9650 Members
9652 size: int (optional)
9653 ring buffer size, must be power of two, default is 65536
9654 The members of ChardevCommon
9656 Since
9658 1.5
9659 ChardevQemuVDAgent (Object)
9661 Configuration info for qemu vdagent implementation.
9662 Members
9664 mouse: boolean (optional)
9665 enable/disable mouse, default is enabled.
9666 clipboard: boolean (optional)
9668 enable/disable clipboard, default is disabled.
9669 The members of ChardevCommon
9671 Since
9673 6.1
9674 If
9676 defined(CONFIG_SPICE_PROTOCOL)
9677 ChardevBackend (Object)
9679 Configuration info for the new chardev backend.
9680 Members
9682 type One of file, serial, parallel, pipe, socket, udp, pty, null,
9683 mux, msmouse, wctablet, braille, testdev, stdio, console,
9684 spicevmc, spiceport, qemu-vdagent, vc, ringbuf, memory
9685 data: ChardevFile when type is "file"
9687 data: ChardevHostdev when type is "serial"
9689 data: ChardevHostdev when type is "parallel"
9691 data: ChardevHostdev when type is "pipe"
9693 data: ChardevSocket when type is "socket"
9695 data: ChardevUdp when type is "udp"
9697 data: ChardevCommon when type is "pty"
9699 data: ChardevCommon when type is "null"
9701 data: ChardevMux when type is "mux"
9703 data: ChardevCommon when type is "msmouse"
9705 data: ChardevCommon when type is "wctablet"
9707 data: ChardevCommon when type is "braille"
9709 data: ChardevCommon when type is "testdev"
9711 data: ChardevStdio when type is "stdio"
9713 data: ChardevCommon when type is "console"
9715 data: ChardevSpiceChannel when type is "spicevmc" (If: defined(CON‐
9717 FIG_SPICE))
9718 data: ChardevSpicePort when type is "spiceport" (If: defined(CON‐
9720 FIG_SPICE))
9721 data: ChardevQemuVDAgent when type is "qemu-vdagent" (If: defined(CON‐
9723 FIG_SPICE_PROTOCOL))
9724 data: ChardevVC when type is "vc"
9726 data: ChardevRingbuf when type is "ringbuf"
9728 data: ChardevRingbuf when type is "memory"
9730 Since
9732 1.4 (testdev since 2.2, wctablet since 2.9, vdagent since 6.1)
9733 ChardevReturn (Object)
9735 Return info about the chardev backend just created.
9736 Members
9738 pty: string (optional)
9739 name of the slave pseudoterminal device, present if and only if
9740 a chardev of type 'pty' was created
9741 Since
9743 1.4
9744 chardev-add (Command)
9746 Add a character device backend
9747 Arguments
9749 id: string
9750 the chardev's ID, must be unique
9751 backend: ChardevBackend
9753 backend type and parameters
9754 Returns
9756 ChardevReturn.
9757 Since
9759 1.4
9760 Example
9762 -> { "execute" : "chardev-add",
9763 "arguments" : { "id" : "foo",
9764 "backend" : { "type" : "null", "data" : {} } } }
9765 <- { "return": {} }
9766 -> { "execute" : "chardev-add",
9768 "arguments" : { "id" : "bar",
9769 "backend" : { "type" : "file",
9770 "data" : { "out" : "/tmp/bar.log" } } } }
9771 <- { "return": {} }
9772 -> { "execute" : "chardev-add",
9774 "arguments" : { "id" : "baz",
9775 "backend" : { "type" : "pty", "data" : {} } } }
9776 <- { "return": { "pty" : "/dev/pty/42" } }
9777 chardev-change (Command)
9779 Change a character device backend
9780 Arguments
9782 id: string
9783 the chardev's ID, must exist
9784 backend: ChardevBackend
9786 new backend type and parameters
9787 Returns
9789 ChardevReturn.
9790 Since
9792 2.10
9793 Example
9795 -> { "execute" : "chardev-change",
9796 "arguments" : { "id" : "baz",
9797 "backend" : { "type" : "pty", "data" : {} } } }
9798 <- { "return": { "pty" : "/dev/pty/42" } }
9799 -> {"execute" : "chardev-change",
9801 "arguments" : {
9802 "id" : "charchannel2",
9803 "backend" : {
9804 "type" : "socket",
9805 "data" : {
9806 "addr" : {
9807 "type" : "unix" ,
9808 "data" : {
9809 "path" : "/tmp/charchannel2.socket"
9810 }
9811 },
9812 "server" : true,
9813 "wait" : false }}}}
9814 <- {"return": {}}
9815 chardev-remove (Command)
9817 Remove a character device backend
9818 Arguments
9820 id: string
9821 the chardev's ID, must exist and not be in use
9822 Returns
9824 Nothing on success
9825 Since
9827 1.4
9828 Example
9830 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
9831 <- { "return": {} }
9832 chardev-send-break (Command)
9834 Send a break to a character device
9835 Arguments
9837 id: string
9838 the chardev's ID, must exist
9839 Returns
9841 Nothing on success
9842 Since
9844 2.10
9845 Example
9847 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
9848 <- { "return": {} }
9849 VSERPORT_CHANGE (Event)
9851 Emitted when the guest opens or closes a virtio-serial port.
9852 Arguments
9854 id: string
9855 device identifier of the virtio-serial port
9856 open: boolean
9858 true if the guest has opened the virtio-serial port
9859 Note
9861 This event is rate-limited.
9862 Since
9864 2.1
9865 Example
9867 <- { "event": "VSERPORT_CHANGE",
9868 "data": { "id": "channel0", "open": true },
9869 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
9870
9872 DumpGuestMemoryFormat (Enum)
9873 An enumeration of guest-memory-dump's format.
9874 Values
9876 elf elf format
9877 kdump-zlib
9879 kdump-compressed format with zlib-compressed
9880 kdump-lzo
9882 kdump-compressed format with lzo-compressed
9883 kdump-snappy
9885 kdump-compressed format with snappy-compressed
9886 win-dmp
9888 Windows full crashdump format, can be used instead of ELF con‐
9889 verting (since 2.13)
9890 Since
9892 2.0
9893 dump-guest-memory (Command)
9895 Dump guest's memory to vmcore. It is a synchronous operation that can
9896 take very long depending on the amount of guest memory.
9897 Arguments
9899 paging: boolean
9900 if true, do paging to get guest's memory mapping. This allows
9901 using gdb to process the core file.
9902 IMPORTANT: this option can make QEMU allocate several gigabytes
9904 of RAM. This can happen for a large guest, or a malicious guest
9905 pretending to be large.
9906 Also, paging=true has the following limitations:
9908 1. The guest may be in a catastrophic state or can have cor‐
9910 rupted memory, which cannot be trusted
9911 2. The guest can be in real-mode even if paging is enabled.
9913 For example, the guest uses ACPI to sleep, and ACPI sleep
9914 state goes in real-mode
9915 3. Currently only supported on i386 and x86_64.
9917 protocol: string
9919 the filename or file descriptor of the vmcore. The supported
9920 protocols are:
9921 1. file: the protocol starts with "file:", and the following
9923 string is the file's path.
9924 2. fd: the protocol starts with "fd:", and the following string
9926 is the fd's name.
9927 detach: boolean (optional)
9929 if true, QMP will return immediately rather than waiting for the
9930 dump to finish. The user can track progress using "query-dump".
9931 (since 2.6).
9932 begin: int (optional)
9934 if specified, the starting physical address.
9935 length: int (optional)
9937 if specified, the memory size, in bytes. If you don't want to
9938 dump all guest's memory, please specify the start begin and
9939 length
9940 format: DumpGuestMemoryFormat (optional)
9942 if specified, the format of guest memory dump. But non-elf for‐
9943 mat is conflict with paging and filter, ie. paging, begin and
9944 length is not allowed to be specified with non-elf format at the
9945 same time (since 2.0)
9946 Note
9948 All boolean arguments default to false
9949 Returns
9951 nothing on success
9952 Since
9954 1.2
9955 Example
9957 -> { "execute": "dump-guest-memory",
9958 "arguments": { "protocol": "fd:dump" } }
9959 <- { "return": {} }
9960 DumpStatus (Enum)
9962 Describe the status of a long-running background guest memory dump.
9963 Values
9965 none no dump-guest-memory has started yet.
9966 active there is one dump running in background.
9968 completed
9970 the last dump has finished successfully.
9971 failed the last dump has failed.
9973 Since
9975 2.6
9976 DumpQueryResult (Object)
9978 The result format for 'query-dump'.
9979 Members
9981 status: DumpStatus
9982 enum of DumpStatus, which shows current dump status
9983 completed: int
9985 bytes written in latest dump (uncompressed)
9986 total: int
9988 total bytes to be written in latest dump (uncompressed)
9989 Since
9991 2.6
9992 query-dump (Command)
9994 Query latest dump status.
9995 Returns
9997 A DumpStatus object showing the dump status.
9998 Since
10000 2.6
10001 Example
10003 -> { "execute": "query-dump" }
10004 <- { "return": { "status": "active", "completed": 1024000,
10005 "total": 2048000 } }
10006 DUMP_COMPLETED (Event)
10008 Emitted when background dump has completed
10009 Arguments
10011 result: DumpQueryResult
10012 final dump status
10013 error: string (optional)
10015 human-readable error string that provides hint on why dump
10016 failed. Only presents on failure. The user should not try to in‐
10017 terpret the error string.
10018 Since
10020 2.6
10021 Example
10023 { "event": "DUMP_COMPLETED",
10024 "data": {"result": {"total": 1090650112, "status": "completed",
10025 "completed": 1090650112} } }
10026 DumpGuestMemoryCapability (Object)
10028 A list of the available formats for dump-guest-memory
10029 Members
10031 formats: array of DumpGuestMemoryFormat
10032 Not documented
10033 Since
10035 2.0
10036 query-dump-guest-memory-capability (Command)
10038 Returns the available formats for dump-guest-memory
10039 Returns
10041 A DumpGuestMemoryCapability object listing available formats for
10042 dump-guest-memory
10043 Since
10045 2.0
10046 Example
10048 -> { "execute": "query-dump-guest-memory-capability" }
10049 <- { "return": { "formats":
10050 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
10051
10053 set_link (Command)
10054 Sets the link status of a virtual network adapter.
10055 Arguments
10057 name: string
10058 the device name of the virtual network adapter
10059 up: boolean
10061 true to set the link status to be up
10062 Returns
10064 Nothing on success If name is not a valid network device, DeviceNot‐
10065 Found
10066 Since
10068 0.14
10069 Notes
10071 Not all network adapters support setting link status. This command
10072 will succeed even if the network adapter does not support link status
10073 notification.
10074 Example
10076 -> { "execute": "set_link",
10077 "arguments": { "name": "e1000.0", "up": false } }
10078 <- { "return": {} }
10079 netdev_add (Command)
10081 Add a network backend.
10082 Additional arguments depend on the type.
10084 Arguments
10086 The members of Netdev
10087 Since
10089 0.14
10090 Returns
10092 Nothing on success If type is not a valid network backend, DeviceNot‐
10093 Found
10094 Example
10096 -> { "execute": "netdev_add",
10097 "arguments": { "type": "user", "id": "netdev1",
10098 "dnssearch": "example.org" } }
10099 <- { "return": {} }
10100 netdev_del (Command)
10102 Remove a network backend.
10103 Arguments
10105 id: string
10106 the name of the network backend to remove
10107 Returns
10109 Nothing on success If id is not a valid network backend, DeviceNotFound
10110 Since
10112 0.14
10113 Example
10115 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
10116 <- { "return": {} }
10117 NetLegacyNicOptions (Object)
10119 Create a new Network Interface Card.
10120 Members
10122 netdev: string (optional)
10123 id of -netdev to connect to
10124 macaddr: string (optional)
10126 MAC address
10127 model: string (optional)
10129 device model (e1000, rtl8139, virtio etc.)
10130 addr: string (optional)
10132 PCI device address
10133 vectors: int (optional)
10135 number of MSI-x vectors, 0 to disable MSI-X
10136 Since
10138 1.2
10139 NetdevUserOptions (Object)
10141 Use the user mode network stack which requires no administrator privi‐
10142 lege to run.
10143 Members
10145 hostname: string (optional)
10146 client hostname reported by the builtin DHCP server
10147 restrict: boolean (optional)
10149 isolate the guest from the host
10150 ipv4: boolean (optional)
10152 whether to support IPv4, default true for enabled (since 2.6)
10153 ipv6: boolean (optional)
10155 whether to support IPv6, default true for enabled (since 2.6)
10156 ip: string (optional)
10158 legacy parameter, use net= instead
10159 net: string (optional)
10161 IP network address that the guest will see, in the form
10162 addr[/netmask] The netmask is optional, and can be either in the
10163 form a.b.c.d or as a number of valid top-most bits. Default is
10164 10.0.2.0/24.
10165 host: string (optional)
10167 guest-visible address of the host
10168 tftp: string (optional)
10170 root directory of the built-in TFTP server
10171 bootfile: string (optional)
10173 BOOTP filename, for use with tftp=
10174 dhcpstart: string (optional)
10176 the first of the 16 IPs the built-in DHCP server can assign
10177 dns: string (optional)
10179 guest-visible address of the virtual nameserver
10180 dnssearch: array of String (optional)
10182 list of DNS suffixes to search, passed as DHCP option to the
10183 guest
10184 domainname: string (optional)
10186 guest-visible domain name of the virtual nameserver (since 3.0)
10187 ipv6-prefix: string (optional)
10189 IPv6 network prefix (default is fec0::) (since 2.6). The network
10190 prefix is given in the usual hexadecimal IPv6 address notation.
10191 ipv6-prefixlen: int (optional)
10193 IPv6 network prefix length (default is 64) (since 2.6)
10194 ipv6-host: string (optional)
10196 guest-visible IPv6 address of the host (since 2.6)
10197 ipv6-dns: string (optional)
10199 guest-visible IPv6 address of the virtual nameserver (since 2.6)
10200 smb: string (optional)
10202 root directory of the built-in SMB server
10203 smbserver: string (optional)
10205 IP address of the built-in SMB server
10206 hostfwd: array of String (optional)
10208 redirect incoming TCP or UDP host connections to guest endpoints
10209 guestfwd: array of String (optional)
10211 forward guest TCP connections
10212 tftp-server-name: string (optional)
10214 RFC2132 "TFTP server name" string (Since 3.1)
10215 Since
10217 1.2
10218 NetdevTapOptions (Object)
10220 Used to configure a host TAP network interface backend.
10221 Members
10223 ifname: string (optional)
10224 interface name
10225 fd: string (optional)
10227 file descriptor of an already opened tap
10228 fds: string (optional)
10230 multiple file descriptors of already opened multiqueue capable
10231 tap
10232 script: string (optional)
10234 script to initialize the interface
10235 downscript: string (optional)
10237 script to shut down the interface
10238 br: string (optional)
10240 bridge name (since 2.8)
10241 helper: string (optional)
10243 command to execute to configure bridge
10244 sndbuf: int (optional)
10246 send buffer limit. Understands [TGMKkb] suffixes.
10247 vnet_hdr: boolean (optional)
10249 enable the IFF_VNET_HDR flag on the tap interface
10250 vhost: boolean (optional)
10252 enable vhost-net network accelerator
10253 vhostfd: string (optional)
10255 file descriptor of an already opened vhost net device
10256 vhostfds: string (optional)
10258 file descriptors of multiple already opened vhost net devices
10259 vhostforce: boolean (optional)
10261 vhost on for non-MSIX virtio guests
10262 queues: int (optional)
10264 number of queues to be created for multiqueue capable tap
10265 poll-us: int (optional)
10267 maximum number of microseconds that could be spent on busy
10268 polling for tap (since 2.7)
10269 Since
10271 1.2
10272 NetdevSocketOptions (Object)
10274 Socket netdevs are used to establish a network connection to another
10275 QEMU virtual machine via a TCP socket.
10276 Members
10278 fd: string (optional)
10279 file descriptor of an already opened socket
10280 listen: string (optional)
10282 port number, and optional hostname, to listen on
10283 connect: string (optional)
10285 port number, and optional hostname, to connect to
10286 mcast: string (optional)
10288 UDP multicast address and port number
10289 localaddr: string (optional)
10291 source address and port for multicast and udp packets
10292 udp: string (optional)
10294 UDP unicast address and port number
10295 Since
10297 1.2
10298 NetdevL2TPv3Options (Object)
10300 Configure an Ethernet over L2TPv3 tunnel.
10301 Members
10303 src: string
10304 source address
10305 dst: string
10307 destination address
10308 srcport: string (optional)
10310 source port - mandatory for udp, optional for ip
10311 dstport: string (optional)
10313 destination port - mandatory for udp, optional for ip
10314 ipv6: boolean (optional)
10316 force the use of ipv6
10317 udp: boolean (optional)
10319 use the udp version of l2tpv3 encapsulation
10320 cookie64: boolean (optional)
10322 use 64 bit coookies
10323 counter: boolean (optional)
10325 have sequence counter
10326 pincounter: boolean (optional)
10328 pin sequence counter to zero - workaround for buggy implementa‐
10329 tions or networks with packet reorder
10330 txcookie: int (optional)
10332 32 or 64 bit transmit cookie
10333 rxcookie: int (optional)
10335 32 or 64 bit receive cookie
10336 txsession: int
10338 32 bit transmit session
10339 rxsession: int (optional)
10341 32 bit receive session - if not specified set to the same value
10342 as transmit
10343 offset: int (optional)
10345 additional offset - allows the insertion of additional applica‐
10346 tion-specific data before the packet payload
10347 Since
10349 2.1
10350 NetdevVdeOptions (Object)
10352 Connect to a vde switch running on the host.
10353 Members
10355 sock: string (optional)
10356 socket path
10357 port: int (optional)
10359 port number
10360 group: string (optional)
10362 group owner of socket
10363 mode: int (optional)
10365 permissions for socket
10366 Since
10368 1.2
10369 NetdevBridgeOptions (Object)
10371 Connect a host TAP network interface to a host bridge device.
10372 Members
10374 br: string (optional)
10375 bridge name
10376 helper: string (optional)
10378 command to execute to configure bridge
10379 Since
10381 1.2
10382 NetdevHubPortOptions (Object)
10384 Connect two or more net clients through a software hub.
10385 Members
10387 hubid: int
10388 hub identifier number
10389 netdev: string (optional)
10391 used to connect hub to a netdev instead of a device (since 2.12)
10392 Since
10394 1.2
10395 NetdevNetmapOptions (Object)
10397 Connect a client to a netmap-enabled NIC or to a VALE switch port
10398 Members
10400 ifname: string
10401 Either the name of an existing network interface supported by
10402 netmap, or the name of a VALE port (created on the fly). A VALE
10403 port name is in the form 'valeXXX:YYY', where XXX and YYY are
10404 non-negative integers. XXX identifies a switch and YYY identi‐
10405 fies a port of the switch. VALE ports having the same XXX are
10406 therefore connected to the same switch.
10407 devname: string (optional)
10409 path of the netmap device (default: '/dev/netmap').
10410 Since
10412 2.0
10413 NetdevVhostUserOptions (Object)
10415 Vhost-user network backend
10416 Members
10418 chardev: string
10419 name of a unix socket chardev
10420 vhostforce: boolean (optional)
10422 vhost on for non-MSIX virtio guests (default: false).
10423 queues: int (optional)
10425 number of queues to be created for multiqueue vhost-user (de‐
10426 fault: 1) (Since 2.5)
10427 Since
10429 2.1
10430 NetdevVhostVDPAOptions (Object)
10432 Vhost-vdpa network backend
10433 vDPA device is a device that uses a datapath which complies with the
10435 virtio specifications with a vendor specific control path.
10436 Members
10438 vhostdev: string (optional)
10439 path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
10440 queues: int (optional)
10442 number of queues to be created for multiqueue vhost-vdpa (de‐
10443 fault: 1)
10444 Since
10446 5.1
10447 NetClientDriver (Enum)
10449 Available netdev drivers.
10450 Values
10452 none Not documented
10453 nic Not documented
10455 user Not documented
10457 tap Not documented
10459 l2tpv3 Not documented
10461 socket Not documented
10463 vde Not documented
10465 bridge Not documented
10467 hubport
10469 Not documented
10470 netmap Not documented
10472 vhost-user
10474 Not documented
10475 vhost-vdpa
10477 Not documented
10478 Since
10480 2.7
10481 vhost-vdpa since 5.1
10483 Netdev (Object)
10485 Captures the configuration of a network device.
10486 Members
10488 id: string
10489 identifier for monitor commands.
10490 type: NetClientDriver
10492 Specify the driver used for interpreting remaining arguments.
10493 The members of NetLegacyNicOptions when type is "nic"
10495 The members of NetdevUserOptions when type is "user"
10497 The members of NetdevTapOptions when type is "tap"
10499 The members of NetdevL2TPv3Options when type is "l2tpv3"
10501 The members of NetdevSocketOptions when type is "socket"
10503 The members of NetdevVdeOptions when type is "vde"
10505 The members of NetdevBridgeOptions when type is "bridge"
10507 The members of NetdevHubPortOptions when type is "hubport"
10509 The members of NetdevNetmapOptions when type is "netmap"
10511 The members of NetdevVhostUserOptions when type is "vhost-user"
10513 The members of NetdevVhostVDPAOptions when type is "vhost-vdpa"
10515 Since
10517 1.2
10518 'l2tpv3' - since 2.1
10520 RxState (Enum)
10522 Packets receiving state
10523 Values
10525 normal filter assigned packets according to the mac-table
10526 none don't receive any assigned packet
10528 all receive all assigned packets
10530 Since
10532 1.6
10533 RxFilterInfo (Object)
10535 Rx-filter information for a NIC.
10536 Members
10538 name: string
10539 net client name
10540 promiscuous: boolean
10542 whether promiscuous mode is enabled
10543 multicast: RxState
10545 multicast receive state
10546 unicast: RxState
10548 unicast receive state
10549 vlan: RxState
10551 vlan receive state (Since 2.0)
10552 broadcast-allowed: boolean
10554 whether to receive broadcast
10555 multicast-overflow: boolean
10557 multicast table is overflowed or not
10558 unicast-overflow: boolean
10560 unicast table is overflowed or not
10561 main-mac: string
10563 the main macaddr string
10564 vlan-table: array of int
10566 a list of active vlan id
10567 unicast-table: array of string
10569 a list of unicast macaddr string
10570 multicast-table: array of string
10572 a list of multicast macaddr string
10573 Since
10575 1.6
10576 query-rx-filter (Command)
10578 Return rx-filter information for all NICs (or for the given NIC).
10579 Arguments
10581 name: string (optional)
10582 net client name
10583 Returns
10585 list of RxFilterInfo for all NICs (or for the given NIC). Returns an
10586 error if the given name doesn't exist, or given NIC doesn't support
10587 rx-filter querying, or given net client isn't a NIC.
10588 Since
10590 1.6
10591 Example
10593 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
10594 <- { "return": [
10595 {
10596 "promiscuous": true,
10597 "name": "vnet0",
10598 "main-mac": "52:54:00:12:34:56",
10599 "unicast": "normal",
10600 "vlan": "normal",
10601 "vlan-table": [
10602 4,
10603 0
10604 ],
10605 "unicast-table": [
10606 ],
10607 "multicast": "normal",
10608 "multicast-overflow": false,
10609 "unicast-overflow": false,
10610 "multicast-table": [
10611 "01:00:5e:00:00:01",
10612 "33:33:00:00:00:01",
10613 "33:33:ff:12:34:56"
10614 ],
10615 "broadcast-allowed": false
10616 }
10617 ]
10618 }
10619 NIC_RX_FILTER_CHANGED (Event)
10621 Emitted once until the 'query-rx-filter' command is executed, the first
10622 event will always be emitted
10623 Arguments
10625 name: string (optional)
10626 net client name
10627 path: string
10629 device path
10630 Since
10632 1.6
10633 Example
10635 <- { "event": "NIC_RX_FILTER_CHANGED",
10636 "data": { "name": "vnet0",
10637 "path": "/machine/peripheral/vnet0/virtio-backend" },
10638 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
10639 }
10640 AnnounceParameters (Object)
10642 Parameters for self-announce timers
10643 Members
10645 initial: int
10646 Initial delay (in ms) before sending the first GARP/RARP an‐
10647 nouncement
10648 max: int
10650 Maximum delay (in ms) between GARP/RARP announcement packets
10651 rounds: int
10653 Number of self-announcement attempts
10654 step: int
10656 Delay increase (in ms) after each self-announcement attempt
10657 interfaces: array of string (optional)
10659 An optional list of interface names, which restricts the an‐
10660 nouncement to the listed interfaces. (Since 4.1)
10661 id: string (optional)
10663 A name to be used to identify an instance of announce-timers and
10664 to allow it to modified later. Not for use as part of the mi‐
10665 gration parameters. (Since 4.1)
10666 Since
10668 4.0
10669 announce-self (Command)
10671 Trigger generation of broadcast RARP frames to update network switches.
10672 This can be useful when network bonds fail-over the active slave.
10673 Arguments
10675 The members of AnnounceParameters
10676 Example
10678 -> { "execute": "announce-self",
10679 "arguments": {
10680 "initial": 50, "max": 550, "rounds": 10, "step": 50,
10681 "interfaces": ["vn2", "vn3"], "id": "bob" } }
10682 <- { "return": {} }
10683 Since
10685 4.0
10686 FAILOVER_NEGOTIATED (Event)
10688 Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotia‐
10689 tion. Failover primary devices which were hidden (not hotplugged when
10690 requested) before will now be hotplugged by the virtio-net standby de‐
10691 vice.
10692 device-id: QEMU device id of the unplugged device
10694 Arguments
10696 device-id: string
10697 Not documented
10698 Since
10700 4.2
10701 Example
10703 <- { "event": "FAILOVER_NEGOTIATED",
10704 "data": "net1" }
10705
10707 RDMA_GID_STATUS_CHANGED (Event)
10708 Emitted when guest driver adds/deletes GID to/from device
10709 Arguments
10711 netdev: string
10712 RoCE Network Device name
10713 gid-status: boolean
10715 Add or delete indication
10716 subnet-prefix: int
10718 Subnet Prefix
10719 interface-id: int
10721 Not documented
10722 interface-id : Interface ID
10723 Since
10725 4.0
10726 Example
10728 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
10729 "event": "RDMA_GID_STATUS_CHANGED",
10730 "data":
10731 {"netdev": "bridge0",
10732 "interface-id": 15880512517475447892,
10733 "gid-status": true,
10734 "subnet-prefix": 33022}}
10735
10737 RockerSwitch (Object)
10738 Rocker switch information.
10739 Members
10741 name: string
10742 switch name
10743 id: int
10745 switch ID
10746 ports: int
10748 number of front-panel ports
10749 Since
10751 2.4
10752 query-rocker (Command)
10754 Return rocker switch information.
10755 Arguments
10757 name: string
10758 Not documented
10759 Returns
10761 Rocker information
10762 Since
10764 2.4
10765 Example
10767 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
10768 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
10769 RockerPortDuplex (Enum)
10771 An eumeration of port duplex states.
10772 Values
10774 half half duplex
10775 full full duplex
10777 Since
10779 2.4
10780 RockerPortAutoneg (Enum)
10782 An eumeration of port autoneg states.
10783 Values
10785 off autoneg is off
10786 on autoneg is on
10788 Since
10790 2.4
10791 RockerPort (Object)
10793 Rocker switch port information.
10794 Members
10796 name: string
10797 port name
10798 enabled: boolean
10800 port is enabled for I/O
10801 link-up: boolean
10803 physical link is UP on port
10804 speed: int
10806 port link speed in Mbps
10807 duplex: RockerPortDuplex
10809 port link duplex
10810 autoneg: RockerPortAutoneg
10812 port link autoneg
10813 Since
10815 2.4
10816 query-rocker-ports (Command)
10818 Return rocker switch port information.
10819 Arguments
10821 name: string
10822 Not documented
10823 Returns
10825 a list of RockerPort information
10826 Since
10828 2.4
10829 Example
10831 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
10832 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
10833 "autoneg": "off", "link-up": true, "speed": 10000},
10834 {"duplex": "full", "enabled": true, "name": "sw1.2",
10835 "autoneg": "off", "link-up": true, "speed": 10000}
10836 ]}
10837 RockerOfDpaFlowKey (Object)
10839 Rocker switch OF-DPA flow key
10840 Members
10842 priority: int
10843 key priority, 0 being lowest priority
10844 tbl-id: int
10846 flow table ID
10847 in-pport: int (optional)
10849 physical input port
10850 tunnel-id: int (optional)
10852 tunnel ID
10853 vlan-id: int (optional)
10855 VLAN ID
10856 eth-type: int (optional)
10858 Ethernet header type
10859 eth-src: string (optional)
10861 Ethernet header source MAC address
10862 eth-dst: string (optional)
10864 Ethernet header destination MAC address
10865 ip-proto: int (optional)
10867 IP Header protocol field
10868 ip-tos: int (optional)
10870 IP header TOS field
10871 ip-dst: string (optional)
10873 IP header destination address
10874 Note
10876 optional members may or may not appear in the flow key depending if
10877 they're relevant to the flow key.
10878 Since
10880 2.4
10881 RockerOfDpaFlowMask (Object)
10883 Rocker switch OF-DPA flow mask
10884 Members
10886 in-pport: int (optional)
10887 physical input port
10888 tunnel-id: int (optional)
10890 tunnel ID
10891 vlan-id: int (optional)
10893 VLAN ID
10894 eth-src: string (optional)
10896 Ethernet header source MAC address
10897 eth-dst: string (optional)
10899 Ethernet header destination MAC address
10900 ip-proto: int (optional)
10902 IP Header protocol field
10903 ip-tos: int (optional)
10905 IP header TOS field
10906 Note
10908 optional members may or may not appear in the flow mask depending if
10909 they're relevant to the flow mask.
10910 Since
10912 2.4
10913 RockerOfDpaFlowAction (Object)
10915 Rocker switch OF-DPA flow action
10916 Members
10918 goto-tbl: int (optional)
10919 next table ID
10920 group-id: int (optional)
10922 group ID
10923 tunnel-lport: int (optional)
10925 tunnel logical port ID
10926 vlan-id: int (optional)
10928 VLAN ID
10929 new-vlan-id: int (optional)
10931 new VLAN ID
10932 out-pport: int (optional)
10934 physical output port
10935 Note
10937 optional members may or may not appear in the flow action depending if
10938 they're relevant to the flow action.
10939 Since
10941 2.4
10942 RockerOfDpaFlow (Object)
10944 Rocker switch OF-DPA flow
10945 Members
10947 cookie: int
10948 flow unique cookie ID
10949 hits: int
10951 count of matches (hits) on flow
10952 key: RockerOfDpaFlowKey
10954 flow key
10955 mask: RockerOfDpaFlowMask
10957 flow mask
10958 action: RockerOfDpaFlowAction
10960 flow action
10961 Since
10963 2.4
10964 query-rocker-of-dpa-flows (Command)
10966 Return rocker OF-DPA flow information.
10967 Arguments
10969 name: string
10970 switch name
10971 tbl-id: int (optional)
10973 flow table ID. If tbl-id is not specified, returns flow infor‐
10974 mation for all tables.
10975 Returns
10977 rocker OF-DPA flow information
10978 Since
10980 2.4
10981 Example
10983 -> { "execute": "query-rocker-of-dpa-flows",
10984 "arguments": { "name": "sw1" } }
10985 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
10986 "hits": 138,
10987 "cookie": 0,
10988 "action": {"goto-tbl": 10},
10989 "mask": {"in-pport": 4294901760}
10990 },
10991 {...more...},
10992 ]}
10993 RockerOfDpaGroup (Object)
10995 Rocker switch OF-DPA group
10996 Members
10998 id: int
10999 group unique ID
11000 type: int
11002 group type
11003 vlan-id: int (optional)
11005 VLAN ID
11006 pport: int (optional)
11008 physical port number
11009 index: int (optional)
11011 group index, unique with group type
11012 out-pport: int (optional)
11014 output physical port number
11015 group-id: int (optional)
11017 next group ID
11018 set-vlan-id: int (optional)
11020 VLAN ID to set
11021 pop-vlan: int (optional)
11023 pop VLAN headr from packet
11024 group-ids: array of int (optional)
11026 list of next group IDs
11027 set-eth-src: string (optional)
11029 set source MAC address in Ethernet header
11030 set-eth-dst: string (optional)
11032 set destination MAC address in Ethernet header
11033 ttl-check: int (optional)
11035 perform TTL check
11036 Note
11038 optional members may or may not appear in the group depending if
11039 they're relevant to the group type.
11040 Since
11042 2.4
11043 query-rocker-of-dpa-groups (Command)
11045 Return rocker OF-DPA group information.
11046 Arguments
11048 name: string
11049 switch name
11050 type: int (optional)
11052 group type. If type is not specified, returns group information
11053 for all group types.
11054 Returns
11056 rocker OF-DPA group information
11057 Since
11059 2.4
11060 Example
11062 -> { "execute": "query-rocker-of-dpa-groups",
11063 "arguments": { "name": "sw1" } }
11064 <- { "return": [ {"type": 0, "out-pport": 2,
11065 "pport": 2, "vlan-id": 3841,
11066 "pop-vlan": 1, "id": 251723778},
11067 {"type": 0, "out-pport": 0,
11068 "pport": 0, "vlan-id": 3841,
11069 "pop-vlan": 1, "id": 251723776},
11070 {"type": 0, "out-pport": 1,
11071 "pport": 1, "vlan-id": 3840,
11072 "pop-vlan": 1, "id": 251658241},
11073 {"type": 0, "out-pport": 0,
11074 "pport": 0, "vlan-id": 3840,
11075 "pop-vlan": 1, "id": 251658240}
11076 ]}
11077
11079 TpmModel (Enum)
11080 An enumeration of TPM models
11081 Values
11083 tpm-tis
11084 TPM TIS model
11085 tpm-crb
11087 TPM CRB model (since 2.12)
11088 tpm-spapr
11090 TPM SPAPR model (since 5.0)
11091 Since
11093 1.5
11094 If
11096 defined(CONFIG_TPM)
11097 query-tpm-models (Command)
11099 Return a list of supported TPM models
11100 Returns
11102 a list of TpmModel
11103 Since
11105 1.5
11106 Example
11108 -> { "execute": "query-tpm-models" }
11109 <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
11110 If
11112 defined(CONFIG_TPM)
11113 TpmType (Enum)
11115 An enumeration of TPM types
11116 Values
11118 passthrough
11119 TPM passthrough type
11120 emulator
11122 Software Emulator TPM type Since: 2.11
11123 Since
11125 1.5
11126 If
11128 defined(CONFIG_TPM)
11129 query-tpm-types (Command)
11131 Return a list of supported TPM types
11132 Returns
11134 a list of TpmType
11135 Since
11137 1.5
11138 Example
11140 -> { "execute": "query-tpm-types" }
11141 <- { "return": [ "passthrough", "emulator" ] }
11142 If
11144 defined(CONFIG_TPM)
11145 TPMPassthroughOptions (Object)
11147 Information about the TPM passthrough type
11148 Members
11150 path: string (optional)
11151 string describing the path used for accessing the TPM device
11152 cancel-path: string (optional)
11154 string showing the TPM's sysfs cancel file for cancellation of
11155 TPM commands while they are executing
11156 Since
11158 1.5
11159 If
11161 defined(CONFIG_TPM)
11162 TPMEmulatorOptions (Object)
11164 Information about the TPM emulator type
11165 Members
11167 chardev: string
11168 Name of a unix socket chardev
11169 Since
11171 2.11
11172 If
11174 defined(CONFIG_TPM)
11175 TpmTypeOptions (Object)
11177 A union referencing different TPM backend types' configuration options
11178 Members
11180 type
11181 • 'passthrough' The configuration options for the TPM
11183 passthrough type
11184 • 'emulator' The configuration options for TPM emulator backend
11186 type
11187 data: TPMPassthroughOptions when type is "passthrough"
11189 data: TPMEmulatorOptions when type is "emulator"
11191 Since
11193 1.5
11194 If
11196 defined(CONFIG_TPM)
11197 TPMInfo (Object)
11199 Information about the TPM
11200 Members
11202 id: string
11203 The Id of the TPM
11204 model: TpmModel
11206 The TPM frontend model
11207 options: TpmTypeOptions
11209 The TPM (backend) type configuration options
11210 Since
11212 1.5
11213 If
11215 defined(CONFIG_TPM)
11216 query-tpm (Command)
11218 Return information about the TPM device
11219 Returns
11221 TPMInfo on success
11222 Since
11224 1.5
11225 Example
11227 -> { "execute": "query-tpm" }
11228 <- { "return":
11229 [
11230 { "model": "tpm-tis",
11231 "options":
11232 { "type": "passthrough",
11233 "data":
11234 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
11235 "path": "/dev/tpm0"
11236 }
11237 },
11238 "id": "tpm0"
11239 }
11240 ]
11241 }
11242 If
11244 defined(CONFIG_TPM)
11245
11247 set_password (Command)
11248 Sets the password of a remote display session.
11249 Arguments
11251 protocol: string
11252 • 'vnc' to modify the VNC server password
11254 • 'spice' to modify the Spice server password
11256 password: string
11258 the new password
11259 connected: string (optional)
11261 how to handle existing clients when changing the password. If
11262 nothing is specified, defaults to 'keep' 'fail' to fail the com‐
11263 mand if clients are connected 'disconnect' to disconnect exist‐
11264 ing clients 'keep' to maintain existing clients
11265 Returns
11267 • Nothing on success
11268 • If Spice is not enabled, DeviceNotFound
11270 Since
11272 0.14
11273 Example
11275 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
11276 "password": "secret" } }
11277 <- { "return": {} }
11278 expire_password (Command)
11280 Expire the password of a remote display server.
11281 Arguments
11283 protocol: string
11284 the name of the remote display protocol 'vnc' or 'spice'
11285 time: string
11287 when to expire the password.
11288 • 'now' to expire the password immediately
11290 • 'never' to cancel password expiration
11292 • '+INT' where INT is the number of seconds from now (integer)
11294 • 'INT' where INT is the absolute time in seconds
11296 Returns
11298 • Nothing on success
11299 • If protocol is 'spice' and Spice is not active, DeviceNotFound
11301 Since
11303 0.14
11304 Notes
11306 Time is relative to the server and currently there is no way to coordi‐
11307 nate server time with client time. It is not recommended to use the
11308 absolute time version of the time parameter unless you're sure you are
11309 on the same machine as the QEMU instance.
11310 Example
11312 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
11313 "time": "+60" } }
11314 <- { "return": {} }
11315 screendump (Command)
11317 Write a PPM of the VGA screen to a file.
11318 Arguments
11320 filename: string
11321 the path of a new PPM file to store the image
11322 device: string (optional)
11324 ID of the display device that should be dumped. If this parame‐
11325 ter is missing, the primary display will be used. (Since 2.12)
11326 head: int (optional)
11328 head to use in case the device supports multiple heads. If this
11329 parameter is missing, head #0 will be used. Also note that the
11330 head can only be specified in conjunction with the device ID.
11331 (Since 2.12)
11332 Returns
11334 Nothing on success
11335 Since
11337 0.14
11338 Example
11340 -> { "execute": "screendump",
11341 "arguments": { "filename": "/tmp/image" } }
11342 <- { "return": {} }
11343 Spice
11345 SpiceBasicInfo (Object)
11346 The basic information for SPICE network connection
11347 Members
11349 host: string
11350 IP address
11351 port: string
11353 port number
11354 family: NetworkAddressFamily
11356 address family
11357 Since
11359 2.1
11360 If
11362 defined(CONFIG_SPICE)
11363 SpiceServerInfo (Object)
11365 Information about a SPICE server
11366 Members
11368 auth: string (optional)
11369 authentication method
11370 The members of SpiceBasicInfo
11372 Since
11374 2.1
11375 If
11377 defined(CONFIG_SPICE)
11378 SpiceChannel (Object)
11380 Information about a SPICE client channel.
11381 Members
11383 connection-id: int
11384 SPICE connection id number. All channels with the same id be‐
11385 long to the same SPICE session.
11386 channel-type: int
11388 SPICE channel type number. "1" is the main control channel,
11389 filter for this one if you want to track spice sessions only
11390 channel-id: int
11392 SPICE channel ID number. Usually "0", might be different when
11393 multiple channels of the same type exist, such as multiple dis‐
11394 play channels in a multihead setup
11395 tls: boolean
11397 true if the channel is encrypted, false otherwise.
11398 The members of SpiceBasicInfo
11400 Since
11402 0.14
11403 If
11405 defined(CONFIG_SPICE)
11406 SpiceQueryMouseMode (Enum)
11408 An enumeration of Spice mouse states.
11409 Values
11411 client Mouse cursor position is determined by the client.
11412 server Mouse cursor position is determined by the server.
11414 unknown
11416 No information is available about mouse mode used by the spice
11417 server.
11418 Note
11420 spice/enums.h has a SpiceMouseMode already, hence the name.
11421 Since
11423 1.1
11424 If
11426 defined(CONFIG_SPICE)
11427 SpiceInfo (Object)
11429 Information about the SPICE session.
11430 Members
11432 enabled: boolean
11433 true if the SPICE server is enabled, false otherwise
11434 migrated: boolean
11436 true if the last guest migration completed and spice migration
11437 had completed as well. false otherwise. (since 1.4)
11438 host: string (optional)
11440 The hostname the SPICE server is bound to. This depends on the
11441 name resolution on the host and may be an IP address.
11442 port: int (optional)
11444 The SPICE server's port number.
11445 compiled-version: string (optional)
11447 SPICE server version.
11448 tls-port: int (optional)
11450 The SPICE server's TLS port number.
11451 auth: string (optional)
11453 the current authentication type used by the server
11454 • 'none' if no authentication is being used
11456 • 'spice' uses SASL or direct TLS authentication, depending on
11458 command line options
11459 mouse-mode: SpiceQueryMouseMode
11461 The mode in which the mouse cursor is displayed currently. Can
11462 be determined by the client or the server, or unknown if spice
11463 server doesn't provide this information. (since: 1.1)
11464 channels: array of SpiceChannel (optional)
11466 a list of SpiceChannel for each active spice channel
11467 Since
11469 0.14
11470 If
11472 defined(CONFIG_SPICE)
11473 query-spice (Command)
11475 Returns information about the current SPICE server
11476 Returns
11478 SpiceInfo
11479 Since
11481 0.14
11482 Example
11484 -> { "execute": "query-spice" }
11485 <- { "return": {
11486 "enabled": true,
11487 "auth": "spice",
11488 "port": 5920,
11489 "tls-port": 5921,
11490 "host": "0.0.0.0",
11491 "channels": [
11492 {
11493 "port": "54924",
11494 "family": "ipv4",
11495 "channel-type": 1,
11496 "connection-id": 1804289383,
11497 "host": "127.0.0.1",
11498 "channel-id": 0,
11499 "tls": true
11500 },
11501 {
11502 "port": "36710",
11503 "family": "ipv4",
11504 "channel-type": 4,
11505 "connection-id": 1804289383,
11506 "host": "127.0.0.1",
11507 "channel-id": 0,
11508 "tls": false
11509 },
11510 [ ... more channels follow ... ]
11511 ]
11512 }
11513 }
11514 If
11516 defined(CONFIG_SPICE)
11517 SPICE_CONNECTED (Event)
11519 Emitted when a SPICE client establishes a connection
11520 Arguments
11522 server: SpiceBasicInfo
11523 server information
11524 client: SpiceBasicInfo
11526 client information
11527 Since
11529 0.14
11530 Example
11532 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
11533 "event": "SPICE_CONNECTED",
11534 "data": {
11535 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
11536 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
11537 }}
11538 If
11540 defined(CONFIG_SPICE)
11541 SPICE_INITIALIZED (Event)
11543 Emitted after initial handshake and authentication takes place (if any)
11544 and the SPICE channel is up and running
11545 Arguments
11547 server: SpiceServerInfo
11548 server information
11549 client: SpiceChannel
11551 client information
11552 Since
11554 0.14
11555 Example
11557 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
11558 "event": "SPICE_INITIALIZED",
11559 "data": {"server": {"auth": "spice", "port": "5921",
11560 "family": "ipv4", "host": "127.0.0.1"},
11561 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
11562 "connection-id": 1804289383, "host": "127.0.0.1",
11563 "channel-id": 0, "tls": true}
11564 }}
11565 If
11567 defined(CONFIG_SPICE)
11568 SPICE_DISCONNECTED (Event)
11570 Emitted when the SPICE connection is closed
11571 Arguments
11573 server: SpiceBasicInfo
11574 server information
11575 client: SpiceBasicInfo
11577 client information
11578 Since
11580 0.14
11581 Example
11583 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
11584 "event": "SPICE_DISCONNECTED",
11585 "data": {
11586 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
11587 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
11588 }}
11589 If
11591 defined(CONFIG_SPICE)
11592 SPICE_MIGRATE_COMPLETED (Event)
11594 Emitted when SPICE migration has completed
11595 Since
11597 1.3
11598 Example
11600 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
11601 "event": "SPICE_MIGRATE_COMPLETED" }
11602 If
11604 defined(CONFIG_SPICE)
11605 VNC
11607 VncBasicInfo (Object)
11608 The basic information for vnc network connection
11609 Members
11611 host: string
11612 IP address
11613 service: string
11615 The service name of the vnc port. This may depend on the host
11616 system's service database so symbolic names should not be relied
11617 on.
11618 family: NetworkAddressFamily
11620 address family
11621 websocket: boolean
11623 true in case the socket is a websocket (since 2.3).
11624 Since
11626 2.1
11627 If
11629 defined(CONFIG_VNC)
11630 VncServerInfo (Object)
11632 The network connection information for server
11633 Members
11635 auth: string (optional)
11636 authentication method used for the plain (non-websocket) VNC
11637 server
11638 The members of VncBasicInfo
11640 Since
11642 2.1
11643 If
11645 defined(CONFIG_VNC)
11646 VncClientInfo (Object)
11648 Information about a connected VNC client.
11649 Members
11651 x509_dname: string (optional)
11652 If x509 authentication is in use, the Distinguished Name of the
11653 client.
11654 sasl_username: string (optional)
11656 If SASL authentication is in use, the SASL username used for au‐
11657 thentication.
11658 The members of VncBasicInfo
11660 Since
11662 0.14
11663 If
11665 defined(CONFIG_VNC)
11666 VncInfo (Object)
11668 Information about the VNC session.
11669 Members
11671 enabled: boolean
11672 true if the VNC server is enabled, false otherwise
11673 host: string (optional)
11675 The hostname the VNC server is bound to. This depends on the
11676 name resolution on the host and may be an IP address.
11677 family: NetworkAddressFamily (optional)
11679 • 'ipv6' if the host is listening for IPv6 connections
11681 • 'ipv4' if the host is listening for IPv4 connections
11683 • 'unix' if the host is listening on a unix domain socket
11685 • 'unknown' otherwise
11687 service: string (optional)
11689 The service name of the server's port. This may depends on the
11690 host system's service database so symbolic names should not be
11691 relied on.
11692 auth: string (optional)
11694 the current authentication type used by the server
11695 • 'none' if no authentication is being used
11697 • 'vnc' if VNC authentication is being used
11699 • 'vencrypt+plain' if VEncrypt is used with plain text authenti‐
11701 cation
11702 • 'vencrypt+tls+none' if VEncrypt is used with TLS and no au‐
11704 thentication
11705 • 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC au‐
11707 thentication
11708 • 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain
11710 text auth
11711 • 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
11713 • 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
11715 • 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain
11717 text auth
11718 • 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
11720 • 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
11722 auth
11723 clients: array of VncClientInfo (optional)
11725 a list of VncClientInfo of all currently connected clients
11726 Since
11728 0.14
11729 If
11731 defined(CONFIG_VNC)
11732 VncPrimaryAuth (Enum)
11734 vnc primary authentication method.
11735 Values
11737 none Not documented
11738 vnc Not documented
11740 ra2 Not documented
11742 ra2ne Not documented
11744 tight Not documented
11746 ultra Not documented
11748 tls Not documented
11750 vencrypt
11752 Not documented
11753 sasl Not documented
11755 Since
11757 2.3
11758 If
11760 defined(CONFIG_VNC)
11761 VncVencryptSubAuth (Enum)
11763 vnc sub authentication method with vencrypt.
11764 Values
11766 plain Not documented
11767 tls-none
11769 Not documented
11770 x509-none
11772 Not documented
11773 tls-vnc
11775 Not documented
11776 x509-vnc
11778 Not documented
11779 tls-plain
11781 Not documented
11782 x509-plain
11784 Not documented
11785 tls-sasl
11787 Not documented
11788 x509-sasl
11790 Not documented
11791 Since
11793 2.3
11794 If
11796 defined(CONFIG_VNC)
11797 VncServerInfo2 (Object)
11799 The network connection information for server
11800 Members
11802 auth: VncPrimaryAuth
11803 The current authentication type used by the servers
11804 vencrypt: VncVencryptSubAuth (optional)
11806 The vencrypt sub authentication type used by the servers, only
11807 specified in case auth == vencrypt.
11808 The members of VncBasicInfo
11810 Since
11812 2.9
11813 If
11815 defined(CONFIG_VNC)
11816 VncInfo2 (Object)
11818 Information about a vnc server
11819 Members
11821 id: string
11822 vnc server name.
11823 server: array of VncServerInfo2
11825 A list of VncBasincInfo describing all listening sockets. The
11826 list can be empty (in case the vnc server is disabled). It also
11827 may have multiple entries: normal + websocket, possibly also
11828 ipv4 + ipv6 in the future.
11829 clients: array of VncClientInfo
11831 A list of VncClientInfo of all currently connected clients. The
11832 list can be empty, for obvious reasons.
11833 auth: VncPrimaryAuth
11835 The current authentication type used by the non-websockets
11836 servers
11837 vencrypt: VncVencryptSubAuth (optional)
11839 The vencrypt authentication type used by the servers, only spec‐
11840 ified in case auth == vencrypt.
11841 display: string (optional)
11843 The display device the vnc server is linked to.
11844 Since
11846 2.3
11847 If
11849 defined(CONFIG_VNC)
11850 query-vnc (Command)
11852 Returns information about the current VNC server
11853 Returns
11855 VncInfo
11856 Since
11858 0.14
11859 Example
11861 -> { "execute": "query-vnc" }
11862 <- { "return": {
11863 "enabled":true,
11864 "host":"0.0.0.0",
11865 "service":"50402",
11866 "auth":"vnc",
11867 "family":"ipv4",
11868 "clients":[
11869 {
11870 "host":"127.0.0.1",
11871 "service":"50401",
11872 "family":"ipv4"
11873 }
11874 ]
11875 }
11876 }
11877 If
11879 defined(CONFIG_VNC)
11880 query-vnc-servers (Command)
11882 Returns a list of vnc servers. The list can be empty.
11883 Returns
11885 a list of VncInfo2
11886 Since
11888 2.3
11889 If
11891 defined(CONFIG_VNC)
11892 change-vnc-password (Command)
11894 Change the VNC server password.
11895 Arguments
11897 password: string
11898 the new password to use with VNC authentication
11899 Since
11901 1.1
11902 Notes
11904 An empty password in this command will set the password to the empty
11905 string. Existing clients are unaffected by executing this command.
11906 If
11908 defined(CONFIG_VNC)
11909 VNC_CONNECTED (Event)
11911 Emitted when a VNC client establishes a connection
11912 Arguments
11914 server: VncServerInfo
11915 server information
11916 client: VncBasicInfo
11918 client information
11919 Note
11921 This event is emitted before any authentication takes place, thus the
11922 authentication ID is not provided
11923 Since
11925 0.13
11926 Example
11928 <- { "event": "VNC_CONNECTED",
11929 "data": {
11930 "server": { "auth": "sasl", "family": "ipv4",
11931 "service": "5901", "host": "0.0.0.0" },
11932 "client": { "family": "ipv4", "service": "58425",
11933 "host": "127.0.0.1" } },
11934 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
11935 If
11937 defined(CONFIG_VNC)
11938 VNC_INITIALIZED (Event)
11940 Emitted after authentication takes place (if any) and the VNC session
11941 is made active
11942 Arguments
11944 server: VncServerInfo
11945 server information
11946 client: VncClientInfo
11948 client information
11949 Since
11951 0.13
11952 Example
11954 <- { "event": "VNC_INITIALIZED",
11955 "data": {
11956 "server": { "auth": "sasl", "family": "ipv4",
11957 "service": "5901", "host": "0.0.0.0"},
11958 "client": { "family": "ipv4", "service": "46089",
11959 "host": "127.0.0.1", "sasl_username": "luiz" } },
11960 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
11961 If
11963 defined(CONFIG_VNC)
11964 VNC_DISCONNECTED (Event)
11966 Emitted when the connection is closed
11967 Arguments
11969 server: VncServerInfo
11970 server information
11971 client: VncClientInfo
11973 client information
11974 Since
11976 0.13
11977 Example
11979 <- { "event": "VNC_DISCONNECTED",
11980 "data": {
11981 "server": { "auth": "sasl", "family": "ipv4",
11982 "service": "5901", "host": "0.0.0.0" },
11983 "client": { "family": "ipv4", "service": "58425",
11984 "host": "127.0.0.1", "sasl_username": "luiz" } },
11985 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
11986 If
11988 defined(CONFIG_VNC)
11989
11991 MouseInfo (Object)
11992 Information about a mouse device.
11993 Members
11995 name: string
11996 the name of the mouse device
11997 index: int
11999 the index of the mouse device
12000 current: boolean
12002 true if this device is currently receiving mouse events
12003 absolute: boolean
12005 true if this device supports absolute coordinates as input
12006 Since
12008 0.14
12009 query-mice (Command)
12011 Returns information about each active mouse device
12012 Returns
12014 a list of MouseInfo for each device
12015 Since
12017 0.14
12018 Example
12020 -> { "execute": "query-mice" }
12021 <- { "return": [
12022 {
12023 "name":"QEMU Microsoft Mouse",
12024 "index":0,
12025 "current":false,
12026 "absolute":false
12027 },
12028 {
12029 "name":"QEMU PS/2 Mouse",
12030 "index":1,
12031 "current":true,
12032 "absolute":true
12033 }
12034 ]
12035 }
12036 QKeyCode (Enum)
12038 An enumeration of key name.
12039 This is used by the send-key command.
12041 Values
12043 unmapped
12044 since 2.0
12045 pause since 2.0
12047 ro since 2.4
12049 kp_comma
12051 since 2.4
12052 kp_equals
12054 since 2.6
12055 power since 2.6
12057 hiragana
12059 since 2.9
12060 henkan since 2.9
12062 yen since 2.9
12064 sleep since 2.10
12066 wake since 2.10
12068 audionext
12070 since 2.10
12071 audioprev
12073 since 2.10
12074 audiostop
12076 since 2.10
12077 audioplay
12079 since 2.10
12080 audiomute
12082 since 2.10
12083 volumeup
12085 since 2.10
12086 volumedown
12088 since 2.10
12089 mediaselect
12091 since 2.10
12092 mail since 2.10
12094 calculator
12096 since 2.10
12097 computer
12099 since 2.10
12100 ac_home
12102 since 2.10
12103 ac_back
12105 since 2.10
12106 ac_forward
12108 since 2.10
12109 ac_refresh
12111 since 2.10
12112 ac_bookmarks
12114 since 2.10
12115 muhenkan
12117 since 2.12
12118 katakanahiragana
12120 since 2.12
12121 lang1 since 6.1
12123 lang2 since 6.1
12125 shift Not documented
12127 shift_r
12129 Not documented
12130 alt Not documented
12132 alt_r Not documented
12134 ctrl Not documented
12136 ctrl_r Not documented
12138 menu Not documented
12140 esc Not documented
12142 1 Not documented
12144 2 Not documented
12146 3 Not documented
12148 4 Not documented
12150 5 Not documented
12152 6 Not documented
12154 7 Not documented
12156 8 Not documented
12158 9 Not documented
12160 0 Not documented
12162 minus Not documented
12164 equal Not documented
12166 backspace
12168 Not documented
12169 tab Not documented
12171 q Not documented
12173 w Not documented
12175 e Not documented
12177 r Not documented
12179 t Not documented
12181 y Not documented
12183 u Not documented
12185 i Not documented
12187 o Not documented
12189 p Not documented
12191 bracket_left
12193 Not documented
12194 bracket_right
12196 Not documented
12197 ret Not documented
12199 a Not documented
12201 s Not documented
12203 d Not documented
12205 f Not documented
12207 g Not documented
12209 h Not documented
12211 j Not documented
12213 k Not documented
12215 l Not documented
12217 semicolon
12219 Not documented
12220 apostrophe
12222 Not documented
12223 grave_accent
12225 Not documented
12226 backslash
12228 Not documented
12229 z Not documented
12231 x Not documented
12233 c Not documented
12235 v Not documented
12237 b Not documented
12239 n Not documented
12241 m Not documented
12243 comma Not documented
12245 dot Not documented
12247 slash Not documented
12249 asterisk
12251 Not documented
12252 spc Not documented
12254 caps_lock
12256 Not documented
12257 f1 Not documented
12259 f2 Not documented
12261 f3 Not documented
12263 f4 Not documented
12265 f5 Not documented
12267 f6 Not documented
12269 f7 Not documented
12271 f8 Not documented
12273 f9 Not documented
12275 f10 Not documented
12277 num_lock
12279 Not documented
12280 scroll_lock
12282 Not documented
12283 kp_divide
12285 Not documented
12286 kp_multiply
12288 Not documented
12289 kp_subtract
12291 Not documented
12292 kp_add Not documented
12294 kp_enter
12296 Not documented
12297 kp_decimal
12299 Not documented
12300 sysrq Not documented
12302 kp_0 Not documented
12304 kp_1 Not documented
12306 kp_2 Not documented
12308 kp_3 Not documented
12310 kp_4 Not documented
12312 kp_5 Not documented
12314 kp_6 Not documented
12316 kp_7 Not documented
12318 kp_8 Not documented
12320 kp_9 Not documented
12322 less Not documented
12324 f11 Not documented
12326 f12 Not documented
12328 print Not documented
12330 home Not documented
12332 pgup Not documented
12334 pgdn Not documented
12336 end Not documented
12338 left Not documented
12340 up Not documented
12342 down Not documented
12344 right Not documented
12346 insert Not documented
12348 delete Not documented
12350 stop Not documented
12352 again Not documented
12354 props Not documented
12356 undo Not documented
12358 front Not documented
12360 copy Not documented
12362 open Not documented
12364 paste Not documented
12366 find Not documented
12368 cut Not documented
12370 lf Not documented
12372 help Not documented
12374 meta_l Not documented
12376 meta_r Not documented
12378 compose
12380 Not documented
12381 'sysrq' was mistakenly added to hack around the fact that the ps2
12382 driver was not generating correct scancodes sequences when 'alt+print'
12383 was pressed. This flaw is now fixed and the 'sysrq' key serves no fur‐
12384 ther purpose. Any further use of 'sysrq' will be transparently changed
12385 to 'print', so they are effectively synonyms.
12386 Since
12388 1.3
12389 KeyValue (Object)
12391 Represents a keyboard key.
12392 Members
12394 type One of number, qcode
12395 data: int when type is "number"
12397 data: QKeyCode when type is "qcode"
12399 Since
12401 1.3
12402 send-key (Command)
12404 Send keys to guest.
12405 Arguments
12407 keys: array of KeyValue
12408 An array of KeyValue elements. All KeyValues in this array are
12409 simultaneously sent to the guest. A KeyValue.number value is
12410 sent directly to the guest, while KeyValue.qcode must be a valid
12411 QKeyCode value
12412 hold-time: int (optional)
12414 time to delay key up events, milliseconds. Defaults to 100
12415 Returns
12417 • Nothing on success
12418 • If key is unknown or redundant, InvalidParameter
12420 Since
12422 1.3
12423 Example
12425 -> { "execute": "send-key",
12426 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
12427 { "type": "qcode", "data": "alt" },
12428 { "type": "qcode", "data": "delete" } ] } }
12429 <- { "return": {} }
12430 InputButton (Enum)
12432 Button of a pointer input device (mouse, tablet).
12433 Values
12435 side front side button of a 5-button mouse (since 2.9)
12436 extra rear side button of a 5-button mouse (since 2.9)
12438 left Not documented
12440 middle Not documented
12442 right Not documented
12444 wheel-up
12446 Not documented
12447 wheel-down
12449 Not documented
12450 Since
12452 2.0
12453 InputAxis (Enum)
12455 Position axis of a pointer input device (mouse, tablet).
12456 Values
12458 x Not documented
12459 y Not documented
12461 Since
12463 2.0
12464 InputKeyEvent (Object)
12466 Keyboard input event.
12467 Members
12469 key: KeyValue
12470 Which key this event is for.
12471 down: boolean
12473 True for key-down and false for key-up events.
12474 Since
12476 2.0
12477 InputBtnEvent (Object)
12479 Pointer button input event.
12480 Members
12482 button: InputButton
12483 Which button this event is for.
12484 down: boolean
12486 True for key-down and false for key-up events.
12487 Since
12489 2.0
12490 InputMoveEvent (Object)
12492 Pointer motion input event.
12493 Members
12495 axis: InputAxis
12496 Which axis is referenced by value.
12497 value: int
12499 Pointer position. For absolute coordinates the valid range is 0
12500 -> 0x7ffff
12501 Since
12503 2.0
12504 InputEvent (Object)
12506 Input event union.
12507 Members
12509 type the input type, one of:
12510 • 'key': Input event of Keyboard
12512 • 'btn': Input event of pointer buttons
12514 • 'rel': Input event of relative pointer motion
12516 • 'abs': Input event of absolute pointer motion
12518 data: InputKeyEvent when type is "key"
12520 data: InputBtnEvent when type is "btn"
12522 data: InputMoveEvent when type is "rel"
12524 data: InputMoveEvent when type is "abs"
12526 Since
12528 2.0
12529 input-send-event (Command)
12531 Send input event(s) to guest.
12532 The device and head parameters can be used to send the input event to
12534 specific input devices in case (a) multiple input devices of the same
12535 kind are added to the virtual machine and (b) you have configured input
12536 routing (see docs/multiseat.txt) for those input devices. The parame‐
12537 ters work exactly like the device and head properties of input devices.
12538 If device is missing, only devices that have no input routing config
12539 are admissible. If device is specified, both input devices with and
12540 without input routing config are admissible, but devices with input
12541 routing config take precedence.
12542 Arguments
12544 device: string (optional)
12545 display device to send event(s) to.
12546 head: int (optional)
12548 head to send event(s) to, in case the display device supports
12549 multiple scanouts.
12550 events: array of InputEvent
12552 List of InputEvent union.
12553 Returns
12555 Nothing on success.
12556 Since
12558 2.6
12559 Note
12561 The consoles are visible in the qom tree, under /backend/console[$in‐
12562 dex]. They have a device link and head property, so it is possible to
12563 map which console belongs to which device and display.
12564 Example
12566 1. Press left mouse button.
12567 -> { "execute": "input-send-event",
12569 "arguments": { "device": "video0",
12570 "events": [ { "type": "btn",
12571 "data" : { "down": true, "button": "left" } } ] } }
12572 <- { "return": {} }
12573 -> { "execute": "input-send-event",
12575 "arguments": { "device": "video0",
12576 "events": [ { "type": "btn",
12577 "data" : { "down": false, "button": "left" } } ] } }
12578 <- { "return": {} }
12579 2. Press ctrl-alt-del.
12581 -> { "execute": "input-send-event",
12583 "arguments": { "events": [
12584 { "type": "key", "data" : { "down": true,
12585 "key": {"type": "qcode", "data": "ctrl" } } },
12586 { "type": "key", "data" : { "down": true,
12587 "key": {"type": "qcode", "data": "alt" } } },
12588 { "type": "key", "data" : { "down": true,
12589 "key": {"type": "qcode", "data": "delete" } } } ] } }
12590 <- { "return": {} }
12591 3. Move mouse pointer to absolute coordinates (20000, 400).
12593 -> { "execute": "input-send-event" ,
12595 "arguments": { "events": [
12596 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
12597 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
12598 <- { "return": {} }
12599 DisplayGTK (Object)
12601 GTK display options.
12602 Members
12604 grab-on-hover: boolean (optional)
12605 Grab keyboard input on mouse hover.
12606 zoom-to-fit: boolean (optional)
12608 Zoom guest display to fit into the host window. When turned off
12609 the host window will be resized instead. In case the display
12610 device can notify the guest on window resizes (virtio-gpu) this
12611 will default to "on", assuming the guest will resize the display
12612 to match the window size then. Otherwise it defaults to "off".
12613 Since 3.1
12614 Since
12616 2.12
12617 DisplayEGLHeadless (Object)
12619 EGL headless display options.
12620 Members
12622 rendernode: string (optional)
12623 Which DRM render node should be used. Default is the first
12624 available node on the host.
12625 Since
12627 3.1
12628 DisplayGLMode (Enum)
12630 Display OpenGL mode.
12631 Values
12633 off Disable OpenGL (default).
12634 on Use OpenGL, pick context type automatically. Would better be
12636 named 'auto' but is called 'on' for backward compatibility with
12637 bool type.
12638 core Use OpenGL with Core (desktop) Context.
12640 es Use OpenGL with ES (embedded systems) Context.
12642 Since
12644 3.0
12645 DisplayCurses (Object)
12647 Curses display options.
12648 Members
12650 charset: string (optional)
12651 Font charset used by guest (default: CP437).
12652 Since
12654 4.0
12655 DisplayType (Enum)
12657 Display (user interface) type.
12658 Values
12660 default
12661 The default user interface, selecting from the first available
12662 of gtk, sdl, cocoa, and vnc.
12663 none No user interface or video output display. The guest will still
12665 see an emulated graphics card, but its output will not be dis‐
12666 played to the QEMU user.
12667 gtk (If: defined(CONFIG_GTK))
12669 The GTK user interface.
12670 sdl (If: defined(CONFIG_SDL))
12672 The SDL user interface.
12673 egl-headless (If: defined(CONFIG_OPENGL) && defined(CONFIG_GBM))
12675 No user interface, offload GL operations to a local DRI device.
12676 Graphical display need to be paired with VNC or Spice. (Since
12677 3.1)
12678 curses (If: defined(CONFIG_CURSES))
12680 Display video output via curses. For graphics device models
12681 which support a text mode, QEMU can display this output using a
12682 curses/ncurses interface. Nothing is displayed when the graphics
12683 device is in graphical mode or if the graphics device does not
12684 support a text mode. Generally only the VGA device models sup‐
12685 port text mode.
12686 cocoa (If: defined(CONFIG_COCOA))
12688 The Cocoa user interface.
12689 spice-app (If: defined(CONFIG_SPICE))
12691 Set up a Spice server and run the default associated application
12692 to connect to it. The server will redirect the serial console
12693 and QEMU monitors. (Since 4.0)
12694 Since
12696 2.12
12697 DisplayOptions (Object)
12699 Display (user interface) options.
12700 Members
12702 type: DisplayType
12703 Which DisplayType qemu should use.
12704 full-screen: boolean (optional)
12706 Start user interface in fullscreen mode (default: off).
12707 window-close: boolean (optional)
12709 Allow to quit qemu with window close button (default: on).
12710 show-cursor: boolean (optional)
12712 Force showing the mouse cursor (default: off). (since: 5.0)
12713 gl: DisplayGLMode (optional)
12715 Enable OpenGL support (default: off).
12716 The members of DisplayGTK when type is "gtk" (If: defined(CONFIG_GTK))
12718 The members of DisplayCurses when type is "curses" (If: defined(CON‐
12720 FIG_CURSES))
12721 The members of DisplayEGLHeadless when type is "egl-headless" (If: de‐
12723 fined(CONFIG_OPENGL) && defined(CONFIG_GBM))
12724 Since
12726 2.12
12727 query-display-options (Command)
12729 Returns information about display configuration
12730 Returns
12732 DisplayOptions
12733 Since
12735 3.1
12736 DisplayReloadType (Enum)
12738 Available DisplayReload types.
12739 Values
12741 vnc VNC display
12742 Since
12744 6.0
12745 DisplayReloadOptionsVNC (Object)
12747 Specify the VNC reload options.
12748 Members
12750 tls-certs: boolean (optional)
12751 reload tls certs or not.
12752 Since
12754 6.0
12755 DisplayReloadOptions (Object)
12757 Options of the display configuration reload.
12758 Members
12760 type: DisplayReloadType
12761 Specify the display type.
12762 The members of DisplayReloadOptionsVNC when type is "vnc"
12764 Since
12766 6.0
12767 display-reload (Command)
12769 Reload display configuration.
12770 Arguments
12772 The members of DisplayReloadOptions
12773 Returns
12775 Nothing on success.
12776 Since
12778 6.0
12779 Example
12781 -> { "execute": "display-reload",
12782 "arguments": { "type": "vnc", "tls-certs": true } }
12783 <- { "return": {} }
12784
12786 QAuthZListPolicy (Enum)
12787 The authorization policy result
12788 Values
12790 deny deny access
12791 allow allow access
12793 Since
12795 4.0
12796 QAuthZListFormat (Enum)
12798 The authorization policy match format
12799 Values
12801 exact an exact string match
12802 glob string with ? and * shell wildcard support
12804 Since
12806 4.0
12807 QAuthZListRule (Object)
12809 A single authorization rule.
12810 Members
12812 match: string
12813 a string or glob to match against a user identity
12814 policy: QAuthZListPolicy
12816 the result to return if match evaluates to true
12817 format: QAuthZListFormat (optional)
12819 the format of the match rule (default 'exact')
12820 Since
12822 4.0
12823 AuthZListProperties (Object)
12825 Properties for authz-list objects.
12826 Members
12828 policy: QAuthZListPolicy (optional)
12829 Default policy to apply when no rule matches (default: deny)
12830 rules: array of QAuthZListRule (optional)
12832 Authorization rules based on matching user
12833 Since
12835 4.0
12836 AuthZListFileProperties (Object)
12838 Properties for authz-listfile objects.
12839 Members
12841 filename: string
12842 File name to load the configuration from. The file must contain
12843 valid JSON for AuthZListProperties.
12844 refresh: boolean (optional)
12846 If true, inotify is used to monitor the file, automatically
12847 reloading changes. If an error occurs during reloading, all au‐
12848 thorizations will fail until the file is next successfully
12849 loaded. (default: true if the binary was built with CONFIG_INO‐
12850 TIFY1, false otherwise)
12851 Since
12853 4.0
12854 AuthZPAMProperties (Object)
12856 Properties for authz-pam objects.
12857 Members
12859 service: string
12860 PAM service name to use for authorization
12861 Since
12863 4.0
12864 AuthZSimpleProperties (Object)
12866 Properties for authz-simple objects.
12867 Members
12869 identity: string
12870 Identifies the allowed user. Its format depends on the network
12871 service that authorization object is associated with. For autho‐
12872 rizing based on TLS x509 certificates, the identity must be the
12873 x509 distinguished name.
12874 Since
12876 4.0
12877
12879 MigrationStats (Object)
12880 Detailed migration status.
12881 Members
12883 transferred: int
12884 amount of bytes already transferred to the target VM
12885 remaining: int
12887 amount of bytes remaining to be transferred to the target VM
12888 total: int
12890 total amount of bytes involved in the migration process
12891 duplicate: int
12893 number of duplicate (zero) pages (since 1.2)
12894 skipped: int
12896 number of skipped zero pages (since 1.5)
12897 normal: int
12899 number of normal pages (since 1.2)
12900 normal-bytes: int
12902 number of normal bytes sent (since 1.2)
12903 dirty-pages-rate: int
12905 number of pages dirtied by second by the guest (since 1.3)
12906 mbps: number
12908 throughput in megabits/sec. (since 1.6)
12909 dirty-sync-count: int
12911 number of times that dirty ram was synchronized (since 2.1)
12912 postcopy-requests: int
12914 The number of page requests received from the destination (since
12915 2.7)
12916 page-size: int
12918 The number of bytes per page for the various page-based statis‐
12919 tics (since 2.10)
12920 multifd-bytes: int
12922 The number of bytes sent through multifd (since 3.0)
12923 pages-per-second: int
12925 the number of memory pages transferred per second (Since 4.0)
12926 Since
12928 0.14
12929 XBZRLECacheStats (Object)
12931 Detailed XBZRLE migration cache statistics
12932 Members
12934 cache-size: int
12935 XBZRLE cache size
12936 bytes: int
12938 amount of bytes already transferred to the target VM
12939 pages: int
12941 amount of pages transferred to the target VM
12942 cache-miss: int
12944 number of cache miss
12945 cache-miss-rate: number
12947 rate of cache miss (since 2.1)
12948 encoding-rate: number
12950 rate of encoded bytes (since 5.1)
12951 overflow: int
12953 number of overflows
12954 Since
12956 1.2
12957 CompressionStats (Object)
12959 Detailed migration compression statistics
12960 Members
12962 pages: int
12963 amount of pages compressed and transferred to the target VM
12964 busy: int
12966 count of times that no free thread was available to compress
12967 data
12968 busy-rate: number
12970 rate of thread busy
12971 compressed-size: int
12973 amount of bytes after compression
12974 compression-rate: number
12976 rate of compressed size
12977 Since
12979 3.1
12980 MigrationStatus (Enum)
12982 An enumeration of migration status.
12983 Values
12985 none no migration has ever happened.
12986 setup migration process has been initiated.
12988 cancelling
12990 in the process of cancelling migration.
12991 cancelled
12993 cancelling migration is finished.
12994 active in the process of doing migration.
12996 postcopy-active
12998 like active, but now in postcopy mode. (since 2.5)
12999 postcopy-paused
13001 during postcopy but paused. (since 3.0)
13002 postcopy-recover
13004 trying to recover from a paused postcopy. (since 3.0)
13005 completed
13007 migration is finished.
13008 failed some error occurred during migration process.
13010 colo VM is in the process of fault tolerance, VM can not get into
13012 this state unless colo capability is enabled for migration.
13013 (since 2.8)
13014 pre-switchover
13016 Paused before device serialisation. (since 2.11)
13017 device During device serialisation when pause-before-switchover is en‐
13019 abled (since 2.11)
13020 wait-unplug
13022 wait for device unplug request by guest OS to be completed.
13023 (since 4.2)
13024 Since
13026 2.3
13027 VfioStats (Object)
13029 Detailed VFIO devices migration statistics
13030 Members
13032 transferred: int
13033 amount of bytes transferred to the target VM by VFIO devices
13034 Since
13036 5.2
13037 MigrationInfo (Object)
13039 Information about current migration process.
13040 Members
13042 status: MigrationStatus (optional)
13043 MigrationStatus describing the current migration status. If
13044 this field is not returned, no migration process has been initi‐
13045 ated
13046 ram: MigrationStats (optional)
13048 MigrationStats containing detailed migration status, only re‐
13049 turned if status is 'active' or 'completed'(since 1.2)
13050 disk: MigrationStats (optional)
13052 MigrationStats containing detailed disk migration status, only
13053 returned if status is 'active' and it is a block migration
13054 xbzrle-cache: XBZRLECacheStats (optional)
13056 XBZRLECacheStats containing detailed XBZRLE migration statis‐
13057 tics, only returned if XBZRLE feature is on and status is 'ac‐
13058 tive' or 'completed' (since 1.2)
13059 total-time: int (optional)
13061 total amount of milliseconds since migration started. If migra‐
13062 tion has ended, it returns the total migration time. (since 1.2)
13063 downtime: int (optional)
13065 only present when migration finishes correctly total downtime in
13066 milliseconds for the guest. (since 1.3)
13067 expected-downtime: int (optional)
13069 only present while migration is active expected downtime in mil‐
13070 liseconds for the guest in last walk of the dirty bitmap. (since
13071 1.3)
13072 setup-time: int (optional)
13074 amount of setup time in milliseconds before the iterations begin
13075 but after the QMP command is issued. This is designed to provide
13076 an accounting of any activities (such as RDMA pinning) which may
13077 be expensive, but do not actually occur during the iterative mi‐
13078 gration rounds themselves. (since 1.6)
13079 cpu-throttle-percentage: int (optional)
13081 percentage of time guest cpus are being throttled during
13082 auto-converge. This is only present when auto-converge has
13083 started throttling guest cpus. (Since 2.7)
13084 error-desc: string (optional)
13086 the human readable error description string, when status is
13087 'failed'. Clients should not attempt to parse the error strings.
13088 (Since 2.7)
13089 postcopy-blocktime: int (optional)
13091 total time when all vCPU were blocked during postcopy live mi‐
13092 gration. This is only present when the postcopy-blocktime migra‐
13093 tion capability is enabled. (Since 3.0)
13094 postcopy-vcpu-blocktime: array of int (optional)
13096 list of the postcopy blocktime per vCPU. This is only present
13097 when the postcopy-blocktime migration capability is enabled.
13098 (Since 3.0)
13099 compression: CompressionStats (optional)
13101 migration compression statistics, only returned if compression
13102 feature is on and status is 'active' or 'completed' (Since 3.1)
13103 socket-address: array of SocketAddress (optional)
13105 Only used for tcp, to know what the real port is (Since 4.0)
13106 vfio: VfioStats (optional)
13108 VfioStats containing detailed VFIO devices migration statistics,
13109 only returned if VFIO device is present, migration is supported
13110 by all VFIO devices and status is 'active' or 'completed' (since
13111 5.2)
13112 blocked-reasons: array of string (optional)
13114 A list of reasons an outgoing migration is blocked. Present and
13115 non-empty when migration is blocked. (since 6.0)
13116 Since
13118 0.14
13119 query-migrate (Command)
13121 Returns information about current migration process. If migration is
13122 active there will be another json-object with RAM migration status and
13123 if block migration is active another one with block migration status.
13124 Returns
13126 MigrationInfo
13127 Since
13129 0.14
13130 Example
13132 1. Before the first migration
13133 -> { "execute": "query-migrate" }
13135 <- { "return": {} }
13136 2. Migration is done and has succeeded
13138 -> { "execute": "query-migrate" }
13140 <- { "return": {
13141 "status": "completed",
13142 "total-time":12345,
13143 "setup-time":12345,
13144 "downtime":12345,
13145 "ram":{
13146 "transferred":123,
13147 "remaining":123,
13148 "total":246,
13149 "duplicate":123,
13150 "normal":123,
13151 "normal-bytes":123456,
13152 "dirty-sync-count":15
13153 }
13154 }
13155 }
13156 3. Migration is done and has failed
13158 -> { "execute": "query-migrate" }
13160 <- { "return": { "status": "failed" } }
13161 4. Migration is being performed and is not a block migration:
13163 -> { "execute": "query-migrate" }
13165 <- {
13166 "return":{
13167 "status":"active",
13168 "total-time":12345,
13169 "setup-time":12345,
13170 "expected-downtime":12345,
13171 "ram":{
13172 "transferred":123,
13173 "remaining":123,
13174 "total":246,
13175 "duplicate":123,
13176 "normal":123,
13177 "normal-bytes":123456,
13178 "dirty-sync-count":15
13179 }
13180 }
13181 }
13182 5. Migration is being performed and is a block migration:
13184 -> { "execute": "query-migrate" }
13186 <- {
13187 "return":{
13188 "status":"active",
13189 "total-time":12345,
13190 "setup-time":12345,
13191 "expected-downtime":12345,
13192 "ram":{
13193 "total":1057024,
13194 "remaining":1053304,
13195 "transferred":3720,
13196 "duplicate":123,
13197 "normal":123,
13198 "normal-bytes":123456,
13199 "dirty-sync-count":15
13200 },
13201 "disk":{
13202 "total":20971520,
13203 "remaining":20880384,
13204 "transferred":91136
13205 }
13206 }
13207 }
13208 6. Migration is being performed and XBZRLE is active:
13210 -> { "execute": "query-migrate" }
13212 <- {
13213 "return":{
13214 "status":"active",
13215 "total-time":12345,
13216 "setup-time":12345,
13217 "expected-downtime":12345,
13218 "ram":{
13219 "total":1057024,
13220 "remaining":1053304,
13221 "transferred":3720,
13222 "duplicate":10,
13223 "normal":3333,
13224 "normal-bytes":3412992,
13225 "dirty-sync-count":15
13226 },
13227 "xbzrle-cache":{
13228 "cache-size":67108864,
13229 "bytes":20971520,
13230 "pages":2444343,
13231 "cache-miss":2244,
13232 "cache-miss-rate":0.123,
13233 "encoding-rate":80.1,
13234 "overflow":34434
13235 }
13236 }
13237 }
13238 MigrationCapability (Enum)
13240 Migration capabilities enumeration
13241 Values
13243 xbzrle Migration supports xbzrle (Xor Based Zero Run Length Encoding).
13244 This feature allows us to minimize migration traffic for certain
13245 work loads, by sending compressed difference of the pages
13246 rdma-pin-all
13248 Controls whether or not the entire VM memory footprint is
13249 mlock()'d on demand or all at once. Refer to docs/rdma.txt for
13250 usage. Disabled by default. (since 2.0)
13251 zero-blocks
13253 During storage migration encode blocks of zeroes efficiently.
13254 This essentially saves 1MB of zeroes per block on the wire. En‐
13255 abling requires source and target VM to support this feature. To
13256 enable it is sufficient to enable the capability on the source
13257 VM. The feature is disabled by default. (since 1.6)
13258 compress
13260 Use multiple compression threads to accelerate live migration.
13261 This feature can help to reduce the migration traffic, by send‐
13262 ing compressed pages. Please note that if compress and xbzrle
13263 are both on, compress only takes effect in the ram bulk stage,
13264 after that, it will be disabled and only xbzrle takes effect,
13265 this can help to minimize migration traffic. The feature is dis‐
13266 abled by default. (since 2.4 )
13267 events generate events for each migration state change (since 2.4 )
13269 auto-converge
13271 If enabled, QEMU will automatically throttle down the guest to
13272 speed up convergence of RAM migration. (since 1.6)
13273 postcopy-ram
13275 Start executing on the migration target before all of RAM has
13276 been migrated, pulling the remaining pages along as needed. The
13277 capacity must have the same setting on both source and target or
13278 migration will not even start. NOTE: If the migration fails dur‐
13279 ing postcopy the VM will fail. (since 2.6)
13280 x-colo If enabled, migration will never end, and the state of the VM on
13282 the primary side will be migrated continuously to the VM on sec‐
13283 ondary side, this process is called COarse-Grain LOck Stepping
13284 (COLO) for Non-stop Service. (since 2.8)
13285 release-ram
13287 if enabled, qemu will free the migrated ram pages on the source
13288 during postcopy-ram migration. (since 2.9)
13289 block If enabled, QEMU will also migrate the contents of all block de‐
13291 vices. Default is disabled. A possible alternative uses mirror
13292 jobs to a builtin NBD server on the destination, which offers
13293 more flexibility. (Since 2.10)
13294 return-path
13296 If enabled, migration will use the return path even for precopy.
13297 (since 2.10)
13298 pause-before-switchover
13300 Pause outgoing migration before serialising device state and be‐
13301 fore disabling block IO (since 2.11)
13302 multifd
13304 Use more than one fd for migration (since 4.0)
13305 dirty-bitmaps
13307 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
13308 postcopy-blocktime
13310 Calculate downtime for postcopy live migration (since 3.0)
13311 late-block-activate
13313 If enabled, the destination will not activate block devices (and
13314 thus take locks) immediately at the end of migration. (since
13315 3.0)
13316 x-ignore-shared
13318 If enabled, QEMU will not migrate shared memory (since 4.0)
13319 validate-uuid
13321 Send the UUID of the source to allow the destination to ensure
13322 it is the same. (since 4.2)
13323 background-snapshot
13325 If enabled, the migration stream will be a snapshot of the VM
13326 exactly at the point when the migration procedure starts. The VM
13327 RAM is saved with running VM. (since 6.0)
13328 Since
13330 1.2
13331 MigrationCapabilityStatus (Object)
13333 Migration capability information
13334 Members
13336 capability: MigrationCapability
13337 capability enum
13338 state: boolean
13340 capability state bool
13341 Since
13343 1.2
13344 migrate-set-capabilities (Command)
13346 Enable/Disable the following migration capabilities (like xbzrle)
13347 Arguments
13349 capabilities: array of MigrationCapabilityStatus
13350 json array of capability modifications to make
13351 Since
13353 1.2
13354 Example
13356 -> { "execute": "migrate-set-capabilities" , "arguments":
13357 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
13358 query-migrate-capabilities (Command)
13360 Returns information about the current migration capabilities status
13361 Returns
13363 MigrationCapabilitiesStatus
13364 Since
13366 1.2
13367 Example
13369 -> { "execute": "query-migrate-capabilities" }
13370 <- { "return": [
13371 {"state": false, "capability": "xbzrle"},
13372 {"state": false, "capability": "rdma-pin-all"},
13373 {"state": false, "capability": "auto-converge"},
13374 {"state": false, "capability": "zero-blocks"},
13375 {"state": false, "capability": "compress"},
13376 {"state": true, "capability": "events"},
13377 {"state": false, "capability": "postcopy-ram"},
13378 {"state": false, "capability": "x-colo"}
13379 ]}
13380 MultiFDCompression (Enum)
13382 An enumeration of multifd compression methods.
13383 Values
13385 none no compression.
13386 zlib use zlib compression method.
13388 zstd (If: defined(CONFIG_ZSTD))
13390 use zstd compression method.
13391 Since
13393 5.0
13394 BitmapMigrationBitmapAliasTransform (Object)
13396 Members
13397 persistent: boolean (optional)
13398 If present, the bitmap will be made persistent or transient de‐
13399 pending on this parameter.
13400 Since
13402 6.0
13403 BitmapMigrationBitmapAlias (Object)
13405 Members
13406 name: string
13407 The name of the bitmap.
13408 alias: string
13410 An alias name for migration (for example the bitmap name on the
13411 opposite site).
13412 transform: BitmapMigrationBitmapAliasTransform (optional)
13414 Allows the modification of the migrated bitmap. (since 6.0)
13415 Since
13417 5.2
13418 BitmapMigrationNodeAlias (Object)
13420 Maps a block node name and the bitmaps it has to aliases for dirty bit‐
13421 map migration.
13422 Members
13424 node-name: string
13425 A block node name.
13426 alias: string
13428 An alias block node name for migration (for example the node
13429 name on the opposite site).
13430 bitmaps: array of BitmapMigrationBitmapAlias
13432 Mappings for the bitmaps on this node.
13433 Since
13435 5.2
13436 MigrationParameter (Enum)
13438 Migration parameters enumeration
13439 Values
13441 announce-initial
13442 Initial delay (in milliseconds) before sending the first an‐
13443 nounce (Since 4.0)
13444 announce-max
13446 Maximum delay (in milliseconds) between packets in the announce‐
13447 ment (Since 4.0)
13448 announce-rounds
13450 Number of self-announce packets sent after migration (Since 4.0)
13451 announce-step
13453 Increase in delay (in milliseconds) between subsequent packets
13454 in the announcement (Since 4.0)
13455 compress-level
13457 Set the compression level to be used in live migration, the com‐
13458 pression level is an integer between 0 and 9, where 0 means no
13459 compression, 1 means the best compression speed, and 9 means
13460 best compression ratio which will consume more CPU.
13461 compress-threads
13463 Set compression thread count to be used in live migration, the
13464 compression thread count is an integer between 1 and 255.
13465 compress-wait-thread
13467 Controls behavior when all compression threads are currently
13468 busy. If true (default), wait for a free compression thread to
13469 become available; otherwise, send the page uncompressed. (Since
13470 3.1)
13471 decompress-threads
13473 Set decompression thread count to be used in live migration, the
13474 decompression thread count is an integer between 1 and 255. Usu‐
13475 ally, decompression is at least 4 times as fast as compression,
13476 so set the decompress-threads to the number about 1/4 of com‐
13477 press-threads is adequate.
13478 throttle-trigger-threshold
13480 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
13481 throttling. It is expressed as percentage. The default value is
13482 50. (Since 5.0)
13483 cpu-throttle-initial
13485 Initial percentage of time guest cpus are throttled when migra‐
13486 tion auto-converge is activated. The default value is 20. (Since
13487 2.7)
13488 cpu-throttle-increment
13490 throttle percentage increase each time auto-converge detects
13491 that migration is not making progress. The default value is 10.
13492 (Since 2.7)
13493 cpu-throttle-tailslow
13495 Make CPU throttling slower at tail stage At the tail stage of
13496 throttling, the Guest is very sensitive to CPU percentage while
13497 the cpu-throttle -increment is excessive usually at tail stage.
13498 If this parameter is true, we will compute the ideal CPU per‐
13499 centage used by the Guest, which may exactly make the dirty rate
13500 match the dirty rate threshold. Then we will choose a smaller
13501 throttle increment between the one specified by cpu-throttle-in‐
13502 crement and the one generated by ideal CPU percentage. There‐
13503 fore, it is compatible to traditional throttling, meanwhile the
13504 throttle increment won't be excessive at tail stage. The de‐
13505 fault value is false. (Since 5.1)
13506 tls-creds
13508 ID of the 'tls-creds' object that provides credentials for es‐
13509 tablishing a TLS connection over the migration data channel. On
13510 the outgoing side of the migration, the credentials must be for
13511 a 'client' endpoint, while for the incoming side the credentials
13512 must be for a 'server' endpoint. Setting this will enable TLS
13513 for all migrations. The default is unset, resulting in unsecured
13514 migration at the QEMU level. (Since 2.7)
13515 tls-hostname
13517 hostname of the target host for the migration. This is required
13518 when using x509 based TLS credentials and the migration URI does
13519 not already include a hostname. For example if using fd: or
13520 exec: based migration, the hostname must be provided so that the
13521 server's x509 certificate identity can be validated. (Since 2.7)
13522 tls-authz
13524 ID of the 'authz' object subclass that provides access control
13525 checking of the TLS x509 certificate distinguished name. This
13526 object is only resolved at time of use, so can be deleted and
13527 recreated on the fly while the migration server is active. If
13528 missing, it will default to denying access (Since 4.0)
13529 max-bandwidth
13531 to set maximum speed for migration. maximum speed in bytes per
13532 second. (Since 2.8)
13533 downtime-limit
13535 set maximum tolerated downtime for migration. maximum downtime
13536 in milliseconds (Since 2.8)
13537 x-checkpoint-delay
13539 The delay time (in ms) between two COLO checkpoints in periodic
13540 mode. (Since 2.8)
13541 block-incremental
13543 Affects how much storage is migrated when the block migration
13544 capability is enabled. When false, the entire storage backing
13545 chain is migrated into a flattened image at the destination;
13546 when true, only the active qcow2 layer is migrated and the des‐
13547 tination must already have access to the same backing chain as
13548 was used on the source. (since 2.10)
13549 multifd-channels
13551 Number of channels used to migrate data in parallel. This is the
13552 same number that the number of sockets used for migration. The
13553 default value is 2 (since 4.0)
13554 xbzrle-cache-size
13556 cache size to be used by XBZRLE migration. It needs to be a
13557 multiple of the target page size and a power of 2 (Since 2.11)
13558 max-postcopy-bandwidth
13560 Background transfer bandwidth during postcopy. Defaults to 0
13561 (unlimited). In bytes per second. (Since 3.0)
13562 max-cpu-throttle
13564 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
13565 multifd-compression
13567 Which compression method to use. Defaults to none. (Since 5.0)
13568 multifd-zlib-level
13570 Set the compression level to be used in live migration, the com‐
13571 pression level is an integer between 0 and 9, where 0 means no
13572 compression, 1 means the best compression speed, and 9 means
13573 best compression ratio which will consume more CPU. Defaults to
13574 1. (Since 5.0)
13575 multifd-zstd-level
13577 Set the compression level to be used in live migration, the com‐
13578 pression level is an integer between 0 and 20, where 0 means no
13579 compression, 1 means the best compression speed, and 20 means
13580 best compression ratio which will consume more CPU. Defaults to
13581 1. (Since 5.0)
13582 block-bitmap-mapping
13584 Maps block nodes and bitmaps on them to aliases for the purpose
13585 of dirty bitmap migration. Such aliases may for example be the
13586 corresponding names on the opposite site. The mapping must be
13587 one-to-one, but not necessarily complete: On the source, un‐
13588 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
13589 nored. On the destination, encountering an unmapped alias in
13590 the incoming migration stream will result in a report, and all
13591 further bitmap migration data will then be discarded. Note that
13592 the destination does not know about bitmaps it does not receive,
13593 so there is no limitation or requirement regarding the number of
13594 bitmaps received, or how they are named, or on which nodes they
13595 are placed. By default (when this parameter has never been
13596 set), bitmap names are mapped to themselves. Nodes are mapped
13597 to their block device name if there is one, and to their node
13598 name otherwise. (Since 5.2)
13599 Since
13601 2.4
13602 MigrateSetParameters (Object)
13604 Members
13605 announce-initial: int (optional)
13606 Initial delay (in milliseconds) before sending the first an‐
13607 nounce (Since 4.0)
13608 announce-max: int (optional)
13610 Maximum delay (in milliseconds) between packets in the announce‐
13611 ment (Since 4.0)
13612 announce-rounds: int (optional)
13614 Number of self-announce packets sent after migration (Since 4.0)
13615 announce-step: int (optional)
13617 Increase in delay (in milliseconds) between subsequent packets
13618 in the announcement (Since 4.0)
13619 compress-level: int (optional)
13621 compression level
13622 compress-threads: int (optional)
13624 compression thread count
13625 compress-wait-thread: boolean (optional)
13627 Controls behavior when all compression threads are currently
13628 busy. If true (default), wait for a free compression thread to
13629 become available; otherwise, send the page uncompressed. (Since
13630 3.1)
13631 decompress-threads: int (optional)
13633 decompression thread count
13634 throttle-trigger-threshold: int (optional)
13636 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
13637 throttling. It is expressed as percentage. The default value is
13638 50. (Since 5.0)
13639 cpu-throttle-initial: int (optional)
13641 Initial percentage of time guest cpus are throttled when migra‐
13642 tion auto-converge is activated. The default value is 20.
13643 (Since 2.7)
13644 cpu-throttle-increment: int (optional)
13646 throttle percentage increase each time auto-converge detects
13647 that migration is not making progress. The default value is 10.
13648 (Since 2.7)
13649 cpu-throttle-tailslow: boolean (optional)
13651 Make CPU throttling slower at tail stage At the tail stage of
13652 throttling, the Guest is very sensitive to CPU percentage while
13653 the cpu-throttle -increment is excessive usually at tail stage.
13654 If this parameter is true, we will compute the ideal CPU per‐
13655 centage used by the Guest, which may exactly make the dirty rate
13656 match the dirty rate threshold. Then we will choose a smaller
13657 throttle increment between the one specified by cpu-throttle-in‐
13658 crement and the one generated by ideal CPU percentage. There‐
13659 fore, it is compatible to traditional throttling, meanwhile the
13660 throttle increment won't be excessive at tail stage. The de‐
13661 fault value is false. (Since 5.1)
13662 tls-creds: StrOrNull (optional)
13664 ID of the 'tls-creds' object that provides credentials for es‐
13665 tablishing a TLS connection over the migration data channel. On
13666 the outgoing side of the migration, the credentials must be for
13667 a 'client' endpoint, while for the incoming side the credentials
13668 must be for a 'server' endpoint. Setting this to a non-empty
13669 string enables TLS for all migrations. An empty string means
13670 that QEMU will use plain text mode for migration, rather than
13671 TLS (Since 2.9) Previously (since 2.7), this was reported by
13672 omitting tls-creds instead.
13673 tls-hostname: StrOrNull (optional)
13675 hostname of the target host for the migration. This is required
13676 when using x509 based TLS credentials and the migration URI does
13677 not already include a hostname. For example if using fd: or
13678 exec: based migration, the hostname must be provided so that the
13679 server's x509 certificate identity can be validated. (Since 2.7)
13680 An empty string means that QEMU will use the hostname associated
13681 with the migration URI, if any. (Since 2.9) Previously (since
13682 2.7), this was reported by omitting tls-hostname instead.
13683 max-bandwidth: int (optional)
13685 to set maximum speed for migration. maximum speed in bytes per
13686 second. (Since 2.8)
13687 downtime-limit: int (optional)
13689 set maximum tolerated downtime for migration. maximum downtime
13690 in milliseconds (Since 2.8)
13691 x-checkpoint-delay: int (optional)
13693 the delay time between two COLO checkpoints. (Since 2.8)
13694 block-incremental: boolean (optional)
13696 Affects how much storage is migrated when the block migration
13697 capability is enabled. When false, the entire storage backing
13698 chain is migrated into a flattened image at the destination;
13699 when true, only the active qcow2 layer is migrated and the des‐
13700 tination must already have access to the same backing chain as
13701 was used on the source. (since 2.10)
13702 multifd-channels: int (optional)
13704 Number of channels used to migrate data in parallel. This is the
13705 same number that the number of sockets used for migration. The
13706 default value is 2 (since 4.0)
13707 xbzrle-cache-size: int (optional)
13709 cache size to be used by XBZRLE migration. It needs to be a
13710 multiple of the target page size and a power of 2 (Since 2.11)
13711 max-postcopy-bandwidth: int (optional)
13713 Background transfer bandwidth during postcopy. Defaults to 0
13714 (unlimited). In bytes per second. (Since 3.0)
13715 max-cpu-throttle: int (optional)
13717 maximum cpu throttle percentage. The default value is 99.
13718 (Since 3.1)
13719 multifd-compression: MultiFDCompression (optional)
13721 Which compression method to use. Defaults to none. (Since 5.0)
13722 multifd-zlib-level: int (optional)
13724 Set the compression level to be used in live migration, the com‐
13725 pression level is an integer between 0 and 9, where 0 means no
13726 compression, 1 means the best compression speed, and 9 means
13727 best compression ratio which will consume more CPU. Defaults to
13728 1. (Since 5.0)
13729 multifd-zstd-level: int (optional)
13731 Set the compression level to be used in live migration, the com‐
13732 pression level is an integer between 0 and 20, where 0 means no
13733 compression, 1 means the best compression speed, and 20 means
13734 best compression ratio which will consume more CPU. Defaults to
13735 1. (Since 5.0)
13736 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
13738 Maps block nodes and bitmaps on them to aliases for the purpose
13739 of dirty bitmap migration. Such aliases may for example be the
13740 corresponding names on the opposite site. The mapping must be
13741 one-to-one, but not necessarily complete: On the source, un‐
13742 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
13743 nored. On the destination, encountering an unmapped alias in
13744 the incoming migration stream will result in a report, and all
13745 further bitmap migration data will then be discarded. Note that
13746 the destination does not know about bitmaps it does not receive,
13747 so there is no limitation or requirement regarding the number of
13748 bitmaps received, or how they are named, or on which nodes they
13749 are placed. By default (when this parameter has never been
13750 set), bitmap names are mapped to themselves. Nodes are mapped
13751 to their block device name if there is one, and to their node
13752 name otherwise. (Since 5.2)
13753 tls-authz: StrOrNull (optional)
13755 Not documented
13756 Since
13758 2.4
13759 migrate-set-parameters (Command)
13761 Set various migration parameters.
13762 Arguments
13764 The members of MigrateSetParameters
13765 Since
13767 2.4
13768 Example
13770 -> { "execute": "migrate-set-parameters" ,
13771 "arguments": { "compress-level": 1 } }
13772 MigrationParameters (Object)
13774 The optional members aren't actually optional.
13775 Members
13777 announce-initial: int (optional)
13778 Initial delay (in milliseconds) before sending the first an‐
13779 nounce (Since 4.0)
13780 announce-max: int (optional)
13782 Maximum delay (in milliseconds) between packets in the announce‐
13783 ment (Since 4.0)
13784 announce-rounds: int (optional)
13786 Number of self-announce packets sent after migration (Since 4.0)
13787 announce-step: int (optional)
13789 Increase in delay (in milliseconds) between subsequent packets
13790 in the announcement (Since 4.0)
13791 compress-level: int (optional)
13793 compression level
13794 compress-threads: int (optional)
13796 compression thread count
13797 compress-wait-thread: boolean (optional)
13799 Controls behavior when all compression threads are currently
13800 busy. If true (default), wait for a free compression thread to
13801 become available; otherwise, send the page uncompressed. (Since
13802 3.1)
13803 decompress-threads: int (optional)
13805 decompression thread count
13806 throttle-trigger-threshold: int (optional)
13808 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
13809 throttling. It is expressed as percentage. The default value is
13810 50. (Since 5.0)
13811 cpu-throttle-initial: int (optional)
13813 Initial percentage of time guest cpus are throttled when migra‐
13814 tion auto-converge is activated. (Since 2.7)
13815 cpu-throttle-increment: int (optional)
13817 throttle percentage increase each time auto-converge detects
13818 that migration is not making progress. (Since 2.7)
13819 cpu-throttle-tailslow: boolean (optional)
13821 Make CPU throttling slower at tail stage At the tail stage of
13822 throttling, the Guest is very sensitive to CPU percentage while
13823 the cpu-throttle -increment is excessive usually at tail stage.
13824 If this parameter is true, we will compute the ideal CPU per‐
13825 centage used by the Guest, which may exactly make the dirty rate
13826 match the dirty rate threshold. Then we will choose a smaller
13827 throttle increment between the one specified by cpu-throttle-in‐
13828 crement and the one generated by ideal CPU percentage. There‐
13829 fore, it is compatible to traditional throttling, meanwhile the
13830 throttle increment won't be excessive at tail stage. The de‐
13831 fault value is false. (Since 5.1)
13832 tls-creds: string (optional)
13834 ID of the 'tls-creds' object that provides credentials for es‐
13835 tablishing a TLS connection over the migration data channel. On
13836 the outgoing side of the migration, the credentials must be for
13837 a 'client' endpoint, while for the incoming side the credentials
13838 must be for a 'server' endpoint. An empty string means that
13839 QEMU will use plain text mode for migration, rather than TLS
13840 (Since 2.7) Note: 2.8 reports this by omitting tls-creds in‐
13841 stead.
13842 tls-hostname: string (optional)
13844 hostname of the target host for the migration. This is required
13845 when using x509 based TLS credentials and the migration URI does
13846 not already include a hostname. For example if using fd: or
13847 exec: based migration, the hostname must be provided so that the
13848 server's x509 certificate identity can be validated. (Since 2.7)
13849 An empty string means that QEMU will use the hostname associated
13850 with the migration URI, if any. (Since 2.9) Note: 2.8 reports
13851 this by omitting tls-hostname instead.
13852 tls-authz: string (optional)
13854 ID of the 'authz' object subclass that provides access control
13855 checking of the TLS x509 certificate distinguished name. (Since
13856 4.0)
13857 max-bandwidth: int (optional)
13859 to set maximum speed for migration. maximum speed in bytes per
13860 second. (Since 2.8)
13861 downtime-limit: int (optional)
13863 set maximum tolerated downtime for migration. maximum downtime
13864 in milliseconds (Since 2.8)
13865 x-checkpoint-delay: int (optional)
13867 the delay time between two COLO checkpoints. (Since 2.8)
13868 block-incremental: boolean (optional)
13870 Affects how much storage is migrated when the block migration
13871 capability is enabled. When false, the entire storage backing
13872 chain is migrated into a flattened image at the destination;
13873 when true, only the active qcow2 layer is migrated and the des‐
13874 tination must already have access to the same backing chain as
13875 was used on the source. (since 2.10)
13876 multifd-channels: int (optional)
13878 Number of channels used to migrate data in parallel. This is the
13879 same number that the number of sockets used for migration. The
13880 default value is 2 (since 4.0)
13881 xbzrle-cache-size: int (optional)
13883 cache size to be used by XBZRLE migration. It needs to be a
13884 multiple of the target page size and a power of 2 (Since 2.11)
13885 max-postcopy-bandwidth: int (optional)
13887 Background transfer bandwidth during postcopy. Defaults to 0
13888 (unlimited). In bytes per second. (Since 3.0)
13889 max-cpu-throttle: int (optional)
13891 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
13892 multifd-compression: MultiFDCompression (optional)
13894 Which compression method to use. Defaults to none. (Since 5.0)
13895 multifd-zlib-level: int (optional)
13897 Set the compression level to be used in live migration, the com‐
13898 pression level is an integer between 0 and 9, where 0 means no
13899 compression, 1 means the best compression speed, and 9 means
13900 best compression ratio which will consume more CPU. Defaults to
13901 1. (Since 5.0)
13902 multifd-zstd-level: int (optional)
13904 Set the compression level to be used in live migration, the com‐
13905 pression level is an integer between 0 and 20, where 0 means no
13906 compression, 1 means the best compression speed, and 20 means
13907 best compression ratio which will consume more CPU. Defaults to
13908 1. (Since 5.0)
13909 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
13911 Maps block nodes and bitmaps on them to aliases for the purpose
13912 of dirty bitmap migration. Such aliases may for example be the
13913 corresponding names on the opposite site. The mapping must be
13914 one-to-one, but not necessarily complete: On the source, un‐
13915 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
13916 nored. On the destination, encountering an unmapped alias in
13917 the incoming migration stream will result in a report, and all
13918 further bitmap migration data will then be discarded. Note that
13919 the destination does not know about bitmaps it does not receive,
13920 so there is no limitation or requirement regarding the number of
13921 bitmaps received, or how they are named, or on which nodes they
13922 are placed. By default (when this parameter has never been
13923 set), bitmap names are mapped to themselves. Nodes are mapped
13924 to their block device name if there is one, and to their node
13925 name otherwise. (Since 5.2)
13926 Since
13928 2.4
13929 query-migrate-parameters (Command)
13931 Returns information about the current migration parameters
13932 Returns
13934 MigrationParameters
13935 Since
13937 2.4
13938 Example
13940 -> { "execute": "query-migrate-parameters" }
13941 <- { "return": {
13942 "decompress-threads": 2,
13943 "cpu-throttle-increment": 10,
13944 "compress-threads": 8,
13945 "compress-level": 1,
13946 "cpu-throttle-initial": 20,
13947 "max-bandwidth": 33554432,
13948 "downtime-limit": 300
13949 }
13950 }
13951 client_migrate_info (Command)
13953 Set migration information for remote display. This makes the server
13954 ask the client to automatically reconnect using the new parameters once
13955 migration finished successfully. Only implemented for SPICE.
13956 Arguments
13958 protocol: string
13959 must be "spice"
13960 hostname: string
13962 migration target hostname
13963 port: int (optional)
13965 spice tcp port for plaintext channels
13966 tls-port: int (optional)
13968 spice tcp port for tls-secured channels
13969 cert-subject: string (optional)
13971 server certificate subject
13972 Since
13974 0.14
13975 Example
13977 -> { "execute": "client_migrate_info",
13978 "arguments": { "protocol": "spice",
13979 "hostname": "virt42.lab.kraxel.org",
13980 "port": 1234 } }
13981 <- { "return": {} }
13982 migrate-start-postcopy (Command)
13984 Followup to a migration command to switch the migration to postcopy
13985 mode. The postcopy-ram capability must be set on both source and des‐
13986 tination before the original migration command.
13987 Since
13989 2.5
13990 Example
13992 -> { "execute": "migrate-start-postcopy" }
13993 <- { "return": {} }
13994 MIGRATION (Event)
13996 Emitted when a migration event happens
13997 Arguments
13999 status: MigrationStatus
14000 MigrationStatus describing the current migration status.
14001 Since
14003 2.4
14004 Example
14006 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
14007 "event": "MIGRATION",
14008 "data": {"status": "completed"} }
14009 MIGRATION_PASS (Event)
14011 Emitted from the source side of a migration at the start of each pass
14012 (when it syncs the dirty bitmap)
14013 Arguments
14015 pass: int
14016 An incrementing count (starting at 1 on the first pass)
14017 Since
14019 2.6
14020 Example
14022 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
14023 "event": "MIGRATION_PASS", "data": {"pass": 2} }
14024 COLOMessage (Enum)
14026 The message transmission between Primary side and Secondary side.
14027 Values
14029 checkpoint-ready
14030 Secondary VM (SVM) is ready for checkpointing
14031 checkpoint-request
14033 Primary VM (PVM) tells SVM to prepare for checkpointing
14034 checkpoint-reply
14036 SVM gets PVM's checkpoint request
14037 vmstate-send
14039 VM's state will be sent by PVM.
14040 vmstate-size
14042 The total size of VMstate.
14043 vmstate-received
14045 VM's state has been received by SVM.
14046 vmstate-loaded
14048 VM's state has been loaded by SVM.
14049 Since
14051 2.8
14052 COLOMode (Enum)
14054 The COLO current mode.
14055 Values
14057 none COLO is disabled.
14058 primary
14060 COLO node in primary side.
14061 secondary
14063 COLO node in slave side.
14064 Since
14066 2.8
14067 FailoverStatus (Enum)
14069 An enumeration of COLO failover status
14070 Values
14072 none no failover has ever happened
14073 require
14075 got failover requirement but not handled
14076 active in the process of doing failover
14078 completed
14080 finish the process of failover
14081 relaunch
14083 restart the failover process, from 'none' -> 'completed' (Since
14084 2.9)
14085 Since
14087 2.8
14088 COLO_EXIT (Event)
14090 Emitted when VM finishes COLO mode due to some errors happening or at
14091 the request of users.
14092 Arguments
14094 mode: COLOMode
14095 report COLO mode when COLO exited.
14096 reason: COLOExitReason
14098 describes the reason for the COLO exit.
14099 Since
14101 3.1
14102 Example
14104 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
14105 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
14106 COLOExitReason (Enum)
14108 The reason for a COLO exit.
14109 Values
14111 none failover has never happened. This state does not occur in the
14112 COLO_EXIT event, and is only visible in the result of
14113 query-colo-status.
14114 request
14116 COLO exit is due to an external request.
14117 error COLO exit is due to an internal error.
14119 processing
14121 COLO is currently handling a failover (since 4.0).
14122 Since
14124 3.1
14125 x-colo-lost-heartbeat (Command)
14127 Tell qemu that heartbeat is lost, request it to do takeover procedures.
14128 If this command is sent to the PVM, the Primary side will exit COLO
14129 mode. If sent to the Secondary, the Secondary side will run failover
14130 work, then takes over server operation to become the service VM.
14131 Since
14133 2.8
14134 Example
14136 -> { "execute": "x-colo-lost-heartbeat" }
14137 <- { "return": {} }
14138 migrate_cancel (Command)
14140 Cancel the current executing migration process.
14141 Returns
14143 nothing on success
14144 Notes
14146 This command succeeds even if there is no migration process running.
14147 Since
14149 0.14
14150 Example
14152 -> { "execute": "migrate_cancel" }
14153 <- { "return": {} }
14154 migrate-continue (Command)
14156 Continue migration when it's in a paused state.
14157 Arguments
14159 state: MigrationStatus
14160 The state the migration is currently expected to be in
14161 Returns
14163 nothing on success
14164 Since
14166 2.11
14167 Example
14169 -> { "execute": "migrate-continue" , "arguments":
14170 { "state": "pre-switchover" } }
14171 <- { "return": {} }
14172 migrate (Command)
14174 Migrates the current running guest to another Virtual Machine.
14175 Arguments
14177 uri: string
14178 the Uniform Resource Identifier of the destination VM
14179 blk: boolean (optional)
14181 do block migration (full disk copy)
14182 inc: boolean (optional)
14184 incremental disk copy migration
14185 detach: boolean (optional)
14187 this argument exists only for compatibility reasons and is ig‐
14188 nored by QEMU
14189 resume: boolean (optional)
14191 resume one paused migration, default "off". (since 3.0)
14192 Returns
14194 nothing on success
14195 Since
14197 0.14
14198 Notes
14200 1. The 'query-migrate' command should be used to check migration's
14201 progress and final result (this information is provided by the 'sta‐
14202 tus' member)
14203 2. All boolean arguments default to false
14205 3. The user Monitor's "detach" argument is invalid in QMP and should
14207 not be used
14208 Example
14210 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
14211 <- { "return": {} }
14212 migrate-incoming (Command)
14214 Start an incoming migration, the qemu must have been started with -in‐
14215 coming defer
14216 Arguments
14218 uri: string
14219 The Uniform Resource Identifier identifying the source or ad‐
14220 dress to listen on
14221 Returns
14223 nothing on success
14224 Since
14226 2.3
14227 Notes
14229 1. It's a bad idea to use a string for the uri, but it needs to stay
14230 compatible with -incoming and the format of the uri is already ex‐
14231 posed above libvirt.
14232 2. QEMU must be started with -incoming defer to allow migrate-incoming
14234 to be used.
14235 3. The uri format is the same as for -incoming
14237 Example
14239 -> { "execute": "migrate-incoming",
14240 "arguments": { "uri": "tcp::4446" } }
14241 <- { "return": {} }
14242 xen-save-devices-state (Command)
14244 Save the state of all devices to file. The RAM and the block devices of
14245 the VM are not saved by this command.
14246 Arguments
14248 filename: string
14249 the file to save the state of the devices to as binary data. See
14250 xen-save-devices-state.txt for a description of the binary for‐
14251 mat.
14252 live: boolean (optional)
14254 Optional argument to ask QEMU to treat this command as part of a
14255 live migration. Default to true. (since 2.11)
14256 Returns
14258 Nothing on success
14259 Since
14261 1.1
14262 Example
14264 -> { "execute": "xen-save-devices-state",
14265 "arguments": { "filename": "/tmp/save" } }
14266 <- { "return": {} }
14267 xen-set-global-dirty-log (Command)
14269 Enable or disable the global dirty log mode.
14270 Arguments
14272 enable: boolean
14273 true to enable, false to disable.
14274 Returns
14276 nothing
14277 Since
14279 1.3
14280 Example
14282 -> { "execute": "xen-set-global-dirty-log",
14283 "arguments": { "enable": true } }
14284 <- { "return": {} }
14285 xen-load-devices-state (Command)
14287 Load the state of all devices from file. The RAM and the block devices
14288 of the VM are not loaded by this command.
14289 Arguments
14291 filename: string
14292 the file to load the state of the devices from as binary data.
14293 See xen-save-devices-state.txt for a description of the binary
14294 format.
14295 Since
14297 2.7
14298 Example
14300 -> { "execute": "xen-load-devices-state",
14301 "arguments": { "filename": "/tmp/resume" } }
14302 <- { "return": {} }
14303 xen-set-replication (Command)
14305 Enable or disable replication.
14306 Arguments
14308 enable: boolean
14309 true to enable, false to disable.
14310 primary: boolean
14312 true for primary or false for secondary.
14313 failover: boolean (optional)
14315 true to do failover, false to stop. but cannot be specified if
14316 'enable' is true. default value is false.
14317 Returns
14319 nothing.
14320 Example
14322 -> { "execute": "xen-set-replication",
14323 "arguments": {"enable": true, "primary": false} }
14324 <- { "return": {} }
14325 Since
14327 2.9
14328 If
14330 defined(CONFIG_REPLICATION)
14331 ReplicationStatus (Object)
14333 The result format for 'query-xen-replication-status'.
14334 Members
14336 error: boolean
14337 true if an error happened, false if replication is normal.
14338 desc: string (optional)
14340 the human readable error description string, when error is
14341 'true'.
14342 Since
14344 2.9
14345 If
14347 defined(CONFIG_REPLICATION)
14348 query-xen-replication-status (Command)
14350 Query replication status while the vm is running.
14351 Returns
14353 A ReplicationResult object showing the status.
14354 Example
14356 -> { "execute": "query-xen-replication-status" }
14357 <- { "return": { "error": false } }
14358 Since
14360 2.9
14361 If
14363 defined(CONFIG_REPLICATION)
14364 xen-colo-do-checkpoint (Command)
14366 Xen uses this command to notify replication to trigger a checkpoint.
14367 Returns
14369 nothing.
14370 Example
14372 -> { "execute": "xen-colo-do-checkpoint" }
14373 <- { "return": {} }
14374 Since
14376 2.9
14377 If
14379 defined(CONFIG_REPLICATION)
14380 COLOStatus (Object)
14382 The result format for 'query-colo-status'.
14383 Members
14385 mode: COLOMode
14386 COLO running mode. If COLO is running, this field will return
14387 'primary' or 'secondary'.
14388 last-mode: COLOMode
14390 COLO last running mode. If COLO is running, this field will re‐
14391 turn same like mode field, after failover we can use this field
14392 to get last colo mode. (since 4.0)
14393 reason: COLOExitReason
14395 describes the reason for the COLO exit.
14396 Since
14398 3.1
14399 query-colo-status (Command)
14401 Query COLO status while the vm is running.
14402 Returns
14404 A COLOStatus object showing the status.
14405 Example
14407 -> { "execute": "query-colo-status" }
14408 <- { "return": { "mode": "primary", "reason": "request" } }
14409 Since
14411 3.1
14412 migrate-recover (Command)
14414 Provide a recovery migration stream URI.
14415 Arguments
14417 uri: string
14418 the URI to be used for the recovery of migration stream.
14419 Returns
14421 nothing.
14422 Example
14424 -> { "execute": "migrate-recover",
14425 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
14426 <- { "return": {} }
14427 Since
14429 3.0
14430 migrate-pause (Command)
14432 Pause a migration. Currently it only supports postcopy.
14433 Returns
14435 nothing.
14436 Example
14438 -> { "execute": "migrate-pause" }
14439 <- { "return": {} }
14440 Since
14442 3.0
14443 UNPLUG_PRIMARY (Event)
14445 Emitted from source side of a migration when migration state is
14446 WAIT_UNPLUG. Device was unplugged by guest operating system. Device
14447 resources in QEMU are kept on standby to be able to re-plug it in case
14448 of migration failure.
14449 Arguments
14451 device-id: string
14452 QEMU device id of the unplugged device
14453 Since
14455 4.2
14456 Example
14458 {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} }
14459 DirtyRateStatus (Enum)
14461 An enumeration of dirtyrate status.
14462 Values
14464 unstarted
14465 the dirtyrate thread has not been started.
14466 measuring
14468 the dirtyrate thread is measuring.
14469 measured
14471 the dirtyrate thread has measured and results are available.
14472 Since
14474 5.2
14475 DirtyRateInfo (Object)
14477 Information about current dirty page rate of vm.
14478 Members
14480 dirty-rate: int (optional)
14481 an estimate of the dirty page rate of the VM in units of MB/s,
14482 present only when estimating the rate has completed.
14483 status: DirtyRateStatus
14485 status containing dirtyrate query status includes 'unstarted' or
14486 'measuring' or 'measured'
14487 start-time: int
14489 start time in units of second for calculation
14490 calc-time: int
14492 time in units of second for sample dirty pages
14493 sample-pages: int
14495 page count per GB for sample dirty pages the default value is
14496 512 (since 6.1)
14497 Since
14499 5.2
14500 calc-dirty-rate (Command)
14502 start calculating dirty page rate for vm
14503 Arguments
14505 calc-time: int
14506 time in units of second for sample dirty pages
14507 sample-pages: int (optional)
14509 page count per GB for sample dirty pages the default value is
14510 512 (since 6.1)
14511 Since
14513 5.2
14514 Example
14516 {"command": "calc-dirty-rate", "data": {"calc-time": 1,
14517 'sample-pages': 512} }
14518 query-dirty-rate (Command)
14520 query dirty page rate in units of MB/s for vm
14521 Since
14523 5.2
14524 snapshot-save (Command)
14526 Save a VM snapshot
14527 Arguments
14529 job-id: string
14530 identifier for the newly created job
14531 tag: string
14533 name of the snapshot to create
14534 vmstate: string
14536 block device node name to save vmstate to
14537 devices: array of string
14539 list of block device node names to save a snapshot to
14540 Applications should not assume that the snapshot save is complete when
14541 this command returns. The job commands / events must be used to deter‐
14542 mine completion and to fetch details of any errors that arise.
14543 Note that execution of the guest CPUs may be stopped during the time it
14545 takes to save the snapshot. A future version of QEMU may ensure CPUs
14546 are executing continuously.
14547 It is strongly recommended that devices contain all writable block de‐
14549 vice nodes if a consistent snapshot is required.
14550 If tag already exists, an error will be reported
14552 Returns
14554 nothing
14555 Example
14557 -> { "execute": "snapshot-save",
14558 "data": {
14559 "job-id": "snapsave0",
14560 "tag": "my-snap",
14561 "vmstate": "disk0",
14562 "devices": ["disk0", "disk1"]
14563 }
14564 }
14565 <- { "return": { } }
14566 <- {"event": "JOB_STATUS_CHANGE",
14567 "data": {"status": "created", "id": "snapsave0"}}
14568 <- {"event": "JOB_STATUS_CHANGE",
14569 "data": {"status": "running", "id": "snapsave0"}}
14570 <- {"event": "STOP"}
14571 <- {"event": "RESUME"}
14572 <- {"event": "JOB_STATUS_CHANGE",
14573 "data": {"status": "waiting", "id": "snapsave0"}}
14574 <- {"event": "JOB_STATUS_CHANGE",
14575 "data": {"status": "pending", "id": "snapsave0"}}
14576 <- {"event": "JOB_STATUS_CHANGE",
14577 "data": {"status": "concluded", "id": "snapsave0"}}
14578 -> {"execute": "query-jobs"}
14579 <- {"return": [{"current-progress": 1,
14580 "status": "concluded",
14581 "total-progress": 1,
14582 "type": "snapshot-save",
14583 "id": "snapsave0"}]}
14584 Since
14586 6.0
14587 snapshot-load (Command)
14589 Load a VM snapshot
14590 Arguments
14592 job-id: string
14593 identifier for the newly created job
14594 tag: string
14596 name of the snapshot to load.
14597 vmstate: string
14599 block device node name to load vmstate from
14600 devices: array of string
14602 list of block device node names to load a snapshot from
14603 Applications should not assume that the snapshot load is complete when
14604 this command returns. The job commands / events must be used to deter‐
14605 mine completion and to fetch details of any errors that arise.
14606 Note that execution of the guest CPUs will be stopped during the time
14608 it takes to load the snapshot.
14609 It is strongly recommended that devices contain all writable block de‐
14611 vice nodes that can have changed since the original snapshot-save com‐
14612 mand execution.
14613 Returns
14615 nothing
14616 Example
14618 -> { "execute": "snapshot-load",
14619 "data": {
14620 "job-id": "snapload0",
14621 "tag": "my-snap",
14622 "vmstate": "disk0",
14623 "devices": ["disk0", "disk1"]
14624 }
14625 }
14626 <- { "return": { } }
14627 <- {"event": "JOB_STATUS_CHANGE",
14628 "data": {"status": "created", "id": "snapload0"}}
14629 <- {"event": "JOB_STATUS_CHANGE",
14630 "data": {"status": "running", "id": "snapload0"}}
14631 <- {"event": "STOP"}
14632 <- {"event": "RESUME"}
14633 <- {"event": "JOB_STATUS_CHANGE",
14634 "data": {"status": "waiting", "id": "snapload0"}}
14635 <- {"event": "JOB_STATUS_CHANGE",
14636 "data": {"status": "pending", "id": "snapload0"}}
14637 <- {"event": "JOB_STATUS_CHANGE",
14638 "data": {"status": "concluded", "id": "snapload0"}}
14639 -> {"execute": "query-jobs"}
14640 <- {"return": [{"current-progress": 1,
14641 "status": "concluded",
14642 "total-progress": 1,
14643 "type": "snapshot-load",
14644 "id": "snapload0"}]}
14645 Since
14647 6.0
14648 snapshot-delete (Command)
14650 Delete a VM snapshot
14651 Arguments
14653 job-id: string
14654 identifier for the newly created job
14655 tag: string
14657 name of the snapshot to delete.
14658 devices: array of string
14660 list of block device node names to delete a snapshot from
14661 Applications should not assume that the snapshot delete is complete
14662 when this command returns. The job commands / events must be used to
14663 determine completion and to fetch details of any errors that arise.
14664 Returns
14666 nothing
14667 Example
14669 -> { "execute": "snapshot-delete",
14670 "data": {
14671 "job-id": "snapdelete0",
14672 "tag": "my-snap",
14673 "devices": ["disk0", "disk1"]
14674 }
14675 }
14676 <- { "return": { } }
14677 <- {"event": "JOB_STATUS_CHANGE",
14678 "data": {"status": "created", "id": "snapdelete0"}}
14679 <- {"event": "JOB_STATUS_CHANGE",
14680 "data": {"status": "running", "id": "snapdelete0"}}
14681 <- {"event": "JOB_STATUS_CHANGE",
14682 "data": {"status": "waiting", "id": "snapdelete0"}}
14683 <- {"event": "JOB_STATUS_CHANGE",
14684 "data": {"status": "pending", "id": "snapdelete0"}}
14685 <- {"event": "JOB_STATUS_CHANGE",
14686 "data": {"status": "concluded", "id": "snapdelete0"}}
14687 -> {"execute": "query-jobs"}
14688 <- {"return": [{"current-progress": 1,
14689 "status": "concluded",
14690 "total-progress": 1,
14691 "type": "snapshot-delete",
14692 "id": "snapdelete0"}]}
14693 Since
14695 6.0
14696
14698 Abort (Object)
14699 This action can be used to test transaction failure.
14700 Since
14702 1.6
14703 ActionCompletionMode (Enum)
14705 An enumeration of Transactional completion modes.
14706 Values
14708 individual
14709 Do not attempt to cancel any other Actions if any Actions fail
14710 after the Transaction request succeeds. All Actions that can
14711 complete successfully will do so without waiting on others.
14712 This is the default.
14713 grouped
14715 If any Action fails after the Transaction succeeds, cancel all
14716 Actions. Actions do not complete until all Actions are ready to
14717 complete. May be rejected by Actions that do not support this
14718 completion mode.
14719 Since
14721 2.5
14722 TransactionAction (Object)
14724 A discriminated record of operations that can be performed with trans‐
14725 action. Action type can be:
14726 • abort: since 1.6
14728 • block-dirty-bitmap-add: since 2.5
14730 • block-dirty-bitmap-remove: since 4.2
14732 • block-dirty-bitmap-clear: since 2.5
14734 • block-dirty-bitmap-enable: since 4.0
14736 • block-dirty-bitmap-disable: since 4.0
14738 • block-dirty-bitmap-merge: since 4.0
14740 • blockdev-backup: since 2.3
14742 • blockdev-snapshot: since 2.5
14744 • blockdev-snapshot-internal-sync: since 1.7
14746 • blockdev-snapshot-sync: since 1.1
14748 • drive-backup: since 1.6
14750 Members
14752 type One of abort, block-dirty-bitmap-add, block-dirty-bitmap-remove,
14753 block-dirty-bitmap-clear, block-dirty-bitmap-enable,
14754 block-dirty-bitmap-disable, block-dirty-bitmap-merge, block‐
14755 dev-backup, blockdev-snapshot, blockdev-snapshot-internal-sync,
14756 blockdev-snapshot-sync, drive-backup
14757 data: Abort when type is "abort"
14759 data: BlockDirtyBitmapAdd when type is "block-dirty-bitmap-add"
14761 data: BlockDirtyBitmap when type is "block-dirty-bitmap-remove"
14763 data: BlockDirtyBitmap when type is "block-dirty-bitmap-clear"
14765 data: BlockDirtyBitmap when type is "block-dirty-bitmap-enable"
14767 data: BlockDirtyBitmap when type is "block-dirty-bitmap-disable"
14769 data: BlockDirtyBitmapMerge when type is "block-dirty-bitmap-merge"
14771 data: BlockdevBackup when type is "blockdev-backup"
14773 data: BlockdevSnapshot when type is "blockdev-snapshot"
14775 data: BlockdevSnapshotInternal when type is "blockdev-snapshot-inter‐
14777 nal-sync"
14778 data: BlockdevSnapshotSync when type is "blockdev-snapshot-sync"
14780 data: DriveBackup when type is "drive-backup"
14782 Since
14784 1.1
14785 TransactionProperties (Object)
14787 Optional arguments to modify the behavior of a Transaction.
14788 Members
14790 completion-mode: ActionCompletionMode (optional)
14791 Controls how jobs launched asynchronously by Actions will com‐
14792 plete or fail as a group. See ActionCompletionMode for details.
14793 Since
14795 2.5
14796 transaction (Command)
14798 Executes a number of transactionable QMP commands atomically. If any
14799 operation fails, then the entire set of actions will be abandoned and
14800 the appropriate error returned.
14801 For external snapshots, the dictionary contains the device, the file to
14803 use for the new snapshot, and the format. The default format, if not
14804 specified, is qcow2.
14805 Each new snapshot defaults to being created by QEMU (wiping any con‐
14807 tents if the file already exists), but it is also possible to reuse an
14808 externally-created file. In the latter case, you should ensure that
14809 the new image file has the same contents as the current one; QEMU can‐
14810 not perform any meaningful check. Typically this is achieved by using
14811 the current image file as the backing file for the new image.
14812 On failure, the original disks pre-snapshot attempt will be used.
14814 For internal snapshots, the dictionary contains the device and the
14816 snapshot's name. If an internal snapshot matching name already exists,
14817 the request will be rejected. Only some image formats support it, for
14818 example, qcow2, and rbd,
14819 On failure, qemu will try delete the newly created internal snapshot in
14821 the transaction. When an I/O error occurs during deletion, the user
14822 needs to fix it later with qemu-img or other command.
14823 Arguments
14825 actions: array of TransactionAction
14826 List of TransactionAction; information needed for the respective
14827 operations.
14828 properties: TransactionProperties (optional)
14830 structure of additional options to control the execution of the
14831 transaction. See TransactionProperties for additional detail.
14832 Returns
14834 nothing on success
14835 Errors depend on the operations of the transaction
14837 Note
14839 The transaction aborts on the first failure. Therefore, there will be
14840 information on only one failed operation returned in an error condi‐
14841 tion, and subsequent actions will not have been attempted.
14842 Since
14844 1.1
14845 Example
14847 -> { "execute": "transaction",
14848 "arguments": { "actions": [
14849 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
14850 "snapshot-file": "/some/place/my-image",
14851 "format": "qcow2" } },
14852 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
14853 "snapshot-file": "/some/place/my-image2",
14854 "snapshot-node-name": "node3432",
14855 "mode": "existing",
14856 "format": "qcow2" } },
14857 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
14858 "snapshot-file": "/some/place/my-image2",
14859 "mode": "existing",
14860 "format": "qcow2" } },
14861 { "type": "blockdev-snapshot-internal-sync", "data" : {
14862 "device": "ide-hd2",
14863 "name": "snapshot0" } } ] } }
14864 <- { "return": {} }
14865
14867 TraceEventState (Enum)
14868 State of a tracing event.
14869 Values
14871 unavailable
14872 The event is statically disabled.
14873 disabled
14875 The event is dynamically disabled.
14876 enabled
14878 The event is dynamically enabled.
14879 Since
14881 2.2
14882 TraceEventInfo (Object)
14884 Information of a tracing event.
14885 Members
14887 name: string
14888 Event name.
14889 state: TraceEventState
14891 Tracing state.
14892 vcpu: boolean
14894 Whether this is a per-vCPU event (since 2.7).
14895 An event is per-vCPU if it has the "vcpu" property in the
14896 "trace-events" files.
14897 Since
14899 2.2
14900 trace-event-get-state (Command)
14902 Query the state of events.
14903 Arguments
14905 name: string
14906 Event name pattern (case-sensitive glob).
14907 vcpu: int (optional)
14909 The vCPU to query (any by default; since 2.7).
14910 Returns
14912 a list of TraceEventInfo for the matching events
14913 An event is returned if:
14915 • its name matches the name pattern, and
14917 • if vcpu is given, the event has the "vcpu" property.
14919 Therefore, if vcpu is given, the operation will only match per-vCPU
14921 events, returning their state on the specified vCPU. Special case: if
14922 name is an exact match, vcpu is given and the event does not have the
14923 "vcpu" property, an error is returned.
14924 Since
14926 2.2
14927 Example
14929 -> { "execute": "trace-event-get-state",
14930 "arguments": { "name": "qemu_memalign" } }
14931 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
14932 trace-event-set-state (Command)
14934 Set the dynamic tracing state of events.
14935 Arguments
14937 name: string
14938 Event name pattern (case-sensitive glob).
14939 enable: boolean
14941 Whether to enable tracing.
14942 ignore-unavailable: boolean (optional)
14944 Do not match unavailable events with name.
14945 vcpu: int (optional)
14947 The vCPU to act upon (all by default; since 2.7).
14948 An event's state is modified if: - its name matches the name pattern,
14949 and - if vcpu is given, the event has the "vcpu" property.
14950 Therefore, if vcpu is given, the operation will only match per-vCPU
14952 events, setting their state on the specified vCPU. Special case: if
14953 name is an exact match, vcpu is given and the event does not have the
14954 "vcpu" property, an error is returned.
14955 Since
14957 2.2
14958 Example
14960 -> { "execute": "trace-event-set-state",
14961 "arguments": { "name": "qemu_memalign", "enable": "true" } }
14962 <- { "return": {} }
14963
14965 CompatPolicyInput (Enum)
14966 Policy for handling "funny" input.
14967 Values
14969 accept Accept silently
14970 reject Reject with an error
14972 crash abort() the process
14974 Since
14976 6.0
14977 CompatPolicyOutput (Enum)
14979 Policy for handling "funny" output.
14980 Values
14982 accept Pass on unchanged
14983 hide Filter out
14985 Since
14987 6.0
14988 CompatPolicy (Object)
14990 Policy for handling deprecated management interfaces.
14991 This is intended for testing users of the management interfaces.
14993 Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
14995 with feature 'deprecated'. We may want to extend it to cover semantic
14996 aspects, CLI, and experimental features.
14997 Members
14999 deprecated-input: CompatPolicyInput (optional)
15000 how to handle deprecated input (default 'accept')
15001 deprecated-output: CompatPolicyOutput (optional)
15003 how to handle deprecated output (default 'accept')
15004 Since
15006 6.0
15007
15009 qmp_capabilities (Command)
15010 Enable QMP capabilities.
15011 Arguments:
15013 Arguments
15015 enable: array of QMPCapability (optional)
15016 An optional list of QMPCapability values to enable. The client
15017 must not enable any capability that is not mentioned in the QMP
15018 greeting message. If the field is not provided, it means no QMP
15019 capabilities will be enabled. (since 2.12)
15020 Example
15022 -> { "execute": "qmp_capabilities",
15023 "arguments": { "enable": [ "oob" ] } }
15024 <- { "return": {} }
15025 Notes
15027 This command is valid exactly when first connecting: it must be issued
15028 before any other command will be accepted, and will fail once the moni‐
15029 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
15030 The QMP client needs to explicitly enable QMP capabilities, otherwise
15032 all the QMP capabilities will be turned off by default.
15033 Since
15035 0.13
15036 QMPCapability (Enum)
15038 Enumeration of capabilities to be advertised during initial client con‐
15039 nection, used for agreeing on particular QMP extension behaviors.
15040 Values
15042 oob QMP ability to support out-of-band requests. (Please refer to
15043 qmp-spec.txt for more information on OOB)
15044 Since
15046 2.12
15047 VersionTriple (Object)
15049 A three-part version number.
15050 Members
15052 major: int
15053 The major version number.
15054 minor: int
15056 The minor version number.
15057 micro: int
15059 The micro version number.
15060 Since
15062 2.4
15063 VersionInfo (Object)
15065 A description of QEMU's version.
15066 Members
15068 qemu: VersionTriple
15069 The version of QEMU. By current convention, a micro version of
15070 50 signifies a development branch. A micro version greater than
15071 or equal to 90 signifies a release candidate for the next minor
15072 version. A micro version of less than 50 signifies a stable re‐
15073 lease.
15074 package: string
15076 QEMU will always set this field to an empty string. Downstream
15077 versions of QEMU should set this to a non-empty string. The ex‐
15078 act format depends on the downstream however it highly recom‐
15079 mended that a unique name is used.
15080 Since
15082 0.14
15083 query-version (Command)
15085 Returns the current version of QEMU.
15086 Returns
15088 A VersionInfo object describing the current version of QEMU.
15089 Since
15091 0.14
15092 Example
15094 -> { "execute": "query-version" }
15095 <- {
15096 "return":{
15097 "qemu":{
15098 "major":0,
15099 "minor":11,
15100 "micro":5
15101 },
15102 "package":""
15103 }
15104 }
15105 CommandInfo (Object)
15107 Information about a QMP command
15108 Members
15110 name: string
15111 The command name
15112 Since
15114 0.14
15115 query-commands (Command)
15117 Return a list of supported QMP commands by this server
15118 Returns
15120 A list of CommandInfo for all supported commands
15121 Since
15123 0.14
15124 Example
15126 -> { "execute": "query-commands" }
15127 <- {
15128 "return":[
15129 {
15130 "name":"query-balloon"
15131 },
15132 {
15133 "name":"system_powerdown"
15134 }
15135 ]
15136 }
15137 Note
15139 This example has been shortened as the real response is too long.
15140 quit (Command)
15142 This command will cause the QEMU process to exit gracefully. While ev‐
15143 ery attempt is made to send the QMP response before terminating, this
15144 is not guaranteed. When using this interface, a premature EOF would
15145 not be unexpected.
15146 Since
15148 0.14
15149 Example
15151 -> { "execute": "quit" }
15152 <- { "return": {} }
15153 MonitorMode (Enum)
15155 An enumeration of monitor modes.
15156 Values
15158 readline
15159 HMP monitor (human-oriented command line interface)
15160 control
15162 QMP monitor (JSON-based machine interface)
15163 Since
15165 5.0
15166 MonitorOptions (Object)
15168 Options to be used for adding a new monitor.
15169 Members
15171 id: string (optional)
15172 Name of the monitor
15173 mode: MonitorMode (optional)
15175 Selects the monitor mode (default: readline in the system emula‐
15176 tor, control in qemu-storage-daemon)
15177 pretty: boolean (optional)
15179 Enables pretty printing (QMP only)
15180 chardev: string
15182 Name of a character device to expose the monitor on
15183 Since
15185 5.0
15186
15188 query-qmp-schema (Command)
15189 Command query-qmp-schema exposes the QMP wire ABI as an array of
15190 SchemaInfo. This lets QMP clients figure out what commands and events
15191 are available in this QEMU, and their parameters and results.
15192 However, the SchemaInfo can't reflect all the rules and restrictions
15194 that apply to QMP. It's interface introspection (figuring out what's
15195 there), not interface specification. The specification is in the QAPI
15196 schema.
15197 Furthermore, while we strive to keep the QMP wire format backwards-com‐
15199 patible across qemu versions, the introspection output is not guaran‐
15200 teed to have the same stability. For example, one version of qemu may
15201 list an object member as an optional non-variant, while another lists
15202 the same member only through the object's variants; or the type of a
15203 member may change from a generic string into a specific enum or from
15204 one specific type into an alternate that includes the original type
15205 alongside something else.
15206 Returns
15208 array of SchemaInfo, where each element describes an entity in the ABI:
15209 command, event, type, ...
15210 The order of the various SchemaInfo is unspecified; however, all names
15212 are guaranteed to be unique (no name will be duplicated with different
15213 meta-types).
15214 Note
15216 the QAPI schema is also used to help define internal interfaces, by
15217 defining QAPI types. These are not part of the QMP wire ABI, and
15218 therefore not returned by this command.
15219 Since
15221 2.5
15222 SchemaMetaType (Enum)
15224 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
15225 Values
15227 builtin
15228 a predefined type such as 'int' or 'bool'.
15229 enum an enumeration type
15231 array an array type
15233 object an object type (struct or union)
15235 alternate
15237 an alternate type
15238 command
15240 a QMP command
15241 event a QMP event
15243 Since
15245 2.5
15246 SchemaInfo (Object)
15248 Members
15249 name: string
15250 the entity's name, inherited from base. The SchemaInfo is al‐
15251 ways referenced by this name. Commands and events have the name
15252 defined in the QAPI schema. Unlike command and event names,
15253 type names are not part of the wire ABI. Consequently, type
15254 names are meaningless strings here, although they are still
15255 guaranteed unique regardless of meta-type.
15256 meta-type: SchemaMetaType
15258 the entity's meta type, inherited from base.
15259 features: array of string (optional)
15261 names of features associated with the entity, in no particular
15262 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
15263 the rest)
15264 The members of SchemaInfoBuiltin when meta-type is "builtin"
15266 The members of SchemaInfoEnum when meta-type is "enum"
15268 The members of SchemaInfoArray when meta-type is "array"
15270 The members of SchemaInfoObject when meta-type is "object"
15272 The members of SchemaInfoAlternate when meta-type is "alternate"
15274 The members of SchemaInfoCommand when meta-type is "command"
15276 The members of SchemaInfoEvent when meta-type is "event"
15278 Additional members depend on the value of meta-type.
15279 Since
15281 2.5
15282 SchemaInfoBuiltin (Object)
15284 Additional SchemaInfo members for meta-type 'builtin'.
15285 Members
15287 json-type: JSONType
15288 the JSON type used for this type on the wire.
15289 Since
15291 2.5
15292 JSONType (Enum)
15294 The four primitive and two structured types according to RFC 8259 sec‐
15295 tion 1, plus 'int' (split off 'number'), plus the obvious top type
15296 'value'.
15297 Values
15299 string Not documented
15300 number Not documented
15302 int Not documented
15304 boolean
15306 Not documented
15307 null Not documented
15309 object Not documented
15311 array Not documented
15313 value Not documented
15315 Since
15317 2.5
15318 SchemaInfoEnum (Object)
15320 Additional SchemaInfo members for meta-type 'enum'.
15321 Members
15323 values: array of string
15324 the enumeration type's values, in no particular order.
15325 Values of this type are JSON string on the wire.
15326 Since
15328 2.5
15329 SchemaInfoArray (Object)
15331 Additional SchemaInfo members for meta-type 'array'.
15332 Members
15334 element-type: string
15335 the array type's element type.
15336 Values of this type are JSON array on the wire.
15337 Since
15339 2.5
15340 SchemaInfoObject (Object)
15342 Additional SchemaInfo members for meta-type 'object'.
15343 Members
15345 members: array of SchemaInfoObjectMember
15346 the object type's (non-variant) members, in no particular order.
15347 tag: string (optional)
15349 the name of the member serving as type tag. An element of mem‐
15350 bers with this name must exist.
15351 variants: array of SchemaInfoObjectVariant (optional)
15353 variant members, i.e. additional members that depend on the type
15354 tag's value. Present exactly when tag is present. The variants
15355 are in no particular order, and may even differ from the order
15356 of the values of the enum type of the tag.
15357 Values of this type are JSON object on the wire.
15358 Since
15360 2.5
15361 SchemaInfoObjectMember (Object)
15363 An object member.
15364 Members
15366 name: string
15367 the member's name, as defined in the QAPI schema.
15368 type: string
15370 the name of the member's type.
15371 default: value (optional)
15373 default when used as command parameter. If absent, the parame‐
15374 ter is mandatory. If present, the value must be null. The pa‐
15375 rameter is optional, and behavior when it's missing is not spec‐
15376 ified here. Future extension: if present and non-null, the pa‐
15377 rameter is optional, and defaults to this value.
15378 features: array of string (optional)
15380 names of features associated with the member, in no particular
15381 order. (since 5.0)
15382 Since
15384 2.5
15385 SchemaInfoObjectVariant (Object)
15387 The variant members for a value of the type tag.
15388 Members
15390 case: string
15391 a value of the type tag.
15392 type: string
15394 the name of the object type that provides the variant members
15395 when the type tag has value case.
15396 Since
15398 2.5
15399 SchemaInfoAlternate (Object)
15401 Additional SchemaInfo members for meta-type 'alternate'.
15402 Members
15404 members: array of SchemaInfoAlternateMember
15405 the alternate type's members, in no particular order. The mem‐
15406 bers' wire encoding is distinct, see docs/de‐
15407 vel/qapi-code-gen.txt section Alternate types.
15408 On the wire, this can be any of the members.
15409 Since
15411 2.5
15412 SchemaInfoAlternateMember (Object)
15414 An alternate member.
15415 Members
15417 type: string
15418 the name of the member's type.
15419 Since
15421 2.5
15422 SchemaInfoCommand (Object)
15424 Additional SchemaInfo members for meta-type 'command'.
15425 Members
15427 arg-type: string
15428 the name of the object type that provides the command's parame‐
15429 ters.
15430 ret-type: string
15432 the name of the command's result type.
15433 allow-oob: boolean (optional)
15435 whether the command allows out-of-band execution, defaults to
15436 false (Since: 2.12)
15437 TODO
15439 success-response (currently irrelevant, because it's QGA, not QMP)
15440 Since
15442 2.5
15443 SchemaInfoEvent (Object)
15445 Additional SchemaInfo members for meta-type 'event'.
15446 Members
15448 arg-type: string
15449 the name of the object type that provides the event's parame‐
15450 ters.
15451 Since
15453 2.5
15454
15456 ObjectPropertyInfo (Object)
15457 Members
15458 name: string
15459 the name of the property
15460 type: string
15462 the type of the property. This will typically come in one of
15463 four forms:
15464 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
15466 ble'. These types are mapped to the appropriate JSON type.
15467 2. A child type in the form 'child<subtype>' where subtype is a
15469 qdev device type name. Child properties create the composi‐
15470 tion tree.
15471 3. A link type in the form 'link<subtype>' where subtype is a
15473 qdev device type name. Link properties form the device model
15474 graph.
15475 description: string (optional)
15477 if specified, the description of the property.
15478 default-value: value (optional)
15480 the default value, if any (since 5.0)
15481 Since
15483 1.2
15484 qom-list (Command)
15486 This command will list any properties of a object given a path in the
15487 object model.
15488 Arguments
15490 path: string
15491 the path within the object model. See qom-get for a description
15492 of this parameter.
15493 Returns
15495 a list of ObjectPropertyInfo that describe the properties of the ob‐
15496 ject.
15497 Since
15499 1.2
15500 Example
15502 -> { "execute": "qom-list",
15503 "arguments": { "path": "/chardevs" } }
15504 <- { "return": [ { "name": "type", "type": "string" },
15505 { "name": "parallel0", "type": "child<chardev-vc>" },
15506 { "name": "serial0", "type": "child<chardev-vc>" },
15507 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
15508 qom-get (Command)
15510 This command will get a property from a object model path and return
15511 the value.
15512 Arguments
15514 path: string
15515 The path within the object model. There are two forms of sup‐
15516 ported paths--absolute and partial paths.
15517 Absolute paths are derived from the root object and can follow
15519 child<> or link<> properties. Since they can follow link<>
15520 properties, they can be arbitrarily long. Absolute paths look
15521 like absolute filenames and are prefixed with a leading slash.
15522 Partial paths look like relative filenames. They do not begin
15524 with a prefix. The matching rules for partial paths are subtle
15525 but designed to make specifying objects easy. At each level of
15526 the composition tree, the partial path is matched as an absolute
15527 path. The first match is not returned. At least two matches
15528 are searched for. A successful result is only returned if only
15529 one match is found. If more than one match is found, a flag is
15530 return to indicate that the match was ambiguous.
15531 property: string
15533 The property name to read
15534 Returns
15536 The property value. The type depends on the property type. child<> and
15537 link<> properties are returned as #str pathnames. All integer property
15538 types (u8, u16, etc) are returned as #int.
15539 Since
15541 1.2
15542 Example
15544 1. Use absolute path
15545 -> { "execute": "qom-get",
15547 "arguments": { "path": "/machine/unattached/device[0]",
15548 "property": "hotplugged" } }
15549 <- { "return": false }
15550 2. Use partial path
15552 -> { "execute": "qom-get",
15554 "arguments": { "path": "unattached/sysbus",
15555 "property": "type" } }
15556 <- { "return": "System" }
15557 qom-set (Command)
15559 This command will set a property from a object model path.
15560 Arguments
15562 path: string
15563 see qom-get for a description of this parameter
15564 property: string
15566 the property name to set
15567 value: value
15569 a value who's type is appropriate for the property type. See
15570 qom-get for a description of type mapping.
15571 Since
15573 1.2
15574 Example
15576 -> { "execute": "qom-set",
15577 "arguments": { "path": "/machine",
15578 "property": "graphics",
15579 "value": false } }
15580 <- { "return": {} }
15581 ObjectTypeInfo (Object)
15583 This structure describes a search result from qom-list-types
15584 Members
15586 name: string
15587 the type name found in the search
15588 abstract: boolean (optional)
15590 the type is abstract and can't be directly instantiated. Omit‐
15591 ted if false. (since 2.10)
15592 parent: string (optional)
15594 Name of parent type, if any (since 2.10)
15595 Since
15597 1.1
15598 qom-list-types (Command)
15600 This command will return a list of types given search parameters
15601 Arguments
15603 implements: string (optional)
15604 if specified, only return types that implement this type name
15605 abstract: boolean (optional)
15607 if true, include abstract types in the results
15608 Returns
15610 a list of ObjectTypeInfo or an empty list if no results are found
15611 Since
15613 1.1
15614 qom-list-properties (Command)
15616 List properties associated with a QOM object.
15617 Arguments
15619 typename: string
15620 the type name of an object
15621 Note
15623 objects can create properties at runtime, for example to describe links
15624 between different devices and/or objects. These properties are not in‐
15625 cluded in the output of this command.
15626 Returns
15628 a list of ObjectPropertyInfo describing object properties
15629 Since
15631 2.12
15632 CanHostSocketcanProperties (Object)
15634 Properties for can-host-socketcan objects.
15635 Members
15637 if: string
15638 interface name of the host system CAN bus to connect to
15639 canbus: string
15641 object ID of the can-bus object to connect to the host interface
15642 Since
15644 2.12
15645 ColoCompareProperties (Object)
15647 Properties for colo-compare objects.
15648 Members
15650 primary_in: string
15651 name of the character device backend to use for the primary in‐
15652 put (incoming packets are redirected to outdev)
15653 secondary_in: string
15655 name of the character device backend to use for secondary input
15656 (incoming packets are only compared to the input on primary_in
15657 and then dropped)
15658 outdev: string
15660 name of the character device backend to use for output
15661 iothread: string
15663 name of the iothread to run in
15664 notify_dev: string (optional)
15666 name of the character device backend to be used to communicate
15667 with the remote colo-frame (only for Xen COLO)
15668 compare_timeout: int (optional)
15670 the maximum time to hold a packet from primary_in for comparison
15671 with an incoming packet on secondary_in in milliseconds (de‐
15672 fault: 3000)
15673 expired_scan_cycle: int (optional)
15675 the interval at which colo-compare checks whether packets from
15676 primary have timed out, in milliseconds (default: 3000)
15677 max_queue_size: int (optional)
15679 the maximum number of packets to keep in the queue for comparing
15680 with incoming packets from secondary_in. If the queue is full
15681 and additional packets are received, the additional packets are
15682 dropped. (default: 1024)
15683 vnet_hdr_support: boolean (optional)
15685 if true, vnet header support is enabled (default: false)
15686 Since
15688 2.8
15689 CryptodevBackendProperties (Object)
15691 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
15692 Members
15694 queues: int (optional)
15695 the number of queues for the cryptodev backend. Ignored for
15696 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
15697 (default: 1)
15698 Since
15700 2.8
15701 CryptodevVhostUserProperties (Object)
15703 Properties for cryptodev-vhost-user objects.
15704 Members
15706 chardev: string
15707 the name of a Unix domain socket character device that connects
15708 to the vhost-user server
15709 The members of CryptodevBackendProperties
15711 Since
15713 2.12
15714 DBusVMStateProperties (Object)
15716 Properties for dbus-vmstate objects.
15717 Members
15719 addr: string
15720 the name of the DBus bus to connect to
15721 id-list: string (optional)
15723 a comma separated list of DBus IDs of helpers whose data should
15724 be included in the VM state on migration
15725 Since
15727 5.0
15728 NetfilterInsert (Enum)
15730 Indicates where to insert a netfilter relative to a given other filter.
15731 Values
15733 before insert before the specified filter
15734 behind insert behind the specified filter
15736 Since
15738 5.0
15739 NetfilterProperties (Object)
15741 Properties for objects of classes derived from netfilter.
15742 Members
15744 netdev: string
15745 id of the network device backend to filter
15746 queue: NetFilterDirection (optional)
15748 indicates which queue(s) to filter (default: all)
15749 status: string (optional)
15751 indicates whether the filter is enabled ("on") or disabled
15752 ("off") (default: "on")
15753 position: string (optional)
15755 specifies where the filter should be inserted in the filter
15756 list. "head" means the filter is inserted at the head of the
15757 filter list, before any existing filters. "tail" means the fil‐
15758 ter is inserted at the tail of the filter list, behind any ex‐
15759 isting filters (default). "id=<id>" means the filter is in‐
15760 serted before or behind the filter specified by <id>, depending
15761 on the insert property. (default: "tail")
15762 insert: NetfilterInsert (optional)
15764 where to insert the filter relative to the filter given in posi‐
15765 tion. Ignored if position is "head" or "tail". (default: be‐
15766 hind)
15767 Since
15769 2.5
15770 FilterBufferProperties (Object)
15772 Properties for filter-buffer objects.
15773 Members
15775 interval: int
15776 a non-zero interval in microseconds. All packets arriving in
15777 the given interval are delayed until the end of the interval.
15778 The members of NetfilterProperties
15780 Since
15782 2.5
15783 FilterDumpProperties (Object)
15785 Properties for filter-dump objects.
15786 Members
15788 file: string
15789 the filename where the dumped packets should be stored
15790 maxlen: int (optional)
15792 maximum number of bytes in a packet that are stored (default:
15793 65536)
15794 The members of NetfilterProperties
15796 Since
15798 2.5
15799 FilterMirrorProperties (Object)
15801 Properties for filter-mirror objects.
15802 Members
15804 outdev: string
15805 the name of a character device backend to which all incoming
15806 packets are mirrored
15807 vnet_hdr_support: boolean (optional)
15809 if true, vnet header support is enabled (default: false)
15810 The members of NetfilterProperties
15812 Since
15814 2.6
15815 FilterRedirectorProperties (Object)
15817 Properties for filter-redirector objects.
15818 At least one of indev or outdev must be present. If both are present,
15820 they must not refer to the same character device backend.
15821 Members
15823 indev: string (optional)
15824 the name of a character device backend from which packets are
15825 received and redirected to the filtered network device
15826 outdev: string (optional)
15828 the name of a character device backend to which all incoming
15829 packets are redirected
15830 vnet_hdr_support: boolean (optional)
15832 if true, vnet header support is enabled (default: false)
15833 The members of NetfilterProperties
15835 Since
15837 2.6
15838 FilterRewriterProperties (Object)
15840 Properties for filter-rewriter objects.
15841 Members
15843 vnet_hdr_support: boolean (optional)
15844 if true, vnet header support is enabled (default: false)
15845 The members of NetfilterProperties
15847 Since
15849 2.8
15850 InputBarrierProperties (Object)
15852 Properties for input-barrier objects.
15853 Members
15855 name: string
15856 the screen name as declared in the screens section of bar‐
15857 rier.conf
15858 server: string (optional)
15860 hostname of the Barrier server (default: "localhost")
15861 port: string (optional)
15863 TCP port of the Barrier server (default: "24800")
15864 x-origin: string (optional)
15866 x coordinate of the leftmost pixel on the guest screen (default:
15867 "0")
15868 y-origin: string (optional)
15870 y coordinate of the topmost pixel on the guest screen (default:
15871 "0")
15872 width: string (optional)
15874 the width of secondary screen in pixels (default: "1920")
15875 height: string (optional)
15877 the height of secondary screen in pixels (default: "1080")
15878 Since
15880 4.2
15881 InputLinuxProperties (Object)
15883 Properties for input-linux objects.
15884 Members
15886 evdev: string
15887 the path of the host evdev device to use
15888 grab_all: boolean (optional)
15890 if true, grab is toggled for all devices (e.g. both keyboard and
15891 mouse) instead of just one device (default: false)
15892 repeat: boolean (optional)
15894 enables auto-repeat events (default: false)
15895 grab-toggle: GrabToggleKeys (optional)
15897 the key or key combination that toggles device grab (default:
15898 ctrl-ctrl)
15899 Since
15901 2.6
15902 IothreadProperties (Object)
15904 Properties for iothread objects.
15905 Members
15907 poll-max-ns: int (optional)
15908 the maximum number of nanoseconds to busy wait for events. 0
15909 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
15910 erwise)
15911 poll-grow: int (optional)
15913 the multiplier used to increase the polling time when the algo‐
15914 rithm detects it is missing events due to not polling long
15915 enough. 0 selects a default behaviour (default: 0)
15916 poll-shrink: int (optional)
15918 the divisor used to decrease the polling time when the algorithm
15919 detects it is spending too long polling without encountering
15920 events. 0 selects a default behaviour (default: 0)
15921 aio-max-batch: int (optional)
15923 maximum number of requests in a batch for the AIO engine, 0
15924 means that the engine will use its default (default:0, since
15925 6.1)
15926 Since
15928 2.0
15929 MemoryBackendProperties (Object)
15931 Properties for objects of classes derived from memory-backend.
15932 Members
15934 merge: boolean (optional)
15935 if true, mark the memory as mergeable (default depends on the
15936 machine type)
15937 dump: boolean (optional)
15939 if true, include the memory in core dumps (default depends on
15940 the machine type)
15941 host-nodes: array of int (optional)
15943 the list of NUMA host nodes to bind the memory to
15944 policy: HostMemPolicy (optional)
15946 the NUMA policy (default: 'default')
15947 prealloc: boolean (optional)
15949 if true, preallocate memory (default: false)
15950 prealloc-threads: int (optional)
15952 number of CPU threads to use for prealloc (default: 1)
15953 share: boolean (optional)
15955 if false, the memory is private to QEMU; if true, it is shared
15956 (default: false)
15957 reserve: boolean (optional)
15959 if true, reserve swap space (or huge pages) if applicable (de‐
15960 fault: true) (since 6.1)
15961 size: int
15963 size of the memory region in bytes
15964 x-use-canonical-path-for-ramblock-id: boolean (optional)
15966 if true, the canoncial path is used for ramblock-id. Disable
15967 this for 4.0 machine types or older to allow migration with
15968 newer QEMU versions. This option is considered stable despite
15969 the x- prefix. (default: false generally, but true for machine
15970 types <= 4.0)
15971 Note
15973 prealloc=true and reserve=false cannot be set at the same time. With
15974 reserve=true, the behavior depends on the operating system: for exam‐
15975 ple, Linux will not reserve swap space for shared file mappings -- "not
15976 applicable". In contrast, reserve=false will bail out if it cannot be
15977 configured accordingly.
15978 Since
15980 2.1
15981 MemoryBackendFileProperties (Object)
15983 Properties for memory-backend-file objects.
15984 Members
15986 align: int (optional)
15987 the base address alignment when QEMU mmap(2)s mem-path. Some
15988 backend stores specified by mem-path require an alignment dif‐
15989 ferent than the default one used by QEMU, e.g. the device DAX
15990 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
15991 users can specify the required alignment via this option. 0 se‐
15992 lects a default alignment (currently the page size). (default:
15993 0)
15994 discard-data: boolean (optional)
15996 if true, the file contents can be destroyed when QEMU exits, to
15997 avoid unnecessarily flushing data to the backing file. Note that
15998 discard-data is only an optimization, and QEMU might not discard
15999 file contents if it aborts unexpectedly or is terminated using
16000 SIGKILL. (default: false)
16001 mem-path: string
16003 the path to either a shared memory or huge page filesystem mount
16004 pmem: boolean (optional) (If: defined(CONFIG_LIBPMEM))
16006 specifies whether the backing file specified by mem-path is in
16007 host persistent memory that can be accessed using the SNIA NVM
16008 programming model (e.g. Intel NVDIMM).
16009 readonly: boolean (optional)
16011 if true, the backing file is opened read-only; if false, it is
16012 opened read-write. (default: false)
16013 The members of MemoryBackendProperties
16015 Since
16017 2.1
16018 MemoryBackendMemfdProperties (Object)
16020 Properties for memory-backend-memfd objects.
16021 The share boolean option is true by default with memfd.
16023 Members
16025 hugetlb: boolean (optional)
16026 if true, the file to be created resides in the hugetlbfs
16027 filesystem (default: false)
16028 hugetlbsize: int (optional)
16030 the hugetlb page size on systems that support multiple hugetlb
16031 page sizes (it must be a power of 2 value supported by the sys‐
16032 tem). 0 selects a default page size. This option is ignored if
16033 hugetlb is false. (default: 0)
16034 seal: boolean (optional)
16036 if true, create a sealed-file, which will block further resizing
16037 of the memory (default: true)
16038 The members of MemoryBackendProperties
16040 Since
16042 2.12
16043 PrManagerHelperProperties (Object)
16045 Properties for pr-manager-helper objects.
16046 Members
16048 path: string
16049 the path to a Unix domain socket for connecting to the external
16050 helper
16051 Since
16053 2.11
16054 QtestProperties (Object)
16056 Properties for qtest objects.
16057 Members
16059 chardev: string
16060 the chardev to be used to receive qtest commands on.
16061 log: string (optional)
16063 the path to a log file
16064 Since
16066 6.0
16067 RemoteObjectProperties (Object)
16069 Properties for x-remote-object objects.
16070 Members
16072 fd: string
16073 file descriptor name previously passed via 'getfd' command
16074 devid: string
16076 the id of the device to be associated with the file descriptor
16077 Since
16079 6.0
16080 RngProperties (Object)
16082 Properties for objects of classes derived from rng.
16083 Members
16085 opened: boolean (optional)
16086 if true, the device is opened immediately when applying this op‐
16087 tion and will probably fail when processing the next option.
16088 Don't use; only provided for compatibility. (default: false)
16089 Features
16091 deprecated
16092 Member opened is deprecated. Setting true doesn't make sense,
16093 and false is already the default.
16094 Since
16096 1.3
16097 RngEgdProperties (Object)
16099 Properties for rng-egd objects.
16100 Members
16102 chardev: string
16103 the name of a character device backend that provides the connec‐
16104 tion to the RNG daemon
16105 The members of RngProperties
16107 Since
16109 1.3
16110 RngRandomProperties (Object)
16112 Properties for rng-random objects.
16113 Members
16115 filename: string (optional)
16116 the filename of the device on the host to obtain entropy from
16117 (default: "/dev/urandom")
16118 The members of RngProperties
16120 Since
16122 1.3
16123 SevGuestProperties (Object)
16125 Properties for sev-guest objects.
16126 Members
16128 sev-device: string (optional)
16129 SEV device to use (default: "/dev/sev")
16130 dh-cert-file: string (optional)
16132 guest owners DH certificate (encoded with base64)
16133 session-file: string (optional)
16135 guest owners session parameters (encoded with base64)
16136 policy: int (optional)
16138 SEV policy value (default: 0x1)
16139 handle: int (optional)
16141 SEV firmware handle (default: 0)
16142 cbitpos: int (optional)
16144 C-bit location in page table entry (default: 0)
16145 reduced-phys-bits: int
16147 number of bits in physical addresses that become unavailable
16148 when SEV is enabled
16149 Since
16151 2.12
16152 ObjectType (Enum)
16154 Values
16155 authz-list
16156 Not documented
16157 authz-listfile
16159 Not documented
16160 authz-pam
16162 Not documented
16163 authz-simple
16165 Not documented
16166 can-bus
16168 Not documented
16169 can-host-socketcan
16171 Not documented
16172 colo-compare
16174 Not documented
16175 cryptodev-backend
16177 Not documented
16178 cryptodev-backend-builtin
16180 Not documented
16181 cryptodev-vhost-user (If: defined(CONFIG_VHOST_CRYPTO))
16183 Not documented
16184 dbus-vmstate
16186 Not documented
16187 filter-buffer
16189 Not documented
16190 filter-dump
16192 Not documented
16193 filter-mirror
16195 Not documented
16196 filter-redirector
16198 Not documented
16199 filter-replay
16201 Not documented
16202 filter-rewriter
16204 Not documented
16205 input-barrier
16207 Not documented
16208 input-linux
16210 Not documented
16211 iothread
16213 Not documented
16214 memory-backend-file
16216 Not documented
16217 memory-backend-memfd (If: defined(CONFIG_LINUX))
16219 Not documented
16220 memory-backend-ram
16222 Not documented
16223 pef-guest
16225 Not documented
16226 pr-manager-helper
16228 Not documented
16229 qtest Not documented
16231 rng-builtin
16233 Not documented
16234 rng-egd
16236 Not documented
16237 rng-random
16239 Not documented
16240 secret Not documented
16242 secret_keyring
16244 Not documented
16245 sev-guest
16247 Not documented
16248 s390-pv-guest
16250 Not documented
16251 throttle-group
16253 Not documented
16254 tls-creds-anon
16256 Not documented
16257 tls-creds-psk
16259 Not documented
16260 tls-creds-x509
16262 Not documented
16263 tls-cipher-suites
16265 Not documented
16266 x-remote-object
16268 Not documented
16269 Since
16271 6.0
16272 ObjectOptions (Object)
16274 Describes the options of a user creatable QOM object.
16275 Members
16277 qom-type: ObjectType
16278 the class name for the object to be created
16279 id: string
16281 the name of the new object
16282 The members of AuthZListProperties when qom-type is "authz-list"
16284 The members of AuthZListFileProperties when qom-type is "authz-list‐
16286 file"
16287 The members of AuthZPAMProperties when qom-type is "authz-pam"
16289 The members of AuthZSimpleProperties when qom-type is "authz-simple"
16291 The members of CanHostSocketcanProperties when qom-type is
16293 "can-host-socketcan"
16294 The members of ColoCompareProperties when qom-type is "colo-compare"
16296 The members of CryptodevBackendProperties when qom-type is "cryp‐
16298 todev-backend"
16299 The members of CryptodevBackendProperties when qom-type is "cryp‐
16301 todev-backend-builtin"
16302 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
16304 todev-vhost-user" (If: defined(CONFIG_VHOST_CRYPTO))
16305 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
16307 The members of FilterBufferProperties when qom-type is "filter-buffer"
16309 The members of FilterDumpProperties when qom-type is "filter-dump"
16311 The members of FilterMirrorProperties when qom-type is "filter-mirror"
16313 The members of FilterRedirectorProperties when qom-type is "fil‐
16315 ter-redirector"
16316 The members of NetfilterProperties when qom-type is "filter-replay"
16318 The members of FilterRewriterProperties when qom-type is "fil‐
16320 ter-rewriter"
16321 The members of InputBarrierProperties when qom-type is "input-barrier"
16323 The members of InputLinuxProperties when qom-type is "input-linux"
16325 The members of IothreadProperties when qom-type is "iothread"
16327 The members of MemoryBackendFileProperties when qom-type is "mem‐
16329 ory-backend-file"
16330 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
16332 ory-backend-memfd" (If: defined(CONFIG_LINUX))
16333 The members of MemoryBackendProperties when qom-type is "memory-back‐
16335 end-ram"
16336 The members of PrManagerHelperProperties when qom-type is "pr-man‐
16338 ager-helper"
16339 The members of QtestProperties when qom-type is "qtest"
16341 The members of RngProperties when qom-type is "rng-builtin"
16343 The members of RngEgdProperties when qom-type is "rng-egd"
16345 The members of RngRandomProperties when qom-type is "rng-random"
16347 The members of SecretProperties when qom-type is "secret"
16349 The members of SecretKeyringProperties when qom-type is "se‐
16351 cret_keyring"
16352 The members of SevGuestProperties when qom-type is "sev-guest"
16354 The members of ThrottleGroupProperties when qom-type is "throt‐
16356 tle-group"
16357 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
16359 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
16361 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
16363 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
16365 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
16367 ject"
16368 Since
16370 6.0
16371 object-add (Command)
16373 Create a QOM object.
16374 Arguments
16376 The members of ObjectOptions
16377 Returns
16379 Nothing on success Error if qom-type is not a valid class name
16380 Since
16382 2.0
16383 Example
16385 -> { "execute": "object-add",
16386 "arguments": { "qom-type": "rng-random", "id": "rng1",
16387 "filename": "/dev/hwrng" } }
16388 <- { "return": {} }
16389 object-del (Command)
16391 Remove a QOM object.
16392 Arguments
16394 id: string
16395 the name of the QOM object to remove
16396 Returns
16398 Nothing on success Error if id is not a valid id for a QOM object
16399 Since
16401 2.0
16402 Example
16404 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
16405 <- { "return": {} }
16406
16408 device-list-properties (Command)
16409 List properties associated with a device.
16410 Arguments
16412 typename: string
16413 the type name of a device
16414 Returns
16416 a list of ObjectPropertyInfo describing a devices properties
16417 Note
16419 objects can create properties at runtime, for example to describe links
16420 between different devices and/or objects. These properties are not in‐
16421 cluded in the output of this command.
16422 Since
16424 1.2
16425 device_add (Command)
16427 Arguments
16428 driver: string
16429 the name of the new device's driver
16430 bus: string (optional)
16432 the device's parent bus (device tree path)
16433 id: string (optional)
16435 the device's ID, must be unique
16436 Additional arguments depend on the type.
16437 Add a device.
16439 Notes
16441 1. For detailed information about this command, please refer to the
16442 'docs/qdev-device-use.txt' file.
16443 2. It's possible to list device properties by running QEMU with the
16445 "-device DEVICE,help" command-line argument, where DEVICE is the de‐
16446 vice's name
16447 Example
16449 -> { "execute": "device_add",
16450 "arguments": { "driver": "e1000", "id": "net1",
16451 "bus": "pci.0",
16452 "mac": "52:54:00:12:34:56" } }
16453 <- { "return": {} }
16454 TODO
16456 This command effectively bypasses QAPI completely due to its "addi‐
16457 tional arguments" business. It shouldn't have been added to the schema
16458 in this form. It should be qapified properly, or replaced by a prop‐
16459 erly qapified command.
16460 Since
16462 0.13
16463 device_del (Command)
16465 Remove a device from a guest
16466 Arguments
16468 id: string
16469 the device's ID or QOM path
16470 Returns
16472 Nothing on success If id is not a valid device, DeviceNotFound
16473 Notes
16475 When this command completes, the device may not be removed from the
16476 guest. Hot removal is an operation that requires guest cooperation.
16477 This command merely requests that the guest begin the hot removal
16478 process. Completion of the device removal process is signaled with a
16479 DEVICE_DELETED event. Guest reset will automatically complete removal
16480 for all devices.
16481 Since
16483 0.14
16484 Example
16486 -> { "execute": "device_del",
16487 "arguments": { "id": "net1" } }
16488 <- { "return": {} }
16489 -> { "execute": "device_del",
16491 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
16492 <- { "return": {} }
16493 DEVICE_DELETED (Event)
16495 Emitted whenever the device removal completion is acknowledged by the
16496 guest. At this point, it's safe to reuse the specified device ID. De‐
16497 vice removal can be initiated by the guest or by HMP/QMP commands.
16498 Arguments
16500 device: string (optional)
16501 device name
16502 path: string
16504 device path
16505 Since
16507 1.5
16508 Example
16510 <- { "event": "DEVICE_DELETED",
16511 "data": { "device": "virtio-net-pci-0",
16512 "path": "/machine/peripheral/virtio-net-pci-0" },
16513 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
16514
16516 SysEmuTarget (Enum)
16517 The comprehensive enumeration of QEMU system emulation ("softmmu") tar‐
16518 gets. Run "./configure --help" in the project root directory, and look
16519 for the *-softmmu targets near the "--target-list" option. The individ‐
16520 ual target constants are not documented here, for the time being.
16521 Values
16523 rx since 5.0
16524 avr since 5.1
16526 aarch64
16528 Not documented
16529 alpha Not documented
16531 arm Not documented
16533 cris Not documented
16535 hppa Not documented
16537 i386 Not documented
16539 m68k Not documented
16541 microblaze
16543 Not documented
16544 microblazeel
16546 Not documented
16547 mips Not documented
16549 mips64 Not documented
16551 mips64el
16553 Not documented
16554 mipsel Not documented
16556 nios2 Not documented
16558 or1k Not documented
16560 ppc Not documented
16562 ppc64 Not documented
16564 riscv32
16566 Not documented
16567 riscv64
16569 Not documented
16570 s390x Not documented
16572 sh4 Not documented
16574 sh4eb Not documented
16576 sparc Not documented
16578 sparc64
16580 Not documented
16581 tricore
16583 Not documented
16584 x86_64 Not documented
16586 xtensa Not documented
16588 xtensaeb
16590 Not documented
16591 Notes
16593 The resulting QMP strings can be appended to the "qemu-system-" prefix
16594 to produce the corresponding QEMU executable name. This is true even
16595 for "qemu-system-x86_64".
16596 Since
16598 3.0
16599 CpuS390State (Enum)
16601 An enumeration of cpu states that can be assumed by a virtual S390 CPU
16602 Values
16604 uninitialized
16605 Not documented
16606 stopped
16608 Not documented
16609 check-stop
16611 Not documented
16612 operating
16614 Not documented
16615 load Not documented
16617 Since
16619 2.12
16620 CpuInfoS390 (Object)
16622 Additional information about a virtual S390 CPU
16623 Members
16625 cpu-state: CpuS390State
16626 the virtual CPU's state
16627 Since
16629 2.12
16630 CpuInfoFast (Object)
16632 Information about a virtual CPU
16633 Members
16635 cpu-index: int
16636 index of the virtual CPU
16637 qom-path: string
16639 path to the CPU object in the QOM tree
16640 thread-id: int
16642 ID of the underlying host thread
16643 props: CpuInstanceProperties (optional)
16645 properties describing to which node/socket/core/thread virtual
16646 CPU belongs to, provided if supported by board
16647 target: SysEmuTarget
16649 the QEMU system emulation target, which determines which addi‐
16650 tional fields will be listed (since 3.0)
16651 The members of CpuInfoS390 when target is "s390x"
16653 Since
16655 2.12
16656 query-cpus-fast (Command)
16658 Returns information about all virtual CPUs.
16659 Returns
16661 list of CpuInfoFast
16662 Since
16664 2.12
16665 Example
16667 -> { "execute": "query-cpus-fast" }
16668 <- { "return": [
16669 {
16670 "thread-id": 25627,
16671 "props": {
16672 "core-id": 0,
16673 "thread-id": 0,
16674 "socket-id": 0
16675 },
16676 "qom-path": "/machine/unattached/device[0]",
16677 "arch":"x86",
16678 "target":"x86_64",
16679 "cpu-index": 0
16680 },
16681 {
16682 "thread-id": 25628,
16683 "props": {
16684 "core-id": 0,
16685 "thread-id": 0,
16686 "socket-id": 1
16687 },
16688 "qom-path": "/machine/unattached/device[2]",
16689 "arch":"x86",
16690 "target":"x86_64",
16691 "cpu-index": 1
16692 }
16693 ]
16694 }
16695 MachineInfo (Object)
16697 Information describing a machine.
16698 Members
16700 name: string
16701 the name of the machine
16702 alias: string (optional)
16704 an alias for the machine name
16705 is-default: boolean (optional)
16707 whether the machine is default
16708 cpu-max: int
16710 maximum number of CPUs supported by the machine type (since 1.5)
16711 hotpluggable-cpus: boolean
16713 cpu hotplug via -device is supported (since 2.7)
16714 numa-mem-supported: boolean
16716 true if '-numa node,mem' option is supported by the machine type
16717 and false otherwise (since 4.1)
16718 deprecated: boolean
16720 if true, the machine type is deprecated and may be removed in
16721 future versions of QEMU according to the QEMU deprecation policy
16722 (since 4.1)
16723 default-cpu-type: string (optional)
16725 default CPU model typename if none is requested via the -cpu ar‐
16726 gument. (since 4.2)
16727 default-ram-id: string (optional)
16729 the default ID of initial RAM memory backend (since 5.2)
16730 Since
16732 1.2
16733 query-machines (Command)
16735 Return a list of supported machines
16736 Returns
16738 a list of MachineInfo
16739 Since
16741 1.2
16742 CurrentMachineParams (Object)
16744 Information describing the running machine parameters.
16745 Members
16747 wakeup-suspend-support: boolean
16748 true if the machine supports wake up from suspend
16749 Since
16751 4.0
16752 query-current-machine (Command)
16754 Return information on the current virtual machine.
16755 Returns
16757 CurrentMachineParams
16758 Since
16760 4.0
16761 TargetInfo (Object)
16763 Information describing the QEMU target.
16764 Members
16766 arch: SysEmuTarget
16767 the target architecture
16768 Since
16770 1.2
16771 query-target (Command)
16773 Return information about the target for this QEMU
16774 Returns
16776 TargetInfo
16777 Since
16779 1.2
16780 UuidInfo (Object)
16782 Guest UUID information (Universally Unique Identifier).
16783 Members
16785 UUID: string
16786 the UUID of the guest
16787 Since
16789 0.14
16790 Notes
16792 If no UUID was specified for the guest, a null UUID is returned.
16793 query-uuid (Command)
16795 Query the guest UUID information.
16796 Returns
16798 The UuidInfo for the guest
16799 Since
16801 0.14
16802 Example
16804 -> { "execute": "query-uuid" }
16805 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
16806 GuidInfo (Object)
16808 GUID information.
16809 Members
16811 guid: string
16812 the globally unique identifier
16813 Since
16815 2.9
16816 query-vm-generation-id (Command)
16818 Show Virtual Machine Generation ID
16819 Since
16821 2.9
16822 system_reset (Command)
16824 Performs a hard reset of a guest.
16825 Since
16827 0.14
16828 Example
16830 -> { "execute": "system_reset" }
16831 <- { "return": {} }
16832 system_powerdown (Command)
16834 Requests that a guest perform a powerdown operation.
16835 Since
16837 0.14
16838 Notes
16840 A guest may or may not respond to this command. This command returning
16841 does not indicate that a guest has accepted the request or that it has
16842 shut down. Many guests will respond to this command by prompting the
16843 user in some way.
16844 Example
16846 -> { "execute": "system_powerdown" }
16847 <- { "return": {} }
16848 system_wakeup (Command)
16850 Wake up guest from suspend. If the guest has wake-up from suspend sup‐
16851 port enabled (wakeup-suspend-support flag from query-current-machine),
16852 wake-up guest from suspend if the guest is in SUSPENDED state. Return
16853 an error otherwise.
16854 Since
16856 1.1
16857 Returns
16859 nothing.
16860 Note
16862 prior to 4.0, this command does nothing in case the guest isn't sus‐
16863 pended.
16864 Example
16866 -> { "execute": "system_wakeup" }
16867 <- { "return": {} }
16868 LostTickPolicy (Enum)
16870 Policy for handling lost ticks in timer devices. Ticks end up getting
16871 lost when, for example, the guest is paused.
16872 Values
16874 discard
16875 throw away the missed ticks and continue with future injection
16876 normally. The guest OS will see the timer jump ahead by a po‐
16877 tentially quite significant amount all at once, as if the inter‐
16878 vening chunk of time had simply not existed; needless to say,
16879 such a sudden jump can easily confuse a guest OS which is not
16880 specifically prepared to deal with it. Assuming the guest OS
16881 can deal correctly with the time jump, the time in the guest and
16882 in the host should now match.
16883 delay continue to deliver ticks at the normal rate. The guest OS will
16885 not notice anything is amiss, as from its point of view time
16886 will have continued to flow normally. The time in the guest
16887 should now be behind the time in the host by exactly the amount
16888 of time during which ticks have been missed.
16889 slew deliver ticks at a higher rate to catch up with the missed
16891 ticks. The guest OS will not notice anything is amiss, as from
16892 its point of view time will have continued to flow normally.
16893 Once the timer has managed to catch up with all the missing
16894 ticks, the time in the guest and in the host should match.
16895 Since
16897 2.0
16898 inject-nmi (Command)
16900 Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all
16901 CPUs (ppc64). The command fails when the guest doesn't support inject‐
16902 ing.
16903 Returns
16905 If successful, nothing
16906 Since
16908 0.14
16909 Note
16911 prior to 2.1, this command was only supported for x86 and s390 VMs
16912 Example
16914 -> { "execute": "inject-nmi" }
16915 <- { "return": {} }
16916 KvmInfo (Object)
16918 Information about support for KVM acceleration
16919 Members
16921 enabled: boolean
16922 true if KVM acceleration is active
16923 present: boolean
16925 true if KVM acceleration is built into this executable
16926 Since
16928 0.14
16929 query-kvm (Command)
16931 Returns information about KVM acceleration
16932 Returns
16934 KvmInfo
16935 Since
16937 0.14
16938 Example
16940 -> { "execute": "query-kvm" }
16941 <- { "return": { "enabled": true, "present": true } }
16942 NumaOptionsType (Enum)
16944 Values
16945 node NUMA nodes configuration
16946 dist NUMA distance configuration (since 2.10)
16948 cpu property based CPU(s) to node mapping (Since: 2.10)
16950 hmat-lb
16952 memory latency and bandwidth information (Since: 5.0)
16953 hmat-cache
16955 memory side cache information (Since: 5.0)
16956 Since
16958 2.1
16959 NumaOptions (Object)
16961 A discriminated record of NUMA options. (for OptsVisitor)
16962 Members
16964 type: NumaOptionsType
16965 Not documented
16966 The members of NumaNodeOptions when type is "node"
16968 The members of NumaDistOptions when type is "dist"
16970 The members of NumaCpuOptions when type is "cpu"
16972 The members of NumaHmatLBOptions when type is "hmat-lb"
16974 The members of NumaHmatCacheOptions when type is "hmat-cache"
16976 Since
16978 2.1
16979 NumaNodeOptions (Object)
16981 Create a guest NUMA node. (for OptsVisitor)
16982 Members
16984 nodeid: int (optional)
16985 NUMA node ID (increase by 1 from 0 if omitted)
16986 cpus: array of int (optional)
16988 VCPUs belonging to this node (assign VCPUS round-robin
16990 if omitted)
16991 mem: int (optional)
16993 memory size of this node; mutually exclusive with memdev.
16994 Equally divide total memory among nodes if both mem and memdev
16995 are omitted.
16996 memdev: string (optional)
16998 memory backend object. If specified for one node, it must be
16999 specified for all nodes.
17000 initiator: int (optional)
17002 defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the
17003 nodeid which has the memory controller responsible for this NUMA
17004 node. This field provides additional information as to the ini‐
17005 tiator node that is closest (as in directly attached) to this
17006 node, and therefore has the best performance (since 5.0)
17007 Since
17009 2.1
17010 NumaDistOptions (Object)
17012 Set the distance between 2 NUMA nodes.
17013 Members
17015 src: int
17016 source NUMA node.
17017 dst: int
17019 destination NUMA node.
17020 val: int
17022 NUMA distance from source node to destination node. When a node
17023 is unreachable from another node, set the distance between them
17024 to 255.
17025 Since
17027 2.10
17028 X86CPURegister32 (Enum)
17030 A X86 32-bit register
17031 Values
17033 EAX Not documented
17034 EBX Not documented
17036 ECX Not documented
17038 EDX Not documented
17040 ESP Not documented
17042 EBP Not documented
17044 ESI Not documented
17046 EDI Not documented
17048 Since
17050 1.5
17051 X86CPUFeatureWordInfo (Object)
17053 Information about a X86 CPU feature word
17054 Members
17056 cpuid-input-eax: int
17057 Input EAX value for CPUID instruction for that feature word
17058 cpuid-input-ecx: int (optional)
17060 Input ECX value for CPUID instruction for that feature word
17061 cpuid-register: X86CPURegister32
17063 Output register containing the feature bits
17064 features: int
17066 value of output register, containing the feature bits
17067 Since
17069 1.5
17070 DummyForceArrays (Object)
17072 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList inter‐
17073 nally
17074 Members
17076 unused: array of X86CPUFeatureWordInfo
17077 Not documented
17078 Since
17080 2.5
17081 NumaCpuOptions (Object)
17083 Option "-numa cpu" overrides default cpu to node mapping. It accepts
17084 the same set of cpu properties as returned by query-hotplug‐
17085 gable-cpus[].props, where node-id could be used to override default
17086 node mapping.
17087 Members
17089 The members of CpuInstanceProperties
17090 Since
17092 2.10
17093 HmatLBMemoryHierarchy (Enum)
17095 The memory hierarchy in the System Locality Latency and Bandwidth In‐
17096 formation Structure of HMAT (Heterogeneous Memory Attribute Table)
17097 For more information about HmatLBMemoryHierarchy, see chapter 5.2.27.4:
17099 Table 5-146: Field "Flags" of ACPI 6.3 spec.
17100 Values
17102 memory the structure represents the memory performance
17103 first-level
17105 first level of memory side cache
17106 second-level
17108 second level of memory side cache
17109 third-level
17111 third level of memory side cache
17112 Since
17114 5.0
17115 HmatLBDataType (Enum)
17117 Data type in the System Locality Latency and Bandwidth Information
17118 Structure of HMAT (Heterogeneous Memory Attribute Table)
17119 For more information about HmatLBDataType, see chapter 5.2.27.4: Table
17121 5-146: Field "Data Type" of ACPI 6.3 spec.
17122 Values
17124 access-latency
17125 access latency (nanoseconds)
17126 read-latency
17128 read latency (nanoseconds)
17129 write-latency
17131 write latency (nanoseconds)
17132 access-bandwidth
17134 access bandwidth (Bytes per second)
17135 read-bandwidth
17137 read bandwidth (Bytes per second)
17138 write-bandwidth
17140 write bandwidth (Bytes per second)
17141 Since
17143 5.0
17144 NumaHmatLBOptions (Object)
17146 Set the system locality latency and bandwidth information between Ini‐
17147 tiator and Target proximity Domains.
17148 For more information about NumaHmatLBOptions, see chapter 5.2.27.4: Ta‐
17150 ble 5-146 of ACPI 6.3 spec.
17151 Members
17153 initiator: int
17154 the Initiator Proximity Domain.
17155 target: int
17157 the Target Proximity Domain.
17158 hierarchy: HmatLBMemoryHierarchy
17160 the Memory Hierarchy. Indicates the performance of memory or
17161 side cache.
17162 data-type: HmatLBDataType
17164 presents the type of data, access/read/write latency or hit la‐
17165 tency.
17166 latency: int (optional)
17168 the value of latency from initiator to target proximity domain,
17169 the latency unit is "ns(nanosecond)".
17170 bandwidth: int (optional)
17172 the value of bandwidth between initiator and target proximity
17173 domain, the bandwidth unit is "Bytes per second".
17174 Since
17176 5.0
17177 HmatCacheAssociativity (Enum)
17179 Cache associativity in the Memory Side Cache Information Structure of
17180 HMAT
17181 For more information of HmatCacheAssociativity, see chapter 5.2.27.5:
17183 Table 5-147 of ACPI 6.3 spec.
17184 Values
17186 none
17187 None (no memory side cache in this proximity domain,
17189 or cache associativity unknown)
17190 direct Direct Mapped
17192 complex
17194 Complex Cache Indexing (implementation specific)
17195 Since
17197 5.0
17198 HmatCacheWritePolicy (Enum)
17200 Cache write policy in the Memory Side Cache Information Structure of
17201 HMAT
17202 For more information of HmatCacheWritePolicy, see chapter 5.2.27.5: Ta‐
17204 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
17205 Values
17207 none None (no memory side cache in this proximity domain, or cache
17208 write policy unknown)
17209 write-back
17211 Write Back (WB)
17212 write-through
17214 Write Through (WT)
17215 Since
17217 5.0
17218 NumaHmatCacheOptions (Object)
17220 Set the memory side cache information for a given memory domain.
17221 For more information of NumaHmatCacheOptions, see chapter 5.2.27.5: Ta‐
17223 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
17224 Members
17226 node-id: int
17227 the memory proximity domain to which the memory belongs.
17228 size: int
17230 the size of memory side cache in bytes.
17231 level: int
17233 the cache level described in this structure.
17234 associativity: HmatCacheAssociativity
17236 the cache associativity, none/direct-mapped/complex(complex
17237 cache indexing).
17238 policy: HmatCacheWritePolicy
17240 the write policy, none/write-back/write-through.
17241 line: int
17243 the cache Line size in bytes.
17244 Since
17246 5.0
17247 memsave (Command)
17249 Save a portion of guest memory to a file.
17250 Arguments
17252 val: int
17253 the virtual address of the guest to start from
17254 size: int
17256 the size of memory region to save
17257 filename: string
17259 the file to save the memory to as binary data
17260 cpu-index: int (optional)
17262 the index of the virtual CPU to use for translating the virtual
17263 address (defaults to CPU 0)
17264 Returns
17266 Nothing on success
17267 Since
17269 0.14
17270 Notes
17272 Errors were not reliably returned until 1.1
17273 Example
17275 -> { "execute": "memsave",
17276 "arguments": { "val": 10,
17277 "size": 100,
17278 "filename": "/tmp/virtual-mem-dump" } }
17279 <- { "return": {} }
17280 pmemsave (Command)
17282 Save a portion of guest physical memory to a file.
17283 Arguments
17285 val: int
17286 the physical address of the guest to start from
17287 size: int
17289 the size of memory region to save
17290 filename: string
17292 the file to save the memory to as binary data
17293 Returns
17295 Nothing on success
17296 Since
17298 0.14
17299 Notes
17301 Errors were not reliably returned until 1.1
17302 Example
17304 -> { "execute": "pmemsave",
17305 "arguments": { "val": 10,
17306 "size": 100,
17307 "filename": "/tmp/physical-mem-dump" } }
17308 <- { "return": {} }
17309 Memdev (Object)
17311 Information about memory backend
17312 Members
17314 id: string (optional)
17315 backend's ID if backend has 'id' property (since 2.9)
17316 size: int
17318 memory backend size
17319 merge: boolean
17321 whether memory merge support is enabled
17322 dump: boolean
17324 whether memory backend's memory is included in a core dump
17325 prealloc: boolean
17327 whether memory was preallocated
17328 share: boolean
17330 whether memory is private to QEMU or shared (since 6.1)
17331 reserve: boolean (optional)
17333 whether swap space (or huge pages) was reserved if applicable.
17334 This corresponds to the user configuration and not the actual
17335 behavior implemented in the OS to perform the reservation. For
17336 example, Linux will never reserve swap space for shared file
17337 mappings. (since 6.1)
17338 host-nodes: array of int
17340 host nodes for its memory policy
17341 policy: HostMemPolicy
17343 memory policy of memory backend
17344 Since
17346 2.1
17347 query-memdev (Command)
17349 Returns information for all memory backends.
17350 Returns
17352 a list of Memdev.
17353 Since
17355 2.1
17356 Example
17358 -> { "execute": "query-memdev" }
17359 <- { "return": [
17360 {
17361 "id": "mem1",
17362 "size": 536870912,
17363 "merge": false,
17364 "dump": true,
17365 "prealloc": false,
17366 "host-nodes": [0, 1],
17367 "policy": "bind"
17368 },
17369 {
17370 "size": 536870912,
17371 "merge": false,
17372 "dump": true,
17373 "prealloc": true,
17374 "host-nodes": [2, 3],
17375 "policy": "preferred"
17376 }
17377 ]
17378 }
17379 CpuInstanceProperties (Object)
17381 List of properties to be used for hotplugging a CPU instance, it should
17382 be passed by management with device_add command when a CPU is being
17383 hotplugged.
17384 Members
17386 node-id: int (optional)
17387 NUMA node ID the CPU belongs to
17388 socket-id: int (optional)
17390 socket number within node/board the CPU belongs to
17391 die-id: int (optional)
17393 die number within node/board the CPU belongs to (Since 4.1)
17394 core-id: int (optional)
17396 core number within die the CPU belongs to
17397 thread-id: int (optional)
17399 thread number within core the CPU belongs to
17400 Note
17402 currently there are 5 properties that could be present but management
17403 should be prepared to pass through other properties with device_add
17404 command to allow for future interface extension. This also requires the
17405 filed names to be kept in sync with the properties passed to -de‐
17406 vice/device_add.
17407 Since
17409 2.7
17410 HotpluggableCPU (Object)
17412 Members
17413 type: string
17414 CPU object type for usage with device_add command
17415 props: CpuInstanceProperties
17417 list of properties to be used for hotplugging CPU
17418 vcpus-count: int
17420 number of logical VCPU threads HotpluggableCPU provides
17421 qom-path: string (optional)
17423 link to existing CPU object if CPU is present or omitted if CPU
17424 is not present.
17425 Since
17427 2.7
17428 query-hotpluggable-cpus (Command)
17430 TODO
17431 Better documentation; currently there is none.
17432 Returns
17434 a list of HotpluggableCPU objects.
17435 Since
17437 2.7
17438 Example
17440 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
17441 -> { "execute": "query-hotpluggable-cpus" }
17443 <- {"return": [
17444 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
17445 "vcpus-count": 1 },
17446 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
17447 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
17448 ]}'
17449 For pc machine type started with -smp 1,maxcpus=2:
17451 -> { "execute": "query-hotpluggable-cpus" }
17453 <- {"return": [
17454 {
17455 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
17456 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
17457 },
17458 {
17459 "qom-path": "/machine/unattached/device[0]",
17460 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
17461 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
17462 }
17463 ]}
17464 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
17466 (Since: 2.11):
17467 -> { "execute": "query-hotpluggable-cpus" }
17469 <- {"return": [
17470 {
17471 "type": "qemu-s390x-cpu", "vcpus-count": 1,
17472 "props": { "core-id": 1 }
17473 },
17474 {
17475 "qom-path": "/machine/unattached/device[0]",
17476 "type": "qemu-s390x-cpu", "vcpus-count": 1,
17477 "props": { "core-id": 0 }
17478 }
17479 ]}
17480 set-numa-node (Command)
17482 Runtime equivalent of '-numa' CLI option, available at preconfigure
17483 stage to configure numa mapping before initializing machine.
17484 Since 3.0
17486 Arguments
17488 The members of NumaOptions
17489 balloon (Command)
17491 Request the balloon driver to change its balloon size.
17492 Arguments
17494 value: int
17495 the target logical size of the VM in bytes. We can deduce the
17496 size of the balloon using this formula:
17497 logical_vm_size = vm_ram_size - balloon_size
17498 From it we have: balloon_size = vm_ram_size - value
17500 Returns
17502 • Nothing on success
17503 • If the balloon driver is enabled but not functional because the KVM
17505 kernel module cannot support it, KvmMissingCap
17506 • If no balloon device is present, DeviceNotActive
17508 Notes
17510 This command just issues a request to the guest. When it returns, the
17511 balloon size may not have changed. A guest can change the balloon size
17512 independent of this command.
17513 Since
17515 0.14
17516 Example
17518 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
17519 <- { "return": {} }
17520 With a 2.5GiB guest this command inflated the ballon to 3GiB.
17522 BalloonInfo (Object)
17524 Information about the guest balloon device.
17525 Members
17527 actual: int
17528 the logical size of the VM in bytes Formula used: logi‐
17529 cal_vm_size = vm_ram_size - balloon_size
17530 Since
17532 0.14
17533 query-balloon (Command)
17535 Return information about the balloon device.
17536 Returns
17538 • BalloonInfo on success
17539 • If the balloon driver is enabled but not functional because the KVM
17541 kernel module cannot support it, KvmMissingCap
17542 • If no balloon device is present, DeviceNotActive
17544 Since
17546 0.14
17547 Example
17549 -> { "execute": "query-balloon" }
17550 <- { "return": {
17551 "actual": 1073741824,
17552 }
17553 }
17554 BALLOON_CHANGE (Event)
17556 Emitted when the guest changes the actual BALLOON level. This value is
17557 equivalent to the actual field return by the 'query-balloon' command
17558 Arguments
17560 actual: int
17561 the logical size of the VM in bytes Formula used: logi‐
17562 cal_vm_size = vm_ram_size - balloon_size
17563 Note
17565 this event is rate-limited.
17566 Since
17568 1.2
17569 Example
17571 <- { "event": "BALLOON_CHANGE",
17572 "data": { "actual": 944766976 },
17573 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
17574 MemoryInfo (Object)
17576 Actual memory information in bytes.
17577 Members
17579 base-memory: int
17580 size of "base" memory specified with command line option -m.
17581 plugged-memory: int (optional)
17583 size of memory that can be hot-unplugged. This field is omitted
17584 if target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE
17585 not defined at build time).
17586 Since
17588 2.11
17589 query-memory-size-summary (Command)
17591 Return the amount of initially allocated and present hotpluggable (if
17592 enabled) memory in bytes.
17593 Example
17595 -> { "execute": "query-memory-size-summary" }
17596 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
17597 Since
17599 2.11
17600 PCDIMMDeviceInfo (Object)
17602 PCDIMMDevice state information
17603 Members
17605 id: string (optional)
17606 device's ID
17607 addr: int
17609 physical address, where device is mapped
17610 size: int
17612 size of memory that the device provides
17613 slot: int
17615 slot number at which device is plugged in
17616 node: int
17618 NUMA node number where device is plugged in
17619 memdev: string
17621 memory backend linked with device
17622 hotplugged: boolean
17624 true if device was hotplugged
17625 hotpluggable: boolean
17627 true if device if could be added/removed while machine is run‐
17628 ning
17629 Since
17631 2.1
17632 VirtioPMEMDeviceInfo (Object)
17634 VirtioPMEM state information
17635 Members
17637 id: string (optional)
17638 device's ID
17639 memaddr: int
17641 physical address in memory, where device is mapped
17642 size: int
17644 size of memory that the device provides
17645 memdev: string
17647 memory backend linked with device
17648 Since
17650 4.1
17651 VirtioMEMDeviceInfo (Object)
17653 VirtioMEMDevice state information
17654 Members
17656 id: string (optional)
17657 device's ID
17658 memaddr: int
17660 physical address in memory, where device is mapped
17661 requested-size: int
17663 the user requested size of the device
17664 size: int
17666 the (current) size of memory that the device provides
17667 max-size: int
17669 the maximum size of memory that the device can provide
17670 block-size: int
17672 the block size of memory that the device provides
17673 node: int
17675 NUMA node number where device is assigned to
17676 memdev: string
17678 memory backend linked with the region
17679 Since
17681 5.1
17682 MemoryDeviceInfo (Object)
17684 Union containing information about a memory device
17685 nvdimm is included since 2.12. virtio-pmem is included since 4.1. vir‐
17687 tio-mem is included since 5.1.
17688 Members
17690 type One of dimm, nvdimm, virtio-pmem, virtio-mem
17691 data: PCDIMMDeviceInfo when type is "dimm"
17693 data: PCDIMMDeviceInfo when type is "nvdimm"
17695 data: VirtioPMEMDeviceInfo when type is "virtio-pmem"
17697 data: VirtioMEMDeviceInfo when type is "virtio-mem"
17699 Since
17701 2.1
17702 query-memory-devices (Command)
17704 Lists available memory devices and their state
17705 Since
17707 2.1
17708 Example
17710 -> { "execute": "query-memory-devices" }
17711 <- { "return": [ { "data":
17712 { "addr": 5368709120,
17713 "hotpluggable": true,
17714 "hotplugged": true,
17715 "id": "d1",
17716 "memdev": "/objects/memX",
17717 "node": 0,
17718 "size": 1073741824,
17719 "slot": 0},
17720 "type": "dimm"
17721 } ] }
17722 MEMORY_DEVICE_SIZE_CHANGE (Event)
17724 Emitted when the size of a memory device changes. Only emitted for mem‐
17725 ory devices that can actually change the size (e.g., virtio-mem due to
17726 guest action).
17727 Arguments
17729 id: string (optional)
17730 device's ID
17731 size: int
17733 the new size of memory that the device provides
17734 Note
17736 this event is rate-limited.
17737 Since
17739 5.1
17740 Example
17742 <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
17743 "data": { "id": "vm0", "size": 1073741824},
17744 "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
17745 MEM_UNPLUG_ERROR (Event)
17747 Emitted when memory hot unplug error occurs.
17748 Arguments
17750 device: string
17751 device name
17752 msg: string
17754 Informative message
17755 Since
17757 2.4
17758 Example
17760 <- { "event": "MEM_UNPLUG_ERROR"
17761 "data": { "device": "dimm1",
17762 "msg": "acpi: device unplug for unsupported device"
17763 },
17764 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
17765 SMPConfiguration (Object)
17767 Schema for CPU topology configuration. A missing value lets QEMU fig‐
17768 ure out a suitable value based on the ones that are provided.
17769 Members
17771 cpus: int (optional)
17772 number of virtual CPUs in the virtual machine
17773 sockets: int (optional)
17775 number of sockets in the CPU topology
17776 dies: int (optional)
17778 number of dies per socket in the CPU topology
17779 cores: int (optional)
17781 number of cores per thread in the CPU topology
17782 threads: int (optional)
17784 number of threads per core in the CPU topology
17785 maxcpus: int (optional)
17787 maximum number of hotpluggable virtual CPUs in the virtual ma‐
17788 chine
17789 Since
17791 6.1
17792 CpuModelInfo (Object)
17794 Virtual CPU model.
17795 A CPU model consists of the name of a CPU definition, to which delta
17797 changes are applied (e.g. features added/removed). Most magic values
17798 that an architecture might require should be hidden behind the name.
17799 However, if required, architectures can expose relevant properties.
17800 Members
17802 name: string
17803 the name of the CPU definition the model is based on
17804 props: value (optional)
17806 a dictionary of QOM properties to be applied
17807 Since
17809 2.8
17810 CpuModelExpansionType (Enum)
17812 An enumeration of CPU model expansion types.
17813 Values
17815 static Expand to a static CPU model, a combination of a static base
17816 model name and property delta changes. As the static base model
17817 will never change, the expanded CPU model will be the same, in‐
17818 dependent of QEMU version, machine type, machine options, and
17819 accelerator options. Therefore, the resulting model can be used
17820 by tooling without having to specify a compatibility machine -
17821 e.g. when displaying the "host" model. The static CPU models are
17822 migration-safe.
17823 full Expand all properties. The produced model is not guaranteed to
17825 be migration-safe, but allows tooling to get an insight and work
17826 with model details.
17827 Note
17829 When a non-migration-safe CPU model is expanded in static mode, some
17830 features enabled by the CPU model may be omitted, because they can't be
17831 implemented by a static CPU model definition (e.g. cache info
17832 passthrough and PMU passthrough in x86). If you need an accurate repre‐
17833 sentation of the features enabled by a non-migration-safe CPU model,
17834 use full. If you need a static representation that will keep ABI com‐
17835 patibility even when changing QEMU version or machine-type, use static
17836 (but keep in mind that some features may be omitted).
17837 Since
17839 2.8
17840 CpuModelCompareResult (Enum)
17842 An enumeration of CPU model comparison results. The result is usually
17843 calculated using e.g. CPU features or CPU generations.
17844 Values
17846 incompatible
17847 If model A is incompatible to model B, model A is not guaranteed
17848 to run where model B runs and the other way around.
17849 identical
17851 If model A is identical to model B, model A is guaranteed to run
17852 where model B runs and the other way around.
17853 superset
17855 If model A is a superset of model B, model B is guaranteed to
17856 run where model A runs. There are no guarantees about the other
17857 way.
17858 subset If model A is a subset of model B, model A is guaranteed to run
17860 where model B runs. There are no guarantees about the other way.
17861 Since
17863 2.8
17864 CpuModelBaselineInfo (Object)
17866 The result of a CPU model baseline.
17867 Members
17869 model: CpuModelInfo
17870 the baselined CpuModelInfo.
17871 Since
17873 2.8
17874 If
17876 defined(TARGET_S390X)
17877 CpuModelCompareInfo (Object)
17879 The result of a CPU model comparison.
17880 Members
17882 result: CpuModelCompareResult
17883 The result of the compare operation.
17884 responsible-properties: array of string
17886 List of properties that led to the comparison result not being
17887 identical.
17888 responsible-properties is a list of QOM property names that led to both
17889 CPUs not being detected as identical. For identical models, this list
17890 is empty. If a QOM property is read-only, that means there's no known
17891 way to make the CPU models identical. If the special property name
17892 "type" is included, the models are by definition not identical and can‐
17893 not be made identical.
17894 Since
17896 2.8
17897 If
17899 defined(TARGET_S390X)
17900 query-cpu-model-comparison (Command)
17902 Compares two CPU models, returning how they compare in a specific con‐
17903 figuration. The results indicates how both models compare regarding
17904 runnability. This result can be used by tooling to make decisions if a
17905 certain CPU model will run in a certain configuration or if a compati‐
17906 ble CPU model has to be created by baselining.
17907 Usually, a CPU model is compared against the maximum possible CPU model
17909 of a certain configuration (e.g. the "host" model for KVM). If that CPU
17910 model is identical or a subset, it will run in that configuration.
17911 The result returned by this command may be affected by:
17913 • QEMU version: CPU models may look different depending on the QEMU
17915 version. (Except for CPU models reported as "static" in
17916 query-cpu-definitions.)
17917 • machine-type: CPU model may look different depending on the ma‐
17919 chine-type. (Except for CPU models reported as "static" in
17920 query-cpu-definitions.)
17921 • machine options (including accelerator): in some architectures, CPU
17923 models may look different depending on machine and accelerator op‐
17924 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
17925 nitions.)
17926 • "-cpu" arguments and global properties: arguments to the -cpu option
17928 and global properties may affect expansion of CPU models. Using
17929 query-cpu-model-expansion while using these is not advised.
17930 Some architectures may not support comparing CPU models. s390x supports
17932 comparing CPU models.
17933 Arguments
17935 modela: CpuModelInfo
17936 Not documented
17937 modelb: CpuModelInfo
17939 Not documented
17940 Returns
17942 a CpuModelBaselineInfo. Returns an error if comparing CPU models is not
17943 supported, if a model cannot be used, if a model contains an unknown
17944 cpu definition name, unknown properties or properties with wrong types.
17945 Note
17947 this command isn't specific to s390x, but is only implemented on this
17948 architecture currently.
17949 Since
17951 2.8
17952 If
17954 defined(TARGET_S390X)
17955 query-cpu-model-baseline (Command)
17957 Baseline two CPU models, creating a compatible third model. The created
17958 model will always be a static, migration-safe CPU model (see "static"
17959 CPU model expansion for details).
17960 This interface can be used by tooling to create a compatible CPU model
17962 out two CPU models. The created CPU model will be identical to or a
17963 subset of both CPU models when comparing them. Therefore, the created
17964 CPU model is guaranteed to run where the given CPU models run.
17965 The result returned by this command may be affected by:
17967 • QEMU version: CPU models may look different depending on the QEMU
17969 version. (Except for CPU models reported as "static" in
17970 query-cpu-definitions.)
17971 • machine-type: CPU model may look different depending on the ma‐
17973 chine-type. (Except for CPU models reported as "static" in
17974 query-cpu-definitions.)
17975 • machine options (including accelerator): in some architectures, CPU
17977 models may look different depending on machine and accelerator op‐
17978 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
17979 nitions.)
17980 • "-cpu" arguments and global properties: arguments to the -cpu option
17982 and global properties may affect expansion of CPU models. Using
17983 query-cpu-model-expansion while using these is not advised.
17984 Some architectures may not support baselining CPU models. s390x sup‐
17986 ports baselining CPU models.
17987 Arguments
17989 modela: CpuModelInfo
17990 Not documented
17991 modelb: CpuModelInfo
17993 Not documented
17994 Returns
17996 a CpuModelBaselineInfo. Returns an error if baselining CPU models is
17997 not supported, if a model cannot be used, if a model contains an un‐
17998 known cpu definition name, unknown properties or properties with wrong
17999 types.
18000 Note
18002 this command isn't specific to s390x, but is only implemented on this
18003 architecture currently.
18004 Since
18006 2.8
18007 If
18009 defined(TARGET_S390X)
18010 CpuModelExpansionInfo (Object)
18012 The result of a cpu model expansion.
18013 Members
18015 model: CpuModelInfo
18016 the expanded CpuModelInfo.
18017 Since
18019 2.8
18020 If
18022 defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)
18023 query-cpu-model-expansion (Command)
18025 Expands a given CPU model (or a combination of CPU model + additional
18026 options) to different granularities, allowing tooling to get an under‐
18027 standing what a specific CPU model looks like in QEMU under a certain
18028 configuration.
18029 This interface can be used to query the "host" CPU model.
18031 The data returned by this command may be affected by:
18033 • QEMU version: CPU models may look different depending on the QEMU
18035 version. (Except for CPU models reported as "static" in
18036 query-cpu-definitions.)
18037 • machine-type: CPU model may look different depending on the ma‐
18039 chine-type. (Except for CPU models reported as "static" in
18040 query-cpu-definitions.)
18041 • machine options (including accelerator): in some architectures, CPU
18043 models may look different depending on machine and accelerator op‐
18044 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
18045 nitions.)
18046 • "-cpu" arguments and global properties: arguments to the -cpu option
18048 and global properties may affect expansion of CPU models. Using
18049 query-cpu-model-expansion while using these is not advised.
18050 Some architectures may not support all expansion types. s390x supports
18052 "full" and "static". Arm only supports "full".
18053 Arguments
18055 type: CpuModelExpansionType
18056 Not documented
18057 model: CpuModelInfo
18059 Not documented
18060 Returns
18062 a CpuModelExpansionInfo. Returns an error if expanding CPU models is
18063 not supported, if the model cannot be expanded, if the model contains
18064 an unknown CPU definition name, unknown properties or properties with a
18065 wrong type. Also returns an error if an expansion type is not sup‐
18066 ported.
18067 Since
18069 2.8
18070 If
18072 defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)
18073 CpuDefinitionInfo (Object)
18075 Virtual CPU definition.
18076 Members
18078 name: string
18079 the name of the CPU definition
18080 migration-safe: boolean (optional)
18082 whether a CPU definition can be safely used for migration in
18083 combination with a QEMU compatibility machine when migrating be‐
18084 tween different QEMU versions and between hosts with different
18085 sets of (hardware or software) capabilities. If not provided,
18086 information is not available and callers should not assume the
18087 CPU definition to be migration-safe. (since 2.8)
18088 static: boolean
18090 whether a CPU definition is static and will not change depending
18091 on QEMU version, machine type, machine options and accelerator
18092 options. A static model is always migration-safe. (since 2.8)
18093 unavailable-features: array of string (optional)
18095 List of properties that prevent the CPU model from running in
18096 the current host. (since 2.8)
18097 typename: string
18099 Type name that can be used as argument to device-list-proper‐
18100 ties, to introspect properties configurable using -cpu or
18101 -global. (since 2.9)
18102 alias-of: string (optional)
18104 Name of CPU model this model is an alias for. The target of the
18105 CPU model alias may change depending on the machine type. Man‐
18106 agement software is supposed to translate CPU model aliases in
18107 the VM configuration, because aliases may stop being migra‐
18108 tion-safe in the future (since 4.1)
18109 deprecated: boolean
18111 If true, this CPU model is deprecated and may be removed in in
18112 some future version of QEMU according to the QEMU deprecation
18113 policy. (since 5.2)
18114 unavailable-features is a list of QOM property names that represent CPU
18115 model attributes that prevent the CPU from running. If the QOM prop‐
18116 erty is read-only, that means there's no known way to make the CPU
18117 model run in the current host. Implementations that choose not to pro‐
18118 vide specific information return the property name "type". If the
18119 property is read-write, it means that it MAY be possible to run the CPU
18120 model in the current host if that property is changed. Management soft‐
18121 ware can use it as hints to suggest or choose an alternative for the
18122 user, or just to generate meaningful error messages explaining why the
18123 CPU model can't be used. If unavailable-features is an empty list, the
18124 CPU model is runnable using the current host and machine-type. If un‐
18125 available-features is not present, runnability information for the CPU
18126 is not available.
18127 Since
18129 1.2
18130 If
18132 defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) ||
18133 defined(TARGET_S390X) || defined(TARGET_MIPS)
18134 query-cpu-definitions (Command)
18136 Return a list of supported virtual CPU definitions
18137 Returns
18139 a list of CpuDefInfo
18140 Since
18142 1.2
18143 If
18145 defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) ||
18146 defined(TARGET_S390X) || defined(TARGET_MIPS)
18147
18149 ReplayMode (Enum)
18150 Mode of the replay subsystem.
18151 Values
18153 none normal execution mode. Replay or record are not enabled.
18154 record record mode. All non-deterministic data is written into the re‐
18156 play log.
18157 play replay mode. Non-deterministic data required for system execu‐
18159 tion is read from the log.
18160 Since
18162 2.5
18163 ReplayInfo (Object)
18165 Record/replay information.
18166 Members
18168 mode: ReplayMode
18169 current mode.
18170 filename: string (optional)
18172 name of the record/replay log file. It is present only in
18173 record or replay modes, when the log is recorded or replayed.
18174 icount: int
18176 current number of executed instructions.
18177 Since
18179 5.2
18180 query-replay (Command)
18182 Retrieve the record/replay information. It includes current instruc‐
18183 tion count which may be used for replay-break and replay-seek commands.
18184 Returns
18186 record/replay information.
18187 Since
18189 5.2
18190 Example
18192 -> { "execute": "query-replay" }
18193 <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
18194 replay-break (Command)
18196 Set replay breakpoint at instruction count icount. Execution stops
18197 when the specified instruction is reached. There can be at most one
18198 breakpoint. When breakpoint is set, any prior one is removed. The
18199 breakpoint may be set only in replay mode and only "in the future",
18200 i.e. at instruction counts greater than the current one. The current
18201 instruction count can be observed with query-replay.
18202 Arguments
18204 icount: int
18205 instruction count to stop at
18206 Since
18208 5.2
18209 Example
18211 -> { "execute": "replay-break", "data": { "icount": 220414 } }
18212 replay-delete-break (Command)
18214 Remove replay breakpoint which was set with replay-break. The command
18215 is ignored when there are no replay breakpoints.
18216 Since
18218 5.2
18219 Example
18221 -> { "execute": "replay-delete-break" }
18222 replay-seek (Command)
18224 Automatically proceed to the instruction count icount, when replaying
18225 the execution. The command automatically loads nearest snapshot and re‐
18226 plays the execution to find the desired instruction. When there is no
18227 preceding snapshot or the execution is not replayed, then the command
18228 fails. icount for the reference may be obtained with query-replay com‐
18229 mand.
18230 Arguments
18232 icount: int
18233 target instruction count
18234 Since
18236 5.2
18237 Example
18239 -> { "execute": "replay-seek", "data": { "icount": 220414 } }
18240
18242 YankInstanceType (Enum)
18243 An enumeration of yank instance types. See YankInstance for more infor‐
18244 mation.
18245 Values
18247 block-node
18248 Not documented
18249 chardev
18251 Not documented
18252 migration
18254 Not documented
18255 Since
18257 6.0
18258 YankInstanceBlockNode (Object)
18260 Specifies which block graph node to yank. See YankInstance for more in‐
18261 formation.
18262 Members
18264 node-name: string
18265 the name of the block graph node
18266 Since
18268 6.0
18269 YankInstanceChardev (Object)
18271 Specifies which character device to yank. See YankInstance for more in‐
18272 formation.
18273 Members
18275 id: string
18276 the chardev's ID
18277 Since
18279 6.0
18280 YankInstance (Object)
18282 A yank instance can be yanked with the yank qmp command to recover from
18283 a hanging QEMU.
18284 Currently implemented yank instances:
18286 • nbd block device: Yanking it will shut down the connection to
18288 the nbd server without attempting to reconnect.
18289 • socket chardev: Yanking it will shut down the connected
18291 socket.
18292 • migration: Yanking it will shut down all migration connec‐
18294 tions. Unlike migrate_cancel, it will not notify the migration
18295 process, so migration will go into failed state, instead of
18296 cancelled state. yank should be used to recover from hangs.
18297 Members
18299 type: YankInstanceType
18300 Not documented
18301 The members of YankInstanceBlockNode when type is "block-node"
18303 The members of YankInstanceChardev when type is "chardev"
18305 Since
18307 6.0
18308 yank (Command)
18310 Try to recover from hanging QEMU by yanking the specified instances.
18311 See YankInstance for more information.
18312 Takes a list of YankInstance as argument.
18314 Arguments
18316 instances: array of YankInstance
18317 Not documented
18318 Returns
18320 • Nothing on success
18321 • DeviceNotFound error, if any of the YankInstances doesn't exist
18323 Example
18325 -> { "execute": "yank",
18326 "arguments": {
18327 "instances": [
18328 { "type": "block-node",
18329 "node-name": "nbd0" }
18330 ] } }
18331 <- { "return": {} }
18332 Since
18334 6.0
18335 query-yank (Command)
18337 Query yank instances. See YankInstance for more information.
18338 Returns
18340 list of YankInstance
18341 Example
18343 -> { "execute": "query-yank" }
18344 <- { "return": [
18345 { "type": "block-node",
18346 "node-name": "nbd0" }
18347 ] }
18348 Since
18350 6.0
18351
18353 add_client (Command)
18354 Allow client connections for VNC, Spice and socket based character de‐
18355 vices to be passed in to QEMU via SCM_RIGHTS.
18356 Arguments
18358 protocol: string
18359 protocol name. Valid names are "vnc", "spice" or the name of a
18360 character device (eg. from -chardev id=XXXX)
18361 fdname: string
18363 file descriptor name previously passed via 'getfd' command
18364 skipauth: boolean (optional)
18366 whether to skip authentication. Only applies to "vnc" and
18367 "spice" protocols
18368 tls: boolean (optional)
18370 whether to perform TLS. Only applies to the "spice" protocol
18371 Returns
18373 nothing on success.
18374 Since
18376 0.14
18377 Example
18379 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
18380 "fdname": "myclient" } }
18381 <- { "return": {} }
18382 NameInfo (Object)
18384 Guest name information.
18385 Members
18387 name: string (optional)
18388 The name of the guest
18389 Since
18391 0.14
18392 query-name (Command)
18394 Return the name information of a guest.
18395 Returns
18397 NameInfo of the guest
18398 Since
18400 0.14
18401 Example
18403 -> { "execute": "query-name" }
18404 <- { "return": { "name": "qemu-name" } }
18405 IOThreadInfo (Object)
18407 Information about an iothread
18408 Members
18410 id: string
18411 the identifier of the iothread
18412 thread-id: int
18414 ID of the underlying host thread
18415 poll-max-ns: int
18417 maximum polling time in ns, 0 means polling is disabled (since
18418 2.9)
18419 poll-grow: int
18421 how many ns will be added to polling time, 0 means that it's not
18422 configured (since 2.9)
18423 poll-shrink: int
18425 how many ns will be removed from polling time, 0 means that it's
18426 not configured (since 2.9)
18427 aio-max-batch: int
18429 maximum number of requests in a batch for the AIO engine, 0
18430 means that the engine will use its default (since 6.1)
18431 Since
18433 2.0
18434 query-iothreads (Command)
18436 Returns a list of information about each iothread.
18437 Note
18439 this list excludes the QEMU main loop thread, which is not declared us‐
18440 ing the -object iothread command-line option. It is always the main
18441 thread of the process.
18442 Returns
18444 a list of IOThreadInfo for each iothread
18445 Since
18447 2.0
18448 Example
18450 -> { "execute": "query-iothreads" }
18451 <- { "return": [
18452 {
18453 "id":"iothread0",
18454 "thread-id":3134
18455 },
18456 {
18457 "id":"iothread1",
18458 "thread-id":3135
18459 }
18460 ]
18461 }
18462 stop (Command)
18464 Stop all guest VCPU execution.
18465 Since
18467 0.14
18468 Notes
18470 This function will succeed even if the guest is already in the stopped
18471 state. In "inmigrate" state, it will ensure that the guest remains
18472 paused once migration finishes, as if the -S option was passed on the
18473 command line.
18474 Example
18476 -> { "execute": "stop" }
18477 <- { "return": {} }
18478 cont (Command)
18480 Resume guest VCPU execution.
18481 Since
18483 0.14
18484 Returns
18486 If successful, nothing
18487 Notes
18489 This command will succeed if the guest is currently running. It will
18490 also succeed if the guest is in the "inmigrate" state; in this case,
18491 the effect of the command is to make sure the guest starts once migra‐
18492 tion finishes, removing the effect of the -S command line option if it
18493 was passed.
18494 Example
18496 -> { "execute": "cont" }
18497 <- { "return": {} }
18498 x-exit-preconfig (Command)
18500 Exit from "preconfig" state
18501 This command makes QEMU exit the preconfig state and proceed with VM
18503 initialization using configuration data provided on the command line
18504 and via the QMP monitor during the preconfig state. The command is only
18505 available during the preconfig state (i.e. when the --preconfig command
18506 line option was in use).
18507 Since 3.0
18509 Returns
18511 nothing
18512 Example
18514 -> { "execute": "x-exit-preconfig" }
18515 <- { "return": {} }
18516 human-monitor-command (Command)
18518 Execute a command on the human monitor and return the output.
18519 Arguments
18521 command-line: string
18522 the command to execute in the human monitor
18523 cpu-index: int (optional)
18525 The CPU to use for commands that require an implicit CPU
18526 Features
18528 savevm-monitor-nodes
18529 If present, HMP command savevm only snapshots monitor-owned
18530 nodes if they have no parents. This allows the use of 'savevm'
18531 with -blockdev. (since 4.2)
18532 Returns
18534 the output of the command as a string
18535 Since
18537 0.14
18538 Notes
18540 This command only exists as a stop-gap. Its use is highly discouraged.
18541 The semantics of this command are not guaranteed: this means that com‐
18542 mand names, arguments and responses can change or be removed at ANY
18543 time. Applications that rely on long term stability guarantees should
18544 NOT use this command.
18545 Known limitations:
18547 • This command is stateless, this means that commands that depend on
18549 state information (such as getfd) might not work
18550 • Commands that prompt the user for data don't currently work
18552 Example
18554 -> { "execute": "human-monitor-command",
18555 "arguments": { "command-line": "info kvm" } }
18556 <- { "return": "kvm support: enabled\r\n" }
18557 getfd (Command)
18559 Receive a file descriptor via SCM rights and assign it a name
18560 Arguments
18562 fdname: string
18563 file descriptor name
18564 Returns
18566 Nothing on success
18567 Since
18569 0.14
18570 Notes
18572 If fdname already exists, the file descriptor assigned to it will be
18573 closed and replaced by the received file descriptor.
18574 The 'closefd' command can be used to explicitly close the file descrip‐
18576 tor when it is no longer needed.
18577 Example
18579 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
18580 <- { "return": {} }
18581 closefd (Command)
18583 Close a file descriptor previously passed via SCM rights
18584 Arguments
18586 fdname: string
18587 file descriptor name
18588 Returns
18590 Nothing on success
18591 Since
18593 0.14
18594 Example
18596 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
18597 <- { "return": {} }
18598 AddfdInfo (Object)
18600 Information about a file descriptor that was added to an fd set.
18601 Members
18603 fdset-id: int
18604 The ID of the fd set that fd was added to.
18605 fd: int
18607 The file descriptor that was received via SCM rights and added
18608 to the fd set.
18609 Since
18611 1.2
18612 add-fd (Command)
18614 Add a file descriptor, that was passed via SCM rights, to an fd set.
18615 Arguments
18617 fdset-id: int (optional)
18618 The ID of the fd set to add the file descriptor to.
18619 opaque: string (optional)
18621 A free-form string that can be used to describe the fd.
18622 Returns
18624 • AddfdInfo on success
18625 • If file descriptor was not received, FdNotSupplied
18627 • If fdset-id is a negative value, InvalidParameterValue
18629 Notes
18631 The list of fd sets is shared by all monitor connections.
18632 If fdset-id is not specified, a new fd set will be created.
18634 Since
18636 1.2
18637 Example
18639 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
18640 <- { "return": { "fdset-id": 1, "fd": 3 } }
18641 remove-fd (Command)
18643 Remove a file descriptor from an fd set.
18644 Arguments
18646 fdset-id: int
18647 The ID of the fd set that the file descriptor belongs to.
18648 fd: int (optional)
18650 The file descriptor that is to be removed.
18651 Returns
18653 • Nothing on success
18654 • If fdset-id or fd is not found, FdNotFound
18656 Since
18658 1.2
18659 Notes
18661 The list of fd sets is shared by all monitor connections.
18662 If fd is not specified, all file descriptors in fdset-id will be re‐
18664 moved.
18665 Example
18667 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
18668 <- { "return": {} }
18669 FdsetFdInfo (Object)
18671 Information about a file descriptor that belongs to an fd set.
18672 Members
18674 fd: int
18675 The file descriptor value.
18676 opaque: string (optional)
18678 A free-form string that can be used to describe the fd.
18679 Since
18681 1.2
18682 FdsetInfo (Object)
18684 Information about an fd set.
18685 Members
18687 fdset-id: int
18688 The ID of the fd set.
18689 fds: array of FdsetFdInfo
18691 A list of file descriptors that belong to this fd set.
18692 Since
18694 1.2
18695 query-fdsets (Command)
18697 Return information describing all fd sets.
18698 Returns
18700 A list of FdsetInfo
18701 Since
18703 1.2
18704 Note
18706 The list of fd sets is shared by all monitor connections.
18707 Example
18709 -> { "execute": "query-fdsets" }
18710 <- { "return": [
18711 {
18712 "fds": [
18713 {
18714 "fd": 30,
18715 "opaque": "rdonly:/path/to/file"
18716 },
18717 {
18718 "fd": 24,
18719 "opaque": "rdwr:/path/to/file"
18720 }
18721 ],
18722 "fdset-id": 1
18723 },
18724 {
18725 "fds": [
18726 {
18727 "fd": 28
18728 },
18729 {
18730 "fd": 29
18731 }
18732 ],
18733 "fdset-id": 0
18734 }
18735 ]
18736 }
18737 CommandLineParameterType (Enum)
18739 Possible types for an option parameter.
18740 Values
18742 string accepts a character string
18743 boolean
18745 accepts "on" or "off"
18746 number accepts a number
18748 size accepts a number followed by an optional suffix (K)ilo, (M)ega,
18750 (G)iga, (T)era
18751 Since
18753 1.5
18754 CommandLineParameterInfo (Object)
18756 Details about a single parameter of a command line option.
18757 Members
18759 name: string
18760 parameter name
18761 type: CommandLineParameterType
18763 parameter CommandLineParameterType
18764 help: string (optional)
18766 human readable text string, not suitable for parsing.
18767 default: string (optional)
18769 default value string (since 2.1)
18770 Since
18772 1.5
18773 CommandLineOptionInfo (Object)
18775 Details about a command line option, including its list of parameter
18776 details
18777 Members
18779 option: string
18780 option name
18781 parameters: array of CommandLineParameterInfo
18783 an array of CommandLineParameterInfo
18784 Since
18786 1.5
18787 query-command-line-options (Command)
18789 Query command line option schema.
18790 Arguments
18792 option: string (optional)
18793 option name
18794 Returns
18796 list of CommandLineOptionInfo for all options (or for the given op‐
18797 tion). Returns an error if the given option doesn't exist.
18798 Since
18800 1.5
18801 Example
18803 -> { "execute": "query-command-line-options",
18804 "arguments": { "option": "option-rom" } }
18805 <- { "return": [
18806 {
18807 "parameters": [
18808 {
18809 "name": "romfile",
18810 "type": "string"
18811 },
18812 {
18813 "name": "bootindex",
18814 "type": "number"
18815 }
18816 ],
18817 "option": "option-rom"
18818 }
18819 ]
18820 }
18821 RTC_CHANGE (Event)
18823 Emitted when the guest changes the RTC time.
18824 Arguments
18826 offset: int
18827 offset between base RTC clock (as specified by -rtc base), and
18828 new RTC clock value
18829 Note
18831 This event is rate-limited.
18832 Since
18834 0.13
18835 Example
18837 <- { "event": "RTC_CHANGE",
18838 "data": { "offset": 78 },
18839 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
18840 If
18842 defined(TARGET_ALPHA) || defined(TARGET_ARM) || defined(TARGET_HPPA) ||
18843 defined(TARGET_I386) || defined(TARGET_MIPS) || defined(TARGET_MIPS64)
18844 || defined(TARGET_PPC) || defined(TARGET_PPC64) || defined(TAR‐
18845 GET_S390X) || defined(TARGET_SH4) || defined(TARGET_SPARC)
18846 rtc-reset-reinjection (Command)
18848 This command will reset the RTC interrupt reinjection backlog. Can be
18849 used if another mechanism to synchronize guest time is in effect, for
18850 example QEMU guest agent's guest-set-time command.
18851 Since
18853 2.1
18854 Example
18856 -> { "execute": "rtc-reset-reinjection" }
18857 <- { "return": {} }
18858 If
18860 defined(TARGET_I386)
18861 SevState (Enum)
18863 An enumeration of SEV state information used during query-sev.
18864 Values
18866 uninit The guest is uninitialized.
18867 launch-update
18869 The guest is currently being launched; plaintext data and regis‐
18870 ter state is being imported.
18871 launch-secret
18873 The guest is currently being launched; ciphertext data is being
18874 imported.
18875 running
18877 The guest is fully launched or migrated in.
18878 send-update
18880 The guest is currently being migrated out to another machine.
18881 receive-update
18883 The guest is currently being migrated from another machine.
18884 Since
18886 2.12
18887 If
18889 defined(TARGET_I386)
18890 SevInfo (Object)
18892 Information about Secure Encrypted Virtualization (SEV) support
18893 Members
18895 enabled: boolean
18896 true if SEV is active
18897 api-major: int
18899 SEV API major version
18900 api-minor: int
18902 SEV API minor version
18903 build-id: int
18905 SEV FW build id
18906 policy: int
18908 SEV policy value
18909 state: SevState
18911 SEV guest state
18912 handle: int
18914 SEV firmware handle
18915 Since
18917 2.12
18918 If
18920 defined(TARGET_I386)
18921 query-sev (Command)
18923 Returns information about SEV
18924 Returns
18926 SevInfo
18927 Since
18929 2.12
18930 Example
18932 -> { "execute": "query-sev" }
18933 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
18934 "build-id" : 0, "policy" : 0, "state" : "running",
18935 "handle" : 1 } }
18936 If
18938 defined(TARGET_I386)
18939 SevLaunchMeasureInfo (Object)
18941 SEV Guest Launch measurement information
18942 Members
18944 data: string
18945 the measurement value encoded in base64
18946 Since
18948 2.12
18949 If
18951 defined(TARGET_I386)
18952 query-sev-launch-measure (Command)
18954 Query the SEV guest launch information.
18955 Returns
18957 The SevLaunchMeasureInfo for the guest
18958 Since
18960 2.12
18961 Example
18963 -> { "execute": "query-sev-launch-measure" }
18964 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
18965 If
18967 defined(TARGET_I386)
18968 SevCapability (Object)
18970 The struct describes capability for a Secure Encrypted Virtualization
18971 feature.
18972 Members
18974 pdh: string
18975 Platform Diffie-Hellman key (base64 encoded)
18976 cert-chain: string
18978 PDH certificate chain (base64 encoded)
18979 cbitpos: int
18981 C-bit location in page table entry
18982 reduced-phys-bits: int
18984 Number of physical Address bit reduction when SEV is enabled
18985 Since
18987 2.12
18988 If
18990 defined(TARGET_I386)
18991 query-sev-capabilities (Command)
18993 This command is used to get the SEV capabilities, and is supported on
18994 AMD X86 platforms only.
18995 Returns
18997 SevCapability objects.
18998 Since
19000 2.12
19001 Example
19003 -> { "execute": "query-sev-capabilities" }
19004 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
19005 "cbitpos": 47, "reduced-phys-bits": 5}}
19006 If
19008 defined(TARGET_I386)
19009 sev-inject-launch-secret (Command)
19011 This command injects a secret blob into memory of SEV guest.
19012 Arguments
19014 packet-header: string
19015 the launch secret packet header encoded in base64
19016 secret: string
19018 the launch secret data to be injected encoded in base64
19019 gpa: int (optional)
19021 the guest physical address where secret will be injected.
19022 Since
19024 6.0
19025 If
19027 defined(TARGET_I386)
19028 dump-skeys (Command)
19030 Dump guest's storage keys
19031 Arguments
19033 filename: string
19034 the path to the file to dump to
19035 This command is only supported on s390 architecture.
19036 Since
19038 2.5
19039 Example
19041 -> { "execute": "dump-skeys",
19042 "arguments": { "filename": "/tmp/skeys" } }
19043 <- { "return": {} }
19044 If
19046 defined(TARGET_S390X)
19047 GICCapability (Object)
19049 The struct describes capability for a specific GIC (Generic Interrupt
19050 Controller) version. These bits are not only decided by QEMU/KVM soft‐
19051 ware version, but also decided by the hardware that the program is run‐
19052 ning upon.
19053 Members
19055 version: int
19056 version of GIC to be described. Currently, only 2 and 3 are sup‐
19057 ported.
19058 emulated: boolean
19060 whether current QEMU/hardware supports emulated GIC device in
19061 user space.
19062 kernel: boolean
19064 whether current QEMU/hardware supports hardware accelerated GIC
19065 device in kernel.
19066 Since
19068 2.6
19069 If
19071 defined(TARGET_ARM)
19072 query-gic-capabilities (Command)
19074 This command is ARM-only. It will return a list of GICCapability ob‐
19075 jects that describe its capability bits.
19076 Returns
19078 a list of GICCapability objects.
19079 Since
19081 2.6
19082 Example
19084 -> { "execute": "query-gic-capabilities" }
19085 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
19086 { "version": 3, "emulated": false, "kernel": true } ] }
19087 If
19089 defined(TARGET_ARM)
19090 SevAttestationReport (Object)
19092 The struct describes attestation report for a Secure Encrypted Virtual‐
19093 ization feature.
19094 Members
19096 data: string
19097 guest attestation report (base64 encoded)
19098 Since
19100 6.1
19101 If
19103 defined(TARGET_I386)
19104 query-sev-attestation-report (Command)
19106 This command is used to get the SEV attestation report, and is sup‐
19107 ported on AMD X86 platforms only.
19108 Arguments
19110 mnonce: string
19111 a random 16 bytes value encoded in base64 (it will be included
19112 in report)
19113 Returns
19115 SevAttestationReport objects.
19116 Since
19118 6.1
19119 Example
19121 -> { "execute" : "query-sev-attestation-report", "arguments": { "mnonce": "aaaaaaa" } }
19122 <- { "return" : { "data": "aaaaaaaabbbddddd"} }
19123 If
19125 defined(TARGET_I386)
19126
19128 AudiodevPerDirectionOptions (Object)
19129 General audio backend options that are used for both playback and
19130 recording.
19131 Members
19133 mixing-engine: boolean (optional)
19134 use QEMU's mixing engine to mix all streams inside QEMU and con‐
19135 vert audio formats when not supported by the backend. When set
19136 to off, fixed-settings must be also off (default on, since 4.2)
19137 fixed-settings: boolean (optional)
19139 use fixed settings for host input/output. When off, frequency,
19140 channels and format must not be specified (default true)
19141 frequency: int (optional)
19143 frequency to use when using fixed settings (default 44100)
19144 channels: int (optional)
19146 number of channels when using fixed settings (default 2)
19147 voices: int (optional)
19149 number of voices to use (default 1)
19150 format: AudioFormat (optional)
19152 sample format to use when using fixed settings (default s16)
19153 buffer-length: int (optional)
19155 the buffer length in microseconds
19156 Since
19158 4.0
19159 AudiodevGenericOptions (Object)
19161 Generic driver-specific options.
19162 Members
19164 in: AudiodevPerDirectionOptions (optional)
19165 options of the capture stream
19166 out: AudiodevPerDirectionOptions (optional)
19168 options of the playback stream
19169 Since
19171 4.0
19172 AudiodevAlsaPerDirectionOptions (Object)
19174 Options of the ALSA backend that are used for both playback and record‐
19175 ing.
19176 Members
19178 dev: string (optional)
19179 the name of the ALSA device to use (default 'default')
19180 period-length: int (optional)
19182 the period length in microseconds
19183 try-poll: boolean (optional)
19185 attempt to use poll mode, falling back to non-polling access on
19186 failure (default true)
19187 The members of AudiodevPerDirectionOptions
19189 Since
19191 4.0
19192 AudiodevAlsaOptions (Object)
19194 Options of the ALSA audio backend.
19195 Members
19197 in: AudiodevAlsaPerDirectionOptions (optional)
19198 options of the capture stream
19199 out: AudiodevAlsaPerDirectionOptions (optional)
19201 options of the playback stream
19202 threshold: int (optional)
19204 set the threshold (in microseconds) when playback starts
19205 Since
19207 4.0
19208 AudiodevCoreaudioPerDirectionOptions (Object)
19210 Options of the Core Audio backend that are used for both playback and
19211 recording.
19212 Members
19214 buffer-count: int (optional)
19215 number of buffers
19216 The members of AudiodevPerDirectionOptions
19218 Since
19220 4.0
19221 AudiodevCoreaudioOptions (Object)
19223 Options of the coreaudio audio backend.
19224 Members
19226 in: AudiodevCoreaudioPerDirectionOptions (optional)
19227 options of the capture stream
19228 out: AudiodevCoreaudioPerDirectionOptions (optional)
19230 options of the playback stream
19231 Since
19233 4.0
19234 AudiodevDsoundOptions (Object)
19236 Options of the DirectSound audio backend.
19237 Members
19239 in: AudiodevPerDirectionOptions (optional)
19240 options of the capture stream
19241 out: AudiodevPerDirectionOptions (optional)
19243 options of the playback stream
19244 latency: int (optional)
19246 add extra latency to playback in microseconds (default 10000)
19247 Since
19249 4.0
19250 AudiodevJackPerDirectionOptions (Object)
19252 Options of the JACK backend that are used for both playback and record‐
19253 ing.
19254 Members
19256 server-name: string (optional)
19257 select from among several possible concurrent server instances
19258 (default: environment variable $JACK_DEFAULT_SERVER if set, else
19259 "default")
19260 client-name: string (optional)
19262 the client name to use. The server will modify this name to cre‐
19263 ate a unique variant, if needed unless exact-name is true (de‐
19264 fault: the guest's name)
19265 connect-ports: string (optional)
19267 if set, a regular expression of JACK client port name(s) to mon‐
19268 itor for and automatically connect to
19269 start-server: boolean (optional)
19271 start a jack server process if one is not already present (de‐
19272 fault: false)
19273 exact-name: boolean (optional)
19275 use the exact name requested otherwise JACK automatically gener‐
19276 ates a unique one, if needed (default: false)
19277 The members of AudiodevPerDirectionOptions
19279 Since
19281 5.1
19282 AudiodevJackOptions (Object)
19284 Options of the JACK audio backend.
19285 Members
19287 in: AudiodevJackPerDirectionOptions (optional)
19288 options of the capture stream
19289 out: AudiodevJackPerDirectionOptions (optional)
19291 options of the playback stream
19292 Since
19294 5.1
19295 AudiodevOssPerDirectionOptions (Object)
19297 Options of the OSS backend that are used for both playback and record‐
19298 ing.
19299 Members
19301 dev: string (optional)
19302 file name of the OSS device (default '/dev/dsp')
19303 buffer-count: int (optional)
19305 number of buffers
19306 try-poll: boolean (optional)
19308 attempt to use poll mode, falling back to non-polling access on
19309 failure (default true)
19310 The members of AudiodevPerDirectionOptions
19312 Since
19314 4.0
19315 AudiodevOssOptions (Object)
19317 Options of the OSS audio backend.
19318 Members
19320 in: AudiodevOssPerDirectionOptions (optional)
19321 options of the capture stream
19322 out: AudiodevOssPerDirectionOptions (optional)
19324 options of the playback stream
19325 try-mmap: boolean (optional)
19327 try using memory-mapped access, falling back to non-mem‐
19328 ory-mapped access on failure (default true)
19329 exclusive: boolean (optional)
19331 open device in exclusive mode (vmix won't work) (default false)
19332 dsp-policy: int (optional)
19334 set the timing policy of the device (between 0 and 10, where
19335 smaller number means smaller latency but higher CPU usage) or -1
19336 to use fragment mode (option ignored on some platforms) (default
19337 5)
19338 Since
19340 4.0
19341 AudiodevPaPerDirectionOptions (Object)
19343 Options of the Pulseaudio backend that are used for both playback and
19344 recording.
19345 Members
19347 name: string (optional)
19348 name of the sink/source to use
19349 stream-name: string (optional)
19351 name of the PulseAudio stream created by qemu. Can be used to
19352 identify the stream in PulseAudio when you create multiple
19353 PulseAudio devices or run multiple qemu instances (default: au‐
19354 diodev's id, since 4.2)
19355 latency: int (optional)
19357 latency you want PulseAudio to achieve in microseconds (default
19358 15000)
19359 The members of AudiodevPerDirectionOptions
19361 Since
19363 4.0
19364 AudiodevPaOptions (Object)
19366 Options of the PulseAudio audio backend.
19367 Members
19369 in: AudiodevPaPerDirectionOptions (optional)
19370 options of the capture stream
19371 out: AudiodevPaPerDirectionOptions (optional)
19373 options of the playback stream
19374 server: string (optional)
19376 PulseAudio server address (default: let PulseAudio choose)
19377 Since
19379 4.0
19380 AudiodevSdlPerDirectionOptions (Object)
19382 Options of the SDL audio backend that are used for both playback and
19383 recording.
19384 Members
19386 buffer-count: int (optional)
19387 number of buffers (default 4)
19388 The members of AudiodevPerDirectionOptions
19390 Since
19392 6.0
19393 AudiodevSdlOptions (Object)
19395 Options of the SDL audio backend.
19396 Members
19398 in: AudiodevSdlPerDirectionOptions (optional)
19399 options of the recording stream
19400 out: AudiodevSdlPerDirectionOptions (optional)
19402 options of the playback stream
19403 Since
19405 6.0
19406 AudiodevWavOptions (Object)
19408 Options of the wav audio backend.
19409 Members
19411 in: AudiodevPerDirectionOptions (optional)
19412 options of the capture stream
19413 out: AudiodevPerDirectionOptions (optional)
19415 options of the playback stream
19416 path: string (optional)
19418 name of the wav file to record (default 'qemu.wav')
19419 Since
19421 4.0
19422 AudioFormat (Enum)
19424 An enumeration of possible audio formats.
19425 Values
19427 u8 unsigned 8 bit integer
19428 s8 signed 8 bit integer
19430 u16 unsigned 16 bit integer
19432 s16 signed 16 bit integer
19434 u32 unsigned 32 bit integer
19436 s32 signed 32 bit integer
19438 f32 single precision floating-point (since 5.0)
19440 Since
19442 4.0
19443 AudiodevDriver (Enum)
19445 An enumeration of possible audio backend drivers.
19446 Values
19448 jack JACK audio backend (since 5.1)
19449 none Not documented
19451 alsa Not documented
19453 coreaudio
19455 Not documented
19456 dsound Not documented
19458 oss Not documented
19460 pa Not documented
19462 sdl Not documented
19464 spice Not documented
19466 wav Not documented
19468 Since
19470 4.0
19471 Audiodev (Object)
19473 Options of an audio backend.
19474 Members
19476 id: string
19477 identifier of the backend
19478 driver: AudiodevDriver
19480 the backend driver to use
19481 timer-period: int (optional)
19483 timer period (in microseconds, 0: use lowest possible)
19484 The members of AudiodevGenericOptions when driver is "none"
19486 The members of AudiodevAlsaOptions when driver is "alsa"
19488 The members of AudiodevCoreaudioOptions when driver is "coreaudio"
19490 The members of AudiodevDsoundOptions when driver is "dsound"
19492 The members of AudiodevJackOptions when driver is "jack"
19494 The members of AudiodevOssOptions when driver is "oss"
19496 The members of AudiodevPaOptions when driver is "pa"
19498 The members of AudiodevSdlOptions when driver is "sdl"
19500 The members of AudiodevGenericOptions when driver is "spice"
19502 The members of AudiodevWavOptions when driver is "wav"
19504 Since
19506 4.0
19507
19509 AcpiTableOptions (Object)
19510 Specify an ACPI table on the command line to load.
19511 At most one of file and data can be specified. The list of files speci‐
19513 fied by any one of them is loaded and concatenated in order. If both
19514 are omitted, data is implied.
19515 Other fields / optargs can be used to override fields of the generic
19517 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
19518 System Description Table Header. If a header field is not overridden,
19519 then the corresponding value from the concatenated blob is used (in
19520 case of file), or it is filled in with a hard-coded value (in case of
19521 data).
19522 String fields are copied into the matching ACPI member from lowest ad‐
19524 dress upwards, and silently truncated / NUL-padded to length.
19525 Members
19527 sig: string (optional)
19528 table signature / identifier (4 bytes)
19529 rev: int (optional)
19531 table revision number (dependent on signature, 1 byte)
19532 oem_id: string (optional)
19534 OEM identifier (6 bytes)
19535 oem_table_id: string (optional)
19537 OEM table identifier (8 bytes)
19538 oem_rev: int (optional)
19540 OEM-supplied revision number (4 bytes)
19541 asl_compiler_id: string (optional)
19543 identifier of the utility that created the table (4 bytes)
19544 asl_compiler_rev: int (optional)
19546 revision number of the utility that created the table (4 bytes)
19547 file: string (optional)
19549 colon (:) separated list of pathnames to load and concatenate as
19550 table data. The resultant binary blob is expected to have an
19551 ACPI table header. At least one file is required. This field ex‐
19552 cludes data.
19553 data: string (optional)
19555 colon (:) separated list of pathnames to load and concatenate as
19556 table data. The resultant binary blob must not have an ACPI ta‐
19557 ble header. At least one file is required. This field excludes
19558 file.
19559 Since
19561 1.5
19562 ACPISlotType (Enum)
19564 Values
19565 DIMM memory slot
19566 CPU logical CPU slot (since 2.7)
19568 ACPIOSTInfo (Object)
19570 OSPM Status Indication for a device For description of possible values
19571 of source and status fields see "_OST (OSPM Status Indication)" chapter
19572 of ACPI5.0 spec.
19573 Members
19575 device: string (optional)
19576 device ID associated with slot
19577 slot: string
19579 slot ID, unique per slot of a given slot-type
19580 slot-type: ACPISlotType
19582 type of the slot
19583 source: int
19585 an integer containing the source event
19586 status: int
19588 an integer containing the status code
19589 Since
19591 2.1
19592 query-acpi-ospm-status (Command)
19594 Return a list of ACPIOSTInfo for devices that support status reporting
19595 via ACPI _OST method.
19596 Since
19598 2.1
19599 Example
19601 -> { "execute": "query-acpi-ospm-status" }
19602 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
19603 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
19604 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
19605 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
19606 ]}
19607 ACPI_DEVICE_OST (Event)
19609 Emitted when guest executes ACPI _OST method.
19610 Arguments
19612 info: ACPIOSTInfo
19613 OSPM Status Indication
19614 Since
19616 2.1
19617 Example
19619 <- { "event": "ACPI_DEVICE_OST",
19620 "data": { "device": "d1", "slot": "0",
19621 "slot-type": "DIMM", "source": 1, "status": 0 } }
19622
19624 PciMemoryRange (Object)
19625 A PCI device memory region
19626 Members
19628 base: int
19629 the starting address (guest physical)
19630 limit: int
19632 the ending address (guest physical)
19633 Since
19635 0.14
19636 PciMemoryRegion (Object)
19638 Information about a PCI device I/O region.
19639 Members
19641 bar: int
19642 the index of the Base Address Register for this region
19643 type: string
19645 • 'io' if the region is a PIO region
19647 • 'memory' if the region is a MMIO region
19649 size: int
19651 memory size
19652 prefetch: boolean (optional)
19654 if type is 'memory', true if the memory is prefetchable
19655 mem_type_64: boolean (optional)
19657 if type is 'memory', true if the BAR is 64-bit
19658 address: int
19660 Not documented
19661 Since
19663 0.14
19664 PciBusInfo (Object)
19666 Information about a bus of a PCI Bridge device
19667 Members
19669 number: int
19670 primary bus interface number. This should be the number of the
19671 bus the device resides on.
19672 secondary: int
19674 secondary bus interface number. This is the number of the main
19675 bus for the bridge
19676 subordinate: int
19678 This is the highest number bus that resides below the bridge.
19679 io_range: PciMemoryRange
19681 The PIO range for all devices on this bridge
19682 memory_range: PciMemoryRange
19684 The MMIO range for all devices on this bridge
19685 prefetchable_range: PciMemoryRange
19687 The range of prefetchable MMIO for all devices on this bridge
19688 Since
19690 2.4
19691 PciBridgeInfo (Object)
19693 Information about a PCI Bridge device
19694 Members
19696 bus: PciBusInfo
19697 information about the bus the device resides on
19698 devices: array of PciDeviceInfo (optional)
19700 a list of PciDeviceInfo for each device on this bridge
19701 Since
19703 0.14
19704 PciDeviceClass (Object)
19706 Information about the Class of a PCI device
19707 Members
19709 desc: string (optional)
19710 a string description of the device's class
19711 class: int
19713 the class code of the device
19714 Since
19716 2.4
19717 PciDeviceId (Object)
19719 Information about the Id of a PCI device
19720 Members
19722 device: int
19723 the PCI device id
19724 vendor: int
19726 the PCI vendor id
19727 subsystem: int (optional)
19729 the PCI subsystem id (since 3.1)
19730 subsystem-vendor: int (optional)
19732 the PCI subsystem vendor id (since 3.1)
19733 Since
19735 2.4
19736 PciDeviceInfo (Object)
19738 Information about a PCI device
19739 Members
19741 bus: int
19742 the bus number of the device
19743 slot: int
19745 the slot the device is located in
19746 function: int
19748 the function of the slot used by the device
19749 class_info: PciDeviceClass
19751 the class of the device
19752 id: PciDeviceId
19754 the PCI device id
19755 irq: int (optional)
19757 if an IRQ is assigned to the device, the IRQ number
19758 irq_pin: int
19760 the IRQ pin, zero means no IRQ (since 5.1)
19761 qdev_id: string
19763 the device name of the PCI device
19764 pci_bridge: PciBridgeInfo (optional)
19766 if the device is a PCI bridge, the bridge information
19767 regions: array of PciMemoryRegion
19769 a list of the PCI I/O regions associated with the device
19770 Notes
19772 the contents of class_info.desc are not stable and should only be
19773 treated as informational.
19774 Since
19776 0.14
19777 PciInfo (Object)
19779 Information about a PCI bus
19780 Members
19782 bus: int
19783 the bus index
19784 devices: array of PciDeviceInfo
19786 a list of devices on this bus
19787 Since
19789 0.14
19790 query-pci (Command)
19792 Return information about the PCI bus topology of the guest.
19793 Returns
19795 a list of PciInfo for each PCI bus. Each bus is represented by a
19796 json-object, which has a key with a json-array of all PCI devices at‐
19797 tached to it. Each device is represented by a json-object.
19798 Since
19800 0.14
19801 Example
19803 -> { "execute": "query-pci" }
19804 <- { "return": [
19805 {
19806 "bus": 0,
19807 "devices": [
19808 {
19809 "bus": 0,
19810 "qdev_id": "",
19811 "slot": 0,
19812 "class_info": {
19813 "class": 1536,
19814 "desc": "Host bridge"
19815 },
19816 "id": {
19817 "device": 32902,
19818 "vendor": 4663
19819 },
19820 "function": 0,
19821 "regions": [
19822 ]
19823 },
19824 {
19825 "bus": 0,
19826 "qdev_id": "",
19827 "slot": 1,
19828 "class_info": {
19829 "class": 1537,
19830 "desc": "ISA bridge"
19831 },
19832 "id": {
19833 "device": 32902,
19834 "vendor": 28672
19835 },
19836 "function": 0,
19837 "regions": [
19838 ]
19839 },
19840 {
19841 "bus": 0,
19842 "qdev_id": "",
19843 "slot": 1,
19844 "class_info": {
19845 "class": 257,
19846 "desc": "IDE controller"
19847 },
19848 "id": {
19849 "device": 32902,
19850 "vendor": 28688
19851 },
19852 "function": 1,
19853 "regions": [
19854 {
19855 "bar": 4,
19856 "size": 16,
19857 "address": 49152,
19858 "type": "io"
19859 }
19860 ]
19861 },
19862 {
19863 "bus": 0,
19864 "qdev_id": "",
19865 "slot": 2,
19866 "class_info": {
19867 "class": 768,
19868 "desc": "VGA controller"
19869 },
19870 "id": {
19871 "device": 4115,
19872 "vendor": 184
19873 },
19874 "function": 0,
19875 "regions": [
19876 {
19877 "prefetch": true,
19878 "mem_type_64": false,
19879 "bar": 0,
19880 "size": 33554432,
19881 "address": 4026531840,
19882 "type": "memory"
19883 },
19884 {
19885 "prefetch": false,
19886 "mem_type_64": false,
19887 "bar": 1,
19888 "size": 4096,
19889 "address": 4060086272,
19890 "type": "memory"
19891 },
19892 {
19893 "prefetch": false,
19894 "mem_type_64": false,
19895 "bar": 6,
19896 "size": 65536,
19897 "address": -1,
19898 "type": "memory"
19899 }
19900 ]
19901 },
19902 {
19903 "bus": 0,
19904 "qdev_id": "",
19905 "irq": 11,
19906 "slot": 4,
19907 "class_info": {
19908 "class": 1280,
19909 "desc": "RAM controller"
19910 },
19911 "id": {
19912 "device": 6900,
19913 "vendor": 4098
19914 },
19915 "function": 0,
19916 "regions": [
19917 {
19918 "bar": 0,
19919 "size": 32,
19920 "address": 49280,
19921 "type": "io"
19922 }
19923 ]
19924 }
19925 ]
19926 }
19927 ]
19928 }
19929 Note
19931 This example has been shortened as the real response is too long.
19932
19934 2021, The QEMU Project Developers
199356.1.0 Nov 08, 2021 QEMU-QMP-REF(7)