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 • HumanReadableText (Object)
51 • Socket data types
53 • NetworkAddressFamily (Enum)
55 • InetSocketAddressBase (Object)
57 • InetSocketAddress (Object)
59 • UnixSocketAddress (Object)
61 • VsockSocketAddress (Object)
63 • InetSocketAddressWrapper (Object)
65 • UnixSocketAddressWrapper (Object)
67 • VsockSocketAddressWrapper (Object)
69 • StringWrapper (Object)
71 • SocketAddressLegacy (Object)
73 • SocketAddressType (Enum)
75 • SocketAddress (Object)
77 • VM run state
79 • RunState (Enum)
81 • ShutdownCause (Enum)
83 • StatusInfo (Object)
85 • query-status (Command)
87 • SHUTDOWN (Event)
89 • POWERDOWN (Event)
91 • RESET (Event)
93 • STOP (Event)
95 • RESUME (Event)
97 • SUSPEND (Event)
99 • SUSPEND_DISK (Event)
101 • WAKEUP (Event)
103 • WATCHDOG (Event)
105 • WatchdogAction (Enum)
107 • RebootAction (Enum)
109 • ShutdownAction (Enum)
111 • PanicAction (Enum)
113 • watchdog-set-action (Command)
115 • set-action (Command)
117 • GUEST_PANICKED (Event)
119 • GUEST_CRASHLOADED (Event)
121 • GuestPanicAction (Enum)
123 • GuestPanicInformationType (Enum)
125 • GuestPanicInformation (Object)
127 • GuestPanicInformationHyperV (Object)
129 • S390CrashReason (Enum)
131 • GuestPanicInformationS390 (Object)
133 • MEMORY_FAILURE (Event)
135 • MemoryFailureRecipient (Enum)
137 • MemoryFailureAction (Enum)
139 • MemoryFailureFlags (Object)
141 • Cryptography
143 • QCryptoTLSCredsEndpoint (Enum)
145 • QCryptoSecretFormat (Enum)
147 • QCryptoHashAlgorithm (Enum)
149 • QCryptoCipherAlgorithm (Enum)
151 • QCryptoCipherMode (Enum)
153 • QCryptoIVGenAlgorithm (Enum)
155 • QCryptoBlockFormat (Enum)
157 • QCryptoBlockOptionsBase (Object)
159 • QCryptoBlockOptionsQCow (Object)
161 • QCryptoBlockOptionsLUKS (Object)
163 • QCryptoBlockCreateOptionsLUKS (Object)
165 • QCryptoBlockOpenOptions (Object)
167 • QCryptoBlockCreateOptions (Object)
169 • QCryptoBlockInfoBase (Object)
171 • QCryptoBlockInfoLUKSSlot (Object)
173 • QCryptoBlockInfoLUKS (Object)
175 • QCryptoBlockInfo (Object)
177 • QCryptoBlockLUKSKeyslotState (Enum)
179 • QCryptoBlockAmendOptionsLUKS (Object)
181 • QCryptoBlockAmendOptions (Object)
183 • SecretCommonProperties (Object)
185 • SecretProperties (Object)
187 • SecretKeyringProperties (Object)
189 • TlsCredsProperties (Object)
191 • TlsCredsAnonProperties (Object)
193 • TlsCredsPskProperties (Object)
195 • TlsCredsX509Properties (Object)
197 • Block devices
199 • Block core (VM unrelated)
201 • Background jobs
203 • Additional block stuff (VM related)
205 • Block device exports
207 • Character devices
209 • ChardevInfo (Object)
211 • query-chardev (Command)
213 • ChardevBackendInfo (Object)
215 • query-chardev-backends (Command)
217 • DataFormat (Enum)
219 • ringbuf-write (Command)
221 • ringbuf-read (Command)
223 • ChardevCommon (Object)
225 • ChardevFile (Object)
227 • ChardevHostdev (Object)
229 • ChardevSocket (Object)
231 • ChardevUdp (Object)
233 • ChardevMux (Object)
235 • ChardevStdio (Object)
237 • ChardevSpiceChannel (Object)
239 • ChardevSpicePort (Object)
241 • ChardevVC (Object)
243 • ChardevRingbuf (Object)
245 • ChardevQemuVDAgent (Object)
247 • ChardevBackendKind (Enum)
249 • ChardevFileWrapper (Object)
251 • ChardevHostdevWrapper (Object)
253 • ChardevSocketWrapper (Object)
255 • ChardevUdpWrapper (Object)
257 • ChardevCommonWrapper (Object)
259 • ChardevMuxWrapper (Object)
261 • ChardevStdioWrapper (Object)
263 • ChardevSpiceChannelWrapper (Object)
265 • ChardevSpicePortWrapper (Object)
267 • ChardevQemuVDAgentWrapper (Object)
269 • ChardevVCWrapper (Object)
271 • ChardevRingbufWrapper (Object)
273 • ChardevBackend (Object)
275 • ChardevReturn (Object)
277 • chardev-add (Command)
279 • chardev-change (Command)
281 • chardev-remove (Command)
283 • chardev-send-break (Command)
285 • VSERPORT_CHANGE (Event)
287 • Dump guest memory
289 • DumpGuestMemoryFormat (Enum)
291 • dump-guest-memory (Command)
293 • DumpStatus (Enum)
295 • DumpQueryResult (Object)
297 • query-dump (Command)
299 • DUMP_COMPLETED (Event)
301 • DumpGuestMemoryCapability (Object)
303 • query-dump-guest-memory-capability (Command)
305 • Net devices
307 • set_link (Command)
309 • netdev_add (Command)
311 • netdev_del (Command)
313 • NetLegacyNicOptions (Object)
315 • NetdevUserOptions (Object)
317 • NetdevTapOptions (Object)
319 • NetdevSocketOptions (Object)
321 • NetdevL2TPv3Options (Object)
323 • NetdevVdeOptions (Object)
325 • NetdevBridgeOptions (Object)
327 • NetdevHubPortOptions (Object)
329 • NetdevNetmapOptions (Object)
331 • NetdevVhostUserOptions (Object)
333 • NetdevVhostVDPAOptions (Object)
335 • NetClientDriver (Enum)
337 • Netdev (Object)
339 • RxState (Enum)
341 • RxFilterInfo (Object)
343 • query-rx-filter (Command)
345 • NIC_RX_FILTER_CHANGED (Event)
347 • AnnounceParameters (Object)
349 • announce-self (Command)
351 • FAILOVER_NEGOTIATED (Event)
353 • RDMA device
355 • RDMA_GID_STATUS_CHANGED (Event)
357 • Rocker switch device
359 • RockerSwitch (Object)
361 • query-rocker (Command)
363 • RockerPortDuplex (Enum)
365 • RockerPortAutoneg (Enum)
367 • RockerPort (Object)
369 • query-rocker-ports (Command)
371 • RockerOfDpaFlowKey (Object)
373 • RockerOfDpaFlowMask (Object)
375 • RockerOfDpaFlowAction (Object)
377 • RockerOfDpaFlow (Object)
379 • query-rocker-of-dpa-flows (Command)
381 • RockerOfDpaGroup (Object)
383 • query-rocker-of-dpa-groups (Command)
385 • TPM (trusted platform module) devices
387 • TpmModel (Enum)
389 • query-tpm-models (Command)
391 • TpmType (Enum)
393 • query-tpm-types (Command)
395 • TPMPassthroughOptions (Object)
397 • TPMEmulatorOptions (Object)
399 • TPMPassthroughOptionsWrapper (Object)
401 • TPMEmulatorOptionsWrapper (Object)
403 • TpmTypeOptions (Object)
405 • TPMInfo (Object)
407 • query-tpm (Command)
409 • Remote desktop
411 • set_password (Command)
413 • expire_password (Command)
415 • screendump (Command)
417 • Spice
419 • VNC
421 • Input
423 • MouseInfo (Object)
425 • query-mice (Command)
427 • QKeyCode (Enum)
429 • KeyValueKind (Enum)
431 • IntWrapper (Object)
433 • QKeyCodeWrapper (Object)
435 • KeyValue (Object)
437 • send-key (Command)
439 • InputButton (Enum)
441 • InputAxis (Enum)
443 • InputKeyEvent (Object)
445 • InputBtnEvent (Object)
447 • InputMoveEvent (Object)
449 • InputEventKind (Enum)
451 • InputKeyEventWrapper (Object)
453 • InputBtnEventWrapper (Object)
455 • InputMoveEventWrapper (Object)
457 • InputEvent (Object)
459 • input-send-event (Command)
461 • DisplayGTK (Object)
463 • DisplayEGLHeadless (Object)
465 • DisplayGLMode (Enum)
467 • DisplayCurses (Object)
469 • DisplayType (Enum)
471 • DisplayOptions (Object)
473 • query-display-options (Command)
475 • DisplayReloadType (Enum)
477 • DisplayReloadOptionsVNC (Object)
479 • DisplayReloadOptions (Object)
481 • display-reload (Command)
483 • User authorization
485 • QAuthZListPolicy (Enum)
487 • QAuthZListFormat (Enum)
489 • QAuthZListRule (Object)
491 • AuthZListProperties (Object)
493 • AuthZListFileProperties (Object)
495 • AuthZPAMProperties (Object)
497 • AuthZSimpleProperties (Object)
499 • Migration
501 • MigrationStats (Object)
503 • XBZRLECacheStats (Object)
505 • CompressionStats (Object)
507 • MigrationStatus (Enum)
509 • VfioStats (Object)
511 • MigrationInfo (Object)
513 • query-migrate (Command)
515 • MigrationCapability (Enum)
517 • MigrationCapabilityStatus (Object)
519 • migrate-set-capabilities (Command)
521 • query-migrate-capabilities (Command)
523 • MultiFDCompression (Enum)
525 • BitmapMigrationBitmapAliasTransform (Object)
527 • BitmapMigrationBitmapAlias (Object)
529 • BitmapMigrationNodeAlias (Object)
531 • MigrationParameter (Enum)
533 • MigrateSetParameters (Object)
535 • migrate-set-parameters (Command)
537 • MigrationParameters (Object)
539 • query-migrate-parameters (Command)
541 • client_migrate_info (Command)
543 • migrate-start-postcopy (Command)
545 • MIGRATION (Event)
547 • MIGRATION_PASS (Event)
549 • COLOMessage (Enum)
551 • COLOMode (Enum)
553 • FailoverStatus (Enum)
555 • COLO_EXIT (Event)
557 • COLOExitReason (Enum)
559 • x-colo-lost-heartbeat (Command)
561 • migrate_cancel (Command)
563 • migrate-continue (Command)
565 • migrate (Command)
567 • migrate-incoming (Command)
569 • xen-save-devices-state (Command)
571 • xen-set-global-dirty-log (Command)
573 • xen-load-devices-state (Command)
575 • xen-set-replication (Command)
577 • ReplicationStatus (Object)
579 • query-xen-replication-status (Command)
581 • xen-colo-do-checkpoint (Command)
583 • COLOStatus (Object)
585 • query-colo-status (Command)
587 • migrate-recover (Command)
589 • migrate-pause (Command)
591 • UNPLUG_PRIMARY (Event)
593 • DirtyRateVcpu (Object)
595 • DirtyRateStatus (Enum)
597 • DirtyRateMeasureMode (Enum)
599 • DirtyRateInfo (Object)
601 • calc-dirty-rate (Command)
603 • query-dirty-rate (Command)
605 • snapshot-save (Command)
607 • snapshot-load (Command)
609 • snapshot-delete (Command)
611 • Transactions
613 • Abort (Object)
615 • ActionCompletionMode (Enum)
617 • TransactionActionKind (Enum)
619 • AbortWrapper (Object)
621 • BlockDirtyBitmapAddWrapper (Object)
623 • BlockDirtyBitmapWrapper (Object)
625 • BlockDirtyBitmapMergeWrapper (Object)
627 • BlockdevBackupWrapper (Object)
629 • BlockdevSnapshotWrapper (Object)
631 • BlockdevSnapshotInternalWrapper (Object)
633 • BlockdevSnapshotSyncWrapper (Object)
635 • DriveBackupWrapper (Object)
637 • TransactionAction (Object)
639 • TransactionProperties (Object)
641 • transaction (Command)
643 • Tracing
645 • TraceEventState (Enum)
647 • TraceEventInfo (Object)
649 • trace-event-get-state (Command)
651 • trace-event-set-state (Command)
653 • Compatibility policy
655 • CompatPolicyInput (Enum)
657 • CompatPolicyOutput (Enum)
659 • CompatPolicy (Object)
661 • QMP monitor control
663 • qmp_capabilities (Command)
665 • QMPCapability (Enum)
667 • VersionTriple (Object)
669 • VersionInfo (Object)
671 • query-version (Command)
673 • CommandInfo (Object)
675 • query-commands (Command)
677 • quit (Command)
679 • MonitorMode (Enum)
681 • MonitorOptions (Object)
683 • QMP introspection
685 • query-qmp-schema (Command)
687 • SchemaMetaType (Enum)
689 • SchemaInfo (Object)
691 • SchemaInfoBuiltin (Object)
693 • JSONType (Enum)
695 • SchemaInfoEnum (Object)
697 • SchemaInfoEnumMember (Object)
699 • SchemaInfoArray (Object)
701 • SchemaInfoObject (Object)
703 • SchemaInfoObjectMember (Object)
705 • SchemaInfoObjectVariant (Object)
707 • SchemaInfoAlternate (Object)
709 • SchemaInfoAlternateMember (Object)
711 • SchemaInfoCommand (Object)
713 • SchemaInfoEvent (Object)
715 • QEMU Object Model (QOM)
717 • ObjectPropertyInfo (Object)
719 • qom-list (Command)
721 • qom-get (Command)
723 • qom-set (Command)
725 • ObjectTypeInfo (Object)
727 • qom-list-types (Command)
729 • qom-list-properties (Command)
731 • CanHostSocketcanProperties (Object)
733 • ColoCompareProperties (Object)
735 • CryptodevBackendProperties (Object)
737 • CryptodevVhostUserProperties (Object)
739 • DBusVMStateProperties (Object)
741 • NetfilterInsert (Enum)
743 • NetfilterProperties (Object)
745 • FilterBufferProperties (Object)
747 • FilterDumpProperties (Object)
749 • FilterMirrorProperties (Object)
751 • FilterRedirectorProperties (Object)
753 • FilterRewriterProperties (Object)
755 • InputBarrierProperties (Object)
757 • InputLinuxProperties (Object)
759 • IothreadProperties (Object)
761 • MemoryBackendProperties (Object)
763 • MemoryBackendFileProperties (Object)
765 • MemoryBackendMemfdProperties (Object)
767 • MemoryBackendEpcProperties (Object)
769 • PrManagerHelperProperties (Object)
771 • QtestProperties (Object)
773 • RemoteObjectProperties (Object)
775 • RngProperties (Object)
777 • RngEgdProperties (Object)
779 • RngRandomProperties (Object)
781 • SevGuestProperties (Object)
783 • ObjectType (Enum)
785 • ObjectOptions (Object)
787 • object-add (Command)
789 • object-del (Command)
791 • Device infrastructure (qdev)
793 • device-list-properties (Command)
795 • device_add (Command)
797 • device_del (Command)
799 • DEVICE_DELETED (Event)
801 • DEVICE_UNPLUG_GUEST_ERROR (Event)
803 • Machines
805 • SysEmuTarget (Enum)
807 • CpuS390State (Enum)
809 • CpuInfoS390 (Object)
811 • CpuInfoFast (Object)
813 • query-cpus-fast (Command)
815 • MachineInfo (Object)
817 • query-machines (Command)
819 • CurrentMachineParams (Object)
821 • query-current-machine (Command)
823 • TargetInfo (Object)
825 • query-target (Command)
827 • UuidInfo (Object)
829 • query-uuid (Command)
831 • GuidInfo (Object)
833 • query-vm-generation-id (Command)
835 • system_reset (Command)
837 • system_powerdown (Command)
839 • system_wakeup (Command)
841 • LostTickPolicy (Enum)
843 • inject-nmi (Command)
845 • KvmInfo (Object)
847 • query-kvm (Command)
849 • NumaOptionsType (Enum)
851 • NumaOptions (Object)
853 • NumaNodeOptions (Object)
855 • NumaDistOptions (Object)
857 • X86CPURegister32 (Enum)
859 • X86CPUFeatureWordInfo (Object)
861 • DummyForceArrays (Object)
863 • NumaCpuOptions (Object)
865 • HmatLBMemoryHierarchy (Enum)
867 • HmatLBDataType (Enum)
869 • NumaHmatLBOptions (Object)
871 • HmatCacheAssociativity (Enum)
873 • HmatCacheWritePolicy (Enum)
875 • NumaHmatCacheOptions (Object)
877 • memsave (Command)
879 • pmemsave (Command)
881 • Memdev (Object)
883 • query-memdev (Command)
885 • CpuInstanceProperties (Object)
887 • HotpluggableCPU (Object)
889 • query-hotpluggable-cpus (Command)
891 • set-numa-node (Command)
893 • balloon (Command)
895 • BalloonInfo (Object)
897 • query-balloon (Command)
899 • BALLOON_CHANGE (Event)
901 • MemoryInfo (Object)
903 • query-memory-size-summary (Command)
905 • PCDIMMDeviceInfo (Object)
907 • VirtioPMEMDeviceInfo (Object)
909 • VirtioMEMDeviceInfo (Object)
911 • SgxEPCDeviceInfo (Object)
913 • MemoryDeviceInfoKind (Enum)
915 • PCDIMMDeviceInfoWrapper (Object)
917 • VirtioPMEMDeviceInfoWrapper (Object)
919 • VirtioMEMDeviceInfoWrapper (Object)
921 • SgxEPCDeviceInfoWrapper (Object)
923 • MemoryDeviceInfo (Object)
925 • SgxEPC (Object)
927 • SgxEPCProperties (Object)
929 • query-memory-devices (Command)
931 • MEMORY_DEVICE_SIZE_CHANGE (Event)
933 • MEM_UNPLUG_ERROR (Event)
935 • SMPConfiguration (Object)
937 • x-query-irq (Command)
939 • x-query-jit (Command)
941 • x-query-numa (Command)
943 • x-query-opcount (Command)
945 • x-query-profile (Command)
947 • x-query-ramblock (Command)
949 • x-query-rdma (Command)
951 • x-query-roms (Command)
953 • x-query-usb (Command)
955 • CpuModelInfo (Object)
957 • CpuModelExpansionType (Enum)
959 • CpuModelCompareResult (Enum)
961 • CpuModelBaselineInfo (Object)
963 • CpuModelCompareInfo (Object)
965 • query-cpu-model-comparison (Command)
967 • query-cpu-model-baseline (Command)
969 • CpuModelExpansionInfo (Object)
971 • query-cpu-model-expansion (Command)
973 • CpuDefinitionInfo (Object)
975 • query-cpu-definitions (Command)
977 • Record/replay
979 • ReplayMode (Enum)
981 • ReplayInfo (Object)
983 • query-replay (Command)
985 • replay-break (Command)
987 • replay-delete-break (Command)
989 • replay-seek (Command)
991 • Yank feature
993 • YankInstanceType (Enum)
995 • YankInstanceBlockNode (Object)
997 • YankInstanceChardev (Object)
999 • YankInstance (Object)
1001 • yank (Command)
1003 • query-yank (Command)
1005 • Miscellanea
1007 • add_client (Command)
1009 • NameInfo (Object)
1011 • query-name (Command)
1013 • IOThreadInfo (Object)
1015 • query-iothreads (Command)
1017 • stop (Command)
1019 • cont (Command)
1021 • x-exit-preconfig (Command)
1023 • human-monitor-command (Command)
1025 • getfd (Command)
1027 • closefd (Command)
1029 • AddfdInfo (Object)
1031 • add-fd (Command)
1033 • remove-fd (Command)
1035 • FdsetFdInfo (Object)
1037 • FdsetInfo (Object)
1039 • query-fdsets (Command)
1041 • CommandLineParameterType (Enum)
1043 • CommandLineParameterInfo (Object)
1045 • CommandLineOptionInfo (Object)
1047 • query-command-line-options (Command)
1049 • RTC_CHANGE (Event)
1051 • rtc-reset-reinjection (Command)
1053 • SevState (Enum)
1055 • SevInfo (Object)
1057 • query-sev (Command)
1059 • SevLaunchMeasureInfo (Object)
1061 • query-sev-launch-measure (Command)
1063 • SevCapability (Object)
1065 • query-sev-capabilities (Command)
1067 • sev-inject-launch-secret (Command)
1069 • SevAttestationReport (Object)
1071 • query-sev-attestation-report (Command)
1073 • dump-skeys (Command)
1075 • GICCapability (Object)
1077 • query-gic-capabilities (Command)
1079 • SGXInfo (Object)
1081 • query-sgx (Command)
1083 • query-sgx-capabilities (Command)
1085 • Audio
1087 • AudiodevPerDirectionOptions (Object)
1089 • AudiodevGenericOptions (Object)
1091 • AudiodevAlsaPerDirectionOptions (Object)
1093 • AudiodevAlsaOptions (Object)
1095 • AudiodevCoreaudioPerDirectionOptions (Object)
1097 • AudiodevCoreaudioOptions (Object)
1099 • AudiodevDsoundOptions (Object)
1101 • AudiodevJackPerDirectionOptions (Object)
1103 • AudiodevJackOptions (Object)
1105 • AudiodevOssPerDirectionOptions (Object)
1107 • AudiodevOssOptions (Object)
1109 • AudiodevPaPerDirectionOptions (Object)
1111 • AudiodevPaOptions (Object)
1113 • AudiodevSdlPerDirectionOptions (Object)
1115 • AudiodevSdlOptions (Object)
1117 • AudiodevWavOptions (Object)
1119 • AudioFormat (Enum)
1121 • AudiodevDriver (Enum)
1123 • Audiodev (Object)
1125 • ACPI
1127 • AcpiTableOptions (Object)
1129 • ACPISlotType (Enum)
1131 • ACPIOSTInfo (Object)
1133 • query-acpi-ospm-status (Command)
1135 • ACPI_DEVICE_OST (Event)
1137 • PCI
1139 • PciMemoryRange (Object)
1141 • PciMemoryRegion (Object)
1143 • PciBusInfo (Object)
1145 • PciBridgeInfo (Object)
1147 • PciDeviceClass (Object)
1149 • PciDeviceId (Object)
1151 • PciDeviceInfo (Object)
1153 • PciInfo (Object)
1155 • query-pci (Command)
1157
1159 This document describes all commands currently supported by QMP.
1160 Most of the time their usage is exactly the same as in the user Moni‐
1162 tor, this means that any other document which also describe commands
1163 (the manpage, QEMU's manual, etc) can and should be consulted.
1164 QMP has two types of commands: regular and query commands. Regular com‐
1166 mands usually change the Virtual Machine's state someway, while query
1167 commands just return information. The sections below are divided ac‐
1168 cordingly.
1169 It's important to observe that all communication examples are formatted
1171 in a reader-friendly way, so that they're easier to understand. How‐
1172 ever, in real protocol usage, they're emitted as a single line.
1173 Also, the following notation is used to denote data flow:
1175 Example:
1177 -> data issued by the Client
1179 <- Server data response
1180 Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
1182 detailed information on the Server command and response formats.
1183
1185 The current QMP command set (described in this file) may be useful for
1186 a number of use cases, however it's limited and several commands have
1187 bad defined semantics, specially with regard to command completion.
1188 These problems are going to be solved incrementally in the next QEMU
1190 releases and we're going to establish a deprecation policy for badly
1191 defined commands.
1192 If you're planning to adopt QMP, please observe the following:
1194 1. The deprecation policy will take effect and be documented soon,
1196 please check the documentation of each used command as soon as a
1197 new release of QEMU is available
1198 2. DO NOT rely on anything which is not explicit documented
1200 3. Errors, in special, are not documented. Applications should NOT
1202 check for specific errors classes or data (it's strongly recom‐
1203 mended to only check for the "error" key)
1204
1206 QapiErrorClass (Enum)
1207 QEMU error classes
1208 Values
1210 GenericError
1211 this is used for errors that don't require a specific error
1212 class. This should be the default case for most errors
1213 CommandNotFound
1215 the requested command has not been found
1216 DeviceNotActive
1218 a device has failed to be become active
1219 DeviceNotFound
1221 the requested device has not been found
1222 KVMMissingCap
1224 the requested operation can't be fulfilled because a required
1225 KVM capability is missing
1226 Since
1228 1.2
1229
1231 IoOperationType (Enum)
1232 An enumeration of the I/O operation types
1233 Values
1235 read read operation
1236 write write operation
1238 Since
1240 2.1
1241 OnOffAuto (Enum)
1243 An enumeration of three options: on, off, and auto
1244 Values
1246 auto QEMU selects the value between on and off
1247 on Enabled
1249 off Disabled
1251 Since
1253 2.2
1254 OnOffSplit (Enum)
1256 An enumeration of three values: on, off, and split
1257 Values
1259 on Enabled
1260 off Disabled
1262 split Mixed
1264 Since
1266 2.6
1267 String (Object)
1269 A fat type wrapping 'str', to be embedded in lists.
1270 Members
1272 str: string
1273 Not documented
1274 Since
1276 1.2
1277 StrOrNull (Alternate)
1279 This is a string value or the explicit lack of a string (null pointer
1280 in C). Intended for cases when 'optional absent' already has a differ‐
1281 ent meaning.
1282 Members
1284 s: string
1285 the string value
1286 n: null
1288 no string value
1289 Since
1291 2.10
1292 OffAutoPCIBAR (Enum)
1294 An enumeration of options for specifying a PCI BAR
1295 Values
1297 off The specified feature is disabled
1298 auto The PCI BAR for the feature is automatically selected
1300 bar0 PCI BAR0 is used for the feature
1302 bar1 PCI BAR1 is used for the feature
1304 bar2 PCI BAR2 is used for the feature
1306 bar3 PCI BAR3 is used for the feature
1308 bar4 PCI BAR4 is used for the feature
1310 bar5 PCI BAR5 is used for the feature
1312 Since
1314 2.12
1315 PCIELinkSpeed (Enum)
1317 An enumeration of PCIe link speeds in units of GT/s
1318 Values
1320 2_5 2.5GT/s
1321 5 5.0GT/s
1323 8 8.0GT/s
1325 16 16.0GT/s
1327 Since
1329 4.0
1330 PCIELinkWidth (Enum)
1332 An enumeration of PCIe link width
1333 Values
1335 1 x1
1336 2 x2
1338 4 x4
1340 8 x8
1342 12 x12
1344 16 x16
1346 32 x32
1348 Since
1350 4.0
1351 HostMemPolicy (Enum)
1353 Host memory policy types
1354 Values
1356 default
1357 restore default policy, remove any nondefault policy
1358 preferred
1360 set the preferred host nodes for allocation
1361 bind a strict policy that restricts memory allocation to the host
1363 nodes specified
1364 interleave
1366 memory allocations are interleaved across the set of host nodes
1367 specified
1368 Since
1370 2.1
1371 NetFilterDirection (Enum)
1373 Indicates whether a netfilter is attached to a netdev's transmit queue
1374 or receive queue or both.
1375 Values
1377 all the filter is attached both to the receive and the transmit
1378 queue of the netdev (default).
1379 rx the filter is attached to the receive queue of the netdev, where
1381 it will receive packets sent to the netdev.
1382 tx the filter is attached to the transmit queue of the netdev,
1384 where it will receive packets sent by the netdev.
1385 Since
1387 2.5
1388 GrabToggleKeys (Enum)
1390 Keys to toggle input-linux between host and guest.
1391 Values
1393 ctrl-ctrl
1394 Not documented
1395 alt-alt
1397 Not documented
1398 shift-shift
1400 Not documented
1401 meta-meta
1403 Not documented
1404 scrolllock
1406 Not documented
1407 ctrl-scrolllock
1409 Not documented
1410 Since
1412 4.0
1413 HumanReadableText (Object)
1415 Members
1416 human-readable-text: string
1417 Formatted output intended for humans.
1418 Since
1420 6.2
1421
1423 NetworkAddressFamily (Enum)
1424 The network address family
1425 Values
1427 ipv4 IPV4 family
1428 ipv6 IPV6 family
1430 unix unix socket
1432 vsock vsock family (since 2.8)
1434 unknown
1436 otherwise
1437 Since
1439 2.1
1440 InetSocketAddressBase (Object)
1442 Members
1443 host: string
1444 host part of the address
1445 port: string
1447 port part of the address
1448 InetSocketAddress (Object)
1450 Captures a socket address or address range in the Internet namespace.
1451 Members
1453 numeric: boolean (optional)
1454 true if the host/port are guaranteed to be numeric, false if
1455 name resolution should be attempted. Defaults to false. (Since
1456 2.9)
1457 to: int (optional)
1459 If present, this is range of possible addresses, with port be‐
1460 tween port and to.
1461 ipv4: boolean (optional)
1463 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1464 ipv6: boolean (optional)
1466 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1467 keep-alive: boolean (optional)
1469 enable keep-alive when connecting to this socket. Not supported
1470 for passive sockets. (Since 4.2)
1471 mptcp: boolean (optional) (If: HAVE_IPPROTO_MPTCP)
1473 enable multi-path TCP. (Since 6.1)
1474 The members of InetSocketAddressBase
1476 Since
1478 1.3
1479 UnixSocketAddress (Object)
1481 Captures a socket address in the local ("Unix socket") namespace.
1482 Members
1484 path: string
1485 filesystem path to use
1486 abstract: boolean (optional) (If: CONFIG_LINUX)
1488 if true, this is a Linux abstract socket address. path will be
1489 prefixed by a null byte, and optionally padded with null bytes.
1490 Defaults to false. (Since 5.1)
1491 tight: boolean (optional) (If: CONFIG_LINUX)
1493 if false, pad an abstract socket address with enough null bytes
1494 to make it fill struct sockaddr_un member sun_path. Defaults to
1495 true. (Since 5.1)
1496 Since
1498 1.3
1499 VsockSocketAddress (Object)
1501 Captures a socket address in the vsock namespace.
1502 Members
1504 cid: string
1505 unique host identifier
1506 port: string
1508 port
1509 Note
1511 string types are used to allow for possible future hostname or service
1512 resolution support.
1513 Since
1515 2.8
1516 InetSocketAddressWrapper (Object)
1518 Members
1519 data: InetSocketAddress
1520 Not documented
1521 Since
1523 1.3
1524 UnixSocketAddressWrapper (Object)
1526 Members
1527 data: UnixSocketAddress
1528 Not documented
1529 Since
1531 1.3
1532 VsockSocketAddressWrapper (Object)
1534 Members
1535 data: VsockSocketAddress
1536 Not documented
1537 Since
1539 2.8
1540 StringWrapper (Object)
1542 Members
1543 data: String
1544 Not documented
1545 Since
1547 1.3
1548 SocketAddressLegacy (Object)
1550 Captures the address of a socket, which could also be a named file de‐
1551 scriptor
1552 Members
1554 type: SocketAddressType
1555 Not documented
1556 The members of InetSocketAddressWrapper when type is "inet"
1558 The members of UnixSocketAddressWrapper when type is "unix"
1560 The members of VsockSocketAddressWrapper when type is "vsock"
1562 The members of StringWrapper when type is "fd"
1564 Note
1566 This type is deprecated in favor of SocketAddress. The difference be‐
1567 tween SocketAddressLegacy and SocketAddress is that the latter is has
1568 fewer {} on the wire.
1569 Since
1571 1.3
1572 SocketAddressType (Enum)
1574 Available SocketAddress types
1575 Values
1577 inet Internet address
1578 unix Unix domain socket
1580 vsock VMCI address
1582 fd decimal is for file descriptor number, otherwise a file descrip‐
1584 tor name. Named file descriptors are permitted in monitor com‐
1585 mands, in combination with the 'getfd' command. Decimal file de‐
1586 scriptors are permitted at startup or other contexts where no
1587 monitor context is active.
1588 Since
1590 2.9
1591 SocketAddress (Object)
1593 Captures the address of a socket, which could also be a named file de‐
1594 scriptor
1595 Members
1597 type: SocketAddressType
1598 Transport type
1599 The members of InetSocketAddress when type is "inet"
1601 The members of UnixSocketAddress when type is "unix"
1603 The members of VsockSocketAddress when type is "vsock"
1605 The members of String when type is "fd"
1607 Since
1609 2.9
1610
1612 RunState (Enum)
1613 An enumeration of VM run states.
1614 Values
1616 debug QEMU is running on a debugger
1617 finish-migrate
1619 guest is paused to finish the migration process
1620 inmigrate
1622 guest is paused waiting for an incoming migration. Note that
1623 this state does not tell whether the machine will start at the
1624 end of the migration. This depends on the command-line -S op‐
1625 tion and any invocation of 'stop' or 'cont' that has happened
1626 since QEMU was started.
1627 internal-error
1629 An internal error that prevents further guest execution has oc‐
1630 curred
1631 io-error
1633 the last IOP has failed and the device is configured to pause on
1634 I/O errors
1635 paused guest has been paused via the 'stop' command
1637 postmigrate
1639 guest is paused following a successful 'migrate'
1640 prelaunch
1642 QEMU was started with -S and guest has not started
1643 restore-vm
1645 guest is paused to restore VM state
1646 running
1648 guest is actively running
1649 save-vm
1651 guest is paused to save the VM state
1652 shutdown
1654 guest is shut down (and -no-shutdown is in use)
1655 suspended
1657 guest is suspended (ACPI S3)
1658 watchdog
1660 the watchdog action is configured to pause and has been trig‐
1661 gered
1662 guest-panicked
1664 guest has been panicked as a result of guest OS panic
1665 colo guest is paused to save/restore VM state under colo checkpoint,
1667 VM can not get into this state unless colo capability is enabled
1668 for migration. (since 2.8)
1669 ShutdownCause (Enum)
1671 An enumeration of reasons for a Shutdown.
1672 Values
1674 none No shutdown request pending
1675 host-error
1677 An error prevents further use of guest
1678 host-qmp-quit
1680 Reaction to the QMP command 'quit'
1681 host-qmp-system-reset
1683 Reaction to the QMP command 'system_reset'
1684 host-signal
1686 Reaction to a signal, such as SIGINT
1687 host-ui
1689 Reaction to a UI event, like window close
1690 guest-shutdown
1692 Guest shutdown/suspend request, via ACPI or other hardware-spe‐
1693 cific means
1694 guest-reset
1696 Guest reset request, and command line turns that into a shutdown
1697 guest-panic
1699 Guest panicked, and command line turns that into a shutdown
1700 subsystem-reset
1702 Partial guest reset that does not trigger QMP events and ignores
1703 --no-reboot. This is useful for sanitizing hypercalls on s390
1704 that are used during kexec/kdump/boot
1705 StatusInfo (Object)
1707 Information about VCPU run state
1708 Members
1710 running: boolean
1711 true if all VCPUs are runnable, false if not runnable
1712 singlestep: boolean
1714 true if VCPUs are in single-step mode
1715 status: RunState
1717 the virtual machine RunState
1718 Since
1720 0.14
1721 Notes
1723 singlestep is enabled through the GDB stub
1724 query-status (Command)
1726 Query the run status of all VCPUs
1727 Returns
1729 StatusInfo reflecting all VCPUs
1730 Since
1732 0.14
1733 Example
1735 -> { "execute": "query-status" }
1736 <- { "return": { "running": true,
1737 "singlestep": false,
1738 "status": "running" } }
1739 SHUTDOWN (Event)
1741 Emitted when the virtual machine has shut down, indicating that qemu is
1742 about to exit.
1743 Arguments
1745 guest: boolean
1746 If true, the shutdown was triggered by a guest request (such as
1747 a guest-initiated ACPI shutdown request or other hardware-spe‐
1748 cific action) rather than a host request (such as sending qemu a
1749 SIGINT). (since 2.10)
1750 reason: ShutdownCause
1752 The ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
1753 Note
1755 If the command-line option "-no-shutdown" has been specified, qemu will
1756 not exit, and a STOP event will eventually follow the SHUTDOWN event
1757 Since
1759 0.12
1760 Example
1762 <- { "event": "SHUTDOWN", "data": { "guest": true },
1763 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1764 POWERDOWN (Event)
1766 Emitted when the virtual machine is powered down through the power con‐
1767 trol system, such as via ACPI.
1768 Since
1770 0.12
1771 Example
1773 <- { "event": "POWERDOWN",
1774 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1775 RESET (Event)
1777 Emitted when the virtual machine is reset
1778 Arguments
1780 guest: boolean
1781 If true, the reset was triggered by a guest request (such as a
1782 guest-initiated ACPI reboot request or other hardware-specific
1783 action) rather than a host request (such as the QMP command sys‐
1784 tem_reset). (since 2.10)
1785 reason: ShutdownCause
1787 The ShutdownCause of the RESET. (since 4.0)
1788 Since
1790 0.12
1791 Example
1793 <- { "event": "RESET", "data": { "guest": false },
1794 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
1795 STOP (Event)
1797 Emitted when the virtual machine is stopped
1798 Since
1800 0.12
1801 Example
1803 <- { "event": "STOP",
1804 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
1805 RESUME (Event)
1807 Emitted when the virtual machine resumes execution
1808 Since
1810 0.12
1811 Example
1813 <- { "event": "RESUME",
1814 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
1815 SUSPEND (Event)
1817 Emitted when guest enters a hardware suspension state, for example, S3
1818 state, which is sometimes called standby state
1819 Since
1821 1.1
1822 Example
1824 <- { "event": "SUSPEND",
1825 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
1826 SUSPEND_DISK (Event)
1828 Emitted when guest enters a hardware suspension state with data saved
1829 on disk, for example, S4 state, which is sometimes called hibernate
1830 state
1831 Note
1833 QEMU shuts down (similar to event SHUTDOWN) when entering this state
1834 Since
1836 1.2
1837 Example
1839 <- { "event": "SUSPEND_DISK",
1840 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
1841 WAKEUP (Event)
1843 Emitted when the guest has woken up from suspend state and is running
1844 Since
1846 1.1
1847 Example
1849 <- { "event": "WAKEUP",
1850 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
1851 WATCHDOG (Event)
1853 Emitted when the watchdog device's timer is expired
1854 Arguments
1856 action: WatchdogAction
1857 action that has been taken
1858 Note
1860 If action is "reset", "shutdown", or "pause" the WATCHDOG event is fol‐
1861 lowed respectively by the RESET, SHUTDOWN, or STOP events
1862 Note
1864 This event is rate-limited.
1865 Since
1867 0.13
1868 Example
1870 <- { "event": "WATCHDOG",
1871 "data": { "action": "reset" },
1872 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
1873 WatchdogAction (Enum)
1875 An enumeration of the actions taken when the watchdog device's timer is
1876 expired
1877 Values
1879 reset system resets
1880 shutdown
1882 system shutdown, note that it is similar to powerdown, which
1883 tries to set to system status and notify guest
1884 poweroff
1886 system poweroff, the emulator program exits
1887 pause system pauses, similar to stop
1889 debug system enters debug state
1891 none nothing is done
1893 inject-nmi
1895 a non-maskable interrupt is injected into the first VCPU (all
1896 VCPUS on x86) (since 2.4)
1897 Since
1899 2.1
1900 RebootAction (Enum)
1902 Possible QEMU actions upon guest reboot
1903 Values
1905 reset Reset the VM
1906 shutdown
1908 Shutdown the VM and exit, according to the shutdown action
1909 Since
1911 6.0
1912 ShutdownAction (Enum)
1914 Possible QEMU actions upon guest shutdown
1915 Values
1917 poweroff
1918 Shutdown the VM and exit
1919 pause pause the VM#
1921 Since
1923 6.0
1924 PanicAction (Enum)
1926 Values
1927 none Continue VM execution
1928 pause Pause the VM
1930 shutdown
1932 Shutdown the VM and exit, according to the shutdown action
1933 Since
1935 6.0
1936 watchdog-set-action (Command)
1938 Set watchdog action
1939 Arguments
1941 action: WatchdogAction
1942 Not documented
1943 Since
1945 2.11
1946 set-action (Command)
1948 Set the actions that will be taken by the emulator in response to guest
1949 events.
1950 Arguments
1952 reboot: RebootAction (optional)
1953 RebootAction action taken on guest reboot.
1954 shutdown: ShutdownAction (optional)
1956 ShutdownAction action taken on guest shutdown.
1957 panic: PanicAction (optional)
1959 PanicAction action taken on guest panic.
1960 watchdog: WatchdogAction (optional)
1962 WatchdogAction action taken when watchdog timer expires .
1963 Returns
1965 Nothing on success.
1966 Since
1968 6.0
1969 Example
1971 -> { "execute": "set-action",
1972 "arguments": { "reboot": "shutdown",
1973 "shutdown" : "pause",
1974 "panic": "pause",
1975 "watchdog": "inject-nmi" } }
1976 <- { "return": {} }
1977 GUEST_PANICKED (Event)
1979 Emitted when guest OS panic is detected
1980 Arguments
1982 action: GuestPanicAction
1983 action that has been taken, currently always "pause"
1984 info: GuestPanicInformation (optional)
1986 information about a panic (since 2.9)
1987 Since
1989 1.5
1990 Example
1992 <- { "event": "GUEST_PANICKED",
1993 "data": { "action": "pause" } }
1994 GUEST_CRASHLOADED (Event)
1996 Emitted when guest OS crash loaded is detected
1997 Arguments
1999 action: GuestPanicAction
2000 action that has been taken, currently always "run"
2001 info: GuestPanicInformation (optional)
2003 information about a panic
2004 Since
2006 5.0
2007 Example
2009 <- { "event": "GUEST_CRASHLOADED",
2010 "data": { "action": "run" } }
2011 GuestPanicAction (Enum)
2013 An enumeration of the actions taken when guest OS panic is detected
2014 Values
2016 pause system pauses
2017 poweroff
2019 Not documented
2020 run Not documented
2022 Since
2024 2.1 (poweroff since 2.8, run since 5.0)
2025 GuestPanicInformationType (Enum)
2027 An enumeration of the guest panic information types
2028 Values
2030 hyper-v
2031 hyper-v guest panic information type
2032 s390 s390 guest panic information type (Since: 2.12)
2034 Since
2036 2.9
2037 GuestPanicInformation (Object)
2039 Information about a guest panic
2040 Members
2042 type: GuestPanicInformationType
2043 Crash type that defines the hypervisor specific information
2044 The members of GuestPanicInformationHyperV when type is "hyper-v"
2046 The members of GuestPanicInformationS390 when type is "s390"
2048 Since
2050 2.9
2051 GuestPanicInformationHyperV (Object)
2053 Hyper-V specific guest panic information (HV crash MSRs)
2054 Members
2056 arg1: int
2057 Not documented
2058 arg2: int
2060 Not documented
2061 arg3: int
2063 Not documented
2064 arg4: int
2066 Not documented
2067 arg5: int
2069 Not documented
2070 Since
2072 2.9
2073 S390CrashReason (Enum)
2075 Reason why the CPU is in a crashed state.
2076 Values
2078 unknown
2079 no crash reason was set
2080 disabled-wait
2082 the CPU has entered a disabled wait state
2083 extint-loop
2085 clock comparator or cpu timer interrupt with new PSW enabled for
2086 external interrupts
2087 pgmint-loop
2089 program interrupt with BAD new PSW
2090 opint-loop
2092 operation exception interrupt with invalid code at the program
2093 interrupt new PSW
2094 Since
2096 2.12
2097 GuestPanicInformationS390 (Object)
2099 S390 specific guest panic information (PSW)
2100 Members
2102 core: int
2103 core id of the CPU that crashed
2104 psw-mask: int
2106 control fields of guest PSW
2107 psw-addr: int
2109 guest instruction address
2110 reason: S390CrashReason
2112 guest crash reason
2113 Since
2115 2.12
2116 MEMORY_FAILURE (Event)
2118 Emitted when a memory failure occurs on host side.
2119 Arguments
2121 recipient: MemoryFailureRecipient
2122 recipient is defined as MemoryFailureRecipient.
2123 action: MemoryFailureAction
2125 action that has been taken. action is defined as MemoryFailure‐
2126 Action.
2127 flags: MemoryFailureFlags
2129 flags for MemoryFailureAction. action is defined as MemoryFail‐
2130 ureFlags.
2131 Since
2133 5.2
2134 Example
2136 <- { "event": "MEMORY_FAILURE",
2137 "data": { "recipient": "hypervisor",
2138 "action": "fatal",
2139 "flags": { 'action-required': false } }
2140 MemoryFailureRecipient (Enum)
2142 Hardware memory failure occurs, handled by recipient.
2143 Values
2145 hypervisor
2146 memory failure at QEMU process address space. (none guest mem‐
2147 ory, but used by QEMU itself).
2148 guest memory failure at guest memory,
2150 Since
2152 5.2
2153 MemoryFailureAction (Enum)
2155 Actions taken by QEMU in response to a hardware memory failure.
2156 Values
2158 ignore the memory failure could be ignored. This will only be the case
2159 for action-optional failures.
2160 inject memory failure occurred in guest memory, the guest enabled MCE
2162 handling mechanism, and QEMU could inject the MCE into the guest
2163 successfully.
2164 fatal the failure is unrecoverable. This occurs for action-required
2166 failures if the recipient is the hypervisor; QEMU will exit.
2167 reset the failure is unrecoverable but confined to the guest. This
2169 occurs if the recipient is a guest guest which is not ready to
2170 handle memory failures.
2171 Since
2173 5.2
2174 MemoryFailureFlags (Object)
2176 Additional information on memory failures.
2177 Members
2179 action-required: boolean
2180 whether a memory failure event is action-required or action-op‐
2181 tional (e.g. a failure during memory scrub).
2182 recursive: boolean
2184 whether the failure occurred while the previous failure was
2185 still in progress.
2186 Since
2188 5.2
2189
2191 QCryptoTLSCredsEndpoint (Enum)
2192 The type of network endpoint that will be using the credentials. Most
2193 types of credential require different setup / structures depending on
2194 whether they will be used in a server versus a client.
2195 Values
2197 client the network endpoint is acting as the client
2198 server the network endpoint is acting as the server
2200 Since
2202 2.5
2203 QCryptoSecretFormat (Enum)
2205 The data format that the secret is provided in
2206 Values
2208 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
2209 be used
2210 base64 arbitrary base64 encoded binary data
2212 Since
2214 2.6
2215 QCryptoHashAlgorithm (Enum)
2217 The supported algorithms for computing content digests
2218 Values
2220 md5 MD5. Should not be used in any new code, legacy compat only
2221 sha1 SHA-1. Should not be used in any new code, legacy compat only
2223 sha224 SHA-224. (since 2.7)
2225 sha256 SHA-256. Current recommended strong hash.
2227 sha384 SHA-384. (since 2.7)
2229 sha512 SHA-512. (since 2.7)
2231 ripemd160
2233 RIPEMD-160. (since 2.7)
2234 Since
2236 2.6
2237 QCryptoCipherAlgorithm (Enum)
2239 The supported algorithms for content encryption ciphers
2240 Values
2242 aes-128
2243 AES with 128 bit / 16 byte keys
2244 aes-192
2246 AES with 192 bit / 24 byte keys
2247 aes-256
2249 AES with 256 bit / 32 byte keys
2250 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
2252 6.1)
2253 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
2255 cast5-128
2257 Cast5 with 128 bit / 16 byte keys
2258 serpent-128
2260 Serpent with 128 bit / 16 byte keys
2261 serpent-192
2263 Serpent with 192 bit / 24 byte keys
2264 serpent-256
2266 Serpent with 256 bit / 32 byte keys
2267 twofish-128
2269 Twofish with 128 bit / 16 byte keys
2270 twofish-192
2272 Twofish with 192 bit / 24 byte keys
2273 twofish-256
2275 Twofish with 256 bit / 32 byte keys
2276 Since
2278 2.6
2279 QCryptoCipherMode (Enum)
2281 The supported modes for content encryption ciphers
2282 Values
2284 ecb Electronic Code Book
2285 cbc Cipher Block Chaining
2287 xts XEX with tweaked code book and ciphertext stealing
2289 ctr Counter (Since 2.8)
2291 Since
2293 2.6
2294 QCryptoIVGenAlgorithm (Enum)
2296 The supported algorithms for generating initialization vectors for full
2297 disk encryption. The 'plain' generator should not be used for disks
2298 with sector numbers larger than 2^32, except where compatibility with
2299 pre-existing Linux dm-crypt volumes is required.
2300 Values
2302 plain 64-bit sector number truncated to 32-bits
2303 plain64
2305 64-bit sector number
2306 essiv 64-bit sector number encrypted with a hash of the encryption key
2308 Since
2310 2.6
2311 QCryptoBlockFormat (Enum)
2313 The supported full disk encryption formats
2314 Values
2316 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
2317 data from old images.
2318 luks LUKS encryption format. Recommended for new images
2320 Since
2322 2.6
2323 QCryptoBlockOptionsBase (Object)
2325 The common options that apply to all full disk encryption formats
2326 Members
2328 format: QCryptoBlockFormat
2329 the encryption format
2330 Since
2332 2.6
2333 QCryptoBlockOptionsQCow (Object)
2335 The options that apply to QCow/QCow2 AES-CBC encryption format
2336 Members
2338 key-secret: string (optional)
2339 the ID of a QCryptoSecret object providing the decryption key.
2340 Mandatory except when probing image for metadata only.
2341 Since
2343 2.6
2344 QCryptoBlockOptionsLUKS (Object)
2346 The options that apply to LUKS encryption format
2347 Members
2349 key-secret: string (optional)
2350 the ID of a QCryptoSecret object providing the decryption key.
2351 Mandatory except when probing image for metadata only.
2352 Since
2354 2.6
2355 QCryptoBlockCreateOptionsLUKS (Object)
2357 The options that apply to LUKS encryption format initialization
2358 Members
2360 cipher-alg: QCryptoCipherAlgorithm (optional)
2361 the cipher algorithm for data encryption Currently defaults to
2362 'aes-256'.
2363 cipher-mode: QCryptoCipherMode (optional)
2365 the cipher mode for data encryption Currently defaults to 'xts'
2366 ivgen-alg: QCryptoIVGenAlgorithm (optional)
2368 the initialization vector generator Currently defaults to
2369 'plain64'
2370 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2372 the initialization vector generator hash Currently defaults to
2373 'sha256'
2374 hash-alg: QCryptoHashAlgorithm (optional)
2376 the master key hash algorithm Currently defaults to 'sha256'
2377 iter-time: int (optional)
2379 number of milliseconds to spend in PBKDF passphrase processing.
2380 Currently defaults to 2000. (since 2.8)
2381 The members of QCryptoBlockOptionsLUKS
2383 Since
2385 2.6
2386 QCryptoBlockOpenOptions (Object)
2388 The options that are available for all encryption formats when opening
2389 an existing volume
2390 Members
2392 The members of QCryptoBlockOptionsBase
2393 The members of QCryptoBlockOptionsQCow when format is "qcow"
2395 The members of QCryptoBlockOptionsLUKS when format is "luks"
2397 Since
2399 2.6
2400 QCryptoBlockCreateOptions (Object)
2402 The options that are available for all encryption formats when initial‐
2403 izing a new volume
2404 Members
2406 The members of QCryptoBlockOptionsBase
2407 The members of QCryptoBlockOptionsQCow when format is "qcow"
2409 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
2411 Since
2413 2.6
2414 QCryptoBlockInfoBase (Object)
2416 The common information that applies to all full disk encryption formats
2417 Members
2419 format: QCryptoBlockFormat
2420 the encryption format
2421 Since
2423 2.7
2424 QCryptoBlockInfoLUKSSlot (Object)
2426 Information about the LUKS block encryption key slot options
2427 Members
2429 active: boolean
2430 whether the key slot is currently in use
2431 key-offset: int
2433 offset to the key material in bytes
2434 iters: int (optional)
2436 number of PBKDF2 iterations for key material
2437 stripes: int (optional)
2439 number of stripes for splitting key material
2440 Since
2442 2.7
2443 QCryptoBlockInfoLUKS (Object)
2445 Information about the LUKS block encryption options
2446 Members
2448 cipher-alg: QCryptoCipherAlgorithm
2449 the cipher algorithm for data encryption
2450 cipher-mode: QCryptoCipherMode
2452 the cipher mode for data encryption
2453 ivgen-alg: QCryptoIVGenAlgorithm
2455 the initialization vector generator
2456 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2458 the initialization vector generator hash
2459 hash-alg: QCryptoHashAlgorithm
2461 the master key hash algorithm
2462 payload-offset: int
2464 offset to the payload data in bytes
2465 master-key-iters: int
2467 number of PBKDF2 iterations for key material
2468 uuid: string
2470 unique identifier for the volume
2471 slots: array of QCryptoBlockInfoLUKSSlot
2473 information about each key slot
2474 Since
2476 2.7
2477 QCryptoBlockInfo (Object)
2479 Information about the block encryption options
2480 Members
2482 The members of QCryptoBlockInfoBase
2483 The members of QCryptoBlockInfoLUKS when format is "luks"
2485 Since
2487 2.7
2488 QCryptoBlockLUKSKeyslotState (Enum)
2490 Defines state of keyslots that are affected by the update
2491 Values
2493 active The slots contain the given password and marked as active
2494 inactive
2496 The slots are erased (contain garbage) and marked as inactive
2497 Since
2499 5.1
2500 QCryptoBlockAmendOptionsLUKS (Object)
2502 This struct defines the update parameters that activate/de-activate set
2503 of keyslots
2504 Members
2506 state: QCryptoBlockLUKSKeyslotState
2507 the desired state of the keyslots
2508 new-secret: string (optional)
2510 The ID of a QCryptoSecret object providing the password to be
2511 written into added active keyslots
2512 old-secret: string (optional)
2514 Optional (for deactivation only) If given will deactivate all
2515 keyslots that match password located in QCryptoSecret with this
2516 ID
2517 iter-time: int (optional)
2519 Optional (for activation only) Number of milliseconds to spend
2520 in PBKDF passphrase processing for the newly activated keyslot.
2521 Currently defaults to 2000.
2522 keyslot: int (optional)
2524 Optional. ID of the keyslot to activate/deactivate. For keyslot
2525 activation, keyslot should not be active already (this is unsafe
2526 to update an active keyslot), but possible if 'force' parameter
2527 is given. If keyslot is not given, first free keyslot will be
2528 written.
2529 For keyslot deactivation, this parameter specifies the exact
2531 keyslot to deactivate
2532 secret: string (optional)
2534 Optional. The ID of a QCryptoSecret object providing the pass‐
2535 word to use to retrieve current master key. Defaults to the
2536 same secret that was used to open the image
2537 Since 5.1
2538 QCryptoBlockAmendOptions (Object)
2540 The options that are available for all encryption formats when amending
2541 encryption settings
2542 Members
2544 The members of QCryptoBlockOptionsBase
2545 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
2547 Since
2549 5.1
2550 SecretCommonProperties (Object)
2552 Properties for objects of classes derived from secret-common.
2553 Members
2555 loaded: boolean (optional)
2556 if true, the secret is loaded immediately when applying this op‐
2557 tion and will probably fail when processing the next option.
2558 Don't use; only provided for compatibility. (default: false)
2559 format: QCryptoSecretFormat (optional)
2561 the data format that the secret is provided in (default: raw)
2562 keyid: string (optional)
2564 the name of another secret that should be used to decrypt the
2565 provided data. If not present, the data is assumed to be unen‐
2566 crypted.
2567 iv: string (optional)
2569 the random initialization vector used for encryption of this
2570 particular secret. Should be a base64 encrypted string of the
2571 16-byte IV. Mandatory if keyid is given. Ignored if keyid is ab‐
2572 sent.
2573 Features
2575 deprecated
2576 Member loaded is deprecated. Setting true doesn't make sense,
2577 and false is already the default.
2578 Since
2580 2.6
2581 SecretProperties (Object)
2583 Properties for secret objects.
2584 Either data or file must be provided, but not both.
2586 Members
2588 data: string (optional)
2589 the associated with the secret from
2590 file: string (optional)
2592 the filename to load the data associated with the secret from
2593 The members of SecretCommonProperties
2595 Since
2597 2.6
2598 SecretKeyringProperties (Object)
2600 Properties for secret_keyring objects.
2601 Members
2603 serial: int
2604 serial number that identifies a key to get from the kernel
2605 The members of SecretCommonProperties
2607 Since
2609 5.1
2610 TlsCredsProperties (Object)
2612 Properties for objects of classes derived from tls-creds.
2613 Members
2615 verify-peer: boolean (optional)
2616 if true the peer credentials will be verified once the handshake
2617 is completed. This is a no-op for anonymous credentials. (de‐
2618 fault: true)
2619 dir: string (optional)
2621 the path of the directory that contains the credential files
2622 endpoint: QCryptoTLSCredsEndpoint (optional)
2624 whether the QEMU network backend that uses the credentials will
2625 be acting as a client or as a server (default: client)
2626 priority: string (optional)
2628 a gnutls priority string as described at
2629 https://gnutls.org/manual/html_node/Priority-Strings.html
2630 Since
2632 2.5
2633 TlsCredsAnonProperties (Object)
2635 Properties for tls-creds-anon objects.
2636 Members
2638 loaded: boolean (optional)
2639 if true, the credentials are loaded immediately when applying
2640 this option and will ignore options that are processed later.
2641 Don't use; only provided for compatibility. (default: false)
2642 The members of TlsCredsProperties
2644 Features
2646 deprecated
2647 Member loaded is deprecated. Setting true doesn't make sense,
2648 and false is already the default.
2649 Since
2651 2.5
2652 TlsCredsPskProperties (Object)
2654 Properties for tls-creds-psk objects.
2655 Members
2657 loaded: boolean (optional)
2658 if true, the credentials are loaded immediately when applying
2659 this option and will ignore options that are processed later.
2660 Don't use; only provided for compatibility. (default: false)
2661 username: string (optional)
2663 the username which will be sent to the server. For clients
2664 only. If absent, "qemu" is sent and the property will read back
2665 as an empty string.
2666 The members of TlsCredsProperties
2668 Features
2670 deprecated
2671 Member loaded is deprecated. Setting true doesn't make sense,
2672 and false is already the default.
2673 Since
2675 3.0
2676 TlsCredsX509Properties (Object)
2678 Properties for tls-creds-x509 objects.
2679 Members
2681 loaded: boolean (optional)
2682 if true, the credentials are loaded immediately when applying
2683 this option and will ignore options that are processed later.
2684 Don't use; only provided for compatibility. (default: false)
2685 sanity-check: boolean (optional)
2687 if true, perform some sanity checks before using the credentials
2688 (default: true)
2689 passwordid: string (optional)
2691 For the server-key.pem and client-key.pem files which contain
2692 sensitive private keys, it is possible to use an encrypted ver‐
2693 sion by providing the passwordid parameter. This provides the
2694 ID of a previously created secret object containing the password
2695 for decryption.
2696 The members of TlsCredsProperties
2698 Features
2700 deprecated
2701 Member loaded is deprecated. Setting true doesn't make sense,
2702 and false is already the default.
2703 Since
2705 2.5
2706
2708 Block core (VM unrelated)
2709 Background jobs
2710 JobType (Enum)
2711 Type of a background job.
2712 Values
2714 commit block commit job type, see "block-commit"
2715 stream block stream job type, see "block-stream"
2717 mirror drive mirror job type, see "drive-mirror"
2719 backup drive backup job type, see "drive-backup"
2721 create image creation job type, see "blockdev-create" (since 3.0)
2723 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
2725 snapshot-load
2727 snapshot load job type, see "snapshot-load" (since 6.0)
2728 snapshot-save
2730 snapshot save job type, see "snapshot-save" (since 6.0)
2731 snapshot-delete
2733 snapshot delete job type, see "snapshot-delete" (since 6.0)
2734 Since
2736 1.7
2737 JobStatus (Enum)
2739 Indicates the present state of a given job in its lifetime.
2740 Values
2742 undefined
2743 Erroneous, default state. Should not ever be visible.
2744 created
2746 The job has been created, but not yet started.
2747 running
2749 The job is currently running.
2750 paused The job is running, but paused. The pause may be requested by
2752 either the QMP user or by internal processes.
2753 ready The job is running, but is ready for the user to signal comple‐
2755 tion. This is used for long-running jobs like mirror that are
2756 designed to run indefinitely.
2757 standby
2759 The job is ready, but paused. This is nearly identical to
2760 paused. The job may return to ready or otherwise be canceled.
2761 waiting
2763 The job is waiting for other jobs in the transaction to converge
2764 to the waiting state. This status will likely not be visible for
2765 the last job in a transaction.
2766 pending
2768 The job has finished its work, but has finalization steps that
2769 it needs to make prior to completing. These changes will require
2770 manual intervention via job-finalize if auto-finalize was set to
2771 false. These pending changes may still fail.
2772 aborting
2774 The job is in the process of being aborted, and will finish with
2775 an error. The job will afterwards report that it is concluded.
2776 This status may not be visible to the management process.
2777 concluded
2779 The job has finished all work. If auto-dismiss was set to false,
2780 the job will remain in the query list until it is dismissed via
2781 job-dismiss.
2782 null The job is in the process of being dismantled. This state should
2784 not ever be visible externally.
2785 Since
2787 2.12
2788 JobVerb (Enum)
2790 Represents command verbs that can be applied to a job.
2791 Values
2793 cancel see job-cancel
2794 pause see job-pause
2796 resume see job-resume
2798 set-speed
2800 see block-job-set-speed
2801 complete
2803 see job-complete
2804 dismiss
2806 see job-dismiss
2807 finalize
2809 see job-finalize
2810 Since
2812 2.12
2813 JOB_STATUS_CHANGE (Event)
2815 Emitted when a job transitions to a different status.
2816 Arguments
2818 id: string
2819 The job identifier
2820 status: JobStatus
2822 The new job status
2823 Since
2825 3.0
2826 job-pause (Command)
2828 Pause an active job.
2829 This command returns immediately after marking the active job for paus‐
2831 ing. Pausing an already paused job is an error.
2832 The job will pause as soon as possible, which means transitioning into
2834 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
2835 The corresponding JOB_STATUS_CHANGE event will be emitted.
2836 Cancelling a paused job automatically resumes it.
2838 Arguments
2840 id: string
2841 The job identifier.
2842 Since
2844 3.0
2845 job-resume (Command)
2847 Resume a paused job.
2848 This command returns immediately after resuming a paused job. Resuming
2850 an already running job is an error.
2851 id : The job identifier.
2853 Arguments
2855 id: string
2856 Not documented
2857 Since
2859 3.0
2860 job-cancel (Command)
2862 Instruct an active background job to cancel at the next opportunity.
2863 This command returns immediately after marking the active job for can‐
2864 cellation.
2865 The job will cancel as soon as possible and then emit a JOB_STA‐
2867 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
2868 is possible that a job successfully completes (e.g. because it was al‐
2869 most done and there was no opportunity to cancel earlier than complet‐
2870 ing the job) and transitions to PENDING instead.
2871 Arguments
2873 id: string
2874 The job identifier.
2875 Since
2877 3.0
2878 job-complete (Command)
2880 Manually trigger completion of an active job in the READY state.
2881 Arguments
2883 id: string
2884 The job identifier.
2885 Since
2887 3.0
2888 job-dismiss (Command)
2890 Deletes a job that is in the CONCLUDED state. This command only needs
2891 to be run explicitly for jobs that don't have automatic dismiss en‐
2892 abled.
2893 This command will refuse to operate on any job that has not yet reached
2895 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
2896 JOB_READY event, job-cancel or job-complete will still need to be used
2897 as appropriate.
2898 Arguments
2900 id: string
2901 The job identifier.
2902 Since
2904 3.0
2905 job-finalize (Command)
2907 Instructs all jobs in a transaction (or a single job if it is not part
2908 of any transaction) to finalize any graph changes and do any necessary
2909 cleanup. This command requires that all involved jobs are in the PEND‐
2910 ING state.
2911 For jobs in a transaction, instructing one job to finalize will force
2913 ALL jobs in the transaction to finalize, so it is only necessary to in‐
2914 struct a single member job to finalize.
2915 Arguments
2917 id: string
2918 The identifier of any job in the transaction, or of a job that
2919 is not part of any transaction.
2920 Since
2922 3.0
2923 JobInfo (Object)
2925 Information about a job.
2926 Members
2928 id: string
2929 The job identifier
2930 type: JobType
2932 The kind of job that is being performed
2933 status: JobStatus
2935 Current job state/status
2936 current-progress: int
2938 Progress made until now. The unit is arbitrary and the value can
2939 only meaningfully be used for the ratio of current-progress to
2940 total-progress. The value is monotonically increasing.
2941 total-progress: int
2943 Estimated current-progress value at the completion of the job.
2944 This value can arbitrarily change while the job is running, in
2945 both directions.
2946 error: string (optional)
2948 If this field is present, the job failed; if it is still missing
2949 in the CONCLUDED state, this indicates successful completion.
2950 The value is a human-readable error message to describe the rea‐
2952 son for the job failure. It should not be parsed by applica‐
2953 tions.
2954 Since
2956 3.0
2957 query-jobs (Command)
2959 Return information about jobs.
2960 Returns
2962 a list with a JobInfo for each active job
2963 Since
2965 3.0
2966 SnapshotInfo (Object)
2968 Members
2969 id: string
2970 unique snapshot id
2971 name: string
2973 user chosen name
2974 vm-state-size: int
2976 size of the VM state
2977 date-sec: int
2979 UTC date of the snapshot in seconds
2980 date-nsec: int
2982 fractional part in nano seconds to be used with date-sec
2983 vm-clock-sec: int
2985 VM clock relative to boot in seconds
2986 vm-clock-nsec: int
2988 fractional part in nano seconds to be used with vm-clock-sec
2989 icount: int (optional)
2991 Current instruction count. Appears when execution record/replay
2992 is enabled. Used for "time-traveling" to match the moment in the
2993 recorded execution with the snapshots. This counter may be ob‐
2994 tained through query-replay command (since 5.2)
2995 Since
2997 1.3
2998 ImageInfoSpecificQCow2EncryptionBase (Object)
3000 Members
3001 format: BlockdevQcow2EncryptionFormat
3002 The encryption format
3003 Since
3005 2.10
3006 ImageInfoSpecificQCow2Encryption (Object)
3008 Members
3009 The members of ImageInfoSpecificQCow2EncryptionBase
3010 The members of QCryptoBlockInfoLUKS when format is "luks"
3012 Since
3014 2.10
3015 ImageInfoSpecificQCow2 (Object)
3017 Members
3018 compat: string
3019 compatibility level
3020 data-file: string (optional)
3022 the filename of the external data file that is stored in the im‐
3023 age and used as a default for opening the image (since: 4.0)
3024 data-file-raw: boolean (optional)
3026 True if the external data file must stay valid as a standalone
3027 (read-only) raw image without looking at qcow2 metadata (since:
3028 4.0)
3029 extended-l2: boolean (optional)
3031 true if the image has extended L2 entries; only valid for compat
3032 >= 1.1 (since 5.2)
3033 lazy-refcounts: boolean (optional)
3035 on or off; only valid for compat >= 1.1
3036 corrupt: boolean (optional)
3038 true if the image has been marked corrupt; only valid for compat
3039 >= 1.1 (since 2.2)
3040 refcount-bits: int
3042 width of a refcount entry in bits (since 2.3)
3043 encrypt: ImageInfoSpecificQCow2Encryption (optional)
3045 details about encryption parameters; only set if image is en‐
3046 crypted (since 2.10)
3047 bitmaps: array of Qcow2BitmapInfo (optional)
3049 A list of qcow2 bitmap details (since 4.0)
3050 compression-type: Qcow2CompressionType
3052 the image cluster compression method (since 5.1)
3053 Since
3055 1.7
3056 ImageInfoSpecificVmdk (Object)
3058 Members
3059 create-type: string
3060 The create type of VMDK image
3061 cid: int
3063 Content id of image
3064 parent-cid: int
3066 Parent VMDK image's cid
3067 extents: array of ImageInfo
3069 List of extent files
3070 Since
3072 1.7
3073 ImageInfoSpecificRbd (Object)
3075 Members
3076 encryption-format: RbdImageEncryptionFormat (optional)
3077 Image encryption format
3078 Since
3080 6.1
3081 ImageInfoSpecificKind (Enum)
3083 Values
3084 luks Since 2.7
3085 rbd Since 6.1
3087 qcow2 Not documented
3089 vmdk Not documented
3091 Since
3093 1.7
3094 ImageInfoSpecificQCow2Wrapper (Object)
3096 Members
3097 data: ImageInfoSpecificQCow2
3098 Not documented
3099 Since
3101 1.7
3102 ImageInfoSpecificVmdkWrapper (Object)
3104 Members
3105 data: ImageInfoSpecificVmdk
3106 Not documented
3107 Since
3109 6.1
3110 ImageInfoSpecificLUKSWrapper (Object)
3112 Members
3113 data: QCryptoBlockInfoLUKS
3114 Not documented
3115 Since
3117 2.7
3118 ImageInfoSpecificRbdWrapper (Object)
3120 Members
3121 data: ImageInfoSpecificRbd
3122 Not documented
3123 Since
3125 6.1
3126 ImageInfoSpecific (Object)
3128 A discriminated record of image format specific information structures.
3129 Members
3131 type: ImageInfoSpecificKind
3132 Not documented
3133 The members of ImageInfoSpecificQCow2Wrapper when type is "qcow2"
3135 The members of ImageInfoSpecificVmdkWrapper when type is "vmdk"
3137 The members of ImageInfoSpecificLUKSWrapper when type is "luks"
3139 The members of ImageInfoSpecificRbdWrapper when type is "rbd"
3141 Since
3143 1.7
3144 ImageInfo (Object)
3146 Information about a QEMU image file
3147 Members
3149 filename: string
3150 name of the image file
3151 format: string
3153 format of the image file
3154 virtual-size: int
3156 maximum capacity in bytes of the image
3157 actual-size: int (optional)
3159 actual size on disk in bytes of the image
3160 dirty-flag: boolean (optional)
3162 true if image is not cleanly closed
3163 cluster-size: int (optional)
3165 size of a cluster in bytes
3166 encrypted: boolean (optional)
3168 true if the image is encrypted
3169 compressed: boolean (optional)
3171 true if the image is compressed (Since 1.7)
3172 backing-filename: string (optional)
3174 name of the backing file
3175 full-backing-filename: string (optional)
3177 full path of the backing file
3178 backing-filename-format: string (optional)
3180 the format of the backing file
3181 snapshots: array of SnapshotInfo (optional)
3183 list of VM snapshots
3184 backing-image: ImageInfo (optional)
3186 info of the backing image (since 1.6)
3187 format-specific: ImageInfoSpecific (optional)
3189 structure supplying additional format-specific information
3190 (since 1.7)
3191 Since
3193 1.3
3194 ImageCheck (Object)
3196 Information about a QEMU image file check
3197 Members
3199 filename: string
3200 name of the image file checked
3201 format: string
3203 format of the image file checked
3204 check-errors: int
3206 number of unexpected errors occurred during check
3207 image-end-offset: int (optional)
3209 offset (in bytes) where the image ends, this field is present if
3210 the driver for the image format supports it
3211 corruptions: int (optional)
3213 number of corruptions found during the check if any
3214 leaks: int (optional)
3216 number of leaks found during the check if any
3217 corruptions-fixed: int (optional)
3219 number of corruptions fixed during the check if any
3220 leaks-fixed: int (optional)
3222 number of leaks fixed during the check if any
3223 total-clusters: int (optional)
3225 total number of clusters, this field is present if the driver
3226 for the image format supports it
3227 allocated-clusters: int (optional)
3229 total number of allocated clusters, this field is present if the
3230 driver for the image format supports it
3231 fragmented-clusters: int (optional)
3233 total number of fragmented clusters, this field is present if
3234 the driver for the image format supports it
3235 compressed-clusters: int (optional)
3237 total number of compressed clusters, this field is present if
3238 the driver for the image format supports it
3239 Since
3241 1.4
3242 MapEntry (Object)
3244 Mapping information from a virtual block range to a host file range
3245 Members
3247 start: int
3248 virtual (guest) offset of the first byte described by this entry
3249 length: int
3251 the number of bytes of the mapped virtual range
3252 data: boolean
3254 reading the image will actually read data from a file (in par‐
3255 ticular, if offset is present this means that the sectors are
3256 not simply preallocated, but contain actual data in raw format)
3257 zero: boolean
3259 whether the virtual blocks read as zeroes
3260 depth: int
3262 number of layers (0 = top image, 1 = top image's backing file,
3263 ..., n - 1 = bottom image (where n is the number of images in
3264 the chain)) before reaching one for which the range is allocated
3265 present: boolean
3267 true if this layer provides the data, false if adding a backing
3268 layer could impact this region (since 6.1)
3269 offset: int (optional)
3271 if present, the image file stores the data for this range in raw
3272 format at the given (host) offset
3273 filename: string (optional)
3275 filename that is referred to by offset
3276 Since
3278 2.6
3279 BlockdevCacheInfo (Object)
3281 Cache mode information for a block device
3282 Members
3284 writeback: boolean
3285 true if writeback mode is enabled
3286 direct: boolean
3288 true if the host page cache is bypassed (O_DIRECT)
3289 no-flush: boolean
3291 true if flush requests are ignored for the device
3292 Since
3294 2.3
3295 BlockDeviceInfo (Object)
3297 Information about the backing device for a block device.
3298 Members
3300 file: string
3301 the filename of the backing device
3302 node-name: string (optional)
3304 the name of the block driver node (Since 2.0)
3305 ro: boolean
3307 true if the backing device was open read-only
3308 drv: string
3310 the name of the block format used to open the backing device. As
3311 of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
3312 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
3313 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2',
3314 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added,
3315 'cow' dropped 2.3: 'host_floppy' deprecated 2.5: 'host_floppy'
3316 dropped 2.6: 'luks' added 2.8: 'replication' added, 'tftp'
3317 dropped 2.9: 'archipelago' dropped
3318 backing_file: string (optional)
3320 the name of the backing file (for copy-on-write)
3321 backing_file_depth: int
3323 number of files in the backing file chain (since: 1.2)
3324 encrypted: boolean
3326 true if the backing device is encrypted
3327 detect_zeroes: BlockdevDetectZeroesOptions
3329 detect and optimize zero writes (Since 2.1)
3330 bps: int
3332 total throughput limit in bytes per second is specified
3333 bps_rd: int
3335 read throughput limit in bytes per second is specified
3336 bps_wr: int
3338 write throughput limit in bytes per second is specified
3339 iops: int
3341 total I/O operations per second is specified
3342 iops_rd: int
3344 read I/O operations per second is specified
3345 iops_wr: int
3347 write I/O operations per second is specified
3348 image: ImageInfo
3350 the info of image used (since: 1.6)
3351 bps_max: int (optional)
3353 total throughput limit during bursts,
3355 in bytes (Since 1.7)
3356 bps_rd_max: int (optional)
3358 read throughput limit during bursts,
3360 in bytes (Since 1.7)
3361 bps_wr_max: int (optional)
3363 write throughput limit during bursts,
3365 in bytes (Since 1.7)
3366 iops_max: int (optional)
3368 total I/O operations per second during bursts,
3370 in bytes (Since 1.7)
3371 iops_rd_max: int (optional)
3373 read I/O operations per second during bursts,
3375 in bytes (Since 1.7)
3376 iops_wr_max: int (optional)
3378 write I/O operations per second during bursts,
3380 in bytes (Since 1.7)
3381 bps_max_length: int (optional)
3383 maximum length of the bps_max burst
3385 period, in seconds. (Since 2.6)
3386 bps_rd_max_length: int (optional)
3388 maximum length of the bps_rd_max
3390 burst period, in seconds. (Since 2.6)
3391 bps_wr_max_length: int (optional)
3393 maximum length of the bps_wr_max
3395 burst period, in seconds. (Since 2.6)
3396 iops_max_length: int (optional)
3398 maximum length of the iops burst
3400 period, in seconds. (Since 2.6)
3401 iops_rd_max_length: int (optional)
3403 maximum length of the iops_rd_max
3405 burst period, in seconds. (Since 2.6)
3406 iops_wr_max_length: int (optional)
3408 maximum length of the iops_wr_max
3410 burst period, in seconds. (Since 2.6)
3411 iops_size: int (optional)
3413 an I/O size in bytes (Since 1.7)
3414 group: string (optional)
3416 throttle group name (Since 2.4)
3417 cache: BlockdevCacheInfo
3419 the cache mode used for the block device (since: 2.3)
3420 write_threshold: int
3422 configured write threshold for the device. 0 if disabled.
3423 (Since 2.3)
3424 dirty-bitmaps: array of BlockDirtyInfo (optional)
3426 dirty bitmaps information (only present if node has one or more
3427 dirty bitmaps) (Since 4.2)
3428 Since
3430 0.14
3431 BlockDeviceIoStatus (Enum)
3433 An enumeration of block device I/O status.
3434 Values
3436 ok The last I/O operation has succeeded
3437 failed The last I/O operation has failed
3439 nospace
3441 The last I/O operation has failed due to a no-space condition
3442 Since
3444 1.0
3445 BlockDirtyInfo (Object)
3447 Block dirty bitmap information.
3448 Members
3450 name: string (optional)
3451 the name of the dirty bitmap (Since 2.4)
3452 count: int
3454 number of dirty bytes according to the dirty bitmap
3455 granularity: int
3457 granularity of the dirty bitmap in bytes (since 1.4)
3458 recording: boolean
3460 true if the bitmap is recording new writes from the guest. Re‐
3461 places active and disabled statuses. (since 4.0)
3462 busy: boolean
3464 true if the bitmap is in-use by some operation (NBD or jobs) and
3465 cannot be modified via QMP or used by another operation. Re‐
3466 places locked and frozen statuses. (since 4.0)
3467 persistent: boolean
3469 true if the bitmap was stored on disk, is scheduled to be stored
3470 on disk, or both. (since 4.0)
3471 inconsistent: boolean (optional)
3473 true if this is a persistent bitmap that was improperly stored.
3474 Implies persistent to be true; recording and busy to be false.
3475 This bitmap cannot be used. To remove it, use block-dirty-bit‐
3476 map-remove. (Since 4.0)
3477 Since
3479 1.3
3480 Qcow2BitmapInfoFlags (Enum)
3482 An enumeration of flags that a bitmap can report to the user.
3483 Values
3485 in-use This flag is set by any process actively modifying the qcow2
3486 file, and cleared when the updated bitmap is flushed to the
3487 qcow2 image. The presence of this flag in an offline image
3488 means that the bitmap was not saved correctly after its last us‐
3489 age, and may contain inconsistent data.
3490 auto The bitmap must reflect all changes of the virtual disk by any
3492 application that would write to this qcow2 file.
3493 Since
3495 4.0
3496 Qcow2BitmapInfo (Object)
3498 Qcow2 bitmap information.
3499 Members
3501 name: string
3502 the name of the bitmap
3503 granularity: int
3505 granularity of the bitmap in bytes
3506 flags: array of Qcow2BitmapInfoFlags
3508 flags of the bitmap
3509 Since
3511 4.0
3512 BlockLatencyHistogramInfo (Object)
3514 Block latency histogram.
3515 Members
3517 boundaries: array of int
3518 list of interval boundary values in nanoseconds, all greater
3519 than zero and in ascending order. For example, the list [10,
3520 50, 100] produces the following histogram intervals: [0, 10),
3521 [10, 50), [50, 100), [100, +inf).
3522 bins: array of int
3524 list of io request counts corresponding to histogram intervals.
3525 len(bins) = len(boundaries) + 1 For the example above, bins may
3526 be something like [3, 1, 5, 2], and corresponding histogram
3527 looks like:
3528 5| *
3530 4| *
3531 3| * *
3532 2| * * *
3533 1| * * * *
3534 +------------------
3535 10 50 100
3536 Since
3538 4.0
3539 BlockInfo (Object)
3541 Block device information. This structure describes a virtual device
3542 and the backing device associated with it.
3543 Members
3545 device: string
3546 The device name associated with the virtual device.
3547 qdev: string (optional)
3549 The qdev ID, or if no ID is assigned, the QOM path of the block
3550 device. (since 2.10)
3551 type: string
3553 This field is returned only for compatibility reasons, it should
3554 not be used (always returns 'unknown')
3555 removable: boolean
3557 True if the device supports removable media.
3558 locked: boolean
3560 True if the guest has locked this device from having its media
3561 removed
3562 tray_open: boolean (optional)
3564 True if the device's tray is open (only present if it has a
3565 tray)
3566 io-status: BlockDeviceIoStatus (optional)
3568 BlockDeviceIoStatus. Only present if the device supports it and
3569 the VM is configured to stop on errors (supported device models:
3570 virtio-blk, IDE, SCSI except scsi-generic)
3571 inserted: BlockDeviceInfo (optional)
3573 BlockDeviceInfo describing the device if media is present
3574 Since
3576 0.14
3577 BlockMeasureInfo (Object)
3579 Image file size calculation information. This structure describes the
3580 size requirements for creating a new image file.
3581 The size requirements depend on the new image file format. File size
3583 always equals virtual disk size for the 'raw' format, even for sparse
3584 POSIX files. Compact formats such as 'qcow2' represent unallocated and
3585 zero regions efficiently so file size may be smaller than virtual disk
3586 size.
3587 The values are upper bounds that are guaranteed to fit the new image
3589 file. Subsequent modification, such as internal snapshot or further
3590 bitmap creation, may require additional space and is not covered here.
3591 Members
3593 required: int
3594 Size required for a new image file, in bytes, when copying just
3595 allocated guest-visible contents.
3596 fully-allocated: int
3598 Image file size, in bytes, once data has been written to all
3599 sectors, when copying just guest-visible contents.
3600 bitmaps: int (optional)
3602 Additional size required if all the top-level bitmap metadata in
3603 the source image were to be copied to the destination, present
3604 only when source and destination both support persistent bit‐
3605 maps. (since 5.1)
3606 Since
3608 2.10
3609 query-block (Command)
3611 Get a list of BlockInfo for all virtual block devices.
3612 Returns
3614 a list of BlockInfo describing each virtual block device. Filter nodes
3615 that were created implicitly are skipped over.
3616 Since
3618 0.14
3619 Example
3621 -> { "execute": "query-block" }
3622 <- {
3623 "return":[
3624 {
3625 "io-status": "ok",
3626 "device":"ide0-hd0",
3627 "locked":false,
3628 "removable":false,
3629 "inserted":{
3630 "ro":false,
3631 "drv":"qcow2",
3632 "encrypted":false,
3633 "file":"disks/test.qcow2",
3634 "backing_file_depth":1,
3635 "bps":1000000,
3636 "bps_rd":0,
3637 "bps_wr":0,
3638 "iops":1000000,
3639 "iops_rd":0,
3640 "iops_wr":0,
3641 "bps_max": 8000000,
3642 "bps_rd_max": 0,
3643 "bps_wr_max": 0,
3644 "iops_max": 0,
3645 "iops_rd_max": 0,
3646 "iops_wr_max": 0,
3647 "iops_size": 0,
3648 "detect_zeroes": "on",
3649 "write_threshold": 0,
3650 "image":{
3651 "filename":"disks/test.qcow2",
3652 "format":"qcow2",
3653 "virtual-size":2048000,
3654 "backing_file":"base.qcow2",
3655 "full-backing-filename":"disks/base.qcow2",
3656 "backing-filename-format":"qcow2",
3657 "snapshots":[
3658 {
3659 "id": "1",
3660 "name": "snapshot1",
3661 "vm-state-size": 0,
3662 "date-sec": 10000200,
3663 "date-nsec": 12,
3664 "vm-clock-sec": 206,
3665 "vm-clock-nsec": 30
3666 }
3667 ],
3668 "backing-image":{
3669 "filename":"disks/base.qcow2",
3670 "format":"qcow2",
3671 "virtual-size":2048000
3672 }
3673 }
3674 },
3675 "qdev": "ide_disk",
3676 "type":"unknown"
3677 },
3678 {
3679 "io-status": "ok",
3680 "device":"ide1-cd0",
3681 "locked":false,
3682 "removable":true,
3683 "qdev": "/machine/unattached/device[23]",
3684 "tray_open": false,
3685 "type":"unknown"
3686 },
3687 {
3688 "device":"floppy0",
3689 "locked":false,
3690 "removable":true,
3691 "qdev": "/machine/unattached/device[20]",
3692 "type":"unknown"
3693 },
3694 {
3695 "device":"sd0",
3696 "locked":false,
3697 "removable":true,
3698 "type":"unknown"
3699 }
3700 ]
3701 }
3702 BlockDeviceTimedStats (Object)
3704 Statistics of a block device during a given interval of time.
3705 Members
3707 interval_length: int
3708 Interval used for calculating the statistics, in seconds.
3709 min_rd_latency_ns: int
3711 Minimum latency of read operations in the defined interval, in
3712 nanoseconds.
3713 min_wr_latency_ns: int
3715 Minimum latency of write operations in the defined interval, in
3716 nanoseconds.
3717 min_flush_latency_ns: int
3719 Minimum latency of flush operations in the defined interval, in
3720 nanoseconds.
3721 max_rd_latency_ns: int
3723 Maximum latency of read operations in the defined interval, in
3724 nanoseconds.
3725 max_wr_latency_ns: int
3727 Maximum latency of write operations in the defined interval, in
3728 nanoseconds.
3729 max_flush_latency_ns: int
3731 Maximum latency of flush operations in the defined interval, in
3732 nanoseconds.
3733 avg_rd_latency_ns: int
3735 Average latency of read operations in the defined interval, in
3736 nanoseconds.
3737 avg_wr_latency_ns: int
3739 Average latency of write operations in the defined interval, in
3740 nanoseconds.
3741 avg_flush_latency_ns: int
3743 Average latency of flush operations in the defined interval, in
3744 nanoseconds.
3745 avg_rd_queue_depth: number
3747 Average number of pending read operations in the defined inter‐
3748 val.
3749 avg_wr_queue_depth: number
3751 Average number of pending write operations in the defined inter‐
3752 val.
3753 Since
3755 2.5
3756 BlockDeviceStats (Object)
3758 Statistics of a virtual block device or a block backing device.
3759 Members
3761 rd_bytes: int
3762 The number of bytes read by the device.
3763 wr_bytes: int
3765 The number of bytes written by the device.
3766 unmap_bytes: int
3768 The number of bytes unmapped by the device (Since 4.2)
3769 rd_operations: int
3771 The number of read operations performed by the device.
3772 wr_operations: int
3774 The number of write operations performed by the device.
3775 flush_operations: int
3777 The number of cache flush operations performed by the device
3778 (since 0.15)
3779 unmap_operations: int
3781 The number of unmap operations performed by the device (Since
3782 4.2)
3783 rd_total_time_ns: int
3785 Total time spent on reads in nanoseconds (since 0.15).
3786 wr_total_time_ns: int
3788 Total time spent on writes in nanoseconds (since 0.15).
3789 flush_total_time_ns: int
3791 Total time spent on cache flushes in nanoseconds (since 0.15).
3792 unmap_total_time_ns: int
3794 Total time spent on unmap operations in nanoseconds (Since 4.2)
3795 wr_highest_offset: int
3797 The offset after the greatest byte written to the device. The
3798 intended use of this information is for growable sparse files
3799 (like qcow2) that are used on top of a physical device.
3800 rd_merged: int
3802 Number of read requests that have been merged into another re‐
3803 quest (Since 2.3).
3804 wr_merged: int
3806 Number of write requests that have been merged into another re‐
3807 quest (Since 2.3).
3808 unmap_merged: int
3810 Number of unmap requests that have been merged into another re‐
3811 quest (Since 4.2)
3812 idle_time_ns: int (optional)
3814 Time since the last I/O operation, in nanoseconds. If the field
3815 is absent it means that there haven't been any operations yet
3816 (Since 2.5).
3817 failed_rd_operations: int
3819 The number of failed read operations performed by the device
3820 (Since 2.5)
3821 failed_wr_operations: int
3823 The number of failed write operations performed by the device
3824 (Since 2.5)
3825 failed_flush_operations: int
3827 The number of failed flush operations performed by the device
3828 (Since 2.5)
3829 failed_unmap_operations: int
3831 The number of failed unmap operations performed by the device
3832 (Since 4.2)
3833 invalid_rd_operations: int
3835 The number of invalid read operations
3837 performed by the device (Since 2.5)
3838 invalid_wr_operations: int
3840 The number of invalid write operations performed by the device
3841 (Since 2.5)
3842 invalid_flush_operations: int
3844 The number of invalid flush operations performed by the device
3845 (Since 2.5)
3846 invalid_unmap_operations: int
3848 The number of invalid unmap operations performed by the device
3849 (Since 4.2)
3850 account_invalid: boolean
3852 Whether invalid operations are included in the last access sta‐
3853 tistics (Since 2.5)
3854 account_failed: boolean
3856 Whether failed operations are included in the latency and last
3857 access statistics (Since 2.5)
3858 timed_stats: array of BlockDeviceTimedStats
3860 Statistics specific to the set of previously defined intervals
3861 of time (Since 2.5)
3862 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
3864 BlockLatencyHistogramInfo. (Since 4.0)
3865 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
3867 BlockLatencyHistogramInfo. (Since 4.0)
3868 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
3870 BlockLatencyHistogramInfo. (Since 4.0)
3871 Since
3873 0.14
3874 BlockStatsSpecificFile (Object)
3876 File driver statistics
3877 Members
3879 discard-nb-ok: int
3880 The number of successful discard operations performed by the
3881 driver.
3882 discard-nb-failed: int
3884 The number of failed discard operations performed by the driver.
3885 discard-bytes-ok: int
3887 The number of bytes discarded by the driver.
3888 Since
3890 4.2
3891 BlockStatsSpecificNvme (Object)
3893 NVMe driver statistics
3894 Members
3896 completion-errors: int
3897 The number of completion errors.
3898 aligned-accesses: int
3900 The number of aligned accesses performed by the driver.
3901 unaligned-accesses: int
3903 The number of unaligned accesses performed by the driver.
3904 Since
3906 5.2
3907 BlockStatsSpecific (Object)
3909 Block driver specific statistics
3910 Members
3912 driver: BlockdevDriver
3913 Not documented
3914 The members of BlockStatsSpecificFile when driver is "file"
3916 The members of BlockStatsSpecificFile when driver is "host_device" (If:
3918 HAVE_HOST_BLOCK_DEVICE)
3919 The members of BlockStatsSpecificNvme when driver is "nvme"
3921 Since
3923 4.2
3924 BlockStats (Object)
3926 Statistics of a virtual block device or a block backing device.
3927 Members
3929 device: string (optional)
3930 If the stats are for a virtual block device, the name corre‐
3931 sponding to the virtual block device.
3932 node-name: string (optional)
3934 The node name of the device. (Since 2.3)
3935 qdev: string (optional)
3937 The qdev ID, or if no ID is assigned, the QOM path of the block
3938 device. (since 3.0)
3939 stats: BlockDeviceStats
3941 A BlockDeviceStats for the device.
3942 driver-specific: BlockStatsSpecific (optional)
3944 Optional driver-specific stats. (Since 4.2)
3945 parent: BlockStats (optional)
3947 This describes the file block device if it has one. Contains
3948 recursively the statistics of the underlying protocol (e.g. the
3949 host file for a qcow2 image). If there is no underlying proto‐
3950 col, this field is omitted
3951 backing: BlockStats (optional)
3953 This describes the backing block device if it has one. (Since
3954 2.0)
3955 Since
3957 0.14
3958 query-blockstats (Command)
3960 Query the BlockStats for all virtual block devices.
3961 Arguments
3963 query-nodes: boolean (optional)
3964 If true, the command will query all the block nodes that have a
3965 node name, in a list which will include "parent" information,
3966 but not "backing". If false or omitted, the behavior is as be‐
3967 fore - query all the device backends, recursively including
3968 their "parent" and "backing". Filter nodes that were created im‐
3969 plicitly are skipped over in this mode. (Since 2.3)
3970 Returns
3972 A list of BlockStats for each virtual block devices.
3973 Since
3975 0.14
3976 Example
3978 -> { "execute": "query-blockstats" }
3979 <- {
3980 "return":[
3981 {
3982 "device":"ide0-hd0",
3983 "parent":{
3984 "stats":{
3985 "wr_highest_offset":3686448128,
3986 "wr_bytes":9786368,
3987 "wr_operations":751,
3988 "rd_bytes":122567168,
3989 "rd_operations":36772
3990 "wr_total_times_ns":313253456
3991 "rd_total_times_ns":3465673657
3992 "flush_total_times_ns":49653
3993 "flush_operations":61,
3994 "rd_merged":0,
3995 "wr_merged":0,
3996 "idle_time_ns":2953431879,
3997 "account_invalid":true,
3998 "account_failed":false
3999 }
4000 },
4001 "stats":{
4002 "wr_highest_offset":2821110784,
4003 "wr_bytes":9786368,
4004 "wr_operations":692,
4005 "rd_bytes":122739200,
4006 "rd_operations":36604
4007 "flush_operations":51,
4008 "wr_total_times_ns":313253456
4009 "rd_total_times_ns":3465673657
4010 "flush_total_times_ns":49653,
4011 "rd_merged":0,
4012 "wr_merged":0,
4013 "idle_time_ns":2953431879,
4014 "account_invalid":true,
4015 "account_failed":false
4016 },
4017 "qdev": "/machine/unattached/device[23]"
4018 },
4019 {
4020 "device":"ide1-cd0",
4021 "stats":{
4022 "wr_highest_offset":0,
4023 "wr_bytes":0,
4024 "wr_operations":0,
4025 "rd_bytes":0,
4026 "rd_operations":0
4027 "flush_operations":0,
4028 "wr_total_times_ns":0
4029 "rd_total_times_ns":0
4030 "flush_total_times_ns":0,
4031 "rd_merged":0,
4032 "wr_merged":0,
4033 "account_invalid":false,
4034 "account_failed":false
4035 },
4036 "qdev": "/machine/unattached/device[24]"
4037 },
4038 {
4039 "device":"floppy0",
4040 "stats":{
4041 "wr_highest_offset":0,
4042 "wr_bytes":0,
4043 "wr_operations":0,
4044 "rd_bytes":0,
4045 "rd_operations":0
4046 "flush_operations":0,
4047 "wr_total_times_ns":0
4048 "rd_total_times_ns":0
4049 "flush_total_times_ns":0,
4050 "rd_merged":0,
4051 "wr_merged":0,
4052 "account_invalid":false,
4053 "account_failed":false
4054 },
4055 "qdev": "/machine/unattached/device[16]"
4056 },
4057 {
4058 "device":"sd0",
4059 "stats":{
4060 "wr_highest_offset":0,
4061 "wr_bytes":0,
4062 "wr_operations":0,
4063 "rd_bytes":0,
4064 "rd_operations":0
4065 "flush_operations":0,
4066 "wr_total_times_ns":0
4067 "rd_total_times_ns":0
4068 "flush_total_times_ns":0,
4069 "rd_merged":0,
4070 "wr_merged":0,
4071 "account_invalid":false,
4072 "account_failed":false
4073 }
4074 }
4075 ]
4076 }
4077 BlockdevOnError (Enum)
4079 An enumeration of possible behaviors for errors on I/O operations. The
4080 exact meaning depends on whether the I/O was initiated by a guest or by
4081 a block job
4082 Values
4084 report for guest operations, report the error to the guest; for jobs,
4085 cancel the job
4086 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
4088 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
4089 the failing request later and may still complete successfully.
4090 The stream block job continues to stream and will complete with
4091 an error.
4092 enospc same as stop on ENOSPC, same as report otherwise.
4094 stop for guest operations, stop the virtual machine; for jobs, pause
4096 the job
4097 auto inherit the error handling policy of the backend (since: 2.7)
4099 Since
4101 1.3
4102 MirrorSyncMode (Enum)
4104 An enumeration of possible behaviors for the initial synchronization
4105 phase of storage mirroring.
4106 Values
4108 top copies data in the topmost image to the destination
4109 full copies data from all images to the destination
4111 none only copy data written from now on
4113 incremental
4115 only copy data described by the dirty bitmap. (since: 2.4)
4116 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
4118 havior on completion is determined by the BitmapSyncMode.
4119 Since
4121 1.3
4122 BitmapSyncMode (Enum)
4124 An enumeration of possible behaviors for the synchronization of a bit‐
4125 map when used for data copy operations.
4126 Values
4128 on-success
4129 The bitmap is only synced when the operation is successful.
4130 This is the behavior always used for 'INCREMENTAL' backups.
4131 never The bitmap is never synchronized with the operation, and is
4133 treated solely as a read-only manifest of blocks to copy.
4134 always The bitmap is always synchronized with the operation, regardless
4136 of whether or not the operation was successful.
4137 Since
4139 4.2
4140 MirrorCopyMode (Enum)
4142 An enumeration whose values tell the mirror block job when to trigger
4143 writes to the target.
4144 Values
4146 background
4147 copy data in background only.
4148 write-blocking
4150 when data is written to the source, write it (synchronously) to
4151 the target as well. In addition, data is copied in background
4152 just like in background mode.
4153 Since
4155 3.0
4156 BlockJobInfo (Object)
4158 Information about a long-running block device operation.
4159 Members
4161 type: string
4162 the job type ('stream' for image streaming)
4163 device: string
4165 The job identifier. Originally the device name but other values
4166 are allowed since QEMU 2.7
4167 len: int
4169 Estimated offset value at the completion of the job. This value
4170 can arbitrarily change while the job is running, in both direc‐
4171 tions.
4172 offset: int
4174 Progress made until now. The unit is arbitrary and the value can
4175 only meaningfully be used for the ratio of offset to len. The
4176 value is monotonically increasing.
4177 busy: boolean
4179 false if the job is known to be in a quiescent state, with no
4180 pending I/O. Since 1.3.
4181 paused: boolean
4183 whether the job is paused or, if busy is true, will pause itself
4184 as soon as possible. Since 1.3.
4185 speed: int
4187 the rate limit, bytes per second
4188 io-status: BlockDeviceIoStatus
4190 the status of the job (since 1.3)
4191 ready: boolean
4193 true if the job may be completed (since 2.2)
4194 status: JobStatus
4196 Current job state/status (since 2.12)
4197 auto-finalize: boolean
4199 Job will finalize itself when PENDING, moving to the CONCLUDED
4200 state. (since 2.12)
4201 auto-dismiss: boolean
4203 Job will dismiss itself when CONCLUDED, moving to the NULL state
4204 and disappearing from the query list. (since 2.12)
4205 error: string (optional)
4207 Error information if the job did not complete successfully. Not
4208 set if the job completed successfully. (since 2.12.1)
4209 Since
4211 1.1
4212 query-block-jobs (Command)
4214 Return information about long-running block device operations.
4215 Returns
4217 a list of BlockJobInfo for each active block job
4218 Since
4220 1.1
4221 block_resize (Command)
4223 Resize a block image while a guest is running.
4224 Either device or node-name must be set but not both.
4226 Arguments
4228 device: string (optional)
4229 the name of the device to get the image resized
4230 node-name: string (optional)
4232 graph node name to get the image resized (Since 2.0)
4233 size: int
4235 new image size in bytes
4236 Returns
4238 • nothing on success
4239 • If device is not a valid block device, DeviceNotFound
4241 Since
4243 0.14
4244 Example
4246 -> { "execute": "block_resize",
4247 "arguments": { "device": "scratch", "size": 1073741824 } }
4248 <- { "return": {} }
4249 NewImageMode (Enum)
4251 An enumeration that tells QEMU how to set the backing file path in a
4252 new image file.
4253 Values
4255 existing
4256 QEMU should look for an existing image file.
4257 absolute-paths
4259 QEMU should create a new image with absolute paths for the back‐
4260 ing file. If there is no backing file available, the new image
4261 will not be backed either.
4262 Since
4264 1.1
4265 BlockdevSnapshotSync (Object)
4267 Either device or node-name must be set but not both.
4268 Members
4270 device: string (optional)
4271 the name of the device to take a snapshot of.
4272 node-name: string (optional)
4274 graph node name to generate the snapshot from (Since 2.0)
4275 snapshot-file: string
4277 the target of the new overlay image. If the file exists, or if
4278 it is a device, the overlay will be created in the existing
4279 file/device. Otherwise, a new file will be created.
4280 snapshot-node-name: string (optional)
4282 the graph node name of the new image (Since 2.0)
4283 format: string (optional)
4285 the format of the overlay image, default is 'qcow2'.
4286 mode: NewImageMode (optional)
4288 whether and how QEMU should create a new image, default is 'ab‐
4289 solute-paths'.
4290 BlockdevSnapshot (Object)
4292 Members
4293 node: string
4294 device or node name that will have a snapshot taken.
4295 overlay: string
4297 reference to the existing block device that will become the
4298 overlay of node, as part of taking the snapshot. It must not
4299 have a current backing file (this can be achieved by passing
4300 "backing": null to blockdev-add).
4301 Since
4303 2.5
4304 BackupPerf (Object)
4306 Optional parameters for backup. These parameters don't affect function‐
4307 ality, but may significantly affect performance.
4308 Members
4310 use-copy-range: boolean (optional)
4311 Use copy offloading. Default false.
4312 max-workers: int (optional)
4314 Maximum number of parallel requests for the sustained background
4315 copying process. Doesn't influence copy-before-write operations.
4316 Default 64.
4317 max-chunk: int (optional)
4319 Maximum request length for the sustained background copying
4320 process. Doesn't influence copy-before-write operations. 0
4321 means unlimited. If max-chunk is non-zero then it should not be
4322 less than job cluster size which is calculated as maximum of
4323 target image cluster size and 64k. Default 0.
4324 Since
4326 6.0
4327 BackupCommon (Object)
4329 Members
4330 job-id: string (optional)
4331 identifier for the newly-created block job. If omitted, the de‐
4332 vice name will be used. (Since 2.7)
4333 device: string
4335 the device name or node-name of a root node which should be
4336 copied.
4337 sync: MirrorSyncMode
4339 what parts of the disk image should be copied to the destination
4340 (all the disk, only the sectors allocated in the topmost image,
4341 from a dirty bitmap, or only new I/O).
4342 speed: int (optional)
4344 the maximum speed, in bytes per second. The default is 0, for
4345 unlimited.
4346 bitmap: string (optional)
4348 The name of a dirty bitmap to use. Must be present if sync is
4349 "bitmap" or "incremental". Can be present if sync is "full" or
4350 "top". Must not be present otherwise. (Since 2.4
4351 (drive-backup), 3.1 (blockdev-backup))
4352 bitmap-mode: BitmapSyncMode (optional)
4354 Specifies the type of data the bitmap should contain after the
4355 operation concludes. Must be present if a bitmap was provided,
4356 Must NOT be present otherwise. (Since 4.2)
4357 compress: boolean (optional)
4359 true to compress data, if the target format supports it. (de‐
4360 fault: false) (since 2.8)
4361 on-source-error: BlockdevOnError (optional)
4363 the action to take on an error on the source, default 'report'.
4364 'stop' and 'enospc' can only be used if the block device sup‐
4365 ports io-status (see BlockInfo).
4366 on-target-error: BlockdevOnError (optional)
4368 the action to take on an error on the target, default 'report'
4369 (no limitations, since this applies to a different block device
4370 than device).
4371 auto-finalize: boolean (optional)
4373 When false, this job will wait in a PENDING state after it has
4374 finished its work, waiting for block-job-finalize before making
4375 any block graph changes. When true, this job will automatically
4376 perform its abort or commit actions. Defaults to true. (Since
4377 2.12)
4378 auto-dismiss: boolean (optional)
4380 When false, this job will wait in a CONCLUDED state after it has
4381 completely ceased all work, and awaits block-job-dismiss. When
4382 true, this job will automatically disappear from the query list
4383 without user intervention. Defaults to true. (Since 2.12)
4384 filter-node-name: string (optional)
4386 the node name that should be assigned to the filter driver that
4387 the backup job inserts into the graph above node specified by
4388 drive. If this option is not given, a node name is autogener‐
4389 ated. (Since: 4.2)
4390 x-perf: BackupPerf (optional)
4392 Performance options. (Since 6.0)
4393 Features
4395 unstable
4396 Member x-perf is experimental.
4397 Note
4399 on-source-error and on-target-error only affect background I/O. If an
4400 error occurs during a guest write request, the device's rerror/werror
4401 actions will be used.
4402 Since
4404 4.2
4405 DriveBackup (Object)
4407 Members
4408 target: string
4409 the target of the new image. If the file exists, or if it is a
4410 device, the existing file/device will be used as the new desti‐
4411 nation. If it does not exist, a new file will be created.
4412 format: string (optional)
4414 the format of the new destination, default is to probe if mode
4415 is 'existing', else the format of the source
4416 mode: NewImageMode (optional)
4418 whether and how QEMU should create a new image, default is 'ab‐
4419 solute-paths'.
4420 The members of BackupCommon
4422 Since
4424 1.6
4425 BlockdevBackup (Object)
4427 Members
4428 target: string
4429 the device name or node-name of the backup target node.
4430 The members of BackupCommon
4432 Since
4434 2.3
4435 blockdev-snapshot-sync (Command)
4437 Takes a synchronous snapshot of a block device.
4438 For the arguments, see the documentation of BlockdevSnapshotSync.
4440 Returns
4442 • nothing on success
4443 • If device is not a valid block device, DeviceNotFound
4445 Since
4447 0.14
4448 Example
4450 -> { "execute": "blockdev-snapshot-sync",
4451 "arguments": { "device": "ide-hd0",
4452 "snapshot-file":
4453 "/some/place/my-image",
4454 "format": "qcow2" } }
4455 <- { "return": {} }
4456 blockdev-snapshot (Command)
4458 Takes a snapshot of a block device.
4459 Take a snapshot, by installing 'node' as the backing image of 'over‐
4461 lay'. Additionally, if 'node' is associated with a block device, the
4462 block device changes to using 'overlay' as its new active image.
4463 For the arguments, see the documentation of BlockdevSnapshot.
4465 Features
4467 allow-write-only-overlay
4468 If present, the check whether this operation is safe was relaxed
4469 so that it can be used to change backing file of a destination
4470 of a blockdev-mirror. (since 5.0)
4471 Since
4473 2.5
4474 Example
4476 -> { "execute": "blockdev-add",
4477 "arguments": { "driver": "qcow2",
4478 "node-name": "node1534",
4479 "file": { "driver": "file",
4480 "filename": "hd1.qcow2" },
4481 "backing": null } }
4482 <- { "return": {} }
4484 -> { "execute": "blockdev-snapshot",
4486 "arguments": { "node": "ide-hd0",
4487 "overlay": "node1534" } }
4488 <- { "return": {} }
4489 change-backing-file (Command)
4491 Change the backing file in the image file metadata. This does not
4492 cause QEMU to reopen the image file to reparse the backing filename (it
4493 may, however, perform a reopen to change permissions from r/o -> r/w ->
4494 r/o, if needed). The new backing file string is written into the image
4495 file metadata, and the QEMU internal strings are updated.
4496 Arguments
4498 image-node-name: string
4499 The name of the block driver state node of the image to modify.
4500 The "device" argument is used to verify "image-node-name" is in
4501 the chain described by "device".
4502 device: string
4504 The device name or node-name of the root node that owns im‐
4505 age-node-name.
4506 backing-file: string
4508 The string to write as the backing file. This string is not
4509 validated, so care should be taken when specifying the string or
4510 the image chain may not be able to be reopened again.
4511 Returns
4513 • Nothing on success
4514 • If "device" does not exist or cannot be determined, DeviceNotFound
4516 Since
4518 2.1
4519 block-commit (Command)
4521 Live commit of data from overlay image nodes into backing nodes - i.e.,
4522 writes data between 'top' and 'base' into 'base'.
4523 If top == base, that is an error. If top has no overlays on top of it,
4525 or if it is in use by a writer, the job will not be completed by it‐
4526 self. The user needs to complete the job with the block-job-complete
4527 command after getting the ready event. (Since 2.0)
4528 If the base image is smaller than top, then the base image will be re‐
4530 sized to be the same size as top. If top is smaller than the base im‐
4531 age, the base will not be truncated. If you want the base image size
4532 to match the size of the smaller top, you can safely truncate it your‐
4533 self once the commit operation successfully completes.
4534 Arguments
4536 job-id: string (optional)
4537 identifier for the newly-created block job. If omitted, the de‐
4538 vice name will be used. (Since 2.7)
4539 device: string
4541 the device name or node-name of a root node
4542 base-node: string (optional)
4544 The node name of the backing image to write data into. If not
4545 specified, this is the deepest backing image. (since: 3.1)
4546 base: string (optional)
4548 Same as base-node, except that it is a file name rather than a
4549 node name. This must be the exact filename string that was used
4550 to open the node; other strings, even if addressing the same
4551 file, are not accepted
4552 top-node: string (optional)
4554 The node name of the backing image within the image chain which
4555 contains the topmost data to be committed down. If not speci‐
4556 fied, this is the active layer. (since: 3.1)
4557 top: string (optional)
4559 Same as top-node, except that it is a file name rather than a
4560 node name. This must be the exact filename string that was used
4561 to open the node; other strings, even if addressing the same
4562 file, are not accepted
4563 backing-file: string (optional)
4565 The backing file string to write into the overlay image of
4566 'top'. If 'top' does not have an overlay image, or if 'top' is
4567 in use by a writer, specifying a backing file string is an er‐
4568 ror.
4569 This filename is not validated. If a pathname string is such
4571 that it cannot be resolved by QEMU, that means that subsequent
4572 QMP or HMP commands must use node-names for the image in ques‐
4573 tion, as filename lookup methods will fail.
4574 If not specified, QEMU will automatically determine the backing
4576 file string to use, or error out if there is no obvious choice.
4577 Care should be taken when specifying the string, to specify a
4578 valid filename or protocol. (Since 2.1)
4579 speed: int (optional)
4581 the maximum speed, in bytes per second
4582 on-error: BlockdevOnError (optional)
4584 the action to take on an error. 'ignore' means that the request
4585 should be retried. (default: report; Since: 5.0)
4586 filter-node-name: string (optional)
4588 the node name that should be assigned to the filter driver that
4589 the commit job inserts into the graph above top. If this option
4590 is not given, a node name is autogenerated. (Since: 2.9)
4591 auto-finalize: boolean (optional)
4593 When false, this job will wait in a PENDING state after it has
4594 finished its work, waiting for block-job-finalize before making
4595 any block graph changes. When true, this job will automatically
4596 perform its abort or commit actions. Defaults to true. (Since
4597 3.1)
4598 auto-dismiss: boolean (optional)
4600 When false, this job will wait in a CONCLUDED state after it has
4601 completely ceased all work, and awaits block-job-dismiss. When
4602 true, this job will automatically disappear from the query list
4603 without user intervention. Defaults to true. (Since 3.1)
4604 Features
4606 deprecated
4607 Members base and top are deprecated. Use base-node and top-node
4608 instead.
4609 Returns
4611 • Nothing on success
4612 • If device does not exist, DeviceNotFound
4614 • Any other error returns a GenericError.
4616 Since
4618 1.3
4619 Example
4621 -> { "execute": "block-commit",
4622 "arguments": { "device": "virtio0",
4623 "top": "/tmp/snap1.qcow2" } }
4624 <- { "return": {} }
4625 drive-backup (Command)
4627 Start a point-in-time copy of a block device to a new destination. The
4628 status of ongoing drive-backup operations can be checked with
4629 query-block-jobs where the BlockJobInfo.type field has the value
4630 'backup'. The operation can be stopped before it has completed using
4631 the block-job-cancel command.
4632 Arguments
4634 The members of DriveBackup
4635 Features
4637 deprecated
4638 This command is deprecated. Use blockdev-backup instead.
4639 Returns
4641 • nothing on success
4642 • If device is not a valid block device, GenericError
4644 Since
4646 1.6
4647 Example
4649 -> { "execute": "drive-backup",
4650 "arguments": { "device": "drive0",
4651 "sync": "full",
4652 "target": "backup.img" } }
4653 <- { "return": {} }
4654 blockdev-backup (Command)
4656 Start a point-in-time copy of a block device to a new destination. The
4657 status of ongoing blockdev-backup operations can be checked with
4658 query-block-jobs where the BlockJobInfo.type field has the value
4659 'backup'. The operation can be stopped before it has completed using
4660 the block-job-cancel command.
4661 Arguments
4663 The members of BlockdevBackup
4664 Returns
4666 • nothing on success
4667 • If device is not a valid block device, DeviceNotFound
4669 Since
4671 2.3
4672 Example
4674 -> { "execute": "blockdev-backup",
4675 "arguments": { "device": "src-id",
4676 "sync": "full",
4677 "target": "tgt-id" } }
4678 <- { "return": {} }
4679 query-named-block-nodes (Command)
4681 Get the named block driver list
4682 Arguments
4684 flat: boolean (optional)
4685 Omit the nested data about backing image ("backing-image" key)
4686 if true. Default is false (Since 5.0)
4687 Returns
4689 the list of BlockDeviceInfo
4690 Since
4692 2.0
4693 Example
4695 -> { "execute": "query-named-block-nodes" }
4696 <- { "return": [ { "ro":false,
4697 "drv":"qcow2",
4698 "encrypted":false,
4699 "file":"disks/test.qcow2",
4700 "node-name": "my-node",
4701 "backing_file_depth":1,
4702 "bps":1000000,
4703 "bps_rd":0,
4704 "bps_wr":0,
4705 "iops":1000000,
4706 "iops_rd":0,
4707 "iops_wr":0,
4708 "bps_max": 8000000,
4709 "bps_rd_max": 0,
4710 "bps_wr_max": 0,
4711 "iops_max": 0,
4712 "iops_rd_max": 0,
4713 "iops_wr_max": 0,
4714 "iops_size": 0,
4715 "write_threshold": 0,
4716 "image":{
4717 "filename":"disks/test.qcow2",
4718 "format":"qcow2",
4719 "virtual-size":2048000,
4720 "backing_file":"base.qcow2",
4721 "full-backing-filename":"disks/base.qcow2",
4722 "backing-filename-format":"qcow2",
4723 "snapshots":[
4724 {
4725 "id": "1",
4726 "name": "snapshot1",
4727 "vm-state-size": 0,
4728 "date-sec": 10000200,
4729 "date-nsec": 12,
4730 "vm-clock-sec": 206,
4731 "vm-clock-nsec": 30
4732 }
4733 ],
4734 "backing-image":{
4735 "filename":"disks/base.qcow2",
4736 "format":"qcow2",
4737 "virtual-size":2048000
4738 }
4739 } } ] }
4740 XDbgBlockGraphNodeType (Enum)
4742 Values
4743 block-backend
4744 corresponds to BlockBackend
4745 block-job
4747 corresponds to BlockJob
4748 block-driver
4750 corresponds to BlockDriverState
4751 Since
4753 4.0
4754 XDbgBlockGraphNode (Object)
4756 Members
4757 id: int
4758 Block graph node identifier. This id is generated only for x-de‐
4759 bug-query-block-graph and does not relate to any other identi‐
4760 fiers in Qemu.
4761 type: XDbgBlockGraphNodeType
4763 Type of graph node. Can be one of block-backend, block-job or
4764 block-driver-state.
4765 name: string
4767 Human readable name of the node. Corresponds to node-name for
4768 block-driver-state nodes; is not guaranteed to be unique in the
4769 whole graph (with block-jobs and block-backends).
4770 Since
4772 4.0
4773 BlockPermission (Enum)
4775 Enum of base block permissions.
4776 Values
4778 consistent-read
4779 A user that has the "permission" of consistent reads is guaran‐
4780 teed that their view of the contents of the block device is com‐
4781 plete and self-consistent, representing the contents of a disk
4782 at a specific point. For most block devices (including their
4783 backing files) this is true, but the property cannot be main‐
4784 tained in a few situations like for intermediate nodes of a com‐
4785 mit block job.
4786 write This permission is required to change the visible disk contents.
4788 write-unchanged
4790 This permission (which is weaker than BLK_PERM_WRITE) is both
4791 enough and required for writes to the block node when the caller
4792 promises that the visible disk content doesn't change. As the
4793 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
4794 cient to perform an unchanging write.
4795 resize This permission is required to change the size of a block node.
4797 graph-mod
4799 This permission is required to change the node that this
4800 BdrvChild points to.
4801 Since
4803 4.0
4804 XDbgBlockGraphEdge (Object)
4806 Block Graph edge description for x-debug-query-block-graph.
4807 Members
4809 parent: int
4810 parent id
4811 child: int
4813 child id
4814 name: string
4816 name of the relation (examples are 'file' and 'backing')
4817 perm: array of BlockPermission
4819 granted permissions for the parent operating on the child
4820 shared-perm: array of BlockPermission
4822 permissions that can still be granted to other users of the
4823 child while it is still attached to this parent
4824 Since
4826 4.0
4827 XDbgBlockGraph (Object)
4829 Block Graph - list of nodes and list of edges.
4830 Members
4832 nodes: array of XDbgBlockGraphNode
4833 Not documented
4834 edges: array of XDbgBlockGraphEdge
4836 Not documented
4837 Since
4839 4.0
4840 x-debug-query-block-graph (Command)
4842 Get the block graph.
4843 Features
4845 unstable
4846 This command is meant for debugging.
4847 Since
4849 4.0
4850 drive-mirror (Command)
4852 Start mirroring a block device's writes to a new destination. target
4853 specifies the target of the new image. If the file exists, or if it is
4854 a device, it will be used as the new destination for writes. If it does
4855 not exist, a new file will be created. format specifies the format of
4856 the mirror image, default is to probe if mode='existing', else the for‐
4857 mat of the source.
4858 Arguments
4860 The members of DriveMirror
4861 Returns
4863 • nothing on success
4864 • If device is not a valid block device, GenericError
4866 Since
4868 1.3
4869 Example
4871 -> { "execute": "drive-mirror",
4872 "arguments": { "device": "ide-hd0",
4873 "target": "/some/place/my-image",
4874 "sync": "full",
4875 "format": "qcow2" } }
4876 <- { "return": {} }
4877 DriveMirror (Object)
4879 A set of parameters describing drive mirror setup.
4880 Members
4882 job-id: string (optional)
4883 identifier for the newly-created block job. If omitted, the de‐
4884 vice name will be used. (Since 2.7)
4885 device: string
4887 the device name or node-name of a root node whose writes should
4888 be mirrored.
4889 target: string
4891 the target of the new image. If the file exists, or if it is a
4892 device, the existing file/device will be used as the new desti‐
4893 nation. If it does not exist, a new file will be created.
4894 format: string (optional)
4896 the format of the new destination, default is to probe if mode
4897 is 'existing', else the format of the source
4898 node-name: string (optional)
4900 the new block driver state node name in the graph (Since 2.1)
4901 replaces: string (optional)
4903 with sync=full graph node name to be replaced by the new image
4904 when a whole image copy is done. This can be used to repair bro‐
4905 ken Quorum files. By default, device is replaced, although im‐
4906 plicitly created filters on it are kept. (Since 2.1)
4907 mode: NewImageMode (optional)
4909 whether and how QEMU should create a new image, default is 'ab‐
4910 solute-paths'.
4911 speed: int (optional)
4913 the maximum speed, in bytes per second
4914 sync: MirrorSyncMode
4916 what parts of the disk image should be copied to the destination
4917 (all the disk, only the sectors allocated in the topmost image,
4918 or only new I/O).
4919 granularity: int (optional)
4921 granularity of the dirty bitmap, default is 64K if the image
4922 format doesn't have clusters, 4K if the clusters are smaller
4923 than that, else the cluster size. Must be a power of 2 between
4924 512 and 64M (since 1.4).
4925 buf-size: int (optional)
4927 maximum amount of data in flight from source to target (since
4928 1.4).
4929 on-source-error: BlockdevOnError (optional)
4931 the action to take on an error on the source, default 'report'.
4932 'stop' and 'enospc' can only be used if the block device sup‐
4933 ports io-status (see BlockInfo).
4934 on-target-error: BlockdevOnError (optional)
4936 the action to take on an error on the target, default 'report'
4937 (no limitations, since this applies to a different block device
4938 than device).
4939 unmap: boolean (optional)
4941 Whether to try to unmap target sectors where source has only
4942 zero. If true, and target unallocated sectors will read as zero,
4943 target image sectors will be unmapped; otherwise, zeroes will be
4944 written. Both will result in identical contents. Default is
4945 true. (Since 2.4)
4946 copy-mode: MirrorCopyMode (optional)
4948 when to copy data to the destination; defaults to 'background'
4949 (Since: 3.0)
4950 auto-finalize: boolean (optional)
4952 When false, this job will wait in a PENDING state after it has
4953 finished its work, waiting for block-job-finalize before making
4954 any block graph changes. When true, this job will automatically
4955 perform its abort or commit actions. Defaults to true. (Since
4956 3.1)
4957 auto-dismiss: boolean (optional)
4959 When false, this job will wait in a CONCLUDED state after it has
4960 completely ceased all work, and awaits block-job-dismiss. When
4961 true, this job will automatically disappear from the query list
4962 without user intervention. Defaults to true. (Since 3.1)
4963 Since
4965 1.3
4966 BlockDirtyBitmap (Object)
4968 Members
4969 node: string
4970 name of device/node which the bitmap is tracking
4971 name: string
4973 name of the dirty bitmap
4974 Since
4976 2.4
4977 BlockDirtyBitmapAdd (Object)
4979 Members
4980 node: string
4981 name of device/node which the bitmap is tracking
4982 name: string
4984 name of the dirty bitmap (must be less than 1024 bytes)
4985 granularity: int (optional)
4987 the bitmap granularity, default is 64k for block-dirty-bit‐
4988 map-add
4989 persistent: boolean (optional)
4991 the bitmap is persistent, i.e. it will be saved to the corre‐
4992 sponding block device image file on its close. For now only
4993 Qcow2 disks support persistent bitmaps. Default is false for
4994 block-dirty-bitmap-add. (Since: 2.10)
4995 disabled: boolean (optional)
4997 the bitmap is created in the disabled state, which means that it
4998 will not track drive changes. The bitmap may be enabled with
4999 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
5000 Since
5002 2.4
5003 BlockDirtyBitmapMergeSource (Alternate)
5005 Members
5006 local: string
5007 name of the bitmap, attached to the same node as target bitmap.
5008 external: BlockDirtyBitmap
5010 bitmap with specified node
5011 Since
5013 4.1
5014 BlockDirtyBitmapMerge (Object)
5016 Members
5017 node: string
5018 name of device/node which the target bitmap is tracking
5019 target: string
5021 name of the destination dirty bitmap
5022 bitmaps: array of BlockDirtyBitmapMergeSource
5024 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
5025 ified BlockDirtyBitmap elements. The latter are supported since
5026 4.1.
5027 Since
5029 4.0
5030 block-dirty-bitmap-add (Command)
5032 Create a dirty bitmap with a name on the node, and start tracking the
5033 writes.
5034 Returns
5036 • nothing on success
5037 • If node is not a valid block device or node, DeviceNotFound
5039 • If name is already taken, GenericError with an explanation
5041 Since
5043 2.4
5044 Example
5046 -> { "execute": "block-dirty-bitmap-add",
5047 "arguments": { "node": "drive0", "name": "bitmap0" } }
5048 <- { "return": {} }
5049 block-dirty-bitmap-remove (Command)
5051 Stop write tracking and remove the dirty bitmap that was created with
5052 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
5053 storage too.
5054 Returns
5056 • nothing on success
5057 • If node is not a valid block device or node, DeviceNotFound
5059 • If name is not found, GenericError with an explanation
5061 • if name is frozen by an operation, GenericError
5063 Since
5065 2.4
5066 Example
5068 -> { "execute": "block-dirty-bitmap-remove",
5069 "arguments": { "node": "drive0", "name": "bitmap0" } }
5070 <- { "return": {} }
5071 block-dirty-bitmap-clear (Command)
5073 Clear (reset) a dirty bitmap on the device, so that an incremental
5074 backup from this point in time forward will only backup clusters modi‐
5075 fied after this clear operation.
5076 Returns
5078 • nothing on success
5079 • If node is not a valid block device, DeviceNotFound
5081 • If name is not found, GenericError with an explanation
5083 Since
5085 2.4
5086 Example
5088 -> { "execute": "block-dirty-bitmap-clear",
5089 "arguments": { "node": "drive0", "name": "bitmap0" } }
5090 <- { "return": {} }
5091 block-dirty-bitmap-enable (Command)
5093 Enables a dirty bitmap so that it will begin tracking disk changes.
5094 Returns
5096 • nothing on success
5097 • If node is not a valid block device, DeviceNotFound
5099 • If name is not found, GenericError with an explanation
5101 Since
5103 4.0
5104 Example
5106 -> { "execute": "block-dirty-bitmap-enable",
5107 "arguments": { "node": "drive0", "name": "bitmap0" } }
5108 <- { "return": {} }
5109 block-dirty-bitmap-disable (Command)
5111 Disables a dirty bitmap so that it will stop tracking disk changes.
5112 Returns
5114 • nothing on success
5115 • If node is not a valid block device, DeviceNotFound
5117 • If name is not found, GenericError with an explanation
5119 Since
5121 4.0
5122 Example
5124 -> { "execute": "block-dirty-bitmap-disable",
5125 "arguments": { "node": "drive0", "name": "bitmap0" } }
5126 <- { "return": {} }
5127 block-dirty-bitmap-merge (Command)
5129 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
5130 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
5131 as the target bitmap. Any bits already set in target will still be set
5132 after the merge, i.e., this operation does not clear the target. On
5133 error, target is unchanged.
5134 The resulting bitmap will count as dirty any clusters that were dirty
5136 in any of the source bitmaps. This can be used to achieve backup check‐
5137 points, or in simpler usages, to copy bitmaps.
5138 Returns
5140 • nothing on success
5141 • If node is not a valid block device, DeviceNotFound
5143 • If any bitmap in bitmaps or target is not found, GenericError
5145 • If any of the bitmaps have different sizes or granularities, Gener‐
5147 icError
5148 Since
5150 4.0
5151 Example
5153 -> { "execute": "block-dirty-bitmap-merge",
5154 "arguments": { "node": "drive0", "target": "bitmap0",
5155 "bitmaps": ["bitmap1"] } }
5156 <- { "return": {} }
5157 BlockDirtyBitmapSha256 (Object)
5159 SHA256 hash of dirty bitmap data
5160 Members
5162 sha256: string
5163 ASCII representation of SHA256 bitmap hash
5164 Since
5166 2.10
5167 x-debug-block-dirty-bitmap-sha256 (Command)
5169 Get bitmap SHA256.
5170 Features
5172 unstable
5173 This command is meant for debugging.
5174 Returns
5176 • BlockDirtyBitmapSha256 on success
5177 • If node is not a valid block device, DeviceNotFound
5179 • If name is not found or if hashing has failed, GenericError with an
5181 explanation
5182 Since
5184 2.10
5185 blockdev-mirror (Command)
5187 Start mirroring a block device's writes to a new destination.
5188 Arguments
5190 job-id: string (optional)
5191 identifier for the newly-created block job. If omitted, the de‐
5192 vice name will be used. (Since 2.7)
5193 device: string
5195 The device name or node-name of a root node whose writes should
5196 be mirrored.
5197 target: string
5199 the id or node-name of the block device to mirror to. This
5200 mustn't be attached to guest.
5201 replaces: string (optional)
5203 with sync=full graph node name to be replaced by the new image
5204 when a whole image copy is done. This can be used to repair bro‐
5205 ken Quorum files. By default, device is replaced, although im‐
5206 plicitly created filters on it are kept.
5207 speed: int (optional)
5209 the maximum speed, in bytes per second
5210 sync: MirrorSyncMode
5212 what parts of the disk image should be copied to the destination
5213 (all the disk, only the sectors allocated in the topmost image,
5214 or only new I/O).
5215 granularity: int (optional)
5217 granularity of the dirty bitmap, default is 64K if the image
5218 format doesn't have clusters, 4K if the clusters are smaller
5219 than that, else the cluster size. Must be a power of 2 between
5220 512 and 64M
5221 buf-size: int (optional)
5223 maximum amount of data in flight from source to target
5224 on-source-error: BlockdevOnError (optional)
5226 the action to take on an error on the source, default 'report'.
5227 'stop' and 'enospc' can only be used if the block device sup‐
5228 ports io-status (see BlockInfo).
5229 on-target-error: BlockdevOnError (optional)
5231 the action to take on an error on the target, default 'report'
5232 (no limitations, since this applies to a different block device
5233 than device).
5234 filter-node-name: string (optional)
5236 the node name that should be assigned to the filter driver that
5237 the mirror job inserts into the graph above device. If this op‐
5238 tion is not given, a node name is autogenerated. (Since: 2.9)
5239 copy-mode: MirrorCopyMode (optional)
5241 when to copy data to the destination; defaults to 'background'
5242 (Since: 3.0)
5243 auto-finalize: boolean (optional)
5245 When false, this job will wait in a PENDING state after it has
5246 finished its work, waiting for block-job-finalize before making
5247 any block graph changes. When true, this job will automatically
5248 perform its abort or commit actions. Defaults to true. (Since
5249 3.1)
5250 auto-dismiss: boolean (optional)
5252 When false, this job will wait in a CONCLUDED state after it has
5253 completely ceased all work, and awaits block-job-dismiss. When
5254 true, this job will automatically disappear from the query list
5255 without user intervention. Defaults to true. (Since 3.1)
5256 Returns
5258 nothing on success.
5259 Since
5261 2.6
5262 Example
5264 -> { "execute": "blockdev-mirror",
5265 "arguments": { "device": "ide-hd0",
5266 "target": "target0",
5267 "sync": "full" } }
5268 <- { "return": {} }
5269 BlockIOThrottle (Object)
5271 A set of parameters describing block throttling.
5272 Members
5274 device: string (optional)
5275 Block device name
5276 id: string (optional)
5278 The name or QOM path of the guest device (since: 2.8)
5279 bps: int
5281 total throughput limit in bytes per second
5282 bps_rd: int
5284 read throughput limit in bytes per second
5285 bps_wr: int
5287 write throughput limit in bytes per second
5288 iops: int
5290 total I/O operations per second
5291 iops_rd: int
5293 read I/O operations per second
5294 iops_wr: int
5296 write I/O operations per second
5297 bps_max: int (optional)
5299 total throughput limit during bursts, in bytes (Since 1.7)
5300 bps_rd_max: int (optional)
5302 read throughput limit during bursts, in bytes (Since 1.7)
5303 bps_wr_max: int (optional)
5305 write throughput limit during bursts, in bytes (Since 1.7)
5306 iops_max: int (optional)
5308 total I/O operations per second during bursts, in bytes (Since
5309 1.7)
5310 iops_rd_max: int (optional)
5312 read I/O operations per second during bursts, in bytes (Since
5313 1.7)
5314 iops_wr_max: int (optional)
5316 write I/O operations per second during bursts, in bytes (Since
5317 1.7)
5318 bps_max_length: int (optional)
5320 maximum length of the bps_max burst period, in seconds. It must
5321 only be set if bps_max is set as well. Defaults to 1. (Since
5322 2.6)
5323 bps_rd_max_length: int (optional)
5325 maximum length of the bps_rd_max burst period, in seconds. It
5326 must only be set if bps_rd_max is set as well. Defaults to 1.
5327 (Since 2.6)
5328 bps_wr_max_length: int (optional)
5330 maximum length of the bps_wr_max burst period, in seconds. It
5331 must only be set if bps_wr_max is set as well. Defaults to 1.
5332 (Since 2.6)
5333 iops_max_length: int (optional)
5335 maximum length of the iops burst period, in seconds. It must
5336 only be set if iops_max is set as well. Defaults to 1. (Since
5337 2.6)
5338 iops_rd_max_length: int (optional)
5340 maximum length of the iops_rd_max burst period, in seconds. It
5341 must only be set if iops_rd_max is set as well. Defaults to 1.
5342 (Since 2.6)
5343 iops_wr_max_length: int (optional)
5345 maximum length of the iops_wr_max burst period, in seconds. It
5346 must only be set if iops_wr_max is set as well. Defaults to 1.
5347 (Since 2.6)
5348 iops_size: int (optional)
5350 an I/O size in bytes (Since 1.7)
5351 group: string (optional)
5353 throttle group name (Since 2.4)
5354 Features
5356 deprecated
5357 Member device is deprecated. Use id instead.
5358 Since
5360 1.1
5361 ThrottleLimits (Object)
5363 Limit parameters for throttling. Since some limit combinations are il‐
5364 legal, limits should always be set in one transaction. All fields are
5365 optional. When setting limits, if a field is missing the current value
5366 is not changed.
5367 Members
5369 iops-total: int (optional)
5370 limit total I/O operations per second
5371 iops-total-max: int (optional)
5373 I/O operations burst
5374 iops-total-max-length: int (optional)
5376 length of the iops-total-max burst period, in seconds It must
5377 only be set if iops-total-max is set as well.
5378 iops-read: int (optional)
5380 limit read operations per second
5381 iops-read-max: int (optional)
5383 I/O operations read burst
5384 iops-read-max-length: int (optional)
5386 length of the iops-read-max burst period, in seconds It must
5387 only be set if iops-read-max is set as well.
5388 iops-write: int (optional)
5390 limit write operations per second
5391 iops-write-max: int (optional)
5393 I/O operations write burst
5394 iops-write-max-length: int (optional)
5396 length of the iops-write-max burst period, in seconds It must
5397 only be set if iops-write-max is set as well.
5398 bps-total: int (optional)
5400 limit total bytes per second
5401 bps-total-max: int (optional)
5403 total bytes burst
5404 bps-total-max-length: int (optional)
5406 length of the bps-total-max burst period, in seconds. It must
5407 only be set if bps-total-max is set as well.
5408 bps-read: int (optional)
5410 limit read bytes per second
5411 bps-read-max: int (optional)
5413 total bytes read burst
5414 bps-read-max-length: int (optional)
5416 length of the bps-read-max burst period, in seconds It must only
5417 be set if bps-read-max is set as well.
5418 bps-write: int (optional)
5420 limit write bytes per second
5421 bps-write-max: int (optional)
5423 total bytes write burst
5424 bps-write-max-length: int (optional)
5426 length of the bps-write-max burst period, in seconds It must
5427 only be set if bps-write-max is set as well.
5428 iops-size: int (optional)
5430 when limiting by iops max size of an I/O in bytes
5431 Since
5433 2.11
5434 ThrottleGroupProperties (Object)
5436 Properties for throttle-group objects.
5437 Members
5439 limits: ThrottleLimits (optional)
5440 limits to apply for this throttle group
5441 x-iops-total: int (optional)
5443 Not documented
5444 x-iops-total-max: int (optional)
5446 Not documented
5447 x-iops-total-max-length: int (optional)
5449 Not documented
5450 x-iops-read: int (optional)
5452 Not documented
5453 x-iops-read-max: int (optional)
5455 Not documented
5456 x-iops-read-max-length: int (optional)
5458 Not documented
5459 x-iops-write: int (optional)
5461 Not documented
5462 x-iops-write-max: int (optional)
5464 Not documented
5465 x-iops-write-max-length: int (optional)
5467 Not documented
5468 x-bps-total: int (optional)
5470 Not documented
5471 x-bps-total-max: int (optional)
5473 Not documented
5474 x-bps-total-max-length: int (optional)
5476 Not documented
5477 x-bps-read: int (optional)
5479 Not documented
5480 x-bps-read-max: int (optional)
5482 Not documented
5483 x-bps-read-max-length: int (optional)
5485 Not documented
5486 x-bps-write: int (optional)
5488 Not documented
5489 x-bps-write-max: int (optional)
5491 Not documented
5492 x-bps-write-max-length: int (optional)
5494 Not documented
5495 x-iops-size: int (optional)
5497 Not documented
5498 Features
5500 unstable
5501 All members starting with x- are aliases for the same key with‐
5502 out x- in the limits object. This is not a stable interface and
5503 may be removed or changed incompatibly in the future. Use lim‐
5504 its for a supported stable interface.
5505 Since
5507 2.11
5508 block-stream (Command)
5510 Copy data from a backing file into a block device.
5511 The block streaming operation is performed in the background until the
5513 entire backing file has been copied. This command returns immediately
5514 once streaming has started. The status of ongoing block streaming op‐
5515 erations can be checked with query-block-jobs. The operation can be
5516 stopped before it has completed using the block-job-cancel command.
5517 The node that receives the data is called the top image, can be located
5519 in any part of the chain (but always above the base image; see below)
5520 and can be specified using its device or node name. Earlier qemu ver‐
5521 sions only allowed 'device' to name the top level node; presence of the
5522 'base-node' parameter during introspection can be used as a witness of
5523 the enhanced semantics of 'device'.
5524 If a base file is specified then sectors are not copied from that base
5526 file and its backing chain. This can be used to stream a subset of the
5527 backing file chain instead of flattening the entire image. When
5528 streaming completes the image file will have the base file as its back‐
5529 ing file, unless that node was changed while the job was running. In
5530 that case, base's parent's backing (or filtered, whichever exists)
5531 child (i.e., base at the beginning of the job) will be the new backing
5532 file.
5533 On successful completion the image file is updated to drop the backing
5535 file and the BLOCK_JOB_COMPLETED event is emitted.
5536 In case device is a filter node, block-stream modifies the first
5538 non-filter overlay node below it to point to the new backing node in‐
5539 stead of modifying device itself.
5540 Arguments
5542 job-id: string (optional)
5543 identifier for the newly-created block job. If omitted, the de‐
5544 vice name will be used. (Since 2.7)
5545 device: string
5547 the device or node name of the top image
5548 base: string (optional)
5550 the common backing file name. It cannot be set if base-node or
5551 bottom is also set.
5552 base-node: string (optional)
5554 the node name of the backing file. It cannot be set if base or
5555 bottom is also set. (Since 2.8)
5556 bottom: string (optional)
5558 the last node in the chain that should be streamed into top. It
5559 cannot be set if base or base-node is also set. It cannot be
5560 filter node. (Since 6.0)
5561 backing-file: string (optional)
5563 The backing file string to write into the top image. This file‐
5564 name is not validated.
5565 If a pathname string is such that it cannot be resolved by QEMU,
5567 that means that subsequent QMP or HMP commands must use
5568 node-names for the image in question, as filename lookup methods
5569 will fail.
5570 If not specified, QEMU will automatically determine the backing
5572 file string to use, or error out if there is no obvious choice.
5573 Care should be taken when specifying the string, to specify a
5574 valid filename or protocol. (Since 2.1)
5575 speed: int (optional)
5577 the maximum speed, in bytes per second
5578 on-error: BlockdevOnError (optional)
5580 the action to take on an error (default report). 'stop' and
5581 'enospc' can only be used if the block device supports io-status
5582 (see BlockInfo). Since 1.3.
5583 filter-node-name: string (optional)
5585 the node name that should be assigned to the filter driver that
5586 the stream job inserts into the graph above device. If this op‐
5587 tion is not given, a node name is autogenerated. (Since: 6.0)
5588 auto-finalize: boolean (optional)
5590 When false, this job will wait in a PENDING state after it has
5591 finished its work, waiting for block-job-finalize before making
5592 any block graph changes. When true, this job will automatically
5593 perform its abort or commit actions. Defaults to true. (Since
5594 3.1)
5595 auto-dismiss: boolean (optional)
5597 When false, this job will wait in a CONCLUDED state after it has
5598 completely ceased all work, and awaits block-job-dismiss. When
5599 true, this job will automatically disappear from the query list
5600 without user intervention. Defaults to true. (Since 3.1)
5601 Returns
5603 • Nothing on success.
5604 • If device does not exist, DeviceNotFound.
5606 Since
5608 1.1
5609 Example
5611 -> { "execute": "block-stream",
5612 "arguments": { "device": "virtio0",
5613 "base": "/tmp/master.qcow2" } }
5614 <- { "return": {} }
5615 block-job-set-speed (Command)
5617 Set maximum speed for a background block operation.
5618 This command can only be issued when there is an active block job.
5620 Throttling can be disabled by setting the speed to 0.
5622 Arguments
5624 device: string
5625 The job identifier. This used to be a device name (hence the
5626 name of the parameter), but since QEMU 2.7 it can have other
5627 values.
5628 speed: int
5630 the maximum speed, in bytes per second, or 0 for unlimited. De‐
5631 faults to 0.
5632 Returns
5634 • Nothing on success
5635 • If no background operation is active on this device, DeviceNotActive
5637 Since
5639 1.1
5640 block-job-cancel (Command)
5642 Stop an active background block operation.
5643 This command returns immediately after marking the active background
5645 block operation for cancellation. It is an error to call this command
5646 if no operation is in progress.
5647 The operation will cancel as soon as possible and then emit the
5649 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
5650 ble when enumerated using query-block-jobs.
5651 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
5653 dicated (via the event BLOCK_JOB_READY) that the source and destination
5654 are synchronized, then the event triggered by this command changes to
5655 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
5656 destination now has a point-in-time copy tied to the time of the can‐
5657 cellation.
5658 For streaming, the image file retains its backing file unless the
5660 streaming operation happens to complete just as it is being cancelled.
5661 A new streaming operation can be started at a later time to finish
5662 copying all data from the backing file.
5663 Arguments
5665 device: string
5666 The job identifier. This used to be a device name (hence the
5667 name of the parameter), but since QEMU 2.7 it can have other
5668 values.
5669 force: boolean (optional)
5671 If true, and the job has already emitted the event
5672 BLOCK_JOB_READY, abandon the job immediately (even if it is
5673 paused) instead of waiting for the destination to complete its
5674 final synchronization (since 1.3)
5675 Returns
5677 • Nothing on success
5678 • If no background operation is active on this device, DeviceNotActive
5680 Since
5682 1.1
5683 block-job-pause (Command)
5685 Pause an active background block operation.
5686 This command returns immediately after marking the active background
5688 block operation for pausing. It is an error to call this command if no
5689 operation is in progress or if the job is already paused.
5690 The operation will pause as soon as possible. No event is emitted when
5692 the operation is actually paused. Cancelling a paused job automati‐
5693 cally resumes it.
5694 Arguments
5696 device: string
5697 The job identifier. This used to be a device name (hence the
5698 name of the parameter), but since QEMU 2.7 it can have other
5699 values.
5700 Returns
5702 • Nothing on success
5703 • If no background operation is active on this device, DeviceNotActive
5705 Since
5707 1.3
5708 block-job-resume (Command)
5710 Resume an active background block operation.
5711 This command returns immediately after resuming a paused background
5713 block operation. It is an error to call this command if no operation
5714 is in progress or if the job is not paused.
5715 This command also clears the error status of the job.
5717 Arguments
5719 device: string
5720 The job identifier. This used to be a device name (hence the
5721 name of the parameter), but since QEMU 2.7 it can have other
5722 values.
5723 Returns
5725 • Nothing on success
5726 • If no background operation is active on this device, DeviceNotActive
5728 Since
5730 1.3
5731 block-job-complete (Command)
5733 Manually trigger completion of an active background block operation.
5734 This is supported for drive mirroring, where it also switches the de‐
5735 vice to write to the target path only. The ability to complete is sig‐
5736 naled with a BLOCK_JOB_READY event.
5737 This command completes an active background block operation syn‐
5739 chronously. The ordering of this command's return with the
5740 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
5741 occurs during the processing of this command: 1) the command itself
5742 will fail; 2) the error will be processed according to the rerror/wer‐
5743 ror arguments that were specified when starting the operation.
5744 A cancelled or paused job cannot be completed.
5746 Arguments
5748 device: string
5749 The job identifier. This used to be a device name (hence the
5750 name of the parameter), but since QEMU 2.7 it can have other
5751 values.
5752 Returns
5754 • Nothing on success
5755 • If no background operation is active on this device, DeviceNotActive
5757 Since
5759 1.3
5760 block-job-dismiss (Command)
5762 For jobs that have already concluded, remove them from the
5763 block-job-query list. This command only needs to be run for jobs which
5764 were started with QEMU 2.12+ job lifetime management semantics.
5765 This command will refuse to operate on any job that has not yet reached
5767 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
5768 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
5769 still need to be used as appropriate.
5770 Arguments
5772 id: string
5773 The job identifier.
5774 Returns
5776 Nothing on success
5777 Since
5779 2.12
5780 block-job-finalize (Command)
5782 Once a job that has manual=true reaches the pending state, it can be
5783 instructed to finalize any graph changes and do any necessary cleanup
5784 via this command. For jobs in a transaction, instructing one job to
5785 finalize will force ALL jobs in the transaction to finalize, so it is
5786 only necessary to instruct a single member job to finalize.
5787 Arguments
5789 id: string
5790 The job identifier.
5791 Returns
5793 Nothing on success
5794 Since
5796 2.12
5797 BlockdevDiscardOptions (Enum)
5799 Determines how to handle discard requests.
5800 Values
5802 ignore Ignore the request
5803 unmap Forward as an unmap request
5805 Since
5807 2.9
5808 BlockdevDetectZeroesOptions (Enum)
5810 Describes the operation mode for the automatic conversion of plain zero
5811 writes by the OS to driver specific optimized zero write commands.
5812 Values
5814 off Disabled (default)
5815 on Enabled
5817 unmap Enabled and even try to unmap blocks if possible. This requires
5819 also that BlockdevDiscardOptions is set to unmap for this de‐
5820 vice.
5821 Since
5823 2.1
5824 BlockdevAioOptions (Enum)
5826 Selects the AIO backend to handle I/O requests
5827 Values
5829 threads
5830 Use qemu's thread pool
5831 native Use native AIO backend (only Linux and Windows)
5833 io_uring (If: CONFIG_LINUX_IO_URING)
5835 Use linux io_uring (since 5.0)
5836 Since
5838 2.9
5839 BlockdevCacheOptions (Object)
5841 Includes cache-related options for block devices
5842 Members
5844 direct: boolean (optional)
5845 enables use of O_DIRECT (bypass the host page cache; default:
5846 false)
5847 no-flush: boolean (optional)
5849 ignore any flush requests for the device (default: false)
5850 Since
5852 2.9
5853 BlockdevDriver (Enum)
5855 Drivers that are supported in block device operations.
5856 Values
5858 throttle
5859 Since 2.11
5860 nvme Since 2.12
5862 copy-on-read
5864 Since 3.0
5865 blklogwrites
5867 Since 3.0
5868 blkreplay
5870 Since 4.2
5871 compress
5873 Since 5.0
5874 copy-before-write
5876 Since 6.2
5877 blkdebug
5879 Not documented
5880 blkverify
5882 Not documented
5883 bochs Not documented
5885 cloop Not documented
5887 dmg Not documented
5889 file Not documented
5891 ftp Not documented
5893 ftps Not documented
5895 gluster
5897 Not documented
5898 host_cdrom (If: HAVE_HOST_BLOCK_DEVICE)
5900 Not documented
5901 host_device (If: HAVE_HOST_BLOCK_DEVICE)
5903 Not documented
5904 http Not documented
5906 https Not documented
5908 iscsi Not documented
5910 luks Not documented
5912 nbd Not documented
5914 nfs Not documented
5916 null-aio
5918 Not documented
5919 null-co
5921 Not documented
5922 parallels
5924 Not documented
5925 preallocate
5927 Not documented
5928 qcow Not documented
5930 qcow2 Not documented
5932 qed Not documented
5934 quorum Not documented
5936 raw Not documented
5938 rbd Not documented
5940 replication (If: CONFIG_REPLICATION)
5942 Not documented
5943 ssh Not documented
5945 vdi Not documented
5947 vhdx Not documented
5949 vmdk Not documented
5951 vpc Not documented
5953 vvfat Not documented
5955 Since
5957 2.9
5958 BlockdevOptionsFile (Object)
5960 Driver specific block device options for the file backend.
5961 Members
5963 filename: string
5964 path to the image file
5965 pr-manager: string (optional)
5967 the id for the object that will handle persistent reservations
5968 for this device (default: none, forward the commands via SG_IO;
5969 since 2.11)
5970 aio: BlockdevAioOptions (optional)
5972 AIO backend (default: threads) (since: 2.8)
5973 aio-max-batch: int (optional)
5975 maximum number of requests to batch together into a single sub‐
5976 mission in the AIO backend. The smallest value between this and
5977 the aio-max-batch value of the IOThread object is chosen. 0
5978 means that the AIO backend will handle it automatically. (de‐
5979 fault: 0, since 6.2)
5980 locking: OnOffAuto (optional)
5982 whether to enable file locking. If set to 'auto', only enable
5983 when Open File Descriptor (OFD) locking API is available (de‐
5984 fault: auto, since 2.10)
5985 drop-cache: boolean (optional) (If: CONFIG_LINUX)
5987 invalidate page cache during live migration. This prevents
5988 stale data on the migration destination with cache.direct=off.
5989 Currently only supported on Linux hosts. (default: on, since:
5990 4.0)
5991 x-check-cache-dropped: boolean (optional)
5993 whether to check that page cache was dropped on live migration.
5994 May cause noticeable delays if the image file is large, do not
5995 use in production. (default: off) (since: 3.0)
5996 Features
5998 dynamic-auto-read-only
5999 If present, enabled auto-read-only means that the driver will
6000 open the image read-only at first, dynamically reopen the image
6001 file read-write when the first writer is attached to the node
6002 and reopen read-only when the last writer is detached. This al‐
6003 lows giving QEMU write permissions only on demand when an opera‐
6004 tion actually needs write access.
6005 unstable
6007 Member x-check-cache-dropped is meant for debugging.
6008 Since
6010 2.9
6011 BlockdevOptionsNull (Object)
6013 Driver specific block device options for the null backend.
6014 Members
6016 size: int (optional)
6017 size of the device in bytes.
6018 latency-ns: int (optional)
6020 emulated latency (in nanoseconds) in processing requests. De‐
6021 fault to zero which completes requests immediately. (Since 2.4)
6022 read-zeroes: boolean (optional)
6024 if true, reads from the device produce zeroes; if false, the
6025 buffer is left unchanged. (default: false; since: 4.1)
6026 Since
6028 2.9
6029 BlockdevOptionsNVMe (Object)
6031 Driver specific block device options for the NVMe backend.
6032 Members
6034 device: string
6035 PCI controller address of the NVMe device in format hhhh:bb:ss.f
6036 (host:bus:slot.function)
6037 namespace: int
6039 namespace number of the device, starting from 1.
6040 Note that the PCI device must have been unbound from any host kernel
6041 driver before instructing QEMU to add the blockdev.
6042 Since
6044 2.12
6045 BlockdevOptionsVVFAT (Object)
6047 Driver specific block device options for the vvfat protocol.
6048 Members
6050 dir: string
6051 directory to be exported as FAT image
6052 fat-type: int (optional)
6054 FAT type: 12, 16 or 32
6055 floppy: boolean (optional)
6057 whether to export a floppy image (true) or partitioned hard disk
6058 (false; default)
6059 label: string (optional)
6061 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
6062 ditionally have some restrictions on labels, which are ignored
6063 by most operating systems. Defaults to "QEMU VVFAT". (since
6064 2.4)
6065 rw: boolean (optional)
6067 whether to allow write operations (default: false)
6068 Since
6070 2.9
6071 BlockdevOptionsGenericFormat (Object)
6073 Driver specific block device options for image format that have no op‐
6074 tion besides their data source.
6075 Members
6077 file: BlockdevRef
6078 reference to or definition of the data source block device
6079 Since
6081 2.9
6082 BlockdevOptionsLUKS (Object)
6084 Driver specific block device options for LUKS.
6085 Members
6087 key-secret: string (optional)
6088 the ID of a QCryptoSecret object providing the decryption key
6089 (since 2.6). Mandatory except when doing a metadata-only probe
6090 of the image.
6091 The members of BlockdevOptionsGenericFormat
6093 Since
6095 2.9
6096 BlockdevOptionsGenericCOWFormat (Object)
6098 Driver specific block device options for image format that have no op‐
6099 tion besides their data source and an optional backing file.
6100 Members
6102 backing: BlockdevRefOrNull (optional)
6103 reference to or definition of the backing file block device,
6104 null disables the backing file entirely. Defaults to the back‐
6105 ing file stored the image file.
6106 The members of BlockdevOptionsGenericFormat
6108 Since
6110 2.9
6111 Qcow2OverlapCheckMode (Enum)
6113 General overlap check modes.
6114 Values
6116 none Do not perform any checks
6117 constant
6119 Perform only checks which can be done in constant time and with‐
6120 out reading anything from disk
6121 cached Perform only checks which can be done without reading anything
6123 from disk
6124 all Perform all available overlap checks
6126 Since
6128 2.9
6129 Qcow2OverlapCheckFlags (Object)
6131 Structure of flags for each metadata structure. Setting a field to
6132 'true' makes qemu guard that structure against unintended overwriting.
6133 The default value is chosen according to the template given.
6134 Members
6136 template: Qcow2OverlapCheckMode (optional)
6137 Specifies a template mode which can be adjusted using the other
6138 flags, defaults to 'cached'
6139 bitmap-directory: boolean (optional)
6141 since 3.0
6142 main-header: boolean (optional)
6144 Not documented
6145 active-l1: boolean (optional)
6147 Not documented
6148 active-l2: boolean (optional)
6150 Not documented
6151 refcount-table: boolean (optional)
6153 Not documented
6154 refcount-block: boolean (optional)
6156 Not documented
6157 snapshot-table: boolean (optional)
6159 Not documented
6160 inactive-l1: boolean (optional)
6162 Not documented
6163 inactive-l2: boolean (optional)
6165 Not documented
6166 Since
6168 2.9
6169 Qcow2OverlapChecks (Alternate)
6171 Specifies which metadata structures should be guarded against unin‐
6172 tended overwriting.
6173 Members
6175 flags: Qcow2OverlapCheckFlags
6176 set of flags for separate specification of each metadata struc‐
6177 ture type
6178 mode: Qcow2OverlapCheckMode
6180 named mode which chooses a specific set of flags
6181 Since
6183 2.9
6184 BlockdevQcowEncryptionFormat (Enum)
6186 Values
6187 aes AES-CBC with plain64 initialization vectors
6188 Since
6190 2.10
6191 BlockdevQcowEncryption (Object)
6193 Members
6194 format: BlockdevQcowEncryptionFormat
6195 Not documented
6196 The members of QCryptoBlockOptionsQCow when format is "aes"
6198 Since
6200 2.10
6201 BlockdevOptionsQcow (Object)
6203 Driver specific block device options for qcow.
6204 Members
6206 encrypt: BlockdevQcowEncryption (optional)
6207 Image decryption options. Mandatory for encrypted images, except
6208 when doing a metadata-only probe of the image.
6209 The members of BlockdevOptionsGenericCOWFormat
6211 Since
6213 2.10
6214 BlockdevQcow2EncryptionFormat (Enum)
6216 Values
6217 aes AES-CBC with plain64 initialization vectors
6218 luks Not documented
6220 Since
6222 2.10
6223 BlockdevQcow2Encryption (Object)
6225 Members
6226 format: BlockdevQcow2EncryptionFormat
6227 Not documented
6228 The members of QCryptoBlockOptionsQCow when format is "aes"
6230 The members of QCryptoBlockOptionsLUKS when format is "luks"
6232 Since
6234 2.10
6235 BlockdevOptionsPreallocate (Object)
6237 Filter driver intended to be inserted between format and protocol node
6238 and do preallocation in protocol node on write.
6239 Members
6241 prealloc-align: int (optional)
6242 on preallocation, align file length to this number, default
6243 1048576 (1M)
6244 prealloc-size: int (optional)
6246 how much to preallocate, default 134217728 (128M)
6247 The members of BlockdevOptionsGenericFormat
6249 Since
6251 6.0
6252 BlockdevOptionsQcow2 (Object)
6254 Driver specific block device options for qcow2.
6255 Members
6257 lazy-refcounts: boolean (optional)
6258 whether to enable the lazy refcounts feature (default is taken
6259 from the image file)
6260 pass-discard-request: boolean (optional)
6262 whether discard requests to the qcow2 device should be forwarded
6263 to the data source
6264 pass-discard-snapshot: boolean (optional)
6266 whether discard requests for the data source should be issued
6267 when a snapshot operation (e.g. deleting a snapshot) frees
6268 clusters in the qcow2 file
6269 pass-discard-other: boolean (optional)
6271 whether discard requests for the data source should be issued on
6272 other occasions where a cluster gets freed
6273 overlap-check: Qcow2OverlapChecks (optional)
6275 which overlap checks to perform for writes to the image, de‐
6276 faults to 'cached' (since 2.2)
6277 cache-size: int (optional)
6279 the maximum total size of the L2 table and refcount block caches
6280 in bytes (since 2.2)
6281 l2-cache-size: int (optional)
6283 the maximum size of the L2 table cache in bytes (since 2.2)
6284 l2-cache-entry-size: int (optional)
6286 the size of each entry in the L2 cache in bytes. It must be a
6287 power of two between 512 and the cluster size. The default value
6288 is the cluster size (since 2.12)
6289 refcount-cache-size: int (optional)
6291 the maximum size of the refcount block cache in bytes (since
6292 2.2)
6293 cache-clean-interval: int (optional)
6295 clean unused entries in the L2 and refcount caches. The interval
6296 is in seconds. The default value is 600 on supporting platforms,
6297 and 0 on other platforms. 0 disables this feature. (since 2.5)
6298 encrypt: BlockdevQcow2Encryption (optional)
6300 Image decryption options. Mandatory for encrypted images, except
6301 when doing a metadata-only probe of the image. (since 2.10)
6302 data-file: BlockdevRef (optional)
6304 reference to or definition of the external data file. This may
6305 only be specified for images that require an external data file.
6306 If it is not specified for such an image, the data file name is
6307 loaded from the image file. (since 4.0)
6308 The members of BlockdevOptionsGenericCOWFormat
6310 Since
6312 2.9
6313 SshHostKeyCheckMode (Enum)
6315 Values
6316 none Don't check the host key at all
6317 hash Compare the host key with a given hash
6319 known_hosts
6321 Check the host key against the known_hosts file
6322 Since
6324 2.12
6325 SshHostKeyCheckHashType (Enum)
6327 Values
6328 md5 The given hash is an md5 hash
6329 sha1 The given hash is an sha1 hash
6331 sha256 The given hash is an sha256 hash
6333 Since
6335 2.12
6336 SshHostKeyHash (Object)
6338 Members
6339 type: SshHostKeyCheckHashType
6340 The hash algorithm used for the hash
6341 hash: string
6343 The expected hash value
6344 Since
6346 2.12
6347 SshHostKeyCheck (Object)
6349 Members
6350 mode: SshHostKeyCheckMode
6351 Not documented
6352 The members of SshHostKeyHash when mode is "hash"
6354 Since
6356 2.12
6357 BlockdevOptionsSsh (Object)
6359 Members
6360 server: InetSocketAddress
6361 host address
6362 path: string
6364 path to the image on the host
6365 user: string (optional)
6367 user as which to connect, defaults to current local user name
6368 host-key-check: SshHostKeyCheck (optional)
6370 Defines how and what to check the host key against (default:
6371 known_hosts)
6372 Since
6374 2.9
6375 BlkdebugEvent (Enum)
6377 Trigger events supported by blkdebug.
6378 Values
6380 l1_shrink_write_table
6381 write zeros to the l1 table to shrink image. (since 2.11)
6382 l1_shrink_free_l2_clusters
6384 discard the l2 tables. (since 2.11)
6385 cor_write
6387 a write due to copy-on-read (since 2.11)
6388 cluster_alloc_space
6390 an allocation of file space for a cluster (since 4.1)
6391 none triggers once at creation of the blkdebug node (since 4.1)
6393 l1_update
6395 Not documented
6396 l1_grow_alloc_table
6398 Not documented
6399 l1_grow_write_table
6401 Not documented
6402 l1_grow_activate_table
6404 Not documented
6405 l2_load
6407 Not documented
6408 l2_update
6410 Not documented
6411 l2_update_compressed
6413 Not documented
6414 l2_alloc_cow_read
6416 Not documented
6417 l2_alloc_write
6419 Not documented
6420 read_aio
6422 Not documented
6423 read_backing_aio
6425 Not documented
6426 read_compressed
6428 Not documented
6429 write_aio
6431 Not documented
6432 write_compressed
6434 Not documented
6435 vmstate_load
6437 Not documented
6438 vmstate_save
6440 Not documented
6441 cow_read
6443 Not documented
6444 cow_write
6446 Not documented
6447 reftable_load
6449 Not documented
6450 reftable_grow
6452 Not documented
6453 reftable_update
6455 Not documented
6456 refblock_load
6458 Not documented
6459 refblock_update
6461 Not documented
6462 refblock_update_part
6464 Not documented
6465 refblock_alloc
6467 Not documented
6468 refblock_alloc_hookup
6470 Not documented
6471 refblock_alloc_write
6473 Not documented
6474 refblock_alloc_write_blocks
6476 Not documented
6477 refblock_alloc_write_table
6479 Not documented
6480 refblock_alloc_switch_table
6482 Not documented
6483 cluster_alloc
6485 Not documented
6486 cluster_alloc_bytes
6488 Not documented
6489 cluster_free
6491 Not documented
6492 flush_to_os
6494 Not documented
6495 flush_to_disk
6497 Not documented
6498 pwritev_rmw_head
6500 Not documented
6501 pwritev_rmw_after_head
6503 Not documented
6504 pwritev_rmw_tail
6506 Not documented
6507 pwritev_rmw_after_tail
6509 Not documented
6510 pwritev
6512 Not documented
6513 pwritev_zero
6515 Not documented
6516 pwritev_done
6518 Not documented
6519 empty_image_prepare
6521 Not documented
6522 Since
6524 2.9
6525 BlkdebugIOType (Enum)
6527 Kinds of I/O that blkdebug can inject errors in.
6528 Values
6530 read .bdrv_co_preadv()
6531 write .bdrv_co_pwritev()
6533 write-zeroes
6535 .bdrv_co_pwrite_zeroes()
6536 discard
6538 .bdrv_co_pdiscard()
6539 flush .bdrv_co_flush_to_disk()
6541 block-status
6543 .bdrv_co_block_status()
6544 Since
6546 4.1
6547 BlkdebugInjectErrorOptions (Object)
6549 Describes a single error injection for blkdebug.
6550 Members
6552 event: BlkdebugEvent
6553 trigger event
6554 state: int (optional)
6556 the state identifier blkdebug needs to be in to actually trigger
6557 the event; defaults to "any"
6558 iotype: BlkdebugIOType (optional)
6560 the type of I/O operations on which this error should be in‐
6561 jected; defaults to "all read, write, write-zeroes, discard, and
6562 flush operations" (since: 4.1)
6563 errno: int (optional)
6565 error identifier (errno) to be returned; defaults to EIO
6566 sector: int (optional)
6568 specifies the sector index which has to be affected in order to
6569 actually trigger the event; defaults to "any sector"
6570 once: boolean (optional)
6572 disables further events after this one has been triggered; de‐
6573 faults to false
6574 immediately: boolean (optional)
6576 fail immediately; defaults to false
6577 Since
6579 2.9
6580 BlkdebugSetStateOptions (Object)
6582 Describes a single state-change event for blkdebug.
6583 Members
6585 event: BlkdebugEvent
6586 trigger event
6587 state: int (optional)
6589 the current state identifier blkdebug needs to be in; defaults
6590 to "any"
6591 new_state: int
6593 the state identifier blkdebug is supposed to assume if this
6594 event is triggered
6595 Since
6597 2.9
6598 BlockdevOptionsBlkdebug (Object)
6600 Driver specific block device options for blkdebug.
6601 Members
6603 image: BlockdevRef
6604 underlying raw block device (or image file)
6605 config: string (optional)
6607 filename of the configuration file
6608 align: int (optional)
6610 required alignment for requests in bytes, must be positive power
6611 of 2, or 0 for default
6612 max-transfer: int (optional)
6614 maximum size for I/O transfers in bytes, must be positive multi‐
6615 ple of align and of the underlying file's request alignment (but
6616 need not be a power of 2), or 0 for default (since 2.10)
6617 opt-write-zero: int (optional)
6619 preferred alignment for write zero requests in bytes, must be
6620 positive multiple of align and of the underlying file's request
6621 alignment (but need not be a power of 2), or 0 for default
6622 (since 2.10)
6623 max-write-zero: int (optional)
6625 maximum size for write zero requests in bytes, must be positive
6626 multiple of align, of opt-write-zero, and of the underlying
6627 file's request alignment (but need not be a power of 2), or 0
6628 for default (since 2.10)
6629 opt-discard: int (optional)
6631 preferred alignment for discard requests in bytes, must be posi‐
6632 tive multiple of align and of the underlying file's request
6633 alignment (but need not be a power of 2), or 0 for default
6634 (since 2.10)
6635 max-discard: int (optional)
6637 maximum size for discard requests in bytes, must be positive
6638 multiple of align, of opt-discard, and of the underlying file's
6639 request alignment (but need not be a power of 2), or 0 for de‐
6640 fault (since 2.10)
6641 inject-error: array of BlkdebugInjectErrorOptions (optional)
6643 array of error injection descriptions
6644 set-state: array of BlkdebugSetStateOptions (optional)
6646 array of state-change descriptions
6647 take-child-perms: array of BlockPermission (optional)
6649 Permissions to take on image in addition to what is necessary
6650 anyway (which depends on how the blkdebug node is used). De‐
6651 faults to none. (since 5.0)
6652 unshare-child-perms: array of BlockPermission (optional)
6654 Permissions not to share on image in addition to what cannot be
6655 shared anyway (which depends on how the blkdebug node is used).
6656 Defaults to none. (since 5.0)
6657 Since
6659 2.9
6660 BlockdevOptionsBlklogwrites (Object)
6662 Driver specific block device options for blklogwrites.
6663 Members
6665 file: BlockdevRef
6666 block device
6667 log: BlockdevRef
6669 block device used to log writes to file
6670 log-sector-size: int (optional)
6672 sector size used in logging writes to file, determines granular‐
6673 ity of offsets and sizes of writes (default: 512)
6674 log-append: boolean (optional)
6676 append to an existing log (default: false)
6677 log-super-update-interval: int (optional)
6679 interval of write requests after which the log super block is
6680 updated to disk (default: 4096)
6681 Since
6683 3.0
6684 BlockdevOptionsBlkverify (Object)
6686 Driver specific block device options for blkverify.
6687 Members
6689 test: BlockdevRef
6690 block device to be tested
6691 raw: BlockdevRef
6693 raw image used for verification
6694 Since
6696 2.9
6697 BlockdevOptionsBlkreplay (Object)
6699 Driver specific block device options for blkreplay.
6700 Members
6702 image: BlockdevRef
6703 disk image which should be controlled with blkreplay
6704 Since
6706 4.2
6707 QuorumReadPattern (Enum)
6709 An enumeration of quorum read patterns.
6710 Values
6712 quorum read all the children and do a quorum vote on reads
6713 fifo read only from the first child that has not failed
6715 Since
6717 2.9
6718 BlockdevOptionsQuorum (Object)
6720 Driver specific block device options for Quorum
6721 Members
6723 blkverify: boolean (optional)
6724 true if the driver must print content mismatch
6726 set to false by default
6727 children: array of BlockdevRef
6729 the children block devices to use
6730 vote-threshold: int
6732 the vote limit under which a read will fail
6733 rewrite-corrupted: boolean (optional)
6735 rewrite corrupted data when quorum is reached (Since 2.1)
6736 read-pattern: QuorumReadPattern (optional)
6738 choose read pattern and set to quorum by default (Since 2.2)
6739 Since
6741 2.9
6742 BlockdevOptionsGluster (Object)
6744 Driver specific block device options for Gluster
6745 Members
6747 volume: string
6748 name of gluster volume where VM image resides
6749 path: string
6751 absolute path to image file in gluster volume
6752 server: array of SocketAddress
6754 gluster servers description
6755 debug: int (optional)
6757 libgfapi log level (default '4' which is Error) (Since 2.8)
6758 logfile: string (optional)
6760 libgfapi log file (default /dev/stderr) (Since 2.8)
6761 Since
6763 2.9
6764 IscsiTransport (Enum)
6766 An enumeration of libiscsi transport types
6767 Values
6769 tcp Not documented
6770 iser Not documented
6772 Since
6774 2.9
6775 IscsiHeaderDigest (Enum)
6777 An enumeration of header digests supported by libiscsi
6778 Values
6780 crc32c Not documented
6781 none Not documented
6783 crc32c-none
6785 Not documented
6786 none-crc32c
6788 Not documented
6789 Since
6791 2.9
6792 BlockdevOptionsIscsi (Object)
6794 Members
6795 transport: IscsiTransport
6796 The iscsi transport type
6797 portal: string
6799 The address of the iscsi portal
6800 target: string
6802 The target iqn name
6803 lun: int (optional)
6805 LUN to connect to. Defaults to 0.
6806 user: string (optional)
6808 User name to log in with. If omitted, no CHAP authentication is
6809 performed.
6810 password-secret: string (optional)
6812 The ID of a QCryptoSecret object providing the password for the
6813 login. This option is required if user is specified.
6814 initiator-name: string (optional)
6816 The iqn name we want to identify to the target as. If this op‐
6817 tion is not specified, an initiator name is generated automati‐
6818 cally.
6819 header-digest: IscsiHeaderDigest (optional)
6821 The desired header digest. Defaults to none-crc32c.
6822 timeout: int (optional)
6824 Timeout in seconds after which a request will timeout. 0 means
6825 no timeout and is the default.
6826 Driver specific block device options for iscsi
6827 Since
6829 2.9
6830 RbdAuthMode (Enum)
6832 Values
6833 cephx Not documented
6834 none Not documented
6836 Since
6838 3.0
6839 RbdImageEncryptionFormat (Enum)
6841 Values
6842 luks Not documented
6843 luks2 Not documented
6845 Since
6847 6.1
6848 RbdEncryptionOptionsLUKSBase (Object)
6850 Members
6851 key-secret: string
6852 ID of a QCryptoSecret object providing a passphrase for unlock‐
6853 ing the encryption
6854 Since
6856 6.1
6857 RbdEncryptionCreateOptionsLUKSBase (Object)
6859 Members
6860 cipher-alg: QCryptoCipherAlgorithm (optional)
6861 The encryption algorithm
6862 The members of RbdEncryptionOptionsLUKSBase
6864 Since
6866 6.1
6867 RbdEncryptionOptionsLUKS (Object)
6869 Members
6870 The members of RbdEncryptionOptionsLUKSBase
6871 Since
6873 6.1
6874 RbdEncryptionOptionsLUKS2 (Object)
6876 Members
6877 The members of RbdEncryptionOptionsLUKSBase
6878 Since
6880 6.1
6881 RbdEncryptionCreateOptionsLUKS (Object)
6883 Members
6884 The members of RbdEncryptionCreateOptionsLUKSBase
6885 Since
6887 6.1
6888 RbdEncryptionCreateOptionsLUKS2 (Object)
6890 Members
6891 The members of RbdEncryptionCreateOptionsLUKSBase
6892 Since
6894 6.1
6895 RbdEncryptionOptions (Object)
6897 Members
6898 format: RbdImageEncryptionFormat
6899 Not documented
6900 The members of RbdEncryptionOptionsLUKS when format is "luks"
6902 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
6904 Since
6906 6.1
6907 RbdEncryptionCreateOptions (Object)
6909 Members
6910 format: RbdImageEncryptionFormat
6911 Not documented
6912 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
6914 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
6916 Since
6918 6.1
6919 BlockdevOptionsRbd (Object)
6921 Members
6922 pool: string
6923 Ceph pool name.
6924 namespace: string (optional)
6926 Rados namespace name in the Ceph pool. (Since 5.0)
6927 image: string
6929 Image name in the Ceph pool.
6930 conf: string (optional)
6932 path to Ceph configuration file. Values in the configuration
6933 file will be overridden by options specified via QAPI.
6934 snapshot: string (optional)
6936 Ceph snapshot name.
6937 encrypt: RbdEncryptionOptions (optional)
6939 Image encryption options. (Since 6.1)
6940 user: string (optional)
6942 Ceph id name.
6943 auth-client-required: array of RbdAuthMode (optional)
6945 Acceptable authentication modes. This maps to Ceph configura‐
6946 tion option "auth_client_required". (Since 3.0)
6947 key-secret: string (optional)
6949 ID of a QCryptoSecret object providing a key for cephx authenti‐
6950 cation. This maps to Ceph configuration option "key". (Since
6951 3.0)
6952 server: array of InetSocketAddressBase (optional)
6954 Monitor host address and port. This maps to the "mon_host" Ceph
6955 option.
6956 Since
6958 2.9
6959 ReplicationMode (Enum)
6961 An enumeration of replication modes.
6962 Values
6964 primary
6965 Primary mode, the vm's state will be sent to secondary QEMU.
6966 secondary
6968 Secondary mode, receive the vm's state from primary QEMU.
6969 Since
6971 2.9
6972 If
6974 CONFIG_REPLICATION
6975 BlockdevOptionsReplication (Object)
6977 Driver specific block device options for replication
6978 Members
6980 mode: ReplicationMode
6981 the replication mode
6982 top-id: string (optional)
6984 In secondary mode, node name or device ID of the root node who
6985 owns the replication node chain. Must not be given in primary
6986 mode.
6987 The members of BlockdevOptionsGenericFormat
6989 Since
6991 2.9
6992 If
6994 CONFIG_REPLICATION
6995 NFSTransport (Enum)
6997 An enumeration of NFS transport types
6998 Values
7000 inet TCP transport
7001 Since
7003 2.9
7004 NFSServer (Object)
7006 Captures the address of the socket
7007 Members
7009 type: NFSTransport
7010 transport type used for NFS (only TCP supported)
7011 host: string
7013 host address for NFS server
7014 Since
7016 2.9
7017 BlockdevOptionsNfs (Object)
7019 Driver specific block device option for NFS
7020 Members
7022 server: NFSServer
7023 host address
7024 path: string
7026 path of the image on the host
7027 user: int (optional)
7029 UID value to use when talking to the server (defaults to 65534
7030 on Windows and getuid() on unix)
7031 group: int (optional)
7033 GID value to use when talking to the server (defaults to 65534
7034 on Windows and getgid() in unix)
7035 tcp-syn-count: int (optional)
7037 number of SYNs during the session establishment (defaults to
7038 libnfs default)
7039 readahead-size: int (optional)
7041 set the readahead size in bytes (defaults to libnfs default)
7042 page-cache-size: int (optional)
7044 set the pagecache size in bytes (defaults to libnfs default)
7045 debug: int (optional)
7047 set the NFS debug level (max 2) (defaults to libnfs default)
7048 Since
7050 2.9
7051 BlockdevOptionsCurlBase (Object)
7053 Driver specific block device options shared by all protocols supported
7054 by the curl backend.
7055 Members
7057 url: string
7058 URL of the image file
7059 readahead: int (optional)
7061 Size of the read-ahead cache; must be a multiple of 512 (de‐
7062 faults to 256 kB)
7063 timeout: int (optional)
7065 Timeout for connections, in seconds (defaults to 5)
7066 username: string (optional)
7068 Username for authentication (defaults to none)
7069 password-secret: string (optional)
7071 ID of a QCryptoSecret object providing a password for authenti‐
7072 cation (defaults to no password)
7073 proxy-username: string (optional)
7075 Username for proxy authentication (defaults to none)
7076 proxy-password-secret: string (optional)
7078 ID of a QCryptoSecret object providing a password for proxy au‐
7079 thentication (defaults to no password)
7080 Since
7082 2.9
7083 BlockdevOptionsCurlHttp (Object)
7085 Driver specific block device options for HTTP connections over the curl
7086 backend. URLs must start with "http://".
7087 Members
7089 cookie: string (optional)
7090 List of cookies to set; format is "name1=content1; name2=con‐
7091 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
7092 ies.
7093 cookie-secret: string (optional)
7095 ID of a QCryptoSecret object providing the cookie data in a se‐
7096 cure way. See cookie for the format. (since 2.10)
7097 The members of BlockdevOptionsCurlBase
7099 Since
7101 2.9
7102 BlockdevOptionsCurlHttps (Object)
7104 Driver specific block device options for HTTPS connections over the
7105 curl backend. URLs must start with "https://".
7106 Members
7108 cookie: string (optional)
7109 List of cookies to set; format is "name1=content1; name2=con‐
7110 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
7111 ies.
7112 sslverify: boolean (optional)
7114 Whether to verify the SSL certificate's validity (defaults to
7115 true)
7116 cookie-secret: string (optional)
7118 ID of a QCryptoSecret object providing the cookie data in a se‐
7119 cure way. See cookie for the format. (since 2.10)
7120 The members of BlockdevOptionsCurlBase
7122 Since
7124 2.9
7125 BlockdevOptionsCurlFtp (Object)
7127 Driver specific block device options for FTP connections over the curl
7128 backend. URLs must start with "ftp://".
7129 Members
7131 The members of BlockdevOptionsCurlBase
7132 Since
7134 2.9
7135 BlockdevOptionsCurlFtps (Object)
7137 Driver specific block device options for FTPS connections over the curl
7138 backend. URLs must start with "ftps://".
7139 Members
7141 sslverify: boolean (optional)
7142 Whether to verify the SSL certificate's validity (defaults to
7143 true)
7144 The members of BlockdevOptionsCurlBase
7146 Since
7148 2.9
7149 BlockdevOptionsNbd (Object)
7151 Driver specific block device options for NBD.
7152 Members
7154 server: SocketAddress
7155 NBD server address
7156 export: string (optional)
7158 export name
7159 tls-creds: string (optional)
7161 TLS credentials ID
7162 x-dirty-bitmap: string (optional)
7164 A metadata context name such as "qemu:dirty-bitmap:NAME" or
7165 "qemu:allocation-depth" to query in place of the traditional
7166 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
7167 the NBD protocol; and yes, naming this option x-context would
7168 have made more sense) (since 3.0)
7169 reconnect-delay: int (optional)
7171 On an unexpected disconnect, the nbd client tries to connect
7172 again until succeeding or encountering a serious error. During
7173 the first reconnect-delay seconds, all requests are paused and
7174 will be rerun on a successful reconnect. After that time, any
7175 delayed requests and all future requests before a successful re‐
7176 connect will immediately fail. Default 0 (Since 4.2)
7177 Features
7179 unstable
7180 Member x-dirty-bitmap is experimental.
7181 Since
7183 2.9
7184 BlockdevOptionsRaw (Object)
7186 Driver specific block device options for the raw driver.
7187 Members
7189 offset: int (optional)
7190 position where the block device starts
7191 size: int (optional)
7193 the assumed size of the device
7194 The members of BlockdevOptionsGenericFormat
7196 Since
7198 2.9
7199 BlockdevOptionsThrottle (Object)
7201 Driver specific block device options for the throttle driver
7202 Members
7204 throttle-group: string
7205 the name of the throttle-group object to use. It must already
7206 exist.
7207 file: BlockdevRef
7209 reference to or definition of the data source block device
7210 Since
7212 2.11
7213 BlockdevOptionsCor (Object)
7215 Driver specific block device options for the copy-on-read driver.
7216 Members
7218 bottom: string (optional)
7219 The name of a non-filter node (allocation-bearing layer) that
7220 limits the COR operations in the backing chain (inclusive), so
7221 that no data below this node will be copied by this filter. If
7222 option is absent, the limit is not applied, so that data from
7223 all backing layers may be copied.
7224 The members of BlockdevOptionsGenericFormat
7226 Since
7228 6.0
7229 BlockdevOptionsCbw (Object)
7231 Driver specific block device options for the copy-before-write driver,
7232 which does so called copy-before-write operations: when data is written
7233 to the filter, the filter first reads corresponding blocks from its
7234 file child and copies them to target child. After successfully copying,
7235 the write request is propagated to file child. If copying fails, the
7236 original write request is failed too and no data is written to file
7237 child.
7238 Members
7240 target: BlockdevRef
7241 The target for copy-before-write operations.
7242 The members of BlockdevOptionsGenericFormat
7244 Since
7246 6.2
7247 BlockdevOptions (Object)
7249 Options for creating a block device. Many options are available for
7250 all block devices, independent of the block driver:
7251 Members
7253 driver: BlockdevDriver
7254 block driver name
7255 node-name: string (optional)
7257 the node name of the new node (Since 2.0). This option is re‐
7258 quired on the top level of blockdev-add. Valid node names start
7259 with an alphabetic character and may contain only alphanumeric
7260 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
7261 ters.
7262 discard: BlockdevDiscardOptions (optional)
7264 discard-related options (default: ignore)
7265 cache: BlockdevCacheOptions (optional)
7267 cache-related options
7268 read-only: boolean (optional)
7270 whether the block device should be read-only (default: false).
7271 Note that some block drivers support only read-only access, ei‐
7272 ther generally or in certain configurations. In this case, the
7273 default value does not work and the option must be specified ex‐
7274 plicitly.
7275 auto-read-only: boolean (optional)
7277 if true and read-only is false, QEMU may automatically decide
7278 not to open the image read-write as requested, but fall back to
7279 read-only instead (and switch between the modes later), e.g. de‐
7280 pending on whether the image file is writable or whether a writ‐
7281 ing user is attached to the node (default: false, since 3.1)
7282 detect-zeroes: BlockdevDetectZeroesOptions (optional)
7284 detect and optimize zero writes (Since 2.1) (default: off)
7285 force-share: boolean (optional)
7287 force share all permission on added nodes. Requires
7288 read-only=true. (Since 2.10)
7289 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
7291 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
7293 writes"
7294 The members of BlockdevOptionsBlkverify when driver is "blkverify"
7296 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
7298 The members of BlockdevOptionsGenericFormat when driver is "bochs"
7300 The members of BlockdevOptionsGenericFormat when driver is "cloop"
7302 The members of BlockdevOptionsGenericFormat when driver is "compress"
7304 The members of BlockdevOptionsCbw when driver is "copy-before-write"
7306 The members of BlockdevOptionsCor when driver is "copy-on-read"
7308 The members of BlockdevOptionsGenericFormat when driver is "dmg"
7310 The members of BlockdevOptionsFile when driver is "file"
7312 The members of BlockdevOptionsCurlFtp when driver is "ftp"
7314 The members of BlockdevOptionsCurlFtps when driver is "ftps"
7316 The members of BlockdevOptionsGluster when driver is "gluster"
7318 The members of BlockdevOptionsFile when driver is "host_cdrom" (If:
7320 HAVE_HOST_BLOCK_DEVICE)
7321 The members of BlockdevOptionsFile when driver is "host_device" (If:
7323 HAVE_HOST_BLOCK_DEVICE)
7324 The members of BlockdevOptionsCurlHttp when driver is "http"
7326 The members of BlockdevOptionsCurlHttps when driver is "https"
7328 The members of BlockdevOptionsIscsi when driver is "iscsi"
7330 The members of BlockdevOptionsLUKS when driver is "luks"
7332 The members of BlockdevOptionsNbd when driver is "nbd"
7334 The members of BlockdevOptionsNfs when driver is "nfs"
7336 The members of BlockdevOptionsNull when driver is "null-aio"
7338 The members of BlockdevOptionsNull when driver is "null-co"
7340 The members of BlockdevOptionsNVMe when driver is "nvme"
7342 The members of BlockdevOptionsGenericFormat when driver is "parallels"
7344 The members of BlockdevOptionsPreallocate when driver is "preallocate"
7346 The members of BlockdevOptionsQcow2 when driver is "qcow2"
7348 The members of BlockdevOptionsQcow when driver is "qcow"
7350 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
7352 The members of BlockdevOptionsQuorum when driver is "quorum"
7354 The members of BlockdevOptionsRaw when driver is "raw"
7356 The members of BlockdevOptionsRbd when driver is "rbd"
7358 The members of BlockdevOptionsReplication when driver is "replication"
7360 (If: CONFIG_REPLICATION)
7361 The members of BlockdevOptionsSsh when driver is "ssh"
7363 The members of BlockdevOptionsThrottle when driver is "throttle"
7365 The members of BlockdevOptionsGenericFormat when driver is "vdi"
7367 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
7369 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
7371 The members of BlockdevOptionsGenericFormat when driver is "vpc"
7373 The members of BlockdevOptionsVVFAT when driver is "vvfat"
7375 Remaining options are determined by the block driver.
7376 Since
7378 2.9
7379 BlockdevRef (Alternate)
7381 Reference to a block device.
7382 Members
7384 definition: BlockdevOptions
7385 defines a new block device inline
7386 reference: string
7388 references the ID of an existing block device
7389 Since
7391 2.9
7392 BlockdevRefOrNull (Alternate)
7394 Reference to a block device.
7395 Members
7397 definition: BlockdevOptions
7398 defines a new block device inline
7399 reference: string
7401 references the ID of an existing block device. An empty string
7402 means that no block device should be referenced. Deprecated;
7403 use null instead.
7404 null: null
7406 No block device should be referenced (since 2.10)
7407 Since
7409 2.9
7410 blockdev-add (Command)
7412 Creates a new block device.
7413 Arguments
7415 The members of BlockdevOptions
7416 Since
7418 2.9
7419 Example
7421 1.
7422 -> { "execute": "blockdev-add",
7423 "arguments": {
7424 "driver": "qcow2",
7425 "node-name": "test1",
7426 "file": {
7427 "driver": "file",
7428 "filename": "test.qcow2"
7429 }
7430 }
7431 }
7432 <- { "return": {} }
7433 2.
7435 -> { "execute": "blockdev-add",
7436 "arguments": {
7437 "driver": "qcow2",
7438 "node-name": "node0",
7439 "discard": "unmap",
7440 "cache": {
7441 "direct": true
7442 },
7443 "file": {
7444 "driver": "file",
7445 "filename": "/tmp/test.qcow2"
7446 },
7447 "backing": {
7448 "driver": "raw",
7449 "file": {
7450 "driver": "file",
7451 "filename": "/dev/fdset/4"
7452 }
7453 }
7454 }
7455 }
7456 <- { "return": {} }
7458 blockdev-reopen (Command)
7460 Reopens one or more block devices using the given set of options. Any
7461 option not specified will be reset to its default value regardless of
7462 its previous status. If an option cannot be changed or a particular
7463 driver does not support reopening then the command will return an er‐
7464 ror. All devices in the list are reopened in one transaction, so if one
7465 of them fails then the whole transaction is cancelled.
7466 The command receives a list of block devices to reopen. For each one of
7468 them, the top-level node-name option (from BlockdevOptions) must be
7469 specified and is used to select the block device to be reopened. Other
7470 node-name options must be either omitted or set to the current name of
7471 the appropriate node. This command won't change any node name and any
7472 attempt to do it will result in an error.
7473 In the case of options that refer to child nodes, the behavior of this
7475 command depends on the value:
7476 1. A set of options (BlockdevOptions): the child is reopened with
7478 the specified set of options.
7479 2. A reference to the current child: the child is reopened using its
7481 existing set of options.
7482 3. A reference to a different node: the current child is replaced
7484 with the specified one.
7485 4. NULL: the current child (if any) is detached.
7487 Options (1) and (2) are supported in all cases. Option (3) is supported
7489 for file and backing, and option (4) for backing only.
7490 Unlike with blockdev-add, the backing option must always be present un‐
7492 less the node being reopened does not have a backing file and its image
7493 does not have a default backing file name as part of its metadata.
7494 Arguments
7496 options: array of BlockdevOptions
7497 Not documented
7498 Since
7500 6.1
7501 blockdev-del (Command)
7503 Deletes a block device that has been added using blockdev-add. The
7504 command will fail if the node is attached to a device or is otherwise
7505 being used.
7506 Arguments
7508 node-name: string
7509 Name of the graph node to delete.
7510 Since
7512 2.9
7513 Example
7515 -> { "execute": "blockdev-add",
7516 "arguments": {
7517 "driver": "qcow2",
7518 "node-name": "node0",
7519 "file": {
7520 "driver": "file",
7521 "filename": "test.qcow2"
7522 }
7523 }
7524 }
7525 <- { "return": {} }
7526 -> { "execute": "blockdev-del",
7528 "arguments": { "node-name": "node0" }
7529 }
7530 <- { "return": {} }
7531 BlockdevCreateOptionsFile (Object)
7533 Driver specific image creation options for file.
7534 Members
7536 filename: string
7537 Filename for the new image file
7538 size: int
7540 Size of the virtual disk in bytes
7541 preallocation: PreallocMode (optional)
7543 Preallocation mode for the new image (default: off; allowed val‐
7544 ues: off, falloc (if CONFIG_POSIX_FALLOCATE), full (if CON‐
7545 FIG_POSIX))
7546 nocow: boolean (optional)
7548 Turn off copy-on-write (valid only on btrfs; default: off)
7549 extent-size-hint: int (optional)
7551 Extent size hint to add to the image file; 0 for not adding an
7552 extent size hint (default: 1 MB, since 5.1)
7553 Since
7555 2.12
7556 BlockdevCreateOptionsGluster (Object)
7558 Driver specific image creation options for gluster.
7559 Members
7561 location: BlockdevOptionsGluster
7562 Where to store the new image file
7563 size: int
7565 Size of the virtual disk in bytes
7566 preallocation: PreallocMode (optional)
7568 Preallocation mode for the new image (default: off; allowed val‐
7569 ues: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), full (if CON‐
7570 FIG_GLUSTERFS_ZEROFILL))
7571 Since
7573 2.12
7574 BlockdevCreateOptionsLUKS (Object)
7576 Driver specific image creation options for LUKS.
7577 Members
7579 file: BlockdevRef
7580 Node to create the image format on
7581 size: int
7583 Size of the virtual disk in bytes
7584 preallocation: PreallocMode (optional)
7586 Preallocation mode for the new image (since: 4.2) (default: off;
7587 allowed values: off, metadata, falloc, full)
7588 The members of QCryptoBlockCreateOptionsLUKS
7590 Since
7592 2.12
7593 BlockdevCreateOptionsNfs (Object)
7595 Driver specific image creation options for NFS.
7596 Members
7598 location: BlockdevOptionsNfs
7599 Where to store the new image file
7600 size: int
7602 Size of the virtual disk in bytes
7603 Since
7605 2.12
7606 BlockdevCreateOptionsParallels (Object)
7608 Driver specific image creation options for parallels.
7609 Members
7611 file: BlockdevRef
7612 Node to create the image format on
7613 size: int
7615 Size of the virtual disk in bytes
7616 cluster-size: int (optional)
7618 Cluster size in bytes (default: 1 MB)
7619 Since
7621 2.12
7622 BlockdevCreateOptionsQcow (Object)
7624 Driver specific image creation options for qcow.
7625 Members
7627 file: BlockdevRef
7628 Node to create the image format on
7629 size: int
7631 Size of the virtual disk in bytes
7632 backing-file: string (optional)
7634 File name of the backing file if a backing file should be used
7635 encrypt: QCryptoBlockCreateOptions (optional)
7637 Encryption options if the image should be encrypted
7638 Since
7640 2.12
7641 BlockdevQcow2Version (Enum)
7643 Values
7644 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
7645 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
7647 Since
7649 2.12
7650 Qcow2CompressionType (Enum)
7652 Compression type used in qcow2 image file
7653 Values
7655 zlib zlib compression, see <http://zlib.net/>
7656 zstd (If: CONFIG_ZSTD)
7658 zstd compression, see <http://github.com/facebook/zstd>
7659 Since
7661 5.1
7662 BlockdevCreateOptionsQcow2 (Object)
7664 Driver specific image creation options for qcow2.
7665 Members
7667 file: BlockdevRef
7668 Node to create the image format on
7669 data-file: BlockdevRef (optional)
7671 Node to use as an external data file in which all guest data is
7672 stored so that only metadata remains in the qcow2 file (since:
7673 4.0)
7674 data-file-raw: boolean (optional)
7676 True if the external data file must stay valid as a standalone
7677 (read-only) raw image without looking at qcow2 metadata (de‐
7678 fault: false; since: 4.0)
7679 extended-l2: boolean (optional)
7681 True to make the image have extended L2 entries (default: false;
7682 since 5.2)
7683 size: int
7685 Size of the virtual disk in bytes
7686 version: BlockdevQcow2Version (optional)
7688 Compatibility level (default: v3)
7689 backing-file: string (optional)
7691 File name of the backing file if a backing file should be used
7692 backing-fmt: BlockdevDriver (optional)
7694 Name of the block driver to use for the backing file
7695 encrypt: QCryptoBlockCreateOptions (optional)
7697 Encryption options if the image should be encrypted
7698 cluster-size: int (optional)
7700 qcow2 cluster size in bytes (default: 65536)
7701 preallocation: PreallocMode (optional)
7703 Preallocation mode for the new image (default: off; allowed val‐
7704 ues: off, falloc, full, metadata)
7705 lazy-refcounts: boolean (optional)
7707 True if refcounts may be updated lazily (default: off)
7708 refcount-bits: int (optional)
7710 Width of reference counts in bits (default: 16)
7711 compression-type: Qcow2CompressionType (optional)
7713 The image cluster compression method (default: zlib, since 5.1)
7714 Since
7716 2.12
7717 BlockdevCreateOptionsQed (Object)
7719 Driver specific image creation options for qed.
7720 Members
7722 file: BlockdevRef
7723 Node to create the image format on
7724 size: int
7726 Size of the virtual disk in bytes
7727 backing-file: string (optional)
7729 File name of the backing file if a backing file should be used
7730 backing-fmt: BlockdevDriver (optional)
7732 Name of the block driver to use for the backing file
7733 cluster-size: int (optional)
7735 Cluster size in bytes (default: 65536)
7736 table-size: int (optional)
7738 L1/L2 table size (in clusters)
7739 Since
7741 2.12
7742 BlockdevCreateOptionsRbd (Object)
7744 Driver specific image creation options for rbd/Ceph.
7745 Members
7747 location: BlockdevOptionsRbd
7748 Where to store the new image file. This location cannot point to
7749 a snapshot.
7750 size: int
7752 Size of the virtual disk in bytes
7753 cluster-size: int (optional)
7755 RBD object size
7756 encrypt: RbdEncryptionCreateOptions (optional)
7758 Image encryption options. (Since 6.1)
7759 Since
7761 2.12
7762 BlockdevVmdkSubformat (Enum)
7764 Subformat options for VMDK images
7765 Values
7767 monolithicSparse
7768 Single file image with sparse cluster allocation
7769 monolithicFlat
7771 Single flat data image and a descriptor file
7772 twoGbMaxExtentSparse
7774 Data is split into 2GB (per virtual LBA) sparse extent files, in
7775 addition to a descriptor file
7776 twoGbMaxExtentFlat
7778 Data is split into 2GB (per virtual LBA) flat extent files, in
7779 addition to a descriptor file
7780 streamOptimized
7782 Single file image sparse cluster allocation, optimized for
7783 streaming over network.
7784 Since
7786 4.0
7787 BlockdevVmdkAdapterType (Enum)
7789 Adapter type info for VMDK images
7790 Values
7792 ide Not documented
7793 buslogic
7795 Not documented
7796 lsilogic
7798 Not documented
7799 legacyESX
7801 Not documented
7802 Since
7804 4.0
7805 BlockdevCreateOptionsVmdk (Object)
7807 Driver specific image creation options for VMDK.
7808 Members
7810 file: BlockdevRef
7811 Where to store the new image file. This refers to the image file
7812 for monolithcSparse and streamOptimized format, or the descrip‐
7813 tor file for other formats.
7814 size: int
7816 Size of the virtual disk in bytes
7817 extents: array of BlockdevRef (optional)
7819 Where to store the data extents. Required for monolithcFlat,
7820 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
7821 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
7822 mats, the number of entries required is calculated as ex‐
7823 tent_number = virtual_size / 2GB. Providing more extents than
7824 will be used is an error.
7825 subformat: BlockdevVmdkSubformat (optional)
7827 The subformat of the VMDK image. Default: "monolithicSparse".
7828 backing-file: string (optional)
7830 The path of backing file. Default: no backing file is used.
7831 adapter-type: BlockdevVmdkAdapterType (optional)
7833 The adapter type used to fill in the descriptor. Default: ide.
7834 hwversion: string (optional)
7836 Hardware version. The meaningful options are "4" or "6". De‐
7837 fault: "4".
7838 toolsversion: string (optional)
7840 VMware guest tools version. Default: "2147483647" (Since 6.2)
7841 zeroed-grain: boolean (optional)
7843 Whether to enable zeroed-grain feature for sparse subformats.
7844 Default: false.
7845 Since
7847 4.0
7848 BlockdevCreateOptionsSsh (Object)
7850 Driver specific image creation options for SSH.
7851 Members
7853 location: BlockdevOptionsSsh
7854 Where to store the new image file
7855 size: int
7857 Size of the virtual disk in bytes
7858 Since
7860 2.12
7861 BlockdevCreateOptionsVdi (Object)
7863 Driver specific image creation options for VDI.
7864 Members
7866 file: BlockdevRef
7867 Node to create the image format on
7868 size: int
7870 Size of the virtual disk in bytes
7871 preallocation: PreallocMode (optional)
7873 Preallocation mode for the new image (default: off; allowed val‐
7874 ues: off, metadata)
7875 Since
7877 2.12
7878 BlockdevVhdxSubformat (Enum)
7880 Values
7881 dynamic
7882 Growing image file
7883 fixed Preallocated fixed-size image file
7885 Since
7887 2.12
7888 BlockdevCreateOptionsVhdx (Object)
7890 Driver specific image creation options for vhdx.
7891 Members
7893 file: BlockdevRef
7894 Node to create the image format on
7895 size: int
7897 Size of the virtual disk in bytes
7898 log-size: int (optional)
7900 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
7901 block-size: int (optional)
7903 Block size in bytes, must be a multiple of 1 MB and not larger
7904 than 256 MB (default: automatically choose a block size depend‐
7905 ing on the image size)
7906 subformat: BlockdevVhdxSubformat (optional)
7908 vhdx subformat (default: dynamic)
7909 block-state-zero: boolean (optional)
7911 Force use of payload blocks of type 'ZERO'. Non-standard, but
7912 default. Do not set to 'off' when using 'qemu-img convert' with
7913 subformat=dynamic.
7914 Since
7916 2.12
7917 BlockdevVpcSubformat (Enum)
7919 Values
7920 dynamic
7921 Growing image file
7922 fixed Preallocated fixed-size image file
7924 Since
7926 2.12
7927 BlockdevCreateOptionsVpc (Object)
7929 Driver specific image creation options for vpc (VHD).
7930 Members
7932 file: BlockdevRef
7933 Node to create the image format on
7934 size: int
7936 Size of the virtual disk in bytes
7937 subformat: BlockdevVpcSubformat (optional)
7939 vhdx subformat (default: dynamic)
7940 force-size: boolean (optional)
7942 Force use of the exact byte size instead of rounding to the next
7943 size that can be represented in CHS geometry (default: false)
7944 Since
7946 2.12
7947 BlockdevCreateOptions (Object)
7949 Options for creating an image format on a given node.
7950 Members
7952 driver: BlockdevDriver
7953 block driver to create the image format
7954 The members of BlockdevCreateOptionsFile when driver is "file"
7956 The members of BlockdevCreateOptionsGluster when driver is "gluster"
7958 The members of BlockdevCreateOptionsLUKS when driver is "luks"
7960 The members of BlockdevCreateOptionsNfs when driver is "nfs"
7962 The members of BlockdevCreateOptionsParallels when driver is "paral‐
7964 lels"
7965 The members of BlockdevCreateOptionsQcow when driver is "qcow"
7967 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
7969 The members of BlockdevCreateOptionsQed when driver is "qed"
7971 The members of BlockdevCreateOptionsRbd when driver is "rbd"
7973 The members of BlockdevCreateOptionsSsh when driver is "ssh"
7975 The members of BlockdevCreateOptionsVdi when driver is "vdi"
7977 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
7979 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
7981 The members of BlockdevCreateOptionsVpc when driver is "vpc"
7983 Since
7985 2.12
7986 blockdev-create (Command)
7988 Starts a job to create an image format on a given node. The job is au‐
7989 tomatically finalized, but a manual job-dismiss is required.
7990 Arguments
7992 job-id: string
7993 Identifier for the newly created job.
7994 options: BlockdevCreateOptions
7996 Options for the image creation.
7997 Since
7999 3.0
8000 BlockdevAmendOptionsLUKS (Object)
8002 Driver specific image amend options for LUKS.
8003 Members
8005 The members of QCryptoBlockAmendOptionsLUKS
8006 Since
8008 5.1
8009 BlockdevAmendOptionsQcow2 (Object)
8011 Driver specific image amend options for qcow2. For now, only encryp‐
8012 tion options can be amended
8013 encrypt Encryption options to be amended
8015 Members
8017 encrypt: QCryptoBlockAmendOptions (optional)
8018 Not documented
8019 Since
8021 5.1
8022 BlockdevAmendOptions (Object)
8024 Options for amending an image format
8025 Members
8027 driver: BlockdevDriver
8028 Block driver of the node to amend.
8029 The members of BlockdevAmendOptionsLUKS when driver is "luks"
8031 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
8033 Since
8035 5.1
8036 x-blockdev-amend (Command)
8038 Starts a job to amend format specific options of an existing open block
8039 device The job is automatically finalized, but a manual job-dismiss is
8040 required.
8041 Arguments
8043 job-id: string
8044 Identifier for the newly created job.
8045 node-name: string
8047 Name of the block node to work on
8048 options: BlockdevAmendOptions
8050 Options (driver specific)
8051 force: boolean (optional)
8053 Allow unsafe operations, format specific For luks that allows
8054 erase of the last active keyslot (permanent loss of data), and
8055 replacement of an active keyslot (possible loss of data if IO
8056 error happens)
8057 Features
8059 unstable
8060 This command is experimental.
8061 Since
8063 5.1
8064 BlockErrorAction (Enum)
8066 An enumeration of action that has been taken when a DISK I/O occurs
8067 Values
8069 ignore error has been ignored
8070 report error has been reported to the device
8072 stop error caused VM to be stopped
8074 Since
8076 2.1
8077 BLOCK_IMAGE_CORRUPTED (Event)
8079 Emitted when a disk image is being marked corrupt. The image can be
8080 identified by its device or node name. The 'device' field is always
8081 present for compatibility reasons, but it can be empty ("") if the im‐
8082 age does not have a device name associated.
8083 Arguments
8085 device: string
8086 device name. This is always present for compatibility reasons,
8087 but it can be empty ("") if the image does not have a device
8088 name associated.
8089 node-name: string (optional)
8091 node name (Since: 2.4)
8092 msg: string
8094 informative message for human consumption, such as the kind of
8095 corruption being detected. It should not be parsed by machine as
8096 it is not guaranteed to be stable
8097 offset: int (optional)
8099 if the corruption resulted from an image access, this is the
8100 host's access offset into the image
8101 size: int (optional)
8103 if the corruption resulted from an image access, this is the ac‐
8104 cess size
8105 fatal: boolean
8107 if set, the image is marked corrupt and therefore unusable after
8108 this event and must be repaired (Since 2.2; before, every
8109 BLOCK_IMAGE_CORRUPTED event was fatal)
8110 Note
8112 If action is "stop", a STOP event will eventually follow the
8113 BLOCK_IO_ERROR event.
8114 Example
8116 <- { "event": "BLOCK_IMAGE_CORRUPTED",
8117 "data": { "device": "ide0-hd0", "node-name": "node0",
8118 "msg": "Prevented active L1 table overwrite", "offset": 196608,
8119 "size": 65536 },
8120 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
8121 Since
8123 1.7
8124 BLOCK_IO_ERROR (Event)
8126 Emitted when a disk I/O error occurs
8127 Arguments
8129 device: string
8130 device name. This is always present for compatibility reasons,
8131 but it can be empty ("") if the image does not have a device
8132 name associated.
8133 node-name: string (optional)
8135 node name. Note that errors may be reported for the root node
8136 that is directly attached to a guest device rather than for the
8137 node where the error occurred. The node name is not present if
8138 the drive is empty. (Since: 2.8)
8139 operation: IoOperationType
8141 I/O operation
8142 action: BlockErrorAction
8144 action that has been taken
8145 nospace: boolean (optional)
8147 true if I/O error was caused due to a no-space condition. This
8148 key is only present if query-block's io-status is present,
8149 please see query-block documentation for more information
8150 (since: 2.2)
8151 reason: string
8153 human readable string describing the error cause. (This field
8154 is a debugging aid for humans, it should not be parsed by appli‐
8155 cations) (since: 2.2)
8156 Note
8158 If action is "stop", a STOP event will eventually follow the
8159 BLOCK_IO_ERROR event
8160 Since
8162 0.13
8163 Example
8165 <- { "event": "BLOCK_IO_ERROR",
8166 "data": { "device": "ide0-hd1",
8167 "node-name": "#block212",
8168 "operation": "write",
8169 "action": "stop" },
8170 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8171 BLOCK_JOB_COMPLETED (Event)
8173 Emitted when a block job has completed
8174 Arguments
8176 type: JobType
8177 job type
8178 device: string
8180 The job identifier. Originally the device name but other values
8181 are allowed since QEMU 2.7
8182 len: int
8184 maximum progress value
8185 offset: int
8187 current progress value. On success this is equal to len. On
8188 failure this is less than len
8189 speed: int
8191 rate limit, bytes per second
8192 error: string (optional)
8194 error message. Only present on failure. This field contains a
8195 human-readable error message. There are no semantics other than
8196 that streaming has failed and clients should not try to inter‐
8197 pret the error string
8198 Since
8200 1.1
8201 Example
8203 <- { "event": "BLOCK_JOB_COMPLETED",
8204 "data": { "type": "stream", "device": "virtio-disk0",
8205 "len": 10737418240, "offset": 10737418240,
8206 "speed": 0 },
8207 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
8208 BLOCK_JOB_CANCELLED (Event)
8210 Emitted when a block job has been cancelled
8211 Arguments
8213 type: JobType
8214 job type
8215 device: string
8217 The job identifier. Originally the device name but other values
8218 are allowed since QEMU 2.7
8219 len: int
8221 maximum progress value
8222 offset: int
8224 current progress value. On success this is equal to len. On
8225 failure this is less than len
8226 speed: int
8228 rate limit, bytes per second
8229 Since
8231 1.1
8232 Example
8234 <- { "event": "BLOCK_JOB_CANCELLED",
8235 "data": { "type": "stream", "device": "virtio-disk0",
8236 "len": 10737418240, "offset": 134217728,
8237 "speed": 0 },
8238 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
8239 BLOCK_JOB_ERROR (Event)
8241 Emitted when a block job encounters an error
8242 Arguments
8244 device: string
8245 The job identifier. Originally the device name but other values
8246 are allowed since QEMU 2.7
8247 operation: IoOperationType
8249 I/O operation
8250 action: BlockErrorAction
8252 action that has been taken
8253 Since
8255 1.3
8256 Example
8258 <- { "event": "BLOCK_JOB_ERROR",
8259 "data": { "device": "ide0-hd1",
8260 "operation": "write",
8261 "action": "stop" },
8262 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8263 BLOCK_JOB_READY (Event)
8265 Emitted when a block job is ready to complete
8266 Arguments
8268 type: JobType
8269 job type
8270 device: string
8272 The job identifier. Originally the device name but other values
8273 are allowed since QEMU 2.7
8274 len: int
8276 maximum progress value
8277 offset: int
8279 current progress value. On success this is equal to len. On
8280 failure this is less than len
8281 speed: int
8283 rate limit, bytes per second
8284 Note
8286 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
8287 event
8288 Since
8290 1.3
8291 Example
8293 <- { "event": "BLOCK_JOB_READY",
8294 "data": { "device": "drive0", "type": "mirror", "speed": 0,
8295 "len": 2097152, "offset": 2097152 }
8296 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8297 BLOCK_JOB_PENDING (Event)
8299 Emitted when a block job is awaiting explicit authorization to finalize
8300 graph changes via block-job-finalize. If this job is part of a transac‐
8301 tion, it will not emit this event until the transaction has converged
8302 first.
8303 Arguments
8305 type: JobType
8306 job type
8307 id: string
8309 The job identifier.
8310 Since
8312 2.12
8313 Example
8315 <- { "event": "BLOCK_JOB_WAITING",
8316 "data": { "device": "drive0", "type": "mirror" },
8317 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8318 PreallocMode (Enum)
8320 Preallocation mode of QEMU image file
8321 Values
8323 off no preallocation
8324 metadata
8326 preallocate only for metadata
8327 falloc like full preallocation but allocate disk space by posix_fallo‐
8329 cate() rather than writing data.
8330 full preallocate all data by writing it to the device to ensure disk
8332 space is really available. This data may or may not be zero, de‐
8333 pending on the image format and storage. full preallocation
8334 also sets up metadata correctly.
8335 Since
8337 2.2
8338 BLOCK_WRITE_THRESHOLD (Event)
8340 Emitted when writes on block device reaches or exceeds the configured
8341 write threshold. For thin-provisioned devices, this means the device
8342 should be extended to avoid pausing for disk exhaustion. The event is
8343 one shot. Once triggered, it needs to be re-registered with another
8344 block-set-write-threshold command.
8345 Arguments
8347 node-name: string
8348 graph node name on which the threshold was exceeded.
8349 amount-exceeded: int
8351 amount of data which exceeded the threshold, in bytes.
8352 write-threshold: int
8354 last configured threshold, in bytes.
8355 Since
8357 2.3
8358 block-set-write-threshold (Command)
8360 Change the write threshold for a block drive. An event will be deliv‐
8361 ered if a write to this block drive crosses the configured threshold.
8362 The threshold is an offset, thus must be non-negative. Default is no
8363 write threshold. Setting the threshold to zero disables it.
8364 This is useful to transparently resize thin-provisioned drives without
8366 the guest OS noticing.
8367 Arguments
8369 node-name: string
8370 graph node name on which the threshold must be set.
8371 write-threshold: int
8373 configured threshold for the block device, bytes. Use 0 to dis‐
8374 able the threshold.
8375 Since
8377 2.3
8378 Example
8380 -> { "execute": "block-set-write-threshold",
8381 "arguments": { "node-name": "mydev",
8382 "write-threshold": 17179869184 } }
8383 <- { "return": {} }
8384 x-blockdev-change (Command)
8386 Dynamically reconfigure the block driver state graph. It can be used to
8387 add, remove, insert or replace a graph node. Currently only the Quorum
8388 driver implements this feature to add or remove its child. This is use‐
8389 ful to fix a broken quorum child.
8390 If node is specified, it will be inserted under parent. child may not
8392 be specified in this case. If both parent and child are specified but
8393 node is not, child will be detached from parent.
8394 Arguments
8396 parent: string
8397 the id or name of the parent node.
8398 child: string (optional)
8400 the name of a child under the given parent node.
8401 node: string (optional)
8403 the name of the node that will be added.
8404 Features
8406 unstable
8407 This command is experimental, and its API is not stable. It
8408 does not support all kinds of operations, all kinds of children,
8409 nor all block drivers.
8410 FIXME Removing children from a quorum node means introducing
8412 gaps in the child indices. This cannot be represented in the
8413 'children' list of BlockdevOptionsQuorum, as returned by
8414 .bdrv_refresh_filename().
8415 Warning: The data in a new quorum child MUST be consistent with
8417 that of the rest of the array.
8418 Since
8420 2.7
8421 Example
8423 1. Add a new node to a quorum
8424 -> { "execute": "blockdev-add",
8425 "arguments": {
8426 "driver": "raw",
8427 "node-name": "new_node",
8428 "file": { "driver": "file",
8429 "filename": "test.raw" } } }
8430 <- { "return": {} }
8431 -> { "execute": "x-blockdev-change",
8432 "arguments": { "parent": "disk1",
8433 "node": "new_node" } }
8434 <- { "return": {} }
8435 2. Delete a quorum's node
8437 -> { "execute": "x-blockdev-change",
8438 "arguments": { "parent": "disk1",
8439 "child": "children.1" } }
8440 <- { "return": {} }
8441 x-blockdev-set-iothread (Command)
8443 Move node and its children into the iothread. If iothread is null then
8444 move node and its children into the main loop.
8445 The node must not be attached to a BlockBackend.
8447 Arguments
8449 node-name: string
8450 the name of the block driver node
8451 iothread: StrOrNull
8453 the name of the IOThread object or null for the main loop
8454 force: boolean (optional)
8456 true if the node and its children should be moved when a Block‐
8457 Backend is already attached
8458 Features
8460 unstable
8461 This command is experimental and intended for test cases that
8462 need control over IOThreads only.
8463 Since
8465 2.12
8466 Example
8468 1. Move a node into an IOThread
8469 -> { "execute": "x-blockdev-set-iothread",
8470 "arguments": { "node-name": "disk1",
8471 "iothread": "iothread0" } }
8472 <- { "return": {} }
8473 2. Move a node into the main loop
8475 -> { "execute": "x-blockdev-set-iothread",
8476 "arguments": { "node-name": "disk1",
8477 "iothread": null } }
8478 <- { "return": {} }
8479 QuorumOpType (Enum)
8481 An enumeration of the quorum operation types
8482 Values
8484 read read operation
8485 write write operation
8487 flush flush operation
8489 Since
8491 2.6
8492 QUORUM_FAILURE (Event)
8494 Emitted by the Quorum block driver if it fails to establish a quorum
8495 Arguments
8497 reference: string
8498 device name if defined else node name
8499 sector-num: int
8501 number of the first sector of the failed read operation
8502 sectors-count: int
8504 failed read operation sector count
8505 Note
8507 This event is rate-limited.
8508 Since
8510 2.0
8511 Example
8513 <- { "event": "QUORUM_FAILURE",
8514 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
8515 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
8516 QUORUM_REPORT_BAD (Event)
8518 Emitted to report a corruption of a Quorum file
8519 Arguments
8521 type: QuorumOpType
8522 quorum operation type (Since 2.6)
8523 error: string (optional)
8525 error message. Only present on failure. This field contains a
8526 human-readable error message. There are no semantics other than
8527 that the block layer reported an error and clients should not
8528 try to interpret the error string.
8529 node-name: string
8531 the graph node name of the block driver state
8532 sector-num: int
8534 number of the first sector of the failed read operation
8535 sectors-count: int
8537 failed read operation sector count
8538 Note
8540 This event is rate-limited.
8541 Since
8543 2.0
8544 Example
8546 1. Read operation
8547 { "event": "QUORUM_REPORT_BAD",
8549 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
8550 "type": "read" },
8551 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
8552 2. Flush operation
8554 { "event": "QUORUM_REPORT_BAD",
8556 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
8557 "type": "flush", "error": "Broken pipe" },
8558 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
8559 BlockdevSnapshotInternal (Object)
8561 Members
8562 device: string
8563 the device name or node-name of a root node to generate the
8564 snapshot from
8565 name: string
8567 the name of the internal snapshot to be created
8568 Notes
8570 In transaction, if name is empty, or any snapshot matching name exists,
8571 the operation will fail. Only some image formats support it, for exam‐
8572 ple, qcow2, and rbd.
8573 Since
8575 1.7
8576 blockdev-snapshot-internal-sync (Command)
8578 Synchronously take an internal snapshot of a block device, when the
8579 format of the image used supports it. If the name is an empty string,
8580 or a snapshot with name already exists, the operation will fail.
8581 For the arguments, see the documentation of BlockdevSnapshotInternal.
8583 Returns
8585 • nothing on success
8586 • If device is not a valid block device, GenericError
8588 • If any snapshot matching name exists, or name is empty, GenericError
8590 • If the format of the image used does not support it, BlockFormatFea‐
8592 tureNotSupported
8593 Since
8595 1.7
8596 Example
8598 -> { "execute": "blockdev-snapshot-internal-sync",
8599 "arguments": { "device": "ide-hd0",
8600 "name": "snapshot0" }
8601 }
8602 <- { "return": {} }
8603 blockdev-snapshot-delete-internal-sync (Command)
8605 Synchronously delete an internal snapshot of a block device, when the
8606 format of the image used support it. The snapshot is identified by name
8607 or id or both. One of the name or id is required. Return SnapshotInfo
8608 for the successfully deleted snapshot.
8609 Arguments
8611 device: string
8612 the device name or node-name of a root node to delete the snap‐
8613 shot from
8614 id: string (optional)
8616 optional the snapshot's ID to be deleted
8617 name: string (optional)
8619 optional the snapshot's name to be deleted
8620 Returns
8622 • SnapshotInfo on success
8623 • If device is not a valid block device, GenericError
8625 • If snapshot not found, GenericError
8627 • If the format of the image used does not support it, BlockFormatFea‐
8629 tureNotSupported
8630 • If id and name are both not specified, GenericError
8632 Since
8634 1.7
8635 Example
8637 -> { "execute": "blockdev-snapshot-delete-internal-sync",
8638 "arguments": { "device": "ide-hd0",
8639 "name": "snapshot0" }
8640 }
8641 <- { "return": {
8642 "id": "1",
8643 "name": "snapshot0",
8644 "vm-state-size": 0,
8645 "date-sec": 1000012,
8646 "date-nsec": 10,
8647 "vm-clock-sec": 100,
8648 "vm-clock-nsec": 20,
8649 "icount": 220414
8650 }
8651 }
8652 Additional block stuff (VM related)
8654 BiosAtaTranslation (Enum)
8655 Policy that BIOS should use to interpret cylinder/head/sector ad‐
8656 dresses. Note that Bochs BIOS and SeaBIOS will not actually translate
8657 logical CHS to physical; instead, they will use logical block address‐
8658 ing.
8659 Values
8661 auto If cylinder/heads/sizes are passed, choose between none and LBA
8662 depending on the size of the disk. If they are not passed,
8663 choose none if QEMU can guess that the disk had 16 or fewer
8664 heads, large if QEMU can guess that the disk had 131072 or fewer
8665 tracks across all heads (i.e. cylinders*heads<131072), otherwise
8666 LBA.
8667 none The physical disk geometry is equal to the logical geometry.
8669 lba Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
8671 heads (if fewer than 255 are enough to cover the whole disk with
8672 1024 cylinders/head). The number of cylinders/head is then com‐
8673 puted based on the number of sectors and heads.
8674 large The number of cylinders per head is scaled down to 1024 by cor‐
8676 respondingly scaling up the number of heads.
8677 rechs Same as large, but first convert a 16-head geometry to 15-head,
8679 by proportionally scaling up the number of cylinders/head.
8680 Since
8682 2.0
8683 FloppyDriveType (Enum)
8685 Type of Floppy drive to be emulated by the Floppy Disk Controller.
8686 Values
8688 144 1.44MB 3.5" drive
8689 288 2.88MB 3.5" drive
8691 120 1.2MB 5.25" drive
8693 none No drive connected
8695 auto Automatically determined by inserted media at boot
8697 Since
8699 2.6
8700 PRManagerInfo (Object)
8702 Information about a persistent reservation manager
8703 Members
8705 id: string
8706 the identifier of the persistent reservation manager
8707 connected: boolean
8709 true if the persistent reservation manager is connected to the
8710 underlying storage or helper
8711 Since
8713 3.0
8714 query-pr-managers (Command)
8716 Returns a list of information about each persistent reservation man‐
8717 ager.
8718 Returns
8720 a list of PRManagerInfo for each persistent reservation manager
8721 Since
8723 3.0
8724 eject (Command)
8726 Ejects the medium from a removable drive.
8727 Arguments
8729 device: string (optional)
8730 Block device name
8731 id: string (optional)
8733 The name or QOM path of the guest device (since: 2.8)
8734 force: boolean (optional)
8736 If true, eject regardless of whether the drive is locked. If
8737 not specified, the default value is false.
8738 Features
8740 deprecated
8741 Member device is deprecated. Use id instead.
8742 Returns
8744 • Nothing on success
8745 • If device is not a valid block device, DeviceNotFound
8747 Notes
8749 Ejecting a device with no media results in success
8750 Since
8752 0.14
8753 Example
8755 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
8756 <- { "return": {} }
8757 blockdev-open-tray (Command)
8759 Opens a block device's tray. If there is a block driver state tree in‐
8760 serted as a medium, it will become inaccessible to the guest (but it
8761 will remain associated to the block device, so closing the tray will
8762 make it accessible again).
8763 If the tray was already open before, this will be a no-op.
8765 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
8767 cases in which no such event will be generated, these include:
8768 • if the guest has locked the tray, force is false and the guest does
8770 not respond to the eject request
8771 • if the BlockBackend denoted by device does not have a guest device
8773 attached to it
8774 • if the guest device does not have an actual tray
8776 Arguments
8778 device: string (optional)
8779 Block device name
8780 id: string (optional)
8782 The name or QOM path of the guest device (since: 2.8)
8783 force: boolean (optional)
8785 if false (the default), an eject request will be sent to the
8786 guest if it has locked the tray (and the tray will not be opened
8787 immediately); if true, the tray will be opened regardless of
8788 whether it is locked
8789 Features
8791 deprecated
8792 Member device is deprecated. Use id instead.
8793 Since
8795 2.5
8796 Example
8798 -> { "execute": "blockdev-open-tray",
8799 "arguments": { "id": "ide0-1-0" } }
8800 <- { "timestamp": { "seconds": 1418751016,
8802 "microseconds": 716996 },
8803 "event": "DEVICE_TRAY_MOVED",
8804 "data": { "device": "ide1-cd0",
8805 "id": "ide0-1-0",
8806 "tray-open": true } }
8807 <- { "return": {} }
8809 blockdev-close-tray (Command)
8811 Closes a block device's tray. If there is a block driver state tree as‐
8812 sociated with the block device (which is currently ejected), that tree
8813 will be loaded as the medium.
8814 If the tray was already closed before, this will be a no-op.
8816 Arguments
8818 device: string (optional)
8819 Block device name
8820 id: string (optional)
8822 The name or QOM path of the guest device (since: 2.8)
8823 Features
8825 deprecated
8826 Member device is deprecated. Use id instead.
8827 Since
8829 2.5
8830 Example
8832 -> { "execute": "blockdev-close-tray",
8833 "arguments": { "id": "ide0-1-0" } }
8834 <- { "timestamp": { "seconds": 1418751345,
8836 "microseconds": 272147 },
8837 "event": "DEVICE_TRAY_MOVED",
8838 "data": { "device": "ide1-cd0",
8839 "id": "ide0-1-0",
8840 "tray-open": false } }
8841 <- { "return": {} }
8843 blockdev-remove-medium (Command)
8845 Removes a medium (a block driver state tree) from a block device. That
8846 block device's tray must currently be open (unless there is no attached
8847 guest device).
8848 If the tray is open and there is no medium inserted, this will be a
8850 no-op.
8851 Arguments
8853 id: string
8854 The name or QOM path of the guest device
8855 Since
8857 2.12
8858 Example
8860 -> { "execute": "blockdev-remove-medium",
8861 "arguments": { "id": "ide0-1-0" } }
8862 <- { "error": { "class": "GenericError",
8864 "desc": "Tray of device 'ide0-1-0' is not open" } }
8865 -> { "execute": "blockdev-open-tray",
8867 "arguments": { "id": "ide0-1-0" } }
8868 <- { "timestamp": { "seconds": 1418751627,
8870 "microseconds": 549958 },
8871 "event": "DEVICE_TRAY_MOVED",
8872 "data": { "device": "ide1-cd0",
8873 "id": "ide0-1-0",
8874 "tray-open": true } }
8875 <- { "return": {} }
8877 -> { "execute": "blockdev-remove-medium",
8879 "arguments": { "id": "ide0-1-0" } }
8880 <- { "return": {} }
8882 blockdev-insert-medium (Command)
8884 Inserts a medium (a block driver state tree) into a block device. That
8885 block device's tray must currently be open (unless there is no attached
8886 guest device) and there must be no medium inserted already.
8887 Arguments
8889 id: string
8890 The name or QOM path of the guest device
8891 node-name: string
8893 name of a node in the block driver state graph
8894 Since
8896 2.12
8897 Example
8899 -> { "execute": "blockdev-add",
8900 "arguments": {
8901 "node-name": "node0",
8902 "driver": "raw",
8903 "file": { "driver": "file",
8904 "filename": "fedora.iso" } } }
8905 <- { "return": {} }
8906 -> { "execute": "blockdev-insert-medium",
8908 "arguments": { "id": "ide0-1-0",
8909 "node-name": "node0" } }
8910 <- { "return": {} }
8912 BlockdevChangeReadOnlyMode (Enum)
8914 Specifies the new read-only mode of a block device subject to the
8915 blockdev-change-medium command.
8916 Values
8918 retain Retains the current read-only mode
8919 read-only
8921 Makes the device read-only
8922 read-write
8924 Makes the device writable
8925 Since
8927 2.3
8928 blockdev-change-medium (Command)
8930 Changes the medium inserted into a block device by ejecting the current
8931 medium and loading a new image file which is inserted as the new medium
8932 (this command combines blockdev-open-tray, blockdev-remove-medium,
8933 blockdev-insert-medium and blockdev-close-tray).
8934 Arguments
8936 device: string (optional)
8937 Block device name
8938 id: string (optional)
8940 The name or QOM path of the guest device (since: 2.8)
8941 filename: string
8943 filename of the new image to be loaded
8944 format: string (optional)
8946 format to open the new image with (defaults to the probed for‐
8947 mat)
8948 read-only-mode: BlockdevChangeReadOnlyMode (optional)
8950 change the read-only mode of the device; defaults to 'retain'
8951 Features
8953 deprecated
8954 Member device is deprecated. Use id instead.
8955 Since
8957 2.5
8958 Examples
8960 1. Change a removable medium
8961 -> { "execute": "blockdev-change-medium",
8963 "arguments": { "id": "ide0-1-0",
8964 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
8965 "format": "raw" } }
8966 <- { "return": {} }
8967 2. Load a read-only medium into a writable drive
8969 -> { "execute": "blockdev-change-medium",
8971 "arguments": { "id": "floppyA",
8972 "filename": "/srv/images/ro.img",
8973 "format": "raw",
8974 "read-only-mode": "retain" } }
8975 <- { "error":
8977 { "class": "GenericError",
8978 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
8979 -> { "execute": "blockdev-change-medium",
8981 "arguments": { "id": "floppyA",
8982 "filename": "/srv/images/ro.img",
8983 "format": "raw",
8984 "read-only-mode": "read-only" } }
8985 <- { "return": {} }
8987 DEVICE_TRAY_MOVED (Event)
8989 Emitted whenever the tray of a removable device is moved by the guest
8990 or by HMP/QMP commands
8991 Arguments
8993 device: string
8994 Block device name. This is always present for compatibility rea‐
8995 sons, but it can be empty ("") if the image does not have a de‐
8996 vice name associated.
8997 id: string
8999 The name or QOM path of the guest device (since 2.8)
9000 tray-open: boolean
9002 true if the tray has been opened or false if it has been closed
9003 Since
9005 1.1
9006 Example
9008 <- { "event": "DEVICE_TRAY_MOVED",
9009 "data": { "device": "ide1-cd0",
9010 "id": "/machine/unattached/device[22]",
9011 "tray-open": true
9012 },
9013 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
9014 PR_MANAGER_STATUS_CHANGED (Event)
9016 Emitted whenever the connected status of a persistent reservation man‐
9017 ager changes.
9018 Arguments
9020 id: string
9021 The id of the PR manager object
9022 connected: boolean
9024 true if the PR manager is connected to a backend
9025 Since
9027 3.0
9028 Example
9030 <- { "event": "PR_MANAGER_STATUS_CHANGED",
9031 "data": { "id": "pr-helper0",
9032 "connected": true
9033 },
9034 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
9035 block_set_io_throttle (Command)
9037 Change I/O throttle limits for a block drive.
9038 Since QEMU 2.4, each device with I/O limits is member of a throttle
9040 group.
9041 If two or more devices are members of the same group, the limits will
9043 apply to the combined I/O of the whole group in a round-robin fashion.
9044 Therefore, setting new I/O limits to a device will affect the whole
9045 group.
9046 The name of the group can be specified using the 'group' parameter. If
9048 the parameter is unset, it is assumed to be the current group of that
9049 device. If it's not in any group yet, the name of the device will be
9050 used as the name for its group.
9051 The 'group' parameter can also be used to move a device to a different
9053 group. In this case the limits specified in the parameters will be ap‐
9054 plied to the new group only.
9055 I/O limits can be disabled by setting all of them to 0. In this case
9057 the device will be removed from its group and the rest of its members
9058 will not be affected. The 'group' parameter is ignored.
9059 Arguments
9061 The members of BlockIOThrottle
9062 Returns
9064 • Nothing on success
9065 • If device is not a valid block device, DeviceNotFound
9067 Since
9069 1.1
9070 Example
9072 -> { "execute": "block_set_io_throttle",
9073 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
9074 "bps": 0,
9075 "bps_rd": 0,
9076 "bps_wr": 0,
9077 "iops": 512,
9078 "iops_rd": 0,
9079 "iops_wr": 0,
9080 "bps_max": 0,
9081 "bps_rd_max": 0,
9082 "bps_wr_max": 0,
9083 "iops_max": 0,
9084 "iops_rd_max": 0,
9085 "iops_wr_max": 0,
9086 "bps_max_length": 0,
9087 "iops_size": 0 } }
9088 <- { "return": {} }
9089 -> { "execute": "block_set_io_throttle",
9091 "arguments": { "id": "ide0-1-0",
9092 "bps": 1000000,
9093 "bps_rd": 0,
9094 "bps_wr": 0,
9095 "iops": 0,
9096 "iops_rd": 0,
9097 "iops_wr": 0,
9098 "bps_max": 8000000,
9099 "bps_rd_max": 0,
9100 "bps_wr_max": 0,
9101 "iops_max": 0,
9102 "iops_rd_max": 0,
9103 "iops_wr_max": 0,
9104 "bps_max_length": 60,
9105 "iops_size": 0 } }
9106 <- { "return": {} }
9107 block-latency-histogram-set (Command)
9109 Manage read, write and flush latency histograms for the device.
9110 If only id parameter is specified, remove all present latency his‐
9112 tograms for the device. Otherwise, add/reset some of (or all) latency
9113 histograms.
9114 Arguments
9116 id: string
9117 The name or QOM path of the guest device.
9118 boundaries: array of int (optional)
9120 list of interval boundary values (see description in BlockLaten‐
9121 cyHistogramInfo definition). If specified, all latency his‐
9122 tograms are removed, and empty ones created for all io types
9123 with intervals corresponding to boundaries (except for io types,
9124 for which specific boundaries are set through the following pa‐
9125 rameters).
9126 boundaries-read: array of int (optional)
9128 list of interval boundary values for read latency histogram. If
9129 specified, old read latency histogram is removed, and empty one
9130 created with intervals corresponding to boundaries-read. The pa‐
9131 rameter has higher priority then boundaries.
9132 boundaries-write: array of int (optional)
9134 list of interval boundary values for write latency histogram.
9135 boundaries-flush: array of int (optional)
9137 list of interval boundary values for flush latency histogram.
9138 Returns
9140 error if device is not found or any boundary arrays are invalid.
9141 Since
9143 4.0
9144 Example
9146 set new histograms for all io types with intervals
9147 [0, 10), [10, 50), [50, 100), [100, +inf):
9148 -> { "execute": "block-latency-histogram-set",
9150 "arguments": { "id": "drive0",
9151 "boundaries": [10, 50, 100] } }
9152 <- { "return": {} }
9153 Example
9155 set new histogram only for write, other histograms will remain
9156 not changed (or not created):
9157 -> { "execute": "block-latency-histogram-set",
9159 "arguments": { "id": "drive0",
9160 "boundaries-write": [10, 50, 100] } }
9161 <- { "return": {} }
9162 Example
9164 set new histograms with the following intervals:
9165 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
9166 write: [0, 1000), [1000, 5000), [5000, +inf)
9167 -> { "execute": "block-latency-histogram-set",
9169 "arguments": { "id": "drive0",
9170 "boundaries": [10, 50, 100],
9171 "boundaries-write": [1000, 5000] } }
9172 <- { "return": {} }
9173 Example
9175 remove all latency histograms:
9176 -> { "execute": "block-latency-histogram-set",
9178 "arguments": { "id": "drive0" } }
9179 <- { "return": {} }
9180 Block device exports
9182 NbdServerOptions (Object)
9183 Keep this type consistent with the nbd-server-start arguments. The only
9184 intended difference is using SocketAddress instead of SocketAddressLe‐
9185 gacy.
9186 Members
9188 addr: SocketAddress
9189 Address on which to listen.
9190 tls-creds: string (optional)
9192 ID of the TLS credentials object (since 2.6).
9193 tls-authz: string (optional)
9195 ID of the QAuthZ authorization object used to validate the
9196 client's x509 distinguished name. This object is is only re‐
9197 solved at time of use, so can be deleted and recreated on the
9198 fly while the NBD server is active. If missing, it will default
9199 to denying access (since 4.0).
9200 max-connections: int (optional)
9202 The maximum number of connections to allow at the same time, 0
9203 for unlimited. (since 5.2; default: 0)
9204 Since
9206 4.2
9207 nbd-server-start (Command)
9209 Start an NBD server listening on the given host and port. Block de‐
9210 vices can then be exported using nbd-server-add. The NBD server will
9211 present them as named exports; for example, another QEMU instance could
9212 refer to them as "nbd:HOST:PORT:exportname=NAME".
9213 Keep this type consistent with the NbdServerOptions type. The only in‐
9215 tended difference is using SocketAddressLegacy instead of SocketAd‐
9216 dress.
9217 Arguments
9219 addr: SocketAddressLegacy
9220 Address on which to listen.
9221 tls-creds: string (optional)
9223 ID of the TLS credentials object (since 2.6).
9224 tls-authz: string (optional)
9226 ID of the QAuthZ authorization object used to validate the
9227 client's x509 distinguished name. This object is is only re‐
9228 solved at time of use, so can be deleted and recreated on the
9229 fly while the NBD server is active. If missing, it will default
9230 to denying access (since 4.0).
9231 max-connections: int (optional)
9233 The maximum number of connections to allow at the same time, 0
9234 for unlimited. (since 5.2; default: 0)
9235 Returns
9237 error if the server is already running.
9238 Since
9240 1.3
9241 BlockExportOptionsNbdBase (Object)
9243 An NBD block export (common options shared between nbd-server-add and
9244 the NBD branch of block-export-add).
9245 Members
9247 name: string (optional)
9248 Export name. If unspecified, the device parameter is used as the
9249 export name. (Since 2.12)
9250 description: string (optional)
9252 Free-form description of the export, up to 4096 bytes. (Since
9253 5.0)
9254 Since
9256 5.0
9257 BlockExportOptionsNbd (Object)
9259 An NBD block export (distinct options used in the NBD branch of
9260 block-export-add).
9261 Members
9263 bitmaps: array of string (optional)
9264 Also export each of the named dirty bitmaps reachable from de‐
9265 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
9266 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
9267 each bitmap.
9268 allocation-depth: boolean (optional)
9270 Also export the allocation depth map for device, so the NBD
9271 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
9272 text name "qemu:allocation-depth" to inspect allocation details.
9273 (since 5.2)
9274 The members of BlockExportOptionsNbdBase
9276 Since
9278 5.2
9279 BlockExportOptionsVhostUserBlk (Object)
9281 A vhost-user-blk block export.
9282 Members
9284 addr: SocketAddress
9285 The vhost-user socket on which to listen. Both 'unix' and 'fd'
9286 SocketAddress types are supported. Passed fds must be UNIX do‐
9287 main sockets.
9288 logical-block-size: int (optional)
9290 Logical block size in bytes. Defaults to 512 bytes.
9291 num-queues: int (optional)
9293 Number of request virtqueues. Must be greater than 0. Defaults
9294 to 1.
9295 Since
9297 5.2
9298 FuseExportAllowOther (Enum)
9300 Possible allow_other modes for FUSE exports.
9301 Values
9303 off Do not pass allow_other as a mount option.
9304 on Pass allow_other as a mount option.
9306 auto Try mounting with allow_other first, and if that fails, retry
9308 without allow_other.
9309 Since
9311 6.1
9312 BlockExportOptionsFuse (Object)
9314 Options for exporting a block graph node on some (file) mountpoint as a
9315 raw image.
9316 Members
9318 mountpoint: string
9319 Path on which to export the block device via FUSE. This must
9320 point to an existing regular file.
9321 growable: boolean (optional)
9323 Whether writes beyond the EOF should grow the block node accord‐
9324 ingly. (default: false)
9325 allow-other: FuseExportAllowOther (optional)
9327 If this is off, only qemu's user is allowed access to this ex‐
9328 port. That cannot be changed even with chmod or chown. En‐
9329 abling this option will allow other users access to the export
9330 with the FUSE mount option "allow_other". Note that using al‐
9331 low_other as a non-root user requires user_allow_other to be en‐
9332 abled in the global fuse.conf configuration file. In auto mode
9333 (the default), the FUSE export driver will first attempt to
9334 mount the export with allow_other, and if that fails, try again
9335 without. (since 6.1; default: auto)
9336 Since
9338 6.0
9339 If
9341 CONFIG_FUSE
9342 NbdServerAddOptions (Object)
9344 An NBD block export, per legacy nbd-server-add command.
9345 Members
9347 device: string
9348 The device name or node name of the node to be exported
9349 writable: boolean (optional)
9351 Whether clients should be able to write to the device via the
9352 NBD connection (default false).
9353 bitmap: string (optional)
9355 Also export a single dirty bitmap reachable from device, so the
9356 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
9357 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
9358 (since 4.0).
9359 The members of BlockExportOptionsNbdBase
9361 Since
9363 5.0
9364 nbd-server-add (Command)
9366 Export a block node to QEMU's embedded NBD server.
9367 The export name will be used as the id for the resulting block export.
9369 Arguments
9371 The members of NbdServerAddOptions
9372 Features
9374 deprecated
9375 This command is deprecated. Use block-export-add instead.
9376 Returns
9378 error if the server is not running, or export with the same name al‐
9379 ready exists.
9380 Since
9382 1.3
9383 BlockExportRemoveMode (Enum)
9385 Mode for removing a block export.
9386 Values
9388 safe Remove export if there are no existing connections, fail other‐
9389 wise.
9390 hard Drop all connections immediately and remove export.
9392 Potential additional modes to be added in the future:
9393 hide: Just hide export from new clients, leave existing connections as
9395 is. Remove export after all clients are disconnected.
9396 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
9398 ther requests from existing clients.
9399 Since
9401 2.12
9402 nbd-server-remove (Command)
9404 Remove NBD export by name.
9405 Arguments
9407 name: string
9408 Block export id.
9409 mode: BlockExportRemoveMode (optional)
9411 Mode of command operation. See BlockExportRemoveMode descrip‐
9412 tion. Default is 'safe'.
9413 Features
9415 deprecated
9416 This command is deprecated. Use block-export-del instead.
9417 Returns
9419 error if
9420 • the server is not running
9422 • export is not found
9424 • mode is 'safe' and there are existing connections
9426 Since
9428 2.12
9429 nbd-server-stop (Command)
9431 Stop QEMU's embedded NBD server, and unregister all devices previously
9432 added via nbd-server-add.
9433 Since
9435 1.3
9436 BlockExportType (Enum)
9438 An enumeration of block export types
9439 Values
9441 nbd NBD export
9442 vhost-user-blk
9444 vhost-user-blk export (since 5.2)
9445 fuse (If: CONFIG_FUSE)
9447 FUSE export (since: 6.0)
9448 Since
9450 4.2
9451 BlockExportOptions (Object)
9453 Describes a block export, i.e. how single node should be exported on an
9454 external interface.
9455 Members
9457 id: string
9458 A unique identifier for the block export (across all export
9459 types)
9460 node-name: string
9462 The node name of the block node to be exported (since: 5.2)
9463 writable: boolean (optional)
9465 True if clients should be able to write to the export (default
9466 false)
9467 writethrough: boolean (optional)
9469 If true, caches are flushed after every write request to the ex‐
9470 port before completion is signalled. (since: 5.2; default:
9471 false)
9472 iothread: string (optional)
9474 The name of the iothread object where the export will run. The
9475 default is to use the thread currently associated with the block
9476 node. (since: 5.2)
9477 fixed-iothread: boolean (optional)
9479 True prevents the block node from being moved to another thread
9480 while the export is active. If true and iothread is given, ex‐
9481 port creation fails if the block node cannot be moved to the io‐
9482 thread. The default is false. (since: 5.2)
9483 type: BlockExportType
9485 Not documented
9486 The members of BlockExportOptionsNbd when type is "nbd"
9488 The members of BlockExportOptionsVhostUserBlk when type is
9490 "vhost-user-blk"
9491 The members of BlockExportOptionsFuse when type is "fuse" (If: CON‐
9493 FIG_FUSE)
9494 Since
9496 4.2
9497 block-export-add (Command)
9499 Creates a new block export.
9500 Arguments
9502 The members of BlockExportOptions
9503 Since
9505 5.2
9506 block-export-del (Command)
9508 Request to remove a block export. This drops the user's reference to
9509 the export, but the export may still stay around after this command re‐
9510 turns until the shutdown of the export has completed.
9511 Arguments
9513 id: string
9514 Block export id.
9515 mode: BlockExportRemoveMode (optional)
9517 Mode of command operation. See BlockExportRemoveMode descrip‐
9518 tion. Default is 'safe'.
9519 Returns
9521 Error if the export is not found or mode is 'safe' and the export is
9522 still in use (e.g. by existing client connections)
9523 Since
9525 5.2
9526 BLOCK_EXPORT_DELETED (Event)
9528 Emitted when a block export is removed and its id can be reused.
9529 Arguments
9531 id: string
9532 Block export id.
9533 Since
9535 5.2
9536 BlockExportInfo (Object)
9538 Information about a single block export.
9539 Members
9541 id: string
9542 The unique identifier for the block export
9543 type: BlockExportType
9545 The block export type
9546 node-name: string
9548 The node name of the block node that is exported
9549 shutting-down: boolean
9551 True if the export is shutting down (e.g. after a block-ex‐
9552 port-del command, but before the shutdown has completed)
9553 Since
9555 5.2
9556 query-block-exports (Command)
9558 Returns
9559 A list of BlockExportInfo describing all block exports
9560 Since
9562 5.2
9563
9565 ChardevInfo (Object)
9566 Information about a character device.
9567 Members
9569 label: string
9570 the label of the character device
9571 filename: string
9573 the filename of the character device
9574 frontend-open: boolean
9576 shows whether the frontend device attached to this backend (eg.
9577 with the chardev=... option) is in open or closed state (since
9578 2.1)
9579 Notes
9581 filename is encoded using the QEMU command line character device encod‐
9582 ing. See the QEMU man page for details.
9583 Since
9585 0.14
9586 query-chardev (Command)
9588 Returns information about current character devices.
9589 Returns
9591 a list of ChardevInfo
9592 Since
9594 0.14
9595 Example
9597 -> { "execute": "query-chardev" }
9598 <- {
9599 "return": [
9600 {
9601 "label": "charchannel0",
9602 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
9603 "frontend-open": false
9604 },
9605 {
9606 "label": "charmonitor",
9607 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
9608 "frontend-open": true
9609 },
9610 {
9611 "label": "charserial0",
9612 "filename": "pty:/dev/pts/2",
9613 "frontend-open": true
9614 }
9615 ]
9616 }
9617 ChardevBackendInfo (Object)
9619 Information about a character device backend
9620 Members
9622 name: string
9623 The backend name
9624 Since
9626 2.0
9627 query-chardev-backends (Command)
9629 Returns information about character device backends.
9630 Returns
9632 a list of ChardevBackendInfo
9633 Since
9635 2.0
9636 Example
9638 -> { "execute": "query-chardev-backends" }
9639 <- {
9640 "return":[
9641 {
9642 "name":"udp"
9643 },
9644 {
9645 "name":"tcp"
9646 },
9647 {
9648 "name":"unix"
9649 },
9650 {
9651 "name":"spiceport"
9652 }
9653 ]
9654 }
9655 DataFormat (Enum)
9657 An enumeration of data format.
9658 Values
9660 utf8 Data is a UTF-8 string (RFC 3629)
9661 base64 Data is Base64 encoded binary (RFC 3548)
9663 Since
9665 1.4
9666 ringbuf-write (Command)
9668 Write to a ring buffer character device.
9669 Arguments
9671 device: string
9672 the ring buffer character device name
9673 data: string
9675 data to write
9676 format: DataFormat (optional)
9678 data encoding (default 'utf8').
9679 • base64: data must be base64 encoded text. Its binary decoding
9681 gets written.
9682 • utf8: data's UTF-8 encoding is written
9684 • data itself is always Unicode regardless of format, like any
9686 other string.
9687 Returns
9689 Nothing on success
9690 Since
9692 1.4
9693 Example
9695 -> { "execute": "ringbuf-write",
9696 "arguments": { "device": "foo",
9697 "data": "abcdefgh",
9698 "format": "utf8" } }
9699 <- { "return": {} }
9700 ringbuf-read (Command)
9702 Read from a ring buffer character device.
9703 Arguments
9705 device: string
9706 the ring buffer character device name
9707 size: int
9709 how many bytes to read at most
9710 format: DataFormat (optional)
9712 data encoding (default 'utf8').
9713 • base64: the data read is returned in base64 encoding.
9715 • utf8: the data read is interpreted as UTF-8. Bug: can screw
9717 up when the buffer contains invalid UTF-8 sequences, NUL char‐
9718 acters, after the ring buffer lost data, and when reading
9719 stops because the size limit is reached.
9720 • The return value is always Unicode regardless of format, like
9722 any other string.
9723 Returns
9725 data read from the device
9726 Since
9728 1.4
9729 Example
9731 -> { "execute": "ringbuf-read",
9732 "arguments": { "device": "foo",
9733 "size": 1000,
9734 "format": "utf8" } }
9735 <- { "return": "abcdefgh" }
9736 ChardevCommon (Object)
9738 Configuration shared across all chardev backends
9739 Members
9741 logfile: string (optional)
9742 The name of a logfile to save output
9743 logappend: boolean (optional)
9745 true to append instead of truncate (default to false to trun‐
9746 cate)
9747 Since
9749 2.6
9750 ChardevFile (Object)
9752 Configuration info for file chardevs.
9753 Members
9755 in: string (optional)
9756 The name of the input file
9757 out: string
9759 The name of the output file
9760 append: boolean (optional)
9762 Open the file in append mode (default false to truncate) (Since
9763 2.6)
9764 The members of ChardevCommon
9766 Since
9768 1.4
9769 ChardevHostdev (Object)
9771 Configuration info for device and pipe chardevs.
9772 Members
9774 device: string
9775 The name of the special file for the device, i.e. /dev/ttyS0 on
9776 Unix or COM1: on Windows
9777 The members of ChardevCommon
9779 Since
9781 1.4
9782 ChardevSocket (Object)
9784 Configuration info for (stream) socket chardevs.
9785 Members
9787 addr: SocketAddressLegacy
9788 socket address to listen on (server=true) or connect to
9789 (server=false)
9790 tls-creds: string (optional)
9792 the ID of the TLS credentials object (since 2.6)
9793 tls-authz: string (optional)
9795 the ID of the QAuthZ authorization object against which the
9796 client's x509 distinguished name will be validated. This object
9797 is only resolved at time of use, so can be deleted and recreated
9798 on the fly while the chardev server is active. If missing, it
9799 will default to denying access (since 4.0)
9800 server: boolean (optional)
9802 create server socket (default: true)
9803 wait: boolean (optional)
9805 wait for incoming connection on server sockets (default: false).
9806 Silently ignored with server: false. This use is deprecated.
9807 nodelay: boolean (optional)
9809 set TCP_NODELAY socket option (default: false)
9810 telnet: boolean (optional)
9812 enable telnet protocol on server sockets (default: false)
9813 tn3270: boolean (optional)
9815 enable tn3270 protocol on server sockets (default: false)
9816 (Since: 2.10)
9817 websocket: boolean (optional)
9819 enable websocket protocol on server sockets (default: false)
9820 (Since: 3.1)
9821 reconnect: int (optional)
9823 For a client socket, if a socket is disconnected, then attempt a
9824 reconnect after the given number of seconds. Setting this to
9825 zero disables this function. (default: 0) (Since: 2.2)
9826 The members of ChardevCommon
9828 Since
9830 1.4
9831 ChardevUdp (Object)
9833 Configuration info for datagram socket chardevs.
9834 Members
9836 remote: SocketAddressLegacy
9837 remote address
9838 local: SocketAddressLegacy (optional)
9840 local address
9841 The members of ChardevCommon
9843 Since
9845 1.5
9846 ChardevMux (Object)
9848 Configuration info for mux chardevs.
9849 Members
9851 chardev: string
9852 name of the base chardev.
9853 The members of ChardevCommon
9855 Since
9857 1.5
9858 ChardevStdio (Object)
9860 Configuration info for stdio chardevs.
9861 Members
9863 signal: boolean (optional)
9864 Allow signals (such as SIGINT triggered by ^C) be delivered to
9865 qemu. Default: true.
9866 The members of ChardevCommon
9868 Since
9870 1.5
9871 ChardevSpiceChannel (Object)
9873 Configuration info for spice vm channel chardevs.
9874 Members
9876 type: string
9877 kind of channel (for example vdagent).
9878 The members of ChardevCommon
9880 Since
9882 1.5
9883 If
9885 CONFIG_SPICE
9886 ChardevSpicePort (Object)
9888 Configuration info for spice port chardevs.
9889 Members
9891 fqdn: string
9892 name of the channel (see docs/spice-port-fqdn.txt)
9893 The members of ChardevCommon
9895 Since
9897 1.5
9898 If
9900 CONFIG_SPICE
9901 ChardevVC (Object)
9903 Configuration info for virtual console chardevs.
9904 Members
9906 width: int (optional)
9907 console width, in pixels
9908 height: int (optional)
9910 console height, in pixels
9911 cols: int (optional)
9913 console width, in chars
9914 rows: int (optional)
9916 console height, in chars
9917 The members of ChardevCommon
9919 Since
9921 1.5
9922 ChardevRingbuf (Object)
9924 Configuration info for ring buffer chardevs.
9925 Members
9927 size: int (optional)
9928 ring buffer size, must be power of two, default is 65536
9929 The members of ChardevCommon
9931 Since
9933 1.5
9934 ChardevQemuVDAgent (Object)
9936 Configuration info for qemu vdagent implementation.
9937 Members
9939 mouse: boolean (optional)
9940 enable/disable mouse, default is enabled.
9941 clipboard: boolean (optional)
9943 enable/disable clipboard, default is disabled.
9944 The members of ChardevCommon
9946 Since
9948 6.1
9949 If
9951 CONFIG_SPICE_PROTOCOL
9952 ChardevBackendKind (Enum)
9954 Values
9955 pipe Since 1.5
9956 udp Since 1.5
9958 mux Since 1.5
9960 msmouse
9962 Since 1.5
9963 wctablet
9965 Since 2.9
9966 braille
9968 Since 1.5
9969 testdev
9971 Since 2.2
9972 stdio Since 1.5
9974 console
9976 Since 1.5
9977 spicevmc (If: CONFIG_SPICE)
9979 Since 1.5
9980 spiceport (If: CONFIG_SPICE)
9982 Since 1.5
9983 qemu-vdagent (If: CONFIG_SPICE_PROTOCOL)
9985 Since 6.1
9986 vc v1.5
9988 ringbuf
9990 Since 1.6
9991 memory Since 1.5
9993 file Not documented
9995 serial Not documented
9997 parallel
9999 Not documented
10000 socket Not documented
10002 pty Not documented
10004 null Not documented
10006 Since
10008 1.4
10009 ChardevFileWrapper (Object)
10011 Members
10012 data: ChardevFile
10013 Not documented
10014 Since
10016 1.4
10017 ChardevHostdevWrapper (Object)
10019 Members
10020 data: ChardevHostdev
10021 Not documented
10022 Since
10024 1.4
10025 ChardevSocketWrapper (Object)
10027 Members
10028 data: ChardevSocket
10029 Not documented
10030 Since
10032 1.4
10033 ChardevUdpWrapper (Object)
10035 Members
10036 data: ChardevUdp
10037 Not documented
10038 Since
10040 1.5
10041 ChardevCommonWrapper (Object)
10043 Members
10044 data: ChardevCommon
10045 Not documented
10046 Since
10048 2.6
10049 ChardevMuxWrapper (Object)
10051 Members
10052 data: ChardevMux
10053 Not documented
10054 Since
10056 1.5
10057 ChardevStdioWrapper (Object)
10059 Members
10060 data: ChardevStdio
10061 Not documented
10062 Since
10064 1.5
10065 ChardevSpiceChannelWrapper (Object)
10067 Members
10068 data: ChardevSpiceChannel
10069 Not documented
10070 Since
10072 1.5
10073 If
10075 CONFIG_SPICE
10076 ChardevSpicePortWrapper (Object)
10078 Members
10079 data: ChardevSpicePort
10080 Not documented
10081 Since
10083 1.5
10084 If
10086 CONFIG_SPICE
10087 ChardevQemuVDAgentWrapper (Object)
10089 Members
10090 data: ChardevQemuVDAgent
10091 Not documented
10092 Since
10094 6.1
10095 If
10097 CONFIG_SPICE_PROTOCOL
10098 ChardevVCWrapper (Object)
10100 Members
10101 data: ChardevVC
10102 Not documented
10103 Since
10105 1.5
10106 ChardevRingbufWrapper (Object)
10108 Members
10109 data: ChardevRingbuf
10110 Not documented
10111 Since
10113 1.5
10114 ChardevBackend (Object)
10116 Configuration info for the new chardev backend.
10117 Members
10119 type: ChardevBackendKind
10120 Not documented
10121 The members of ChardevFileWrapper when type is "file"
10123 The members of ChardevHostdevWrapper when type is "serial"
10125 The members of ChardevHostdevWrapper when type is "parallel"
10127 The members of ChardevHostdevWrapper when type is "pipe"
10129 The members of ChardevSocketWrapper when type is "socket"
10131 The members of ChardevUdpWrapper when type is "udp"
10133 The members of ChardevCommonWrapper when type is "pty"
10135 The members of ChardevCommonWrapper when type is "null"
10137 The members of ChardevMuxWrapper when type is "mux"
10139 The members of ChardevCommonWrapper when type is "msmouse"
10141 The members of ChardevCommonWrapper when type is "wctablet"
10143 The members of ChardevCommonWrapper when type is "braille"
10145 The members of ChardevCommonWrapper when type is "testdev"
10147 The members of ChardevStdioWrapper when type is "stdio"
10149 The members of ChardevCommonWrapper when type is "console"
10151 The members of ChardevSpiceChannelWrapper when type is "spicevmc" (If:
10153 CONFIG_SPICE)
10154 The members of ChardevSpicePortWrapper when type is "spiceport" (If:
10156 CONFIG_SPICE)
10157 The members of ChardevQemuVDAgentWrapper when type is "qemu-vdagent"
10159 (If: CONFIG_SPICE_PROTOCOL)
10160 The members of ChardevVCWrapper when type is "vc"
10162 The members of ChardevRingbufWrapper when type is "ringbuf"
10164 The members of ChardevRingbufWrapper when type is "memory"
10166 Since
10168 1.4
10169 ChardevReturn (Object)
10171 Return info about the chardev backend just created.
10172 Members
10174 pty: string (optional)
10175 name of the slave pseudoterminal device, present if and only if
10176 a chardev of type 'pty' was created
10177 Since
10179 1.4
10180 chardev-add (Command)
10182 Add a character device backend
10183 Arguments
10185 id: string
10186 the chardev's ID, must be unique
10187 backend: ChardevBackend
10189 backend type and parameters
10190 Returns
10192 ChardevReturn.
10193 Since
10195 1.4
10196 Example
10198 -> { "execute" : "chardev-add",
10199 "arguments" : { "id" : "foo",
10200 "backend" : { "type" : "null", "data" : {} } } }
10201 <- { "return": {} }
10202 -> { "execute" : "chardev-add",
10204 "arguments" : { "id" : "bar",
10205 "backend" : { "type" : "file",
10206 "data" : { "out" : "/tmp/bar.log" } } } }
10207 <- { "return": {} }
10208 -> { "execute" : "chardev-add",
10210 "arguments" : { "id" : "baz",
10211 "backend" : { "type" : "pty", "data" : {} } } }
10212 <- { "return": { "pty" : "/dev/pty/42" } }
10213 chardev-change (Command)
10215 Change a character device backend
10216 Arguments
10218 id: string
10219 the chardev's ID, must exist
10220 backend: ChardevBackend
10222 new backend type and parameters
10223 Returns
10225 ChardevReturn.
10226 Since
10228 2.10
10229 Example
10231 -> { "execute" : "chardev-change",
10232 "arguments" : { "id" : "baz",
10233 "backend" : { "type" : "pty", "data" : {} } } }
10234 <- { "return": { "pty" : "/dev/pty/42" } }
10235 -> {"execute" : "chardev-change",
10237 "arguments" : {
10238 "id" : "charchannel2",
10239 "backend" : {
10240 "type" : "socket",
10241 "data" : {
10242 "addr" : {
10243 "type" : "unix" ,
10244 "data" : {
10245 "path" : "/tmp/charchannel2.socket"
10246 }
10247 },
10248 "server" : true,
10249 "wait" : false }}}}
10250 <- {"return": {}}
10251 chardev-remove (Command)
10253 Remove a character device backend
10254 Arguments
10256 id: string
10257 the chardev's ID, must exist and not be in use
10258 Returns
10260 Nothing on success
10261 Since
10263 1.4
10264 Example
10266 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
10267 <- { "return": {} }
10268 chardev-send-break (Command)
10270 Send a break to a character device
10271 Arguments
10273 id: string
10274 the chardev's ID, must exist
10275 Returns
10277 Nothing on success
10278 Since
10280 2.10
10281 Example
10283 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
10284 <- { "return": {} }
10285 VSERPORT_CHANGE (Event)
10287 Emitted when the guest opens or closes a virtio-serial port.
10288 Arguments
10290 id: string
10291 device identifier of the virtio-serial port
10292 open: boolean
10294 true if the guest has opened the virtio-serial port
10295 Note
10297 This event is rate-limited.
10298 Since
10300 2.1
10301 Example
10303 <- { "event": "VSERPORT_CHANGE",
10304 "data": { "id": "channel0", "open": true },
10305 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
10306
10308 DumpGuestMemoryFormat (Enum)
10309 An enumeration of guest-memory-dump's format.
10310 Values
10312 elf elf format
10313 kdump-zlib
10315 kdump-compressed format with zlib-compressed
10316 kdump-lzo
10318 kdump-compressed format with lzo-compressed
10319 kdump-snappy
10321 kdump-compressed format with snappy-compressed
10322 win-dmp
10324 Windows full crashdump format, can be used instead of ELF con‐
10325 verting (since 2.13)
10326 Since
10328 2.0
10329 dump-guest-memory (Command)
10331 Dump guest's memory to vmcore. It is a synchronous operation that can
10332 take very long depending on the amount of guest memory.
10333 Arguments
10335 paging: boolean
10336 if true, do paging to get guest's memory mapping. This allows
10337 using gdb to process the core file.
10338 IMPORTANT: this option can make QEMU allocate several gigabytes
10340 of RAM. This can happen for a large guest, or a malicious guest
10341 pretending to be large.
10342 Also, paging=true has the following limitations:
10344 1. The guest may be in a catastrophic state or can have cor‐
10346 rupted memory, which cannot be trusted
10347 2. The guest can be in real-mode even if paging is enabled.
10349 For example, the guest uses ACPI to sleep, and ACPI sleep
10350 state goes in real-mode
10351 3. Currently only supported on i386 and x86_64.
10353 protocol: string
10355 the filename or file descriptor of the vmcore. The supported
10356 protocols are:
10357 1. file: the protocol starts with "file:", and the following
10359 string is the file's path.
10360 2. fd: the protocol starts with "fd:", and the following string
10362 is the fd's name.
10363 detach: boolean (optional)
10365 if true, QMP will return immediately rather than waiting for the
10366 dump to finish. The user can track progress using "query-dump".
10367 (since 2.6).
10368 begin: int (optional)
10370 if specified, the starting physical address.
10371 length: int (optional)
10373 if specified, the memory size, in bytes. If you don't want to
10374 dump all guest's memory, please specify the start begin and
10375 length
10376 format: DumpGuestMemoryFormat (optional)
10378 if specified, the format of guest memory dump. But non-elf for‐
10379 mat is conflict with paging and filter, ie. paging, begin and
10380 length is not allowed to be specified with non-elf format at the
10381 same time (since 2.0)
10382 Note
10384 All boolean arguments default to false
10385 Returns
10387 nothing on success
10388 Since
10390 1.2
10391 Example
10393 -> { "execute": "dump-guest-memory",
10394 "arguments": { "protocol": "fd:dump" } }
10395 <- { "return": {} }
10396 DumpStatus (Enum)
10398 Describe the status of a long-running background guest memory dump.
10399 Values
10401 none no dump-guest-memory has started yet.
10402 active there is one dump running in background.
10404 completed
10406 the last dump has finished successfully.
10407 failed the last dump has failed.
10409 Since
10411 2.6
10412 DumpQueryResult (Object)
10414 The result format for 'query-dump'.
10415 Members
10417 status: DumpStatus
10418 enum of DumpStatus, which shows current dump status
10419 completed: int
10421 bytes written in latest dump (uncompressed)
10422 total: int
10424 total bytes to be written in latest dump (uncompressed)
10425 Since
10427 2.6
10428 query-dump (Command)
10430 Query latest dump status.
10431 Returns
10433 A DumpStatus object showing the dump status.
10434 Since
10436 2.6
10437 Example
10439 -> { "execute": "query-dump" }
10440 <- { "return": { "status": "active", "completed": 1024000,
10441 "total": 2048000 } }
10442 DUMP_COMPLETED (Event)
10444 Emitted when background dump has completed
10445 Arguments
10447 result: DumpQueryResult
10448 final dump status
10449 error: string (optional)
10451 human-readable error string that provides hint on why dump
10452 failed. Only presents on failure. The user should not try to in‐
10453 terpret the error string.
10454 Since
10456 2.6
10457 Example
10459 { "event": "DUMP_COMPLETED",
10460 "data": {"result": {"total": 1090650112, "status": "completed",
10461 "completed": 1090650112} } }
10462 DumpGuestMemoryCapability (Object)
10464 A list of the available formats for dump-guest-memory
10465 Members
10467 formats: array of DumpGuestMemoryFormat
10468 Not documented
10469 Since
10471 2.0
10472 query-dump-guest-memory-capability (Command)
10474 Returns the available formats for dump-guest-memory
10475 Returns
10477 A DumpGuestMemoryCapability object listing available formats for
10478 dump-guest-memory
10479 Since
10481 2.0
10482 Example
10484 -> { "execute": "query-dump-guest-memory-capability" }
10485 <- { "return": { "formats":
10486 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
10487
10489 set_link (Command)
10490 Sets the link status of a virtual network adapter.
10491 Arguments
10493 name: string
10494 the device name of the virtual network adapter
10495 up: boolean
10497 true to set the link status to be up
10498 Returns
10500 Nothing on success If name is not a valid network device, DeviceNot‐
10501 Found
10502 Since
10504 0.14
10505 Notes
10507 Not all network adapters support setting link status. This command
10508 will succeed even if the network adapter does not support link status
10509 notification.
10510 Example
10512 -> { "execute": "set_link",
10513 "arguments": { "name": "e1000.0", "up": false } }
10514 <- { "return": {} }
10515 netdev_add (Command)
10517 Add a network backend.
10518 Additional arguments depend on the type.
10520 Arguments
10522 The members of Netdev
10523 Since
10525 0.14
10526 Returns
10528 Nothing on success If type is not a valid network backend, DeviceNot‐
10529 Found
10530 Example
10532 -> { "execute": "netdev_add",
10533 "arguments": { "type": "user", "id": "netdev1",
10534 "dnssearch": "example.org" } }
10535 <- { "return": {} }
10536 netdev_del (Command)
10538 Remove a network backend.
10539 Arguments
10541 id: string
10542 the name of the network backend to remove
10543 Returns
10545 Nothing on success If id is not a valid network backend, DeviceNotFound
10546 Since
10548 0.14
10549 Example
10551 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
10552 <- { "return": {} }
10553 NetLegacyNicOptions (Object)
10555 Create a new Network Interface Card.
10556 Members
10558 netdev: string (optional)
10559 id of -netdev to connect to
10560 macaddr: string (optional)
10562 MAC address
10563 model: string (optional)
10565 device model (e1000, rtl8139, virtio etc.)
10566 addr: string (optional)
10568 PCI device address
10569 vectors: int (optional)
10571 number of MSI-x vectors, 0 to disable MSI-X
10572 Since
10574 1.2
10575 NetdevUserOptions (Object)
10577 Use the user mode network stack which requires no administrator privi‐
10578 lege to run.
10579 Members
10581 hostname: string (optional)
10582 client hostname reported by the builtin DHCP server
10583 restrict: boolean (optional)
10585 isolate the guest from the host
10586 ipv4: boolean (optional)
10588 whether to support IPv4, default true for enabled (since 2.6)
10589 ipv6: boolean (optional)
10591 whether to support IPv6, default true for enabled (since 2.6)
10592 ip: string (optional)
10594 legacy parameter, use net= instead
10595 net: string (optional)
10597 IP network address that the guest will see, in the form
10598 addr[/netmask] The netmask is optional, and can be either in the
10599 form a.b.c.d or as a number of valid top-most bits. Default is
10600 10.0.2.0/24.
10601 host: string (optional)
10603 guest-visible address of the host
10604 tftp: string (optional)
10606 root directory of the built-in TFTP server
10607 bootfile: string (optional)
10609 BOOTP filename, for use with tftp=
10610 dhcpstart: string (optional)
10612 the first of the 16 IPs the built-in DHCP server can assign
10613 dns: string (optional)
10615 guest-visible address of the virtual nameserver
10616 dnssearch: array of String (optional)
10618 list of DNS suffixes to search, passed as DHCP option to the
10619 guest
10620 domainname: string (optional)
10622 guest-visible domain name of the virtual nameserver (since 3.0)
10623 ipv6-prefix: string (optional)
10625 IPv6 network prefix (default is fec0::) (since 2.6). The network
10626 prefix is given in the usual hexadecimal IPv6 address notation.
10627 ipv6-prefixlen: int (optional)
10629 IPv6 network prefix length (default is 64) (since 2.6)
10630 ipv6-host: string (optional)
10632 guest-visible IPv6 address of the host (since 2.6)
10633 ipv6-dns: string (optional)
10635 guest-visible IPv6 address of the virtual nameserver (since 2.6)
10636 smb: string (optional)
10638 root directory of the built-in SMB server
10639 smbserver: string (optional)
10641 IP address of the built-in SMB server
10642 hostfwd: array of String (optional)
10644 redirect incoming TCP or UDP host connections to guest endpoints
10645 guestfwd: array of String (optional)
10647 forward guest TCP connections
10648 tftp-server-name: string (optional)
10650 RFC2132 "TFTP server name" string (Since 3.1)
10651 Since
10653 1.2
10654 NetdevTapOptions (Object)
10656 Used to configure a host TAP network interface backend.
10657 Members
10659 ifname: string (optional)
10660 interface name
10661 fd: string (optional)
10663 file descriptor of an already opened tap
10664 fds: string (optional)
10666 multiple file descriptors of already opened multiqueue capable
10667 tap
10668 script: string (optional)
10670 script to initialize the interface
10671 downscript: string (optional)
10673 script to shut down the interface
10674 br: string (optional)
10676 bridge name (since 2.8)
10677 helper: string (optional)
10679 command to execute to configure bridge
10680 sndbuf: int (optional)
10682 send buffer limit. Understands [TGMKkb] suffixes.
10683 vnet_hdr: boolean (optional)
10685 enable the IFF_VNET_HDR flag on the tap interface
10686 vhost: boolean (optional)
10688 enable vhost-net network accelerator
10689 vhostfd: string (optional)
10691 file descriptor of an already opened vhost net device
10692 vhostfds: string (optional)
10694 file descriptors of multiple already opened vhost net devices
10695 vhostforce: boolean (optional)
10697 vhost on for non-MSIX virtio guests
10698 queues: int (optional)
10700 number of queues to be created for multiqueue capable tap
10701 poll-us: int (optional)
10703 maximum number of microseconds that could be spent on busy
10704 polling for tap (since 2.7)
10705 Since
10707 1.2
10708 NetdevSocketOptions (Object)
10710 Socket netdevs are used to establish a network connection to another
10711 QEMU virtual machine via a TCP socket.
10712 Members
10714 fd: string (optional)
10715 file descriptor of an already opened socket
10716 listen: string (optional)
10718 port number, and optional hostname, to listen on
10719 connect: string (optional)
10721 port number, and optional hostname, to connect to
10722 mcast: string (optional)
10724 UDP multicast address and port number
10725 localaddr: string (optional)
10727 source address and port for multicast and udp packets
10728 udp: string (optional)
10730 UDP unicast address and port number
10731 Since
10733 1.2
10734 NetdevL2TPv3Options (Object)
10736 Configure an Ethernet over L2TPv3 tunnel.
10737 Members
10739 src: string
10740 source address
10741 dst: string
10743 destination address
10744 srcport: string (optional)
10746 source port - mandatory for udp, optional for ip
10747 dstport: string (optional)
10749 destination port - mandatory for udp, optional for ip
10750 ipv6: boolean (optional)
10752 force the use of ipv6
10753 udp: boolean (optional)
10755 use the udp version of l2tpv3 encapsulation
10756 cookie64: boolean (optional)
10758 use 64 bit coookies
10759 counter: boolean (optional)
10761 have sequence counter
10762 pincounter: boolean (optional)
10764 pin sequence counter to zero - workaround for buggy implementa‐
10765 tions or networks with packet reorder
10766 txcookie: int (optional)
10768 32 or 64 bit transmit cookie
10769 rxcookie: int (optional)
10771 32 or 64 bit receive cookie
10772 txsession: int
10774 32 bit transmit session
10775 rxsession: int (optional)
10777 32 bit receive session - if not specified set to the same value
10778 as transmit
10779 offset: int (optional)
10781 additional offset - allows the insertion of additional applica‐
10782 tion-specific data before the packet payload
10783 Since
10785 2.1
10786 NetdevVdeOptions (Object)
10788 Connect to a vde switch running on the host.
10789 Members
10791 sock: string (optional)
10792 socket path
10793 port: int (optional)
10795 port number
10796 group: string (optional)
10798 group owner of socket
10799 mode: int (optional)
10801 permissions for socket
10802 Since
10804 1.2
10805 NetdevBridgeOptions (Object)
10807 Connect a host TAP network interface to a host bridge device.
10808 Members
10810 br: string (optional)
10811 bridge name
10812 helper: string (optional)
10814 command to execute to configure bridge
10815 Since
10817 1.2
10818 NetdevHubPortOptions (Object)
10820 Connect two or more net clients through a software hub.
10821 Members
10823 hubid: int
10824 hub identifier number
10825 netdev: string (optional)
10827 used to connect hub to a netdev instead of a device (since 2.12)
10828 Since
10830 1.2
10831 NetdevNetmapOptions (Object)
10833 Connect a client to a netmap-enabled NIC or to a VALE switch port
10834 Members
10836 ifname: string
10837 Either the name of an existing network interface supported by
10838 netmap, or the name of a VALE port (created on the fly). A VALE
10839 port name is in the form 'valeXXX:YYY', where XXX and YYY are
10840 non-negative integers. XXX identifies a switch and YYY identi‐
10841 fies a port of the switch. VALE ports having the same XXX are
10842 therefore connected to the same switch.
10843 devname: string (optional)
10845 path of the netmap device (default: '/dev/netmap').
10846 Since
10848 2.0
10849 NetdevVhostUserOptions (Object)
10851 Vhost-user network backend
10852 Members
10854 chardev: string
10855 name of a unix socket chardev
10856 vhostforce: boolean (optional)
10858 vhost on for non-MSIX virtio guests (default: false).
10859 queues: int (optional)
10861 number of queues to be created for multiqueue vhost-user (de‐
10862 fault: 1) (Since 2.5)
10863 Since
10865 2.1
10866 NetdevVhostVDPAOptions (Object)
10868 Vhost-vdpa network backend
10869 vDPA device is a device that uses a datapath which complies with the
10871 virtio specifications with a vendor specific control path.
10872 Members
10874 vhostdev: string (optional)
10875 path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
10876 queues: int (optional)
10878 number of queues to be created for multiqueue vhost-vdpa (de‐
10879 fault: 1)
10880 Since
10882 5.1
10883 NetClientDriver (Enum)
10885 Available netdev drivers.
10886 Values
10888 none Not documented
10889 nic Not documented
10891 user Not documented
10893 tap Not documented
10895 l2tpv3 Not documented
10897 socket Not documented
10899 vde Not documented
10901 bridge Not documented
10903 hubport
10905 Not documented
10906 netmap Not documented
10908 vhost-user
10910 Not documented
10911 vhost-vdpa
10913 Not documented
10914 Since
10916 2.7
10917 vhost-vdpa since 5.1
10919 Netdev (Object)
10921 Captures the configuration of a network device.
10922 Members
10924 id: string
10925 identifier for monitor commands.
10926 type: NetClientDriver
10928 Specify the driver used for interpreting remaining arguments.
10929 The members of NetLegacyNicOptions when type is "nic"
10931 The members of NetdevUserOptions when type is "user"
10933 The members of NetdevTapOptions when type is "tap"
10935 The members of NetdevL2TPv3Options when type is "l2tpv3"
10937 The members of NetdevSocketOptions when type is "socket"
10939 The members of NetdevVdeOptions when type is "vde"
10941 The members of NetdevBridgeOptions when type is "bridge"
10943 The members of NetdevHubPortOptions when type is "hubport"
10945 The members of NetdevNetmapOptions when type is "netmap"
10947 The members of NetdevVhostUserOptions when type is "vhost-user"
10949 The members of NetdevVhostVDPAOptions when type is "vhost-vdpa"
10951 Since
10953 1.2
10954 'l2tpv3' - since 2.1
10956 RxState (Enum)
10958 Packets receiving state
10959 Values
10961 normal filter assigned packets according to the mac-table
10962 none don't receive any assigned packet
10964 all receive all assigned packets
10966 Since
10968 1.6
10969 RxFilterInfo (Object)
10971 Rx-filter information for a NIC.
10972 Members
10974 name: string
10975 net client name
10976 promiscuous: boolean
10978 whether promiscuous mode is enabled
10979 multicast: RxState
10981 multicast receive state
10982 unicast: RxState
10984 unicast receive state
10985 vlan: RxState
10987 vlan receive state (Since 2.0)
10988 broadcast-allowed: boolean
10990 whether to receive broadcast
10991 multicast-overflow: boolean
10993 multicast table is overflowed or not
10994 unicast-overflow: boolean
10996 unicast table is overflowed or not
10997 main-mac: string
10999 the main macaddr string
11000 vlan-table: array of int
11002 a list of active vlan id
11003 unicast-table: array of string
11005 a list of unicast macaddr string
11006 multicast-table: array of string
11008 a list of multicast macaddr string
11009 Since
11011 1.6
11012 query-rx-filter (Command)
11014 Return rx-filter information for all NICs (or for the given NIC).
11015 Arguments
11017 name: string (optional)
11018 net client name
11019 Returns
11021 list of RxFilterInfo for all NICs (or for the given NIC). Returns an
11022 error if the given name doesn't exist, or given NIC doesn't support
11023 rx-filter querying, or given net client isn't a NIC.
11024 Since
11026 1.6
11027 Example
11029 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
11030 <- { "return": [
11031 {
11032 "promiscuous": true,
11033 "name": "vnet0",
11034 "main-mac": "52:54:00:12:34:56",
11035 "unicast": "normal",
11036 "vlan": "normal",
11037 "vlan-table": [
11038 4,
11039 0
11040 ],
11041 "unicast-table": [
11042 ],
11043 "multicast": "normal",
11044 "multicast-overflow": false,
11045 "unicast-overflow": false,
11046 "multicast-table": [
11047 "01:00:5e:00:00:01",
11048 "33:33:00:00:00:01",
11049 "33:33:ff:12:34:56"
11050 ],
11051 "broadcast-allowed": false
11052 }
11053 ]
11054 }
11055 NIC_RX_FILTER_CHANGED (Event)
11057 Emitted once until the 'query-rx-filter' command is executed, the first
11058 event will always be emitted
11059 Arguments
11061 name: string (optional)
11062 net client name
11063 path: string
11065 device path
11066 Since
11068 1.6
11069 Example
11071 <- { "event": "NIC_RX_FILTER_CHANGED",
11072 "data": { "name": "vnet0",
11073 "path": "/machine/peripheral/vnet0/virtio-backend" },
11074 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
11075 }
11076 AnnounceParameters (Object)
11078 Parameters for self-announce timers
11079 Members
11081 initial: int
11082 Initial delay (in ms) before sending the first GARP/RARP an‐
11083 nouncement
11084 max: int
11086 Maximum delay (in ms) between GARP/RARP announcement packets
11087 rounds: int
11089 Number of self-announcement attempts
11090 step: int
11092 Delay increase (in ms) after each self-announcement attempt
11093 interfaces: array of string (optional)
11095 An optional list of interface names, which restricts the an‐
11096 nouncement to the listed interfaces. (Since 4.1)
11097 id: string (optional)
11099 A name to be used to identify an instance of announce-timers and
11100 to allow it to modified later. Not for use as part of the mi‐
11101 gration parameters. (Since 4.1)
11102 Since
11104 4.0
11105 announce-self (Command)
11107 Trigger generation of broadcast RARP frames to update network switches.
11108 This can be useful when network bonds fail-over the active slave.
11109 Arguments
11111 The members of AnnounceParameters
11112 Example
11114 -> { "execute": "announce-self",
11115 "arguments": {
11116 "initial": 50, "max": 550, "rounds": 10, "step": 50,
11117 "interfaces": ["vn2", "vn3"], "id": "bob" } }
11118 <- { "return": {} }
11119 Since
11121 4.0
11122 FAILOVER_NEGOTIATED (Event)
11124 Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotia‐
11125 tion. Failover primary devices which were hidden (not hotplugged when
11126 requested) before will now be hotplugged by the virtio-net standby de‐
11127 vice.
11128 device-id: QEMU device id of the unplugged device
11130 Arguments
11132 device-id: string
11133 Not documented
11134 Since
11136 4.2
11137 Example
11139 <- { "event": "FAILOVER_NEGOTIATED",
11140 "data": "net1" }
11141
11143 RDMA_GID_STATUS_CHANGED (Event)
11144 Emitted when guest driver adds/deletes GID to/from device
11145 Arguments
11147 netdev: string
11148 RoCE Network Device name
11149 gid-status: boolean
11151 Add or delete indication
11152 subnet-prefix: int
11154 Subnet Prefix
11155 interface-id: int
11157 Not documented
11158 interface-id : Interface ID
11159 Since
11161 4.0
11162 Example
11164 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
11165 "event": "RDMA_GID_STATUS_CHANGED",
11166 "data":
11167 {"netdev": "bridge0",
11168 "interface-id": 15880512517475447892,
11169 "gid-status": true,
11170 "subnet-prefix": 33022}}
11171
11173 RockerSwitch (Object)
11174 Rocker switch information.
11175 Members
11177 name: string
11178 switch name
11179 id: int
11181 switch ID
11182 ports: int
11184 number of front-panel ports
11185 Since
11187 2.4
11188 query-rocker (Command)
11190 Return rocker switch information.
11191 Arguments
11193 name: string
11194 Not documented
11195 Returns
11197 Rocker information
11198 Since
11200 2.4
11201 Example
11203 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
11204 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
11205 RockerPortDuplex (Enum)
11207 An eumeration of port duplex states.
11208 Values
11210 half half duplex
11211 full full duplex
11213 Since
11215 2.4
11216 RockerPortAutoneg (Enum)
11218 An eumeration of port autoneg states.
11219 Values
11221 off autoneg is off
11222 on autoneg is on
11224 Since
11226 2.4
11227 RockerPort (Object)
11229 Rocker switch port information.
11230 Members
11232 name: string
11233 port name
11234 enabled: boolean
11236 port is enabled for I/O
11237 link-up: boolean
11239 physical link is UP on port
11240 speed: int
11242 port link speed in Mbps
11243 duplex: RockerPortDuplex
11245 port link duplex
11246 autoneg: RockerPortAutoneg
11248 port link autoneg
11249 Since
11251 2.4
11252 query-rocker-ports (Command)
11254 Return rocker switch port information.
11255 Arguments
11257 name: string
11258 Not documented
11259 Returns
11261 a list of RockerPort information
11262 Since
11264 2.4
11265 Example
11267 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
11268 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
11269 "autoneg": "off", "link-up": true, "speed": 10000},
11270 {"duplex": "full", "enabled": true, "name": "sw1.2",
11271 "autoneg": "off", "link-up": true, "speed": 10000}
11272 ]}
11273 RockerOfDpaFlowKey (Object)
11275 Rocker switch OF-DPA flow key
11276 Members
11278 priority: int
11279 key priority, 0 being lowest priority
11280 tbl-id: int
11282 flow table ID
11283 in-pport: int (optional)
11285 physical input port
11286 tunnel-id: int (optional)
11288 tunnel ID
11289 vlan-id: int (optional)
11291 VLAN ID
11292 eth-type: int (optional)
11294 Ethernet header type
11295 eth-src: string (optional)
11297 Ethernet header source MAC address
11298 eth-dst: string (optional)
11300 Ethernet header destination MAC address
11301 ip-proto: int (optional)
11303 IP Header protocol field
11304 ip-tos: int (optional)
11306 IP header TOS field
11307 ip-dst: string (optional)
11309 IP header destination address
11310 Note
11312 optional members may or may not appear in the flow key depending if
11313 they're relevant to the flow key.
11314 Since
11316 2.4
11317 RockerOfDpaFlowMask (Object)
11319 Rocker switch OF-DPA flow mask
11320 Members
11322 in-pport: int (optional)
11323 physical input port
11324 tunnel-id: int (optional)
11326 tunnel ID
11327 vlan-id: int (optional)
11329 VLAN ID
11330 eth-src: string (optional)
11332 Ethernet header source MAC address
11333 eth-dst: string (optional)
11335 Ethernet header destination MAC address
11336 ip-proto: int (optional)
11338 IP Header protocol field
11339 ip-tos: int (optional)
11341 IP header TOS field
11342 Note
11344 optional members may or may not appear in the flow mask depending if
11345 they're relevant to the flow mask.
11346 Since
11348 2.4
11349 RockerOfDpaFlowAction (Object)
11351 Rocker switch OF-DPA flow action
11352 Members
11354 goto-tbl: int (optional)
11355 next table ID
11356 group-id: int (optional)
11358 group ID
11359 tunnel-lport: int (optional)
11361 tunnel logical port ID
11362 vlan-id: int (optional)
11364 VLAN ID
11365 new-vlan-id: int (optional)
11367 new VLAN ID
11368 out-pport: int (optional)
11370 physical output port
11371 Note
11373 optional members may or may not appear in the flow action depending if
11374 they're relevant to the flow action.
11375 Since
11377 2.4
11378 RockerOfDpaFlow (Object)
11380 Rocker switch OF-DPA flow
11381 Members
11383 cookie: int
11384 flow unique cookie ID
11385 hits: int
11387 count of matches (hits) on flow
11388 key: RockerOfDpaFlowKey
11390 flow key
11391 mask: RockerOfDpaFlowMask
11393 flow mask
11394 action: RockerOfDpaFlowAction
11396 flow action
11397 Since
11399 2.4
11400 query-rocker-of-dpa-flows (Command)
11402 Return rocker OF-DPA flow information.
11403 Arguments
11405 name: string
11406 switch name
11407 tbl-id: int (optional)
11409 flow table ID. If tbl-id is not specified, returns flow infor‐
11410 mation for all tables.
11411 Returns
11413 rocker OF-DPA flow information
11414 Since
11416 2.4
11417 Example
11419 -> { "execute": "query-rocker-of-dpa-flows",
11420 "arguments": { "name": "sw1" } }
11421 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
11422 "hits": 138,
11423 "cookie": 0,
11424 "action": {"goto-tbl": 10},
11425 "mask": {"in-pport": 4294901760}
11426 },
11427 {...more...},
11428 ]}
11429 RockerOfDpaGroup (Object)
11431 Rocker switch OF-DPA group
11432 Members
11434 id: int
11435 group unique ID
11436 type: int
11438 group type
11439 vlan-id: int (optional)
11441 VLAN ID
11442 pport: int (optional)
11444 physical port number
11445 index: int (optional)
11447 group index, unique with group type
11448 out-pport: int (optional)
11450 output physical port number
11451 group-id: int (optional)
11453 next group ID
11454 set-vlan-id: int (optional)
11456 VLAN ID to set
11457 pop-vlan: int (optional)
11459 pop VLAN headr from packet
11460 group-ids: array of int (optional)
11462 list of next group IDs
11463 set-eth-src: string (optional)
11465 set source MAC address in Ethernet header
11466 set-eth-dst: string (optional)
11468 set destination MAC address in Ethernet header
11469 ttl-check: int (optional)
11471 perform TTL check
11472 Note
11474 optional members may or may not appear in the group depending if
11475 they're relevant to the group type.
11476 Since
11478 2.4
11479 query-rocker-of-dpa-groups (Command)
11481 Return rocker OF-DPA group information.
11482 Arguments
11484 name: string
11485 switch name
11486 type: int (optional)
11488 group type. If type is not specified, returns group information
11489 for all group types.
11490 Returns
11492 rocker OF-DPA group information
11493 Since
11495 2.4
11496 Example
11498 -> { "execute": "query-rocker-of-dpa-groups",
11499 "arguments": { "name": "sw1" } }
11500 <- { "return": [ {"type": 0, "out-pport": 2,
11501 "pport": 2, "vlan-id": 3841,
11502 "pop-vlan": 1, "id": 251723778},
11503 {"type": 0, "out-pport": 0,
11504 "pport": 0, "vlan-id": 3841,
11505 "pop-vlan": 1, "id": 251723776},
11506 {"type": 0, "out-pport": 1,
11507 "pport": 1, "vlan-id": 3840,
11508 "pop-vlan": 1, "id": 251658241},
11509 {"type": 0, "out-pport": 0,
11510 "pport": 0, "vlan-id": 3840,
11511 "pop-vlan": 1, "id": 251658240}
11512 ]}
11513
11515 TpmModel (Enum)
11516 An enumeration of TPM models
11517 Values
11519 tpm-tis
11520 TPM TIS model
11521 tpm-crb
11523 TPM CRB model (since 2.12)
11524 tpm-spapr
11526 TPM SPAPR model (since 5.0)
11527 Since
11529 1.5
11530 If
11532 CONFIG_TPM
11533 query-tpm-models (Command)
11535 Return a list of supported TPM models
11536 Returns
11538 a list of TpmModel
11539 Since
11541 1.5
11542 Example
11544 -> { "execute": "query-tpm-models" }
11545 <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
11546 If
11548 CONFIG_TPM
11549 TpmType (Enum)
11551 An enumeration of TPM types
11552 Values
11554 passthrough
11555 TPM passthrough type
11556 emulator
11558 Software Emulator TPM type Since: 2.11
11559 Since
11561 1.5
11562 If
11564 CONFIG_TPM
11565 query-tpm-types (Command)
11567 Return a list of supported TPM types
11568 Returns
11570 a list of TpmType
11571 Since
11573 1.5
11574 Example
11576 -> { "execute": "query-tpm-types" }
11577 <- { "return": [ "passthrough", "emulator" ] }
11578 If
11580 CONFIG_TPM
11581 TPMPassthroughOptions (Object)
11583 Information about the TPM passthrough type
11584 Members
11586 path: string (optional)
11587 string describing the path used for accessing the TPM device
11588 cancel-path: string (optional)
11590 string showing the TPM's sysfs cancel file for cancellation of
11591 TPM commands while they are executing
11592 Since
11594 1.5
11595 If
11597 CONFIG_TPM
11598 TPMEmulatorOptions (Object)
11600 Information about the TPM emulator type
11601 Members
11603 chardev: string
11604 Name of a unix socket chardev
11605 Since
11607 2.11
11608 If
11610 CONFIG_TPM
11611 TPMPassthroughOptionsWrapper (Object)
11613 Members
11614 data: TPMPassthroughOptions
11615 Not documented
11616 Since
11618 1.5
11619 If
11621 CONFIG_TPM
11622 TPMEmulatorOptionsWrapper (Object)
11624 Members
11625 data: TPMEmulatorOptions
11626 Not documented
11627 Since
11629 2.11
11630 If
11632 CONFIG_TPM
11633 TpmTypeOptions (Object)
11635 A union referencing different TPM backend types' configuration options
11636 Members
11638 type: TpmType
11639 • 'passthrough' The configuration options for the TPM
11641 passthrough type
11642 • 'emulator' The configuration options for TPM emulator backend
11644 type
11645 The members of TPMPassthroughOptionsWrapper when type is "passthrough"
11647 The members of TPMEmulatorOptionsWrapper when type is "emulator"
11649 Since
11651 1.5
11652 If
11654 CONFIG_TPM
11655 TPMInfo (Object)
11657 Information about the TPM
11658 Members
11660 id: string
11661 The Id of the TPM
11662 model: TpmModel
11664 The TPM frontend model
11665 options: TpmTypeOptions
11667 The TPM (backend) type configuration options
11668 Since
11670 1.5
11671 If
11673 CONFIG_TPM
11674 query-tpm (Command)
11676 Return information about the TPM device
11677 Returns
11679 TPMInfo on success
11680 Since
11682 1.5
11683 Example
11685 -> { "execute": "query-tpm" }
11686 <- { "return":
11687 [
11688 { "model": "tpm-tis",
11689 "options":
11690 { "type": "passthrough",
11691 "data":
11692 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
11693 "path": "/dev/tpm0"
11694 }
11695 },
11696 "id": "tpm0"
11697 }
11698 ]
11699 }
11700 If
11702 CONFIG_TPM
11703
11705 set_password (Command)
11706 Sets the password of a remote display session.
11707 Arguments
11709 protocol: string
11710 • 'vnc' to modify the VNC server password
11712 • 'spice' to modify the Spice server password
11714 password: string
11716 the new password
11717 connected: string (optional)
11719 how to handle existing clients when changing the password. If
11720 nothing is specified, defaults to 'keep' 'fail' to fail the com‐
11721 mand if clients are connected 'disconnect' to disconnect exist‐
11722 ing clients 'keep' to maintain existing clients
11723 Returns
11725 • Nothing on success
11726 • If Spice is not enabled, DeviceNotFound
11728 Since
11730 0.14
11731 Example
11733 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
11734 "password": "secret" } }
11735 <- { "return": {} }
11736 expire_password (Command)
11738 Expire the password of a remote display server.
11739 Arguments
11741 protocol: string
11742 the name of the remote display protocol 'vnc' or 'spice'
11743 time: string
11745 when to expire the password.
11746 • 'now' to expire the password immediately
11748 • 'never' to cancel password expiration
11750 • '+INT' where INT is the number of seconds from now (integer)
11752 • 'INT' where INT is the absolute time in seconds
11754 Returns
11756 • Nothing on success
11757 • If protocol is 'spice' and Spice is not active, DeviceNotFound
11759 Since
11761 0.14
11762 Notes
11764 Time is relative to the server and currently there is no way to coordi‐
11765 nate server time with client time. It is not recommended to use the
11766 absolute time version of the time parameter unless you're sure you are
11767 on the same machine as the QEMU instance.
11768 Example
11770 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
11771 "time": "+60" } }
11772 <- { "return": {} }
11773 screendump (Command)
11775 Write a PPM of the VGA screen to a file.
11776 Arguments
11778 filename: string
11779 the path of a new PPM file to store the image
11780 device: string (optional)
11782 ID of the display device that should be dumped. If this parame‐
11783 ter is missing, the primary display will be used. (Since 2.12)
11784 head: int (optional)
11786 head to use in case the device supports multiple heads. If this
11787 parameter is missing, head #0 will be used. Also note that the
11788 head can only be specified in conjunction with the device ID.
11789 (Since 2.12)
11790 Returns
11792 Nothing on success
11793 Since
11795 0.14
11796 Example
11798 -> { "execute": "screendump",
11799 "arguments": { "filename": "/tmp/image" } }
11800 <- { "return": {} }
11801 Spice
11803 SpiceBasicInfo (Object)
11804 The basic information for SPICE network connection
11805 Members
11807 host: string
11808 IP address
11809 port: string
11811 port number
11812 family: NetworkAddressFamily
11814 address family
11815 Since
11817 2.1
11818 If
11820 CONFIG_SPICE
11821 SpiceServerInfo (Object)
11823 Information about a SPICE server
11824 Members
11826 auth: string (optional)
11827 authentication method
11828 The members of SpiceBasicInfo
11830 Since
11832 2.1
11833 If
11835 CONFIG_SPICE
11836 SpiceChannel (Object)
11838 Information about a SPICE client channel.
11839 Members
11841 connection-id: int
11842 SPICE connection id number. All channels with the same id be‐
11843 long to the same SPICE session.
11844 channel-type: int
11846 SPICE channel type number. "1" is the main control channel,
11847 filter for this one if you want to track spice sessions only
11848 channel-id: int
11850 SPICE channel ID number. Usually "0", might be different when
11851 multiple channels of the same type exist, such as multiple dis‐
11852 play channels in a multihead setup
11853 tls: boolean
11855 true if the channel is encrypted, false otherwise.
11856 The members of SpiceBasicInfo
11858 Since
11860 0.14
11861 If
11863 CONFIG_SPICE
11864 SpiceQueryMouseMode (Enum)
11866 An enumeration of Spice mouse states.
11867 Values
11869 client Mouse cursor position is determined by the client.
11870 server Mouse cursor position is determined by the server.
11872 unknown
11874 No information is available about mouse mode used by the spice
11875 server.
11876 Note
11878 spice/enums.h has a SpiceMouseMode already, hence the name.
11879 Since
11881 1.1
11882 If
11884 CONFIG_SPICE
11885 SpiceInfo (Object)
11887 Information about the SPICE session.
11888 Members
11890 enabled: boolean
11891 true if the SPICE server is enabled, false otherwise
11892 migrated: boolean
11894 true if the last guest migration completed and spice migration
11895 had completed as well. false otherwise. (since 1.4)
11896 host: string (optional)
11898 The hostname the SPICE server is bound to. This depends on the
11899 name resolution on the host and may be an IP address.
11900 port: int (optional)
11902 The SPICE server's port number.
11903 compiled-version: string (optional)
11905 SPICE server version.
11906 tls-port: int (optional)
11908 The SPICE server's TLS port number.
11909 auth: string (optional)
11911 the current authentication type used by the server
11912 • 'none' if no authentication is being used
11914 • 'spice' uses SASL or direct TLS authentication, depending on
11916 command line options
11917 mouse-mode: SpiceQueryMouseMode
11919 The mode in which the mouse cursor is displayed currently. Can
11920 be determined by the client or the server, or unknown if spice
11921 server doesn't provide this information. (since: 1.1)
11922 channels: array of SpiceChannel (optional)
11924 a list of SpiceChannel for each active spice channel
11925 Since
11927 0.14
11928 If
11930 CONFIG_SPICE
11931 query-spice (Command)
11933 Returns information about the current SPICE server
11934 Returns
11936 SpiceInfo
11937 Since
11939 0.14
11940 Example
11942 -> { "execute": "query-spice" }
11943 <- { "return": {
11944 "enabled": true,
11945 "auth": "spice",
11946 "port": 5920,
11947 "tls-port": 5921,
11948 "host": "0.0.0.0",
11949 "channels": [
11950 {
11951 "port": "54924",
11952 "family": "ipv4",
11953 "channel-type": 1,
11954 "connection-id": 1804289383,
11955 "host": "127.0.0.1",
11956 "channel-id": 0,
11957 "tls": true
11958 },
11959 {
11960 "port": "36710",
11961 "family": "ipv4",
11962 "channel-type": 4,
11963 "connection-id": 1804289383,
11964 "host": "127.0.0.1",
11965 "channel-id": 0,
11966 "tls": false
11967 },
11968 [ ... more channels follow ... ]
11969 ]
11970 }
11971 }
11972 If
11974 CONFIG_SPICE
11975 SPICE_CONNECTED (Event)
11977 Emitted when a SPICE client establishes a connection
11978 Arguments
11980 server: SpiceBasicInfo
11981 server information
11982 client: SpiceBasicInfo
11984 client information
11985 Since
11987 0.14
11988 Example
11990 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
11991 "event": "SPICE_CONNECTED",
11992 "data": {
11993 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
11994 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
11995 }}
11996 If
11998 CONFIG_SPICE
11999 SPICE_INITIALIZED (Event)
12001 Emitted after initial handshake and authentication takes place (if any)
12002 and the SPICE channel is up and running
12003 Arguments
12005 server: SpiceServerInfo
12006 server information
12007 client: SpiceChannel
12009 client information
12010 Since
12012 0.14
12013 Example
12015 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
12016 "event": "SPICE_INITIALIZED",
12017 "data": {"server": {"auth": "spice", "port": "5921",
12018 "family": "ipv4", "host": "127.0.0.1"},
12019 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
12020 "connection-id": 1804289383, "host": "127.0.0.1",
12021 "channel-id": 0, "tls": true}
12022 }}
12023 If
12025 CONFIG_SPICE
12026 SPICE_DISCONNECTED (Event)
12028 Emitted when the SPICE connection is closed
12029 Arguments
12031 server: SpiceBasicInfo
12032 server information
12033 client: SpiceBasicInfo
12035 client information
12036 Since
12038 0.14
12039 Example
12041 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
12042 "event": "SPICE_DISCONNECTED",
12043 "data": {
12044 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
12045 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
12046 }}
12047 If
12049 CONFIG_SPICE
12050 SPICE_MIGRATE_COMPLETED (Event)
12052 Emitted when SPICE migration has completed
12053 Since
12055 1.3
12056 Example
12058 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
12059 "event": "SPICE_MIGRATE_COMPLETED" }
12060 If
12062 CONFIG_SPICE
12063 VNC
12065 VncBasicInfo (Object)
12066 The basic information for vnc network connection
12067 Members
12069 host: string
12070 IP address
12071 service: string
12073 The service name of the vnc port. This may depend on the host
12074 system's service database so symbolic names should not be relied
12075 on.
12076 family: NetworkAddressFamily
12078 address family
12079 websocket: boolean
12081 true in case the socket is a websocket (since 2.3).
12082 Since
12084 2.1
12085 If
12087 CONFIG_VNC
12088 VncServerInfo (Object)
12090 The network connection information for server
12091 Members
12093 auth: string (optional)
12094 authentication method used for the plain (non-websocket) VNC
12095 server
12096 The members of VncBasicInfo
12098 Since
12100 2.1
12101 If
12103 CONFIG_VNC
12104 VncClientInfo (Object)
12106 Information about a connected VNC client.
12107 Members
12109 x509_dname: string (optional)
12110 If x509 authentication is in use, the Distinguished Name of the
12111 client.
12112 sasl_username: string (optional)
12114 If SASL authentication is in use, the SASL username used for au‐
12115 thentication.
12116 The members of VncBasicInfo
12118 Since
12120 0.14
12121 If
12123 CONFIG_VNC
12124 VncInfo (Object)
12126 Information about the VNC session.
12127 Members
12129 enabled: boolean
12130 true if the VNC server is enabled, false otherwise
12131 host: string (optional)
12133 The hostname the VNC server is bound to. This depends on the
12134 name resolution on the host and may be an IP address.
12135 family: NetworkAddressFamily (optional)
12137 • 'ipv6' if the host is listening for IPv6 connections
12139 • 'ipv4' if the host is listening for IPv4 connections
12141 • 'unix' if the host is listening on a unix domain socket
12143 • 'unknown' otherwise
12145 service: string (optional)
12147 The service name of the server's port. This may depends on the
12148 host system's service database so symbolic names should not be
12149 relied on.
12150 auth: string (optional)
12152 the current authentication type used by the server
12153 • 'none' if no authentication is being used
12155 • 'vnc' if VNC authentication is being used
12157 • 'vencrypt+plain' if VEncrypt is used with plain text authenti‐
12159 cation
12160 • 'vencrypt+tls+none' if VEncrypt is used with TLS and no au‐
12162 thentication
12163 • 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC au‐
12165 thentication
12166 • 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain
12168 text auth
12169 • 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
12171 • 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
12173 • 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain
12175 text auth
12176 • 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
12178 • 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
12180 auth
12181 clients: array of VncClientInfo (optional)
12183 a list of VncClientInfo of all currently connected clients
12184 Since
12186 0.14
12187 If
12189 CONFIG_VNC
12190 VncPrimaryAuth (Enum)
12192 vnc primary authentication method.
12193 Values
12195 none Not documented
12196 vnc Not documented
12198 ra2 Not documented
12200 ra2ne Not documented
12202 tight Not documented
12204 ultra Not documented
12206 tls Not documented
12208 vencrypt
12210 Not documented
12211 sasl Not documented
12213 Since
12215 2.3
12216 If
12218 CONFIG_VNC
12219 VncVencryptSubAuth (Enum)
12221 vnc sub authentication method with vencrypt.
12222 Values
12224 plain Not documented
12225 tls-none
12227 Not documented
12228 x509-none
12230 Not documented
12231 tls-vnc
12233 Not documented
12234 x509-vnc
12236 Not documented
12237 tls-plain
12239 Not documented
12240 x509-plain
12242 Not documented
12243 tls-sasl
12245 Not documented
12246 x509-sasl
12248 Not documented
12249 Since
12251 2.3
12252 If
12254 CONFIG_VNC
12255 VncServerInfo2 (Object)
12257 The network connection information for server
12258 Members
12260 auth: VncPrimaryAuth
12261 The current authentication type used by the servers
12262 vencrypt: VncVencryptSubAuth (optional)
12264 The vencrypt sub authentication type used by the servers, only
12265 specified in case auth == vencrypt.
12266 The members of VncBasicInfo
12268 Since
12270 2.9
12271 If
12273 CONFIG_VNC
12274 VncInfo2 (Object)
12276 Information about a vnc server
12277 Members
12279 id: string
12280 vnc server name.
12281 server: array of VncServerInfo2
12283 A list of VncBasincInfo describing all listening sockets. The
12284 list can be empty (in case the vnc server is disabled). It also
12285 may have multiple entries: normal + websocket, possibly also
12286 ipv4 + ipv6 in the future.
12287 clients: array of VncClientInfo
12289 A list of VncClientInfo of all currently connected clients. The
12290 list can be empty, for obvious reasons.
12291 auth: VncPrimaryAuth
12293 The current authentication type used by the non-websockets
12294 servers
12295 vencrypt: VncVencryptSubAuth (optional)
12297 The vencrypt authentication type used by the servers, only spec‐
12298 ified in case auth == vencrypt.
12299 display: string (optional)
12301 The display device the vnc server is linked to.
12302 Since
12304 2.3
12305 If
12307 CONFIG_VNC
12308 query-vnc (Command)
12310 Returns information about the current VNC server
12311 Returns
12313 VncInfo
12314 Since
12316 0.14
12317 Example
12319 -> { "execute": "query-vnc" }
12320 <- { "return": {
12321 "enabled":true,
12322 "host":"0.0.0.0",
12323 "service":"50402",
12324 "auth":"vnc",
12325 "family":"ipv4",
12326 "clients":[
12327 {
12328 "host":"127.0.0.1",
12329 "service":"50401",
12330 "family":"ipv4"
12331 }
12332 ]
12333 }
12334 }
12335 If
12337 CONFIG_VNC
12338 query-vnc-servers (Command)
12340 Returns a list of vnc servers. The list can be empty.
12341 Returns
12343 a list of VncInfo2
12344 Since
12346 2.3
12347 If
12349 CONFIG_VNC
12350 change-vnc-password (Command)
12352 Change the VNC server password.
12353 Arguments
12355 password: string
12356 the new password to use with VNC authentication
12357 Since
12359 1.1
12360 Notes
12362 An empty password in this command will set the password to the empty
12363 string. Existing clients are unaffected by executing this command.
12364 If
12366 CONFIG_VNC
12367 VNC_CONNECTED (Event)
12369 Emitted when a VNC client establishes a connection
12370 Arguments
12372 server: VncServerInfo
12373 server information
12374 client: VncBasicInfo
12376 client information
12377 Note
12379 This event is emitted before any authentication takes place, thus the
12380 authentication ID is not provided
12381 Since
12383 0.13
12384 Example
12386 <- { "event": "VNC_CONNECTED",
12387 "data": {
12388 "server": { "auth": "sasl", "family": "ipv4",
12389 "service": "5901", "host": "0.0.0.0" },
12390 "client": { "family": "ipv4", "service": "58425",
12391 "host": "127.0.0.1" } },
12392 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
12393 If
12395 CONFIG_VNC
12396 VNC_INITIALIZED (Event)
12398 Emitted after authentication takes place (if any) and the VNC session
12399 is made active
12400 Arguments
12402 server: VncServerInfo
12403 server information
12404 client: VncClientInfo
12406 client information
12407 Since
12409 0.13
12410 Example
12412 <- { "event": "VNC_INITIALIZED",
12413 "data": {
12414 "server": { "auth": "sasl", "family": "ipv4",
12415 "service": "5901", "host": "0.0.0.0"},
12416 "client": { "family": "ipv4", "service": "46089",
12417 "host": "127.0.0.1", "sasl_username": "luiz" } },
12418 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
12419 If
12421 CONFIG_VNC
12422 VNC_DISCONNECTED (Event)
12424 Emitted when the connection is closed
12425 Arguments
12427 server: VncServerInfo
12428 server information
12429 client: VncClientInfo
12431 client information
12432 Since
12434 0.13
12435 Example
12437 <- { "event": "VNC_DISCONNECTED",
12438 "data": {
12439 "server": { "auth": "sasl", "family": "ipv4",
12440 "service": "5901", "host": "0.0.0.0" },
12441 "client": { "family": "ipv4", "service": "58425",
12442 "host": "127.0.0.1", "sasl_username": "luiz" } },
12443 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
12444 If
12446 CONFIG_VNC
12447
12449 MouseInfo (Object)
12450 Information about a mouse device.
12451 Members
12453 name: string
12454 the name of the mouse device
12455 index: int
12457 the index of the mouse device
12458 current: boolean
12460 true if this device is currently receiving mouse events
12461 absolute: boolean
12463 true if this device supports absolute coordinates as input
12464 Since
12466 0.14
12467 query-mice (Command)
12469 Returns information about each active mouse device
12470 Returns
12472 a list of MouseInfo for each device
12473 Since
12475 0.14
12476 Example
12478 -> { "execute": "query-mice" }
12479 <- { "return": [
12480 {
12481 "name":"QEMU Microsoft Mouse",
12482 "index":0,
12483 "current":false,
12484 "absolute":false
12485 },
12486 {
12487 "name":"QEMU PS/2 Mouse",
12488 "index":1,
12489 "current":true,
12490 "absolute":true
12491 }
12492 ]
12493 }
12494 QKeyCode (Enum)
12496 An enumeration of key name.
12497 This is used by the send-key command.
12499 Values
12501 unmapped
12502 since 2.0
12503 pause since 2.0
12505 ro since 2.4
12507 kp_comma
12509 since 2.4
12510 kp_equals
12512 since 2.6
12513 power since 2.6
12515 hiragana
12517 since 2.9
12518 henkan since 2.9
12520 yen since 2.9
12522 sleep since 2.10
12524 wake since 2.10
12526 audionext
12528 since 2.10
12529 audioprev
12531 since 2.10
12532 audiostop
12534 since 2.10
12535 audioplay
12537 since 2.10
12538 audiomute
12540 since 2.10
12541 volumeup
12543 since 2.10
12544 volumedown
12546 since 2.10
12547 mediaselect
12549 since 2.10
12550 mail since 2.10
12552 calculator
12554 since 2.10
12555 computer
12557 since 2.10
12558 ac_home
12560 since 2.10
12561 ac_back
12563 since 2.10
12564 ac_forward
12566 since 2.10
12567 ac_refresh
12569 since 2.10
12570 ac_bookmarks
12572 since 2.10
12573 muhenkan
12575 since 2.12
12576 katakanahiragana
12578 since 2.12
12579 lang1 since 6.1
12581 lang2 since 6.1
12583 shift Not documented
12585 shift_r
12587 Not documented
12588 alt Not documented
12590 alt_r Not documented
12592 ctrl Not documented
12594 ctrl_r Not documented
12596 menu Not documented
12598 esc Not documented
12600 1 Not documented
12602 2 Not documented
12604 3 Not documented
12606 4 Not documented
12608 5 Not documented
12610 6 Not documented
12612 7 Not documented
12614 8 Not documented
12616 9 Not documented
12618 0 Not documented
12620 minus Not documented
12622 equal Not documented
12624 backspace
12626 Not documented
12627 tab Not documented
12629 q Not documented
12631 w Not documented
12633 e Not documented
12635 r Not documented
12637 t Not documented
12639 y Not documented
12641 u Not documented
12643 i Not documented
12645 o Not documented
12647 p Not documented
12649 bracket_left
12651 Not documented
12652 bracket_right
12654 Not documented
12655 ret Not documented
12657 a Not documented
12659 s Not documented
12661 d Not documented
12663 f Not documented
12665 g Not documented
12667 h Not documented
12669 j Not documented
12671 k Not documented
12673 l Not documented
12675 semicolon
12677 Not documented
12678 apostrophe
12680 Not documented
12681 grave_accent
12683 Not documented
12684 backslash
12686 Not documented
12687 z Not documented
12689 x Not documented
12691 c Not documented
12693 v Not documented
12695 b Not documented
12697 n Not documented
12699 m Not documented
12701 comma Not documented
12703 dot Not documented
12705 slash Not documented
12707 asterisk
12709 Not documented
12710 spc Not documented
12712 caps_lock
12714 Not documented
12715 f1 Not documented
12717 f2 Not documented
12719 f3 Not documented
12721 f4 Not documented
12723 f5 Not documented
12725 f6 Not documented
12727 f7 Not documented
12729 f8 Not documented
12731 f9 Not documented
12733 f10 Not documented
12735 num_lock
12737 Not documented
12738 scroll_lock
12740 Not documented
12741 kp_divide
12743 Not documented
12744 kp_multiply
12746 Not documented
12747 kp_subtract
12749 Not documented
12750 kp_add Not documented
12752 kp_enter
12754 Not documented
12755 kp_decimal
12757 Not documented
12758 sysrq Not documented
12760 kp_0 Not documented
12762 kp_1 Not documented
12764 kp_2 Not documented
12766 kp_3 Not documented
12768 kp_4 Not documented
12770 kp_5 Not documented
12772 kp_6 Not documented
12774 kp_7 Not documented
12776 kp_8 Not documented
12778 kp_9 Not documented
12780 less Not documented
12782 f11 Not documented
12784 f12 Not documented
12786 print Not documented
12788 home Not documented
12790 pgup Not documented
12792 pgdn Not documented
12794 end Not documented
12796 left Not documented
12798 up Not documented
12800 down Not documented
12802 right Not documented
12804 insert Not documented
12806 delete Not documented
12808 stop Not documented
12810 again Not documented
12812 props Not documented
12814 undo Not documented
12816 front Not documented
12818 copy Not documented
12820 open Not documented
12822 paste Not documented
12824 find Not documented
12826 cut Not documented
12828 lf Not documented
12830 help Not documented
12832 meta_l Not documented
12834 meta_r Not documented
12836 compose
12838 Not documented
12839 'sysrq' was mistakenly added to hack around the fact that the ps2
12840 driver was not generating correct scancodes sequences when 'alt+print'
12841 was pressed. This flaw is now fixed and the 'sysrq' key serves no fur‐
12842 ther purpose. Any further use of 'sysrq' will be transparently changed
12843 to 'print', so they are effectively synonyms.
12844 Since
12846 1.3
12847 KeyValueKind (Enum)
12849 Values
12850 number Not documented
12851 qcode Not documented
12853 Since
12855 1.3
12856 IntWrapper (Object)
12858 Members
12859 data: int
12860 Not documented
12861 Since
12863 1.3
12864 QKeyCodeWrapper (Object)
12866 Members
12867 data: QKeyCode
12868 Not documented
12869 Since
12871 1.3
12872 KeyValue (Object)
12874 Represents a keyboard key.
12875 Members
12877 type: KeyValueKind
12878 Not documented
12879 The members of IntWrapper when type is "number"
12881 The members of QKeyCodeWrapper when type is "qcode"
12883 Since
12885 1.3
12886 send-key (Command)
12888 Send keys to guest.
12889 Arguments
12891 keys: array of KeyValue
12892 An array of KeyValue elements. All KeyValues in this array are
12893 simultaneously sent to the guest. A KeyValue.number value is
12894 sent directly to the guest, while KeyValue.qcode must be a valid
12895 QKeyCode value
12896 hold-time: int (optional)
12898 time to delay key up events, milliseconds. Defaults to 100
12899 Returns
12901 • Nothing on success
12902 • If key is unknown or redundant, InvalidParameter
12904 Since
12906 1.3
12907 Example
12909 -> { "execute": "send-key",
12910 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
12911 { "type": "qcode", "data": "alt" },
12912 { "type": "qcode", "data": "delete" } ] } }
12913 <- { "return": {} }
12914 InputButton (Enum)
12916 Button of a pointer input device (mouse, tablet).
12917 Values
12919 side front side button of a 5-button mouse (since 2.9)
12920 extra rear side button of a 5-button mouse (since 2.9)
12922 left Not documented
12924 middle Not documented
12926 right Not documented
12928 wheel-up
12930 Not documented
12931 wheel-down
12933 Not documented
12934 Since
12936 2.0
12937 InputAxis (Enum)
12939 Position axis of a pointer input device (mouse, tablet).
12940 Values
12942 x Not documented
12943 y Not documented
12945 Since
12947 2.0
12948 InputKeyEvent (Object)
12950 Keyboard input event.
12951 Members
12953 key: KeyValue
12954 Which key this event is for.
12955 down: boolean
12957 True for key-down and false for key-up events.
12958 Since
12960 2.0
12961 InputBtnEvent (Object)
12963 Pointer button input event.
12964 Members
12966 button: InputButton
12967 Which button this event is for.
12968 down: boolean
12970 True for key-down and false for key-up events.
12971 Since
12973 2.0
12974 InputMoveEvent (Object)
12976 Pointer motion input event.
12977 Members
12979 axis: InputAxis
12980 Which axis is referenced by value.
12981 value: int
12983 Pointer position. For absolute coordinates the valid range is 0
12984 -> 0x7ffff
12985 Since
12987 2.0
12988 InputEventKind (Enum)
12990 Values
12991 key Not documented
12992 btn Not documented
12994 rel Not documented
12996 abs Not documented
12998 Since
13000 2.0
13001 InputKeyEventWrapper (Object)
13003 Members
13004 data: InputKeyEvent
13005 Not documented
13006 Since
13008 2.0
13009 InputBtnEventWrapper (Object)
13011 Members
13012 data: InputBtnEvent
13013 Not documented
13014 Since
13016 2.0
13017 InputMoveEventWrapper (Object)
13019 Members
13020 data: InputMoveEvent
13021 Not documented
13022 Since
13024 2.0
13025 InputEvent (Object)
13027 Input event union.
13028 Members
13030 type: InputEventKind
13031 the input type, one of:
13032 • 'key': Input event of Keyboard
13034 • 'btn': Input event of pointer buttons
13036 • 'rel': Input event of relative pointer motion
13038 • 'abs': Input event of absolute pointer motion
13040 The members of InputKeyEventWrapper when type is "key"
13042 The members of InputBtnEventWrapper when type is "btn"
13044 The members of InputMoveEventWrapper when type is "rel"
13046 The members of InputMoveEventWrapper when type is "abs"
13048 Since
13050 2.0
13051 input-send-event (Command)
13053 Send input event(s) to guest.
13054 The device and head parameters can be used to send the input event to
13056 specific input devices in case (a) multiple input devices of the same
13057 kind are added to the virtual machine and (b) you have configured input
13058 routing (see docs/multiseat.txt) for those input devices. The parame‐
13059 ters work exactly like the device and head properties of input devices.
13060 If device is missing, only devices that have no input routing config
13061 are admissible. If device is specified, both input devices with and
13062 without input routing config are admissible, but devices with input
13063 routing config take precedence.
13064 Arguments
13066 device: string (optional)
13067 display device to send event(s) to.
13068 head: int (optional)
13070 head to send event(s) to, in case the display device supports
13071 multiple scanouts.
13072 events: array of InputEvent
13074 List of InputEvent union.
13075 Returns
13077 Nothing on success.
13078 Since
13080 2.6
13081 Note
13083 The consoles are visible in the qom tree, under /backend/console[$in‐
13084 dex]. They have a device link and head property, so it is possible to
13085 map which console belongs to which device and display.
13086 Example
13088 1. Press left mouse button.
13089 -> { "execute": "input-send-event",
13091 "arguments": { "device": "video0",
13092 "events": [ { "type": "btn",
13093 "data" : { "down": true, "button": "left" } } ] } }
13094 <- { "return": {} }
13095 -> { "execute": "input-send-event",
13097 "arguments": { "device": "video0",
13098 "events": [ { "type": "btn",
13099 "data" : { "down": false, "button": "left" } } ] } }
13100 <- { "return": {} }
13101 2. Press ctrl-alt-del.
13103 -> { "execute": "input-send-event",
13105 "arguments": { "events": [
13106 { "type": "key", "data" : { "down": true,
13107 "key": {"type": "qcode", "data": "ctrl" } } },
13108 { "type": "key", "data" : { "down": true,
13109 "key": {"type": "qcode", "data": "alt" } } },
13110 { "type": "key", "data" : { "down": true,
13111 "key": {"type": "qcode", "data": "delete" } } } ] } }
13112 <- { "return": {} }
13113 3. Move mouse pointer to absolute coordinates (20000, 400).
13115 -> { "execute": "input-send-event" ,
13117 "arguments": { "events": [
13118 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
13119 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
13120 <- { "return": {} }
13121 DisplayGTK (Object)
13123 GTK display options.
13124 Members
13126 grab-on-hover: boolean (optional)
13127 Grab keyboard input on mouse hover.
13128 zoom-to-fit: boolean (optional)
13130 Zoom guest display to fit into the host window. When turned off
13131 the host window will be resized instead. In case the display
13132 device can notify the guest on window resizes (virtio-gpu) this
13133 will default to "on", assuming the guest will resize the display
13134 to match the window size then. Otherwise it defaults to "off".
13135 Since 3.1
13136 Since
13138 2.12
13139 DisplayEGLHeadless (Object)
13141 EGL headless display options.
13142 Members
13144 rendernode: string (optional)
13145 Which DRM render node should be used. Default is the first
13146 available node on the host.
13147 Since
13149 3.1
13150 DisplayGLMode (Enum)
13152 Display OpenGL mode.
13153 Values
13155 off Disable OpenGL (default).
13156 on Use OpenGL, pick context type automatically. Would better be
13158 named 'auto' but is called 'on' for backward compatibility with
13159 bool type.
13160 core Use OpenGL with Core (desktop) Context.
13162 es Use OpenGL with ES (embedded systems) Context.
13164 Since
13166 3.0
13167 DisplayCurses (Object)
13169 Curses display options.
13170 Members
13172 charset: string (optional)
13173 Font charset used by guest (default: CP437).
13174 Since
13176 4.0
13177 DisplayType (Enum)
13179 Display (user interface) type.
13180 Values
13182 default
13183 The default user interface, selecting from the first available
13184 of gtk, sdl, cocoa, and vnc.
13185 none No user interface or video output display. The guest will still
13187 see an emulated graphics card, but its output will not be dis‐
13188 played to the QEMU user.
13189 gtk (If: CONFIG_GTK)
13191 The GTK user interface.
13192 sdl (If: CONFIG_SDL)
13194 The SDL user interface.
13195 egl-headless (If: CONFIG_OPENGL and CONFIG_GBM)
13197 No user interface, offload GL operations to a local DRI device.
13198 Graphical display need to be paired with VNC or Spice. (Since
13199 3.1)
13200 curses (If: CONFIG_CURSES)
13202 Display video output via curses. For graphics device models
13203 which support a text mode, QEMU can display this output using a
13204 curses/ncurses interface. Nothing is displayed when the graphics
13205 device is in graphical mode or if the graphics device does not
13206 support a text mode. Generally only the VGA device models sup‐
13207 port text mode.
13208 cocoa (If: CONFIG_COCOA)
13210 The Cocoa user interface.
13211 spice-app (If: CONFIG_SPICE)
13213 Set up a Spice server and run the default associated application
13214 to connect to it. The server will redirect the serial console
13215 and QEMU monitors. (Since 4.0)
13216 Since
13218 2.12
13219 DisplayOptions (Object)
13221 Display (user interface) options.
13222 Members
13224 type: DisplayType
13225 Which DisplayType qemu should use.
13226 full-screen: boolean (optional)
13228 Start user interface in fullscreen mode (default: off).
13229 window-close: boolean (optional)
13231 Allow to quit qemu with window close button (default: on).
13232 show-cursor: boolean (optional)
13234 Force showing the mouse cursor (default: off). (since: 5.0)
13235 gl: DisplayGLMode (optional)
13237 Enable OpenGL support (default: off).
13238 The members of DisplayGTK when type is "gtk" (If: CONFIG_GTK)
13240 The members of DisplayCurses when type is "curses" (If: CONFIG_CURSES)
13242 The members of DisplayEGLHeadless when type is "egl-headless" (If: CON‐
13244 FIG_OPENGL and CONFIG_GBM)
13245 Since
13247 2.12
13248 query-display-options (Command)
13250 Returns information about display configuration
13251 Returns
13253 DisplayOptions
13254 Since
13256 3.1
13257 DisplayReloadType (Enum)
13259 Available DisplayReload types.
13260 Values
13262 vnc VNC display
13263 Since
13265 6.0
13266 DisplayReloadOptionsVNC (Object)
13268 Specify the VNC reload options.
13269 Members
13271 tls-certs: boolean (optional)
13272 reload tls certs or not.
13273 Since
13275 6.0
13276 DisplayReloadOptions (Object)
13278 Options of the display configuration reload.
13279 Members
13281 type: DisplayReloadType
13282 Specify the display type.
13283 The members of DisplayReloadOptionsVNC when type is "vnc"
13285 Since
13287 6.0
13288 display-reload (Command)
13290 Reload display configuration.
13291 Arguments
13293 The members of DisplayReloadOptions
13294 Returns
13296 Nothing on success.
13297 Since
13299 6.0
13300 Example
13302 -> { "execute": "display-reload",
13303 "arguments": { "type": "vnc", "tls-certs": true } }
13304 <- { "return": {} }
13305
13307 QAuthZListPolicy (Enum)
13308 The authorization policy result
13309 Values
13311 deny deny access
13312 allow allow access
13314 Since
13316 4.0
13317 QAuthZListFormat (Enum)
13319 The authorization policy match format
13320 Values
13322 exact an exact string match
13323 glob string with ? and * shell wildcard support
13325 Since
13327 4.0
13328 QAuthZListRule (Object)
13330 A single authorization rule.
13331 Members
13333 match: string
13334 a string or glob to match against a user identity
13335 policy: QAuthZListPolicy
13337 the result to return if match evaluates to true
13338 format: QAuthZListFormat (optional)
13340 the format of the match rule (default 'exact')
13341 Since
13343 4.0
13344 AuthZListProperties (Object)
13346 Properties for authz-list objects.
13347 Members
13349 policy: QAuthZListPolicy (optional)
13350 Default policy to apply when no rule matches (default: deny)
13351 rules: array of QAuthZListRule (optional)
13353 Authorization rules based on matching user
13354 Since
13356 4.0
13357 AuthZListFileProperties (Object)
13359 Properties for authz-listfile objects.
13360 Members
13362 filename: string
13363 File name to load the configuration from. The file must contain
13364 valid JSON for AuthZListProperties.
13365 refresh: boolean (optional)
13367 If true, inotify is used to monitor the file, automatically
13368 reloading changes. If an error occurs during reloading, all au‐
13369 thorizations will fail until the file is next successfully
13370 loaded. (default: true if the binary was built with CONFIG_INO‐
13371 TIFY1, false otherwise)
13372 Since
13374 4.0
13375 AuthZPAMProperties (Object)
13377 Properties for authz-pam objects.
13378 Members
13380 service: string
13381 PAM service name to use for authorization
13382 Since
13384 4.0
13385 AuthZSimpleProperties (Object)
13387 Properties for authz-simple objects.
13388 Members
13390 identity: string
13391 Identifies the allowed user. Its format depends on the network
13392 service that authorization object is associated with. For autho‐
13393 rizing based on TLS x509 certificates, the identity must be the
13394 x509 distinguished name.
13395 Since
13397 4.0
13398
13400 MigrationStats (Object)
13401 Detailed migration status.
13402 Members
13404 transferred: int
13405 amount of bytes already transferred to the target VM
13406 remaining: int
13408 amount of bytes remaining to be transferred to the target VM
13409 total: int
13411 total amount of bytes involved in the migration process
13412 duplicate: int
13414 number of duplicate (zero) pages (since 1.2)
13415 skipped: int
13417 number of skipped zero pages (since 1.5)
13418 normal: int
13420 number of normal pages (since 1.2)
13421 normal-bytes: int
13423 number of normal bytes sent (since 1.2)
13424 dirty-pages-rate: int
13426 number of pages dirtied by second by the guest (since 1.3)
13427 mbps: number
13429 throughput in megabits/sec. (since 1.6)
13430 dirty-sync-count: int
13432 number of times that dirty ram was synchronized (since 2.1)
13433 postcopy-requests: int
13435 The number of page requests received from the destination (since
13436 2.7)
13437 page-size: int
13439 The number of bytes per page for the various page-based statis‐
13440 tics (since 2.10)
13441 multifd-bytes: int
13443 The number of bytes sent through multifd (since 3.0)
13444 pages-per-second: int
13446 the number of memory pages transferred per second (Since 4.0)
13447 Since
13449 0.14
13450 XBZRLECacheStats (Object)
13452 Detailed XBZRLE migration cache statistics
13453 Members
13455 cache-size: int
13456 XBZRLE cache size
13457 bytes: int
13459 amount of bytes already transferred to the target VM
13460 pages: int
13462 amount of pages transferred to the target VM
13463 cache-miss: int
13465 number of cache miss
13466 cache-miss-rate: number
13468 rate of cache miss (since 2.1)
13469 encoding-rate: number
13471 rate of encoded bytes (since 5.1)
13472 overflow: int
13474 number of overflows
13475 Since
13477 1.2
13478 CompressionStats (Object)
13480 Detailed migration compression statistics
13481 Members
13483 pages: int
13484 amount of pages compressed and transferred to the target VM
13485 busy: int
13487 count of times that no free thread was available to compress
13488 data
13489 busy-rate: number
13491 rate of thread busy
13492 compressed-size: int
13494 amount of bytes after compression
13495 compression-rate: number
13497 rate of compressed size
13498 Since
13500 3.1
13501 MigrationStatus (Enum)
13503 An enumeration of migration status.
13504 Values
13506 none no migration has ever happened.
13507 setup migration process has been initiated.
13509 cancelling
13511 in the process of cancelling migration.
13512 cancelled
13514 cancelling migration is finished.
13515 active in the process of doing migration.
13517 postcopy-active
13519 like active, but now in postcopy mode. (since 2.5)
13520 postcopy-paused
13522 during postcopy but paused. (since 3.0)
13523 postcopy-recover
13525 trying to recover from a paused postcopy. (since 3.0)
13526 completed
13528 migration is finished.
13529 failed some error occurred during migration process.
13531 colo VM is in the process of fault tolerance, VM can not get into
13533 this state unless colo capability is enabled for migration.
13534 (since 2.8)
13535 pre-switchover
13537 Paused before device serialisation. (since 2.11)
13538 device During device serialisation when pause-before-switchover is en‐
13540 abled (since 2.11)
13541 wait-unplug
13543 wait for device unplug request by guest OS to be completed.
13544 (since 4.2)
13545 Since
13547 2.3
13548 VfioStats (Object)
13550 Detailed VFIO devices migration statistics
13551 Members
13553 transferred: int
13554 amount of bytes transferred to the target VM by VFIO devices
13555 Since
13557 5.2
13558 MigrationInfo (Object)
13560 Information about current migration process.
13561 Members
13563 status: MigrationStatus (optional)
13564 MigrationStatus describing the current migration status. If
13565 this field is not returned, no migration process has been initi‐
13566 ated
13567 ram: MigrationStats (optional)
13569 MigrationStats containing detailed migration status, only re‐
13570 turned if status is 'active' or 'completed'(since 1.2)
13571 disk: MigrationStats (optional)
13573 MigrationStats containing detailed disk migration status, only
13574 returned if status is 'active' and it is a block migration
13575 xbzrle-cache: XBZRLECacheStats (optional)
13577 XBZRLECacheStats containing detailed XBZRLE migration statis‐
13578 tics, only returned if XBZRLE feature is on and status is 'ac‐
13579 tive' or 'completed' (since 1.2)
13580 total-time: int (optional)
13582 total amount of milliseconds since migration started. If migra‐
13583 tion has ended, it returns the total migration time. (since 1.2)
13584 downtime: int (optional)
13586 only present when migration finishes correctly total downtime in
13587 milliseconds for the guest. (since 1.3)
13588 expected-downtime: int (optional)
13590 only present while migration is active expected downtime in mil‐
13591 liseconds for the guest in last walk of the dirty bitmap. (since
13592 1.3)
13593 setup-time: int (optional)
13595 amount of setup time in milliseconds before the iterations begin
13596 but after the QMP command is issued. This is designed to provide
13597 an accounting of any activities (such as RDMA pinning) which may
13598 be expensive, but do not actually occur during the iterative mi‐
13599 gration rounds themselves. (since 1.6)
13600 cpu-throttle-percentage: int (optional)
13602 percentage of time guest cpus are being throttled during
13603 auto-converge. This is only present when auto-converge has
13604 started throttling guest cpus. (Since 2.7)
13605 error-desc: string (optional)
13607 the human readable error description string, when status is
13608 'failed'. Clients should not attempt to parse the error strings.
13609 (Since 2.7)
13610 postcopy-blocktime: int (optional)
13612 total time when all vCPU were blocked during postcopy live mi‐
13613 gration. This is only present when the postcopy-blocktime migra‐
13614 tion capability is enabled. (Since 3.0)
13615 postcopy-vcpu-blocktime: array of int (optional)
13617 list of the postcopy blocktime per vCPU. This is only present
13618 when the postcopy-blocktime migration capability is enabled.
13619 (Since 3.0)
13620 compression: CompressionStats (optional)
13622 migration compression statistics, only returned if compression
13623 feature is on and status is 'active' or 'completed' (Since 3.1)
13624 socket-address: array of SocketAddress (optional)
13626 Only used for tcp, to know what the real port is (Since 4.0)
13627 vfio: VfioStats (optional)
13629 VfioStats containing detailed VFIO devices migration statistics,
13630 only returned if VFIO device is present, migration is supported
13631 by all VFIO devices and status is 'active' or 'completed' (since
13632 5.2)
13633 blocked-reasons: array of string (optional)
13635 A list of reasons an outgoing migration is blocked. Present and
13636 non-empty when migration is blocked. (since 6.0)
13637 Since
13639 0.14
13640 query-migrate (Command)
13642 Returns information about current migration process. If migration is
13643 active there will be another json-object with RAM migration status and
13644 if block migration is active another one with block migration status.
13645 Returns
13647 MigrationInfo
13648 Since
13650 0.14
13651 Example
13653 1. Before the first migration
13654 -> { "execute": "query-migrate" }
13656 <- { "return": {} }
13657 2. Migration is done and has succeeded
13659 -> { "execute": "query-migrate" }
13661 <- { "return": {
13662 "status": "completed",
13663 "total-time":12345,
13664 "setup-time":12345,
13665 "downtime":12345,
13666 "ram":{
13667 "transferred":123,
13668 "remaining":123,
13669 "total":246,
13670 "duplicate":123,
13671 "normal":123,
13672 "normal-bytes":123456,
13673 "dirty-sync-count":15
13674 }
13675 }
13676 }
13677 3. Migration is done and has failed
13679 -> { "execute": "query-migrate" }
13681 <- { "return": { "status": "failed" } }
13682 4. Migration is being performed and is not a block migration:
13684 -> { "execute": "query-migrate" }
13686 <- {
13687 "return":{
13688 "status":"active",
13689 "total-time":12345,
13690 "setup-time":12345,
13691 "expected-downtime":12345,
13692 "ram":{
13693 "transferred":123,
13694 "remaining":123,
13695 "total":246,
13696 "duplicate":123,
13697 "normal":123,
13698 "normal-bytes":123456,
13699 "dirty-sync-count":15
13700 }
13701 }
13702 }
13703 5. Migration is being performed and is a block migration:
13705 -> { "execute": "query-migrate" }
13707 <- {
13708 "return":{
13709 "status":"active",
13710 "total-time":12345,
13711 "setup-time":12345,
13712 "expected-downtime":12345,
13713 "ram":{
13714 "total":1057024,
13715 "remaining":1053304,
13716 "transferred":3720,
13717 "duplicate":123,
13718 "normal":123,
13719 "normal-bytes":123456,
13720 "dirty-sync-count":15
13721 },
13722 "disk":{
13723 "total":20971520,
13724 "remaining":20880384,
13725 "transferred":91136
13726 }
13727 }
13728 }
13729 6. Migration is being performed and XBZRLE is active:
13731 -> { "execute": "query-migrate" }
13733 <- {
13734 "return":{
13735 "status":"active",
13736 "total-time":12345,
13737 "setup-time":12345,
13738 "expected-downtime":12345,
13739 "ram":{
13740 "total":1057024,
13741 "remaining":1053304,
13742 "transferred":3720,
13743 "duplicate":10,
13744 "normal":3333,
13745 "normal-bytes":3412992,
13746 "dirty-sync-count":15
13747 },
13748 "xbzrle-cache":{
13749 "cache-size":67108864,
13750 "bytes":20971520,
13751 "pages":2444343,
13752 "cache-miss":2244,
13753 "cache-miss-rate":0.123,
13754 "encoding-rate":80.1,
13755 "overflow":34434
13756 }
13757 }
13758 }
13759 MigrationCapability (Enum)
13761 Migration capabilities enumeration
13762 Values
13764 xbzrle Migration supports xbzrle (Xor Based Zero Run Length Encoding).
13765 This feature allows us to minimize migration traffic for certain
13766 work loads, by sending compressed difference of the pages
13767 rdma-pin-all
13769 Controls whether or not the entire VM memory footprint is
13770 mlock()'d on demand or all at once. Refer to docs/rdma.txt for
13771 usage. Disabled by default. (since 2.0)
13772 zero-blocks
13774 During storage migration encode blocks of zeroes efficiently.
13775 This essentially saves 1MB of zeroes per block on the wire. En‐
13776 abling requires source and target VM to support this feature. To
13777 enable it is sufficient to enable the capability on the source
13778 VM. The feature is disabled by default. (since 1.6)
13779 compress
13781 Use multiple compression threads to accelerate live migration.
13782 This feature can help to reduce the migration traffic, by send‐
13783 ing compressed pages. Please note that if compress and xbzrle
13784 are both on, compress only takes effect in the ram bulk stage,
13785 after that, it will be disabled and only xbzrle takes effect,
13786 this can help to minimize migration traffic. The feature is dis‐
13787 abled by default. (since 2.4 )
13788 events generate events for each migration state change (since 2.4 )
13790 auto-converge
13792 If enabled, QEMU will automatically throttle down the guest to
13793 speed up convergence of RAM migration. (since 1.6)
13794 postcopy-ram
13796 Start executing on the migration target before all of RAM has
13797 been migrated, pulling the remaining pages along as needed. The
13798 capacity must have the same setting on both source and target or
13799 migration will not even start. NOTE: If the migration fails dur‐
13800 ing postcopy the VM will fail. (since 2.6)
13801 x-colo If enabled, migration will never end, and the state of the VM on
13803 the primary side will be migrated continuously to the VM on sec‐
13804 ondary side, this process is called COarse-Grain LOck Stepping
13805 (COLO) for Non-stop Service. (since 2.8)
13806 release-ram
13808 if enabled, qemu will free the migrated ram pages on the source
13809 during postcopy-ram migration. (since 2.9)
13810 block If enabled, QEMU will also migrate the contents of all block de‐
13812 vices. Default is disabled. A possible alternative uses mirror
13813 jobs to a builtin NBD server on the destination, which offers
13814 more flexibility. (Since 2.10)
13815 return-path
13817 If enabled, migration will use the return path even for precopy.
13818 (since 2.10)
13819 pause-before-switchover
13821 Pause outgoing migration before serialising device state and be‐
13822 fore disabling block IO (since 2.11)
13823 multifd
13825 Use more than one fd for migration (since 4.0)
13826 dirty-bitmaps
13828 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
13829 postcopy-blocktime
13831 Calculate downtime for postcopy live migration (since 3.0)
13832 late-block-activate
13834 If enabled, the destination will not activate block devices (and
13835 thus take locks) immediately at the end of migration. (since
13836 3.0)
13837 x-ignore-shared
13839 If enabled, QEMU will not migrate shared memory (since 4.0)
13840 validate-uuid
13842 Send the UUID of the source to allow the destination to ensure
13843 it is the same. (since 4.2)
13844 background-snapshot
13846 If enabled, the migration stream will be a snapshot of the VM
13847 exactly at the point when the migration procedure starts. The VM
13848 RAM is saved with running VM. (since 6.0)
13849 Features
13851 unstable
13852 Members x-colo and x-ignore-shared are experimental.
13853 Since
13855 1.2
13856 MigrationCapabilityStatus (Object)
13858 Migration capability information
13859 Members
13861 capability: MigrationCapability
13862 capability enum
13863 state: boolean
13865 capability state bool
13866 Since
13868 1.2
13869 migrate-set-capabilities (Command)
13871 Enable/Disable the following migration capabilities (like xbzrle)
13872 Arguments
13874 capabilities: array of MigrationCapabilityStatus
13875 json array of capability modifications to make
13876 Since
13878 1.2
13879 Example
13881 -> { "execute": "migrate-set-capabilities" , "arguments":
13882 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
13883 query-migrate-capabilities (Command)
13885 Returns information about the current migration capabilities status
13886 Returns
13888 MigrationCapabilitiesStatus
13889 Since
13891 1.2
13892 Example
13894 -> { "execute": "query-migrate-capabilities" }
13895 <- { "return": [
13896 {"state": false, "capability": "xbzrle"},
13897 {"state": false, "capability": "rdma-pin-all"},
13898 {"state": false, "capability": "auto-converge"},
13899 {"state": false, "capability": "zero-blocks"},
13900 {"state": false, "capability": "compress"},
13901 {"state": true, "capability": "events"},
13902 {"state": false, "capability": "postcopy-ram"},
13903 {"state": false, "capability": "x-colo"}
13904 ]}
13905 MultiFDCompression (Enum)
13907 An enumeration of multifd compression methods.
13908 Values
13910 none no compression.
13911 zlib use zlib compression method.
13913 zstd (If: CONFIG_ZSTD)
13915 use zstd compression method.
13916 Since
13918 5.0
13919 BitmapMigrationBitmapAliasTransform (Object)
13921 Members
13922 persistent: boolean (optional)
13923 If present, the bitmap will be made persistent or transient de‐
13924 pending on this parameter.
13925 Since
13927 6.0
13928 BitmapMigrationBitmapAlias (Object)
13930 Members
13931 name: string
13932 The name of the bitmap.
13933 alias: string
13935 An alias name for migration (for example the bitmap name on the
13936 opposite site).
13937 transform: BitmapMigrationBitmapAliasTransform (optional)
13939 Allows the modification of the migrated bitmap. (since 6.0)
13940 Since
13942 5.2
13943 BitmapMigrationNodeAlias (Object)
13945 Maps a block node name and the bitmaps it has to aliases for dirty bit‐
13946 map migration.
13947 Members
13949 node-name: string
13950 A block node name.
13951 alias: string
13953 An alias block node name for migration (for example the node
13954 name on the opposite site).
13955 bitmaps: array of BitmapMigrationBitmapAlias
13957 Mappings for the bitmaps on this node.
13958 Since
13960 5.2
13961 MigrationParameter (Enum)
13963 Migration parameters enumeration
13964 Values
13966 announce-initial
13967 Initial delay (in milliseconds) before sending the first an‐
13968 nounce (Since 4.0)
13969 announce-max
13971 Maximum delay (in milliseconds) between packets in the announce‐
13972 ment (Since 4.0)
13973 announce-rounds
13975 Number of self-announce packets sent after migration (Since 4.0)
13976 announce-step
13978 Increase in delay (in milliseconds) between subsequent packets
13979 in the announcement (Since 4.0)
13980 compress-level
13982 Set the compression level to be used in live migration, the com‐
13983 pression level is an integer between 0 and 9, where 0 means no
13984 compression, 1 means the best compression speed, and 9 means
13985 best compression ratio which will consume more CPU.
13986 compress-threads
13988 Set compression thread count to be used in live migration, the
13989 compression thread count is an integer between 1 and 255.
13990 compress-wait-thread
13992 Controls behavior when all compression threads are currently
13993 busy. If true (default), wait for a free compression thread to
13994 become available; otherwise, send the page uncompressed. (Since
13995 3.1)
13996 decompress-threads
13998 Set decompression thread count to be used in live migration, the
13999 decompression thread count is an integer between 1 and 255. Usu‐
14000 ally, decompression is at least 4 times as fast as compression,
14001 so set the decompress-threads to the number about 1/4 of com‐
14002 press-threads is adequate.
14003 throttle-trigger-threshold
14005 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
14006 throttling. It is expressed as percentage. The default value is
14007 50. (Since 5.0)
14008 cpu-throttle-initial
14010 Initial percentage of time guest cpus are throttled when migra‐
14011 tion auto-converge is activated. The default value is 20. (Since
14012 2.7)
14013 cpu-throttle-increment
14015 throttle percentage increase each time auto-converge detects
14016 that migration is not making progress. The default value is 10.
14017 (Since 2.7)
14018 cpu-throttle-tailslow
14020 Make CPU throttling slower at tail stage At the tail stage of
14021 throttling, the Guest is very sensitive to CPU percentage while
14022 the cpu-throttle -increment is excessive usually at tail stage.
14023 If this parameter is true, we will compute the ideal CPU per‐
14024 centage used by the Guest, which may exactly make the dirty rate
14025 match the dirty rate threshold. Then we will choose a smaller
14026 throttle increment between the one specified by cpu-throttle-in‐
14027 crement and the one generated by ideal CPU percentage. There‐
14028 fore, it is compatible to traditional throttling, meanwhile the
14029 throttle increment won't be excessive at tail stage. The de‐
14030 fault value is false. (Since 5.1)
14031 tls-creds
14033 ID of the 'tls-creds' object that provides credentials for es‐
14034 tablishing a TLS connection over the migration data channel. On
14035 the outgoing side of the migration, the credentials must be for
14036 a 'client' endpoint, while for the incoming side the credentials
14037 must be for a 'server' endpoint. Setting this will enable TLS
14038 for all migrations. The default is unset, resulting in unsecured
14039 migration at the QEMU level. (Since 2.7)
14040 tls-hostname
14042 hostname of the target host for the migration. This is required
14043 when using x509 based TLS credentials and the migration URI does
14044 not already include a hostname. For example if using fd: or
14045 exec: based migration, the hostname must be provided so that the
14046 server's x509 certificate identity can be validated. (Since 2.7)
14047 tls-authz
14049 ID of the 'authz' object subclass that provides access control
14050 checking of the TLS x509 certificate distinguished name. This
14051 object is only resolved at time of use, so can be deleted and
14052 recreated on the fly while the migration server is active. If
14053 missing, it will default to denying access (Since 4.0)
14054 max-bandwidth
14056 to set maximum speed for migration. maximum speed in bytes per
14057 second. (Since 2.8)
14058 downtime-limit
14060 set maximum tolerated downtime for migration. maximum downtime
14061 in milliseconds (Since 2.8)
14062 x-checkpoint-delay
14064 The delay time (in ms) between two COLO checkpoints in periodic
14065 mode. (Since 2.8)
14066 block-incremental
14068 Affects how much storage is migrated when the block migration
14069 capability is enabled. When false, the entire storage backing
14070 chain is migrated into a flattened image at the destination;
14071 when true, only the active qcow2 layer is migrated and the des‐
14072 tination must already have access to the same backing chain as
14073 was used on the source. (since 2.10)
14074 multifd-channels
14076 Number of channels used to migrate data in parallel. This is the
14077 same number that the number of sockets used for migration. The
14078 default value is 2 (since 4.0)
14079 xbzrle-cache-size
14081 cache size to be used by XBZRLE migration. It needs to be a
14082 multiple of the target page size and a power of 2 (Since 2.11)
14083 max-postcopy-bandwidth
14085 Background transfer bandwidth during postcopy. Defaults to 0
14086 (unlimited). In bytes per second. (Since 3.0)
14087 max-cpu-throttle
14089 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
14090 multifd-compression
14092 Which compression method to use. Defaults to none. (Since 5.0)
14093 multifd-zlib-level
14095 Set the compression level to be used in live migration, the com‐
14096 pression level is an integer between 0 and 9, where 0 means no
14097 compression, 1 means the best compression speed, and 9 means
14098 best compression ratio which will consume more CPU. Defaults to
14099 1. (Since 5.0)
14100 multifd-zstd-level
14102 Set the compression level to be used in live migration, the com‐
14103 pression level is an integer between 0 and 20, where 0 means no
14104 compression, 1 means the best compression speed, and 20 means
14105 best compression ratio which will consume more CPU. Defaults to
14106 1. (Since 5.0)
14107 block-bitmap-mapping
14109 Maps block nodes and bitmaps on them to aliases for the purpose
14110 of dirty bitmap migration. Such aliases may for example be the
14111 corresponding names on the opposite site. The mapping must be
14112 one-to-one, but not necessarily complete: On the source, un‐
14113 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
14114 nored. On the destination, encountering an unmapped alias in
14115 the incoming migration stream will result in a report, and all
14116 further bitmap migration data will then be discarded. Note that
14117 the destination does not know about bitmaps it does not receive,
14118 so there is no limitation or requirement regarding the number of
14119 bitmaps received, or how they are named, or on which nodes they
14120 are placed. By default (when this parameter has never been
14121 set), bitmap names are mapped to themselves. Nodes are mapped
14122 to their block device name if there is one, and to their node
14123 name otherwise. (Since 5.2)
14124 Features
14126 unstable
14127 Member x-checkpoint-delay is experimental.
14128 Since
14130 2.4
14131 MigrateSetParameters (Object)
14133 Members
14134 announce-initial: int (optional)
14135 Initial delay (in milliseconds) before sending the first an‐
14136 nounce (Since 4.0)
14137 announce-max: int (optional)
14139 Maximum delay (in milliseconds) between packets in the announce‐
14140 ment (Since 4.0)
14141 announce-rounds: int (optional)
14143 Number of self-announce packets sent after migration (Since 4.0)
14144 announce-step: int (optional)
14146 Increase in delay (in milliseconds) between subsequent packets
14147 in the announcement (Since 4.0)
14148 compress-level: int (optional)
14150 compression level
14151 compress-threads: int (optional)
14153 compression thread count
14154 compress-wait-thread: boolean (optional)
14156 Controls behavior when all compression threads are currently
14157 busy. If true (default), wait for a free compression thread to
14158 become available; otherwise, send the page uncompressed. (Since
14159 3.1)
14160 decompress-threads: int (optional)
14162 decompression thread count
14163 throttle-trigger-threshold: int (optional)
14165 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
14166 throttling. It is expressed as percentage. The default value is
14167 50. (Since 5.0)
14168 cpu-throttle-initial: int (optional)
14170 Initial percentage of time guest cpus are throttled when migra‐
14171 tion auto-converge is activated. The default value is 20.
14172 (Since 2.7)
14173 cpu-throttle-increment: int (optional)
14175 throttle percentage increase each time auto-converge detects
14176 that migration is not making progress. The default value is 10.
14177 (Since 2.7)
14178 cpu-throttle-tailslow: boolean (optional)
14180 Make CPU throttling slower at tail stage At the tail stage of
14181 throttling, the Guest is very sensitive to CPU percentage while
14182 the cpu-throttle -increment is excessive usually at tail stage.
14183 If this parameter is true, we will compute the ideal CPU per‐
14184 centage used by the Guest, which may exactly make the dirty rate
14185 match the dirty rate threshold. Then we will choose a smaller
14186 throttle increment between the one specified by cpu-throttle-in‐
14187 crement and the one generated by ideal CPU percentage. There‐
14188 fore, it is compatible to traditional throttling, meanwhile the
14189 throttle increment won't be excessive at tail stage. The de‐
14190 fault value is false. (Since 5.1)
14191 tls-creds: StrOrNull (optional)
14193 ID of the 'tls-creds' object that provides credentials for es‐
14194 tablishing a TLS connection over the migration data channel. On
14195 the outgoing side of the migration, the credentials must be for
14196 a 'client' endpoint, while for the incoming side the credentials
14197 must be for a 'server' endpoint. Setting this to a non-empty
14198 string enables TLS for all migrations. An empty string means
14199 that QEMU will use plain text mode for migration, rather than
14200 TLS (Since 2.9) Previously (since 2.7), this was reported by
14201 omitting tls-creds instead.
14202 tls-hostname: StrOrNull (optional)
14204 hostname of the target host for the migration. This is required
14205 when using x509 based TLS credentials and the migration URI does
14206 not already include a hostname. For example if using fd: or
14207 exec: based migration, the hostname must be provided so that the
14208 server's x509 certificate identity can be validated. (Since 2.7)
14209 An empty string means that QEMU will use the hostname associated
14210 with the migration URI, if any. (Since 2.9) Previously (since
14211 2.7), this was reported by omitting tls-hostname instead.
14212 max-bandwidth: int (optional)
14214 to set maximum speed for migration. maximum speed in bytes per
14215 second. (Since 2.8)
14216 downtime-limit: int (optional)
14218 set maximum tolerated downtime for migration. maximum downtime
14219 in milliseconds (Since 2.8)
14220 x-checkpoint-delay: int (optional)
14222 the delay time between two COLO checkpoints. (Since 2.8)
14223 block-incremental: boolean (optional)
14225 Affects how much storage is migrated when the block migration
14226 capability is enabled. When false, the entire storage backing
14227 chain is migrated into a flattened image at the destination;
14228 when true, only the active qcow2 layer is migrated and the des‐
14229 tination must already have access to the same backing chain as
14230 was used on the source. (since 2.10)
14231 multifd-channels: int (optional)
14233 Number of channels used to migrate data in parallel. This is the
14234 same number that the number of sockets used for migration. The
14235 default value is 2 (since 4.0)
14236 xbzrle-cache-size: int (optional)
14238 cache size to be used by XBZRLE migration. It needs to be a
14239 multiple of the target page size and a power of 2 (Since 2.11)
14240 max-postcopy-bandwidth: int (optional)
14242 Background transfer bandwidth during postcopy. Defaults to 0
14243 (unlimited). In bytes per second. (Since 3.0)
14244 max-cpu-throttle: int (optional)
14246 maximum cpu throttle percentage. The default value is 99.
14247 (Since 3.1)
14248 multifd-compression: MultiFDCompression (optional)
14250 Which compression method to use. Defaults to none. (Since 5.0)
14251 multifd-zlib-level: int (optional)
14253 Set the compression level to be used in live migration, the com‐
14254 pression level is an integer between 0 and 9, where 0 means no
14255 compression, 1 means the best compression speed, and 9 means
14256 best compression ratio which will consume more CPU. Defaults to
14257 1. (Since 5.0)
14258 multifd-zstd-level: int (optional)
14260 Set the compression level to be used in live migration, the com‐
14261 pression level is an integer between 0 and 20, where 0 means no
14262 compression, 1 means the best compression speed, and 20 means
14263 best compression ratio which will consume more CPU. Defaults to
14264 1. (Since 5.0)
14265 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
14267 Maps block nodes and bitmaps on them to aliases for the purpose
14268 of dirty bitmap migration. Such aliases may for example be the
14269 corresponding names on the opposite site. The mapping must be
14270 one-to-one, but not necessarily complete: On the source, un‐
14271 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
14272 nored. On the destination, encountering an unmapped alias in
14273 the incoming migration stream will result in a report, and all
14274 further bitmap migration data will then be discarded. Note that
14275 the destination does not know about bitmaps it does not receive,
14276 so there is no limitation or requirement regarding the number of
14277 bitmaps received, or how they are named, or on which nodes they
14278 are placed. By default (when this parameter has never been
14279 set), bitmap names are mapped to themselves. Nodes are mapped
14280 to their block device name if there is one, and to their node
14281 name otherwise. (Since 5.2)
14282 tls-authz: StrOrNull (optional)
14284 Not documented
14285 Features
14287 unstable
14288 Member x-checkpoint-delay is experimental.
14289 Since
14291 2.4
14292 migrate-set-parameters (Command)
14294 Set various migration parameters.
14295 Arguments
14297 The members of MigrateSetParameters
14298 Since
14300 2.4
14301 Example
14303 -> { "execute": "migrate-set-parameters" ,
14304 "arguments": { "compress-level": 1 } }
14305 MigrationParameters (Object)
14307 The optional members aren't actually optional.
14308 Members
14310 announce-initial: int (optional)
14311 Initial delay (in milliseconds) before sending the first an‐
14312 nounce (Since 4.0)
14313 announce-max: int (optional)
14315 Maximum delay (in milliseconds) between packets in the announce‐
14316 ment (Since 4.0)
14317 announce-rounds: int (optional)
14319 Number of self-announce packets sent after migration (Since 4.0)
14320 announce-step: int (optional)
14322 Increase in delay (in milliseconds) between subsequent packets
14323 in the announcement (Since 4.0)
14324 compress-level: int (optional)
14326 compression level
14327 compress-threads: int (optional)
14329 compression thread count
14330 compress-wait-thread: boolean (optional)
14332 Controls behavior when all compression threads are currently
14333 busy. If true (default), wait for a free compression thread to
14334 become available; otherwise, send the page uncompressed. (Since
14335 3.1)
14336 decompress-threads: int (optional)
14338 decompression thread count
14339 throttle-trigger-threshold: int (optional)
14341 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
14342 throttling. It is expressed as percentage. The default value is
14343 50. (Since 5.0)
14344 cpu-throttle-initial: int (optional)
14346 Initial percentage of time guest cpus are throttled when migra‐
14347 tion auto-converge is activated. (Since 2.7)
14348 cpu-throttle-increment: int (optional)
14350 throttle percentage increase each time auto-converge detects
14351 that migration is not making progress. (Since 2.7)
14352 cpu-throttle-tailslow: boolean (optional)
14354 Make CPU throttling slower at tail stage At the tail stage of
14355 throttling, the Guest is very sensitive to CPU percentage while
14356 the cpu-throttle -increment is excessive usually at tail stage.
14357 If this parameter is true, we will compute the ideal CPU per‐
14358 centage used by the Guest, which may exactly make the dirty rate
14359 match the dirty rate threshold. Then we will choose a smaller
14360 throttle increment between the one specified by cpu-throttle-in‐
14361 crement and the one generated by ideal CPU percentage. There‐
14362 fore, it is compatible to traditional throttling, meanwhile the
14363 throttle increment won't be excessive at tail stage. The de‐
14364 fault value is false. (Since 5.1)
14365 tls-creds: string (optional)
14367 ID of the 'tls-creds' object that provides credentials for es‐
14368 tablishing a TLS connection over the migration data channel. On
14369 the outgoing side of the migration, the credentials must be for
14370 a 'client' endpoint, while for the incoming side the credentials
14371 must be for a 'server' endpoint. An empty string means that
14372 QEMU will use plain text mode for migration, rather than TLS
14373 (Since 2.7) Note: 2.8 reports this by omitting tls-creds in‐
14374 stead.
14375 tls-hostname: string (optional)
14377 hostname of the target host for the migration. This is required
14378 when using x509 based TLS credentials and the migration URI does
14379 not already include a hostname. For example if using fd: or
14380 exec: based migration, the hostname must be provided so that the
14381 server's x509 certificate identity can be validated. (Since 2.7)
14382 An empty string means that QEMU will use the hostname associated
14383 with the migration URI, if any. (Since 2.9) Note: 2.8 reports
14384 this by omitting tls-hostname instead.
14385 tls-authz: string (optional)
14387 ID of the 'authz' object subclass that provides access control
14388 checking of the TLS x509 certificate distinguished name. (Since
14389 4.0)
14390 max-bandwidth: int (optional)
14392 to set maximum speed for migration. maximum speed in bytes per
14393 second. (Since 2.8)
14394 downtime-limit: int (optional)
14396 set maximum tolerated downtime for migration. maximum downtime
14397 in milliseconds (Since 2.8)
14398 x-checkpoint-delay: int (optional)
14400 the delay time between two COLO checkpoints. (Since 2.8)
14401 block-incremental: boolean (optional)
14403 Affects how much storage is migrated when the block migration
14404 capability is enabled. When false, the entire storage backing
14405 chain is migrated into a flattened image at the destination;
14406 when true, only the active qcow2 layer is migrated and the des‐
14407 tination must already have access to the same backing chain as
14408 was used on the source. (since 2.10)
14409 multifd-channels: int (optional)
14411 Number of channels used to migrate data in parallel. This is the
14412 same number that the number of sockets used for migration. The
14413 default value is 2 (since 4.0)
14414 xbzrle-cache-size: int (optional)
14416 cache size to be used by XBZRLE migration. It needs to be a
14417 multiple of the target page size and a power of 2 (Since 2.11)
14418 max-postcopy-bandwidth: int (optional)
14420 Background transfer bandwidth during postcopy. Defaults to 0
14421 (unlimited). In bytes per second. (Since 3.0)
14422 max-cpu-throttle: int (optional)
14424 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
14425 multifd-compression: MultiFDCompression (optional)
14427 Which compression method to use. Defaults to none. (Since 5.0)
14428 multifd-zlib-level: int (optional)
14430 Set the compression level to be used in live migration, the com‐
14431 pression level is an integer between 0 and 9, where 0 means no
14432 compression, 1 means the best compression speed, and 9 means
14433 best compression ratio which will consume more CPU. Defaults to
14434 1. (Since 5.0)
14435 multifd-zstd-level: int (optional)
14437 Set the compression level to be used in live migration, the com‐
14438 pression level is an integer between 0 and 20, where 0 means no
14439 compression, 1 means the best compression speed, and 20 means
14440 best compression ratio which will consume more CPU. Defaults to
14441 1. (Since 5.0)
14442 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
14444 Maps block nodes and bitmaps on them to aliases for the purpose
14445 of dirty bitmap migration. Such aliases may for example be the
14446 corresponding names on the opposite site. The mapping must be
14447 one-to-one, but not necessarily complete: On the source, un‐
14448 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
14449 nored. On the destination, encountering an unmapped alias in
14450 the incoming migration stream will result in a report, and all
14451 further bitmap migration data will then be discarded. Note that
14452 the destination does not know about bitmaps it does not receive,
14453 so there is no limitation or requirement regarding the number of
14454 bitmaps received, or how they are named, or on which nodes they
14455 are placed. By default (when this parameter has never been
14456 set), bitmap names are mapped to themselves. Nodes are mapped
14457 to their block device name if there is one, and to their node
14458 name otherwise. (Since 5.2)
14459 Features
14461 unstable
14462 Member x-checkpoint-delay is experimental.
14463 Since
14465 2.4
14466 query-migrate-parameters (Command)
14468 Returns information about the current migration parameters
14469 Returns
14471 MigrationParameters
14472 Since
14474 2.4
14475 Example
14477 -> { "execute": "query-migrate-parameters" }
14478 <- { "return": {
14479 "decompress-threads": 2,
14480 "cpu-throttle-increment": 10,
14481 "compress-threads": 8,
14482 "compress-level": 1,
14483 "cpu-throttle-initial": 20,
14484 "max-bandwidth": 33554432,
14485 "downtime-limit": 300
14486 }
14487 }
14488 client_migrate_info (Command)
14490 Set migration information for remote display. This makes the server
14491 ask the client to automatically reconnect using the new parameters once
14492 migration finished successfully. Only implemented for SPICE.
14493 Arguments
14495 protocol: string
14496 must be "spice"
14497 hostname: string
14499 migration target hostname
14500 port: int (optional)
14502 spice tcp port for plaintext channels
14503 tls-port: int (optional)
14505 spice tcp port for tls-secured channels
14506 cert-subject: string (optional)
14508 server certificate subject
14509 Since
14511 0.14
14512 Example
14514 -> { "execute": "client_migrate_info",
14515 "arguments": { "protocol": "spice",
14516 "hostname": "virt42.lab.kraxel.org",
14517 "port": 1234 } }
14518 <- { "return": {} }
14519 migrate-start-postcopy (Command)
14521 Followup to a migration command to switch the migration to postcopy
14522 mode. The postcopy-ram capability must be set on both source and des‐
14523 tination before the original migration command.
14524 Since
14526 2.5
14527 Example
14529 -> { "execute": "migrate-start-postcopy" }
14530 <- { "return": {} }
14531 MIGRATION (Event)
14533 Emitted when a migration event happens
14534 Arguments
14536 status: MigrationStatus
14537 MigrationStatus describing the current migration status.
14538 Since
14540 2.4
14541 Example
14543 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
14544 "event": "MIGRATION",
14545 "data": {"status": "completed"} }
14546 MIGRATION_PASS (Event)
14548 Emitted from the source side of a migration at the start of each pass
14549 (when it syncs the dirty bitmap)
14550 Arguments
14552 pass: int
14553 An incrementing count (starting at 1 on the first pass)
14554 Since
14556 2.6
14557 Example
14559 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
14560 "event": "MIGRATION_PASS", "data": {"pass": 2} }
14561 COLOMessage (Enum)
14563 The message transmission between Primary side and Secondary side.
14564 Values
14566 checkpoint-ready
14567 Secondary VM (SVM) is ready for checkpointing
14568 checkpoint-request
14570 Primary VM (PVM) tells SVM to prepare for checkpointing
14571 checkpoint-reply
14573 SVM gets PVM's checkpoint request
14574 vmstate-send
14576 VM's state will be sent by PVM.
14577 vmstate-size
14579 The total size of VMstate.
14580 vmstate-received
14582 VM's state has been received by SVM.
14583 vmstate-loaded
14585 VM's state has been loaded by SVM.
14586 Since
14588 2.8
14589 COLOMode (Enum)
14591 The COLO current mode.
14592 Values
14594 none COLO is disabled.
14595 primary
14597 COLO node in primary side.
14598 secondary
14600 COLO node in slave side.
14601 Since
14603 2.8
14604 FailoverStatus (Enum)
14606 An enumeration of COLO failover status
14607 Values
14609 none no failover has ever happened
14610 require
14612 got failover requirement but not handled
14613 active in the process of doing failover
14615 completed
14617 finish the process of failover
14618 relaunch
14620 restart the failover process, from 'none' -> 'completed' (Since
14621 2.9)
14622 Since
14624 2.8
14625 COLO_EXIT (Event)
14627 Emitted when VM finishes COLO mode due to some errors happening or at
14628 the request of users.
14629 Arguments
14631 mode: COLOMode
14632 report COLO mode when COLO exited.
14633 reason: COLOExitReason
14635 describes the reason for the COLO exit.
14636 Since
14638 3.1
14639 Example
14641 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
14642 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
14643 COLOExitReason (Enum)
14645 The reason for a COLO exit.
14646 Values
14648 none failover has never happened. This state does not occur in the
14649 COLO_EXIT event, and is only visible in the result of
14650 query-colo-status.
14651 request
14653 COLO exit is due to an external request.
14654 error COLO exit is due to an internal error.
14656 processing
14658 COLO is currently handling a failover (since 4.0).
14659 Since
14661 3.1
14662 x-colo-lost-heartbeat (Command)
14664 Tell qemu that heartbeat is lost, request it to do takeover procedures.
14665 If this command is sent to the PVM, the Primary side will exit COLO
14666 mode. If sent to the Secondary, the Secondary side will run failover
14667 work, then takes over server operation to become the service VM.
14668 Features
14670 unstable
14671 This command is experimental.
14672 Since
14674 2.8
14675 Example
14677 -> { "execute": "x-colo-lost-heartbeat" }
14678 <- { "return": {} }
14679 migrate_cancel (Command)
14681 Cancel the current executing migration process.
14682 Returns
14684 nothing on success
14685 Notes
14687 This command succeeds even if there is no migration process running.
14688 Since
14690 0.14
14691 Example
14693 -> { "execute": "migrate_cancel" }
14694 <- { "return": {} }
14695 migrate-continue (Command)
14697 Continue migration when it's in a paused state.
14698 Arguments
14700 state: MigrationStatus
14701 The state the migration is currently expected to be in
14702 Returns
14704 nothing on success
14705 Since
14707 2.11
14708 Example
14710 -> { "execute": "migrate-continue" , "arguments":
14711 { "state": "pre-switchover" } }
14712 <- { "return": {} }
14713 migrate (Command)
14715 Migrates the current running guest to another Virtual Machine.
14716 Arguments
14718 uri: string
14719 the Uniform Resource Identifier of the destination VM
14720 blk: boolean (optional)
14722 do block migration (full disk copy)
14723 inc: boolean (optional)
14725 incremental disk copy migration
14726 detach: boolean (optional)
14728 this argument exists only for compatibility reasons and is ig‐
14729 nored by QEMU
14730 resume: boolean (optional)
14732 resume one paused migration, default "off". (since 3.0)
14733 Returns
14735 nothing on success
14736 Since
14738 0.14
14739 Notes
14741 1. The 'query-migrate' command should be used to check migration's
14742 progress and final result (this information is provided by the 'sta‐
14743 tus' member)
14744 2. All boolean arguments default to false
14746 3. The user Monitor's "detach" argument is invalid in QMP and should
14748 not be used
14749 Example
14751 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
14752 <- { "return": {} }
14753 migrate-incoming (Command)
14755 Start an incoming migration, the qemu must have been started with -in‐
14756 coming defer
14757 Arguments
14759 uri: string
14760 The Uniform Resource Identifier identifying the source or ad‐
14761 dress to listen on
14762 Returns
14764 nothing on success
14765 Since
14767 2.3
14768 Notes
14770 1. It's a bad idea to use a string for the uri, but it needs to stay
14771 compatible with -incoming and the format of the uri is already ex‐
14772 posed above libvirt.
14773 2. QEMU must be started with -incoming defer to allow migrate-incoming
14775 to be used.
14776 3. The uri format is the same as for -incoming
14778 Example
14780 -> { "execute": "migrate-incoming",
14781 "arguments": { "uri": "tcp::4446" } }
14782 <- { "return": {} }
14783 xen-save-devices-state (Command)
14785 Save the state of all devices to file. The RAM and the block devices of
14786 the VM are not saved by this command.
14787 Arguments
14789 filename: string
14790 the file to save the state of the devices to as binary data. See
14791 xen-save-devices-state.txt for a description of the binary for‐
14792 mat.
14793 live: boolean (optional)
14795 Optional argument to ask QEMU to treat this command as part of a
14796 live migration. Default to true. (since 2.11)
14797 Returns
14799 Nothing on success
14800 Since
14802 1.1
14803 Example
14805 -> { "execute": "xen-save-devices-state",
14806 "arguments": { "filename": "/tmp/save" } }
14807 <- { "return": {} }
14808 xen-set-global-dirty-log (Command)
14810 Enable or disable the global dirty log mode.
14811 Arguments
14813 enable: boolean
14814 true to enable, false to disable.
14815 Returns
14817 nothing
14818 Since
14820 1.3
14821 Example
14823 -> { "execute": "xen-set-global-dirty-log",
14824 "arguments": { "enable": true } }
14825 <- { "return": {} }
14826 xen-load-devices-state (Command)
14828 Load the state of all devices from file. The RAM and the block devices
14829 of the VM are not loaded by this command.
14830 Arguments
14832 filename: string
14833 the file to load the state of the devices from as binary data.
14834 See xen-save-devices-state.txt for a description of the binary
14835 format.
14836 Since
14838 2.7
14839 Example
14841 -> { "execute": "xen-load-devices-state",
14842 "arguments": { "filename": "/tmp/resume" } }
14843 <- { "return": {} }
14844 xen-set-replication (Command)
14846 Enable or disable replication.
14847 Arguments
14849 enable: boolean
14850 true to enable, false to disable.
14851 primary: boolean
14853 true for primary or false for secondary.
14854 failover: boolean (optional)
14856 true to do failover, false to stop. but cannot be specified if
14857 'enable' is true. default value is false.
14858 Returns
14860 nothing.
14861 Example
14863 -> { "execute": "xen-set-replication",
14864 "arguments": {"enable": true, "primary": false} }
14865 <- { "return": {} }
14866 Since
14868 2.9
14869 If
14871 CONFIG_REPLICATION
14872 ReplicationStatus (Object)
14874 The result format for 'query-xen-replication-status'.
14875 Members
14877 error: boolean
14878 true if an error happened, false if replication is normal.
14879 desc: string (optional)
14881 the human readable error description string, when error is
14882 'true'.
14883 Since
14885 2.9
14886 If
14888 CONFIG_REPLICATION
14889 query-xen-replication-status (Command)
14891 Query replication status while the vm is running.
14892 Returns
14894 A ReplicationResult object showing the status.
14895 Example
14897 -> { "execute": "query-xen-replication-status" }
14898 <- { "return": { "error": false } }
14899 Since
14901 2.9
14902 If
14904 CONFIG_REPLICATION
14905 xen-colo-do-checkpoint (Command)
14907 Xen uses this command to notify replication to trigger a checkpoint.
14908 Returns
14910 nothing.
14911 Example
14913 -> { "execute": "xen-colo-do-checkpoint" }
14914 <- { "return": {} }
14915 Since
14917 2.9
14918 If
14920 CONFIG_REPLICATION
14921 COLOStatus (Object)
14923 The result format for 'query-colo-status'.
14924 Members
14926 mode: COLOMode
14927 COLO running mode. If COLO is running, this field will return
14928 'primary' or 'secondary'.
14929 last-mode: COLOMode
14931 COLO last running mode. If COLO is running, this field will re‐
14932 turn same like mode field, after failover we can use this field
14933 to get last colo mode. (since 4.0)
14934 reason: COLOExitReason
14936 describes the reason for the COLO exit.
14937 Since
14939 3.1
14940 query-colo-status (Command)
14942 Query COLO status while the vm is running.
14943 Returns
14945 A COLOStatus object showing the status.
14946 Example
14948 -> { "execute": "query-colo-status" }
14949 <- { "return": { "mode": "primary", "reason": "request" } }
14950 Since
14952 3.1
14953 migrate-recover (Command)
14955 Provide a recovery migration stream URI.
14956 Arguments
14958 uri: string
14959 the URI to be used for the recovery of migration stream.
14960 Returns
14962 nothing.
14963 Example
14965 -> { "execute": "migrate-recover",
14966 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
14967 <- { "return": {} }
14968 Since
14970 3.0
14971 migrate-pause (Command)
14973 Pause a migration. Currently it only supports postcopy.
14974 Returns
14976 nothing.
14977 Example
14979 -> { "execute": "migrate-pause" }
14980 <- { "return": {} }
14981 Since
14983 3.0
14984 UNPLUG_PRIMARY (Event)
14986 Emitted from source side of a migration when migration state is
14987 WAIT_UNPLUG. Device was unplugged by guest operating system. Device
14988 resources in QEMU are kept on standby to be able to re-plug it in case
14989 of migration failure.
14990 Arguments
14992 device-id: string
14993 QEMU device id of the unplugged device
14994 Since
14996 4.2
14997 Example
14999 {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} }
15000 DirtyRateVcpu (Object)
15002 Dirty rate of vcpu.
15003 Members
15005 id: int
15006 vcpu index.
15007 dirty-rate: int
15009 dirty rate.
15010 Since
15012 6.2
15013 DirtyRateStatus (Enum)
15015 An enumeration of dirtyrate status.
15016 Values
15018 unstarted
15019 the dirtyrate thread has not been started.
15020 measuring
15022 the dirtyrate thread is measuring.
15023 measured
15025 the dirtyrate thread has measured and results are available.
15026 Since
15028 5.2
15029 DirtyRateMeasureMode (Enum)
15031 An enumeration of mode of measuring dirtyrate.
15032 Values
15034 page-sampling
15035 calculate dirtyrate by sampling pages.
15036 dirty-ring
15038 calculate dirtyrate by dirty ring.
15039 dirty-bitmap
15041 calculate dirtyrate by dirty bitmap.
15042 Since
15044 6.2
15045 DirtyRateInfo (Object)
15047 Information about current dirty page rate of vm.
15048 Members
15050 dirty-rate: int (optional)
15051 an estimate of the dirty page rate of the VM in units of MB/s,
15052 present only when estimating the rate has completed.
15053 status: DirtyRateStatus
15055 status containing dirtyrate query status includes 'unstarted' or
15056 'measuring' or 'measured'
15057 start-time: int
15059 start time in units of second for calculation
15060 calc-time: int
15062 time in units of second for sample dirty pages
15063 sample-pages: int
15065 page count per GB for sample dirty pages the default value is
15066 512 (since 6.1)
15067 mode: DirtyRateMeasureMode
15069 mode containing method of calculate dirtyrate includes
15070 'page-sampling' and 'dirty-ring' (Since 6.2)
15071 vcpu-dirty-rate: array of DirtyRateVcpu (optional)
15073 dirtyrate for each vcpu if dirty-ring mode specified (Since 6.2)
15074 Since
15076 5.2
15077 calc-dirty-rate (Command)
15079 start calculating dirty page rate for vm
15080 Arguments
15082 calc-time: int
15083 time in units of second for sample dirty pages
15084 sample-pages: int (optional)
15086 page count per GB for sample dirty pages the default value is
15087 512 (since 6.1)
15088 mode: DirtyRateMeasureMode (optional)
15090 mechanism of calculating dirtyrate includes 'page-sampling' and
15091 'dirty-ring' (Since 6.1)
15092 Since
15094 5.2
15095 Example
15097 {"command": "calc-dirty-rate", "data": {"calc-time": 1,
15098 'sample-pages': 512} }
15099 query-dirty-rate (Command)
15101 query dirty page rate in units of MB/s for vm
15102 Since
15104 5.2
15105 snapshot-save (Command)
15107 Save a VM snapshot
15108 Arguments
15110 job-id: string
15111 identifier for the newly created job
15112 tag: string
15114 name of the snapshot to create
15115 vmstate: string
15117 block device node name to save vmstate to
15118 devices: array of string
15120 list of block device node names to save a snapshot to
15121 Applications should not assume that the snapshot save is complete when
15122 this command returns. The job commands / events must be used to deter‐
15123 mine completion and to fetch details of any errors that arise.
15124 Note that execution of the guest CPUs may be stopped during the time it
15126 takes to save the snapshot. A future version of QEMU may ensure CPUs
15127 are executing continuously.
15128 It is strongly recommended that devices contain all writable block de‐
15130 vice nodes if a consistent snapshot is required.
15131 If tag already exists, an error will be reported
15133 Returns
15135 nothing
15136 Example
15138 -> { "execute": "snapshot-save",
15139 "data": {
15140 "job-id": "snapsave0",
15141 "tag": "my-snap",
15142 "vmstate": "disk0",
15143 "devices": ["disk0", "disk1"]
15144 }
15145 }
15146 <- { "return": { } }
15147 <- {"event": "JOB_STATUS_CHANGE",
15148 "data": {"status": "created", "id": "snapsave0"}}
15149 <- {"event": "JOB_STATUS_CHANGE",
15150 "data": {"status": "running", "id": "snapsave0"}}
15151 <- {"event": "STOP"}
15152 <- {"event": "RESUME"}
15153 <- {"event": "JOB_STATUS_CHANGE",
15154 "data": {"status": "waiting", "id": "snapsave0"}}
15155 <- {"event": "JOB_STATUS_CHANGE",
15156 "data": {"status": "pending", "id": "snapsave0"}}
15157 <- {"event": "JOB_STATUS_CHANGE",
15158 "data": {"status": "concluded", "id": "snapsave0"}}
15159 -> {"execute": "query-jobs"}
15160 <- {"return": [{"current-progress": 1,
15161 "status": "concluded",
15162 "total-progress": 1,
15163 "type": "snapshot-save",
15164 "id": "snapsave0"}]}
15165 Since
15167 6.0
15168 snapshot-load (Command)
15170 Load a VM snapshot
15171 Arguments
15173 job-id: string
15174 identifier for the newly created job
15175 tag: string
15177 name of the snapshot to load.
15178 vmstate: string
15180 block device node name to load vmstate from
15181 devices: array of string
15183 list of block device node names to load a snapshot from
15184 Applications should not assume that the snapshot load is complete when
15185 this command returns. The job commands / events must be used to deter‐
15186 mine completion and to fetch details of any errors that arise.
15187 Note that execution of the guest CPUs will be stopped during the time
15189 it takes to load the snapshot.
15190 It is strongly recommended that devices contain all writable block de‐
15192 vice nodes that can have changed since the original snapshot-save com‐
15193 mand execution.
15194 Returns
15196 nothing
15197 Example
15199 -> { "execute": "snapshot-load",
15200 "data": {
15201 "job-id": "snapload0",
15202 "tag": "my-snap",
15203 "vmstate": "disk0",
15204 "devices": ["disk0", "disk1"]
15205 }
15206 }
15207 <- { "return": { } }
15208 <- {"event": "JOB_STATUS_CHANGE",
15209 "data": {"status": "created", "id": "snapload0"}}
15210 <- {"event": "JOB_STATUS_CHANGE",
15211 "data": {"status": "running", "id": "snapload0"}}
15212 <- {"event": "STOP"}
15213 <- {"event": "RESUME"}
15214 <- {"event": "JOB_STATUS_CHANGE",
15215 "data": {"status": "waiting", "id": "snapload0"}}
15216 <- {"event": "JOB_STATUS_CHANGE",
15217 "data": {"status": "pending", "id": "snapload0"}}
15218 <- {"event": "JOB_STATUS_CHANGE",
15219 "data": {"status": "concluded", "id": "snapload0"}}
15220 -> {"execute": "query-jobs"}
15221 <- {"return": [{"current-progress": 1,
15222 "status": "concluded",
15223 "total-progress": 1,
15224 "type": "snapshot-load",
15225 "id": "snapload0"}]}
15226 Since
15228 6.0
15229 snapshot-delete (Command)
15231 Delete a VM snapshot
15232 Arguments
15234 job-id: string
15235 identifier for the newly created job
15236 tag: string
15238 name of the snapshot to delete.
15239 devices: array of string
15241 list of block device node names to delete a snapshot from
15242 Applications should not assume that the snapshot delete is complete
15243 when this command returns. The job commands / events must be used to
15244 determine completion and to fetch details of any errors that arise.
15245 Returns
15247 nothing
15248 Example
15250 -> { "execute": "snapshot-delete",
15251 "data": {
15252 "job-id": "snapdelete0",
15253 "tag": "my-snap",
15254 "devices": ["disk0", "disk1"]
15255 }
15256 }
15257 <- { "return": { } }
15258 <- {"event": "JOB_STATUS_CHANGE",
15259 "data": {"status": "created", "id": "snapdelete0"}}
15260 <- {"event": "JOB_STATUS_CHANGE",
15261 "data": {"status": "running", "id": "snapdelete0"}}
15262 <- {"event": "JOB_STATUS_CHANGE",
15263 "data": {"status": "waiting", "id": "snapdelete0"}}
15264 <- {"event": "JOB_STATUS_CHANGE",
15265 "data": {"status": "pending", "id": "snapdelete0"}}
15266 <- {"event": "JOB_STATUS_CHANGE",
15267 "data": {"status": "concluded", "id": "snapdelete0"}}
15268 -> {"execute": "query-jobs"}
15269 <- {"return": [{"current-progress": 1,
15270 "status": "concluded",
15271 "total-progress": 1,
15272 "type": "snapshot-delete",
15273 "id": "snapdelete0"}]}
15274 Since
15276 6.0
15277
15279 Abort (Object)
15280 This action can be used to test transaction failure.
15281 Since
15283 1.6
15284 ActionCompletionMode (Enum)
15286 An enumeration of Transactional completion modes.
15287 Values
15289 individual
15290 Do not attempt to cancel any other Actions if any Actions fail
15291 after the Transaction request succeeds. All Actions that can
15292 complete successfully will do so without waiting on others.
15293 This is the default.
15294 grouped
15296 If any Action fails after the Transaction succeeds, cancel all
15297 Actions. Actions do not complete until all Actions are ready to
15298 complete. May be rejected by Actions that do not support this
15299 completion mode.
15300 Since
15302 2.5
15303 TransactionActionKind (Enum)
15305 Values
15306 abort Since 1.6
15307 block-dirty-bitmap-add
15309 Since 2.5
15310 block-dirty-bitmap-remove
15312 Since 4.2
15313 block-dirty-bitmap-clear
15315 Since 2.5
15316 block-dirty-bitmap-enable
15318 Since 4.0
15319 block-dirty-bitmap-disable
15321 Since 4.0
15322 block-dirty-bitmap-merge
15324 Since 4.0
15325 blockdev-backup
15327 Since 2.3
15328 blockdev-snapshot
15330 Since 2.5
15331 blockdev-snapshot-internal-sync
15333 Since 1.7
15334 blockdev-snapshot-sync
15336 since 1.1
15337 drive-backup
15339 Since 1.6
15340 Features
15342 deprecated
15343 Member drive-backup is deprecated. Use member blockdev-backup
15344 instead.
15345 Since
15347 1.1
15348 AbortWrapper (Object)
15350 Members
15351 data: Abort
15352 Not documented
15353 Since
15355 1.6
15356 BlockDirtyBitmapAddWrapper (Object)
15358 Members
15359 data: BlockDirtyBitmapAdd
15360 Not documented
15361 Since
15363 2.5
15364 BlockDirtyBitmapWrapper (Object)
15366 Members
15367 data: BlockDirtyBitmap
15368 Not documented
15369 Since
15371 2.5
15372 BlockDirtyBitmapMergeWrapper (Object)
15374 Members
15375 data: BlockDirtyBitmapMerge
15376 Not documented
15377 Since
15379 4.0
15380 BlockdevBackupWrapper (Object)
15382 Members
15383 data: BlockdevBackup
15384 Not documented
15385 Since
15387 2.3
15388 BlockdevSnapshotWrapper (Object)
15390 Members
15391 data: BlockdevSnapshot
15392 Not documented
15393 Since
15395 2.5
15396 BlockdevSnapshotInternalWrapper (Object)
15398 Members
15399 data: BlockdevSnapshotInternal
15400 Not documented
15401 Since
15403 1.7
15404 BlockdevSnapshotSyncWrapper (Object)
15406 Members
15407 data: BlockdevSnapshotSync
15408 Not documented
15409 Since
15411 1.1
15412 DriveBackupWrapper (Object)
15414 Members
15415 data: DriveBackup
15416 Not documented
15417 Since
15419 1.6
15420 TransactionAction (Object)
15422 A discriminated record of operations that can be performed with trans‐
15423 action.
15424 Members
15426 type: TransactionActionKind
15427 Not documented
15428 The members of AbortWrapper when type is "abort"
15430 The members of BlockDirtyBitmapAddWrapper when type is
15432 "block-dirty-bitmap-add"
15433 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
15435 map-remove"
15436 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
15438 map-clear"
15439 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
15441 map-enable"
15442 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
15444 map-disable"
15445 The members of BlockDirtyBitmapMergeWrapper when type is
15447 "block-dirty-bitmap-merge"
15448 The members of BlockdevBackupWrapper when type is "blockdev-backup"
15450 The members of BlockdevSnapshotWrapper when type is "blockdev-snapshot"
15452 The members of BlockdevSnapshotInternalWrapper when type is "block‐
15454 dev-snapshot-internal-sync"
15455 The members of BlockdevSnapshotSyncWrapper when type is "blockdev-snap‐
15457 shot-sync"
15458 The members of DriveBackupWrapper when type is "drive-backup"
15460 Since
15462 1.1
15463 TransactionProperties (Object)
15465 Optional arguments to modify the behavior of a Transaction.
15466 Members
15468 completion-mode: ActionCompletionMode (optional)
15469 Controls how jobs launched asynchronously by Actions will com‐
15470 plete or fail as a group. See ActionCompletionMode for details.
15471 Since
15473 2.5
15474 transaction (Command)
15476 Executes a number of transactionable QMP commands atomically. If any
15477 operation fails, then the entire set of actions will be abandoned and
15478 the appropriate error returned.
15479 For external snapshots, the dictionary contains the device, the file to
15481 use for the new snapshot, and the format. The default format, if not
15482 specified, is qcow2.
15483 Each new snapshot defaults to being created by QEMU (wiping any con‐
15485 tents if the file already exists), but it is also possible to reuse an
15486 externally-created file. In the latter case, you should ensure that
15487 the new image file has the same contents as the current one; QEMU can‐
15488 not perform any meaningful check. Typically this is achieved by using
15489 the current image file as the backing file for the new image.
15490 On failure, the original disks pre-snapshot attempt will be used.
15492 For internal snapshots, the dictionary contains the device and the
15494 snapshot's name. If an internal snapshot matching name already exists,
15495 the request will be rejected. Only some image formats support it, for
15496 example, qcow2, and rbd,
15497 On failure, qemu will try delete the newly created internal snapshot in
15499 the transaction. When an I/O error occurs during deletion, the user
15500 needs to fix it later with qemu-img or other command.
15501 Arguments
15503 actions: array of TransactionAction
15504 List of TransactionAction; information needed for the respective
15505 operations.
15506 properties: TransactionProperties (optional)
15508 structure of additional options to control the execution of the
15509 transaction. See TransactionProperties for additional detail.
15510 Returns
15512 nothing on success
15513 Errors depend on the operations of the transaction
15515 Note
15517 The transaction aborts on the first failure. Therefore, there will be
15518 information on only one failed operation returned in an error condi‐
15519 tion, and subsequent actions will not have been attempted.
15520 Since
15522 1.1
15523 Example
15525 -> { "execute": "transaction",
15526 "arguments": { "actions": [
15527 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
15528 "snapshot-file": "/some/place/my-image",
15529 "format": "qcow2" } },
15530 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
15531 "snapshot-file": "/some/place/my-image2",
15532 "snapshot-node-name": "node3432",
15533 "mode": "existing",
15534 "format": "qcow2" } },
15535 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
15536 "snapshot-file": "/some/place/my-image2",
15537 "mode": "existing",
15538 "format": "qcow2" } },
15539 { "type": "blockdev-snapshot-internal-sync", "data" : {
15540 "device": "ide-hd2",
15541 "name": "snapshot0" } } ] } }
15542 <- { "return": {} }
15543
15545 TraceEventState (Enum)
15546 State of a tracing event.
15547 Values
15549 unavailable
15550 The event is statically disabled.
15551 disabled
15553 The event is dynamically disabled.
15554 enabled
15556 The event is dynamically enabled.
15557 Since
15559 2.2
15560 TraceEventInfo (Object)
15562 Information of a tracing event.
15563 Members
15565 name: string
15566 Event name.
15567 state: TraceEventState
15569 Tracing state.
15570 vcpu: boolean
15572 Whether this is a per-vCPU event (since 2.7).
15573 An event is per-vCPU if it has the "vcpu" property in the
15574 "trace-events" files.
15575 Since
15577 2.2
15578 trace-event-get-state (Command)
15580 Query the state of events.
15581 Arguments
15583 name: string
15584 Event name pattern (case-sensitive glob).
15585 vcpu: int (optional)
15587 The vCPU to query (any by default; since 2.7).
15588 Returns
15590 a list of TraceEventInfo for the matching events
15591 An event is returned if:
15593 • its name matches the name pattern, and
15595 • if vcpu is given, the event has the "vcpu" property.
15597 Therefore, if vcpu is given, the operation will only match per-vCPU
15599 events, returning their state on the specified vCPU. Special case: if
15600 name is an exact match, vcpu is given and the event does not have the
15601 "vcpu" property, an error is returned.
15602 Since
15604 2.2
15605 Example
15607 -> { "execute": "trace-event-get-state",
15608 "arguments": { "name": "qemu_memalign" } }
15609 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
15610 trace-event-set-state (Command)
15612 Set the dynamic tracing state of events.
15613 Arguments
15615 name: string
15616 Event name pattern (case-sensitive glob).
15617 enable: boolean
15619 Whether to enable tracing.
15620 ignore-unavailable: boolean (optional)
15622 Do not match unavailable events with name.
15623 vcpu: int (optional)
15625 The vCPU to act upon (all by default; since 2.7).
15626 An event's state is modified if: - its name matches the name pattern,
15627 and - if vcpu is given, the event has the "vcpu" property.
15628 Therefore, if vcpu is given, the operation will only match per-vCPU
15630 events, setting their state on the specified vCPU. Special case: if
15631 name is an exact match, vcpu is given and the event does not have the
15632 "vcpu" property, an error is returned.
15633 Since
15635 2.2
15636 Example
15638 -> { "execute": "trace-event-set-state",
15639 "arguments": { "name": "qemu_memalign", "enable": true } }
15640 <- { "return": {} }
15641
15643 CompatPolicyInput (Enum)
15644 Policy for handling "funny" input.
15645 Values
15647 accept Accept silently
15648 reject Reject with an error
15650 crash abort() the process
15652 Since
15654 6.0
15655 CompatPolicyOutput (Enum)
15657 Policy for handling "funny" output.
15658 Values
15660 accept Pass on unchanged
15661 hide Filter out
15663 Since
15665 6.0
15666 CompatPolicy (Object)
15668 Policy for handling deprecated management interfaces.
15669 This is intended for testing users of the management interfaces.
15671 Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
15673 with feature 'deprecated'. We may want to extend it to cover semantic
15674 aspects, CLI, and experimental features.
15675 Limitation: deprecated-output policy hide is not implemented for enu‐
15677 meration values. They behave the same as with policy accept.
15678 Members
15680 deprecated-input: CompatPolicyInput (optional)
15681 how to handle deprecated input (default 'accept')
15682 deprecated-output: CompatPolicyOutput (optional)
15684 how to handle deprecated output (default 'accept')
15685 unstable-input: CompatPolicyInput (optional)
15687 how to handle unstable input (default 'accept') (since 6.2)
15688 unstable-output: CompatPolicyOutput (optional)
15690 how to handle unstable output (default 'accept') (since 6.2)
15691 Since
15693 6.0
15694
15696 qmp_capabilities (Command)
15697 Enable QMP capabilities.
15698 Arguments:
15700 Arguments
15702 enable: array of QMPCapability (optional)
15703 An optional list of QMPCapability values to enable. The client
15704 must not enable any capability that is not mentioned in the QMP
15705 greeting message. If the field is not provided, it means no QMP
15706 capabilities will be enabled. (since 2.12)
15707 Example
15709 -> { "execute": "qmp_capabilities",
15710 "arguments": { "enable": [ "oob" ] } }
15711 <- { "return": {} }
15712 Notes
15714 This command is valid exactly when first connecting: it must be issued
15715 before any other command will be accepted, and will fail once the moni‐
15716 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
15717 The QMP client needs to explicitly enable QMP capabilities, otherwise
15719 all the QMP capabilities will be turned off by default.
15720 Since
15722 0.13
15723 QMPCapability (Enum)
15725 Enumeration of capabilities to be advertised during initial client con‐
15726 nection, used for agreeing on particular QMP extension behaviors.
15727 Values
15729 oob QMP ability to support out-of-band requests. (Please refer to
15730 qmp-spec.txt for more information on OOB)
15731 Since
15733 2.12
15734 VersionTriple (Object)
15736 A three-part version number.
15737 Members
15739 major: int
15740 The major version number.
15741 minor: int
15743 The minor version number.
15744 micro: int
15746 The micro version number.
15747 Since
15749 2.4
15750 VersionInfo (Object)
15752 A description of QEMU's version.
15753 Members
15755 qemu: VersionTriple
15756 The version of QEMU. By current convention, a micro version of
15757 50 signifies a development branch. A micro version greater than
15758 or equal to 90 signifies a release candidate for the next minor
15759 version. A micro version of less than 50 signifies a stable re‐
15760 lease.
15761 package: string
15763 QEMU will always set this field to an empty string. Downstream
15764 versions of QEMU should set this to a non-empty string. The ex‐
15765 act format depends on the downstream however it highly recom‐
15766 mended that a unique name is used.
15767 Since
15769 0.14
15770 query-version (Command)
15772 Returns the current version of QEMU.
15773 Returns
15775 A VersionInfo object describing the current version of QEMU.
15776 Since
15778 0.14
15779 Example
15781 -> { "execute": "query-version" }
15782 <- {
15783 "return":{
15784 "qemu":{
15785 "major":0,
15786 "minor":11,
15787 "micro":5
15788 },
15789 "package":""
15790 }
15791 }
15792 CommandInfo (Object)
15794 Information about a QMP command
15795 Members
15797 name: string
15798 The command name
15799 Since
15801 0.14
15802 query-commands (Command)
15804 Return a list of supported QMP commands by this server
15805 Returns
15807 A list of CommandInfo for all supported commands
15808 Since
15810 0.14
15811 Example
15813 -> { "execute": "query-commands" }
15814 <- {
15815 "return":[
15816 {
15817 "name":"query-balloon"
15818 },
15819 {
15820 "name":"system_powerdown"
15821 }
15822 ]
15823 }
15824 Note
15826 This example has been shortened as the real response is too long.
15827 quit (Command)
15829 This command will cause the QEMU process to exit gracefully. While ev‐
15830 ery attempt is made to send the QMP response before terminating, this
15831 is not guaranteed. When using this interface, a premature EOF would
15832 not be unexpected.
15833 Since
15835 0.14
15836 Example
15838 -> { "execute": "quit" }
15839 <- { "return": {} }
15840 MonitorMode (Enum)
15842 An enumeration of monitor modes.
15843 Values
15845 readline
15846 HMP monitor (human-oriented command line interface)
15847 control
15849 QMP monitor (JSON-based machine interface)
15850 Since
15852 5.0
15853 MonitorOptions (Object)
15855 Options to be used for adding a new monitor.
15856 Members
15858 id: string (optional)
15859 Name of the monitor
15860 mode: MonitorMode (optional)
15862 Selects the monitor mode (default: readline in the system emula‐
15863 tor, control in qemu-storage-daemon)
15864 pretty: boolean (optional)
15866 Enables pretty printing (QMP only)
15867 chardev: string
15869 Name of a character device to expose the monitor on
15870 Since
15872 5.0
15873
15875 query-qmp-schema (Command)
15876 Command query-qmp-schema exposes the QMP wire ABI as an array of
15877 SchemaInfo. This lets QMP clients figure out what commands and events
15878 are available in this QEMU, and their parameters and results.
15879 However, the SchemaInfo can't reflect all the rules and restrictions
15881 that apply to QMP. It's interface introspection (figuring out what's
15882 there), not interface specification. The specification is in the QAPI
15883 schema.
15884 Furthermore, while we strive to keep the QMP wire format backwards-com‐
15886 patible across qemu versions, the introspection output is not guaran‐
15887 teed to have the same stability. For example, one version of qemu may
15888 list an object member as an optional non-variant, while another lists
15889 the same member only through the object's variants; or the type of a
15890 member may change from a generic string into a specific enum or from
15891 one specific type into an alternate that includes the original type
15892 alongside something else.
15893 Returns
15895 array of SchemaInfo, where each element describes an entity in the ABI:
15896 command, event, type, ...
15897 The order of the various SchemaInfo is unspecified; however, all names
15899 are guaranteed to be unique (no name will be duplicated with different
15900 meta-types).
15901 Note
15903 the QAPI schema is also used to help define internal interfaces, by
15904 defining QAPI types. These are not part of the QMP wire ABI, and
15905 therefore not returned by this command.
15906 Since
15908 2.5
15909 SchemaMetaType (Enum)
15911 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
15912 Values
15914 builtin
15915 a predefined type such as 'int' or 'bool'.
15916 enum an enumeration type
15918 array an array type
15920 object an object type (struct or union)
15922 alternate
15924 an alternate type
15925 command
15927 a QMP command
15928 event a QMP event
15930 Since
15932 2.5
15933 SchemaInfo (Object)
15935 Members
15936 name: string
15937 the entity's name, inherited from base. The SchemaInfo is al‐
15938 ways referenced by this name. Commands and events have the name
15939 defined in the QAPI schema. Unlike command and event names,
15940 type names are not part of the wire ABI. Consequently, type
15941 names are meaningless strings here, although they are still
15942 guaranteed unique regardless of meta-type.
15943 meta-type: SchemaMetaType
15945 the entity's meta type, inherited from base.
15946 features: array of string (optional)
15948 names of features associated with the entity, in no particular
15949 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
15950 the rest)
15951 The members of SchemaInfoBuiltin when meta-type is "builtin"
15953 The members of SchemaInfoEnum when meta-type is "enum"
15955 The members of SchemaInfoArray when meta-type is "array"
15957 The members of SchemaInfoObject when meta-type is "object"
15959 The members of SchemaInfoAlternate when meta-type is "alternate"
15961 The members of SchemaInfoCommand when meta-type is "command"
15963 The members of SchemaInfoEvent when meta-type is "event"
15965 Additional members depend on the value of meta-type.
15966 Since
15968 2.5
15969 SchemaInfoBuiltin (Object)
15971 Additional SchemaInfo members for meta-type 'builtin'.
15972 Members
15974 json-type: JSONType
15975 the JSON type used for this type on the wire.
15976 Since
15978 2.5
15979 JSONType (Enum)
15981 The four primitive and two structured types according to RFC 8259 sec‐
15982 tion 1, plus 'int' (split off 'number'), plus the obvious top type
15983 'value'.
15984 Values
15986 string Not documented
15987 number Not documented
15989 int Not documented
15991 boolean
15993 Not documented
15994 null Not documented
15996 object Not documented
15998 array Not documented
16000 value Not documented
16002 Since
16004 2.5
16005 SchemaInfoEnum (Object)
16007 Additional SchemaInfo members for meta-type 'enum'.
16008 Members
16010 members: array of SchemaInfoEnumMember
16011 the enum type's members, in no particular order (since 6.2).
16012 values: array of string
16014 the enumeration type's member names, in no particular order.
16015 Redundant with members. Just for backward compatibility.
16016 Features
16018 deprecated
16019 Member values is deprecated. Use members instead.
16020 Values of this type are JSON string on the wire.
16021 Since
16023 2.5
16024 SchemaInfoEnumMember (Object)
16026 An object member.
16027 Members
16029 name: string
16030 the member's name, as defined in the QAPI schema.
16031 features: array of string (optional)
16033 names of features associated with the member, in no particular
16034 order.
16035 Since
16037 6.2
16038 SchemaInfoArray (Object)
16040 Additional SchemaInfo members for meta-type 'array'.
16041 Members
16043 element-type: string
16044 the array type's element type.
16045 Values of this type are JSON array on the wire.
16046 Since
16048 2.5
16049 SchemaInfoObject (Object)
16051 Additional SchemaInfo members for meta-type 'object'.
16052 Members
16054 members: array of SchemaInfoObjectMember
16055 the object type's (non-variant) members, in no particular order.
16056 tag: string (optional)
16058 the name of the member serving as type tag. An element of mem‐
16059 bers with this name must exist.
16060 variants: array of SchemaInfoObjectVariant (optional)
16062 variant members, i.e. additional members that depend on the type
16063 tag's value. Present exactly when tag is present. The variants
16064 are in no particular order, and may even differ from the order
16065 of the values of the enum type of the tag.
16066 Values of this type are JSON object on the wire.
16067 Since
16069 2.5
16070 SchemaInfoObjectMember (Object)
16072 An object member.
16073 Members
16075 name: string
16076 the member's name, as defined in the QAPI schema.
16077 type: string
16079 the name of the member's type.
16080 default: value (optional)
16082 default when used as command parameter. If absent, the parame‐
16083 ter is mandatory. If present, the value must be null. The pa‐
16084 rameter is optional, and behavior when it's missing is not spec‐
16085 ified here. Future extension: if present and non-null, the pa‐
16086 rameter is optional, and defaults to this value.
16087 features: array of string (optional)
16089 names of features associated with the member, in no particular
16090 order. (since 5.0)
16091 Since
16093 2.5
16094 SchemaInfoObjectVariant (Object)
16096 The variant members for a value of the type tag.
16097 Members
16099 case: string
16100 a value of the type tag.
16101 type: string
16103 the name of the object type that provides the variant members
16104 when the type tag has value case.
16105 Since
16107 2.5
16108 SchemaInfoAlternate (Object)
16110 Additional SchemaInfo members for meta-type 'alternate'.
16111 Members
16113 members: array of SchemaInfoAlternateMember
16114 the alternate type's members, in no particular order. The mem‐
16115 bers' wire encoding is distinct, see docs/de‐
16116 vel/qapi-code-gen.txt section Alternate types.
16117 On the wire, this can be any of the members.
16118 Since
16120 2.5
16121 SchemaInfoAlternateMember (Object)
16123 An alternate member.
16124 Members
16126 type: string
16127 the name of the member's type.
16128 Since
16130 2.5
16131 SchemaInfoCommand (Object)
16133 Additional SchemaInfo members for meta-type 'command'.
16134 Members
16136 arg-type: string
16137 the name of the object type that provides the command's parame‐
16138 ters.
16139 ret-type: string
16141 the name of the command's result type.
16142 allow-oob: boolean (optional)
16144 whether the command allows out-of-band execution, defaults to
16145 false (Since: 2.12)
16146 TODO
16148 success-response (currently irrelevant, because it's QGA, not QMP)
16149 Since
16151 2.5
16152 SchemaInfoEvent (Object)
16154 Additional SchemaInfo members for meta-type 'event'.
16155 Members
16157 arg-type: string
16158 the name of the object type that provides the event's parame‐
16159 ters.
16160 Since
16162 2.5
16163
16165 ObjectPropertyInfo (Object)
16166 Members
16167 name: string
16168 the name of the property
16169 type: string
16171 the type of the property. This will typically come in one of
16172 four forms:
16173 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
16175 ble'. These types are mapped to the appropriate JSON type.
16176 2. A child type in the form 'child<subtype>' where subtype is a
16178 qdev device type name. Child properties create the composi‐
16179 tion tree.
16180 3. A link type in the form 'link<subtype>' where subtype is a
16182 qdev device type name. Link properties form the device model
16183 graph.
16184 description: string (optional)
16186 if specified, the description of the property.
16187 default-value: value (optional)
16189 the default value, if any (since 5.0)
16190 Since
16192 1.2
16193 qom-list (Command)
16195 This command will list any properties of a object given a path in the
16196 object model.
16197 Arguments
16199 path: string
16200 the path within the object model. See qom-get for a description
16201 of this parameter.
16202 Returns
16204 a list of ObjectPropertyInfo that describe the properties of the ob‐
16205 ject.
16206 Since
16208 1.2
16209 Example
16211 -> { "execute": "qom-list",
16212 "arguments": { "path": "/chardevs" } }
16213 <- { "return": [ { "name": "type", "type": "string" },
16214 { "name": "parallel0", "type": "child<chardev-vc>" },
16215 { "name": "serial0", "type": "child<chardev-vc>" },
16216 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
16217 qom-get (Command)
16219 This command will get a property from a object model path and return
16220 the value.
16221 Arguments
16223 path: string
16224 The path within the object model. There are two forms of sup‐
16225 ported paths--absolute and partial paths.
16226 Absolute paths are derived from the root object and can follow
16228 child<> or link<> properties. Since they can follow link<>
16229 properties, they can be arbitrarily long. Absolute paths look
16230 like absolute filenames and are prefixed with a leading slash.
16231 Partial paths look like relative filenames. They do not begin
16233 with a prefix. The matching rules for partial paths are subtle
16234 but designed to make specifying objects easy. At each level of
16235 the composition tree, the partial path is matched as an absolute
16236 path. The first match is not returned. At least two matches
16237 are searched for. A successful result is only returned if only
16238 one match is found. If more than one match is found, a flag is
16239 return to indicate that the match was ambiguous.
16240 property: string
16242 The property name to read
16243 Returns
16245 The property value. The type depends on the property type. child<> and
16246 link<> properties are returned as #str pathnames. All integer property
16247 types (u8, u16, etc) are returned as #int.
16248 Since
16250 1.2
16251 Example
16253 1. Use absolute path
16254 -> { "execute": "qom-get",
16256 "arguments": { "path": "/machine/unattached/device[0]",
16257 "property": "hotplugged" } }
16258 <- { "return": false }
16259 2. Use partial path
16261 -> { "execute": "qom-get",
16263 "arguments": { "path": "unattached/sysbus",
16264 "property": "type" } }
16265 <- { "return": "System" }
16266 qom-set (Command)
16268 This command will set a property from a object model path.
16269 Arguments
16271 path: string
16272 see qom-get for a description of this parameter
16273 property: string
16275 the property name to set
16276 value: value
16278 a value who's type is appropriate for the property type. See
16279 qom-get for a description of type mapping.
16280 Since
16282 1.2
16283 Example
16285 -> { "execute": "qom-set",
16286 "arguments": { "path": "/machine",
16287 "property": "graphics",
16288 "value": false } }
16289 <- { "return": {} }
16290 ObjectTypeInfo (Object)
16292 This structure describes a search result from qom-list-types
16293 Members
16295 name: string
16296 the type name found in the search
16297 abstract: boolean (optional)
16299 the type is abstract and can't be directly instantiated. Omit‐
16300 ted if false. (since 2.10)
16301 parent: string (optional)
16303 Name of parent type, if any (since 2.10)
16304 Since
16306 1.1
16307 qom-list-types (Command)
16309 This command will return a list of types given search parameters
16310 Arguments
16312 implements: string (optional)
16313 if specified, only return types that implement this type name
16314 abstract: boolean (optional)
16316 if true, include abstract types in the results
16317 Returns
16319 a list of ObjectTypeInfo or an empty list if no results are found
16320 Since
16322 1.1
16323 qom-list-properties (Command)
16325 List properties associated with a QOM object.
16326 Arguments
16328 typename: string
16329 the type name of an object
16330 Note
16332 objects can create properties at runtime, for example to describe links
16333 between different devices and/or objects. These properties are not in‐
16334 cluded in the output of this command.
16335 Returns
16337 a list of ObjectPropertyInfo describing object properties
16338 Since
16340 2.12
16341 CanHostSocketcanProperties (Object)
16343 Properties for can-host-socketcan objects.
16344 Members
16346 if: string
16347 interface name of the host system CAN bus to connect to
16348 canbus: string
16350 object ID of the can-bus object to connect to the host interface
16351 Since
16353 2.12
16354 ColoCompareProperties (Object)
16356 Properties for colo-compare objects.
16357 Members
16359 primary_in: string
16360 name of the character device backend to use for the primary in‐
16361 put (incoming packets are redirected to outdev)
16362 secondary_in: string
16364 name of the character device backend to use for secondary input
16365 (incoming packets are only compared to the input on primary_in
16366 and then dropped)
16367 outdev: string
16369 name of the character device backend to use for output
16370 iothread: string
16372 name of the iothread to run in
16373 notify_dev: string (optional)
16375 name of the character device backend to be used to communicate
16376 with the remote colo-frame (only for Xen COLO)
16377 compare_timeout: int (optional)
16379 the maximum time to hold a packet from primary_in for comparison
16380 with an incoming packet on secondary_in in milliseconds (de‐
16381 fault: 3000)
16382 expired_scan_cycle: int (optional)
16384 the interval at which colo-compare checks whether packets from
16385 primary have timed out, in milliseconds (default: 3000)
16386 max_queue_size: int (optional)
16388 the maximum number of packets to keep in the queue for comparing
16389 with incoming packets from secondary_in. If the queue is full
16390 and additional packets are received, the additional packets are
16391 dropped. (default: 1024)
16392 vnet_hdr_support: boolean (optional)
16394 if true, vnet header support is enabled (default: false)
16395 Since
16397 2.8
16398 CryptodevBackendProperties (Object)
16400 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
16401 Members
16403 queues: int (optional)
16404 the number of queues for the cryptodev backend. Ignored for
16405 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
16406 (default: 1)
16407 Since
16409 2.8
16410 CryptodevVhostUserProperties (Object)
16412 Properties for cryptodev-vhost-user objects.
16413 Members
16415 chardev: string
16416 the name of a Unix domain socket character device that connects
16417 to the vhost-user server
16418 The members of CryptodevBackendProperties
16420 Since
16422 2.12
16423 DBusVMStateProperties (Object)
16425 Properties for dbus-vmstate objects.
16426 Members
16428 addr: string
16429 the name of the DBus bus to connect to
16430 id-list: string (optional)
16432 a comma separated list of DBus IDs of helpers whose data should
16433 be included in the VM state on migration
16434 Since
16436 5.0
16437 NetfilterInsert (Enum)
16439 Indicates where to insert a netfilter relative to a given other filter.
16440 Values
16442 before insert before the specified filter
16443 behind insert behind the specified filter
16445 Since
16447 5.0
16448 NetfilterProperties (Object)
16450 Properties for objects of classes derived from netfilter.
16451 Members
16453 netdev: string
16454 id of the network device backend to filter
16455 queue: NetFilterDirection (optional)
16457 indicates which queue(s) to filter (default: all)
16458 status: string (optional)
16460 indicates whether the filter is enabled ("on") or disabled
16461 ("off") (default: "on")
16462 position: string (optional)
16464 specifies where the filter should be inserted in the filter
16465 list. "head" means the filter is inserted at the head of the
16466 filter list, before any existing filters. "tail" means the fil‐
16467 ter is inserted at the tail of the filter list, behind any ex‐
16468 isting filters (default). "id=<id>" means the filter is in‐
16469 serted before or behind the filter specified by <id>, depending
16470 on the insert property. (default: "tail")
16471 insert: NetfilterInsert (optional)
16473 where to insert the filter relative to the filter given in posi‐
16474 tion. Ignored if position is "head" or "tail". (default: be‐
16475 hind)
16476 Since
16478 2.5
16479 FilterBufferProperties (Object)
16481 Properties for filter-buffer objects.
16482 Members
16484 interval: int
16485 a non-zero interval in microseconds. All packets arriving in
16486 the given interval are delayed until the end of the interval.
16487 The members of NetfilterProperties
16489 Since
16491 2.5
16492 FilterDumpProperties (Object)
16494 Properties for filter-dump objects.
16495 Members
16497 file: string
16498 the filename where the dumped packets should be stored
16499 maxlen: int (optional)
16501 maximum number of bytes in a packet that are stored (default:
16502 65536)
16503 The members of NetfilterProperties
16505 Since
16507 2.5
16508 FilterMirrorProperties (Object)
16510 Properties for filter-mirror objects.
16511 Members
16513 outdev: string
16514 the name of a character device backend to which all incoming
16515 packets are mirrored
16516 vnet_hdr_support: boolean (optional)
16518 if true, vnet header support is enabled (default: false)
16519 The members of NetfilterProperties
16521 Since
16523 2.6
16524 FilterRedirectorProperties (Object)
16526 Properties for filter-redirector objects.
16527 At least one of indev or outdev must be present. If both are present,
16529 they must not refer to the same character device backend.
16530 Members
16532 indev: string (optional)
16533 the name of a character device backend from which packets are
16534 received and redirected to the filtered network device
16535 outdev: string (optional)
16537 the name of a character device backend to which all incoming
16538 packets are redirected
16539 vnet_hdr_support: boolean (optional)
16541 if true, vnet header support is enabled (default: false)
16542 The members of NetfilterProperties
16544 Since
16546 2.6
16547 FilterRewriterProperties (Object)
16549 Properties for filter-rewriter objects.
16550 Members
16552 vnet_hdr_support: boolean (optional)
16553 if true, vnet header support is enabled (default: false)
16554 The members of NetfilterProperties
16556 Since
16558 2.8
16559 InputBarrierProperties (Object)
16561 Properties for input-barrier objects.
16562 Members
16564 name: string
16565 the screen name as declared in the screens section of bar‐
16566 rier.conf
16567 server: string (optional)
16569 hostname of the Barrier server (default: "localhost")
16570 port: string (optional)
16572 TCP port of the Barrier server (default: "24800")
16573 x-origin: string (optional)
16575 x coordinate of the leftmost pixel on the guest screen (default:
16576 "0")
16577 y-origin: string (optional)
16579 y coordinate of the topmost pixel on the guest screen (default:
16580 "0")
16581 width: string (optional)
16583 the width of secondary screen in pixels (default: "1920")
16584 height: string (optional)
16586 the height of secondary screen in pixels (default: "1080")
16587 Since
16589 4.2
16590 InputLinuxProperties (Object)
16592 Properties for input-linux objects.
16593 Members
16595 evdev: string
16596 the path of the host evdev device to use
16597 grab_all: boolean (optional)
16599 if true, grab is toggled for all devices (e.g. both keyboard and
16600 mouse) instead of just one device (default: false)
16601 repeat: boolean (optional)
16603 enables auto-repeat events (default: false)
16604 grab-toggle: GrabToggleKeys (optional)
16606 the key or key combination that toggles device grab (default:
16607 ctrl-ctrl)
16608 Since
16610 2.6
16611 IothreadProperties (Object)
16613 Properties for iothread objects.
16614 Members
16616 poll-max-ns: int (optional)
16617 the maximum number of nanoseconds to busy wait for events. 0
16618 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
16619 erwise)
16620 poll-grow: int (optional)
16622 the multiplier used to increase the polling time when the algo‐
16623 rithm detects it is missing events due to not polling long
16624 enough. 0 selects a default behaviour (default: 0)
16625 poll-shrink: int (optional)
16627 the divisor used to decrease the polling time when the algorithm
16628 detects it is spending too long polling without encountering
16629 events. 0 selects a default behaviour (default: 0)
16630 aio-max-batch: int (optional)
16632 maximum number of requests in a batch for the AIO engine, 0
16633 means that the engine will use its default (default:0, since
16634 6.1)
16635 Since
16637 2.0
16638 MemoryBackendProperties (Object)
16640 Properties for objects of classes derived from memory-backend.
16641 Members
16643 merge: boolean (optional)
16644 if true, mark the memory as mergeable (default depends on the
16645 machine type)
16646 dump: boolean (optional)
16648 if true, include the memory in core dumps (default depends on
16649 the machine type)
16650 host-nodes: array of int (optional)
16652 the list of NUMA host nodes to bind the memory to
16653 policy: HostMemPolicy (optional)
16655 the NUMA policy (default: 'default')
16656 prealloc: boolean (optional)
16658 if true, preallocate memory (default: false)
16659 prealloc-threads: int (optional)
16661 number of CPU threads to use for prealloc (default: 1)
16662 share: boolean (optional)
16664 if false, the memory is private to QEMU; if true, it is shared
16665 (default: false)
16666 reserve: boolean (optional)
16668 if true, reserve swap space (or huge pages) if applicable (de‐
16669 fault: true) (since 6.1)
16670 size: int
16672 size of the memory region in bytes
16673 x-use-canonical-path-for-ramblock-id: boolean (optional)
16675 if true, the canoncial path is used for ramblock-id. Disable
16676 this for 4.0 machine types or older to allow migration with
16677 newer QEMU versions. (default: false generally, but true for
16678 machine types <= 4.0)
16679 Note
16681 prealloc=true and reserve=false cannot be set at the same time. With
16682 reserve=true, the behavior depends on the operating system: for exam‐
16683 ple, Linux will not reserve swap space for shared file mappings -- "not
16684 applicable". In contrast, reserve=false will bail out if it cannot be
16685 configured accordingly.
16686 Since
16688 2.1
16689 MemoryBackendFileProperties (Object)
16691 Properties for memory-backend-file objects.
16692 Members
16694 align: int (optional)
16695 the base address alignment when QEMU mmap(2)s mem-path. Some
16696 backend stores specified by mem-path require an alignment dif‐
16697 ferent than the default one used by QEMU, e.g. the device DAX
16698 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
16699 users can specify the required alignment via this option. 0 se‐
16700 lects a default alignment (currently the page size). (default:
16701 0)
16702 discard-data: boolean (optional)
16704 if true, the file contents can be destroyed when QEMU exits, to
16705 avoid unnecessarily flushing data to the backing file. Note that
16706 discard-data is only an optimization, and QEMU might not discard
16707 file contents if it aborts unexpectedly or is terminated using
16708 SIGKILL. (default: false)
16709 mem-path: string
16711 the path to either a shared memory or huge page filesystem mount
16712 pmem: boolean (optional) (If: CONFIG_LIBPMEM)
16714 specifies whether the backing file specified by mem-path is in
16715 host persistent memory that can be accessed using the SNIA NVM
16716 programming model (e.g. Intel NVDIMM).
16717 readonly: boolean (optional)
16719 if true, the backing file is opened read-only; if false, it is
16720 opened read-write. (default: false)
16721 The members of MemoryBackendProperties
16723 Since
16725 2.1
16726 MemoryBackendMemfdProperties (Object)
16728 Properties for memory-backend-memfd objects.
16729 The share boolean option is true by default with memfd.
16731 Members
16733 hugetlb: boolean (optional)
16734 if true, the file to be created resides in the hugetlbfs
16735 filesystem (default: false)
16736 hugetlbsize: int (optional)
16738 the hugetlb page size on systems that support multiple hugetlb
16739 page sizes (it must be a power of 2 value supported by the sys‐
16740 tem). 0 selects a default page size. This option is ignored if
16741 hugetlb is false. (default: 0)
16742 seal: boolean (optional)
16744 if true, create a sealed-file, which will block further resizing
16745 of the memory (default: true)
16746 The members of MemoryBackendProperties
16748 Since
16750 2.12
16751 MemoryBackendEpcProperties (Object)
16753 Properties for memory-backend-epc objects.
16754 The share boolean option is true by default with epc
16756 The merge boolean option is false by default with epc
16758 The dump boolean option is false by default with epc
16760 Members
16762 The members of MemoryBackendProperties
16763 Since
16765 6.2
16766 PrManagerHelperProperties (Object)
16768 Properties for pr-manager-helper objects.
16769 Members
16771 path: string
16772 the path to a Unix domain socket for connecting to the external
16773 helper
16774 Since
16776 2.11
16777 QtestProperties (Object)
16779 Properties for qtest objects.
16780 Members
16782 chardev: string
16783 the chardev to be used to receive qtest commands on.
16784 log: string (optional)
16786 the path to a log file
16787 Since
16789 6.0
16790 RemoteObjectProperties (Object)
16792 Properties for x-remote-object objects.
16793 Members
16795 fd: string
16796 file descriptor name previously passed via 'getfd' command
16797 devid: string
16799 the id of the device to be associated with the file descriptor
16800 Since
16802 6.0
16803 RngProperties (Object)
16805 Properties for objects of classes derived from rng.
16806 Members
16808 opened: boolean (optional)
16809 if true, the device is opened immediately when applying this op‐
16810 tion and will probably fail when processing the next option.
16811 Don't use; only provided for compatibility. (default: false)
16812 Features
16814 deprecated
16815 Member opened is deprecated. Setting true doesn't make sense,
16816 and false is already the default.
16817 Since
16819 1.3
16820 RngEgdProperties (Object)
16822 Properties for rng-egd objects.
16823 Members
16825 chardev: string
16826 the name of a character device backend that provides the connec‐
16827 tion to the RNG daemon
16828 The members of RngProperties
16830 Since
16832 1.3
16833 RngRandomProperties (Object)
16835 Properties for rng-random objects.
16836 Members
16838 filename: string (optional)
16839 the filename of the device on the host to obtain entropy from
16840 (default: "/dev/urandom")
16841 The members of RngProperties
16843 Since
16845 1.3
16846 SevGuestProperties (Object)
16848 Properties for sev-guest objects.
16849 Members
16851 sev-device: string (optional)
16852 SEV device to use (default: "/dev/sev")
16853 dh-cert-file: string (optional)
16855 guest owners DH certificate (encoded with base64)
16856 session-file: string (optional)
16858 guest owners session parameters (encoded with base64)
16859 policy: int (optional)
16861 SEV policy value (default: 0x1)
16862 handle: int (optional)
16864 SEV firmware handle (default: 0)
16865 cbitpos: int (optional)
16867 C-bit location in page table entry (default: 0)
16868 reduced-phys-bits: int
16870 number of bits in physical addresses that become unavailable
16871 when SEV is enabled
16872 kernel-hashes: boolean (optional)
16874 if true, add hashes of kernel/initrd/cmdline to a designated
16875 guest firmware page for measured boot with -kernel (default:
16876 false) (since 6.2)
16877 Since
16879 2.12
16880 ObjectType (Enum)
16882 Values
16883 authz-list
16884 Not documented
16885 authz-listfile
16887 Not documented
16888 authz-pam
16890 Not documented
16891 authz-simple
16893 Not documented
16894 can-bus
16896 Not documented
16897 can-host-socketcan (If: CONFIG_LINUX)
16899 Not documented
16900 colo-compare
16902 Not documented
16903 cryptodev-backend
16905 Not documented
16906 cryptodev-backend-builtin
16908 Not documented
16909 cryptodev-vhost-user (If: CONFIG_VHOST_CRYPTO)
16911 Not documented
16912 dbus-vmstate
16914 Not documented
16915 filter-buffer
16917 Not documented
16918 filter-dump
16920 Not documented
16921 filter-mirror
16923 Not documented
16924 filter-redirector
16926 Not documented
16927 filter-replay
16929 Not documented
16930 filter-rewriter
16932 Not documented
16933 input-barrier
16935 Not documented
16936 input-linux (If: CONFIG_LINUX)
16938 Not documented
16939 iothread
16941 Not documented
16942 memory-backend-epc (If: CONFIG_LINUX)
16944 Not documented
16945 memory-backend-file
16947 Not documented
16948 memory-backend-memfd (If: CONFIG_LINUX)
16950 Not documented
16951 memory-backend-ram
16953 Not documented
16954 pef-guest
16956 Not documented
16957 pr-manager-helper (If: CONFIG_LINUX)
16959 Not documented
16960 qtest Not documented
16962 rng-builtin
16964 Not documented
16965 rng-egd
16967 Not documented
16968 rng-random (If: CONFIG_POSIX)
16970 Not documented
16971 secret Not documented
16973 secret_keyring (If: CONFIG_SECRET_KEYRING)
16975 Not documented
16976 sev-guest
16978 Not documented
16979 s390-pv-guest
16981 Not documented
16982 throttle-group
16984 Not documented
16985 tls-creds-anon
16987 Not documented
16988 tls-creds-psk
16990 Not documented
16991 tls-creds-x509
16993 Not documented
16994 tls-cipher-suites
16996 Not documented
16997 x-remote-object
16999 Not documented
17000 Features
17002 unstable
17003 Member x-remote-object is experimental.
17004 Since
17006 6.0
17007 ObjectOptions (Object)
17009 Describes the options of a user creatable QOM object.
17010 Members
17012 qom-type: ObjectType
17013 the class name for the object to be created
17014 id: string
17016 the name of the new object
17017 The members of AuthZListProperties when qom-type is "authz-list"
17019 The members of AuthZListFileProperties when qom-type is "authz-list‐
17021 file"
17022 The members of AuthZPAMProperties when qom-type is "authz-pam"
17024 The members of AuthZSimpleProperties when qom-type is "authz-simple"
17026 The members of CanHostSocketcanProperties when qom-type is
17028 "can-host-socketcan" (If: CONFIG_LINUX)
17029 The members of ColoCompareProperties when qom-type is "colo-compare"
17031 The members of CryptodevBackendProperties when qom-type is "cryp‐
17033 todev-backend"
17034 The members of CryptodevBackendProperties when qom-type is "cryp‐
17036 todev-backend-builtin"
17037 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
17039 todev-vhost-user" (If: CONFIG_VHOST_CRYPTO)
17040 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
17042 The members of FilterBufferProperties when qom-type is "filter-buffer"
17044 The members of FilterDumpProperties when qom-type is "filter-dump"
17046 The members of FilterMirrorProperties when qom-type is "filter-mirror"
17048 The members of FilterRedirectorProperties when qom-type is "fil‐
17050 ter-redirector"
17051 The members of NetfilterProperties when qom-type is "filter-replay"
17053 The members of FilterRewriterProperties when qom-type is "fil‐
17055 ter-rewriter"
17056 The members of InputBarrierProperties when qom-type is "input-barrier"
17058 The members of InputLinuxProperties when qom-type is "input-linux" (If:
17060 CONFIG_LINUX)
17061 The members of IothreadProperties when qom-type is "iothread"
17063 The members of MemoryBackendEpcProperties when qom-type is "mem‐
17065 ory-backend-epc" (If: CONFIG_LINUX)
17066 The members of MemoryBackendFileProperties when qom-type is "mem‐
17068 ory-backend-file"
17069 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
17071 ory-backend-memfd" (If: CONFIG_LINUX)
17072 The members of MemoryBackendProperties when qom-type is "memory-back‐
17074 end-ram"
17075 The members of PrManagerHelperProperties when qom-type is "pr-man‐
17077 ager-helper" (If: CONFIG_LINUX)
17078 The members of QtestProperties when qom-type is "qtest"
17080 The members of RngProperties when qom-type is "rng-builtin"
17082 The members of RngEgdProperties when qom-type is "rng-egd"
17084 The members of RngRandomProperties when qom-type is "rng-random" (If:
17086 CONFIG_POSIX)
17087 The members of SecretProperties when qom-type is "secret"
17089 The members of SecretKeyringProperties when qom-type is "se‐
17091 cret_keyring" (If: CONFIG_SECRET_KEYRING)
17092 The members of SevGuestProperties when qom-type is "sev-guest"
17094 The members of ThrottleGroupProperties when qom-type is "throt‐
17096 tle-group"
17097 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
17099 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
17101 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
17103 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
17105 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
17107 ject"
17108 Since
17110 6.0
17111 object-add (Command)
17113 Create a QOM object.
17114 Arguments
17116 The members of ObjectOptions
17117 Returns
17119 Nothing on success Error if qom-type is not a valid class name
17120 Since
17122 2.0
17123 Example
17125 -> { "execute": "object-add",
17126 "arguments": { "qom-type": "rng-random", "id": "rng1",
17127 "filename": "/dev/hwrng" } }
17128 <- { "return": {} }
17129 object-del (Command)
17131 Remove a QOM object.
17132 Arguments
17134 id: string
17135 the name of the QOM object to remove
17136 Returns
17138 Nothing on success Error if id is not a valid id for a QOM object
17139 Since
17141 2.0
17142 Example
17144 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
17145 <- { "return": {} }
17146
17148 device-list-properties (Command)
17149 List properties associated with a device.
17150 Arguments
17152 typename: string
17153 the type name of a device
17154 Returns
17156 a list of ObjectPropertyInfo describing a devices properties
17157 Note
17159 objects can create properties at runtime, for example to describe links
17160 between different devices and/or objects. These properties are not in‐
17161 cluded in the output of this command.
17162 Since
17164 1.2
17165 device_add (Command)
17167 Add a device.
17168 Arguments
17170 driver: string
17171 the name of the new device's driver
17172 bus: string (optional)
17174 the device's parent bus (device tree path)
17175 id: string (optional)
17177 the device's ID, must be unique
17178 Features
17180 json-cli
17181 If present, the "-device" command line option supports JSON syn‐
17182 tax with a structure identical to the arguments of this command.
17183 Notes
17185 Additional arguments depend on the type.
17186 1. For detailed information about this command, please refer to the
17188 'docs/qdev-device-use.txt' file.
17189 2. It's possible to list device properties by running QEMU with the
17191 "-device DEVICE,help" command-line argument, where DEVICE is the de‐
17192 vice's name
17193 Example
17195 -> { "execute": "device_add",
17196 "arguments": { "driver": "e1000", "id": "net1",
17197 "bus": "pci.0",
17198 "mac": "52:54:00:12:34:56" } }
17199 <- { "return": {} }
17200 TODO
17202 This command effectively bypasses QAPI completely due to its "addi‐
17203 tional arguments" business. It shouldn't have been added to the schema
17204 in this form. It should be qapified properly, or replaced by a prop‐
17205 erly qapified command.
17206 Since
17208 0.13
17209 device_del (Command)
17211 Remove a device from a guest
17212 Arguments
17214 id: string
17215 the device's ID or QOM path
17216 Returns
17218 Nothing on success If id is not a valid device, DeviceNotFound
17219 Notes
17221 When this command completes, the device may not be removed from the
17222 guest. Hot removal is an operation that requires guest cooperation.
17223 This command merely requests that the guest begin the hot removal
17224 process. Completion of the device removal process is signaled with a
17225 DEVICE_DELETED event. Guest reset will automatically complete removal
17226 for all devices. If a guest-side error in the hot removal process is
17227 detected, the device will not be removed and a DEVICE_UNPLUG_GUEST_ER‐
17228 ROR event is sent. Some errors cannot be detected.
17229 Since
17231 0.14
17232 Example
17234 -> { "execute": "device_del",
17235 "arguments": { "id": "net1" } }
17236 <- { "return": {} }
17237 -> { "execute": "device_del",
17239 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
17240 <- { "return": {} }
17241 DEVICE_DELETED (Event)
17243 Emitted whenever the device removal completion is acknowledged by the
17244 guest. At this point, it's safe to reuse the specified device ID. De‐
17245 vice removal can be initiated by the guest or by HMP/QMP commands.
17246 Arguments
17248 device: string (optional)
17249 the device's ID if it has one
17250 path: string
17252 the device's QOM path
17253 Since
17255 1.5
17256 Example
17258 <- { "event": "DEVICE_DELETED",
17259 "data": { "device": "virtio-net-pci-0",
17260 "path": "/machine/peripheral/virtio-net-pci-0" },
17261 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
17262 DEVICE_UNPLUG_GUEST_ERROR (Event)
17264 Emitted when a device hot unplug fails due to a guest reported error.
17265 Arguments
17267 device: string (optional)
17268 the device's ID if it has one
17269 path: string
17271 the device's QOM path
17272 Since
17274 6.2
17275 Example
17277 <- { "event": "DEVICE_UNPLUG_GUEST_ERROR"
17278 "data": { "device": "core1",
17279 "path": "/machine/peripheral/core1" },
17280 },
17281 "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
17282
17284 SysEmuTarget (Enum)
17285 The comprehensive enumeration of QEMU system emulation ("softmmu") tar‐
17286 gets. Run "./configure --help" in the project root directory, and look
17287 for the *-softmmu targets near the "--target-list" option. The individ‐
17288 ual target constants are not documented here, for the time being.
17289 Values
17291 rx since 5.0
17292 avr since 5.1
17294 aarch64
17296 Not documented
17297 alpha Not documented
17299 arm Not documented
17301 cris Not documented
17303 hppa Not documented
17305 i386 Not documented
17307 m68k Not documented
17309 microblaze
17311 Not documented
17312 microblazeel
17314 Not documented
17315 mips Not documented
17317 mips64 Not documented
17319 mips64el
17321 Not documented
17322 mipsel Not documented
17324 nios2 Not documented
17326 or1k Not documented
17328 ppc Not documented
17330 ppc64 Not documented
17332 riscv32
17334 Not documented
17335 riscv64
17337 Not documented
17338 s390x Not documented
17340 sh4 Not documented
17342 sh4eb Not documented
17344 sparc Not documented
17346 sparc64
17348 Not documented
17349 tricore
17351 Not documented
17352 x86_64 Not documented
17354 xtensa Not documented
17356 xtensaeb
17358 Not documented
17359 Notes
17361 The resulting QMP strings can be appended to the "qemu-system-" prefix
17362 to produce the corresponding QEMU executable name. This is true even
17363 for "qemu-system-x86_64".
17364 Since
17366 3.0
17367 CpuS390State (Enum)
17369 An enumeration of cpu states that can be assumed by a virtual S390 CPU
17370 Values
17372 uninitialized
17373 Not documented
17374 stopped
17376 Not documented
17377 check-stop
17379 Not documented
17380 operating
17382 Not documented
17383 load Not documented
17385 Since
17387 2.12
17388 CpuInfoS390 (Object)
17390 Additional information about a virtual S390 CPU
17391 Members
17393 cpu-state: CpuS390State
17394 the virtual CPU's state
17395 Since
17397 2.12
17398 CpuInfoFast (Object)
17400 Information about a virtual CPU
17401 Members
17403 cpu-index: int
17404 index of the virtual CPU
17405 qom-path: string
17407 path to the CPU object in the QOM tree
17408 thread-id: int
17410 ID of the underlying host thread
17411 props: CpuInstanceProperties (optional)
17413 properties describing to which node/socket/core/thread virtual
17414 CPU belongs to, provided if supported by board
17415 target: SysEmuTarget
17417 the QEMU system emulation target, which determines which addi‐
17418 tional fields will be listed (since 3.0)
17419 The members of CpuInfoS390 when target is "s390x"
17421 Since
17423 2.12
17424 query-cpus-fast (Command)
17426 Returns information about all virtual CPUs.
17427 Returns
17429 list of CpuInfoFast
17430 Since
17432 2.12
17433 Example
17435 -> { "execute": "query-cpus-fast" }
17436 <- { "return": [
17437 {
17438 "thread-id": 25627,
17439 "props": {
17440 "core-id": 0,
17441 "thread-id": 0,
17442 "socket-id": 0
17443 },
17444 "qom-path": "/machine/unattached/device[0]",
17445 "arch":"x86",
17446 "target":"x86_64",
17447 "cpu-index": 0
17448 },
17449 {
17450 "thread-id": 25628,
17451 "props": {
17452 "core-id": 0,
17453 "thread-id": 0,
17454 "socket-id": 1
17455 },
17456 "qom-path": "/machine/unattached/device[2]",
17457 "arch":"x86",
17458 "target":"x86_64",
17459 "cpu-index": 1
17460 }
17461 ]
17462 }
17463 MachineInfo (Object)
17465 Information describing a machine.
17466 Members
17468 name: string
17469 the name of the machine
17470 alias: string (optional)
17472 an alias for the machine name
17473 is-default: boolean (optional)
17475 whether the machine is default
17476 cpu-max: int
17478 maximum number of CPUs supported by the machine type (since 1.5)
17479 hotpluggable-cpus: boolean
17481 cpu hotplug via -device is supported (since 2.7)
17482 numa-mem-supported: boolean
17484 true if '-numa node,mem' option is supported by the machine type
17485 and false otherwise (since 4.1)
17486 deprecated: boolean
17488 if true, the machine type is deprecated and may be removed in
17489 future versions of QEMU according to the QEMU deprecation policy
17490 (since 4.1)
17491 default-cpu-type: string (optional)
17493 default CPU model typename if none is requested via the -cpu ar‐
17494 gument. (since 4.2)
17495 default-ram-id: string (optional)
17497 the default ID of initial RAM memory backend (since 5.2)
17498 Since
17500 1.2
17501 query-machines (Command)
17503 Return a list of supported machines
17504 Returns
17506 a list of MachineInfo
17507 Since
17509 1.2
17510 CurrentMachineParams (Object)
17512 Information describing the running machine parameters.
17513 Members
17515 wakeup-suspend-support: boolean
17516 true if the machine supports wake up from suspend
17517 Since
17519 4.0
17520 query-current-machine (Command)
17522 Return information on the current virtual machine.
17523 Returns
17525 CurrentMachineParams
17526 Since
17528 4.0
17529 TargetInfo (Object)
17531 Information describing the QEMU target.
17532 Members
17534 arch: SysEmuTarget
17535 the target architecture
17536 Since
17538 1.2
17539 query-target (Command)
17541 Return information about the target for this QEMU
17542 Returns
17544 TargetInfo
17545 Since
17547 1.2
17548 UuidInfo (Object)
17550 Guest UUID information (Universally Unique Identifier).
17551 Members
17553 UUID: string
17554 the UUID of the guest
17555 Since
17557 0.14
17558 Notes
17560 If no UUID was specified for the guest, a null UUID is returned.
17561 query-uuid (Command)
17563 Query the guest UUID information.
17564 Returns
17566 The UuidInfo for the guest
17567 Since
17569 0.14
17570 Example
17572 -> { "execute": "query-uuid" }
17573 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
17574 GuidInfo (Object)
17576 GUID information.
17577 Members
17579 guid: string
17580 the globally unique identifier
17581 Since
17583 2.9
17584 query-vm-generation-id (Command)
17586 Show Virtual Machine Generation ID
17587 Since
17589 2.9
17590 system_reset (Command)
17592 Performs a hard reset of a guest.
17593 Since
17595 0.14
17596 Example
17598 -> { "execute": "system_reset" }
17599 <- { "return": {} }
17600 system_powerdown (Command)
17602 Requests that a guest perform a powerdown operation.
17603 Since
17605 0.14
17606 Notes
17608 A guest may or may not respond to this command. This command returning
17609 does not indicate that a guest has accepted the request or that it has
17610 shut down. Many guests will respond to this command by prompting the
17611 user in some way.
17612 Example
17614 -> { "execute": "system_powerdown" }
17615 <- { "return": {} }
17616 system_wakeup (Command)
17618 Wake up guest from suspend. If the guest has wake-up from suspend sup‐
17619 port enabled (wakeup-suspend-support flag from query-current-machine),
17620 wake-up guest from suspend if the guest is in SUSPENDED state. Return
17621 an error otherwise.
17622 Since
17624 1.1
17625 Returns
17627 nothing.
17628 Note
17630 prior to 4.0, this command does nothing in case the guest isn't sus‐
17631 pended.
17632 Example
17634 -> { "execute": "system_wakeup" }
17635 <- { "return": {} }
17636 LostTickPolicy (Enum)
17638 Policy for handling lost ticks in timer devices. Ticks end up getting
17639 lost when, for example, the guest is paused.
17640 Values
17642 discard
17643 throw away the missed ticks and continue with future injection
17644 normally. The guest OS will see the timer jump ahead by a po‐
17645 tentially quite significant amount all at once, as if the inter‐
17646 vening chunk of time had simply not existed; needless to say,
17647 such a sudden jump can easily confuse a guest OS which is not
17648 specifically prepared to deal with it. Assuming the guest OS
17649 can deal correctly with the time jump, the time in the guest and
17650 in the host should now match.
17651 delay continue to deliver ticks at the normal rate. The guest OS will
17653 not notice anything is amiss, as from its point of view time
17654 will have continued to flow normally. The time in the guest
17655 should now be behind the time in the host by exactly the amount
17656 of time during which ticks have been missed.
17657 slew deliver ticks at a higher rate to catch up with the missed
17659 ticks. The guest OS will not notice anything is amiss, as from
17660 its point of view time will have continued to flow normally.
17661 Once the timer has managed to catch up with all the missing
17662 ticks, the time in the guest and in the host should match.
17663 Since
17665 2.0
17666 inject-nmi (Command)
17668 Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all
17669 CPUs (ppc64). The command fails when the guest doesn't support inject‐
17670 ing.
17671 Returns
17673 If successful, nothing
17674 Since
17676 0.14
17677 Note
17679 prior to 2.1, this command was only supported for x86 and s390 VMs
17680 Example
17682 -> { "execute": "inject-nmi" }
17683 <- { "return": {} }
17684 KvmInfo (Object)
17686 Information about support for KVM acceleration
17687 Members
17689 enabled: boolean
17690 true if KVM acceleration is active
17691 present: boolean
17693 true if KVM acceleration is built into this executable
17694 Since
17696 0.14
17697 query-kvm (Command)
17699 Returns information about KVM acceleration
17700 Returns
17702 KvmInfo
17703 Since
17705 0.14
17706 Example
17708 -> { "execute": "query-kvm" }
17709 <- { "return": { "enabled": true, "present": true } }
17710 NumaOptionsType (Enum)
17712 Values
17713 node NUMA nodes configuration
17714 dist NUMA distance configuration (since 2.10)
17716 cpu property based CPU(s) to node mapping (Since: 2.10)
17718 hmat-lb
17720 memory latency and bandwidth information (Since: 5.0)
17721 hmat-cache
17723 memory side cache information (Since: 5.0)
17724 Since
17726 2.1
17727 NumaOptions (Object)
17729 A discriminated record of NUMA options. (for OptsVisitor)
17730 Members
17732 type: NumaOptionsType
17733 Not documented
17734 The members of NumaNodeOptions when type is "node"
17736 The members of NumaDistOptions when type is "dist"
17738 The members of NumaCpuOptions when type is "cpu"
17740 The members of NumaHmatLBOptions when type is "hmat-lb"
17742 The members of NumaHmatCacheOptions when type is "hmat-cache"
17744 Since
17746 2.1
17747 NumaNodeOptions (Object)
17749 Create a guest NUMA node. (for OptsVisitor)
17750 Members
17752 nodeid: int (optional)
17753 NUMA node ID (increase by 1 from 0 if omitted)
17754 cpus: array of int (optional)
17756 VCPUs belonging to this node (assign VCPUS round-robin
17758 if omitted)
17759 mem: int (optional)
17761 memory size of this node; mutually exclusive with memdev.
17762 Equally divide total memory among nodes if both mem and memdev
17763 are omitted.
17764 memdev: string (optional)
17766 memory backend object. If specified for one node, it must be
17767 specified for all nodes.
17768 initiator: int (optional)
17770 defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the
17771 nodeid which has the memory controller responsible for this NUMA
17772 node. This field provides additional information as to the ini‐
17773 tiator node that is closest (as in directly attached) to this
17774 node, and therefore has the best performance (since 5.0)
17775 Since
17777 2.1
17778 NumaDistOptions (Object)
17780 Set the distance between 2 NUMA nodes.
17781 Members
17783 src: int
17784 source NUMA node.
17785 dst: int
17787 destination NUMA node.
17788 val: int
17790 NUMA distance from source node to destination node. When a node
17791 is unreachable from another node, set the distance between them
17792 to 255.
17793 Since
17795 2.10
17796 X86CPURegister32 (Enum)
17798 A X86 32-bit register
17799 Values
17801 EAX Not documented
17802 EBX Not documented
17804 ECX Not documented
17806 EDX Not documented
17808 ESP Not documented
17810 EBP Not documented
17812 ESI Not documented
17814 EDI Not documented
17816 Since
17818 1.5
17819 X86CPUFeatureWordInfo (Object)
17821 Information about a X86 CPU feature word
17822 Members
17824 cpuid-input-eax: int
17825 Input EAX value for CPUID instruction for that feature word
17826 cpuid-input-ecx: int (optional)
17828 Input ECX value for CPUID instruction for that feature word
17829 cpuid-register: X86CPURegister32
17831 Output register containing the feature bits
17832 features: int
17834 value of output register, containing the feature bits
17835 Since
17837 1.5
17838 DummyForceArrays (Object)
17840 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList inter‐
17841 nally
17842 Members
17844 unused: array of X86CPUFeatureWordInfo
17845 Not documented
17846 Since
17848 2.5
17849 NumaCpuOptions (Object)
17851 Option "-numa cpu" overrides default cpu to node mapping. It accepts
17852 the same set of cpu properties as returned by query-hotplug‐
17853 gable-cpus[].props, where node-id could be used to override default
17854 node mapping.
17855 Members
17857 The members of CpuInstanceProperties
17858 Since
17860 2.10
17861 HmatLBMemoryHierarchy (Enum)
17863 The memory hierarchy in the System Locality Latency and Bandwidth In‐
17864 formation Structure of HMAT (Heterogeneous Memory Attribute Table)
17865 For more information about HmatLBMemoryHierarchy, see chapter 5.2.27.4:
17867 Table 5-146: Field "Flags" of ACPI 6.3 spec.
17868 Values
17870 memory the structure represents the memory performance
17871 first-level
17873 first level of memory side cache
17874 second-level
17876 second level of memory side cache
17877 third-level
17879 third level of memory side cache
17880 Since
17882 5.0
17883 HmatLBDataType (Enum)
17885 Data type in the System Locality Latency and Bandwidth Information
17886 Structure of HMAT (Heterogeneous Memory Attribute Table)
17887 For more information about HmatLBDataType, see chapter 5.2.27.4: Table
17889 5-146: Field "Data Type" of ACPI 6.3 spec.
17890 Values
17892 access-latency
17893 access latency (nanoseconds)
17894 read-latency
17896 read latency (nanoseconds)
17897 write-latency
17899 write latency (nanoseconds)
17900 access-bandwidth
17902 access bandwidth (Bytes per second)
17903 read-bandwidth
17905 read bandwidth (Bytes per second)
17906 write-bandwidth
17908 write bandwidth (Bytes per second)
17909 Since
17911 5.0
17912 NumaHmatLBOptions (Object)
17914 Set the system locality latency and bandwidth information between Ini‐
17915 tiator and Target proximity Domains.
17916 For more information about NumaHmatLBOptions, see chapter 5.2.27.4: Ta‐
17918 ble 5-146 of ACPI 6.3 spec.
17919 Members
17921 initiator: int
17922 the Initiator Proximity Domain.
17923 target: int
17925 the Target Proximity Domain.
17926 hierarchy: HmatLBMemoryHierarchy
17928 the Memory Hierarchy. Indicates the performance of memory or
17929 side cache.
17930 data-type: HmatLBDataType
17932 presents the type of data, access/read/write latency or hit la‐
17933 tency.
17934 latency: int (optional)
17936 the value of latency from initiator to target proximity domain,
17937 the latency unit is "ns(nanosecond)".
17938 bandwidth: int (optional)
17940 the value of bandwidth between initiator and target proximity
17941 domain, the bandwidth unit is "Bytes per second".
17942 Since
17944 5.0
17945 HmatCacheAssociativity (Enum)
17947 Cache associativity in the Memory Side Cache Information Structure of
17948 HMAT
17949 For more information of HmatCacheAssociativity, see chapter 5.2.27.5:
17951 Table 5-147 of ACPI 6.3 spec.
17952 Values
17954 none
17955 None (no memory side cache in this proximity domain,
17957 or cache associativity unknown)
17958 direct Direct Mapped
17960 complex
17962 Complex Cache Indexing (implementation specific)
17963 Since
17965 5.0
17966 HmatCacheWritePolicy (Enum)
17968 Cache write policy in the Memory Side Cache Information Structure of
17969 HMAT
17970 For more information of HmatCacheWritePolicy, see chapter 5.2.27.5: Ta‐
17972 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
17973 Values
17975 none None (no memory side cache in this proximity domain, or cache
17976 write policy unknown)
17977 write-back
17979 Write Back (WB)
17980 write-through
17982 Write Through (WT)
17983 Since
17985 5.0
17986 NumaHmatCacheOptions (Object)
17988 Set the memory side cache information for a given memory domain.
17989 For more information of NumaHmatCacheOptions, see chapter 5.2.27.5: Ta‐
17991 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
17992 Members
17994 node-id: int
17995 the memory proximity domain to which the memory belongs.
17996 size: int
17998 the size of memory side cache in bytes.
17999 level: int
18001 the cache level described in this structure.
18002 associativity: HmatCacheAssociativity
18004 the cache associativity, none/direct-mapped/complex(complex
18005 cache indexing).
18006 policy: HmatCacheWritePolicy
18008 the write policy, none/write-back/write-through.
18009 line: int
18011 the cache Line size in bytes.
18012 Since
18014 5.0
18015 memsave (Command)
18017 Save a portion of guest memory to a file.
18018 Arguments
18020 val: int
18021 the virtual address of the guest to start from
18022 size: int
18024 the size of memory region to save
18025 filename: string
18027 the file to save the memory to as binary data
18028 cpu-index: int (optional)
18030 the index of the virtual CPU to use for translating the virtual
18031 address (defaults to CPU 0)
18032 Returns
18034 Nothing on success
18035 Since
18037 0.14
18038 Notes
18040 Errors were not reliably returned until 1.1
18041 Example
18043 -> { "execute": "memsave",
18044 "arguments": { "val": 10,
18045 "size": 100,
18046 "filename": "/tmp/virtual-mem-dump" } }
18047 <- { "return": {} }
18048 pmemsave (Command)
18050 Save a portion of guest physical memory to a file.
18051 Arguments
18053 val: int
18054 the physical address of the guest to start from
18055 size: int
18057 the size of memory region to save
18058 filename: string
18060 the file to save the memory to as binary data
18061 Returns
18063 Nothing on success
18064 Since
18066 0.14
18067 Notes
18069 Errors were not reliably returned until 1.1
18070 Example
18072 -> { "execute": "pmemsave",
18073 "arguments": { "val": 10,
18074 "size": 100,
18075 "filename": "/tmp/physical-mem-dump" } }
18076 <- { "return": {} }
18077 Memdev (Object)
18079 Information about memory backend
18080 Members
18082 id: string (optional)
18083 backend's ID if backend has 'id' property (since 2.9)
18084 size: int
18086 memory backend size
18087 merge: boolean
18089 whether memory merge support is enabled
18090 dump: boolean
18092 whether memory backend's memory is included in a core dump
18093 prealloc: boolean
18095 whether memory was preallocated
18096 share: boolean
18098 whether memory is private to QEMU or shared (since 6.1)
18099 reserve: boolean (optional)
18101 whether swap space (or huge pages) was reserved if applicable.
18102 This corresponds to the user configuration and not the actual
18103 behavior implemented in the OS to perform the reservation. For
18104 example, Linux will never reserve swap space for shared file
18105 mappings. (since 6.1)
18106 host-nodes: array of int
18108 host nodes for its memory policy
18109 policy: HostMemPolicy
18111 memory policy of memory backend
18112 Since
18114 2.1
18115 query-memdev (Command)
18117 Returns information for all memory backends.
18118 Returns
18120 a list of Memdev.
18121 Since
18123 2.1
18124 Example
18126 -> { "execute": "query-memdev" }
18127 <- { "return": [
18128 {
18129 "id": "mem1",
18130 "size": 536870912,
18131 "merge": false,
18132 "dump": true,
18133 "prealloc": false,
18134 "host-nodes": [0, 1],
18135 "policy": "bind"
18136 },
18137 {
18138 "size": 536870912,
18139 "merge": false,
18140 "dump": true,
18141 "prealloc": true,
18142 "host-nodes": [2, 3],
18143 "policy": "preferred"
18144 }
18145 ]
18146 }
18147 CpuInstanceProperties (Object)
18149 List of properties to be used for hotplugging a CPU instance, it should
18150 be passed by management with device_add command when a CPU is being
18151 hotplugged.
18152 Members
18154 node-id: int (optional)
18155 NUMA node ID the CPU belongs to
18156 socket-id: int (optional)
18158 socket number within node/board the CPU belongs to
18159 die-id: int (optional)
18161 die number within node/board the CPU belongs to (Since 4.1)
18162 core-id: int (optional)
18164 core number within die the CPU belongs to
18165 thread-id: int (optional)
18167 thread number within core the CPU belongs to
18168 Note
18170 currently there are 5 properties that could be present but management
18171 should be prepared to pass through other properties with device_add
18172 command to allow for future interface extension. This also requires the
18173 filed names to be kept in sync with the properties passed to -de‐
18174 vice/device_add.
18175 Since
18177 2.7
18178 HotpluggableCPU (Object)
18180 Members
18181 type: string
18182 CPU object type for usage with device_add command
18183 props: CpuInstanceProperties
18185 list of properties to be used for hotplugging CPU
18186 vcpus-count: int
18188 number of logical VCPU threads HotpluggableCPU provides
18189 qom-path: string (optional)
18191 link to existing CPU object if CPU is present or omitted if CPU
18192 is not present.
18193 Since
18195 2.7
18196 query-hotpluggable-cpus (Command)
18198 TODO
18199 Better documentation; currently there is none.
18200 Returns
18202 a list of HotpluggableCPU objects.
18203 Since
18205 2.7
18206 Example
18208 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
18209 -> { "execute": "query-hotpluggable-cpus" }
18211 <- {"return": [
18212 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
18213 "vcpus-count": 1 },
18214 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
18215 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
18216 ]}'
18217 For pc machine type started with -smp 1,maxcpus=2:
18219 -> { "execute": "query-hotpluggable-cpus" }
18221 <- {"return": [
18222 {
18223 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
18224 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
18225 },
18226 {
18227 "qom-path": "/machine/unattached/device[0]",
18228 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
18229 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
18230 }
18231 ]}
18232 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
18234 (Since: 2.11):
18235 -> { "execute": "query-hotpluggable-cpus" }
18237 <- {"return": [
18238 {
18239 "type": "qemu-s390x-cpu", "vcpus-count": 1,
18240 "props": { "core-id": 1 }
18241 },
18242 {
18243 "qom-path": "/machine/unattached/device[0]",
18244 "type": "qemu-s390x-cpu", "vcpus-count": 1,
18245 "props": { "core-id": 0 }
18246 }
18247 ]}
18248 set-numa-node (Command)
18250 Runtime equivalent of '-numa' CLI option, available at preconfigure
18251 stage to configure numa mapping before initializing machine.
18252 Since 3.0
18254 Arguments
18256 The members of NumaOptions
18257 balloon (Command)
18259 Request the balloon driver to change its balloon size.
18260 Arguments
18262 value: int
18263 the target logical size of the VM in bytes. We can deduce the
18264 size of the balloon using this formula:
18265 logical_vm_size = vm_ram_size - balloon_size
18266 From it we have: balloon_size = vm_ram_size - value
18268 Returns
18270 • Nothing on success
18271 • If the balloon driver is enabled but not functional because the KVM
18273 kernel module cannot support it, KvmMissingCap
18274 • If no balloon device is present, DeviceNotActive
18276 Notes
18278 This command just issues a request to the guest. When it returns, the
18279 balloon size may not have changed. A guest can change the balloon size
18280 independent of this command.
18281 Since
18283 0.14
18284 Example
18286 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
18287 <- { "return": {} }
18288 With a 2.5GiB guest this command inflated the ballon to 3GiB.
18290 BalloonInfo (Object)
18292 Information about the guest balloon device.
18293 Members
18295 actual: int
18296 the logical size of the VM in bytes Formula used: logi‐
18297 cal_vm_size = vm_ram_size - balloon_size
18298 Since
18300 0.14
18301 query-balloon (Command)
18303 Return information about the balloon device.
18304 Returns
18306 • BalloonInfo on success
18307 • If the balloon driver is enabled but not functional because the KVM
18309 kernel module cannot support it, KvmMissingCap
18310 • If no balloon device is present, DeviceNotActive
18312 Since
18314 0.14
18315 Example
18317 -> { "execute": "query-balloon" }
18318 <- { "return": {
18319 "actual": 1073741824,
18320 }
18321 }
18322 BALLOON_CHANGE (Event)
18324 Emitted when the guest changes the actual BALLOON level. This value is
18325 equivalent to the actual field return by the 'query-balloon' command
18326 Arguments
18328 actual: int
18329 the logical size of the VM in bytes Formula used: logi‐
18330 cal_vm_size = vm_ram_size - balloon_size
18331 Note
18333 this event is rate-limited.
18334 Since
18336 1.2
18337 Example
18339 <- { "event": "BALLOON_CHANGE",
18340 "data": { "actual": 944766976 },
18341 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
18342 MemoryInfo (Object)
18344 Actual memory information in bytes.
18345 Members
18347 base-memory: int
18348 size of "base" memory specified with command line option -m.
18349 plugged-memory: int (optional)
18351 size of memory that can be hot-unplugged. This field is omitted
18352 if target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE
18353 not defined at build time).
18354 Since
18356 2.11
18357 query-memory-size-summary (Command)
18359 Return the amount of initially allocated and present hotpluggable (if
18360 enabled) memory in bytes.
18361 Example
18363 -> { "execute": "query-memory-size-summary" }
18364 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
18365 Since
18367 2.11
18368 PCDIMMDeviceInfo (Object)
18370 PCDIMMDevice state information
18371 Members
18373 id: string (optional)
18374 device's ID
18375 addr: int
18377 physical address, where device is mapped
18378 size: int
18380 size of memory that the device provides
18381 slot: int
18383 slot number at which device is plugged in
18384 node: int
18386 NUMA node number where device is plugged in
18387 memdev: string
18389 memory backend linked with device
18390 hotplugged: boolean
18392 true if device was hotplugged
18393 hotpluggable: boolean
18395 true if device if could be added/removed while machine is run‐
18396 ning
18397 Since
18399 2.1
18400 VirtioPMEMDeviceInfo (Object)
18402 VirtioPMEM state information
18403 Members
18405 id: string (optional)
18406 device's ID
18407 memaddr: int
18409 physical address in memory, where device is mapped
18410 size: int
18412 size of memory that the device provides
18413 memdev: string
18415 memory backend linked with device
18416 Since
18418 4.1
18419 VirtioMEMDeviceInfo (Object)
18421 VirtioMEMDevice state information
18422 Members
18424 id: string (optional)
18425 device's ID
18426 memaddr: int
18428 physical address in memory, where device is mapped
18429 requested-size: int
18431 the user requested size of the device
18432 size: int
18434 the (current) size of memory that the device provides
18435 max-size: int
18437 the maximum size of memory that the device can provide
18438 block-size: int
18440 the block size of memory that the device provides
18441 node: int
18443 NUMA node number where device is assigned to
18444 memdev: string
18446 memory backend linked with the region
18447 Since
18449 5.1
18450 SgxEPCDeviceInfo (Object)
18452 Sgx EPC state information
18453 Members
18455 id: string (optional)
18456 device's ID
18457 memaddr: int
18459 physical address in memory, where device is mapped
18460 size: int
18462 size of memory that the device provides
18463 memdev: string
18465 memory backend linked with device
18466 Since
18468 6.2
18469 MemoryDeviceInfoKind (Enum)
18471 Values
18472 dimm Not documented
18473 nvdimm Not documented
18475 virtio-pmem
18477 Not documented
18478 virtio-mem
18480 Not documented
18481 sgx-epc
18483 Not documented
18484 Since
18486 2.1
18487 PCDIMMDeviceInfoWrapper (Object)
18489 Members
18490 data: PCDIMMDeviceInfo
18491 Not documented
18492 Since
18494 2.1
18495 VirtioPMEMDeviceInfoWrapper (Object)
18497 Members
18498 data: VirtioPMEMDeviceInfo
18499 Not documented
18500 Since
18502 2.1
18503 VirtioMEMDeviceInfoWrapper (Object)
18505 Members
18506 data: VirtioMEMDeviceInfo
18507 Not documented
18508 Since
18510 2.1
18511 SgxEPCDeviceInfoWrapper (Object)
18513 Members
18514 data: SgxEPCDeviceInfo
18515 Not documented
18516 Since
18518 6.2
18519 MemoryDeviceInfo (Object)
18521 Union containing information about a memory device
18522 nvdimm is included since 2.12. virtio-pmem is included since 4.1. vir‐
18524 tio-mem is included since 5.1. sgx-epc is included since 6.2.
18525 Members
18527 type: MemoryDeviceInfoKind
18528 Not documented
18529 The members of PCDIMMDeviceInfoWrapper when type is "dimm"
18531 The members of PCDIMMDeviceInfoWrapper when type is "nvdimm"
18533 The members of VirtioPMEMDeviceInfoWrapper when type is "virtio-pmem"
18535 The members of VirtioMEMDeviceInfoWrapper when type is "virtio-mem"
18537 The members of SgxEPCDeviceInfoWrapper when type is "sgx-epc"
18539 Since
18541 2.1
18542 SgxEPC (Object)
18544 Sgx EPC cmdline information
18545 Members
18547 memdev: string
18548 memory backend linked with device
18549 Since
18551 6.2
18552 SgxEPCProperties (Object)
18554 SGX properties of machine types.
18555 Members
18557 sgx-epc: array of SgxEPC
18558 list of ids of memory-backend-epc objects.
18559 Since
18561 6.2
18562 query-memory-devices (Command)
18564 Lists available memory devices and their state
18565 Since
18567 2.1
18568 Example
18570 -> { "execute": "query-memory-devices" }
18571 <- { "return": [ { "data":
18572 { "addr": 5368709120,
18573 "hotpluggable": true,
18574 "hotplugged": true,
18575 "id": "d1",
18576 "memdev": "/objects/memX",
18577 "node": 0,
18578 "size": 1073741824,
18579 "slot": 0},
18580 "type": "dimm"
18581 } ] }
18582 MEMORY_DEVICE_SIZE_CHANGE (Event)
18584 Emitted when the size of a memory device changes. Only emitted for mem‐
18585 ory devices that can actually change the size (e.g., virtio-mem due to
18586 guest action).
18587 Arguments
18589 id: string (optional)
18590 device's ID
18591 size: int
18593 the new size of memory that the device provides
18594 qom-path: string
18596 path to the device object in the QOM tree (since 6.2)
18597 Note
18599 this event is rate-limited.
18600 Since
18602 5.1
18603 Example
18605 <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
18606 "data": { "id": "vm0", "size": 1073741824},
18607 "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
18608 MEM_UNPLUG_ERROR (Event)
18610 Emitted when memory hot unplug error occurs.
18611 Arguments
18613 device: string
18614 device name
18615 msg: string
18617 Informative message
18618 Features
18620 deprecated
18621 This event is deprecated. Use DEVICE_UNPLUG_GUEST_ERROR instead.
18622 Since
18624 2.4
18625 Example
18627 <- { "event": "MEM_UNPLUG_ERROR"
18628 "data": { "device": "dimm1",
18629 "msg": "acpi: device unplug for unsupported device"
18630 },
18631 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
18632 SMPConfiguration (Object)
18634 Schema for CPU topology configuration. A missing value lets QEMU fig‐
18635 ure out a suitable value based on the ones that are provided.
18636 Members
18638 cpus: int (optional)
18639 number of virtual CPUs in the virtual machine
18640 sockets: int (optional)
18642 number of sockets in the CPU topology
18643 dies: int (optional)
18645 number of dies per socket in the CPU topology
18646 cores: int (optional)
18648 number of cores per die in the CPU topology
18649 threads: int (optional)
18651 number of threads per core in the CPU topology
18652 maxcpus: int (optional)
18654 maximum number of hotpluggable virtual CPUs in the virtual ma‐
18655 chine
18656 Since
18658 6.1
18659 x-query-irq (Command)
18661 Query interrupt statistics
18662 Features
18664 unstable
18665 This command is meant for debugging.
18666 Returns
18668 interrupt statistics
18669 Since
18671 6.2
18672 x-query-jit (Command)
18674 Query TCG compiler statistics
18675 Features
18677 unstable
18678 This command is meant for debugging.
18679 Returns
18681 TCG compiler statistics
18682 Since
18684 6.2
18685 If
18687 CONFIG_TCG
18688 x-query-numa (Command)
18690 Query NUMA topology information
18691 Features
18693 unstable
18694 This command is meant for debugging.
18695 Returns
18697 topology information
18698 Since
18700 6.2
18701 x-query-opcount (Command)
18703 Query TCG opcode counters
18704 Features
18706 unstable
18707 This command is meant for debugging.
18708 Returns
18710 TCG opcode counters
18711 Since
18713 6.2
18714 If
18716 CONFIG_TCG
18717 x-query-profile (Command)
18719 Query TCG profiling information
18720 Features
18722 unstable
18723 This command is meant for debugging.
18724 Returns
18726 profile information
18727 Since
18729 6.2
18730 x-query-ramblock (Command)
18732 Query system ramblock information
18733 Features
18735 unstable
18736 This command is meant for debugging.
18737 Returns
18739 system ramblock information
18740 Since
18742 6.2
18743 x-query-rdma (Command)
18745 Query RDMA state
18746 Features
18748 unstable
18749 This command is meant for debugging.
18750 Returns
18752 RDMA state
18753 Since
18755 6.2
18756 x-query-roms (Command)
18758 Query information on the registered ROMS
18759 Features
18761 unstable
18762 This command is meant for debugging.
18763 Returns
18765 registered ROMs
18766 Since
18768 6.2
18769 x-query-usb (Command)
18771 Query information on the USB devices
18772 Features
18774 unstable
18775 This command is meant for debugging.
18776 Returns
18778 USB device information
18779 Since
18781 6.2
18782 CpuModelInfo (Object)
18784 Virtual CPU model.
18785 A CPU model consists of the name of a CPU definition, to which delta
18787 changes are applied (e.g. features added/removed). Most magic values
18788 that an architecture might require should be hidden behind the name.
18789 However, if required, architectures can expose relevant properties.
18790 Members
18792 name: string
18793 the name of the CPU definition the model is based on
18794 props: value (optional)
18796 a dictionary of QOM properties to be applied
18797 Since
18799 2.8
18800 CpuModelExpansionType (Enum)
18802 An enumeration of CPU model expansion types.
18803 Values
18805 static Expand to a static CPU model, a combination of a static base
18806 model name and property delta changes. As the static base model
18807 will never change, the expanded CPU model will be the same, in‐
18808 dependent of QEMU version, machine type, machine options, and
18809 accelerator options. Therefore, the resulting model can be used
18810 by tooling without having to specify a compatibility machine -
18811 e.g. when displaying the "host" model. The static CPU models are
18812 migration-safe.
18813 full Expand all properties. The produced model is not guaranteed to
18815 be migration-safe, but allows tooling to get an insight and work
18816 with model details.
18817 Note
18819 When a non-migration-safe CPU model is expanded in static mode, some
18820 features enabled by the CPU model may be omitted, because they can't be
18821 implemented by a static CPU model definition (e.g. cache info
18822 passthrough and PMU passthrough in x86). If you need an accurate repre‐
18823 sentation of the features enabled by a non-migration-safe CPU model,
18824 use full. If you need a static representation that will keep ABI com‐
18825 patibility even when changing QEMU version or machine-type, use static
18826 (but keep in mind that some features may be omitted).
18827 Since
18829 2.8
18830 CpuModelCompareResult (Enum)
18832 An enumeration of CPU model comparison results. The result is usually
18833 calculated using e.g. CPU features or CPU generations.
18834 Values
18836 incompatible
18837 If model A is incompatible to model B, model A is not guaranteed
18838 to run where model B runs and the other way around.
18839 identical
18841 If model A is identical to model B, model A is guaranteed to run
18842 where model B runs and the other way around.
18843 superset
18845 If model A is a superset of model B, model B is guaranteed to
18846 run where model A runs. There are no guarantees about the other
18847 way.
18848 subset If model A is a subset of model B, model A is guaranteed to run
18850 where model B runs. There are no guarantees about the other way.
18851 Since
18853 2.8
18854 CpuModelBaselineInfo (Object)
18856 The result of a CPU model baseline.
18857 Members
18859 model: CpuModelInfo
18860 the baselined CpuModelInfo.
18861 Since
18863 2.8
18864 If
18866 TARGET_S390X
18867 CpuModelCompareInfo (Object)
18869 The result of a CPU model comparison.
18870 Members
18872 result: CpuModelCompareResult
18873 The result of the compare operation.
18874 responsible-properties: array of string
18876 List of properties that led to the comparison result not being
18877 identical.
18878 responsible-properties is a list of QOM property names that led to both
18879 CPUs not being detected as identical. For identical models, this list
18880 is empty. If a QOM property is read-only, that means there's no known
18881 way to make the CPU models identical. If the special property name
18882 "type" is included, the models are by definition not identical and can‐
18883 not be made identical.
18884 Since
18886 2.8
18887 If
18889 TARGET_S390X
18890 query-cpu-model-comparison (Command)
18892 Compares two CPU models, returning how they compare in a specific con‐
18893 figuration. The results indicates how both models compare regarding
18894 runnability. This result can be used by tooling to make decisions if a
18895 certain CPU model will run in a certain configuration or if a compati‐
18896 ble CPU model has to be created by baselining.
18897 Usually, a CPU model is compared against the maximum possible CPU model
18899 of a certain configuration (e.g. the "host" model for KVM). If that CPU
18900 model is identical or a subset, it will run in that configuration.
18901 The result returned by this command may be affected by:
18903 • QEMU version: CPU models may look different depending on the QEMU
18905 version. (Except for CPU models reported as "static" in
18906 query-cpu-definitions.)
18907 • machine-type: CPU model may look different depending on the ma‐
18909 chine-type. (Except for CPU models reported as "static" in
18910 query-cpu-definitions.)
18911 • machine options (including accelerator): in some architectures, CPU
18913 models may look different depending on machine and accelerator op‐
18914 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
18915 nitions.)
18916 • "-cpu" arguments and global properties: arguments to the -cpu option
18918 and global properties may affect expansion of CPU models. Using
18919 query-cpu-model-expansion while using these is not advised.
18920 Some architectures may not support comparing CPU models. s390x supports
18922 comparing CPU models.
18923 Arguments
18925 modela: CpuModelInfo
18926 Not documented
18927 modelb: CpuModelInfo
18929 Not documented
18930 Returns
18932 a CpuModelBaselineInfo. Returns an error if comparing CPU models is not
18933 supported, if a model cannot be used, if a model contains an unknown
18934 cpu definition name, unknown properties or properties with wrong types.
18935 Note
18937 this command isn't specific to s390x, but is only implemented on this
18938 architecture currently.
18939 Since
18941 2.8
18942 If
18944 TARGET_S390X
18945 query-cpu-model-baseline (Command)
18947 Baseline two CPU models, creating a compatible third model. The created
18948 model will always be a static, migration-safe CPU model (see "static"
18949 CPU model expansion for details).
18950 This interface can be used by tooling to create a compatible CPU model
18952 out two CPU models. The created CPU model will be identical to or a
18953 subset of both CPU models when comparing them. Therefore, the created
18954 CPU model is guaranteed to run where the given CPU models run.
18955 The result returned by this command may be affected by:
18957 • QEMU version: CPU models may look different depending on the QEMU
18959 version. (Except for CPU models reported as "static" in
18960 query-cpu-definitions.)
18961 • machine-type: CPU model may look different depending on the ma‐
18963 chine-type. (Except for CPU models reported as "static" in
18964 query-cpu-definitions.)
18965 • machine options (including accelerator): in some architectures, CPU
18967 models may look different depending on machine and accelerator op‐
18968 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
18969 nitions.)
18970 • "-cpu" arguments and global properties: arguments to the -cpu option
18972 and global properties may affect expansion of CPU models. Using
18973 query-cpu-model-expansion while using these is not advised.
18974 Some architectures may not support baselining CPU models. s390x sup‐
18976 ports baselining CPU models.
18977 Arguments
18979 modela: CpuModelInfo
18980 Not documented
18981 modelb: CpuModelInfo
18983 Not documented
18984 Returns
18986 a CpuModelBaselineInfo. Returns an error if baselining CPU models is
18987 not supported, if a model cannot be used, if a model contains an un‐
18988 known cpu definition name, unknown properties or properties with wrong
18989 types.
18990 Note
18992 this command isn't specific to s390x, but is only implemented on this
18993 architecture currently.
18994 Since
18996 2.8
18997 If
18999 TARGET_S390X
19000 CpuModelExpansionInfo (Object)
19002 The result of a cpu model expansion.
19003 Members
19005 model: CpuModelInfo
19006 the expanded CpuModelInfo.
19007 Since
19009 2.8
19010 If
19012 TARGET_S390X or TARGET_I386 or TARGET_ARM
19013 query-cpu-model-expansion (Command)
19015 Expands a given CPU model (or a combination of CPU model + additional
19016 options) to different granularities, allowing tooling to get an under‐
19017 standing what a specific CPU model looks like in QEMU under a certain
19018 configuration.
19019 This interface can be used to query the "host" CPU model.
19021 The data returned by this command may be affected by:
19023 • QEMU version: CPU models may look different depending on the QEMU
19025 version. (Except for CPU models reported as "static" in
19026 query-cpu-definitions.)
19027 • machine-type: CPU model may look different depending on the ma‐
19029 chine-type. (Except for CPU models reported as "static" in
19030 query-cpu-definitions.)
19031 • machine options (including accelerator): in some architectures, CPU
19033 models may look different depending on machine and accelerator op‐
19034 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
19035 nitions.)
19036 • "-cpu" arguments and global properties: arguments to the -cpu option
19038 and global properties may affect expansion of CPU models. Using
19039 query-cpu-model-expansion while using these is not advised.
19040 Some architectures may not support all expansion types. s390x supports
19042 "full" and "static". Arm only supports "full".
19043 Arguments
19045 type: CpuModelExpansionType
19046 Not documented
19047 model: CpuModelInfo
19049 Not documented
19050 Returns
19052 a CpuModelExpansionInfo. Returns an error if expanding CPU models is
19053 not supported, if the model cannot be expanded, if the model contains
19054 an unknown CPU definition name, unknown properties or properties with a
19055 wrong type. Also returns an error if an expansion type is not sup‐
19056 ported.
19057 Since
19059 2.8
19060 If
19062 TARGET_S390X or TARGET_I386 or TARGET_ARM
19063 CpuDefinitionInfo (Object)
19065 Virtual CPU definition.
19066 Members
19068 name: string
19069 the name of the CPU definition
19070 migration-safe: boolean (optional)
19072 whether a CPU definition can be safely used for migration in
19073 combination with a QEMU compatibility machine when migrating be‐
19074 tween different QEMU versions and between hosts with different
19075 sets of (hardware or software) capabilities. If not provided,
19076 information is not available and callers should not assume the
19077 CPU definition to be migration-safe. (since 2.8)
19078 static: boolean
19080 whether a CPU definition is static and will not change depending
19081 on QEMU version, machine type, machine options and accelerator
19082 options. A static model is always migration-safe. (since 2.8)
19083 unavailable-features: array of string (optional)
19085 List of properties that prevent the CPU model from running in
19086 the current host. (since 2.8)
19087 typename: string
19089 Type name that can be used as argument to device-list-proper‐
19090 ties, to introspect properties configurable using -cpu or
19091 -global. (since 2.9)
19092 alias-of: string (optional)
19094 Name of CPU model this model is an alias for. The target of the
19095 CPU model alias may change depending on the machine type. Man‐
19096 agement software is supposed to translate CPU model aliases in
19097 the VM configuration, because aliases may stop being migra‐
19098 tion-safe in the future (since 4.1)
19099 deprecated: boolean
19101 If true, this CPU model is deprecated and may be removed in in
19102 some future version of QEMU according to the QEMU deprecation
19103 policy. (since 5.2)
19104 unavailable-features is a list of QOM property names that represent CPU
19105 model attributes that prevent the CPU from running. If the QOM prop‐
19106 erty is read-only, that means there's no known way to make the CPU
19107 model run in the current host. Implementations that choose not to pro‐
19108 vide specific information return the property name "type". If the
19109 property is read-write, it means that it MAY be possible to run the CPU
19110 model in the current host if that property is changed. Management soft‐
19111 ware can use it as hints to suggest or choose an alternative for the
19112 user, or just to generate meaningful error messages explaining why the
19113 CPU model can't be used. If unavailable-features is an empty list, the
19114 CPU model is runnable using the current host and machine-type. If un‐
19115 available-features is not present, runnability information for the CPU
19116 is not available.
19117 Since
19119 1.2
19120 If
19122 TARGET_PPC or TARGET_ARM or TARGET_I386 or TARGET_S390X or TARGET_MIPS
19123 query-cpu-definitions (Command)
19125 Return a list of supported virtual CPU definitions
19126 Returns
19128 a list of CpuDefInfo
19129 Since
19131 1.2
19132 If
19134 TARGET_PPC or TARGET_ARM or TARGET_I386 or TARGET_S390X or TARGET_MIPS
19135
19137 ReplayMode (Enum)
19138 Mode of the replay subsystem.
19139 Values
19141 none normal execution mode. Replay or record are not enabled.
19142 record record mode. All non-deterministic data is written into the re‐
19144 play log.
19145 play replay mode. Non-deterministic data required for system execu‐
19147 tion is read from the log.
19148 Since
19150 2.5
19151 ReplayInfo (Object)
19153 Record/replay information.
19154 Members
19156 mode: ReplayMode
19157 current mode.
19158 filename: string (optional)
19160 name of the record/replay log file. It is present only in
19161 record or replay modes, when the log is recorded or replayed.
19162 icount: int
19164 current number of executed instructions.
19165 Since
19167 5.2
19168 query-replay (Command)
19170 Retrieve the record/replay information. It includes current instruc‐
19171 tion count which may be used for replay-break and replay-seek commands.
19172 Returns
19174 record/replay information.
19175 Since
19177 5.2
19178 Example
19180 -> { "execute": "query-replay" }
19181 <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
19182 replay-break (Command)
19184 Set replay breakpoint at instruction count icount. Execution stops
19185 when the specified instruction is reached. There can be at most one
19186 breakpoint. When breakpoint is set, any prior one is removed. The
19187 breakpoint may be set only in replay mode and only "in the future",
19188 i.e. at instruction counts greater than the current one. The current
19189 instruction count can be observed with query-replay.
19190 Arguments
19192 icount: int
19193 instruction count to stop at
19194 Since
19196 5.2
19197 Example
19199 -> { "execute": "replay-break", "data": { "icount": 220414 } }
19200 replay-delete-break (Command)
19202 Remove replay breakpoint which was set with replay-break. The command
19203 is ignored when there are no replay breakpoints.
19204 Since
19206 5.2
19207 Example
19209 -> { "execute": "replay-delete-break" }
19210 replay-seek (Command)
19212 Automatically proceed to the instruction count icount, when replaying
19213 the execution. The command automatically loads nearest snapshot and re‐
19214 plays the execution to find the desired instruction. When there is no
19215 preceding snapshot or the execution is not replayed, then the command
19216 fails. icount for the reference may be obtained with query-replay com‐
19217 mand.
19218 Arguments
19220 icount: int
19221 target instruction count
19222 Since
19224 5.2
19225 Example
19227 -> { "execute": "replay-seek", "data": { "icount": 220414 } }
19228
19230 YankInstanceType (Enum)
19231 An enumeration of yank instance types. See YankInstance for more infor‐
19232 mation.
19233 Values
19235 block-node
19236 Not documented
19237 chardev
19239 Not documented
19240 migration
19242 Not documented
19243 Since
19245 6.0
19246 YankInstanceBlockNode (Object)
19248 Specifies which block graph node to yank. See YankInstance for more in‐
19249 formation.
19250 Members
19252 node-name: string
19253 the name of the block graph node
19254 Since
19256 6.0
19257 YankInstanceChardev (Object)
19259 Specifies which character device to yank. See YankInstance for more in‐
19260 formation.
19261 Members
19263 id: string
19264 the chardev's ID
19265 Since
19267 6.0
19268 YankInstance (Object)
19270 A yank instance can be yanked with the yank qmp command to recover from
19271 a hanging QEMU.
19272 Currently implemented yank instances:
19274 • nbd block device: Yanking it will shut down the connection to
19276 the nbd server without attempting to reconnect.
19277 • socket chardev: Yanking it will shut down the connected
19279 socket.
19280 • migration: Yanking it will shut down all migration connec‐
19282 tions. Unlike migrate_cancel, it will not notify the migration
19283 process, so migration will go into failed state, instead of
19284 cancelled state. yank should be used to recover from hangs.
19285 Members
19287 type: YankInstanceType
19288 Not documented
19289 The members of YankInstanceBlockNode when type is "block-node"
19291 The members of YankInstanceChardev when type is "chardev"
19293 Since
19295 6.0
19296 yank (Command)
19298 Try to recover from hanging QEMU by yanking the specified instances.
19299 See YankInstance for more information.
19300 Takes a list of YankInstance as argument.
19302 Arguments
19304 instances: array of YankInstance
19305 Not documented
19306 Returns
19308 • Nothing on success
19309 • DeviceNotFound error, if any of the YankInstances doesn't exist
19311 Example
19313 -> { "execute": "yank",
19314 "arguments": {
19315 "instances": [
19316 { "type": "block-node",
19317 "node-name": "nbd0" }
19318 ] } }
19319 <- { "return": {} }
19320 Since
19322 6.0
19323 query-yank (Command)
19325 Query yank instances. See YankInstance for more information.
19326 Returns
19328 list of YankInstance
19329 Example
19331 -> { "execute": "query-yank" }
19332 <- { "return": [
19333 { "type": "block-node",
19334 "node-name": "nbd0" }
19335 ] }
19336 Since
19338 6.0
19339
19341 add_client (Command)
19342 Allow client connections for VNC, Spice and socket based character de‐
19343 vices to be passed in to QEMU via SCM_RIGHTS.
19344 Arguments
19346 protocol: string
19347 protocol name. Valid names are "vnc", "spice" or the name of a
19348 character device (eg. from -chardev id=XXXX)
19349 fdname: string
19351 file descriptor name previously passed via 'getfd' command
19352 skipauth: boolean (optional)
19354 whether to skip authentication. Only applies to "vnc" and
19355 "spice" protocols
19356 tls: boolean (optional)
19358 whether to perform TLS. Only applies to the "spice" protocol
19359 Returns
19361 nothing on success.
19362 Since
19364 0.14
19365 Example
19367 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
19368 "fdname": "myclient" } }
19369 <- { "return": {} }
19370 NameInfo (Object)
19372 Guest name information.
19373 Members
19375 name: string (optional)
19376 The name of the guest
19377 Since
19379 0.14
19380 query-name (Command)
19382 Return the name information of a guest.
19383 Returns
19385 NameInfo of the guest
19386 Since
19388 0.14
19389 Example
19391 -> { "execute": "query-name" }
19392 <- { "return": { "name": "qemu-name" } }
19393 IOThreadInfo (Object)
19395 Information about an iothread
19396 Members
19398 id: string
19399 the identifier of the iothread
19400 thread-id: int
19402 ID of the underlying host thread
19403 poll-max-ns: int
19405 maximum polling time in ns, 0 means polling is disabled (since
19406 2.9)
19407 poll-grow: int
19409 how many ns will be added to polling time, 0 means that it's not
19410 configured (since 2.9)
19411 poll-shrink: int
19413 how many ns will be removed from polling time, 0 means that it's
19414 not configured (since 2.9)
19415 aio-max-batch: int
19417 maximum number of requests in a batch for the AIO engine, 0
19418 means that the engine will use its default (since 6.1)
19419 Since
19421 2.0
19422 query-iothreads (Command)
19424 Returns a list of information about each iothread.
19425 Note
19427 this list excludes the QEMU main loop thread, which is not declared us‐
19428 ing the -object iothread command-line option. It is always the main
19429 thread of the process.
19430 Returns
19432 a list of IOThreadInfo for each iothread
19433 Since
19435 2.0
19436 Example
19438 -> { "execute": "query-iothreads" }
19439 <- { "return": [
19440 {
19441 "id":"iothread0",
19442 "thread-id":3134
19443 },
19444 {
19445 "id":"iothread1",
19446 "thread-id":3135
19447 }
19448 ]
19449 }
19450 stop (Command)
19452 Stop all guest VCPU execution.
19453 Since
19455 0.14
19456 Notes
19458 This function will succeed even if the guest is already in the stopped
19459 state. In "inmigrate" state, it will ensure that the guest remains
19460 paused once migration finishes, as if the -S option was passed on the
19461 command line.
19462 Example
19464 -> { "execute": "stop" }
19465 <- { "return": {} }
19466 cont (Command)
19468 Resume guest VCPU execution.
19469 Since
19471 0.14
19472 Returns
19474 If successful, nothing
19475 Notes
19477 This command will succeed if the guest is currently running. It will
19478 also succeed if the guest is in the "inmigrate" state; in this case,
19479 the effect of the command is to make sure the guest starts once migra‐
19480 tion finishes, removing the effect of the -S command line option if it
19481 was passed.
19482 Example
19484 -> { "execute": "cont" }
19485 <- { "return": {} }
19486 x-exit-preconfig (Command)
19488 Exit from "preconfig" state
19489 This command makes QEMU exit the preconfig state and proceed with VM
19491 initialization using configuration data provided on the command line
19492 and via the QMP monitor during the preconfig state. The command is only
19493 available during the preconfig state (i.e. when the --preconfig command
19494 line option was in use).
19495 Features
19497 unstable
19498 This command is experimental.
19499 Since 3.0
19500 Returns
19502 nothing
19503 Example
19505 -> { "execute": "x-exit-preconfig" }
19506 <- { "return": {} }
19507 human-monitor-command (Command)
19509 Execute a command on the human monitor and return the output.
19510 Arguments
19512 command-line: string
19513 the command to execute in the human monitor
19514 cpu-index: int (optional)
19516 The CPU to use for commands that require an implicit CPU
19517 Features
19519 savevm-monitor-nodes
19520 If present, HMP command savevm only snapshots monitor-owned
19521 nodes if they have no parents. This allows the use of 'savevm'
19522 with -blockdev. (since 4.2)
19523 Returns
19525 the output of the command as a string
19526 Since
19528 0.14
19529 Notes
19531 This command only exists as a stop-gap. Its use is highly discouraged.
19532 The semantics of this command are not guaranteed: this means that com‐
19533 mand names, arguments and responses can change or be removed at ANY
19534 time. Applications that rely on long term stability guarantees should
19535 NOT use this command.
19536 Known limitations:
19538 • This command is stateless, this means that commands that depend on
19540 state information (such as getfd) might not work
19541 • Commands that prompt the user for data don't currently work
19543 Example
19545 -> { "execute": "human-monitor-command",
19546 "arguments": { "command-line": "info kvm" } }
19547 <- { "return": "kvm support: enabled\r\n" }
19548 getfd (Command)
19550 Receive a file descriptor via SCM rights and assign it a name
19551 Arguments
19553 fdname: string
19554 file descriptor name
19555 Returns
19557 Nothing on success
19558 Since
19560 0.14
19561 Notes
19563 If fdname already exists, the file descriptor assigned to it will be
19564 closed and replaced by the received file descriptor.
19565 The 'closefd' command can be used to explicitly close the file descrip‐
19567 tor when it is no longer needed.
19568 Example
19570 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
19571 <- { "return": {} }
19572 closefd (Command)
19574 Close a file descriptor previously passed via SCM rights
19575 Arguments
19577 fdname: string
19578 file descriptor name
19579 Returns
19581 Nothing on success
19582 Since
19584 0.14
19585 Example
19587 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
19588 <- { "return": {} }
19589 AddfdInfo (Object)
19591 Information about a file descriptor that was added to an fd set.
19592 Members
19594 fdset-id: int
19595 The ID of the fd set that fd was added to.
19596 fd: int
19598 The file descriptor that was received via SCM rights and added
19599 to the fd set.
19600 Since
19602 1.2
19603 add-fd (Command)
19605 Add a file descriptor, that was passed via SCM rights, to an fd set.
19606 Arguments
19608 fdset-id: int (optional)
19609 The ID of the fd set to add the file descriptor to.
19610 opaque: string (optional)
19612 A free-form string that can be used to describe the fd.
19613 Returns
19615 • AddfdInfo on success
19616 • If file descriptor was not received, FdNotSupplied
19618 • If fdset-id is a negative value, InvalidParameterValue
19620 Notes
19622 The list of fd sets is shared by all monitor connections.
19623 If fdset-id is not specified, a new fd set will be created.
19625 Since
19627 1.2
19628 Example
19630 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
19631 <- { "return": { "fdset-id": 1, "fd": 3 } }
19632 remove-fd (Command)
19634 Remove a file descriptor from an fd set.
19635 Arguments
19637 fdset-id: int
19638 The ID of the fd set that the file descriptor belongs to.
19639 fd: int (optional)
19641 The file descriptor that is to be removed.
19642 Returns
19644 • Nothing on success
19645 • If fdset-id or fd is not found, FdNotFound
19647 Since
19649 1.2
19650 Notes
19652 The list of fd sets is shared by all monitor connections.
19653 If fd is not specified, all file descriptors in fdset-id will be re‐
19655 moved.
19656 Example
19658 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
19659 <- { "return": {} }
19660 FdsetFdInfo (Object)
19662 Information about a file descriptor that belongs to an fd set.
19663 Members
19665 fd: int
19666 The file descriptor value.
19667 opaque: string (optional)
19669 A free-form string that can be used to describe the fd.
19670 Since
19672 1.2
19673 FdsetInfo (Object)
19675 Information about an fd set.
19676 Members
19678 fdset-id: int
19679 The ID of the fd set.
19680 fds: array of FdsetFdInfo
19682 A list of file descriptors that belong to this fd set.
19683 Since
19685 1.2
19686 query-fdsets (Command)
19688 Return information describing all fd sets.
19689 Returns
19691 A list of FdsetInfo
19692 Since
19694 1.2
19695 Note
19697 The list of fd sets is shared by all monitor connections.
19698 Example
19700 -> { "execute": "query-fdsets" }
19701 <- { "return": [
19702 {
19703 "fds": [
19704 {
19705 "fd": 30,
19706 "opaque": "rdonly:/path/to/file"
19707 },
19708 {
19709 "fd": 24,
19710 "opaque": "rdwr:/path/to/file"
19711 }
19712 ],
19713 "fdset-id": 1
19714 },
19715 {
19716 "fds": [
19717 {
19718 "fd": 28
19719 },
19720 {
19721 "fd": 29
19722 }
19723 ],
19724 "fdset-id": 0
19725 }
19726 ]
19727 }
19728 CommandLineParameterType (Enum)
19730 Possible types for an option parameter.
19731 Values
19733 string accepts a character string
19734 boolean
19736 accepts "on" or "off"
19737 number accepts a number
19739 size accepts a number followed by an optional suffix (K)ilo, (M)ega,
19741 (G)iga, (T)era
19742 Since
19744 1.5
19745 CommandLineParameterInfo (Object)
19747 Details about a single parameter of a command line option.
19748 Members
19750 name: string
19751 parameter name
19752 type: CommandLineParameterType
19754 parameter CommandLineParameterType
19755 help: string (optional)
19757 human readable text string, not suitable for parsing.
19758 default: string (optional)
19760 default value string (since 2.1)
19761 Since
19763 1.5
19764 CommandLineOptionInfo (Object)
19766 Details about a command line option, including its list of parameter
19767 details
19768 Members
19770 option: string
19771 option name
19772 parameters: array of CommandLineParameterInfo
19774 an array of CommandLineParameterInfo
19775 Since
19777 1.5
19778 query-command-line-options (Command)
19780 Query command line option schema.
19781 Arguments
19783 option: string (optional)
19784 option name
19785 Returns
19787 list of CommandLineOptionInfo for all options (or for the given op‐
19788 tion). Returns an error if the given option doesn't exist.
19789 Since
19791 1.5
19792 Example
19794 -> { "execute": "query-command-line-options",
19795 "arguments": { "option": "option-rom" } }
19796 <- { "return": [
19797 {
19798 "parameters": [
19799 {
19800 "name": "romfile",
19801 "type": "string"
19802 },
19803 {
19804 "name": "bootindex",
19805 "type": "number"
19806 }
19807 ],
19808 "option": "option-rom"
19809 }
19810 ]
19811 }
19812 RTC_CHANGE (Event)
19814 Emitted when the guest changes the RTC time.
19815 Arguments
19817 offset: int
19818 offset between base RTC clock (as specified by -rtc base), and
19819 new RTC clock value
19820 Note
19822 This event is rate-limited.
19823 Since
19825 0.13
19826 Example
19828 <- { "event": "RTC_CHANGE",
19829 "data": { "offset": 78 },
19830 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
19831 If
19833 TARGET_ALPHA or TARGET_ARM or TARGET_HPPA or TARGET_I386 or TARGET_MIPS
19834 or TARGET_MIPS64 or TARGET_PPC or TARGET_PPC64 or TARGET_S390X or TAR‐
19835 GET_SH4 or TARGET_SPARC
19836 rtc-reset-reinjection (Command)
19838 This command will reset the RTC interrupt reinjection backlog. Can be
19839 used if another mechanism to synchronize guest time is in effect, for
19840 example QEMU guest agent's guest-set-time command.
19841 Since
19843 2.1
19844 Example
19846 -> { "execute": "rtc-reset-reinjection" }
19847 <- { "return": {} }
19848 If
19850 TARGET_I386
19851 SevState (Enum)
19853 An enumeration of SEV state information used during query-sev.
19854 Values
19856 uninit The guest is uninitialized.
19857 launch-update
19859 The guest is currently being launched; plaintext data and regis‐
19860 ter state is being imported.
19861 launch-secret
19863 The guest is currently being launched; ciphertext data is being
19864 imported.
19865 running
19867 The guest is fully launched or migrated in.
19868 send-update
19870 The guest is currently being migrated out to another machine.
19871 receive-update
19873 The guest is currently being migrated from another machine.
19874 Since
19876 2.12
19877 If
19879 TARGET_I386
19880 SevInfo (Object)
19882 Information about Secure Encrypted Virtualization (SEV) support
19883 Members
19885 enabled: boolean
19886 true if SEV is active
19887 api-major: int
19889 SEV API major version
19890 api-minor: int
19892 SEV API minor version
19893 build-id: int
19895 SEV FW build id
19896 policy: int
19898 SEV policy value
19899 state: SevState
19901 SEV guest state
19902 handle: int
19904 SEV firmware handle
19905 Since
19907 2.12
19908 If
19910 TARGET_I386
19911 query-sev (Command)
19913 Returns information about SEV
19914 Returns
19916 SevInfo
19917 Since
19919 2.12
19920 Example
19922 -> { "execute": "query-sev" }
19923 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
19924 "build-id" : 0, "policy" : 0, "state" : "running",
19925 "handle" : 1 } }
19926 If
19928 TARGET_I386
19929 SevLaunchMeasureInfo (Object)
19931 SEV Guest Launch measurement information
19932 Members
19934 data: string
19935 the measurement value encoded in base64
19936 Since
19938 2.12
19939 If
19941 TARGET_I386
19942 query-sev-launch-measure (Command)
19944 Query the SEV guest launch information.
19945 Returns
19947 The SevLaunchMeasureInfo for the guest
19948 Since
19950 2.12
19951 Example
19953 -> { "execute": "query-sev-launch-measure" }
19954 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
19955 If
19957 TARGET_I386
19958 SevCapability (Object)
19960 The struct describes capability for a Secure Encrypted Virtualization
19961 feature.
19962 Members
19964 pdh: string
19965 Platform Diffie-Hellman key (base64 encoded)
19966 cert-chain: string
19968 PDH certificate chain (base64 encoded)
19969 cbitpos: int
19971 C-bit location in page table entry
19972 reduced-phys-bits: int
19974 Number of physical Address bit reduction when SEV is enabled
19975 Since
19977 2.12
19978 If
19980 TARGET_I386
19981 query-sev-capabilities (Command)
19983 This command is used to get the SEV capabilities, and is supported on
19984 AMD X86 platforms only.
19985 Returns
19987 SevCapability objects.
19988 Since
19990 2.12
19991 Example
19993 -> { "execute": "query-sev-capabilities" }
19994 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
19995 "cbitpos": 47, "reduced-phys-bits": 5}}
19996 If
19998 TARGET_I386
19999 sev-inject-launch-secret (Command)
20001 This command injects a secret blob into memory of SEV guest.
20002 Arguments
20004 packet-header: string
20005 the launch secret packet header encoded in base64
20006 secret: string
20008 the launch secret data to be injected encoded in base64
20009 gpa: int (optional)
20011 the guest physical address where secret will be injected.
20012 Since
20014 6.0
20015 If
20017 TARGET_I386
20018 SevAttestationReport (Object)
20020 The struct describes attestation report for a Secure Encrypted Virtual‐
20021 ization feature.
20022 Members
20024 data: string
20025 guest attestation report (base64 encoded)
20026 Since
20028 6.1
20029 If
20031 TARGET_I386
20032 query-sev-attestation-report (Command)
20034 This command is used to get the SEV attestation report, and is sup‐
20035 ported on AMD X86 platforms only.
20036 Arguments
20038 mnonce: string
20039 a random 16 bytes value encoded in base64 (it will be included
20040 in report)
20041 Returns
20043 SevAttestationReport objects.
20044 Since
20046 6.1
20047 Example
20049 -> { "execute" : "query-sev-attestation-report",
20050 "arguments": { "mnonce": "aaaaaaa" } }
20051 <- { "return" : { "data": "aaaaaaaabbbddddd"} }
20052 If
20054 TARGET_I386
20055 dump-skeys (Command)
20057 Dump guest's storage keys
20058 Arguments
20060 filename: string
20061 the path to the file to dump to
20062 This command is only supported on s390 architecture.
20063 Since
20065 2.5
20066 Example
20068 -> { "execute": "dump-skeys",
20069 "arguments": { "filename": "/tmp/skeys" } }
20070 <- { "return": {} }
20071 If
20073 TARGET_S390X
20074 GICCapability (Object)
20076 The struct describes capability for a specific GIC (Generic Interrupt
20077 Controller) version. These bits are not only decided by QEMU/KVM soft‐
20078 ware version, but also decided by the hardware that the program is run‐
20079 ning upon.
20080 Members
20082 version: int
20083 version of GIC to be described. Currently, only 2 and 3 are sup‐
20084 ported.
20085 emulated: boolean
20087 whether current QEMU/hardware supports emulated GIC device in
20088 user space.
20089 kernel: boolean
20091 whether current QEMU/hardware supports hardware accelerated GIC
20092 device in kernel.
20093 Since
20095 2.6
20096 If
20098 TARGET_ARM
20099 query-gic-capabilities (Command)
20101 This command is ARM-only. It will return a list of GICCapability ob‐
20102 jects that describe its capability bits.
20103 Returns
20105 a list of GICCapability objects.
20106 Since
20108 2.6
20109 Example
20111 -> { "execute": "query-gic-capabilities" }
20112 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
20113 { "version": 3, "emulated": false, "kernel": true } ] }
20114 If
20116 TARGET_ARM
20117 SGXInfo (Object)
20119 Information about intel Safe Guard eXtension (SGX) support
20120 Members
20122 sgx: boolean
20123 true if SGX is supported
20124 sgx1: boolean
20126 true if SGX1 is supported
20127 sgx2: boolean
20129 true if SGX2 is supported
20130 flc: boolean
20132 true if FLC is supported
20133 section-size: int
20135 The EPC section size for guest
20136 Since
20138 6.2
20139 If
20141 TARGET_I386
20142 query-sgx (Command)
20144 Returns information about SGX
20145 Returns
20147 SGXInfo
20148 Since
20150 6.2
20151 Example
20153 -> { "execute": "query-sgx" }
20154 <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
20155 "flc": true, "section-size" : 0 } }
20156 If
20158 TARGET_I386
20159 query-sgx-capabilities (Command)
20161 Returns information from host SGX capabilities
20162 Returns
20164 SGXInfo
20165 Since
20167 6.2
20168 Example
20170 -> { "execute": "query-sgx-capabilities" }
20171 <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
20172 "flc": true, "section-size" : 0 } }
20173 If
20175 TARGET_I386
20176
20178 AudiodevPerDirectionOptions (Object)
20179 General audio backend options that are used for both playback and
20180 recording.
20181 Members
20183 mixing-engine: boolean (optional)
20184 use QEMU's mixing engine to mix all streams inside QEMU and con‐
20185 vert audio formats when not supported by the backend. When set
20186 to off, fixed-settings must be also off (default on, since 4.2)
20187 fixed-settings: boolean (optional)
20189 use fixed settings for host input/output. When off, frequency,
20190 channels and format must not be specified (default true)
20191 frequency: int (optional)
20193 frequency to use when using fixed settings (default 44100)
20194 channels: int (optional)
20196 number of channels when using fixed settings (default 2)
20197 voices: int (optional)
20199 number of voices to use (default 1)
20200 format: AudioFormat (optional)
20202 sample format to use when using fixed settings (default s16)
20203 buffer-length: int (optional)
20205 the buffer length in microseconds
20206 Since
20208 4.0
20209 AudiodevGenericOptions (Object)
20211 Generic driver-specific options.
20212 Members
20214 in: AudiodevPerDirectionOptions (optional)
20215 options of the capture stream
20216 out: AudiodevPerDirectionOptions (optional)
20218 options of the playback stream
20219 Since
20221 4.0
20222 AudiodevAlsaPerDirectionOptions (Object)
20224 Options of the ALSA backend that are used for both playback and record‐
20225 ing.
20226 Members
20228 dev: string (optional)
20229 the name of the ALSA device to use (default 'default')
20230 period-length: int (optional)
20232 the period length in microseconds
20233 try-poll: boolean (optional)
20235 attempt to use poll mode, falling back to non-polling access on
20236 failure (default true)
20237 The members of AudiodevPerDirectionOptions
20239 Since
20241 4.0
20242 AudiodevAlsaOptions (Object)
20244 Options of the ALSA audio backend.
20245 Members
20247 in: AudiodevAlsaPerDirectionOptions (optional)
20248 options of the capture stream
20249 out: AudiodevAlsaPerDirectionOptions (optional)
20251 options of the playback stream
20252 threshold: int (optional)
20254 set the threshold (in microseconds) when playback starts
20255 Since
20257 4.0
20258 AudiodevCoreaudioPerDirectionOptions (Object)
20260 Options of the Core Audio backend that are used for both playback and
20261 recording.
20262 Members
20264 buffer-count: int (optional)
20265 number of buffers
20266 The members of AudiodevPerDirectionOptions
20268 Since
20270 4.0
20271 AudiodevCoreaudioOptions (Object)
20273 Options of the coreaudio audio backend.
20274 Members
20276 in: AudiodevCoreaudioPerDirectionOptions (optional)
20277 options of the capture stream
20278 out: AudiodevCoreaudioPerDirectionOptions (optional)
20280 options of the playback stream
20281 Since
20283 4.0
20284 AudiodevDsoundOptions (Object)
20286 Options of the DirectSound audio backend.
20287 Members
20289 in: AudiodevPerDirectionOptions (optional)
20290 options of the capture stream
20291 out: AudiodevPerDirectionOptions (optional)
20293 options of the playback stream
20294 latency: int (optional)
20296 add extra latency to playback in microseconds (default 10000)
20297 Since
20299 4.0
20300 AudiodevJackPerDirectionOptions (Object)
20302 Options of the JACK backend that are used for both playback and record‐
20303 ing.
20304 Members
20306 server-name: string (optional)
20307 select from among several possible concurrent server instances
20308 (default: environment variable $JACK_DEFAULT_SERVER if set, else
20309 "default")
20310 client-name: string (optional)
20312 the client name to use. The server will modify this name to cre‐
20313 ate a unique variant, if needed unless exact-name is true (de‐
20314 fault: the guest's name)
20315 connect-ports: string (optional)
20317 if set, a regular expression of JACK client port name(s) to mon‐
20318 itor for and automatically connect to
20319 start-server: boolean (optional)
20321 start a jack server process if one is not already present (de‐
20322 fault: false)
20323 exact-name: boolean (optional)
20325 use the exact name requested otherwise JACK automatically gener‐
20326 ates a unique one, if needed (default: false)
20327 The members of AudiodevPerDirectionOptions
20329 Since
20331 5.1
20332 AudiodevJackOptions (Object)
20334 Options of the JACK audio backend.
20335 Members
20337 in: AudiodevJackPerDirectionOptions (optional)
20338 options of the capture stream
20339 out: AudiodevJackPerDirectionOptions (optional)
20341 options of the playback stream
20342 Since
20344 5.1
20345 AudiodevOssPerDirectionOptions (Object)
20347 Options of the OSS backend that are used for both playback and record‐
20348 ing.
20349 Members
20351 dev: string (optional)
20352 file name of the OSS device (default '/dev/dsp')
20353 buffer-count: int (optional)
20355 number of buffers
20356 try-poll: boolean (optional)
20358 attempt to use poll mode, falling back to non-polling access on
20359 failure (default true)
20360 The members of AudiodevPerDirectionOptions
20362 Since
20364 4.0
20365 AudiodevOssOptions (Object)
20367 Options of the OSS audio backend.
20368 Members
20370 in: AudiodevOssPerDirectionOptions (optional)
20371 options of the capture stream
20372 out: AudiodevOssPerDirectionOptions (optional)
20374 options of the playback stream
20375 try-mmap: boolean (optional)
20377 try using memory-mapped access, falling back to non-mem‐
20378 ory-mapped access on failure (default true)
20379 exclusive: boolean (optional)
20381 open device in exclusive mode (vmix won't work) (default false)
20382 dsp-policy: int (optional)
20384 set the timing policy of the device (between 0 and 10, where
20385 smaller number means smaller latency but higher CPU usage) or -1
20386 to use fragment mode (option ignored on some platforms) (default
20387 5)
20388 Since
20390 4.0
20391 AudiodevPaPerDirectionOptions (Object)
20393 Options of the Pulseaudio backend that are used for both playback and
20394 recording.
20395 Members
20397 name: string (optional)
20398 name of the sink/source to use
20399 stream-name: string (optional)
20401 name of the PulseAudio stream created by qemu. Can be used to
20402 identify the stream in PulseAudio when you create multiple
20403 PulseAudio devices or run multiple qemu instances (default: au‐
20404 diodev's id, since 4.2)
20405 latency: int (optional)
20407 latency you want PulseAudio to achieve in microseconds (default
20408 15000)
20409 The members of AudiodevPerDirectionOptions
20411 Since
20413 4.0
20414 AudiodevPaOptions (Object)
20416 Options of the PulseAudio audio backend.
20417 Members
20419 in: AudiodevPaPerDirectionOptions (optional)
20420 options of the capture stream
20421 out: AudiodevPaPerDirectionOptions (optional)
20423 options of the playback stream
20424 server: string (optional)
20426 PulseAudio server address (default: let PulseAudio choose)
20427 Since
20429 4.0
20430 AudiodevSdlPerDirectionOptions (Object)
20432 Options of the SDL audio backend that are used for both playback and
20433 recording.
20434 Members
20436 buffer-count: int (optional)
20437 number of buffers (default 4)
20438 The members of AudiodevPerDirectionOptions
20440 Since
20442 6.0
20443 AudiodevSdlOptions (Object)
20445 Options of the SDL audio backend.
20446 Members
20448 in: AudiodevSdlPerDirectionOptions (optional)
20449 options of the recording stream
20450 out: AudiodevSdlPerDirectionOptions (optional)
20452 options of the playback stream
20453 Since
20455 6.0
20456 AudiodevWavOptions (Object)
20458 Options of the wav audio backend.
20459 Members
20461 in: AudiodevPerDirectionOptions (optional)
20462 options of the capture stream
20463 out: AudiodevPerDirectionOptions (optional)
20465 options of the playback stream
20466 path: string (optional)
20468 name of the wav file to record (default 'qemu.wav')
20469 Since
20471 4.0
20472 AudioFormat (Enum)
20474 An enumeration of possible audio formats.
20475 Values
20477 u8 unsigned 8 bit integer
20478 s8 signed 8 bit integer
20480 u16 unsigned 16 bit integer
20482 s16 signed 16 bit integer
20484 u32 unsigned 32 bit integer
20486 s32 signed 32 bit integer
20488 f32 single precision floating-point (since 5.0)
20490 Since
20492 4.0
20493 AudiodevDriver (Enum)
20495 An enumeration of possible audio backend drivers.
20496 Values
20498 jack JACK audio backend (since 5.1)
20499 none Not documented
20501 alsa Not documented
20503 coreaudio
20505 Not documented
20506 dsound Not documented
20508 oss Not documented
20510 pa Not documented
20512 sdl Not documented
20514 spice Not documented
20516 wav Not documented
20518 Since
20520 4.0
20521 Audiodev (Object)
20523 Options of an audio backend.
20524 Members
20526 id: string
20527 identifier of the backend
20528 driver: AudiodevDriver
20530 the backend driver to use
20531 timer-period: int (optional)
20533 timer period (in microseconds, 0: use lowest possible)
20534 The members of AudiodevGenericOptions when driver is "none"
20536 The members of AudiodevAlsaOptions when driver is "alsa"
20538 The members of AudiodevCoreaudioOptions when driver is "coreaudio"
20540 The members of AudiodevDsoundOptions when driver is "dsound"
20542 The members of AudiodevJackOptions when driver is "jack"
20544 The members of AudiodevOssOptions when driver is "oss"
20546 The members of AudiodevPaOptions when driver is "pa"
20548 The members of AudiodevSdlOptions when driver is "sdl"
20550 The members of AudiodevGenericOptions when driver is "spice"
20552 The members of AudiodevWavOptions when driver is "wav"
20554 Since
20556 4.0
20557
20559 AcpiTableOptions (Object)
20560 Specify an ACPI table on the command line to load.
20561 At most one of file and data can be specified. The list of files speci‐
20563 fied by any one of them is loaded and concatenated in order. If both
20564 are omitted, data is implied.
20565 Other fields / optargs can be used to override fields of the generic
20567 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
20568 System Description Table Header. If a header field is not overridden,
20569 then the corresponding value from the concatenated blob is used (in
20570 case of file), or it is filled in with a hard-coded value (in case of
20571 data).
20572 String fields are copied into the matching ACPI member from lowest ad‐
20574 dress upwards, and silently truncated / NUL-padded to length.
20575 Members
20577 sig: string (optional)
20578 table signature / identifier (4 bytes)
20579 rev: int (optional)
20581 table revision number (dependent on signature, 1 byte)
20582 oem_id: string (optional)
20584 OEM identifier (6 bytes)
20585 oem_table_id: string (optional)
20587 OEM table identifier (8 bytes)
20588 oem_rev: int (optional)
20590 OEM-supplied revision number (4 bytes)
20591 asl_compiler_id: string (optional)
20593 identifier of the utility that created the table (4 bytes)
20594 asl_compiler_rev: int (optional)
20596 revision number of the utility that created the table (4 bytes)
20597 file: string (optional)
20599 colon (:) separated list of pathnames to load and concatenate as
20600 table data. The resultant binary blob is expected to have an
20601 ACPI table header. At least one file is required. This field ex‐
20602 cludes data.
20603 data: string (optional)
20605 colon (:) separated list of pathnames to load and concatenate as
20606 table data. The resultant binary blob must not have an ACPI ta‐
20607 ble header. At least one file is required. This field excludes
20608 file.
20609 Since
20611 1.5
20612 ACPISlotType (Enum)
20614 Values
20615 DIMM memory slot
20616 CPU logical CPU slot (since 2.7)
20618 ACPIOSTInfo (Object)
20620 OSPM Status Indication for a device For description of possible values
20621 of source and status fields see "_OST (OSPM Status Indication)" chapter
20622 of ACPI5.0 spec.
20623 Members
20625 device: string (optional)
20626 device ID associated with slot
20627 slot: string
20629 slot ID, unique per slot of a given slot-type
20630 slot-type: ACPISlotType
20632 type of the slot
20633 source: int
20635 an integer containing the source event
20636 status: int
20638 an integer containing the status code
20639 Since
20641 2.1
20642 query-acpi-ospm-status (Command)
20644 Return a list of ACPIOSTInfo for devices that support status reporting
20645 via ACPI _OST method.
20646 Since
20648 2.1
20649 Example
20651 -> { "execute": "query-acpi-ospm-status" }
20652 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
20653 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
20654 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
20655 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
20656 ]}
20657 ACPI_DEVICE_OST (Event)
20659 Emitted when guest executes ACPI _OST method.
20660 Arguments
20662 info: ACPIOSTInfo
20663 OSPM Status Indication
20664 Since
20666 2.1
20667 Example
20669 <- { "event": "ACPI_DEVICE_OST",
20670 "data": { "device": "d1", "slot": "0",
20671 "slot-type": "DIMM", "source": 1, "status": 0 } }
20672
20674 PciMemoryRange (Object)
20675 A PCI device memory region
20676 Members
20678 base: int
20679 the starting address (guest physical)
20680 limit: int
20682 the ending address (guest physical)
20683 Since
20685 0.14
20686 PciMemoryRegion (Object)
20688 Information about a PCI device I/O region.
20689 Members
20691 bar: int
20692 the index of the Base Address Register for this region
20693 type: string
20695 • 'io' if the region is a PIO region
20697 • 'memory' if the region is a MMIO region
20699 size: int
20701 memory size
20702 prefetch: boolean (optional)
20704 if type is 'memory', true if the memory is prefetchable
20705 mem_type_64: boolean (optional)
20707 if type is 'memory', true if the BAR is 64-bit
20708 address: int
20710 Not documented
20711 Since
20713 0.14
20714 PciBusInfo (Object)
20716 Information about a bus of a PCI Bridge device
20717 Members
20719 number: int
20720 primary bus interface number. This should be the number of the
20721 bus the device resides on.
20722 secondary: int
20724 secondary bus interface number. This is the number of the main
20725 bus for the bridge
20726 subordinate: int
20728 This is the highest number bus that resides below the bridge.
20729 io_range: PciMemoryRange
20731 The PIO range for all devices on this bridge
20732 memory_range: PciMemoryRange
20734 The MMIO range for all devices on this bridge
20735 prefetchable_range: PciMemoryRange
20737 The range of prefetchable MMIO for all devices on this bridge
20738 Since
20740 2.4
20741 PciBridgeInfo (Object)
20743 Information about a PCI Bridge device
20744 Members
20746 bus: PciBusInfo
20747 information about the bus the device resides on
20748 devices: array of PciDeviceInfo (optional)
20750 a list of PciDeviceInfo for each device on this bridge
20751 Since
20753 0.14
20754 PciDeviceClass (Object)
20756 Information about the Class of a PCI device
20757 Members
20759 desc: string (optional)
20760 a string description of the device's class
20761 class: int
20763 the class code of the device
20764 Since
20766 2.4
20767 PciDeviceId (Object)
20769 Information about the Id of a PCI device
20770 Members
20772 device: int
20773 the PCI device id
20774 vendor: int
20776 the PCI vendor id
20777 subsystem: int (optional)
20779 the PCI subsystem id (since 3.1)
20780 subsystem-vendor: int (optional)
20782 the PCI subsystem vendor id (since 3.1)
20783 Since
20785 2.4
20786 PciDeviceInfo (Object)
20788 Information about a PCI device
20789 Members
20791 bus: int
20792 the bus number of the device
20793 slot: int
20795 the slot the device is located in
20796 function: int
20798 the function of the slot used by the device
20799 class_info: PciDeviceClass
20801 the class of the device
20802 id: PciDeviceId
20804 the PCI device id
20805 irq: int (optional)
20807 if an IRQ is assigned to the device, the IRQ number
20808 irq_pin: int
20810 the IRQ pin, zero means no IRQ (since 5.1)
20811 qdev_id: string
20813 the device name of the PCI device
20814 pci_bridge: PciBridgeInfo (optional)
20816 if the device is a PCI bridge, the bridge information
20817 regions: array of PciMemoryRegion
20819 a list of the PCI I/O regions associated with the device
20820 Notes
20822 the contents of class_info.desc are not stable and should only be
20823 treated as informational.
20824 Since
20826 0.14
20827 PciInfo (Object)
20829 Information about a PCI bus
20830 Members
20832 bus: int
20833 the bus index
20834 devices: array of PciDeviceInfo
20836 a list of devices on this bus
20837 Since
20839 0.14
20840 query-pci (Command)
20842 Return information about the PCI bus topology of the guest.
20843 Returns
20845 a list of PciInfo for each PCI bus. Each bus is represented by a
20846 json-object, which has a key with a json-array of all PCI devices at‐
20847 tached to it. Each device is represented by a json-object.
20848 Since
20850 0.14
20851 Example
20853 -> { "execute": "query-pci" }
20854 <- { "return": [
20855 {
20856 "bus": 0,
20857 "devices": [
20858 {
20859 "bus": 0,
20860 "qdev_id": "",
20861 "slot": 0,
20862 "class_info": {
20863 "class": 1536,
20864 "desc": "Host bridge"
20865 },
20866 "id": {
20867 "device": 32902,
20868 "vendor": 4663
20869 },
20870 "function": 0,
20871 "regions": [
20872 ]
20873 },
20874 {
20875 "bus": 0,
20876 "qdev_id": "",
20877 "slot": 1,
20878 "class_info": {
20879 "class": 1537,
20880 "desc": "ISA bridge"
20881 },
20882 "id": {
20883 "device": 32902,
20884 "vendor": 28672
20885 },
20886 "function": 0,
20887 "regions": [
20888 ]
20889 },
20890 {
20891 "bus": 0,
20892 "qdev_id": "",
20893 "slot": 1,
20894 "class_info": {
20895 "class": 257,
20896 "desc": "IDE controller"
20897 },
20898 "id": {
20899 "device": 32902,
20900 "vendor": 28688
20901 },
20902 "function": 1,
20903 "regions": [
20904 {
20905 "bar": 4,
20906 "size": 16,
20907 "address": 49152,
20908 "type": "io"
20909 }
20910 ]
20911 },
20912 {
20913 "bus": 0,
20914 "qdev_id": "",
20915 "slot": 2,
20916 "class_info": {
20917 "class": 768,
20918 "desc": "VGA controller"
20919 },
20920 "id": {
20921 "device": 4115,
20922 "vendor": 184
20923 },
20924 "function": 0,
20925 "regions": [
20926 {
20927 "prefetch": true,
20928 "mem_type_64": false,
20929 "bar": 0,
20930 "size": 33554432,
20931 "address": 4026531840,
20932 "type": "memory"
20933 },
20934 {
20935 "prefetch": false,
20936 "mem_type_64": false,
20937 "bar": 1,
20938 "size": 4096,
20939 "address": 4060086272,
20940 "type": "memory"
20941 },
20942 {
20943 "prefetch": false,
20944 "mem_type_64": false,
20945 "bar": 6,
20946 "size": 65536,
20947 "address": -1,
20948 "type": "memory"
20949 }
20950 ]
20951 },
20952 {
20953 "bus": 0,
20954 "qdev_id": "",
20955 "irq": 11,
20956 "slot": 4,
20957 "class_info": {
20958 "class": 1280,
20959 "desc": "RAM controller"
20960 },
20961 "id": {
20962 "device": 6900,
20963 "vendor": 4098
20964 },
20965 "function": 0,
20966 "regions": [
20967 {
20968 "bar": 0,
20969 "size": 32,
20970 "address": 49280,
20971 "type": "io"
20972 }
20973 ]
20974 }
20975 ]
20976 }
20977 ]
20978 }
20979 Note
20981 This example has been shortened as the real response is too long.
20982
20984 2022, The QEMU Project Developers
209856.2.0 Jun 11, 2022 QEMU-QMP-REF(7)