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 • NotifyVmexitOption (Enum)
143 • Cryptography
145 • QCryptoTLSCredsEndpoint (Enum)
147 • QCryptoSecretFormat (Enum)
149 • QCryptoHashAlgorithm (Enum)
151 • QCryptoCipherAlgorithm (Enum)
153 • QCryptoCipherMode (Enum)
155 • QCryptoIVGenAlgorithm (Enum)
157 • QCryptoBlockFormat (Enum)
159 • QCryptoBlockOptionsBase (Object)
161 • QCryptoBlockOptionsQCow (Object)
163 • QCryptoBlockOptionsLUKS (Object)
165 • QCryptoBlockCreateOptionsLUKS (Object)
167 • QCryptoBlockOpenOptions (Object)
169 • QCryptoBlockCreateOptions (Object)
171 • QCryptoBlockInfoBase (Object)
173 • QCryptoBlockInfoLUKSSlot (Object)
175 • QCryptoBlockInfoLUKS (Object)
177 • QCryptoBlockInfo (Object)
179 • QCryptoBlockLUKSKeyslotState (Enum)
181 • QCryptoBlockAmendOptionsLUKS (Object)
183 • QCryptoBlockAmendOptions (Object)
185 • SecretCommonProperties (Object)
187 • SecretProperties (Object)
189 • SecretKeyringProperties (Object)
191 • TlsCredsProperties (Object)
193 • TlsCredsAnonProperties (Object)
195 • TlsCredsPskProperties (Object)
197 • TlsCredsX509Properties (Object)
199 • QCryptoAkCipherAlgorithm (Enum)
201 • QCryptoAkCipherKeyType (Enum)
203 • QCryptoRSAPaddingAlgorithm (Enum)
205 • QCryptoAkCipherOptionsRSA (Object)
207 • QCryptoAkCipherOptions (Object)
209 • Block devices
211 • Block core (VM unrelated)
213 • Background jobs
215 • Additional block stuff (VM related)
217 • Block device exports
219 • Character devices
221 • ChardevInfo (Object)
223 • query-chardev (Command)
225 • ChardevBackendInfo (Object)
227 • query-chardev-backends (Command)
229 • DataFormat (Enum)
231 • ringbuf-write (Command)
233 • ringbuf-read (Command)
235 • ChardevCommon (Object)
237 • ChardevFile (Object)
239 • ChardevHostdev (Object)
241 • ChardevSocket (Object)
243 • ChardevUdp (Object)
245 • ChardevMux (Object)
247 • ChardevStdio (Object)
249 • ChardevSpiceChannel (Object)
251 • ChardevSpicePort (Object)
253 • ChardevDBus (Object)
255 • ChardevVC (Object)
257 • ChardevRingbuf (Object)
259 • ChardevQemuVDAgent (Object)
261 • ChardevBackendKind (Enum)
263 • ChardevFileWrapper (Object)
265 • ChardevHostdevWrapper (Object)
267 • ChardevSocketWrapper (Object)
269 • ChardevUdpWrapper (Object)
271 • ChardevCommonWrapper (Object)
273 • ChardevMuxWrapper (Object)
275 • ChardevStdioWrapper (Object)
277 • ChardevSpiceChannelWrapper (Object)
279 • ChardevSpicePortWrapper (Object)
281 • ChardevQemuVDAgentWrapper (Object)
283 • ChardevDBusWrapper (Object)
285 • ChardevVCWrapper (Object)
287 • ChardevRingbufWrapper (Object)
289 • ChardevBackend (Object)
291 • ChardevReturn (Object)
293 • chardev-add (Command)
295 • chardev-change (Command)
297 • chardev-remove (Command)
299 • chardev-send-break (Command)
301 • VSERPORT_CHANGE (Event)
303 • Dump guest memory
305 • DumpGuestMemoryFormat (Enum)
307 • dump-guest-memory (Command)
309 • DumpStatus (Enum)
311 • DumpQueryResult (Object)
313 • query-dump (Command)
315 • DUMP_COMPLETED (Event)
317 • DumpGuestMemoryCapability (Object)
319 • query-dump-guest-memory-capability (Command)
321 • Net devices
323 • set_link (Command)
325 • netdev_add (Command)
327 • netdev_del (Command)
329 • NetLegacyNicOptions (Object)
331 • NetdevUserOptions (Object)
333 • NetdevTapOptions (Object)
335 • NetdevSocketOptions (Object)
337 • NetdevL2TPv3Options (Object)
339 • NetdevVdeOptions (Object)
341 • NetdevBridgeOptions (Object)
343 • NetdevHubPortOptions (Object)
345 • NetdevNetmapOptions (Object)
347 • NetdevVhostUserOptions (Object)
349 • NetdevVhostVDPAOptions (Object)
351 • NetdevVmnetHostOptions (Object)
353 • NetdevVmnetSharedOptions (Object)
355 • NetdevVmnetBridgedOptions (Object)
357 • NetdevStreamOptions (Object)
359 • NetdevDgramOptions (Object)
361 • NetClientDriver (Enum)
363 • Netdev (Object)
365 • RxState (Enum)
367 • RxFilterInfo (Object)
369 • query-rx-filter (Command)
371 • NIC_RX_FILTER_CHANGED (Event)
373 • AnnounceParameters (Object)
375 • announce-self (Command)
377 • FAILOVER_NEGOTIATED (Event)
379 • NETDEV_STREAM_CONNECTED (Event)
381 • NETDEV_STREAM_DISCONNECTED (Event)
383 • RDMA device
385 • RDMA_GID_STATUS_CHANGED (Event)
387 • Rocker switch device
389 • RockerSwitch (Object)
391 • query-rocker (Command)
393 • RockerPortDuplex (Enum)
395 • RockerPortAutoneg (Enum)
397 • RockerPort (Object)
399 • query-rocker-ports (Command)
401 • RockerOfDpaFlowKey (Object)
403 • RockerOfDpaFlowMask (Object)
405 • RockerOfDpaFlowAction (Object)
407 • RockerOfDpaFlow (Object)
409 • query-rocker-of-dpa-flows (Command)
411 • RockerOfDpaGroup (Object)
413 • query-rocker-of-dpa-groups (Command)
415 • TPM (trusted platform module) devices
417 • TpmModel (Enum)
419 • query-tpm-models (Command)
421 • TpmType (Enum)
423 • query-tpm-types (Command)
425 • TPMPassthroughOptions (Object)
427 • TPMEmulatorOptions (Object)
429 • TPMPassthroughOptionsWrapper (Object)
431 • TPMEmulatorOptionsWrapper (Object)
433 • TpmTypeOptions (Object)
435 • TPMInfo (Object)
437 • query-tpm (Command)
439 • Remote desktop
441 • DisplayProtocol (Enum)
443 • SetPasswordAction (Enum)
445 • SetPasswordOptions (Object)
447 • SetPasswordOptionsVnc (Object)
449 • set_password (Command)
451 • ExpirePasswordOptions (Object)
453 • ExpirePasswordOptionsVnc (Object)
455 • expire_password (Command)
457 • ImageFormat (Enum)
459 • screendump (Command)
461 • Spice
463 • VNC
465 • Input
467 • MouseInfo (Object)
469 • query-mice (Command)
471 • QKeyCode (Enum)
473 • KeyValueKind (Enum)
475 • IntWrapper (Object)
477 • QKeyCodeWrapper (Object)
479 • KeyValue (Object)
481 • send-key (Command)
483 • InputButton (Enum)
485 • InputAxis (Enum)
487 • InputKeyEvent (Object)
489 • InputBtnEvent (Object)
491 • InputMoveEvent (Object)
493 • InputEventKind (Enum)
495 • InputKeyEventWrapper (Object)
497 • InputBtnEventWrapper (Object)
499 • InputMoveEventWrapper (Object)
501 • InputEvent (Object)
503 • input-send-event (Command)
505 • DisplayGTK (Object)
507 • DisplayEGLHeadless (Object)
509 • DisplayDBus (Object)
511 • DisplayGLMode (Enum)
513 • DisplayCurses (Object)
515 • DisplayCocoa (Object)
517 • HotKeyMod (Enum)
519 • DisplaySDL (Object)
521 • DisplayType (Enum)
523 • DisplayOptions (Object)
525 • query-display-options (Command)
527 • DisplayReloadType (Enum)
529 • DisplayReloadOptionsVNC (Object)
531 • DisplayReloadOptions (Object)
533 • display-reload (Command)
535 • DisplayUpdateType (Enum)
537 • DisplayUpdateOptionsVNC (Object)
539 • DisplayUpdateOptions (Object)
541 • display-update (Command)
543 • User authorization
545 • QAuthZListPolicy (Enum)
547 • QAuthZListFormat (Enum)
549 • QAuthZListRule (Object)
551 • AuthZListProperties (Object)
553 • AuthZListFileProperties (Object)
555 • AuthZPAMProperties (Object)
557 • AuthZSimpleProperties (Object)
559 • Migration
561 • MigrationStats (Object)
563 • XBZRLECacheStats (Object)
565 • CompressionStats (Object)
567 • MigrationStatus (Enum)
569 • VfioStats (Object)
571 • MigrationInfo (Object)
573 • query-migrate (Command)
575 • MigrationCapability (Enum)
577 • MigrationCapabilityStatus (Object)
579 • migrate-set-capabilities (Command)
581 • query-migrate-capabilities (Command)
583 • MultiFDCompression (Enum)
585 • BitmapMigrationBitmapAliasTransform (Object)
587 • BitmapMigrationBitmapAlias (Object)
589 • BitmapMigrationNodeAlias (Object)
591 • MigrationParameter (Enum)
593 • MigrateSetParameters (Object)
595 • migrate-set-parameters (Command)
597 • MigrationParameters (Object)
599 • query-migrate-parameters (Command)
601 • client_migrate_info (Command)
603 • migrate-start-postcopy (Command)
605 • MIGRATION (Event)
607 • MIGRATION_PASS (Event)
609 • COLOMessage (Enum)
611 • COLOMode (Enum)
613 • FailoverStatus (Enum)
615 • COLO_EXIT (Event)
617 • COLOExitReason (Enum)
619 • x-colo-lost-heartbeat (Command)
621 • migrate_cancel (Command)
623 • migrate-continue (Command)
625 • migrate (Command)
627 • migrate-incoming (Command)
629 • xen-save-devices-state (Command)
631 • xen-set-global-dirty-log (Command)
633 • xen-load-devices-state (Command)
635 • xen-set-replication (Command)
637 • ReplicationStatus (Object)
639 • query-xen-replication-status (Command)
641 • xen-colo-do-checkpoint (Command)
643 • COLOStatus (Object)
645 • query-colo-status (Command)
647 • migrate-recover (Command)
649 • migrate-pause (Command)
651 • UNPLUG_PRIMARY (Event)
653 • DirtyRateVcpu (Object)
655 • DirtyRateStatus (Enum)
657 • DirtyRateMeasureMode (Enum)
659 • DirtyRateInfo (Object)
661 • calc-dirty-rate (Command)
663 • query-dirty-rate (Command)
665 • DirtyLimitInfo (Object)
667 • set-vcpu-dirty-limit (Command)
669 • cancel-vcpu-dirty-limit (Command)
671 • query-vcpu-dirty-limit (Command)
673 • snapshot-save (Command)
675 • snapshot-load (Command)
677 • snapshot-delete (Command)
679 • Transactions
681 • Abort (Object)
683 • ActionCompletionMode (Enum)
685 • TransactionActionKind (Enum)
687 • AbortWrapper (Object)
689 • BlockDirtyBitmapAddWrapper (Object)
691 • BlockDirtyBitmapWrapper (Object)
693 • BlockDirtyBitmapMergeWrapper (Object)
695 • BlockdevBackupWrapper (Object)
697 • BlockdevSnapshotWrapper (Object)
699 • BlockdevSnapshotInternalWrapper (Object)
701 • BlockdevSnapshotSyncWrapper (Object)
703 • DriveBackupWrapper (Object)
705 • TransactionAction (Object)
707 • TransactionProperties (Object)
709 • transaction (Command)
711 • Tracing
713 • TraceEventState (Enum)
715 • TraceEventInfo (Object)
717 • trace-event-get-state (Command)
719 • trace-event-set-state (Command)
721 • Compatibility policy
723 • CompatPolicyInput (Enum)
725 • CompatPolicyOutput (Enum)
727 • CompatPolicy (Object)
729 • QMP monitor control
731 • qmp_capabilities (Command)
733 • QMPCapability (Enum)
735 • VersionTriple (Object)
737 • VersionInfo (Object)
739 • query-version (Command)
741 • CommandInfo (Object)
743 • query-commands (Command)
745 • quit (Command)
747 • MonitorMode (Enum)
749 • MonitorOptions (Object)
751 • QMP introspection
753 • query-qmp-schema (Command)
755 • SchemaMetaType (Enum)
757 • SchemaInfo (Object)
759 • SchemaInfoBuiltin (Object)
761 • JSONType (Enum)
763 • SchemaInfoEnum (Object)
765 • SchemaInfoEnumMember (Object)
767 • SchemaInfoArray (Object)
769 • SchemaInfoObject (Object)
771 • SchemaInfoObjectMember (Object)
773 • SchemaInfoObjectVariant (Object)
775 • SchemaInfoAlternate (Object)
777 • SchemaInfoAlternateMember (Object)
779 • SchemaInfoCommand (Object)
781 • SchemaInfoEvent (Object)
783 • QEMU Object Model (QOM)
785 • ObjectPropertyInfo (Object)
787 • qom-list (Command)
789 • qom-get (Command)
791 • qom-set (Command)
793 • ObjectTypeInfo (Object)
795 • qom-list-types (Command)
797 • qom-list-properties (Command)
799 • CanHostSocketcanProperties (Object)
801 • ColoCompareProperties (Object)
803 • CryptodevBackendProperties (Object)
805 • CryptodevVhostUserProperties (Object)
807 • DBusVMStateProperties (Object)
809 • NetfilterInsert (Enum)
811 • NetfilterProperties (Object)
813 • FilterBufferProperties (Object)
815 • FilterDumpProperties (Object)
817 • FilterMirrorProperties (Object)
819 • FilterRedirectorProperties (Object)
821 • FilterRewriterProperties (Object)
823 • InputBarrierProperties (Object)
825 • InputLinuxProperties (Object)
827 • EventLoopBaseProperties (Object)
829 • IothreadProperties (Object)
831 • MainLoopProperties (Object)
833 • MemoryBackendProperties (Object)
835 • MemoryBackendFileProperties (Object)
837 • MemoryBackendMemfdProperties (Object)
839 • MemoryBackendEpcProperties (Object)
841 • PrManagerHelperProperties (Object)
843 • QtestProperties (Object)
845 • RemoteObjectProperties (Object)
847 • VfioUserServerProperties (Object)
849 • RngProperties (Object)
851 • RngEgdProperties (Object)
853 • RngRandomProperties (Object)
855 • SevGuestProperties (Object)
857 • ThreadContextProperties (Object)
859 • ObjectType (Enum)
861 • ObjectOptions (Object)
863 • object-add (Command)
865 • object-del (Command)
867 • Device infrastructure (qdev)
869 • device-list-properties (Command)
871 • device_add (Command)
873 • device_del (Command)
875 • DEVICE_DELETED (Event)
877 • DEVICE_UNPLUG_GUEST_ERROR (Event)
879 • Machines
881 • SysEmuTarget (Enum)
883 • CpuS390State (Enum)
885 • CpuInfoS390 (Object)
887 • CpuInfoFast (Object)
889 • query-cpus-fast (Command)
891 • MachineInfo (Object)
893 • query-machines (Command)
895 • CurrentMachineParams (Object)
897 • query-current-machine (Command)
899 • TargetInfo (Object)
901 • query-target (Command)
903 • UuidInfo (Object)
905 • query-uuid (Command)
907 • GuidInfo (Object)
909 • query-vm-generation-id (Command)
911 • system_reset (Command)
913 • system_powerdown (Command)
915 • system_wakeup (Command)
917 • LostTickPolicy (Enum)
919 • inject-nmi (Command)
921 • KvmInfo (Object)
923 • query-kvm (Command)
925 • NumaOptionsType (Enum)
927 • NumaOptions (Object)
929 • NumaNodeOptions (Object)
931 • NumaDistOptions (Object)
933 • CXLFixedMemoryWindowOptions (Object)
935 • CXLFMWProperties (Object)
937 • X86CPURegister32 (Enum)
939 • X86CPUFeatureWordInfo (Object)
941 • DummyForceArrays (Object)
943 • NumaCpuOptions (Object)
945 • HmatLBMemoryHierarchy (Enum)
947 • HmatLBDataType (Enum)
949 • NumaHmatLBOptions (Object)
951 • HmatCacheAssociativity (Enum)
953 • HmatCacheWritePolicy (Enum)
955 • NumaHmatCacheOptions (Object)
957 • memsave (Command)
959 • pmemsave (Command)
961 • Memdev (Object)
963 • query-memdev (Command)
965 • CpuInstanceProperties (Object)
967 • HotpluggableCPU (Object)
969 • query-hotpluggable-cpus (Command)
971 • set-numa-node (Command)
973 • balloon (Command)
975 • BalloonInfo (Object)
977 • query-balloon (Command)
979 • BALLOON_CHANGE (Event)
981 • MemoryInfo (Object)
983 • query-memory-size-summary (Command)
985 • PCDIMMDeviceInfo (Object)
987 • VirtioPMEMDeviceInfo (Object)
989 • VirtioMEMDeviceInfo (Object)
991 • SgxEPCDeviceInfo (Object)
993 • MemoryDeviceInfoKind (Enum)
995 • PCDIMMDeviceInfoWrapper (Object)
997 • VirtioPMEMDeviceInfoWrapper (Object)
999 • VirtioMEMDeviceInfoWrapper (Object)
1001 • SgxEPCDeviceInfoWrapper (Object)
1003 • MemoryDeviceInfo (Object)
1005 • SgxEPC (Object)
1007 • SgxEPCProperties (Object)
1009 • query-memory-devices (Command)
1011 • MEMORY_DEVICE_SIZE_CHANGE (Event)
1013 • MEM_UNPLUG_ERROR (Event)
1015 • BootConfiguration (Object)
1017 • SMPConfiguration (Object)
1019 • x-query-irq (Command)
1021 • x-query-jit (Command)
1023 • x-query-numa (Command)
1025 • x-query-opcount (Command)
1027 • x-query-profile (Command)
1029 • x-query-ramblock (Command)
1031 • x-query-rdma (Command)
1033 • x-query-roms (Command)
1035 • x-query-usb (Command)
1037 • SmbiosEntryPointType (Enum)
1039 • MemorySizeConfiguration (Object)
1041 • dumpdtb (Command)
1043 • CpuModelInfo (Object)
1045 • CpuModelExpansionType (Enum)
1047 • CpuModelCompareResult (Enum)
1049 • CpuModelBaselineInfo (Object)
1051 • CpuModelCompareInfo (Object)
1053 • query-cpu-model-comparison (Command)
1055 • query-cpu-model-baseline (Command)
1057 • CpuModelExpansionInfo (Object)
1059 • query-cpu-model-expansion (Command)
1061 • CpuDefinitionInfo (Object)
1063 • query-cpu-definitions (Command)
1065 • Record/replay
1067 • ReplayMode (Enum)
1069 • ReplayInfo (Object)
1071 • query-replay (Command)
1073 • replay-break (Command)
1075 • replay-delete-break (Command)
1077 • replay-seek (Command)
1079 • Yank feature
1081 • YankInstanceType (Enum)
1083 • YankInstanceBlockNode (Object)
1085 • YankInstanceChardev (Object)
1087 • YankInstance (Object)
1089 • yank (Command)
1091 • query-yank (Command)
1093 • Miscellanea
1095 • add_client (Command)
1097 • NameInfo (Object)
1099 • query-name (Command)
1101 • IOThreadInfo (Object)
1103 • query-iothreads (Command)
1105 • stop (Command)
1107 • cont (Command)
1109 • x-exit-preconfig (Command)
1111 • human-monitor-command (Command)
1113 • getfd (Command)
1115 • closefd (Command)
1117 • AddfdInfo (Object)
1119 • add-fd (Command)
1121 • remove-fd (Command)
1123 • FdsetFdInfo (Object)
1125 • FdsetInfo (Object)
1127 • query-fdsets (Command)
1129 • CommandLineParameterType (Enum)
1131 • CommandLineParameterInfo (Object)
1133 • CommandLineOptionInfo (Object)
1135 • query-command-line-options (Command)
1137 • RTC_CHANGE (Event)
1139 • VFU_CLIENT_HANGUP (Event)
1141 • rtc-reset-reinjection (Command)
1143 • SevState (Enum)
1145 • SevInfo (Object)
1147 • query-sev (Command)
1149 • SevLaunchMeasureInfo (Object)
1151 • query-sev-launch-measure (Command)
1153 • SevCapability (Object)
1155 • query-sev-capabilities (Command)
1157 • sev-inject-launch-secret (Command)
1159 • SevAttestationReport (Object)
1161 • query-sev-attestation-report (Command)
1163 • dump-skeys (Command)
1165 • GICCapability (Object)
1167 • query-gic-capabilities (Command)
1169 • SGXEPCSection (Object)
1171 • SGXInfo (Object)
1173 • query-sgx (Command)
1175 • query-sgx-capabilities (Command)
1177 • Audio
1179 • AudiodevPerDirectionOptions (Object)
1181 • AudiodevGenericOptions (Object)
1183 • AudiodevAlsaPerDirectionOptions (Object)
1185 • AudiodevAlsaOptions (Object)
1187 • AudiodevSndioOptions (Object)
1189 • AudiodevCoreaudioPerDirectionOptions (Object)
1191 • AudiodevCoreaudioOptions (Object)
1193 • AudiodevDsoundOptions (Object)
1195 • AudiodevJackPerDirectionOptions (Object)
1197 • AudiodevJackOptions (Object)
1199 • AudiodevOssPerDirectionOptions (Object)
1201 • AudiodevOssOptions (Object)
1203 • AudiodevPaPerDirectionOptions (Object)
1205 • AudiodevPaOptions (Object)
1207 • AudiodevSdlPerDirectionOptions (Object)
1209 • AudiodevSdlOptions (Object)
1211 • AudiodevWavOptions (Object)
1213 • AudioFormat (Enum)
1215 • AudiodevDriver (Enum)
1217 • Audiodev (Object)
1219 • ACPI
1221 • AcpiTableOptions (Object)
1223 • ACPISlotType (Enum)
1225 • ACPIOSTInfo (Object)
1227 • query-acpi-ospm-status (Command)
1229 • ACPI_DEVICE_OST (Event)
1231 • PCI
1233 • PciMemoryRange (Object)
1235 • PciMemoryRegion (Object)
1237 • PciBusInfo (Object)
1239 • PciBridgeInfo (Object)
1241 • PciDeviceClass (Object)
1243 • PciDeviceId (Object)
1245 • PciDeviceInfo (Object)
1247 • PciInfo (Object)
1249 • query-pci (Command)
1251 • Statistics
1253 • StatsType (Enum)
1255 • StatsUnit (Enum)
1257 • StatsProvider (Enum)
1259 • StatsTarget (Enum)
1261 • StatsRequest (Object)
1263 • StatsVCPUFilter (Object)
1265 • StatsFilter (Object)
1267 • StatsValue (Alternate)
1269 • Stats (Object)
1271 • StatsResult (Object)
1273 • query-stats (Command)
1275 • StatsSchemaValue (Object)
1277 • StatsSchema (Object)
1279 • query-stats-schemas (Command)
1281 • Virtio devices
1283 • VirtioInfo (Object)
1285 • x-query-virtio (Command)
1287 • VhostStatus (Object)
1289 • VirtioStatus (Object)
1291 • x-query-virtio-status (Command)
1293 • VirtioDeviceStatus (Object)
1295 • VhostDeviceProtocols (Object)
1297 • VirtioDeviceFeatures (Object)
1299 • VirtQueueStatus (Object)
1301 • x-query-virtio-queue-status (Command)
1303 • VirtVhostQueueStatus (Object)
1305 • x-query-virtio-vhost-queue-status (Command)
1307 • VirtioRingDesc (Object)
1309 • VirtioRingAvail (Object)
1311 • VirtioRingUsed (Object)
1313 • VirtioQueueElement (Object)
1315 • x-query-virtio-queue-element (Command)
1317
1319 This document describes all commands currently supported by QMP.
1320 Most of the time their usage is exactly the same as in the user Moni‐
1322 tor, this means that any other document which also describe commands
1323 (the manpage, QEMU's manual, etc) can and should be consulted.
1324 QMP has two types of commands: regular and query commands. Regular com‐
1326 mands usually change the Virtual Machine's state someway, while query
1327 commands just return information. The sections below are divided ac‐
1328 cordingly.
1329 It's important to observe that all communication examples are formatted
1331 in a reader-friendly way, so that they're easier to understand. How‐
1332 ever, in real protocol usage, they're emitted as a single line.
1333 Also, the following notation is used to denote data flow:
1335 Example:
1337 -> data issued by the Client
1339 <- Server data response
1340 Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
1342 detailed information on the Server command and response formats.
1343
1345 The current QMP command set (described in this file) may be useful for
1346 a number of use cases, however it's limited and several commands have
1347 bad defined semantics, specially with regard to command completion.
1348 These problems are going to be solved incrementally in the next QEMU
1350 releases and we're going to establish a deprecation policy for badly
1351 defined commands.
1352 If you're planning to adopt QMP, please observe the following:
1354 1. The deprecation policy will take effect and be documented soon,
1356 please check the documentation of each used command as soon as a
1357 new release of QEMU is available
1358 2. DO NOT rely on anything which is not explicit documented
1360 3. Errors, in special, are not documented. Applications should NOT
1362 check for specific errors classes or data (it's strongly recom‐
1363 mended to only check for the "error" key)
1364
1366 QapiErrorClass (Enum)
1367 QEMU error classes
1368 Values
1370 GenericError
1371 this is used for errors that don't require a specific error
1372 class. This should be the default case for most errors
1373 CommandNotFound
1375 the requested command has not been found
1376 DeviceNotActive
1378 a device has failed to be become active
1379 DeviceNotFound
1381 the requested device has not been found
1382 KVMMissingCap
1384 the requested operation can't be fulfilled because a required
1385 KVM capability is missing
1386 Since
1388 1.2
1389
1391 IoOperationType (Enum)
1392 An enumeration of the I/O operation types
1393 Values
1395 read read operation
1396 write write operation
1398 Since
1400 2.1
1401 OnOffAuto (Enum)
1403 An enumeration of three options: on, off, and auto
1404 Values
1406 auto QEMU selects the value between on and off
1407 on Enabled
1409 off Disabled
1411 Since
1413 2.2
1414 OnOffSplit (Enum)
1416 An enumeration of three values: on, off, and split
1417 Values
1419 on Enabled
1420 off Disabled
1422 split Mixed
1424 Since
1426 2.6
1427 String (Object)
1429 A fat type wrapping 'str', to be embedded in lists.
1430 Members
1432 str: string
1433 Not documented
1434 Since
1436 1.2
1437 StrOrNull (Alternate)
1439 This is a string value or the explicit lack of a string (null pointer
1440 in C). Intended for cases when 'optional absent' already has a differ‐
1441 ent meaning.
1442 Members
1444 s: string
1445 the string value
1446 n: null
1448 no string value
1449 Since
1451 2.10
1452 OffAutoPCIBAR (Enum)
1454 An enumeration of options for specifying a PCI BAR
1455 Values
1457 off The specified feature is disabled
1458 auto The PCI BAR for the feature is automatically selected
1460 bar0 PCI BAR0 is used for the feature
1462 bar1 PCI BAR1 is used for the feature
1464 bar2 PCI BAR2 is used for the feature
1466 bar3 PCI BAR3 is used for the feature
1468 bar4 PCI BAR4 is used for the feature
1470 bar5 PCI BAR5 is used for the feature
1472 Since
1474 2.12
1475 PCIELinkSpeed (Enum)
1477 An enumeration of PCIe link speeds in units of GT/s
1478 Values
1480 2_5 2.5GT/s
1481 5 5.0GT/s
1483 8 8.0GT/s
1485 16 16.0GT/s
1487 Since
1489 4.0
1490 PCIELinkWidth (Enum)
1492 An enumeration of PCIe link width
1493 Values
1495 1 x1
1496 2 x2
1498 4 x4
1500 8 x8
1502 12 x12
1504 16 x16
1506 32 x32
1508 Since
1510 4.0
1511 HostMemPolicy (Enum)
1513 Host memory policy types
1514 Values
1516 default
1517 restore default policy, remove any nondefault policy
1518 preferred
1520 set the preferred host nodes for allocation
1521 bind a strict policy that restricts memory allocation to the host
1523 nodes specified
1524 interleave
1526 memory allocations are interleaved across the set of host nodes
1527 specified
1528 Since
1530 2.1
1531 NetFilterDirection (Enum)
1533 Indicates whether a netfilter is attached to a netdev's transmit queue
1534 or receive queue or both.
1535 Values
1537 all the filter is attached both to the receive and the transmit
1538 queue of the netdev (default).
1539 rx the filter is attached to the receive queue of the netdev, where
1541 it will receive packets sent to the netdev.
1542 tx the filter is attached to the transmit queue of the netdev,
1544 where it will receive packets sent by the netdev.
1545 Since
1547 2.5
1548 GrabToggleKeys (Enum)
1550 Keys to toggle input-linux between host and guest.
1551 Values
1553 ctrl-ctrl
1554 Not documented
1555 alt-alt
1557 Not documented
1558 shift-shift
1560 Not documented
1561 meta-meta
1563 Not documented
1564 scrolllock
1566 Not documented
1567 ctrl-scrolllock
1569 Not documented
1570 Since
1572 4.0
1573 HumanReadableText (Object)
1575 Members
1576 human-readable-text: string
1577 Formatted output intended for humans.
1578 Since
1580 6.2
1581
1583 NetworkAddressFamily (Enum)
1584 The network address family
1585 Values
1587 ipv4 IPV4 family
1588 ipv6 IPV6 family
1590 unix unix socket
1592 vsock vsock family (since 2.8)
1594 unknown
1596 otherwise
1597 Since
1599 2.1
1600 InetSocketAddressBase (Object)
1602 Members
1603 host: string
1604 host part of the address
1605 port: string
1607 port part of the address
1608 InetSocketAddress (Object)
1610 Captures a socket address or address range in the Internet namespace.
1611 Members
1613 numeric: boolean (optional)
1614 true if the host/port are guaranteed to be numeric, false if
1615 name resolution should be attempted. Defaults to false. (Since
1616 2.9)
1617 to: int (optional)
1619 If present, this is range of possible addresses, with port be‐
1620 tween port and to.
1621 ipv4: boolean (optional)
1623 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1624 ipv6: boolean (optional)
1626 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1627 keep-alive: boolean (optional)
1629 enable keep-alive when connecting to this socket. Not supported
1630 for passive sockets. (Since 4.2)
1631 mptcp: boolean (optional) (If: HAVE_IPPROTO_MPTCP)
1633 enable multi-path TCP. (Since 6.1)
1634 The members of InetSocketAddressBase
1636 Since
1638 1.3
1639 UnixSocketAddress (Object)
1641 Captures a socket address in the local ("Unix socket") namespace.
1642 Members
1644 path: string
1645 filesystem path to use
1646 abstract: boolean (optional) (If: CONFIG_LINUX)
1648 if true, this is a Linux abstract socket address. path will be
1649 prefixed by a null byte, and optionally padded with null bytes.
1650 Defaults to false. (Since 5.1)
1651 tight: boolean (optional) (If: CONFIG_LINUX)
1653 if false, pad an abstract socket address with enough null bytes
1654 to make it fill struct sockaddr_un member sun_path. Defaults to
1655 true. (Since 5.1)
1656 Since
1658 1.3
1659 VsockSocketAddress (Object)
1661 Captures a socket address in the vsock namespace.
1662 Members
1664 cid: string
1665 unique host identifier
1666 port: string
1668 port
1669 Note
1671 string types are used to allow for possible future hostname or service
1672 resolution support.
1673 Since
1675 2.8
1676 InetSocketAddressWrapper (Object)
1678 Members
1679 data: InetSocketAddress
1680 Not documented
1681 Since
1683 1.3
1684 UnixSocketAddressWrapper (Object)
1686 Members
1687 data: UnixSocketAddress
1688 Not documented
1689 Since
1691 1.3
1692 VsockSocketAddressWrapper (Object)
1694 Members
1695 data: VsockSocketAddress
1696 Not documented
1697 Since
1699 2.8
1700 StringWrapper (Object)
1702 Members
1703 data: String
1704 Not documented
1705 Since
1707 1.3
1708 SocketAddressLegacy (Object)
1710 Captures the address of a socket, which could also be a named file de‐
1711 scriptor
1712 Members
1714 type: SocketAddressType
1715 Not documented
1716 The members of InetSocketAddressWrapper when type is "inet"
1718 The members of UnixSocketAddressWrapper when type is "unix"
1720 The members of VsockSocketAddressWrapper when type is "vsock"
1722 The members of StringWrapper when type is "fd"
1724 Note
1726 This type is deprecated in favor of SocketAddress. The difference be‐
1727 tween SocketAddressLegacy and SocketAddress is that the latter has
1728 fewer {} on the wire.
1729 Since
1731 1.3
1732 SocketAddressType (Enum)
1734 Available SocketAddress types
1735 Values
1737 inet Internet address
1738 unix Unix domain socket
1740 vsock VMCI address
1742 fd decimal is for file descriptor number, otherwise a file descrip‐
1744 tor name. Named file descriptors are permitted in monitor com‐
1745 mands, in combination with the 'getfd' command. Decimal file de‐
1746 scriptors are permitted at startup or other contexts where no
1747 monitor context is active.
1748 Since
1750 2.9
1751 SocketAddress (Object)
1753 Captures the address of a socket, which could also be a named file de‐
1754 scriptor
1755 Members
1757 type: SocketAddressType
1758 Transport type
1759 The members of InetSocketAddress when type is "inet"
1761 The members of UnixSocketAddress when type is "unix"
1763 The members of VsockSocketAddress when type is "vsock"
1765 The members of String when type is "fd"
1767 Since
1769 2.9
1770
1772 RunState (Enum)
1773 An enumeration of VM run states.
1774 Values
1776 debug QEMU is running on a debugger
1777 finish-migrate
1779 guest is paused to finish the migration process
1780 inmigrate
1782 guest is paused waiting for an incoming migration. Note that
1783 this state does not tell whether the machine will start at the
1784 end of the migration. This depends on the command-line -S op‐
1785 tion and any invocation of 'stop' or 'cont' that has happened
1786 since QEMU was started.
1787 internal-error
1789 An internal error that prevents further guest execution has oc‐
1790 curred
1791 io-error
1793 the last IOP has failed and the device is configured to pause on
1794 I/O errors
1795 paused guest has been paused via the 'stop' command
1797 postmigrate
1799 guest is paused following a successful 'migrate'
1800 prelaunch
1802 QEMU was started with -S and guest has not started
1803 restore-vm
1805 guest is paused to restore VM state
1806 running
1808 guest is actively running
1809 save-vm
1811 guest is paused to save the VM state
1812 shutdown
1814 guest is shut down (and -no-shutdown is in use)
1815 suspended
1817 guest is suspended (ACPI S3)
1818 watchdog
1820 the watchdog action is configured to pause and has been trig‐
1821 gered
1822 guest-panicked
1824 guest has been panicked as a result of guest OS panic
1825 colo guest is paused to save/restore VM state under colo checkpoint,
1827 VM can not get into this state unless colo capability is enabled
1828 for migration. (since 2.8)
1829 ShutdownCause (Enum)
1831 An enumeration of reasons for a Shutdown.
1832 Values
1834 none No shutdown request pending
1835 host-error
1837 An error prevents further use of guest
1838 host-qmp-quit
1840 Reaction to the QMP command 'quit'
1841 host-qmp-system-reset
1843 Reaction to the QMP command 'system_reset'
1844 host-signal
1846 Reaction to a signal, such as SIGINT
1847 host-ui
1849 Reaction to a UI event, like window close
1850 guest-shutdown
1852 Guest shutdown/suspend request, via ACPI or other hardware-spe‐
1853 cific means
1854 guest-reset
1856 Guest reset request, and command line turns that into a shutdown
1857 guest-panic
1859 Guest panicked, and command line turns that into a shutdown
1860 subsystem-reset
1862 Partial guest reset that does not trigger QMP events and ignores
1863 --no-reboot. This is useful for sanitizing hypercalls on s390
1864 that are used during kexec/kdump/boot
1865 snapshot-load
1867 A snapshot is being loaded by the record & replay subsystem.
1868 This value is used only within QEMU. It doesn't occur in QMP.
1869 (since 7.2)
1870 StatusInfo (Object)
1872 Information about VCPU run state
1873 Members
1875 running: boolean
1876 true if all VCPUs are runnable, false if not runnable
1877 singlestep: boolean
1879 true if VCPUs are in single-step mode
1880 status: RunState
1882 the virtual machine RunState
1883 Since
1885 0.14
1886 Notes
1888 singlestep is enabled through the GDB stub
1889 query-status (Command)
1891 Query the run status of all VCPUs
1892 Returns
1894 StatusInfo reflecting all VCPUs
1895 Since
1897 0.14
1898 Example
1900 -> { "execute": "query-status" }
1901 <- { "return": { "running": true,
1902 "singlestep": false,
1903 "status": "running" } }
1904 SHUTDOWN (Event)
1906 Emitted when the virtual machine has shut down, indicating that qemu is
1907 about to exit.
1908 Arguments
1910 guest: boolean
1911 If true, the shutdown was triggered by a guest request (such as
1912 a guest-initiated ACPI shutdown request or other hardware-spe‐
1913 cific action) rather than a host request (such as sending qemu a
1914 SIGINT). (since 2.10)
1915 reason: ShutdownCause
1917 The ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
1918 Note
1920 If the command-line option "-no-shutdown" has been specified, qemu will
1921 not exit, and a STOP event will eventually follow the SHUTDOWN event
1922 Since
1924 0.12
1925 Example
1927 <- { "event": "SHUTDOWN",
1928 "data": { "guest": true, "reason": "guest-shutdown" },
1929 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1930 POWERDOWN (Event)
1932 Emitted when the virtual machine is powered down through the power con‐
1933 trol system, such as via ACPI.
1934 Since
1936 0.12
1937 Example
1939 <- { "event": "POWERDOWN",
1940 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1941 RESET (Event)
1943 Emitted when the virtual machine is reset
1944 Arguments
1946 guest: boolean
1947 If true, the reset was triggered by a guest request (such as a
1948 guest-initiated ACPI reboot request or other hardware-specific
1949 action) rather than a host request (such as the QMP command sys‐
1950 tem_reset). (since 2.10)
1951 reason: ShutdownCause
1953 The ShutdownCause of the RESET. (since 4.0)
1954 Since
1956 0.12
1957 Example
1959 <- { "event": "RESET",
1960 "data": { "guest": false, "reason": "guest-reset" },
1961 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
1962 STOP (Event)
1964 Emitted when the virtual machine is stopped
1965 Since
1967 0.12
1968 Example
1970 <- { "event": "STOP",
1971 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
1972 RESUME (Event)
1974 Emitted when the virtual machine resumes execution
1975 Since
1977 0.12
1978 Example
1980 <- { "event": "RESUME",
1981 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
1982 SUSPEND (Event)
1984 Emitted when guest enters a hardware suspension state, for example, S3
1985 state, which is sometimes called standby state
1986 Since
1988 1.1
1989 Example
1991 <- { "event": "SUSPEND",
1992 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
1993 SUSPEND_DISK (Event)
1995 Emitted when guest enters a hardware suspension state with data saved
1996 on disk, for example, S4 state, which is sometimes called hibernate
1997 state
1998 Note
2000 QEMU shuts down (similar to event SHUTDOWN) when entering this state
2001 Since
2003 1.2
2004 Example
2006 <- { "event": "SUSPEND_DISK",
2007 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
2008 WAKEUP (Event)
2010 Emitted when the guest has woken up from suspend state and is running
2011 Since
2013 1.1
2014 Example
2016 <- { "event": "WAKEUP",
2017 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
2018 WATCHDOG (Event)
2020 Emitted when the watchdog device's timer is expired
2021 Arguments
2023 action: WatchdogAction
2024 action that has been taken
2025 Note
2027 If action is "reset", "shutdown", or "pause" the WATCHDOG event is fol‐
2028 lowed respectively by the RESET, SHUTDOWN, or STOP events
2029 Note
2031 This event is rate-limited.
2032 Since
2034 0.13
2035 Example
2037 <- { "event": "WATCHDOG",
2038 "data": { "action": "reset" },
2039 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
2040 WatchdogAction (Enum)
2042 An enumeration of the actions taken when the watchdog device's timer is
2043 expired
2044 Values
2046 reset system resets
2047 shutdown
2049 system shutdown, note that it is similar to powerdown, which
2050 tries to set to system status and notify guest
2051 poweroff
2053 system poweroff, the emulator program exits
2054 pause system pauses, similar to stop
2056 debug system enters debug state
2058 none nothing is done
2060 inject-nmi
2062 a non-maskable interrupt is injected into the first VCPU (all
2063 VCPUS on x86) (since 2.4)
2064 Since
2066 2.1
2067 RebootAction (Enum)
2069 Possible QEMU actions upon guest reboot
2070 Values
2072 reset Reset the VM
2073 shutdown
2075 Shutdown the VM and exit, according to the shutdown action
2076 Since
2078 6.0
2079 ShutdownAction (Enum)
2081 Possible QEMU actions upon guest shutdown
2082 Values
2084 poweroff
2085 Shutdown the VM and exit
2086 pause pause the VM
2088 Since
2090 6.0
2091 PanicAction (Enum)
2093 Values
2094 none Continue VM execution
2095 pause Pause the VM
2097 shutdown
2099 Shutdown the VM and exit, according to the shutdown action
2100 exit-failure
2102 Shutdown the VM and exit with nonzero status (since 7.1)
2103 Since
2105 6.0
2106 watchdog-set-action (Command)
2108 Set watchdog action
2109 Arguments
2111 action: WatchdogAction
2112 Not documented
2113 Since
2115 2.11
2116 set-action (Command)
2118 Set the actions that will be taken by the emulator in response to guest
2119 events.
2120 Arguments
2122 reboot: RebootAction (optional)
2123 RebootAction action taken on guest reboot.
2124 shutdown: ShutdownAction (optional)
2126 ShutdownAction action taken on guest shutdown.
2127 panic: PanicAction (optional)
2129 PanicAction action taken on guest panic.
2130 watchdog: WatchdogAction (optional)
2132 WatchdogAction action taken when watchdog timer expires .
2133 Returns
2135 Nothing on success.
2136 Since
2138 6.0
2139 Example
2141 -> { "execute": "set-action",
2142 "arguments": { "reboot": "shutdown",
2143 "shutdown" : "pause",
2144 "panic": "pause",
2145 "watchdog": "inject-nmi" } }
2146 <- { "return": {} }
2147 GUEST_PANICKED (Event)
2149 Emitted when guest OS panic is detected
2150 Arguments
2152 action: GuestPanicAction
2153 action that has been taken, currently always "pause"
2154 info: GuestPanicInformation (optional)
2156 information about a panic (since 2.9)
2157 Since
2159 1.5
2160 Example
2162 <- { "event": "GUEST_PANICKED",
2163 "data": { "action": "pause" },
2164 "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
2165 GUEST_CRASHLOADED (Event)
2167 Emitted when guest OS crash loaded is detected
2168 Arguments
2170 action: GuestPanicAction
2171 action that has been taken, currently always "run"
2172 info: GuestPanicInformation (optional)
2174 information about a panic
2175 Since
2177 5.0
2178 Example
2180 <- { "event": "GUEST_CRASHLOADED",
2181 "data": { "action": "run" },
2182 "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
2183 GuestPanicAction (Enum)
2185 An enumeration of the actions taken when guest OS panic is detected
2186 Values
2188 pause system pauses
2189 poweroff
2191 Not documented
2192 run Not documented
2194 Since
2196 2.1 (poweroff since 2.8, run since 5.0)
2197 GuestPanicInformationType (Enum)
2199 An enumeration of the guest panic information types
2200 Values
2202 hyper-v
2203 hyper-v guest panic information type
2204 s390 s390 guest panic information type (Since: 2.12)
2206 Since
2208 2.9
2209 GuestPanicInformation (Object)
2211 Information about a guest panic
2212 Members
2214 type: GuestPanicInformationType
2215 Crash type that defines the hypervisor specific information
2216 The members of GuestPanicInformationHyperV when type is "hyper-v"
2218 The members of GuestPanicInformationS390 when type is "s390"
2220 Since
2222 2.9
2223 GuestPanicInformationHyperV (Object)
2225 Hyper-V specific guest panic information (HV crash MSRs)
2226 Members
2228 arg1: int
2229 Not documented
2230 arg2: int
2232 Not documented
2233 arg3: int
2235 Not documented
2236 arg4: int
2238 Not documented
2239 arg5: int
2241 Not documented
2242 Since
2244 2.9
2245 S390CrashReason (Enum)
2247 Reason why the CPU is in a crashed state.
2248 Values
2250 unknown
2251 no crash reason was set
2252 disabled-wait
2254 the CPU has entered a disabled wait state
2255 extint-loop
2257 clock comparator or cpu timer interrupt with new PSW enabled for
2258 external interrupts
2259 pgmint-loop
2261 program interrupt with BAD new PSW
2262 opint-loop
2264 operation exception interrupt with invalid code at the program
2265 interrupt new PSW
2266 Since
2268 2.12
2269 GuestPanicInformationS390 (Object)
2271 S390 specific guest panic information (PSW)
2272 Members
2274 core: int
2275 core id of the CPU that crashed
2276 psw-mask: int
2278 control fields of guest PSW
2279 psw-addr: int
2281 guest instruction address
2282 reason: S390CrashReason
2284 guest crash reason
2285 Since
2287 2.12
2288 MEMORY_FAILURE (Event)
2290 Emitted when a memory failure occurs on host side.
2291 Arguments
2293 recipient: MemoryFailureRecipient
2294 recipient is defined as MemoryFailureRecipient.
2295 action: MemoryFailureAction
2297 action that has been taken. action is defined as MemoryFailure‐
2298 Action.
2299 flags: MemoryFailureFlags
2301 flags for MemoryFailureAction. action is defined as MemoryFail‐
2302 ureFlags.
2303 Since
2305 5.2
2306 Example
2308 <- { "event": "MEMORY_FAILURE",
2309 "data": { "recipient": "hypervisor",
2310 "action": "fatal",
2311 "flags": { "action-required": false,
2312 "recursive": false } },
2313 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
2314 MemoryFailureRecipient (Enum)
2316 Hardware memory failure occurs, handled by recipient.
2317 Values
2319 hypervisor
2320 memory failure at QEMU process address space. (none guest mem‐
2321 ory, but used by QEMU itself).
2322 guest memory failure at guest memory,
2324 Since
2326 5.2
2327 MemoryFailureAction (Enum)
2329 Actions taken by QEMU in response to a hardware memory failure.
2330 Values
2332 ignore the memory failure could be ignored. This will only be the case
2333 for action-optional failures.
2334 inject memory failure occurred in guest memory, the guest enabled MCE
2336 handling mechanism, and QEMU could inject the MCE into the guest
2337 successfully.
2338 fatal the failure is unrecoverable. This occurs for action-required
2340 failures if the recipient is the hypervisor; QEMU will exit.
2341 reset the failure is unrecoverable but confined to the guest. This
2343 occurs if the recipient is a guest guest which is not ready to
2344 handle memory failures.
2345 Since
2347 5.2
2348 MemoryFailureFlags (Object)
2350 Additional information on memory failures.
2351 Members
2353 action-required: boolean
2354 whether a memory failure event is action-required or action-op‐
2355 tional (e.g. a failure during memory scrub).
2356 recursive: boolean
2358 whether the failure occurred while the previous failure was
2359 still in progress.
2360 Since
2362 5.2
2363 NotifyVmexitOption (Enum)
2365 An enumeration of the options specified when enabling notify VM exit
2366 Values
2368 run enable the feature, do nothing and continue if the notify VM
2369 exit happens.
2370 internal-error
2372 enable the feature, raise a internal error if the notify VM exit
2373 happens.
2374 disable
2376 disable the feature.
2377 Since
2379 7.2
2380
2382 QCryptoTLSCredsEndpoint (Enum)
2383 The type of network endpoint that will be using the credentials. Most
2384 types of credential require different setup / structures depending on
2385 whether they will be used in a server versus a client.
2386 Values
2388 client the network endpoint is acting as the client
2389 server the network endpoint is acting as the server
2391 Since
2393 2.5
2394 QCryptoSecretFormat (Enum)
2396 The data format that the secret is provided in
2397 Values
2399 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
2400 be used
2401 base64 arbitrary base64 encoded binary data
2403 Since
2405 2.6
2406 QCryptoHashAlgorithm (Enum)
2408 The supported algorithms for computing content digests
2409 Values
2411 md5 MD5. Should not be used in any new code, legacy compat only
2412 sha1 SHA-1. Should not be used in any new code, legacy compat only
2414 sha224 SHA-224. (since 2.7)
2416 sha256 SHA-256. Current recommended strong hash.
2418 sha384 SHA-384. (since 2.7)
2420 sha512 SHA-512. (since 2.7)
2422 ripemd160
2424 RIPEMD-160. (since 2.7)
2425 Since
2427 2.6
2428 QCryptoCipherAlgorithm (Enum)
2430 The supported algorithms for content encryption ciphers
2431 Values
2433 aes-128
2434 AES with 128 bit / 16 byte keys
2435 aes-192
2437 AES with 192 bit / 24 byte keys
2438 aes-256
2440 AES with 256 bit / 32 byte keys
2441 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
2443 6.1)
2444 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
2446 cast5-128
2448 Cast5 with 128 bit / 16 byte keys
2449 serpent-128
2451 Serpent with 128 bit / 16 byte keys
2452 serpent-192
2454 Serpent with 192 bit / 24 byte keys
2455 serpent-256
2457 Serpent with 256 bit / 32 byte keys
2458 twofish-128
2460 Twofish with 128 bit / 16 byte keys
2461 twofish-192
2463 Twofish with 192 bit / 24 byte keys
2464 twofish-256
2466 Twofish with 256 bit / 32 byte keys
2467 Since
2469 2.6
2470 QCryptoCipherMode (Enum)
2472 The supported modes for content encryption ciphers
2473 Values
2475 ecb Electronic Code Book
2476 cbc Cipher Block Chaining
2478 xts XEX with tweaked code book and ciphertext stealing
2480 ctr Counter (Since 2.8)
2482 Since
2484 2.6
2485 QCryptoIVGenAlgorithm (Enum)
2487 The supported algorithms for generating initialization vectors for full
2488 disk encryption. The 'plain' generator should not be used for disks
2489 with sector numbers larger than 2^32, except where compatibility with
2490 pre-existing Linux dm-crypt volumes is required.
2491 Values
2493 plain 64-bit sector number truncated to 32-bits
2494 plain64
2496 64-bit sector number
2497 essiv 64-bit sector number encrypted with a hash of the encryption key
2499 Since
2501 2.6
2502 QCryptoBlockFormat (Enum)
2504 The supported full disk encryption formats
2505 Values
2507 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
2508 data from old images.
2509 luks LUKS encryption format. Recommended for new images
2511 Since
2513 2.6
2514 QCryptoBlockOptionsBase (Object)
2516 The common options that apply to all full disk encryption formats
2517 Members
2519 format: QCryptoBlockFormat
2520 the encryption format
2521 Since
2523 2.6
2524 QCryptoBlockOptionsQCow (Object)
2526 The options that apply to QCow/QCow2 AES-CBC encryption format
2527 Members
2529 key-secret: string (optional)
2530 the ID of a QCryptoSecret object providing the decryption key.
2531 Mandatory except when probing image for metadata only.
2532 Since
2534 2.6
2535 QCryptoBlockOptionsLUKS (Object)
2537 The options that apply to LUKS encryption format
2538 Members
2540 key-secret: string (optional)
2541 the ID of a QCryptoSecret object providing the decryption key.
2542 Mandatory except when probing image for metadata only.
2543 Since
2545 2.6
2546 QCryptoBlockCreateOptionsLUKS (Object)
2548 The options that apply to LUKS encryption format initialization
2549 Members
2551 cipher-alg: QCryptoCipherAlgorithm (optional)
2552 the cipher algorithm for data encryption Currently defaults to
2553 'aes-256'.
2554 cipher-mode: QCryptoCipherMode (optional)
2556 the cipher mode for data encryption Currently defaults to 'xts'
2557 ivgen-alg: QCryptoIVGenAlgorithm (optional)
2559 the initialization vector generator Currently defaults to
2560 'plain64'
2561 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2563 the initialization vector generator hash Currently defaults to
2564 'sha256'
2565 hash-alg: QCryptoHashAlgorithm (optional)
2567 the master key hash algorithm Currently defaults to 'sha256'
2568 iter-time: int (optional)
2570 number of milliseconds to spend in PBKDF passphrase processing.
2571 Currently defaults to 2000. (since 2.8)
2572 The members of QCryptoBlockOptionsLUKS
2574 Since
2576 2.6
2577 QCryptoBlockOpenOptions (Object)
2579 The options that are available for all encryption formats when opening
2580 an existing volume
2581 Members
2583 The members of QCryptoBlockOptionsBase
2584 The members of QCryptoBlockOptionsQCow when format is "qcow"
2586 The members of QCryptoBlockOptionsLUKS when format is "luks"
2588 Since
2590 2.6
2591 QCryptoBlockCreateOptions (Object)
2593 The options that are available for all encryption formats when initial‐
2594 izing a new volume
2595 Members
2597 The members of QCryptoBlockOptionsBase
2598 The members of QCryptoBlockOptionsQCow when format is "qcow"
2600 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
2602 Since
2604 2.6
2605 QCryptoBlockInfoBase (Object)
2607 The common information that applies to all full disk encryption formats
2608 Members
2610 format: QCryptoBlockFormat
2611 the encryption format
2612 Since
2614 2.7
2615 QCryptoBlockInfoLUKSSlot (Object)
2617 Information about the LUKS block encryption key slot options
2618 Members
2620 active: boolean
2621 whether the key slot is currently in use
2622 key-offset: int
2624 offset to the key material in bytes
2625 iters: int (optional)
2627 number of PBKDF2 iterations for key material
2628 stripes: int (optional)
2630 number of stripes for splitting key material
2631 Since
2633 2.7
2634 QCryptoBlockInfoLUKS (Object)
2636 Information about the LUKS block encryption options
2637 Members
2639 cipher-alg: QCryptoCipherAlgorithm
2640 the cipher algorithm for data encryption
2641 cipher-mode: QCryptoCipherMode
2643 the cipher mode for data encryption
2644 ivgen-alg: QCryptoIVGenAlgorithm
2646 the initialization vector generator
2647 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2649 the initialization vector generator hash
2650 hash-alg: QCryptoHashAlgorithm
2652 the master key hash algorithm
2653 payload-offset: int
2655 offset to the payload data in bytes
2656 master-key-iters: int
2658 number of PBKDF2 iterations for key material
2659 uuid: string
2661 unique identifier for the volume
2662 slots: array of QCryptoBlockInfoLUKSSlot
2664 information about each key slot
2665 Since
2667 2.7
2668 QCryptoBlockInfo (Object)
2670 Information about the block encryption options
2671 Members
2673 The members of QCryptoBlockInfoBase
2674 The members of QCryptoBlockInfoLUKS when format is "luks"
2676 Since
2678 2.7
2679 QCryptoBlockLUKSKeyslotState (Enum)
2681 Defines state of keyslots that are affected by the update
2682 Values
2684 active The slots contain the given password and marked as active
2685 inactive
2687 The slots are erased (contain garbage) and marked as inactive
2688 Since
2690 5.1
2691 QCryptoBlockAmendOptionsLUKS (Object)
2693 This struct defines the update parameters that activate/de-activate set
2694 of keyslots
2695 Members
2697 state: QCryptoBlockLUKSKeyslotState
2698 the desired state of the keyslots
2699 new-secret: string (optional)
2701 The ID of a QCryptoSecret object providing the password to be
2702 written into added active keyslots
2703 old-secret: string (optional)
2705 Optional (for deactivation only) If given will deactivate all
2706 keyslots that match password located in QCryptoSecret with this
2707 ID
2708 iter-time: int (optional)
2710 Optional (for activation only) Number of milliseconds to spend
2711 in PBKDF passphrase processing for the newly activated keyslot.
2712 Currently defaults to 2000.
2713 keyslot: int (optional)
2715 Optional. ID of the keyslot to activate/deactivate. For keyslot
2716 activation, keyslot should not be active already (this is unsafe
2717 to update an active keyslot), but possible if 'force' parameter
2718 is given. If keyslot is not given, first free keyslot will be
2719 written.
2720 For keyslot deactivation, this parameter specifies the exact
2722 keyslot to deactivate
2723 secret: string (optional)
2725 Optional. The ID of a QCryptoSecret object providing the pass‐
2726 word to use to retrieve current master key. Defaults to the
2727 same secret that was used to open the image
2728 Since
2730 5.1
2731 QCryptoBlockAmendOptions (Object)
2733 The options that are available for all encryption formats when amending
2734 encryption settings
2735 Members
2737 The members of QCryptoBlockOptionsBase
2738 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
2740 Since
2742 5.1
2743 SecretCommonProperties (Object)
2745 Properties for objects of classes derived from secret-common.
2746 Members
2748 loaded: boolean (optional)
2749 if true, the secret is loaded immediately when applying this op‐
2750 tion and will probably fail when processing the next option.
2751 Don't use; only provided for compatibility. (default: false)
2752 format: QCryptoSecretFormat (optional)
2754 the data format that the secret is provided in (default: raw)
2755 keyid: string (optional)
2757 the name of another secret that should be used to decrypt the
2758 provided data. If not present, the data is assumed to be unen‐
2759 crypted.
2760 iv: string (optional)
2762 the random initialization vector used for encryption of this
2763 particular secret. Should be a base64 encrypted string of the
2764 16-byte IV. Mandatory if keyid is given. Ignored if keyid is ab‐
2765 sent.
2766 Features
2768 deprecated
2769 Member loaded is deprecated. Setting true doesn't make sense,
2770 and false is already the default.
2771 Since
2773 2.6
2774 SecretProperties (Object)
2776 Properties for secret objects.
2777 Either data or file must be provided, but not both.
2779 Members
2781 data: string (optional)
2782 the associated with the secret from
2783 file: string (optional)
2785 the filename to load the data associated with the secret from
2786 The members of SecretCommonProperties
2788 Since
2790 2.6
2791 SecretKeyringProperties (Object)
2793 Properties for secret_keyring objects.
2794 Members
2796 serial: int
2797 serial number that identifies a key to get from the kernel
2798 The members of SecretCommonProperties
2800 Since
2802 5.1
2803 TlsCredsProperties (Object)
2805 Properties for objects of classes derived from tls-creds.
2806 Members
2808 verify-peer: boolean (optional)
2809 if true the peer credentials will be verified once the handshake
2810 is completed. This is a no-op for anonymous credentials. (de‐
2811 fault: true)
2812 dir: string (optional)
2814 the path of the directory that contains the credential files
2815 endpoint: QCryptoTLSCredsEndpoint (optional)
2817 whether the QEMU network backend that uses the credentials will
2818 be acting as a client or as a server (default: client)
2819 priority: string (optional)
2821 a gnutls priority string as described at
2822 https://gnutls.org/manual/html_node/Priority-Strings.html
2823 Since
2825 2.5
2826 TlsCredsAnonProperties (Object)
2828 Properties for tls-creds-anon objects.
2829 Members
2831 loaded: boolean (optional)
2832 if true, the credentials are loaded immediately when applying
2833 this option and will ignore options that are processed later.
2834 Don't use; only provided for compatibility. (default: false)
2835 The members of TlsCredsProperties
2837 Features
2839 deprecated
2840 Member loaded is deprecated. Setting true doesn't make sense,
2841 and false is already the default.
2842 Since
2844 2.5
2845 TlsCredsPskProperties (Object)
2847 Properties for tls-creds-psk objects.
2848 Members
2850 loaded: boolean (optional)
2851 if true, the credentials are loaded immediately when applying
2852 this option and will ignore options that are processed later.
2853 Don't use; only provided for compatibility. (default: false)
2854 username: string (optional)
2856 the username which will be sent to the server. For clients
2857 only. If absent, "qemu" is sent and the property will read back
2858 as an empty string.
2859 The members of TlsCredsProperties
2861 Features
2863 deprecated
2864 Member loaded is deprecated. Setting true doesn't make sense,
2865 and false is already the default.
2866 Since
2868 3.0
2869 TlsCredsX509Properties (Object)
2871 Properties for tls-creds-x509 objects.
2872 Members
2874 loaded: boolean (optional)
2875 if true, the credentials are loaded immediately when applying
2876 this option and will ignore options that are processed later.
2877 Don't use; only provided for compatibility. (default: false)
2878 sanity-check: boolean (optional)
2880 if true, perform some sanity checks before using the credentials
2881 (default: true)
2882 passwordid: string (optional)
2884 For the server-key.pem and client-key.pem files which contain
2885 sensitive private keys, it is possible to use an encrypted ver‐
2886 sion by providing the passwordid parameter. This provides the
2887 ID of a previously created secret object containing the password
2888 for decryption.
2889 The members of TlsCredsProperties
2891 Features
2893 deprecated
2894 Member loaded is deprecated. Setting true doesn't make sense,
2895 and false is already the default.
2896 Since
2898 2.5
2899 QCryptoAkCipherAlgorithm (Enum)
2901 The supported algorithms for asymmetric encryption ciphers
2902 Values
2904 rsa RSA algorithm
2905 Since
2907 7.1
2908 QCryptoAkCipherKeyType (Enum)
2910 The type of asymmetric keys.
2911 Values
2913 public Not documented
2914 private
2916 Not documented
2917 Since
2919 7.1
2920 QCryptoRSAPaddingAlgorithm (Enum)
2922 The padding algorithm for RSA.
2923 Values
2925 raw no padding used
2926 pkcs1 pkcs1#v1.5
2928 Since
2930 7.1
2931 QCryptoAkCipherOptionsRSA (Object)
2933 Specific parameters for RSA algorithm.
2934 Members
2936 hash-alg: QCryptoHashAlgorithm
2937 QCryptoHashAlgorithm
2938 padding-alg: QCryptoRSAPaddingAlgorithm
2940 QCryptoRSAPaddingAlgorithm
2941 Since
2943 7.1
2944 QCryptoAkCipherOptions (Object)
2946 The options that are available for all asymmetric key algorithms when
2947 creating a new QCryptoAkCipher.
2948 Members
2950 alg: QCryptoAkCipherAlgorithm
2951 Not documented
2952 The members of QCryptoAkCipherOptionsRSA when alg is "rsa"
2954 Since
2956 7.1
2957
2959 Block core (VM unrelated)
2960 Background jobs
2961 JobType (Enum)
2962 Type of a background job.
2963 Values
2965 commit block commit job type, see "block-commit"
2966 stream block stream job type, see "block-stream"
2968 mirror drive mirror job type, see "drive-mirror"
2970 backup drive backup job type, see "drive-backup"
2972 create image creation job type, see "blockdev-create" (since 3.0)
2974 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
2976 snapshot-load
2978 snapshot load job type, see "snapshot-load" (since 6.0)
2979 snapshot-save
2981 snapshot save job type, see "snapshot-save" (since 6.0)
2982 snapshot-delete
2984 snapshot delete job type, see "snapshot-delete" (since 6.0)
2985 Since
2987 1.7
2988 JobStatus (Enum)
2990 Indicates the present state of a given job in its lifetime.
2991 Values
2993 undefined
2994 Erroneous, default state. Should not ever be visible.
2995 created
2997 The job has been created, but not yet started.
2998 running
3000 The job is currently running.
3001 paused The job is running, but paused. The pause may be requested by
3003 either the QMP user or by internal processes.
3004 ready The job is running, but is ready for the user to signal comple‐
3006 tion. This is used for long-running jobs like mirror that are
3007 designed to run indefinitely.
3008 standby
3010 The job is ready, but paused. This is nearly identical to
3011 paused. The job may return to ready or otherwise be canceled.
3012 waiting
3014 The job is waiting for other jobs in the transaction to converge
3015 to the waiting state. This status will likely not be visible for
3016 the last job in a transaction.
3017 pending
3019 The job has finished its work, but has finalization steps that
3020 it needs to make prior to completing. These changes will require
3021 manual intervention via job-finalize if auto-finalize was set to
3022 false. These pending changes may still fail.
3023 aborting
3025 The job is in the process of being aborted, and will finish with
3026 an error. The job will afterwards report that it is concluded.
3027 This status may not be visible to the management process.
3028 concluded
3030 The job has finished all work. If auto-dismiss was set to false,
3031 the job will remain in the query list until it is dismissed via
3032 job-dismiss.
3033 null The job is in the process of being dismantled. This state should
3035 not ever be visible externally.
3036 Since
3038 2.12
3039 JobVerb (Enum)
3041 Represents command verbs that can be applied to a job.
3042 Values
3044 cancel see job-cancel
3045 pause see job-pause
3047 resume see job-resume
3049 set-speed
3051 see block-job-set-speed
3052 complete
3054 see job-complete
3055 dismiss
3057 see job-dismiss
3058 finalize
3060 see job-finalize
3061 Since
3063 2.12
3064 JOB_STATUS_CHANGE (Event)
3066 Emitted when a job transitions to a different status.
3067 Arguments
3069 id: string
3070 The job identifier
3071 status: JobStatus
3073 The new job status
3074 Since
3076 3.0
3077 job-pause (Command)
3079 Pause an active job.
3080 This command returns immediately after marking the active job for paus‐
3082 ing. Pausing an already paused job is an error.
3083 The job will pause as soon as possible, which means transitioning into
3085 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
3086 The corresponding JOB_STATUS_CHANGE event will be emitted.
3087 Cancelling a paused job automatically resumes it.
3089 Arguments
3091 id: string
3092 The job identifier.
3093 Since
3095 3.0
3096 job-resume (Command)
3098 Resume a paused job.
3099 This command returns immediately after resuming a paused job. Resuming
3101 an already running job is an error.
3102 id : The job identifier.
3104 Arguments
3106 id: string
3107 Not documented
3108 Since
3110 3.0
3111 job-cancel (Command)
3113 Instruct an active background job to cancel at the next opportunity.
3114 This command returns immediately after marking the active job for can‐
3115 cellation.
3116 The job will cancel as soon as possible and then emit a JOB_STA‐
3118 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
3119 is possible that a job successfully completes (e.g. because it was al‐
3120 most done and there was no opportunity to cancel earlier than complet‐
3121 ing the job) and transitions to PENDING instead.
3122 Arguments
3124 id: string
3125 The job identifier.
3126 Since
3128 3.0
3129 job-complete (Command)
3131 Manually trigger completion of an active job in the READY state.
3132 Arguments
3134 id: string
3135 The job identifier.
3136 Since
3138 3.0
3139 job-dismiss (Command)
3141 Deletes a job that is in the CONCLUDED state. This command only needs
3142 to be run explicitly for jobs that don't have automatic dismiss en‐
3143 abled.
3144 This command will refuse to operate on any job that has not yet reached
3146 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
3147 JOB_READY event, job-cancel or job-complete will still need to be used
3148 as appropriate.
3149 Arguments
3151 id: string
3152 The job identifier.
3153 Since
3155 3.0
3156 job-finalize (Command)
3158 Instructs all jobs in a transaction (or a single job if it is not part
3159 of any transaction) to finalize any graph changes and do any necessary
3160 cleanup. This command requires that all involved jobs are in the PEND‐
3161 ING state.
3162 For jobs in a transaction, instructing one job to finalize will force
3164 ALL jobs in the transaction to finalize, so it is only necessary to in‐
3165 struct a single member job to finalize.
3166 Arguments
3168 id: string
3169 The identifier of any job in the transaction, or of a job that
3170 is not part of any transaction.
3171 Since
3173 3.0
3174 JobInfo (Object)
3176 Information about a job.
3177 Members
3179 id: string
3180 The job identifier
3181 type: JobType
3183 The kind of job that is being performed
3184 status: JobStatus
3186 Current job state/status
3187 current-progress: int
3189 Progress made until now. The unit is arbitrary and the value can
3190 only meaningfully be used for the ratio of current-progress to
3191 total-progress. The value is monotonically increasing.
3192 total-progress: int
3194 Estimated current-progress value at the completion of the job.
3195 This value can arbitrarily change while the job is running, in
3196 both directions.
3197 error: string (optional)
3199 If this field is present, the job failed; if it is still missing
3200 in the CONCLUDED state, this indicates successful completion.
3201 The value is a human-readable error message to describe the rea‐
3203 son for the job failure. It should not be parsed by applica‐
3204 tions.
3205 Since
3207 3.0
3208 query-jobs (Command)
3210 Return information about jobs.
3211 Returns
3213 a list with a JobInfo for each active job
3214 Since
3216 3.0
3217 SnapshotInfo (Object)
3219 Members
3220 id: string
3221 unique snapshot id
3222 name: string
3224 user chosen name
3225 vm-state-size: int
3227 size of the VM state
3228 date-sec: int
3230 UTC date of the snapshot in seconds
3231 date-nsec: int
3233 fractional part in nano seconds to be used with date-sec
3234 vm-clock-sec: int
3236 VM clock relative to boot in seconds
3237 vm-clock-nsec: int
3239 fractional part in nano seconds to be used with vm-clock-sec
3240 icount: int (optional)
3242 Current instruction count. Appears when execution record/replay
3243 is enabled. Used for "time-traveling" to match the moment in the
3244 recorded execution with the snapshots. This counter may be ob‐
3245 tained through query-replay command (since 5.2)
3246 Since
3248 1.3
3249 ImageInfoSpecificQCow2EncryptionBase (Object)
3251 Members
3252 format: BlockdevQcow2EncryptionFormat
3253 The encryption format
3254 Since
3256 2.10
3257 ImageInfoSpecificQCow2Encryption (Object)
3259 Members
3260 The members of ImageInfoSpecificQCow2EncryptionBase
3261 The members of QCryptoBlockInfoLUKS when format is "luks"
3263 Since
3265 2.10
3266 ImageInfoSpecificQCow2 (Object)
3268 Members
3269 compat: string
3270 compatibility level
3271 data-file: string (optional)
3273 the filename of the external data file that is stored in the im‐
3274 age and used as a default for opening the image (since: 4.0)
3275 data-file-raw: boolean (optional)
3277 True if the external data file must stay valid as a standalone
3278 (read-only) raw image without looking at qcow2 metadata (since:
3279 4.0)
3280 extended-l2: boolean (optional)
3282 true if the image has extended L2 entries; only valid for compat
3283 >= 1.1 (since 5.2)
3284 lazy-refcounts: boolean (optional)
3286 on or off; only valid for compat >= 1.1
3287 corrupt: boolean (optional)
3289 true if the image has been marked corrupt; only valid for compat
3290 >= 1.1 (since 2.2)
3291 refcount-bits: int
3293 width of a refcount entry in bits (since 2.3)
3294 encrypt: ImageInfoSpecificQCow2Encryption (optional)
3296 details about encryption parameters; only set if image is en‐
3297 crypted (since 2.10)
3298 bitmaps: array of Qcow2BitmapInfo (optional)
3300 A list of qcow2 bitmap details (since 4.0)
3301 compression-type: Qcow2CompressionType
3303 the image cluster compression method (since 5.1)
3304 Since
3306 1.7
3307 ImageInfoSpecificVmdk (Object)
3309 Members
3310 create-type: string
3311 The create type of VMDK image
3312 cid: int
3314 Content id of image
3315 parent-cid: int
3317 Parent VMDK image's cid
3318 extents: array of ImageInfo
3320 List of extent files
3321 Since
3323 1.7
3324 ImageInfoSpecificRbd (Object)
3326 Members
3327 encryption-format: RbdImageEncryptionFormat (optional)
3328 Image encryption format
3329 Since
3331 6.1
3332 ImageInfoSpecificKind (Enum)
3334 Values
3335 luks Since 2.7
3336 rbd Since 6.1
3338 qcow2 Not documented
3340 vmdk Not documented
3342 Since
3344 1.7
3345 ImageInfoSpecificQCow2Wrapper (Object)
3347 Members
3348 data: ImageInfoSpecificQCow2
3349 Not documented
3350 Since
3352 1.7
3353 ImageInfoSpecificVmdkWrapper (Object)
3355 Members
3356 data: ImageInfoSpecificVmdk
3357 Not documented
3358 Since
3360 6.1
3361 ImageInfoSpecificLUKSWrapper (Object)
3363 Members
3364 data: QCryptoBlockInfoLUKS
3365 Not documented
3366 Since
3368 2.7
3369 ImageInfoSpecificRbdWrapper (Object)
3371 Members
3372 data: ImageInfoSpecificRbd
3373 Not documented
3374 Since
3376 6.1
3377 ImageInfoSpecific (Object)
3379 A discriminated record of image format specific information structures.
3380 Members
3382 type: ImageInfoSpecificKind
3383 Not documented
3384 The members of ImageInfoSpecificQCow2Wrapper when type is "qcow2"
3386 The members of ImageInfoSpecificVmdkWrapper when type is "vmdk"
3388 The members of ImageInfoSpecificLUKSWrapper when type is "luks"
3390 The members of ImageInfoSpecificRbdWrapper when type is "rbd"
3392 Since
3394 1.7
3395 ImageInfo (Object)
3397 Information about a QEMU image file
3398 Members
3400 filename: string
3401 name of the image file
3402 format: string
3404 format of the image file
3405 virtual-size: int
3407 maximum capacity in bytes of the image
3408 actual-size: int (optional)
3410 actual size on disk in bytes of the image
3411 dirty-flag: boolean (optional)
3413 true if image is not cleanly closed
3414 cluster-size: int (optional)
3416 size of a cluster in bytes
3417 encrypted: boolean (optional)
3419 true if the image is encrypted
3420 compressed: boolean (optional)
3422 true if the image is compressed (Since 1.7)
3423 backing-filename: string (optional)
3425 name of the backing file
3426 full-backing-filename: string (optional)
3428 full path of the backing file
3429 backing-filename-format: string (optional)
3431 the format of the backing file
3432 snapshots: array of SnapshotInfo (optional)
3434 list of VM snapshots
3435 backing-image: ImageInfo (optional)
3437 info of the backing image (since 1.6)
3438 format-specific: ImageInfoSpecific (optional)
3440 structure supplying additional format-specific information
3441 (since 1.7)
3442 Since
3444 1.3
3445 ImageCheck (Object)
3447 Information about a QEMU image file check
3448 Members
3450 filename: string
3451 name of the image file checked
3452 format: string
3454 format of the image file checked
3455 check-errors: int
3457 number of unexpected errors occurred during check
3458 image-end-offset: int (optional)
3460 offset (in bytes) where the image ends, this field is present if
3461 the driver for the image format supports it
3462 corruptions: int (optional)
3464 number of corruptions found during the check if any
3465 leaks: int (optional)
3467 number of leaks found during the check if any
3468 corruptions-fixed: int (optional)
3470 number of corruptions fixed during the check if any
3471 leaks-fixed: int (optional)
3473 number of leaks fixed during the check if any
3474 total-clusters: int (optional)
3476 total number of clusters, this field is present if the driver
3477 for the image format supports it
3478 allocated-clusters: int (optional)
3480 total number of allocated clusters, this field is present if the
3481 driver for the image format supports it
3482 fragmented-clusters: int (optional)
3484 total number of fragmented clusters, this field is present if
3485 the driver for the image format supports it
3486 compressed-clusters: int (optional)
3488 total number of compressed clusters, this field is present if
3489 the driver for the image format supports it
3490 Since
3492 1.4
3493 MapEntry (Object)
3495 Mapping information from a virtual block range to a host file range
3496 Members
3498 start: int
3499 virtual (guest) offset of the first byte described by this entry
3500 length: int
3502 the number of bytes of the mapped virtual range
3503 data: boolean
3505 reading the image will actually read data from a file (in par‐
3506 ticular, if offset is present this means that the sectors are
3507 not simply preallocated, but contain actual data in raw format)
3508 zero: boolean
3510 whether the virtual blocks read as zeroes
3511 depth: int
3513 number of layers (0 = top image, 1 = top image's backing file,
3514 ..., n - 1 = bottom image (where n is the number of images in
3515 the chain)) before reaching one for which the range is allocated
3516 present: boolean
3518 true if this layer provides the data, false if adding a backing
3519 layer could impact this region (since 6.1)
3520 offset: int (optional)
3522 if present, the image file stores the data for this range in raw
3523 format at the given (host) offset
3524 filename: string (optional)
3526 filename that is referred to by offset
3527 Since
3529 2.6
3530 BlockdevCacheInfo (Object)
3532 Cache mode information for a block device
3533 Members
3535 writeback: boolean
3536 true if writeback mode is enabled
3537 direct: boolean
3539 true if the host page cache is bypassed (O_DIRECT)
3540 no-flush: boolean
3542 true if flush requests are ignored for the device
3543 Since
3545 2.3
3546 BlockDeviceInfo (Object)
3548 Information about the backing device for a block device.
3549 Members
3551 file: string
3552 the filename of the backing device
3553 node-name: string (optional)
3555 the name of the block driver node (Since 2.0)
3556 ro: boolean
3558 true if the backing device was open read-only
3559 drv: string
3561 the name of the block format used to open the backing device. As
3562 of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
3563 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
3564 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2',
3565 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added,
3566 'cow' dropped 2.3: 'host_floppy' deprecated 2.5: 'host_floppy'
3567 dropped 2.6: 'luks' added 2.8: 'replication' added, 'tftp'
3568 dropped 2.9: 'archipelago' dropped
3569 backing_file: string (optional)
3571 the name of the backing file (for copy-on-write)
3572 backing_file_depth: int
3574 number of files in the backing file chain (since: 1.2)
3575 encrypted: boolean
3577 true if the backing device is encrypted
3578 detect_zeroes: BlockdevDetectZeroesOptions
3580 detect and optimize zero writes (Since 2.1)
3581 bps: int
3583 total throughput limit in bytes per second is specified
3584 bps_rd: int
3586 read throughput limit in bytes per second is specified
3587 bps_wr: int
3589 write throughput limit in bytes per second is specified
3590 iops: int
3592 total I/O operations per second is specified
3593 iops_rd: int
3595 read I/O operations per second is specified
3596 iops_wr: int
3598 write I/O operations per second is specified
3599 image: ImageInfo
3601 the info of image used (since: 1.6)
3602 bps_max: int (optional)
3604 total throughput limit during bursts,
3606 in bytes (Since 1.7)
3607 bps_rd_max: int (optional)
3609 read throughput limit during bursts,
3611 in bytes (Since 1.7)
3612 bps_wr_max: int (optional)
3614 write throughput limit during bursts,
3616 in bytes (Since 1.7)
3617 iops_max: int (optional)
3619 total I/O operations per second during bursts,
3621 in bytes (Since 1.7)
3622 iops_rd_max: int (optional)
3624 read I/O operations per second during bursts,
3626 in bytes (Since 1.7)
3627 iops_wr_max: int (optional)
3629 write I/O operations per second during bursts,
3631 in bytes (Since 1.7)
3632 bps_max_length: int (optional)
3634 maximum length of the bps_max burst
3636 period, in seconds. (Since 2.6)
3637 bps_rd_max_length: int (optional)
3639 maximum length of the bps_rd_max
3641 burst period, in seconds. (Since 2.6)
3642 bps_wr_max_length: int (optional)
3644 maximum length of the bps_wr_max
3646 burst period, in seconds. (Since 2.6)
3647 iops_max_length: int (optional)
3649 maximum length of the iops burst
3651 period, in seconds. (Since 2.6)
3652 iops_rd_max_length: int (optional)
3654 maximum length of the iops_rd_max
3656 burst period, in seconds. (Since 2.6)
3657 iops_wr_max_length: int (optional)
3659 maximum length of the iops_wr_max
3661 burst period, in seconds. (Since 2.6)
3662 iops_size: int (optional)
3664 an I/O size in bytes (Since 1.7)
3665 group: string (optional)
3667 throttle group name (Since 2.4)
3668 cache: BlockdevCacheInfo
3670 the cache mode used for the block device (since: 2.3)
3671 write_threshold: int
3673 configured write threshold for the device. 0 if disabled.
3674 (Since 2.3)
3675 dirty-bitmaps: array of BlockDirtyInfo (optional)
3677 dirty bitmaps information (only present if node has one or more
3678 dirty bitmaps) (Since 4.2)
3679 Since
3681 0.14
3682 BlockDeviceIoStatus (Enum)
3684 An enumeration of block device I/O status.
3685 Values
3687 ok The last I/O operation has succeeded
3688 failed The last I/O operation has failed
3690 nospace
3692 The last I/O operation has failed due to a no-space condition
3693 Since
3695 1.0
3696 BlockDirtyInfo (Object)
3698 Block dirty bitmap information.
3699 Members
3701 name: string (optional)
3702 the name of the dirty bitmap (Since 2.4)
3703 count: int
3705 number of dirty bytes according to the dirty bitmap
3706 granularity: int
3708 granularity of the dirty bitmap in bytes (since 1.4)
3709 recording: boolean
3711 true if the bitmap is recording new writes from the guest. Re‐
3712 places active and disabled statuses. (since 4.0)
3713 busy: boolean
3715 true if the bitmap is in-use by some operation (NBD or jobs) and
3716 cannot be modified via QMP or used by another operation. Re‐
3717 places locked and frozen statuses. (since 4.0)
3718 persistent: boolean
3720 true if the bitmap was stored on disk, is scheduled to be stored
3721 on disk, or both. (since 4.0)
3722 inconsistent: boolean (optional)
3724 true if this is a persistent bitmap that was improperly stored.
3725 Implies persistent to be true; recording and busy to be false.
3726 This bitmap cannot be used. To remove it, use block-dirty-bit‐
3727 map-remove. (Since 4.0)
3728 Since
3730 1.3
3731 Qcow2BitmapInfoFlags (Enum)
3733 An enumeration of flags that a bitmap can report to the user.
3734 Values
3736 in-use This flag is set by any process actively modifying the qcow2
3737 file, and cleared when the updated bitmap is flushed to the
3738 qcow2 image. The presence of this flag in an offline image
3739 means that the bitmap was not saved correctly after its last us‐
3740 age, and may contain inconsistent data.
3741 auto The bitmap must reflect all changes of the virtual disk by any
3743 application that would write to this qcow2 file.
3744 Since
3746 4.0
3747 Qcow2BitmapInfo (Object)
3749 Qcow2 bitmap information.
3750 Members
3752 name: string
3753 the name of the bitmap
3754 granularity: int
3756 granularity of the bitmap in bytes
3757 flags: array of Qcow2BitmapInfoFlags
3759 flags of the bitmap
3760 Since
3762 4.0
3763 BlockLatencyHistogramInfo (Object)
3765 Block latency histogram.
3766 Members
3768 boundaries: array of int
3769 list of interval boundary values in nanoseconds, all greater
3770 than zero and in ascending order. For example, the list [10,
3771 50, 100] produces the following histogram intervals: [0, 10),
3772 [10, 50), [50, 100), [100, +inf).
3773 bins: array of int
3775 list of io request counts corresponding to histogram intervals.
3776 len(bins) = len(boundaries) + 1 For the example above, bins may
3777 be something like [3, 1, 5, 2], and corresponding histogram
3778 looks like:
3779 5| *
3781 4| *
3782 3| * *
3783 2| * * *
3784 1| * * * *
3785 +------------------
3786 10 50 100
3787 Since
3789 4.0
3790 BlockInfo (Object)
3792 Block device information. This structure describes a virtual device
3793 and the backing device associated with it.
3794 Members
3796 device: string
3797 The device name associated with the virtual device.
3798 qdev: string (optional)
3800 The qdev ID, or if no ID is assigned, the QOM path of the block
3801 device. (since 2.10)
3802 type: string
3804 This field is returned only for compatibility reasons, it should
3805 not be used (always returns 'unknown')
3806 removable: boolean
3808 True if the device supports removable media.
3809 locked: boolean
3811 True if the guest has locked this device from having its media
3812 removed
3813 tray_open: boolean (optional)
3815 True if the device's tray is open (only present if it has a
3816 tray)
3817 io-status: BlockDeviceIoStatus (optional)
3819 BlockDeviceIoStatus. Only present if the device supports it and
3820 the VM is configured to stop on errors (supported device models:
3821 virtio-blk, IDE, SCSI except scsi-generic)
3822 inserted: BlockDeviceInfo (optional)
3824 BlockDeviceInfo describing the device if media is present
3825 Since
3827 0.14
3828 BlockMeasureInfo (Object)
3830 Image file size calculation information. This structure describes the
3831 size requirements for creating a new image file.
3832 The size requirements depend on the new image file format. File size
3834 always equals virtual disk size for the 'raw' format, even for sparse
3835 POSIX files. Compact formats such as 'qcow2' represent unallocated and
3836 zero regions efficiently so file size may be smaller than virtual disk
3837 size.
3838 The values are upper bounds that are guaranteed to fit the new image
3840 file. Subsequent modification, such as internal snapshot or further
3841 bitmap creation, may require additional space and is not covered here.
3842 Members
3844 required: int
3845 Size required for a new image file, in bytes, when copying just
3846 allocated guest-visible contents.
3847 fully-allocated: int
3849 Image file size, in bytes, once data has been written to all
3850 sectors, when copying just guest-visible contents.
3851 bitmaps: int (optional)
3853 Additional size required if all the top-level bitmap metadata in
3854 the source image were to be copied to the destination, present
3855 only when source and destination both support persistent bit‐
3856 maps. (since 5.1)
3857 Since
3859 2.10
3860 query-block (Command)
3862 Get a list of BlockInfo for all virtual block devices.
3863 Returns
3865 a list of BlockInfo describing each virtual block device. Filter nodes
3866 that were created implicitly are skipped over.
3867 Since
3869 0.14
3870 Example
3872 -> { "execute": "query-block" }
3873 <- {
3874 "return":[
3875 {
3876 "io-status": "ok",
3877 "device":"ide0-hd0",
3878 "locked":false,
3879 "removable":false,
3880 "inserted":{
3881 "ro":false,
3882 "drv":"qcow2",
3883 "encrypted":false,
3884 "file":"disks/test.qcow2",
3885 "backing_file_depth":1,
3886 "bps":1000000,
3887 "bps_rd":0,
3888 "bps_wr":0,
3889 "iops":1000000,
3890 "iops_rd":0,
3891 "iops_wr":0,
3892 "bps_max": 8000000,
3893 "bps_rd_max": 0,
3894 "bps_wr_max": 0,
3895 "iops_max": 0,
3896 "iops_rd_max": 0,
3897 "iops_wr_max": 0,
3898 "iops_size": 0,
3899 "detect_zeroes": "on",
3900 "write_threshold": 0,
3901 "image":{
3902 "filename":"disks/test.qcow2",
3903 "format":"qcow2",
3904 "virtual-size":2048000,
3905 "backing_file":"base.qcow2",
3906 "full-backing-filename":"disks/base.qcow2",
3907 "backing-filename-format":"qcow2",
3908 "snapshots":[
3909 {
3910 "id": "1",
3911 "name": "snapshot1",
3912 "vm-state-size": 0,
3913 "date-sec": 10000200,
3914 "date-nsec": 12,
3915 "vm-clock-sec": 206,
3916 "vm-clock-nsec": 30
3917 }
3918 ],
3919 "backing-image":{
3920 "filename":"disks/base.qcow2",
3921 "format":"qcow2",
3922 "virtual-size":2048000
3923 }
3924 }
3925 },
3926 "qdev": "ide_disk",
3927 "type":"unknown"
3928 },
3929 {
3930 "io-status": "ok",
3931 "device":"ide1-cd0",
3932 "locked":false,
3933 "removable":true,
3934 "qdev": "/machine/unattached/device[23]",
3935 "tray_open": false,
3936 "type":"unknown"
3937 },
3938 {
3939 "device":"floppy0",
3940 "locked":false,
3941 "removable":true,
3942 "qdev": "/machine/unattached/device[20]",
3943 "type":"unknown"
3944 },
3945 {
3946 "device":"sd0",
3947 "locked":false,
3948 "removable":true,
3949 "type":"unknown"
3950 }
3951 ]
3952 }
3953 BlockDeviceTimedStats (Object)
3955 Statistics of a block device during a given interval of time.
3956 Members
3958 interval_length: int
3959 Interval used for calculating the statistics, in seconds.
3960 min_rd_latency_ns: int
3962 Minimum latency of read operations in the defined interval, in
3963 nanoseconds.
3964 min_wr_latency_ns: int
3966 Minimum latency of write operations in the defined interval, in
3967 nanoseconds.
3968 min_flush_latency_ns: int
3970 Minimum latency of flush operations in the defined interval, in
3971 nanoseconds.
3972 max_rd_latency_ns: int
3974 Maximum latency of read operations in the defined interval, in
3975 nanoseconds.
3976 max_wr_latency_ns: int
3978 Maximum latency of write operations in the defined interval, in
3979 nanoseconds.
3980 max_flush_latency_ns: int
3982 Maximum latency of flush operations in the defined interval, in
3983 nanoseconds.
3984 avg_rd_latency_ns: int
3986 Average latency of read operations in the defined interval, in
3987 nanoseconds.
3988 avg_wr_latency_ns: int
3990 Average latency of write operations in the defined interval, in
3991 nanoseconds.
3992 avg_flush_latency_ns: int
3994 Average latency of flush operations in the defined interval, in
3995 nanoseconds.
3996 avg_rd_queue_depth: number
3998 Average number of pending read operations in the defined inter‐
3999 val.
4000 avg_wr_queue_depth: number
4002 Average number of pending write operations in the defined inter‐
4003 val.
4004 Since
4006 2.5
4007 BlockDeviceStats (Object)
4009 Statistics of a virtual block device or a block backing device.
4010 Members
4012 rd_bytes: int
4013 The number of bytes read by the device.
4014 wr_bytes: int
4016 The number of bytes written by the device.
4017 unmap_bytes: int
4019 The number of bytes unmapped by the device (Since 4.2)
4020 rd_operations: int
4022 The number of read operations performed by the device.
4023 wr_operations: int
4025 The number of write operations performed by the device.
4026 flush_operations: int
4028 The number of cache flush operations performed by the device
4029 (since 0.15)
4030 unmap_operations: int
4032 The number of unmap operations performed by the device (Since
4033 4.2)
4034 rd_total_time_ns: int
4036 Total time spent on reads in nanoseconds (since 0.15).
4037 wr_total_time_ns: int
4039 Total time spent on writes in nanoseconds (since 0.15).
4040 flush_total_time_ns: int
4042 Total time spent on cache flushes in nanoseconds (since 0.15).
4043 unmap_total_time_ns: int
4045 Total time spent on unmap operations in nanoseconds (Since 4.2)
4046 wr_highest_offset: int
4048 The offset after the greatest byte written to the device. The
4049 intended use of this information is for growable sparse files
4050 (like qcow2) that are used on top of a physical device.
4051 rd_merged: int
4053 Number of read requests that have been merged into another re‐
4054 quest (Since 2.3).
4055 wr_merged: int
4057 Number of write requests that have been merged into another re‐
4058 quest (Since 2.3).
4059 unmap_merged: int
4061 Number of unmap requests that have been merged into another re‐
4062 quest (Since 4.2)
4063 idle_time_ns: int (optional)
4065 Time since the last I/O operation, in nanoseconds. If the field
4066 is absent it means that there haven't been any operations yet
4067 (Since 2.5).
4068 failed_rd_operations: int
4070 The number of failed read operations performed by the device
4071 (Since 2.5)
4072 failed_wr_operations: int
4074 The number of failed write operations performed by the device
4075 (Since 2.5)
4076 failed_flush_operations: int
4078 The number of failed flush operations performed by the device
4079 (Since 2.5)
4080 failed_unmap_operations: int
4082 The number of failed unmap operations performed by the device
4083 (Since 4.2)
4084 invalid_rd_operations: int
4086 The number of invalid read operations
4088 performed by the device (Since 2.5)
4089 invalid_wr_operations: int
4091 The number of invalid write operations performed by the device
4092 (Since 2.5)
4093 invalid_flush_operations: int
4095 The number of invalid flush operations performed by the device
4096 (Since 2.5)
4097 invalid_unmap_operations: int
4099 The number of invalid unmap operations performed by the device
4100 (Since 4.2)
4101 account_invalid: boolean
4103 Whether invalid operations are included in the last access sta‐
4104 tistics (Since 2.5)
4105 account_failed: boolean
4107 Whether failed operations are included in the latency and last
4108 access statistics (Since 2.5)
4109 timed_stats: array of BlockDeviceTimedStats
4111 Statistics specific to the set of previously defined intervals
4112 of time (Since 2.5)
4113 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
4115 BlockLatencyHistogramInfo. (Since 4.0)
4116 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
4118 BlockLatencyHistogramInfo. (Since 4.0)
4119 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
4121 BlockLatencyHistogramInfo. (Since 4.0)
4122 Since
4124 0.14
4125 BlockStatsSpecificFile (Object)
4127 File driver statistics
4128 Members
4130 discard-nb-ok: int
4131 The number of successful discard operations performed by the
4132 driver.
4133 discard-nb-failed: int
4135 The number of failed discard operations performed by the driver.
4136 discard-bytes-ok: int
4138 The number of bytes discarded by the driver.
4139 Since
4141 4.2
4142 BlockStatsSpecificNvme (Object)
4144 NVMe driver statistics
4145 Members
4147 completion-errors: int
4148 The number of completion errors.
4149 aligned-accesses: int
4151 The number of aligned accesses performed by the driver.
4152 unaligned-accesses: int
4154 The number of unaligned accesses performed by the driver.
4155 Since
4157 5.2
4158 BlockStatsSpecific (Object)
4160 Block driver specific statistics
4161 Members
4163 driver: BlockdevDriver
4164 Not documented
4165 The members of BlockStatsSpecificFile when driver is "file"
4167 The members of BlockStatsSpecificFile when driver is "host_device" (If:
4169 HAVE_HOST_BLOCK_DEVICE)
4170 The members of BlockStatsSpecificNvme when driver is "nvme"
4172 Since
4174 4.2
4175 BlockStats (Object)
4177 Statistics of a virtual block device or a block backing device.
4178 Members
4180 device: string (optional)
4181 If the stats are for a virtual block device, the name corre‐
4182 sponding to the virtual block device.
4183 node-name: string (optional)
4185 The node name of the device. (Since 2.3)
4186 qdev: string (optional)
4188 The qdev ID, or if no ID is assigned, the QOM path of the block
4189 device. (since 3.0)
4190 stats: BlockDeviceStats
4192 A BlockDeviceStats for the device.
4193 driver-specific: BlockStatsSpecific (optional)
4195 Optional driver-specific stats. (Since 4.2)
4196 parent: BlockStats (optional)
4198 This describes the file block device if it has one. Contains
4199 recursively the statistics of the underlying protocol (e.g. the
4200 host file for a qcow2 image). If there is no underlying proto‐
4201 col, this field is omitted
4202 backing: BlockStats (optional)
4204 This describes the backing block device if it has one. (Since
4205 2.0)
4206 Since
4208 0.14
4209 query-blockstats (Command)
4211 Query the BlockStats for all virtual block devices.
4212 Arguments
4214 query-nodes: boolean (optional)
4215 If true, the command will query all the block nodes that have a
4216 node name, in a list which will include "parent" information,
4217 but not "backing". If false or omitted, the behavior is as be‐
4218 fore - query all the device backends, recursively including
4219 their "parent" and "backing". Filter nodes that were created im‐
4220 plicitly are skipped over in this mode. (Since 2.3)
4221 Returns
4223 A list of BlockStats for each virtual block devices.
4224 Since
4226 0.14
4227 Example
4229 -> { "execute": "query-blockstats" }
4230 <- {
4231 "return":[
4232 {
4233 "device":"ide0-hd0",
4234 "parent":{
4235 "stats":{
4236 "wr_highest_offset":3686448128,
4237 "wr_bytes":9786368,
4238 "wr_operations":751,
4239 "rd_bytes":122567168,
4240 "rd_operations":36772
4241 "wr_total_times_ns":313253456
4242 "rd_total_times_ns":3465673657
4243 "flush_total_times_ns":49653
4244 "flush_operations":61,
4245 "rd_merged":0,
4246 "wr_merged":0,
4247 "idle_time_ns":2953431879,
4248 "account_invalid":true,
4249 "account_failed":false
4250 }
4251 },
4252 "stats":{
4253 "wr_highest_offset":2821110784,
4254 "wr_bytes":9786368,
4255 "wr_operations":692,
4256 "rd_bytes":122739200,
4257 "rd_operations":36604
4258 "flush_operations":51,
4259 "wr_total_times_ns":313253456
4260 "rd_total_times_ns":3465673657
4261 "flush_total_times_ns":49653,
4262 "rd_merged":0,
4263 "wr_merged":0,
4264 "idle_time_ns":2953431879,
4265 "account_invalid":true,
4266 "account_failed":false
4267 },
4268 "qdev": "/machine/unattached/device[23]"
4269 },
4270 {
4271 "device":"ide1-cd0",
4272 "stats":{
4273 "wr_highest_offset":0,
4274 "wr_bytes":0,
4275 "wr_operations":0,
4276 "rd_bytes":0,
4277 "rd_operations":0
4278 "flush_operations":0,
4279 "wr_total_times_ns":0
4280 "rd_total_times_ns":0
4281 "flush_total_times_ns":0,
4282 "rd_merged":0,
4283 "wr_merged":0,
4284 "account_invalid":false,
4285 "account_failed":false
4286 },
4287 "qdev": "/machine/unattached/device[24]"
4288 },
4289 {
4290 "device":"floppy0",
4291 "stats":{
4292 "wr_highest_offset":0,
4293 "wr_bytes":0,
4294 "wr_operations":0,
4295 "rd_bytes":0,
4296 "rd_operations":0
4297 "flush_operations":0,
4298 "wr_total_times_ns":0
4299 "rd_total_times_ns":0
4300 "flush_total_times_ns":0,
4301 "rd_merged":0,
4302 "wr_merged":0,
4303 "account_invalid":false,
4304 "account_failed":false
4305 },
4306 "qdev": "/machine/unattached/device[16]"
4307 },
4308 {
4309 "device":"sd0",
4310 "stats":{
4311 "wr_highest_offset":0,
4312 "wr_bytes":0,
4313 "wr_operations":0,
4314 "rd_bytes":0,
4315 "rd_operations":0
4316 "flush_operations":0,
4317 "wr_total_times_ns":0
4318 "rd_total_times_ns":0
4319 "flush_total_times_ns":0,
4320 "rd_merged":0,
4321 "wr_merged":0,
4322 "account_invalid":false,
4323 "account_failed":false
4324 }
4325 }
4326 ]
4327 }
4328 BlockdevOnError (Enum)
4330 An enumeration of possible behaviors for errors on I/O operations. The
4331 exact meaning depends on whether the I/O was initiated by a guest or by
4332 a block job
4333 Values
4335 report for guest operations, report the error to the guest; for jobs,
4336 cancel the job
4337 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
4339 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
4340 the failing request later and may still complete successfully.
4341 The stream block job continues to stream and will complete with
4342 an error.
4343 enospc same as stop on ENOSPC, same as report otherwise.
4345 stop for guest operations, stop the virtual machine; for jobs, pause
4347 the job
4348 auto inherit the error handling policy of the backend (since: 2.7)
4350 Since
4352 1.3
4353 MirrorSyncMode (Enum)
4355 An enumeration of possible behaviors for the initial synchronization
4356 phase of storage mirroring.
4357 Values
4359 top copies data in the topmost image to the destination
4360 full copies data from all images to the destination
4362 none only copy data written from now on
4364 incremental
4366 only copy data described by the dirty bitmap. (since: 2.4)
4367 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
4369 havior on completion is determined by the BitmapSyncMode.
4370 Since
4372 1.3
4373 BitmapSyncMode (Enum)
4375 An enumeration of possible behaviors for the synchronization of a bit‐
4376 map when used for data copy operations.
4377 Values
4379 on-success
4380 The bitmap is only synced when the operation is successful.
4381 This is the behavior always used for 'INCREMENTAL' backups.
4382 never The bitmap is never synchronized with the operation, and is
4384 treated solely as a read-only manifest of blocks to copy.
4385 always The bitmap is always synchronized with the operation, regardless
4387 of whether or not the operation was successful.
4388 Since
4390 4.2
4391 MirrorCopyMode (Enum)
4393 An enumeration whose values tell the mirror block job when to trigger
4394 writes to the target.
4395 Values
4397 background
4398 copy data in background only.
4399 write-blocking
4401 when data is written to the source, write it (synchronously) to
4402 the target as well. In addition, data is copied in background
4403 just like in background mode.
4404 Since
4406 3.0
4407 BlockJobInfo (Object)
4409 Information about a long-running block device operation.
4410 Members
4412 type: string
4413 the job type ('stream' for image streaming)
4414 device: string
4416 The job identifier. Originally the device name but other values
4417 are allowed since QEMU 2.7
4418 len: int
4420 Estimated offset value at the completion of the job. This value
4421 can arbitrarily change while the job is running, in both direc‐
4422 tions.
4423 offset: int
4425 Progress made until now. The unit is arbitrary and the value can
4426 only meaningfully be used for the ratio of offset to len. The
4427 value is monotonically increasing.
4428 busy: boolean
4430 false if the job is known to be in a quiescent state, with no
4431 pending I/O. Since 1.3.
4432 paused: boolean
4434 whether the job is paused or, if busy is true, will pause itself
4435 as soon as possible. Since 1.3.
4436 speed: int
4438 the rate limit, bytes per second
4439 io-status: BlockDeviceIoStatus
4441 the status of the job (since 1.3)
4442 ready: boolean
4444 true if the job may be completed (since 2.2)
4445 status: JobStatus
4447 Current job state/status (since 2.12)
4448 auto-finalize: boolean
4450 Job will finalize itself when PENDING, moving to the CONCLUDED
4451 state. (since 2.12)
4452 auto-dismiss: boolean
4454 Job will dismiss itself when CONCLUDED, moving to the NULL state
4455 and disappearing from the query list. (since 2.12)
4456 error: string (optional)
4458 Error information if the job did not complete successfully. Not
4459 set if the job completed successfully. (since 2.12.1)
4460 Since
4462 1.1
4463 query-block-jobs (Command)
4465 Return information about long-running block device operations.
4466 Returns
4468 a list of BlockJobInfo for each active block job
4469 Since
4471 1.1
4472 block_resize (Command)
4474 Resize a block image while a guest is running.
4475 Either device or node-name must be set but not both.
4477 Arguments
4479 device: string (optional)
4480 the name of the device to get the image resized
4481 node-name: string (optional)
4483 graph node name to get the image resized (Since 2.0)
4484 size: int
4486 new image size in bytes
4487 Returns
4489 • nothing on success
4490 • If device is not a valid block device, DeviceNotFound
4492 Since
4494 0.14
4495 Example
4497 -> { "execute": "block_resize",
4498 "arguments": { "device": "scratch", "size": 1073741824 } }
4499 <- { "return": {} }
4500 NewImageMode (Enum)
4502 An enumeration that tells QEMU how to set the backing file path in a
4503 new image file.
4504 Values
4506 existing
4507 QEMU should look for an existing image file.
4508 absolute-paths
4510 QEMU should create a new image with absolute paths for the back‐
4511 ing file. If there is no backing file available, the new image
4512 will not be backed either.
4513 Since
4515 1.1
4516 BlockdevSnapshotSync (Object)
4518 Either device or node-name must be set but not both.
4519 Members
4521 device: string (optional)
4522 the name of the device to take a snapshot of.
4523 node-name: string (optional)
4525 graph node name to generate the snapshot from (Since 2.0)
4526 snapshot-file: string
4528 the target of the new overlay image. If the file exists, or if
4529 it is a device, the overlay will be created in the existing
4530 file/device. Otherwise, a new file will be created.
4531 snapshot-node-name: string (optional)
4533 the graph node name of the new image (Since 2.0)
4534 format: string (optional)
4536 the format of the overlay image, default is 'qcow2'.
4537 mode: NewImageMode (optional)
4539 whether and how QEMU should create a new image, default is 'ab‐
4540 solute-paths'.
4541 BlockdevSnapshot (Object)
4543 Members
4544 node: string
4545 device or node name that will have a snapshot taken.
4546 overlay: string
4548 reference to the existing block device that will become the
4549 overlay of node, as part of taking the snapshot. It must not
4550 have a current backing file (this can be achieved by passing
4551 "backing": null to blockdev-add).
4552 Since
4554 2.5
4555 BackupPerf (Object)
4557 Optional parameters for backup. These parameters don't affect function‐
4558 ality, but may significantly affect performance.
4559 Members
4561 use-copy-range: boolean (optional)
4562 Use copy offloading. Default false.
4563 max-workers: int (optional)
4565 Maximum number of parallel requests for the sustained background
4566 copying process. Doesn't influence copy-before-write operations.
4567 Default 64.
4568 max-chunk: int (optional)
4570 Maximum request length for the sustained background copying
4571 process. Doesn't influence copy-before-write operations. 0
4572 means unlimited. If max-chunk is non-zero then it should not be
4573 less than job cluster size which is calculated as maximum of
4574 target image cluster size and 64k. Default 0.
4575 Since
4577 6.0
4578 BackupCommon (Object)
4580 Members
4581 job-id: string (optional)
4582 identifier for the newly-created block job. If omitted, the de‐
4583 vice name will be used. (Since 2.7)
4584 device: string
4586 the device name or node-name of a root node which should be
4587 copied.
4588 sync: MirrorSyncMode
4590 what parts of the disk image should be copied to the destination
4591 (all the disk, only the sectors allocated in the topmost image,
4592 from a dirty bitmap, or only new I/O).
4593 speed: int (optional)
4595 the maximum speed, in bytes per second. The default is 0, for
4596 unlimited.
4597 bitmap: string (optional)
4599 The name of a dirty bitmap to use. Must be present if sync is
4600 "bitmap" or "incremental". Can be present if sync is "full" or
4601 "top". Must not be present otherwise. (Since 2.4
4602 (drive-backup), 3.1 (blockdev-backup))
4603 bitmap-mode: BitmapSyncMode (optional)
4605 Specifies the type of data the bitmap should contain after the
4606 operation concludes. Must be present if a bitmap was provided,
4607 Must NOT be present otherwise. (Since 4.2)
4608 compress: boolean (optional)
4610 true to compress data, if the target format supports it. (de‐
4611 fault: false) (since 2.8)
4612 on-source-error: BlockdevOnError (optional)
4614 the action to take on an error on the source, default 'report'.
4615 'stop' and 'enospc' can only be used if the block device sup‐
4616 ports io-status (see BlockInfo).
4617 on-target-error: BlockdevOnError (optional)
4619 the action to take on an error on the target, default 'report'
4620 (no limitations, since this applies to a different block device
4621 than device).
4622 auto-finalize: boolean (optional)
4624 When false, this job will wait in a PENDING state after it has
4625 finished its work, waiting for block-job-finalize before making
4626 any block graph changes. When true, this job will automatically
4627 perform its abort or commit actions. Defaults to true. (Since
4628 2.12)
4629 auto-dismiss: boolean (optional)
4631 When false, this job will wait in a CONCLUDED state after it has
4632 completely ceased all work, and awaits block-job-dismiss. When
4633 true, this job will automatically disappear from the query list
4634 without user intervention. Defaults to true. (Since 2.12)
4635 filter-node-name: string (optional)
4637 the node name that should be assigned to the filter driver that
4638 the backup job inserts into the graph above node specified by
4639 drive. If this option is not given, a node name is autogener‐
4640 ated. (Since: 4.2)
4641 x-perf: BackupPerf (optional)
4643 Performance options. (Since 6.0)
4644 Features
4646 unstable
4647 Member x-perf is experimental.
4648 Note
4650 on-source-error and on-target-error only affect background I/O. If an
4651 error occurs during a guest write request, the device's rerror/werror
4652 actions will be used.
4653 Since
4655 4.2
4656 DriveBackup (Object)
4658 Members
4659 target: string
4660 the target of the new image. If the file exists, or if it is a
4661 device, the existing file/device will be used as the new desti‐
4662 nation. If it does not exist, a new file will be created.
4663 format: string (optional)
4665 the format of the new destination, default is to probe if mode
4666 is 'existing', else the format of the source
4667 mode: NewImageMode (optional)
4669 whether and how QEMU should create a new image, default is 'ab‐
4670 solute-paths'.
4671 The members of BackupCommon
4673 Since
4675 1.6
4676 BlockdevBackup (Object)
4678 Members
4679 target: string
4680 the device name or node-name of the backup target node.
4681 The members of BackupCommon
4683 Since
4685 2.3
4686 blockdev-snapshot-sync (Command)
4688 Takes a synchronous snapshot of a block device.
4689 For the arguments, see the documentation of BlockdevSnapshotSync.
4691 Returns
4693 • nothing on success
4694 • If device is not a valid block device, DeviceNotFound
4696 Since
4698 0.14
4699 Example
4701 -> { "execute": "blockdev-snapshot-sync",
4702 "arguments": { "device": "ide-hd0",
4703 "snapshot-file":
4704 "/some/place/my-image",
4705 "format": "qcow2" } }
4706 <- { "return": {} }
4707 blockdev-snapshot (Command)
4709 Takes a snapshot of a block device.
4710 Take a snapshot, by installing 'node' as the backing image of 'over‐
4712 lay'. Additionally, if 'node' is associated with a block device, the
4713 block device changes to using 'overlay' as its new active image.
4714 For the arguments, see the documentation of BlockdevSnapshot.
4716 Features
4718 allow-write-only-overlay
4719 If present, the check whether this operation is safe was relaxed
4720 so that it can be used to change backing file of a destination
4721 of a blockdev-mirror. (since 5.0)
4722 Since
4724 2.5
4725 Example
4727 -> { "execute": "blockdev-add",
4728 "arguments": { "driver": "qcow2",
4729 "node-name": "node1534",
4730 "file": { "driver": "file",
4731 "filename": "hd1.qcow2" },
4732 "backing": null } }
4733 <- { "return": {} }
4735 -> { "execute": "blockdev-snapshot",
4737 "arguments": { "node": "ide-hd0",
4738 "overlay": "node1534" } }
4739 <- { "return": {} }
4740 change-backing-file (Command)
4742 Change the backing file in the image file metadata. This does not
4743 cause QEMU to reopen the image file to reparse the backing filename (it
4744 may, however, perform a reopen to change permissions from r/o -> r/w ->
4745 r/o, if needed). The new backing file string is written into the image
4746 file metadata, and the QEMU internal strings are updated.
4747 Arguments
4749 image-node-name: string
4750 The name of the block driver state node of the image to modify.
4751 The "device" argument is used to verify "image-node-name" is in
4752 the chain described by "device".
4753 device: string
4755 The device name or node-name of the root node that owns im‐
4756 age-node-name.
4757 backing-file: string
4759 The string to write as the backing file. This string is not
4760 validated, so care should be taken when specifying the string or
4761 the image chain may not be able to be reopened again.
4762 Returns
4764 • Nothing on success
4765 • If "device" does not exist or cannot be determined, DeviceNotFound
4767 Since
4769 2.1
4770 block-commit (Command)
4772 Live commit of data from overlay image nodes into backing nodes - i.e.,
4773 writes data between 'top' and 'base' into 'base'.
4774 If top == base, that is an error. If top has no overlays on top of it,
4776 or if it is in use by a writer, the job will not be completed by it‐
4777 self. The user needs to complete the job with the block-job-complete
4778 command after getting the ready event. (Since 2.0)
4779 If the base image is smaller than top, then the base image will be re‐
4781 sized to be the same size as top. If top is smaller than the base im‐
4782 age, the base will not be truncated. If you want the base image size
4783 to match the size of the smaller top, you can safely truncate it your‐
4784 self once the commit operation successfully completes.
4785 Arguments
4787 job-id: string (optional)
4788 identifier for the newly-created block job. If omitted, the de‐
4789 vice name will be used. (Since 2.7)
4790 device: string
4792 the device name or node-name of a root node
4793 base-node: string (optional)
4795 The node name of the backing image to write data into. If not
4796 specified, this is the deepest backing image. (since: 3.1)
4797 base: string (optional)
4799 Same as base-node, except that it is a file name rather than a
4800 node name. This must be the exact filename string that was used
4801 to open the node; other strings, even if addressing the same
4802 file, are not accepted
4803 top-node: string (optional)
4805 The node name of the backing image within the image chain which
4806 contains the topmost data to be committed down. If not speci‐
4807 fied, this is the active layer. (since: 3.1)
4808 top: string (optional)
4810 Same as top-node, except that it is a file name rather than a
4811 node name. This must be the exact filename string that was used
4812 to open the node; other strings, even if addressing the same
4813 file, are not accepted
4814 backing-file: string (optional)
4816 The backing file string to write into the overlay image of
4817 'top'. If 'top' does not have an overlay image, or if 'top' is
4818 in use by a writer, specifying a backing file string is an er‐
4819 ror.
4820 This filename is not validated. If a pathname string is such
4822 that it cannot be resolved by QEMU, that means that subsequent
4823 QMP or HMP commands must use node-names for the image in ques‐
4824 tion, as filename lookup methods will fail.
4825 If not specified, QEMU will automatically determine the backing
4827 file string to use, or error out if there is no obvious choice.
4828 Care should be taken when specifying the string, to specify a
4829 valid filename or protocol. (Since 2.1)
4830 speed: int (optional)
4832 the maximum speed, in bytes per second
4833 on-error: BlockdevOnError (optional)
4835 the action to take on an error. 'ignore' means that the request
4836 should be retried. (default: report; Since: 5.0)
4837 filter-node-name: string (optional)
4839 the node name that should be assigned to the filter driver that
4840 the commit job inserts into the graph above top. If this option
4841 is not given, a node name is autogenerated. (Since: 2.9)
4842 auto-finalize: boolean (optional)
4844 When false, this job will wait in a PENDING state after it has
4845 finished its work, waiting for block-job-finalize before making
4846 any block graph changes. When true, this job will automatically
4847 perform its abort or commit actions. Defaults to true. (Since
4848 3.1)
4849 auto-dismiss: boolean (optional)
4851 When false, this job will wait in a CONCLUDED state after it has
4852 completely ceased all work, and awaits block-job-dismiss. When
4853 true, this job will automatically disappear from the query list
4854 without user intervention. Defaults to true. (Since 3.1)
4855 Features
4857 deprecated
4858 Members base and top are deprecated. Use base-node and top-node
4859 instead.
4860 Returns
4862 • Nothing on success
4863 • If device does not exist, DeviceNotFound
4865 • Any other error returns a GenericError.
4867 Since
4869 1.3
4870 Example
4872 -> { "execute": "block-commit",
4873 "arguments": { "device": "virtio0",
4874 "top": "/tmp/snap1.qcow2" } }
4875 <- { "return": {} }
4876 drive-backup (Command)
4878 Start a point-in-time copy of a block device to a new destination. The
4879 status of ongoing drive-backup operations can be checked with
4880 query-block-jobs where the BlockJobInfo.type field has the value
4881 'backup'. The operation can be stopped before it has completed using
4882 the block-job-cancel command.
4883 Arguments
4885 The members of DriveBackup
4886 Features
4888 deprecated
4889 This command is deprecated. Use blockdev-backup instead.
4890 Returns
4892 • nothing on success
4893 • If device is not a valid block device, GenericError
4895 Since
4897 1.6
4898 Example
4900 -> { "execute": "drive-backup",
4901 "arguments": { "device": "drive0",
4902 "sync": "full",
4903 "target": "backup.img" } }
4904 <- { "return": {} }
4905 blockdev-backup (Command)
4907 Start a point-in-time copy of a block device to a new destination. The
4908 status of ongoing blockdev-backup operations can be checked with
4909 query-block-jobs where the BlockJobInfo.type field has the value
4910 'backup'. The operation can be stopped before it has completed using
4911 the block-job-cancel command.
4912 Arguments
4914 The members of BlockdevBackup
4915 Returns
4917 • nothing on success
4918 • If device is not a valid block device, DeviceNotFound
4920 Since
4922 2.3
4923 Example
4925 -> { "execute": "blockdev-backup",
4926 "arguments": { "device": "src-id",
4927 "sync": "full",
4928 "target": "tgt-id" } }
4929 <- { "return": {} }
4930 query-named-block-nodes (Command)
4932 Get the named block driver list
4933 Arguments
4935 flat: boolean (optional)
4936 Omit the nested data about backing image ("backing-image" key)
4937 if true. Default is false (Since 5.0)
4938 Returns
4940 the list of BlockDeviceInfo
4941 Since
4943 2.0
4944 Example
4946 -> { "execute": "query-named-block-nodes" }
4947 <- { "return": [ { "ro":false,
4948 "drv":"qcow2",
4949 "encrypted":false,
4950 "file":"disks/test.qcow2",
4951 "node-name": "my-node",
4952 "backing_file_depth":1,
4953 "detect_zeroes":"off",
4954 "bps":1000000,
4955 "bps_rd":0,
4956 "bps_wr":0,
4957 "iops":1000000,
4958 "iops_rd":0,
4959 "iops_wr":0,
4960 "bps_max": 8000000,
4961 "bps_rd_max": 0,
4962 "bps_wr_max": 0,
4963 "iops_max": 0,
4964 "iops_rd_max": 0,
4965 "iops_wr_max": 0,
4966 "iops_size": 0,
4967 "write_threshold": 0,
4968 "image":{
4969 "filename":"disks/test.qcow2",
4970 "format":"qcow2",
4971 "virtual-size":2048000,
4972 "backing_file":"base.qcow2",
4973 "full-backing-filename":"disks/base.qcow2",
4974 "backing-filename-format":"qcow2",
4975 "snapshots":[
4976 {
4977 "id": "1",
4978 "name": "snapshot1",
4979 "vm-state-size": 0,
4980 "date-sec": 10000200,
4981 "date-nsec": 12,
4982 "vm-clock-sec": 206,
4983 "vm-clock-nsec": 30
4984 }
4985 ],
4986 "backing-image":{
4987 "filename":"disks/base.qcow2",
4988 "format":"qcow2",
4989 "virtual-size":2048000
4990 }
4991 } } ] }
4992 XDbgBlockGraphNodeType (Enum)
4994 Values
4995 block-backend
4996 corresponds to BlockBackend
4997 block-job
4999 corresponds to BlockJob
5000 block-driver
5002 corresponds to BlockDriverState
5003 Since
5005 4.0
5006 XDbgBlockGraphNode (Object)
5008 Members
5009 id: int
5010 Block graph node identifier. This id is generated only for x-de‐
5011 bug-query-block-graph and does not relate to any other identi‐
5012 fiers in Qemu.
5013 type: XDbgBlockGraphNodeType
5015 Type of graph node. Can be one of block-backend, block-job or
5016 block-driver-state.
5017 name: string
5019 Human readable name of the node. Corresponds to node-name for
5020 block-driver-state nodes; is not guaranteed to be unique in the
5021 whole graph (with block-jobs and block-backends).
5022 Since
5024 4.0
5025 BlockPermission (Enum)
5027 Enum of base block permissions.
5028 Values
5030 consistent-read
5031 A user that has the "permission" of consistent reads is guaran‐
5032 teed that their view of the contents of the block device is com‐
5033 plete and self-consistent, representing the contents of a disk
5034 at a specific point. For most block devices (including their
5035 backing files) this is true, but the property cannot be main‐
5036 tained in a few situations like for intermediate nodes of a com‐
5037 mit block job.
5038 write This permission is required to change the visible disk contents.
5040 write-unchanged
5042 This permission (which is weaker than BLK_PERM_WRITE) is both
5043 enough and required for writes to the block node when the caller
5044 promises that the visible disk content doesn't change. As the
5045 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
5046 cient to perform an unchanging write.
5047 resize This permission is required to change the size of a block node.
5049 Since
5051 4.0
5052 XDbgBlockGraphEdge (Object)
5054 Block Graph edge description for x-debug-query-block-graph.
5055 Members
5057 parent: int
5058 parent id
5059 child: int
5061 child id
5062 name: string
5064 name of the relation (examples are 'file' and 'backing')
5065 perm: array of BlockPermission
5067 granted permissions for the parent operating on the child
5068 shared-perm: array of BlockPermission
5070 permissions that can still be granted to other users of the
5071 child while it is still attached to this parent
5072 Since
5074 4.0
5075 XDbgBlockGraph (Object)
5077 Block Graph - list of nodes and list of edges.
5078 Members
5080 nodes: array of XDbgBlockGraphNode
5081 Not documented
5082 edges: array of XDbgBlockGraphEdge
5084 Not documented
5085 Since
5087 4.0
5088 x-debug-query-block-graph (Command)
5090 Get the block graph.
5091 Features
5093 unstable
5094 This command is meant for debugging.
5095 Since
5097 4.0
5098 drive-mirror (Command)
5100 Start mirroring a block device's writes to a new destination. target
5101 specifies the target of the new image. If the file exists, or if it is
5102 a device, it will be used as the new destination for writes. If it does
5103 not exist, a new file will be created. format specifies the format of
5104 the mirror image, default is to probe if mode='existing', else the for‐
5105 mat of the source.
5106 Arguments
5108 The members of DriveMirror
5109 Returns
5111 • nothing on success
5112 • If device is not a valid block device, GenericError
5114 Since
5116 1.3
5117 Example
5119 -> { "execute": "drive-mirror",
5120 "arguments": { "device": "ide-hd0",
5121 "target": "/some/place/my-image",
5122 "sync": "full",
5123 "format": "qcow2" } }
5124 <- { "return": {} }
5125 DriveMirror (Object)
5127 A set of parameters describing drive mirror setup.
5128 Members
5130 job-id: string (optional)
5131 identifier for the newly-created block job. If omitted, the de‐
5132 vice name will be used. (Since 2.7)
5133 device: string
5135 the device name or node-name of a root node whose writes should
5136 be mirrored.
5137 target: string
5139 the target of the new image. If the file exists, or if it is a
5140 device, the existing file/device will be used as the new desti‐
5141 nation. If it does not exist, a new file will be created.
5142 format: string (optional)
5144 the format of the new destination, default is to probe if mode
5145 is 'existing', else the format of the source
5146 node-name: string (optional)
5148 the new block driver state node name in the graph (Since 2.1)
5149 replaces: string (optional)
5151 with sync=full graph node name to be replaced by the new image
5152 when a whole image copy is done. This can be used to repair bro‐
5153 ken Quorum files. By default, device is replaced, although im‐
5154 plicitly created filters on it are kept. (Since 2.1)
5155 mode: NewImageMode (optional)
5157 whether and how QEMU should create a new image, default is 'ab‐
5158 solute-paths'.
5159 speed: int (optional)
5161 the maximum speed, in bytes per second
5162 sync: MirrorSyncMode
5164 what parts of the disk image should be copied to the destination
5165 (all the disk, only the sectors allocated in the topmost image,
5166 or only new I/O).
5167 granularity: int (optional)
5169 granularity of the dirty bitmap, default is 64K if the image
5170 format doesn't have clusters, 4K if the clusters are smaller
5171 than that, else the cluster size. Must be a power of 2 between
5172 512 and 64M (since 1.4).
5173 buf-size: int (optional)
5175 maximum amount of data in flight from source to target (since
5176 1.4).
5177 on-source-error: BlockdevOnError (optional)
5179 the action to take on an error on the source, default 'report'.
5180 'stop' and 'enospc' can only be used if the block device sup‐
5181 ports io-status (see BlockInfo).
5182 on-target-error: BlockdevOnError (optional)
5184 the action to take on an error on the target, default 'report'
5185 (no limitations, since this applies to a different block device
5186 than device).
5187 unmap: boolean (optional)
5189 Whether to try to unmap target sectors where source has only
5190 zero. If true, and target unallocated sectors will read as zero,
5191 target image sectors will be unmapped; otherwise, zeroes will be
5192 written. Both will result in identical contents. Default is
5193 true. (Since 2.4)
5194 copy-mode: MirrorCopyMode (optional)
5196 when to copy data to the destination; defaults to 'background'
5197 (Since: 3.0)
5198 auto-finalize: boolean (optional)
5200 When false, this job will wait in a PENDING state after it has
5201 finished its work, waiting for block-job-finalize before making
5202 any block graph changes. When true, this job will automatically
5203 perform its abort or commit actions. Defaults to true. (Since
5204 3.1)
5205 auto-dismiss: boolean (optional)
5207 When false, this job will wait in a CONCLUDED state after it has
5208 completely ceased all work, and awaits block-job-dismiss. When
5209 true, this job will automatically disappear from the query list
5210 without user intervention. Defaults to true. (Since 3.1)
5211 Since
5213 1.3
5214 BlockDirtyBitmap (Object)
5216 Members
5217 node: string
5218 name of device/node which the bitmap is tracking
5219 name: string
5221 name of the dirty bitmap
5222 Since
5224 2.4
5225 BlockDirtyBitmapAdd (Object)
5227 Members
5228 node: string
5229 name of device/node which the bitmap is tracking
5230 name: string
5232 name of the dirty bitmap (must be less than 1024 bytes)
5233 granularity: int (optional)
5235 the bitmap granularity, default is 64k for block-dirty-bit‐
5236 map-add
5237 persistent: boolean (optional)
5239 the bitmap is persistent, i.e. it will be saved to the corre‐
5240 sponding block device image file on its close. For now only
5241 Qcow2 disks support persistent bitmaps. Default is false for
5242 block-dirty-bitmap-add. (Since: 2.10)
5243 disabled: boolean (optional)
5245 the bitmap is created in the disabled state, which means that it
5246 will not track drive changes. The bitmap may be enabled with
5247 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
5248 Since
5250 2.4
5251 BlockDirtyBitmapOrStr (Alternate)
5253 Members
5254 local: string
5255 name of the bitmap, attached to the same node as target bitmap.
5256 external: BlockDirtyBitmap
5258 bitmap with specified node
5259 Since
5261 4.1
5262 BlockDirtyBitmapMerge (Object)
5264 Members
5265 node: string
5266 name of device/node which the target bitmap is tracking
5267 target: string
5269 name of the destination dirty bitmap
5270 bitmaps: array of BlockDirtyBitmapOrStr
5272 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
5273 ified BlockDirtyBitmap elements. The latter are supported since
5274 4.1.
5275 Since
5277 4.0
5278 block-dirty-bitmap-add (Command)
5280 Create a dirty bitmap with a name on the node, and start tracking the
5281 writes.
5282 Returns
5284 • nothing on success
5285 • If node is not a valid block device or node, DeviceNotFound
5287 • If name is already taken, GenericError with an explanation
5289 Since
5291 2.4
5292 Example
5294 -> { "execute": "block-dirty-bitmap-add",
5295 "arguments": { "node": "drive0", "name": "bitmap0" } }
5296 <- { "return": {} }
5297 block-dirty-bitmap-remove (Command)
5299 Stop write tracking and remove the dirty bitmap that was created with
5300 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
5301 storage too.
5302 Returns
5304 • nothing on success
5305 • If node is not a valid block device or node, DeviceNotFound
5307 • If name is not found, GenericError with an explanation
5309 • if name is frozen by an operation, GenericError
5311 Since
5313 2.4
5314 Example
5316 -> { "execute": "block-dirty-bitmap-remove",
5317 "arguments": { "node": "drive0", "name": "bitmap0" } }
5318 <- { "return": {} }
5319 block-dirty-bitmap-clear (Command)
5321 Clear (reset) a dirty bitmap on the device, so that an incremental
5322 backup from this point in time forward will only backup clusters modi‐
5323 fied after this clear operation.
5324 Returns
5326 • nothing on success
5327 • If node is not a valid block device, DeviceNotFound
5329 • If name is not found, GenericError with an explanation
5331 Since
5333 2.4
5334 Example
5336 -> { "execute": "block-dirty-bitmap-clear",
5337 "arguments": { "node": "drive0", "name": "bitmap0" } }
5338 <- { "return": {} }
5339 block-dirty-bitmap-enable (Command)
5341 Enables a dirty bitmap so that it will begin tracking disk changes.
5342 Returns
5344 • nothing on success
5345 • If node is not a valid block device, DeviceNotFound
5347 • If name is not found, GenericError with an explanation
5349 Since
5351 4.0
5352 Example
5354 -> { "execute": "block-dirty-bitmap-enable",
5355 "arguments": { "node": "drive0", "name": "bitmap0" } }
5356 <- { "return": {} }
5357 block-dirty-bitmap-disable (Command)
5359 Disables a dirty bitmap so that it will stop tracking disk changes.
5360 Returns
5362 • nothing on success
5363 • If node is not a valid block device, DeviceNotFound
5365 • If name is not found, GenericError with an explanation
5367 Since
5369 4.0
5370 Example
5372 -> { "execute": "block-dirty-bitmap-disable",
5373 "arguments": { "node": "drive0", "name": "bitmap0" } }
5374 <- { "return": {} }
5375 block-dirty-bitmap-merge (Command)
5377 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
5378 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
5379 as the target bitmap. Any bits already set in target will still be set
5380 after the merge, i.e., this operation does not clear the target. On
5381 error, target is unchanged.
5382 The resulting bitmap will count as dirty any clusters that were dirty
5384 in any of the source bitmaps. This can be used to achieve backup check‐
5385 points, or in simpler usages, to copy bitmaps.
5386 Returns
5388 • nothing on success
5389 • If node is not a valid block device, DeviceNotFound
5391 • If any bitmap in bitmaps or target is not found, GenericError
5393 • If any of the bitmaps have different sizes or granularities, Gener‐
5395 icError
5396 Since
5398 4.0
5399 Example
5401 -> { "execute": "block-dirty-bitmap-merge",
5402 "arguments": { "node": "drive0", "target": "bitmap0",
5403 "bitmaps": ["bitmap1"] } }
5404 <- { "return": {} }
5405 BlockDirtyBitmapSha256 (Object)
5407 SHA256 hash of dirty bitmap data
5408 Members
5410 sha256: string
5411 ASCII representation of SHA256 bitmap hash
5412 Since
5414 2.10
5415 x-debug-block-dirty-bitmap-sha256 (Command)
5417 Get bitmap SHA256.
5418 Features
5420 unstable
5421 This command is meant for debugging.
5422 Returns
5424 • BlockDirtyBitmapSha256 on success
5425 • If node is not a valid block device, DeviceNotFound
5427 • If name is not found or if hashing has failed, GenericError with an
5429 explanation
5430 Since
5432 2.10
5433 blockdev-mirror (Command)
5435 Start mirroring a block device's writes to a new destination.
5436 Arguments
5438 job-id: string (optional)
5439 identifier for the newly-created block job. If omitted, the de‐
5440 vice name will be used. (Since 2.7)
5441 device: string
5443 The device name or node-name of a root node whose writes should
5444 be mirrored.
5445 target: string
5447 the id or node-name of the block device to mirror to. This
5448 mustn't be attached to guest.
5449 replaces: string (optional)
5451 with sync=full graph node name to be replaced by the new image
5452 when a whole image copy is done. This can be used to repair bro‐
5453 ken Quorum files. By default, device is replaced, although im‐
5454 plicitly created filters on it are kept.
5455 speed: int (optional)
5457 the maximum speed, in bytes per second
5458 sync: MirrorSyncMode
5460 what parts of the disk image should be copied to the destination
5461 (all the disk, only the sectors allocated in the topmost image,
5462 or only new I/O).
5463 granularity: int (optional)
5465 granularity of the dirty bitmap, default is 64K if the image
5466 format doesn't have clusters, 4K if the clusters are smaller
5467 than that, else the cluster size. Must be a power of 2 between
5468 512 and 64M
5469 buf-size: int (optional)
5471 maximum amount of data in flight from source to target
5472 on-source-error: BlockdevOnError (optional)
5474 the action to take on an error on the source, default 'report'.
5475 'stop' and 'enospc' can only be used if the block device sup‐
5476 ports io-status (see BlockInfo).
5477 on-target-error: BlockdevOnError (optional)
5479 the action to take on an error on the target, default 'report'
5480 (no limitations, since this applies to a different block device
5481 than device).
5482 filter-node-name: string (optional)
5484 the node name that should be assigned to the filter driver that
5485 the mirror job inserts into the graph above device. If this op‐
5486 tion is not given, a node name is autogenerated. (Since: 2.9)
5487 copy-mode: MirrorCopyMode (optional)
5489 when to copy data to the destination; defaults to 'background'
5490 (Since: 3.0)
5491 auto-finalize: boolean (optional)
5493 When false, this job will wait in a PENDING state after it has
5494 finished its work, waiting for block-job-finalize before making
5495 any block graph changes. When true, this job will automatically
5496 perform its abort or commit actions. Defaults to true. (Since
5497 3.1)
5498 auto-dismiss: boolean (optional)
5500 When false, this job will wait in a CONCLUDED state after it has
5501 completely ceased all work, and awaits block-job-dismiss. When
5502 true, this job will automatically disappear from the query list
5503 without user intervention. Defaults to true. (Since 3.1)
5504 Returns
5506 nothing on success.
5507 Since
5509 2.6
5510 Example
5512 -> { "execute": "blockdev-mirror",
5513 "arguments": { "device": "ide-hd0",
5514 "target": "target0",
5515 "sync": "full" } }
5516 <- { "return": {} }
5517 BlockIOThrottle (Object)
5519 A set of parameters describing block throttling.
5520 Members
5522 device: string (optional)
5523 Block device name
5524 id: string (optional)
5526 The name or QOM path of the guest device (since: 2.8)
5527 bps: int
5529 total throughput limit in bytes per second
5530 bps_rd: int
5532 read throughput limit in bytes per second
5533 bps_wr: int
5535 write throughput limit in bytes per second
5536 iops: int
5538 total I/O operations per second
5539 iops_rd: int
5541 read I/O operations per second
5542 iops_wr: int
5544 write I/O operations per second
5545 bps_max: int (optional)
5547 total throughput limit during bursts, in bytes (Since 1.7)
5548 bps_rd_max: int (optional)
5550 read throughput limit during bursts, in bytes (Since 1.7)
5551 bps_wr_max: int (optional)
5553 write throughput limit during bursts, in bytes (Since 1.7)
5554 iops_max: int (optional)
5556 total I/O operations per second during bursts, in bytes (Since
5557 1.7)
5558 iops_rd_max: int (optional)
5560 read I/O operations per second during bursts, in bytes (Since
5561 1.7)
5562 iops_wr_max: int (optional)
5564 write I/O operations per second during bursts, in bytes (Since
5565 1.7)
5566 bps_max_length: int (optional)
5568 maximum length of the bps_max burst period, in seconds. It must
5569 only be set if bps_max is set as well. Defaults to 1. (Since
5570 2.6)
5571 bps_rd_max_length: int (optional)
5573 maximum length of the bps_rd_max burst period, in seconds. It
5574 must only be set if bps_rd_max is set as well. Defaults to 1.
5575 (Since 2.6)
5576 bps_wr_max_length: int (optional)
5578 maximum length of the bps_wr_max burst period, in seconds. It
5579 must only be set if bps_wr_max is set as well. Defaults to 1.
5580 (Since 2.6)
5581 iops_max_length: int (optional)
5583 maximum length of the iops burst period, in seconds. It must
5584 only be set if iops_max is set as well. Defaults to 1. (Since
5585 2.6)
5586 iops_rd_max_length: int (optional)
5588 maximum length of the iops_rd_max burst period, in seconds. It
5589 must only be set if iops_rd_max is set as well. Defaults to 1.
5590 (Since 2.6)
5591 iops_wr_max_length: int (optional)
5593 maximum length of the iops_wr_max burst period, in seconds. It
5594 must only be set if iops_wr_max is set as well. Defaults to 1.
5595 (Since 2.6)
5596 iops_size: int (optional)
5598 an I/O size in bytes (Since 1.7)
5599 group: string (optional)
5601 throttle group name (Since 2.4)
5602 Features
5604 deprecated
5605 Member device is deprecated. Use id instead.
5606 Since
5608 1.1
5609 ThrottleLimits (Object)
5611 Limit parameters for throttling. Since some limit combinations are il‐
5612 legal, limits should always be set in one transaction. All fields are
5613 optional. When setting limits, if a field is missing the current value
5614 is not changed.
5615 Members
5617 iops-total: int (optional)
5618 limit total I/O operations per second
5619 iops-total-max: int (optional)
5621 I/O operations burst
5622 iops-total-max-length: int (optional)
5624 length of the iops-total-max burst period, in seconds It must
5625 only be set if iops-total-max is set as well.
5626 iops-read: int (optional)
5628 limit read operations per second
5629 iops-read-max: int (optional)
5631 I/O operations read burst
5632 iops-read-max-length: int (optional)
5634 length of the iops-read-max burst period, in seconds It must
5635 only be set if iops-read-max is set as well.
5636 iops-write: int (optional)
5638 limit write operations per second
5639 iops-write-max: int (optional)
5641 I/O operations write burst
5642 iops-write-max-length: int (optional)
5644 length of the iops-write-max burst period, in seconds It must
5645 only be set if iops-write-max is set as well.
5646 bps-total: int (optional)
5648 limit total bytes per second
5649 bps-total-max: int (optional)
5651 total bytes burst
5652 bps-total-max-length: int (optional)
5654 length of the bps-total-max burst period, in seconds. It must
5655 only be set if bps-total-max is set as well.
5656 bps-read: int (optional)
5658 limit read bytes per second
5659 bps-read-max: int (optional)
5661 total bytes read burst
5662 bps-read-max-length: int (optional)
5664 length of the bps-read-max burst period, in seconds It must only
5665 be set if bps-read-max is set as well.
5666 bps-write: int (optional)
5668 limit write bytes per second
5669 bps-write-max: int (optional)
5671 total bytes write burst
5672 bps-write-max-length: int (optional)
5674 length of the bps-write-max burst period, in seconds It must
5675 only be set if bps-write-max is set as well.
5676 iops-size: int (optional)
5678 when limiting by iops max size of an I/O in bytes
5679 Since
5681 2.11
5682 ThrottleGroupProperties (Object)
5684 Properties for throttle-group objects.
5685 Members
5687 limits: ThrottleLimits (optional)
5688 limits to apply for this throttle group
5689 x-iops-total: int (optional)
5691 Not documented
5692 x-iops-total-max: int (optional)
5694 Not documented
5695 x-iops-total-max-length: int (optional)
5697 Not documented
5698 x-iops-read: int (optional)
5700 Not documented
5701 x-iops-read-max: int (optional)
5703 Not documented
5704 x-iops-read-max-length: int (optional)
5706 Not documented
5707 x-iops-write: int (optional)
5709 Not documented
5710 x-iops-write-max: int (optional)
5712 Not documented
5713 x-iops-write-max-length: int (optional)
5715 Not documented
5716 x-bps-total: int (optional)
5718 Not documented
5719 x-bps-total-max: int (optional)
5721 Not documented
5722 x-bps-total-max-length: int (optional)
5724 Not documented
5725 x-bps-read: int (optional)
5727 Not documented
5728 x-bps-read-max: int (optional)
5730 Not documented
5731 x-bps-read-max-length: int (optional)
5733 Not documented
5734 x-bps-write: int (optional)
5736 Not documented
5737 x-bps-write-max: int (optional)
5739 Not documented
5740 x-bps-write-max-length: int (optional)
5742 Not documented
5743 x-iops-size: int (optional)
5745 Not documented
5746 Features
5748 unstable
5749 All members starting with x- are aliases for the same key with‐
5750 out x- in the limits object. This is not a stable interface and
5751 may be removed or changed incompatibly in the future. Use lim‐
5752 its for a supported stable interface.
5753 Since
5755 2.11
5756 block-stream (Command)
5758 Copy data from a backing file into a block device.
5759 The block streaming operation is performed in the background until the
5761 entire backing file has been copied. This command returns immediately
5762 once streaming has started. The status of ongoing block streaming op‐
5763 erations can be checked with query-block-jobs. The operation can be
5764 stopped before it has completed using the block-job-cancel command.
5765 The node that receives the data is called the top image, can be located
5767 in any part of the chain (but always above the base image; see below)
5768 and can be specified using its device or node name. Earlier qemu ver‐
5769 sions only allowed 'device' to name the top level node; presence of the
5770 'base-node' parameter during introspection can be used as a witness of
5771 the enhanced semantics of 'device'.
5772 If a base file is specified then sectors are not copied from that base
5774 file and its backing chain. This can be used to stream a subset of the
5775 backing file chain instead of flattening the entire image. When
5776 streaming completes the image file will have the base file as its back‐
5777 ing file, unless that node was changed while the job was running. In
5778 that case, base's parent's backing (or filtered, whichever exists)
5779 child (i.e., base at the beginning of the job) will be the new backing
5780 file.
5781 On successful completion the image file is updated to drop the backing
5783 file and the BLOCK_JOB_COMPLETED event is emitted.
5784 In case device is a filter node, block-stream modifies the first
5786 non-filter overlay node below it to point to the new backing node in‐
5787 stead of modifying device itself.
5788 Arguments
5790 job-id: string (optional)
5791 identifier for the newly-created block job. If omitted, the de‐
5792 vice name will be used. (Since 2.7)
5793 device: string
5795 the device or node name of the top image
5796 base: string (optional)
5798 the common backing file name. It cannot be set if base-node or
5799 bottom is also set.
5800 base-node: string (optional)
5802 the node name of the backing file. It cannot be set if base or
5803 bottom is also set. (Since 2.8)
5804 bottom: string (optional)
5806 the last node in the chain that should be streamed into top. It
5807 cannot be set if base or base-node is also set. It cannot be
5808 filter node. (Since 6.0)
5809 backing-file: string (optional)
5811 The backing file string to write into the top image. This file‐
5812 name is not validated.
5813 If a pathname string is such that it cannot be resolved by QEMU,
5815 that means that subsequent QMP or HMP commands must use
5816 node-names for the image in question, as filename lookup methods
5817 will fail.
5818 If not specified, QEMU will automatically determine the backing
5820 file string to use, or error out if there is no obvious choice.
5821 Care should be taken when specifying the string, to specify a
5822 valid filename or protocol. (Since 2.1)
5823 speed: int (optional)
5825 the maximum speed, in bytes per second
5826 on-error: BlockdevOnError (optional)
5828 the action to take on an error (default report). 'stop' and
5829 'enospc' can only be used if the block device supports io-status
5830 (see BlockInfo). Since 1.3.
5831 filter-node-name: string (optional)
5833 the node name that should be assigned to the filter driver that
5834 the stream job inserts into the graph above device. If this op‐
5835 tion is not given, a node name is autogenerated. (Since: 6.0)
5836 auto-finalize: boolean (optional)
5838 When false, this job will wait in a PENDING state after it has
5839 finished its work, waiting for block-job-finalize before making
5840 any block graph changes. When true, this job will automatically
5841 perform its abort or commit actions. Defaults to true. (Since
5842 3.1)
5843 auto-dismiss: boolean (optional)
5845 When false, this job will wait in a CONCLUDED state after it has
5846 completely ceased all work, and awaits block-job-dismiss. When
5847 true, this job will automatically disappear from the query list
5848 without user intervention. Defaults to true. (Since 3.1)
5849 Returns
5851 • Nothing on success.
5852 • If device does not exist, DeviceNotFound.
5854 Since
5856 1.1
5857 Example
5859 -> { "execute": "block-stream",
5860 "arguments": { "device": "virtio0",
5861 "base": "/tmp/master.qcow2" } }
5862 <- { "return": {} }
5863 block-job-set-speed (Command)
5865 Set maximum speed for a background block operation.
5866 This command can only be issued when there is an active block job.
5868 Throttling can be disabled by setting the speed to 0.
5870 Arguments
5872 device: string
5873 The job identifier. This used to be a device name (hence the
5874 name of the parameter), but since QEMU 2.7 it can have other
5875 values.
5876 speed: int
5878 the maximum speed, in bytes per second, or 0 for unlimited. De‐
5879 faults to 0.
5880 Returns
5882 • Nothing on success
5883 • If no background operation is active on this device, DeviceNotActive
5885 Since
5887 1.1
5888 block-job-cancel (Command)
5890 Stop an active background block operation.
5891 This command returns immediately after marking the active background
5893 block operation for cancellation. It is an error to call this command
5894 if no operation is in progress.
5895 The operation will cancel as soon as possible and then emit the
5897 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
5898 ble when enumerated using query-block-jobs.
5899 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
5901 dicated (via the event BLOCK_JOB_READY) that the source and destination
5902 are synchronized, then the event triggered by this command changes to
5903 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
5904 destination now has a point-in-time copy tied to the time of the can‐
5905 cellation.
5906 For streaming, the image file retains its backing file unless the
5908 streaming operation happens to complete just as it is being cancelled.
5909 A new streaming operation can be started at a later time to finish
5910 copying all data from the backing file.
5911 Arguments
5913 device: string
5914 The job identifier. This used to be a device name (hence the
5915 name of the parameter), but since QEMU 2.7 it can have other
5916 values.
5917 force: boolean (optional)
5919 If true, and the job has already emitted the event
5920 BLOCK_JOB_READY, abandon the job immediately (even if it is
5921 paused) instead of waiting for the destination to complete its
5922 final synchronization (since 1.3)
5923 Returns
5925 • Nothing on success
5926 • If no background operation is active on this device, DeviceNotActive
5928 Since
5930 1.1
5931 block-job-pause (Command)
5933 Pause an active background block operation.
5934 This command returns immediately after marking the active background
5936 block operation for pausing. It is an error to call this command if no
5937 operation is in progress or if the job is already paused.
5938 The operation will pause as soon as possible. No event is emitted when
5940 the operation is actually paused. Cancelling a paused job automati‐
5941 cally resumes it.
5942 Arguments
5944 device: string
5945 The job identifier. This used to be a device name (hence the
5946 name of the parameter), but since QEMU 2.7 it can have other
5947 values.
5948 Returns
5950 • Nothing on success
5951 • If no background operation is active on this device, DeviceNotActive
5953 Since
5955 1.3
5956 block-job-resume (Command)
5958 Resume an active background block operation.
5959 This command returns immediately after resuming a paused background
5961 block operation. It is an error to call this command if no operation
5962 is in progress or if the job is not paused.
5963 This command also clears the error status of the job.
5965 Arguments
5967 device: string
5968 The job identifier. This used to be a device name (hence the
5969 name of the parameter), but since QEMU 2.7 it can have other
5970 values.
5971 Returns
5973 • Nothing on success
5974 • If no background operation is active on this device, DeviceNotActive
5976 Since
5978 1.3
5979 block-job-complete (Command)
5981 Manually trigger completion of an active background block operation.
5982 This is supported for drive mirroring, where it also switches the de‐
5983 vice to write to the target path only. The ability to complete is sig‐
5984 naled with a BLOCK_JOB_READY event.
5985 This command completes an active background block operation syn‐
5987 chronously. The ordering of this command's return with the
5988 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
5989 occurs during the processing of this command: 1) the command itself
5990 will fail; 2) the error will be processed according to the rerror/wer‐
5991 ror arguments that were specified when starting the operation.
5992 A cancelled or paused job cannot be completed.
5994 Arguments
5996 device: string
5997 The job identifier. This used to be a device name (hence the
5998 name of the parameter), but since QEMU 2.7 it can have other
5999 values.
6000 Returns
6002 • Nothing on success
6003 • If no background operation is active on this device, DeviceNotActive
6005 Since
6007 1.3
6008 block-job-dismiss (Command)
6010 For jobs that have already concluded, remove them from the
6011 block-job-query list. This command only needs to be run for jobs which
6012 were started with QEMU 2.12+ job lifetime management semantics.
6013 This command will refuse to operate on any job that has not yet reached
6015 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
6016 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
6017 still need to be used as appropriate.
6018 Arguments
6020 id: string
6021 The job identifier.
6022 Returns
6024 Nothing on success
6025 Since
6027 2.12
6028 block-job-finalize (Command)
6030 Once a job that has manual=true reaches the pending state, it can be
6031 instructed to finalize any graph changes and do any necessary cleanup
6032 via this command. For jobs in a transaction, instructing one job to
6033 finalize will force ALL jobs in the transaction to finalize, so it is
6034 only necessary to instruct a single member job to finalize.
6035 Arguments
6037 id: string
6038 The job identifier.
6039 Returns
6041 Nothing on success
6042 Since
6044 2.12
6045 BlockdevDiscardOptions (Enum)
6047 Determines how to handle discard requests.
6048 Values
6050 ignore Ignore the request
6051 unmap Forward as an unmap request
6053 Since
6055 2.9
6056 BlockdevDetectZeroesOptions (Enum)
6058 Describes the operation mode for the automatic conversion of plain zero
6059 writes by the OS to driver specific optimized zero write commands.
6060 Values
6062 off Disabled (default)
6063 on Enabled
6065 unmap Enabled and even try to unmap blocks if possible. This requires
6067 also that BlockdevDiscardOptions is set to unmap for this de‐
6068 vice.
6069 Since
6071 2.1
6072 BlockdevAioOptions (Enum)
6074 Selects the AIO backend to handle I/O requests
6075 Values
6077 threads
6078 Use qemu's thread pool
6079 native Use native AIO backend (only Linux and Windows)
6081 io_uring (If: CONFIG_LINUX_IO_URING)
6083 Use linux io_uring (since 5.0)
6084 Since
6086 2.9
6087 BlockdevCacheOptions (Object)
6089 Includes cache-related options for block devices
6090 Members
6092 direct: boolean (optional)
6093 enables use of O_DIRECT (bypass the host page cache; default:
6094 false)
6095 no-flush: boolean (optional)
6097 ignore any flush requests for the device (default: false)
6098 Since
6100 2.9
6101 BlockdevDriver (Enum)
6103 Drivers that are supported in block device operations.
6104 Values
6106 throttle
6107 Since 2.11
6108 nvme Since 2.12
6110 copy-on-read
6112 Since 3.0
6113 blklogwrites
6115 Since 3.0
6116 blkreplay
6118 Since 4.2
6119 compress
6121 Since 5.0
6122 copy-before-write
6124 Since 6.2
6125 snapshot-access
6127 Since 7.0
6128 blkdebug
6130 Not documented
6131 blkverify
6133 Not documented
6134 bochs Not documented
6136 cloop Not documented
6138 dmg Not documented
6140 file Not documented
6142 ftp Not documented
6144 ftps Not documented
6146 gluster
6148 Not documented
6149 host_cdrom (If: HAVE_HOST_BLOCK_DEVICE)
6151 Not documented
6152 host_device (If: HAVE_HOST_BLOCK_DEVICE)
6154 Not documented
6155 http Not documented
6157 https Not documented
6159 io_uring (If: CONFIG_BLKIO)
6161 Not documented
6162 iscsi Not documented
6164 luks Not documented
6166 nbd Not documented
6168 nfs Not documented
6170 null-aio
6172 Not documented
6173 null-co
6175 Not documented
6176 nvme-io_uring (If: CONFIG_BLKIO)
6178 Not documented
6179 parallels
6181 Not documented
6182 preallocate
6184 Not documented
6185 qcow Not documented
6187 qcow2 Not documented
6189 qed Not documented
6191 quorum Not documented
6193 raw Not documented
6195 rbd Not documented
6197 replication (If: CONFIG_REPLICATION)
6199 Not documented
6200 ssh Not documented
6202 vdi Not documented
6204 vhdx Not documented
6206 virtio-blk-vfio-pci (If: CONFIG_BLKIO)
6208 Not documented
6209 virtio-blk-vhost-user (If: CONFIG_BLKIO)
6211 Not documented
6212 virtio-blk-vhost-vdpa (If: CONFIG_BLKIO)
6214 Not documented
6215 vmdk Not documented
6217 vpc Not documented
6219 vvfat Not documented
6221 Since
6223 2.9
6224 BlockdevOptionsFile (Object)
6226 Driver specific block device options for the file backend.
6227 Members
6229 filename: string
6230 path to the image file
6231 pr-manager: string (optional)
6233 the id for the object that will handle persistent reservations
6234 for this device (default: none, forward the commands via SG_IO;
6235 since 2.11)
6236 aio: BlockdevAioOptions (optional)
6238 AIO backend (default: threads) (since: 2.8)
6239 aio-max-batch: int (optional)
6241 maximum number of requests to batch together into a single sub‐
6242 mission in the AIO backend. The smallest value between this and
6243 the aio-max-batch value of the IOThread object is chosen. 0
6244 means that the AIO backend will handle it automatically. (de‐
6245 fault: 0, since 6.2)
6246 locking: OnOffAuto (optional)
6248 whether to enable file locking. If set to 'auto', only enable
6249 when Open File Descriptor (OFD) locking API is available (de‐
6250 fault: auto, since 2.10)
6251 drop-cache: boolean (optional) (If: CONFIG_LINUX)
6253 invalidate page cache during live migration. This prevents
6254 stale data on the migration destination with cache.direct=off.
6255 Currently only supported on Linux hosts. (default: on, since:
6256 4.0)
6257 x-check-cache-dropped: boolean (optional)
6259 whether to check that page cache was dropped on live migration.
6260 May cause noticeable delays if the image file is large, do not
6261 use in production. (default: off) (since: 3.0)
6262 Features
6264 dynamic-auto-read-only
6265 If present, enabled auto-read-only means that the driver will
6266 open the image read-only at first, dynamically reopen the image
6267 file read-write when the first writer is attached to the node
6268 and reopen read-only when the last writer is detached. This al‐
6269 lows giving QEMU write permissions only on demand when an opera‐
6270 tion actually needs write access.
6271 unstable
6273 Member x-check-cache-dropped is meant for debugging.
6274 Since
6276 2.9
6277 BlockdevOptionsNull (Object)
6279 Driver specific block device options for the null backend.
6280 Members
6282 size: int (optional)
6283 size of the device in bytes.
6284 latency-ns: int (optional)
6286 emulated latency (in nanoseconds) in processing requests. De‐
6287 fault to zero which completes requests immediately. (Since 2.4)
6288 read-zeroes: boolean (optional)
6290 if true, reads from the device produce zeroes; if false, the
6291 buffer is left unchanged. (default: false; since: 4.1)
6292 Since
6294 2.9
6295 BlockdevOptionsNVMe (Object)
6297 Driver specific block device options for the NVMe backend.
6298 Members
6300 device: string
6301 PCI controller address of the NVMe device in format hhhh:bb:ss.f
6302 (host:bus:slot.function)
6303 namespace: int
6305 namespace number of the device, starting from 1.
6306 Note that the PCI device must have been unbound from any host kernel
6307 driver before instructing QEMU to add the blockdev.
6308 Since
6310 2.12
6311 BlockdevOptionsVVFAT (Object)
6313 Driver specific block device options for the vvfat protocol.
6314 Members
6316 dir: string
6317 directory to be exported as FAT image
6318 fat-type: int (optional)
6320 FAT type: 12, 16 or 32
6321 floppy: boolean (optional)
6323 whether to export a floppy image (true) or partitioned hard disk
6324 (false; default)
6325 label: string (optional)
6327 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
6328 ditionally have some restrictions on labels, which are ignored
6329 by most operating systems. Defaults to "QEMU VVFAT". (since
6330 2.4)
6331 rw: boolean (optional)
6333 whether to allow write operations (default: false)
6334 Since
6336 2.9
6337 BlockdevOptionsGenericFormat (Object)
6339 Driver specific block device options for image format that have no op‐
6340 tion besides their data source.
6341 Members
6343 file: BlockdevRef
6344 reference to or definition of the data source block device
6345 Since
6347 2.9
6348 BlockdevOptionsLUKS (Object)
6350 Driver specific block device options for LUKS.
6351 Members
6353 key-secret: string (optional)
6354 the ID of a QCryptoSecret object providing the decryption key
6355 (since 2.6). Mandatory except when doing a metadata-only probe
6356 of the image.
6357 The members of BlockdevOptionsGenericFormat
6359 Since
6361 2.9
6362 BlockdevOptionsGenericCOWFormat (Object)
6364 Driver specific block device options for image format that have no op‐
6365 tion besides their data source and an optional backing file.
6366 Members
6368 backing: BlockdevRefOrNull (optional)
6369 reference to or definition of the backing file block device,
6370 null disables the backing file entirely. Defaults to the back‐
6371 ing file stored the image file.
6372 The members of BlockdevOptionsGenericFormat
6374 Since
6376 2.9
6377 Qcow2OverlapCheckMode (Enum)
6379 General overlap check modes.
6380 Values
6382 none Do not perform any checks
6383 constant
6385 Perform only checks which can be done in constant time and with‐
6386 out reading anything from disk
6387 cached Perform only checks which can be done without reading anything
6389 from disk
6390 all Perform all available overlap checks
6392 Since
6394 2.9
6395 Qcow2OverlapCheckFlags (Object)
6397 Structure of flags for each metadata structure. Setting a field to
6398 'true' makes qemu guard that structure against unintended overwriting.
6399 The default value is chosen according to the template given.
6400 Members
6402 template: Qcow2OverlapCheckMode (optional)
6403 Specifies a template mode which can be adjusted using the other
6404 flags, defaults to 'cached'
6405 bitmap-directory: boolean (optional)
6407 since 3.0
6408 main-header: boolean (optional)
6410 Not documented
6411 active-l1: boolean (optional)
6413 Not documented
6414 active-l2: boolean (optional)
6416 Not documented
6417 refcount-table: boolean (optional)
6419 Not documented
6420 refcount-block: boolean (optional)
6422 Not documented
6423 snapshot-table: boolean (optional)
6425 Not documented
6426 inactive-l1: boolean (optional)
6428 Not documented
6429 inactive-l2: boolean (optional)
6431 Not documented
6432 Since
6434 2.9
6435 Qcow2OverlapChecks (Alternate)
6437 Specifies which metadata structures should be guarded against unin‐
6438 tended overwriting.
6439 Members
6441 flags: Qcow2OverlapCheckFlags
6442 set of flags for separate specification of each metadata struc‐
6443 ture type
6444 mode: Qcow2OverlapCheckMode
6446 named mode which chooses a specific set of flags
6447 Since
6449 2.9
6450 BlockdevQcowEncryptionFormat (Enum)
6452 Values
6453 aes AES-CBC with plain64 initialization vectors
6454 Since
6456 2.10
6457 BlockdevQcowEncryption (Object)
6459 Members
6460 format: BlockdevQcowEncryptionFormat
6461 Not documented
6462 The members of QCryptoBlockOptionsQCow when format is "aes"
6464 Since
6466 2.10
6467 BlockdevOptionsQcow (Object)
6469 Driver specific block device options for qcow.
6470 Members
6472 encrypt: BlockdevQcowEncryption (optional)
6473 Image decryption options. Mandatory for encrypted images, except
6474 when doing a metadata-only probe of the image.
6475 The members of BlockdevOptionsGenericCOWFormat
6477 Since
6479 2.10
6480 BlockdevQcow2EncryptionFormat (Enum)
6482 Values
6483 aes AES-CBC with plain64 initialization vectors
6484 luks Not documented
6486 Since
6488 2.10
6489 BlockdevQcow2Encryption (Object)
6491 Members
6492 format: BlockdevQcow2EncryptionFormat
6493 Not documented
6494 The members of QCryptoBlockOptionsQCow when format is "aes"
6496 The members of QCryptoBlockOptionsLUKS when format is "luks"
6498 Since
6500 2.10
6501 BlockdevOptionsPreallocate (Object)
6503 Filter driver intended to be inserted between format and protocol node
6504 and do preallocation in protocol node on write.
6505 Members
6507 prealloc-align: int (optional)
6508 on preallocation, align file length to this number, default
6509 1048576 (1M)
6510 prealloc-size: int (optional)
6512 how much to preallocate, default 134217728 (128M)
6513 The members of BlockdevOptionsGenericFormat
6515 Since
6517 6.0
6518 BlockdevOptionsQcow2 (Object)
6520 Driver specific block device options for qcow2.
6521 Members
6523 lazy-refcounts: boolean (optional)
6524 whether to enable the lazy refcounts feature (default is taken
6525 from the image file)
6526 pass-discard-request: boolean (optional)
6528 whether discard requests to the qcow2 device should be forwarded
6529 to the data source
6530 pass-discard-snapshot: boolean (optional)
6532 whether discard requests for the data source should be issued
6533 when a snapshot operation (e.g. deleting a snapshot) frees
6534 clusters in the qcow2 file
6535 pass-discard-other: boolean (optional)
6537 whether discard requests for the data source should be issued on
6538 other occasions where a cluster gets freed
6539 overlap-check: Qcow2OverlapChecks (optional)
6541 which overlap checks to perform for writes to the image, de‐
6542 faults to 'cached' (since 2.2)
6543 cache-size: int (optional)
6545 the maximum total size of the L2 table and refcount block caches
6546 in bytes (since 2.2)
6547 l2-cache-size: int (optional)
6549 the maximum size of the L2 table cache in bytes (since 2.2)
6550 l2-cache-entry-size: int (optional)
6552 the size of each entry in the L2 cache in bytes. It must be a
6553 power of two between 512 and the cluster size. The default value
6554 is the cluster size (since 2.12)
6555 refcount-cache-size: int (optional)
6557 the maximum size of the refcount block cache in bytes (since
6558 2.2)
6559 cache-clean-interval: int (optional)
6561 clean unused entries in the L2 and refcount caches. The interval
6562 is in seconds. The default value is 600 on supporting platforms,
6563 and 0 on other platforms. 0 disables this feature. (since 2.5)
6564 encrypt: BlockdevQcow2Encryption (optional)
6566 Image decryption options. Mandatory for encrypted images, except
6567 when doing a metadata-only probe of the image. (since 2.10)
6568 data-file: BlockdevRef (optional)
6570 reference to or definition of the external data file. This may
6571 only be specified for images that require an external data file.
6572 If it is not specified for such an image, the data file name is
6573 loaded from the image file. (since 4.0)
6574 The members of BlockdevOptionsGenericCOWFormat
6576 Since
6578 2.9
6579 SshHostKeyCheckMode (Enum)
6581 Values
6582 none Don't check the host key at all
6583 hash Compare the host key with a given hash
6585 known_hosts
6587 Check the host key against the known_hosts file
6588 Since
6590 2.12
6591 SshHostKeyCheckHashType (Enum)
6593 Values
6594 md5 The given hash is an md5 hash
6595 sha1 The given hash is an sha1 hash
6597 sha256 The given hash is an sha256 hash
6599 Since
6601 2.12
6602 SshHostKeyHash (Object)
6604 Members
6605 type: SshHostKeyCheckHashType
6606 The hash algorithm used for the hash
6607 hash: string
6609 The expected hash value
6610 Since
6612 2.12
6613 SshHostKeyCheck (Object)
6615 Members
6616 mode: SshHostKeyCheckMode
6617 Not documented
6618 The members of SshHostKeyHash when mode is "hash"
6620 Since
6622 2.12
6623 BlockdevOptionsSsh (Object)
6625 Members
6626 server: InetSocketAddress
6627 host address
6628 path: string
6630 path to the image on the host
6631 user: string (optional)
6633 user as which to connect, defaults to current local user name
6634 host-key-check: SshHostKeyCheck (optional)
6636 Defines how and what to check the host key against (default:
6637 known_hosts)
6638 Since
6640 2.9
6641 BlkdebugEvent (Enum)
6643 Trigger events supported by blkdebug.
6644 Values
6646 l1_shrink_write_table
6647 write zeros to the l1 table to shrink image. (since 2.11)
6648 l1_shrink_free_l2_clusters
6650 discard the l2 tables. (since 2.11)
6651 cor_write
6653 a write due to copy-on-read (since 2.11)
6654 cluster_alloc_space
6656 an allocation of file space for a cluster (since 4.1)
6657 none triggers once at creation of the blkdebug node (since 4.1)
6659 l1_update
6661 Not documented
6662 l1_grow_alloc_table
6664 Not documented
6665 l1_grow_write_table
6667 Not documented
6668 l1_grow_activate_table
6670 Not documented
6671 l2_load
6673 Not documented
6674 l2_update
6676 Not documented
6677 l2_update_compressed
6679 Not documented
6680 l2_alloc_cow_read
6682 Not documented
6683 l2_alloc_write
6685 Not documented
6686 read_aio
6688 Not documented
6689 read_backing_aio
6691 Not documented
6692 read_compressed
6694 Not documented
6695 write_aio
6697 Not documented
6698 write_compressed
6700 Not documented
6701 vmstate_load
6703 Not documented
6704 vmstate_save
6706 Not documented
6707 cow_read
6709 Not documented
6710 cow_write
6712 Not documented
6713 reftable_load
6715 Not documented
6716 reftable_grow
6718 Not documented
6719 reftable_update
6721 Not documented
6722 refblock_load
6724 Not documented
6725 refblock_update
6727 Not documented
6728 refblock_update_part
6730 Not documented
6731 refblock_alloc
6733 Not documented
6734 refblock_alloc_hookup
6736 Not documented
6737 refblock_alloc_write
6739 Not documented
6740 refblock_alloc_write_blocks
6742 Not documented
6743 refblock_alloc_write_table
6745 Not documented
6746 refblock_alloc_switch_table
6748 Not documented
6749 cluster_alloc
6751 Not documented
6752 cluster_alloc_bytes
6754 Not documented
6755 cluster_free
6757 Not documented
6758 flush_to_os
6760 Not documented
6761 flush_to_disk
6763 Not documented
6764 pwritev_rmw_head
6766 Not documented
6767 pwritev_rmw_after_head
6769 Not documented
6770 pwritev_rmw_tail
6772 Not documented
6773 pwritev_rmw_after_tail
6775 Not documented
6776 pwritev
6778 Not documented
6779 pwritev_zero
6781 Not documented
6782 pwritev_done
6784 Not documented
6785 empty_image_prepare
6787 Not documented
6788 Since
6790 2.9
6791 BlkdebugIOType (Enum)
6793 Kinds of I/O that blkdebug can inject errors in.
6794 Values
6796 read .bdrv_co_preadv()
6797 write .bdrv_co_pwritev()
6799 write-zeroes
6801 .bdrv_co_pwrite_zeroes()
6802 discard
6804 .bdrv_co_pdiscard()
6805 flush .bdrv_co_flush_to_disk()
6807 block-status
6809 .bdrv_co_block_status()
6810 Since
6812 4.1
6813 BlkdebugInjectErrorOptions (Object)
6815 Describes a single error injection for blkdebug.
6816 Members
6818 event: BlkdebugEvent
6819 trigger event
6820 state: int (optional)
6822 the state identifier blkdebug needs to be in to actually trigger
6823 the event; defaults to "any"
6824 iotype: BlkdebugIOType (optional)
6826 the type of I/O operations on which this error should be in‐
6827 jected; defaults to "all read, write, write-zeroes, discard, and
6828 flush operations" (since: 4.1)
6829 errno: int (optional)
6831 error identifier (errno) to be returned; defaults to EIO
6832 sector: int (optional)
6834 specifies the sector index which has to be affected in order to
6835 actually trigger the event; defaults to "any sector"
6836 once: boolean (optional)
6838 disables further events after this one has been triggered; de‐
6839 faults to false
6840 immediately: boolean (optional)
6842 fail immediately; defaults to false
6843 Since
6845 2.9
6846 BlkdebugSetStateOptions (Object)
6848 Describes a single state-change event for blkdebug.
6849 Members
6851 event: BlkdebugEvent
6852 trigger event
6853 state: int (optional)
6855 the current state identifier blkdebug needs to be in; defaults
6856 to "any"
6857 new_state: int
6859 the state identifier blkdebug is supposed to assume if this
6860 event is triggered
6861 Since
6863 2.9
6864 BlockdevOptionsBlkdebug (Object)
6866 Driver specific block device options for blkdebug.
6867 Members
6869 image: BlockdevRef
6870 underlying raw block device (or image file)
6871 config: string (optional)
6873 filename of the configuration file
6874 align: int (optional)
6876 required alignment for requests in bytes, must be positive power
6877 of 2, or 0 for default
6878 max-transfer: int (optional)
6880 maximum size for I/O transfers in bytes, must be positive multi‐
6881 ple of align and of the underlying file's request alignment (but
6882 need not be a power of 2), or 0 for default (since 2.10)
6883 opt-write-zero: int (optional)
6885 preferred alignment for write zero requests in bytes, must be
6886 positive multiple of align and of the underlying file's request
6887 alignment (but need not be a power of 2), or 0 for default
6888 (since 2.10)
6889 max-write-zero: int (optional)
6891 maximum size for write zero requests in bytes, must be positive
6892 multiple of align, of opt-write-zero, and of the underlying
6893 file's request alignment (but need not be a power of 2), or 0
6894 for default (since 2.10)
6895 opt-discard: int (optional)
6897 preferred alignment for discard requests in bytes, must be posi‐
6898 tive multiple of align and of the underlying file's request
6899 alignment (but need not be a power of 2), or 0 for default
6900 (since 2.10)
6901 max-discard: int (optional)
6903 maximum size for discard requests in bytes, must be positive
6904 multiple of align, of opt-discard, and of the underlying file's
6905 request alignment (but need not be a power of 2), or 0 for de‐
6906 fault (since 2.10)
6907 inject-error: array of BlkdebugInjectErrorOptions (optional)
6909 array of error injection descriptions
6910 set-state: array of BlkdebugSetStateOptions (optional)
6912 array of state-change descriptions
6913 take-child-perms: array of BlockPermission (optional)
6915 Permissions to take on image in addition to what is necessary
6916 anyway (which depends on how the blkdebug node is used). De‐
6917 faults to none. (since 5.0)
6918 unshare-child-perms: array of BlockPermission (optional)
6920 Permissions not to share on image in addition to what cannot be
6921 shared anyway (which depends on how the blkdebug node is used).
6922 Defaults to none. (since 5.0)
6923 Since
6925 2.9
6926 BlockdevOptionsBlklogwrites (Object)
6928 Driver specific block device options for blklogwrites.
6929 Members
6931 file: BlockdevRef
6932 block device
6933 log: BlockdevRef
6935 block device used to log writes to file
6936 log-sector-size: int (optional)
6938 sector size used in logging writes to file, determines granular‐
6939 ity of offsets and sizes of writes (default: 512)
6940 log-append: boolean (optional)
6942 append to an existing log (default: false)
6943 log-super-update-interval: int (optional)
6945 interval of write requests after which the log super block is
6946 updated to disk (default: 4096)
6947 Since
6949 3.0
6950 BlockdevOptionsBlkverify (Object)
6952 Driver specific block device options for blkverify.
6953 Members
6955 test: BlockdevRef
6956 block device to be tested
6957 raw: BlockdevRef
6959 raw image used for verification
6960 Since
6962 2.9
6963 BlockdevOptionsBlkreplay (Object)
6965 Driver specific block device options for blkreplay.
6966 Members
6968 image: BlockdevRef
6969 disk image which should be controlled with blkreplay
6970 Since
6972 4.2
6973 QuorumReadPattern (Enum)
6975 An enumeration of quorum read patterns.
6976 Values
6978 quorum read all the children and do a quorum vote on reads
6979 fifo read only from the first child that has not failed
6981 Since
6983 2.9
6984 BlockdevOptionsQuorum (Object)
6986 Driver specific block device options for Quorum
6987 Members
6989 blkverify: boolean (optional)
6990 true if the driver must print content mismatch
6992 set to false by default
6993 children: array of BlockdevRef
6995 the children block devices to use
6996 vote-threshold: int
6998 the vote limit under which a read will fail
6999 rewrite-corrupted: boolean (optional)
7001 rewrite corrupted data when quorum is reached (Since 2.1)
7002 read-pattern: QuorumReadPattern (optional)
7004 choose read pattern and set to quorum by default (Since 2.2)
7005 Since
7007 2.9
7008 BlockdevOptionsGluster (Object)
7010 Driver specific block device options for Gluster
7011 Members
7013 volume: string
7014 name of gluster volume where VM image resides
7015 path: string
7017 absolute path to image file in gluster volume
7018 server: array of SocketAddress
7020 gluster servers description
7021 debug: int (optional)
7023 libgfapi log level (default '4' which is Error) (Since 2.8)
7024 logfile: string (optional)
7026 libgfapi log file (default /dev/stderr) (Since 2.8)
7027 Since
7029 2.9
7030 BlockdevOptionsIoUring (Object)
7032 Driver specific block device options for the io_uring backend.
7033 Members
7035 filename: string
7036 path to the image file
7037 Since
7039 7.2
7040 If
7042 CONFIG_BLKIO
7043 BlockdevOptionsNvmeIoUring (Object)
7045 Driver specific block device options for the nvme-io_uring backend.
7046 Members
7048 path: string
7049 path to the NVMe namespace's character device (e.g. /dev/ng0n1).
7050 Since
7052 7.2
7053 If
7055 CONFIG_BLKIO
7056 BlockdevOptionsVirtioBlkVfioPci (Object)
7058 Driver specific block device options for the virtio-blk-vfio-pci back‐
7059 end.
7060 Members
7062 path: string
7063 path to the PCI device's sysfs directory (e.g. /sys/bus/pci/de‐
7064 vices/0000:00:01.0).
7065 Since
7067 7.2
7068 If
7070 CONFIG_BLKIO
7071 BlockdevOptionsVirtioBlkVhostUser (Object)
7073 Driver specific block device options for the virtio-blk-vhost-user
7074 backend.
7075 Members
7077 path: string
7078 path to the vhost-user UNIX domain socket.
7079 Since
7081 7.2
7082 If
7084 CONFIG_BLKIO
7085 BlockdevOptionsVirtioBlkVhostVdpa (Object)
7087 Driver specific block device options for the virtio-blk-vhost-vdpa
7088 backend.
7089 Members
7091 path: string
7092 path to the vhost-vdpa character device.
7093 Since
7095 7.2
7096 If
7098 CONFIG_BLKIO
7099 IscsiTransport (Enum)
7101 An enumeration of libiscsi transport types
7102 Values
7104 tcp Not documented
7105 iser Not documented
7107 Since
7109 2.9
7110 IscsiHeaderDigest (Enum)
7112 An enumeration of header digests supported by libiscsi
7113 Values
7115 crc32c Not documented
7116 none Not documented
7118 crc32c-none
7120 Not documented
7121 none-crc32c
7123 Not documented
7124 Since
7126 2.9
7127 BlockdevOptionsIscsi (Object)
7129 Members
7130 transport: IscsiTransport
7131 The iscsi transport type
7132 portal: string
7134 The address of the iscsi portal
7135 target: string
7137 The target iqn name
7138 lun: int (optional)
7140 LUN to connect to. Defaults to 0.
7141 user: string (optional)
7143 User name to log in with. If omitted, no CHAP authentication is
7144 performed.
7145 password-secret: string (optional)
7147 The ID of a QCryptoSecret object providing the password for the
7148 login. This option is required if user is specified.
7149 initiator-name: string (optional)
7151 The iqn name we want to identify to the target as. If this op‐
7152 tion is not specified, an initiator name is generated automati‐
7153 cally.
7154 header-digest: IscsiHeaderDigest (optional)
7156 The desired header digest. Defaults to none-crc32c.
7157 timeout: int (optional)
7159 Timeout in seconds after which a request will timeout. 0 means
7160 no timeout and is the default.
7161 Driver specific block device options for iscsi
7162 Since
7164 2.9
7165 RbdAuthMode (Enum)
7167 Values
7168 cephx Not documented
7169 none Not documented
7171 Since
7173 3.0
7174 RbdImageEncryptionFormat (Enum)
7176 Values
7177 luks Not documented
7178 luks2 Not documented
7180 Since
7182 6.1
7183 RbdEncryptionOptionsLUKSBase (Object)
7185 Members
7186 key-secret: string
7187 ID of a QCryptoSecret object providing a passphrase for unlock‐
7188 ing the encryption
7189 Since
7191 6.1
7192 RbdEncryptionCreateOptionsLUKSBase (Object)
7194 Members
7195 cipher-alg: QCryptoCipherAlgorithm (optional)
7196 The encryption algorithm
7197 The members of RbdEncryptionOptionsLUKSBase
7199 Since
7201 6.1
7202 RbdEncryptionOptionsLUKS (Object)
7204 Members
7205 The members of RbdEncryptionOptionsLUKSBase
7206 Since
7208 6.1
7209 RbdEncryptionOptionsLUKS2 (Object)
7211 Members
7212 The members of RbdEncryptionOptionsLUKSBase
7213 Since
7215 6.1
7216 RbdEncryptionCreateOptionsLUKS (Object)
7218 Members
7219 The members of RbdEncryptionCreateOptionsLUKSBase
7220 Since
7222 6.1
7223 RbdEncryptionCreateOptionsLUKS2 (Object)
7225 Members
7226 The members of RbdEncryptionCreateOptionsLUKSBase
7227 Since
7229 6.1
7230 RbdEncryptionOptions (Object)
7232 Members
7233 format: RbdImageEncryptionFormat
7234 Not documented
7235 The members of RbdEncryptionOptionsLUKS when format is "luks"
7237 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
7239 Since
7241 6.1
7242 RbdEncryptionCreateOptions (Object)
7244 Members
7245 format: RbdImageEncryptionFormat
7246 Not documented
7247 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
7249 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
7251 Since
7253 6.1
7254 BlockdevOptionsRbd (Object)
7256 Members
7257 pool: string
7258 Ceph pool name.
7259 namespace: string (optional)
7261 Rados namespace name in the Ceph pool. (Since 5.0)
7262 image: string
7264 Image name in the Ceph pool.
7265 conf: string (optional)
7267 path to Ceph configuration file. Values in the configuration
7268 file will be overridden by options specified via QAPI.
7269 snapshot: string (optional)
7271 Ceph snapshot name.
7272 encrypt: RbdEncryptionOptions (optional)
7274 Image encryption options. (Since 6.1)
7275 user: string (optional)
7277 Ceph id name.
7278 auth-client-required: array of RbdAuthMode (optional)
7280 Acceptable authentication modes. This maps to Ceph configura‐
7281 tion option "auth_client_required". (Since 3.0)
7282 key-secret: string (optional)
7284 ID of a QCryptoSecret object providing a key for cephx authenti‐
7285 cation. This maps to Ceph configuration option "key". (Since
7286 3.0)
7287 server: array of InetSocketAddressBase (optional)
7289 Monitor host address and port. This maps to the "mon_host" Ceph
7290 option.
7291 Since
7293 2.9
7294 ReplicationMode (Enum)
7296 An enumeration of replication modes.
7297 Values
7299 primary
7300 Primary mode, the vm's state will be sent to secondary QEMU.
7301 secondary
7303 Secondary mode, receive the vm's state from primary QEMU.
7304 Since
7306 2.9
7307 If
7309 CONFIG_REPLICATION
7310 BlockdevOptionsReplication (Object)
7312 Driver specific block device options for replication
7313 Members
7315 mode: ReplicationMode
7316 the replication mode
7317 top-id: string (optional)
7319 In secondary mode, node name or device ID of the root node who
7320 owns the replication node chain. Must not be given in primary
7321 mode.
7322 The members of BlockdevOptionsGenericFormat
7324 Since
7326 2.9
7327 If
7329 CONFIG_REPLICATION
7330 NFSTransport (Enum)
7332 An enumeration of NFS transport types
7333 Values
7335 inet TCP transport
7336 Since
7338 2.9
7339 NFSServer (Object)
7341 Captures the address of the socket
7342 Members
7344 type: NFSTransport
7345 transport type used for NFS (only TCP supported)
7346 host: string
7348 host address for NFS server
7349 Since
7351 2.9
7352 BlockdevOptionsNfs (Object)
7354 Driver specific block device option for NFS
7355 Members
7357 server: NFSServer
7358 host address
7359 path: string
7361 path of the image on the host
7362 user: int (optional)
7364 UID value to use when talking to the server (defaults to 65534
7365 on Windows and getuid() on unix)
7366 group: int (optional)
7368 GID value to use when talking to the server (defaults to 65534
7369 on Windows and getgid() in unix)
7370 tcp-syn-count: int (optional)
7372 number of SYNs during the session establishment (defaults to
7373 libnfs default)
7374 readahead-size: int (optional)
7376 set the readahead size in bytes (defaults to libnfs default)
7377 page-cache-size: int (optional)
7379 set the pagecache size in bytes (defaults to libnfs default)
7380 debug: int (optional)
7382 set the NFS debug level (max 2) (defaults to libnfs default)
7383 Since
7385 2.9
7386 BlockdevOptionsCurlBase (Object)
7388 Driver specific block device options shared by all protocols supported
7389 by the curl backend.
7390 Members
7392 url: string
7393 URL of the image file
7394 readahead: int (optional)
7396 Size of the read-ahead cache; must be a multiple of 512 (de‐
7397 faults to 256 kB)
7398 timeout: int (optional)
7400 Timeout for connections, in seconds (defaults to 5)
7401 username: string (optional)
7403 Username for authentication (defaults to none)
7404 password-secret: string (optional)
7406 ID of a QCryptoSecret object providing a password for authenti‐
7407 cation (defaults to no password)
7408 proxy-username: string (optional)
7410 Username for proxy authentication (defaults to none)
7411 proxy-password-secret: string (optional)
7413 ID of a QCryptoSecret object providing a password for proxy au‐
7414 thentication (defaults to no password)
7415 Since
7417 2.9
7418 BlockdevOptionsCurlHttp (Object)
7420 Driver specific block device options for HTTP connections over the curl
7421 backend. URLs must start with "http://".
7422 Members
7424 cookie: string (optional)
7425 List of cookies to set; format is "name1=content1; name2=con‐
7426 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
7427 ies.
7428 cookie-secret: string (optional)
7430 ID of a QCryptoSecret object providing the cookie data in a se‐
7431 cure way. See cookie for the format. (since 2.10)
7432 The members of BlockdevOptionsCurlBase
7434 Since
7436 2.9
7437 BlockdevOptionsCurlHttps (Object)
7439 Driver specific block device options for HTTPS connections over the
7440 curl backend. URLs must start with "https://".
7441 Members
7443 cookie: string (optional)
7444 List of cookies to set; format is "name1=content1; name2=con‐
7445 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
7446 ies.
7447 sslverify: boolean (optional)
7449 Whether to verify the SSL certificate's validity (defaults to
7450 true)
7451 cookie-secret: string (optional)
7453 ID of a QCryptoSecret object providing the cookie data in a se‐
7454 cure way. See cookie for the format. (since 2.10)
7455 The members of BlockdevOptionsCurlBase
7457 Since
7459 2.9
7460 BlockdevOptionsCurlFtp (Object)
7462 Driver specific block device options for FTP connections over the curl
7463 backend. URLs must start with "ftp://".
7464 Members
7466 The members of BlockdevOptionsCurlBase
7467 Since
7469 2.9
7470 BlockdevOptionsCurlFtps (Object)
7472 Driver specific block device options for FTPS connections over the curl
7473 backend. URLs must start with "ftps://".
7474 Members
7476 sslverify: boolean (optional)
7477 Whether to verify the SSL certificate's validity (defaults to
7478 true)
7479 The members of BlockdevOptionsCurlBase
7481 Since
7483 2.9
7484 BlockdevOptionsNbd (Object)
7486 Driver specific block device options for NBD.
7487 Members
7489 server: SocketAddress
7490 NBD server address
7491 export: string (optional)
7493 export name
7494 tls-creds: string (optional)
7496 TLS credentials ID
7497 tls-hostname: string (optional)
7499 TLS hostname override for certificate validation (Since 7.0)
7500 x-dirty-bitmap: string (optional)
7502 A metadata context name such as "qemu:dirty-bitmap:NAME" or
7503 "qemu:allocation-depth" to query in place of the traditional
7504 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
7505 the NBD protocol; and yes, naming this option x-context would
7506 have made more sense) (since 3.0)
7507 reconnect-delay: int (optional)
7509 On an unexpected disconnect, the nbd client tries to connect
7510 again until succeeding or encountering a serious error. During
7511 the first reconnect-delay seconds, all requests are paused and
7512 will be rerun on a successful reconnect. After that time, any
7513 delayed requests and all future requests before a successful re‐
7514 connect will immediately fail. Default 0 (Since 4.2)
7515 open-timeout: int (optional)
7517 In seconds. If zero, the nbd driver tries the connection only
7518 once, and fails to open if the connection fails. If non-zero,
7519 the nbd driver will repeat connection attempts until successful
7520 or until open-timeout seconds have elapsed. Default 0 (Since
7521 7.0)
7522 Features
7524 unstable
7525 Member x-dirty-bitmap is experimental.
7526 Since
7528 2.9
7529 BlockdevOptionsRaw (Object)
7531 Driver specific block device options for the raw driver.
7532 Members
7534 offset: int (optional)
7535 position where the block device starts
7536 size: int (optional)
7538 the assumed size of the device
7539 The members of BlockdevOptionsGenericFormat
7541 Since
7543 2.9
7544 BlockdevOptionsThrottle (Object)
7546 Driver specific block device options for the throttle driver
7547 Members
7549 throttle-group: string
7550 the name of the throttle-group object to use. It must already
7551 exist.
7552 file: BlockdevRef
7554 reference to or definition of the data source block device
7555 Since
7557 2.11
7558 BlockdevOptionsCor (Object)
7560 Driver specific block device options for the copy-on-read driver.
7561 Members
7563 bottom: string (optional)
7564 The name of a non-filter node (allocation-bearing layer) that
7565 limits the COR operations in the backing chain (inclusive), so
7566 that no data below this node will be copied by this filter. If
7567 option is absent, the limit is not applied, so that data from
7568 all backing layers may be copied.
7569 The members of BlockdevOptionsGenericFormat
7571 Since
7573 6.0
7574 OnCbwError (Enum)
7576 An enumeration of possible behaviors for copy-before-write operation
7577 failures.
7578 Values
7580 break-guest-write
7581 report the error to the guest. This way, the guest will not be
7582 able to overwrite areas that cannot be backed up, so the backup
7583 process remains valid.
7584 break-snapshot
7586 continue guest write. Doing so will make the provided snapshot
7587 state invalid and any backup or export process based on it will
7588 finally fail.
7589 Since
7591 7.1
7592 BlockdevOptionsCbw (Object)
7594 Driver specific block device options for the copy-before-write driver,
7595 which does so called copy-before-write operations: when data is written
7596 to the filter, the filter first reads corresponding blocks from its
7597 file child and copies them to target child. After successfully copying,
7598 the write request is propagated to file child. If copying fails, the
7599 original write request is failed too and no data is written to file
7600 child.
7601 Members
7603 target: BlockdevRef
7604 The target for copy-before-write operations.
7605 bitmap: BlockDirtyBitmap (optional)
7607 If specified, copy-before-write filter will do copy-before-write
7608 operations only for dirty regions of the bitmap. Bitmap size
7609 must be equal to length of file and target child of the filter.
7610 Note also, that bitmap is used only to initialize internal bit‐
7611 map of the process, so further modifications (or removing) of
7612 specified bitmap doesn't influence the filter. (Since 7.0)
7613 on-cbw-error: OnCbwError (optional)
7615 Behavior on failure of copy-before-write operation. Default is
7616 break-guest-write. (Since 7.1)
7617 cbw-timeout: int (optional)
7619 Zero means no limit. Non-zero sets the timeout in seconds for
7620 copy-before-write operation. When a timeout occurs, the respec‐
7621 tive copy-before-write operation will fail, and the on-cbw-error
7622 parameter will decide how this failure is handled. Default 0.
7623 (Since 7.1)
7624 The members of BlockdevOptionsGenericFormat
7626 Since
7628 6.2
7629 BlockdevOptions (Object)
7631 Options for creating a block device. Many options are available for
7632 all block devices, independent of the block driver:
7633 Members
7635 driver: BlockdevDriver
7636 block driver name
7637 node-name: string (optional)
7639 the node name of the new node (Since 2.0). This option is re‐
7640 quired on the top level of blockdev-add. Valid node names start
7641 with an alphabetic character and may contain only alphanumeric
7642 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
7643 ters.
7644 discard: BlockdevDiscardOptions (optional)
7646 discard-related options (default: ignore)
7647 cache: BlockdevCacheOptions (optional)
7649 cache-related options
7650 read-only: boolean (optional)
7652 whether the block device should be read-only (default: false).
7653 Note that some block drivers support only read-only access, ei‐
7654 ther generally or in certain configurations. In this case, the
7655 default value does not work and the option must be specified ex‐
7656 plicitly.
7657 auto-read-only: boolean (optional)
7659 if true and read-only is false, QEMU may automatically decide
7660 not to open the image read-write as requested, but fall back to
7661 read-only instead (and switch between the modes later), e.g. de‐
7662 pending on whether the image file is writable or whether a writ‐
7663 ing user is attached to the node (default: false, since 3.1)
7664 detect-zeroes: BlockdevDetectZeroesOptions (optional)
7666 detect and optimize zero writes (Since 2.1) (default: off)
7667 force-share: boolean (optional)
7669 force share all permission on added nodes. Requires
7670 read-only=true. (Since 2.10)
7671 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
7673 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
7675 writes"
7676 The members of BlockdevOptionsBlkverify when driver is "blkverify"
7678 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
7680 The members of BlockdevOptionsGenericFormat when driver is "bochs"
7682 The members of BlockdevOptionsGenericFormat when driver is "cloop"
7684 The members of BlockdevOptionsGenericFormat when driver is "compress"
7686 The members of BlockdevOptionsCbw when driver is "copy-before-write"
7688 The members of BlockdevOptionsCor when driver is "copy-on-read"
7690 The members of BlockdevOptionsGenericFormat when driver is "dmg"
7692 The members of BlockdevOptionsFile when driver is "file"
7694 The members of BlockdevOptionsCurlFtp when driver is "ftp"
7696 The members of BlockdevOptionsCurlFtps when driver is "ftps"
7698 The members of BlockdevOptionsGluster when driver is "gluster"
7700 The members of BlockdevOptionsFile when driver is "host_cdrom" (If:
7702 HAVE_HOST_BLOCK_DEVICE)
7703 The members of BlockdevOptionsFile when driver is "host_device" (If:
7705 HAVE_HOST_BLOCK_DEVICE)
7706 The members of BlockdevOptionsCurlHttp when driver is "http"
7708 The members of BlockdevOptionsCurlHttps when driver is "https"
7710 The members of BlockdevOptionsIoUring when driver is "io_uring" (If:
7712 CONFIG_BLKIO)
7713 The members of BlockdevOptionsIscsi when driver is "iscsi"
7715 The members of BlockdevOptionsLUKS when driver is "luks"
7717 The members of BlockdevOptionsNbd when driver is "nbd"
7719 The members of BlockdevOptionsNfs when driver is "nfs"
7721 The members of BlockdevOptionsNull when driver is "null-aio"
7723 The members of BlockdevOptionsNull when driver is "null-co"
7725 The members of BlockdevOptionsNVMe when driver is "nvme"
7727 The members of BlockdevOptionsNvmeIoUring when driver is "nvme-io_ur‐
7729 ing" (If: CONFIG_BLKIO)
7730 The members of BlockdevOptionsGenericFormat when driver is "parallels"
7732 The members of BlockdevOptionsPreallocate when driver is "preallocate"
7734 The members of BlockdevOptionsQcow2 when driver is "qcow2"
7736 The members of BlockdevOptionsQcow when driver is "qcow"
7738 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
7740 The members of BlockdevOptionsQuorum when driver is "quorum"
7742 The members of BlockdevOptionsRaw when driver is "raw"
7744 The members of BlockdevOptionsRbd when driver is "rbd"
7746 The members of BlockdevOptionsReplication when driver is "replication"
7748 (If: CONFIG_REPLICATION)
7749 The members of BlockdevOptionsGenericFormat when driver is "snap‐
7751 shot-access"
7752 The members of BlockdevOptionsSsh when driver is "ssh"
7754 The members of BlockdevOptionsThrottle when driver is "throttle"
7756 The members of BlockdevOptionsGenericFormat when driver is "vdi"
7758 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
7760 The members of BlockdevOptionsVirtioBlkVfioPci when driver is "vir‐
7762 tio-blk-vfio-pci" (If: CONFIG_BLKIO)
7763 The members of BlockdevOptionsVirtioBlkVhostUser when driver is "vir‐
7765 tio-blk-vhost-user" (If: CONFIG_BLKIO)
7766 The members of BlockdevOptionsVirtioBlkVhostVdpa when driver is "vir‐
7768 tio-blk-vhost-vdpa" (If: CONFIG_BLKIO)
7769 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
7771 The members of BlockdevOptionsGenericFormat when driver is "vpc"
7773 The members of BlockdevOptionsVVFAT when driver is "vvfat"
7775 Remaining options are determined by the block driver.
7776 Since
7778 2.9
7779 BlockdevRef (Alternate)
7781 Reference to a block device.
7782 Members
7784 definition: BlockdevOptions
7785 defines a new block device inline
7786 reference: string
7788 references the ID of an existing block device
7789 Since
7791 2.9
7792 BlockdevRefOrNull (Alternate)
7794 Reference to a block device.
7795 Members
7797 definition: BlockdevOptions
7798 defines a new block device inline
7799 reference: string
7801 references the ID of an existing block device. An empty string
7802 means that no block device should be referenced. Deprecated;
7803 use null instead.
7804 null: null
7806 No block device should be referenced (since 2.10)
7807 Since
7809 2.9
7810 blockdev-add (Command)
7812 Creates a new block device.
7813 Arguments
7815 The members of BlockdevOptions
7816 Since
7818 2.9
7819 Example
7821 1.
7822 -> { "execute": "blockdev-add",
7823 "arguments": {
7824 "driver": "qcow2",
7825 "node-name": "test1",
7826 "file": {
7827 "driver": "file",
7828 "filename": "test.qcow2"
7829 }
7830 }
7831 }
7832 <- { "return": {} }
7833 2.
7835 -> { "execute": "blockdev-add",
7836 "arguments": {
7837 "driver": "qcow2",
7838 "node-name": "node0",
7839 "discard": "unmap",
7840 "cache": {
7841 "direct": true
7842 },
7843 "file": {
7844 "driver": "file",
7845 "filename": "/tmp/test.qcow2"
7846 },
7847 "backing": {
7848 "driver": "raw",
7849 "file": {
7850 "driver": "file",
7851 "filename": "/dev/fdset/4"
7852 }
7853 }
7854 }
7855 }
7856 <- { "return": {} }
7858 blockdev-reopen (Command)
7860 Reopens one or more block devices using the given set of options. Any
7861 option not specified will be reset to its default value regardless of
7862 its previous status. If an option cannot be changed or a particular
7863 driver does not support reopening then the command will return an er‐
7864 ror. All devices in the list are reopened in one transaction, so if one
7865 of them fails then the whole transaction is cancelled.
7866 The command receives a list of block devices to reopen. For each one of
7868 them, the top-level node-name option (from BlockdevOptions) must be
7869 specified and is used to select the block device to be reopened. Other
7870 node-name options must be either omitted or set to the current name of
7871 the appropriate node. This command won't change any node name and any
7872 attempt to do it will result in an error.
7873 In the case of options that refer to child nodes, the behavior of this
7875 command depends on the value:
7876 1. A set of options (BlockdevOptions): the child is reopened with
7878 the specified set of options.
7879 2. A reference to the current child: the child is reopened using its
7881 existing set of options.
7882 3. A reference to a different node: the current child is replaced
7884 with the specified one.
7885 4. NULL: the current child (if any) is detached.
7887 Options (1) and (2) are supported in all cases. Option (3) is supported
7889 for file and backing, and option (4) for backing only.
7890 Unlike with blockdev-add, the backing option must always be present un‐
7892 less the node being reopened does not have a backing file and its image
7893 does not have a default backing file name as part of its metadata.
7894 Arguments
7896 options: array of BlockdevOptions
7897 Not documented
7898 Since
7900 6.1
7901 blockdev-del (Command)
7903 Deletes a block device that has been added using blockdev-add. The
7904 command will fail if the node is attached to a device or is otherwise
7905 being used.
7906 Arguments
7908 node-name: string
7909 Name of the graph node to delete.
7910 Since
7912 2.9
7913 Example
7915 -> { "execute": "blockdev-add",
7916 "arguments": {
7917 "driver": "qcow2",
7918 "node-name": "node0",
7919 "file": {
7920 "driver": "file",
7921 "filename": "test.qcow2"
7922 }
7923 }
7924 }
7925 <- { "return": {} }
7926 -> { "execute": "blockdev-del",
7928 "arguments": { "node-name": "node0" }
7929 }
7930 <- { "return": {} }
7931 BlockdevCreateOptionsFile (Object)
7933 Driver specific image creation options for file.
7934 Members
7936 filename: string
7937 Filename for the new image file
7938 size: int
7940 Size of the virtual disk in bytes
7941 preallocation: PreallocMode (optional)
7943 Preallocation mode for the new image (default: off; allowed val‐
7944 ues: off, falloc (if CONFIG_POSIX_FALLOCATE), full (if CON‐
7945 FIG_POSIX))
7946 nocow: boolean (optional)
7948 Turn off copy-on-write (valid only on btrfs; default: off)
7949 extent-size-hint: int (optional)
7951 Extent size hint to add to the image file; 0 for not adding an
7952 extent size hint (default: 1 MB, since 5.1)
7953 Since
7955 2.12
7956 BlockdevCreateOptionsGluster (Object)
7958 Driver specific image creation options for gluster.
7959 Members
7961 location: BlockdevOptionsGluster
7962 Where to store the new image file
7963 size: int
7965 Size of the virtual disk in bytes
7966 preallocation: PreallocMode (optional)
7968 Preallocation mode for the new image (default: off; allowed val‐
7969 ues: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), full (if CON‐
7970 FIG_GLUSTERFS_ZEROFILL))
7971 Since
7973 2.12
7974 BlockdevCreateOptionsLUKS (Object)
7976 Driver specific image creation options for LUKS.
7977 Members
7979 file: BlockdevRef
7980 Node to create the image format on
7981 size: int
7983 Size of the virtual disk in bytes
7984 preallocation: PreallocMode (optional)
7986 Preallocation mode for the new image (since: 4.2) (default: off;
7987 allowed values: off, metadata, falloc, full)
7988 The members of QCryptoBlockCreateOptionsLUKS
7990 Since
7992 2.12
7993 BlockdevCreateOptionsNfs (Object)
7995 Driver specific image creation options for NFS.
7996 Members
7998 location: BlockdevOptionsNfs
7999 Where to store the new image file
8000 size: int
8002 Size of the virtual disk in bytes
8003 Since
8005 2.12
8006 BlockdevCreateOptionsParallels (Object)
8008 Driver specific image creation options for parallels.
8009 Members
8011 file: BlockdevRef
8012 Node to create the image format on
8013 size: int
8015 Size of the virtual disk in bytes
8016 cluster-size: int (optional)
8018 Cluster size in bytes (default: 1 MB)
8019 Since
8021 2.12
8022 BlockdevCreateOptionsQcow (Object)
8024 Driver specific image creation options for qcow.
8025 Members
8027 file: BlockdevRef
8028 Node to create the image format on
8029 size: int
8031 Size of the virtual disk in bytes
8032 backing-file: string (optional)
8034 File name of the backing file if a backing file should be used
8035 encrypt: QCryptoBlockCreateOptions (optional)
8037 Encryption options if the image should be encrypted
8038 Since
8040 2.12
8041 BlockdevQcow2Version (Enum)
8043 Values
8044 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
8045 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
8047 Since
8049 2.12
8050 Qcow2CompressionType (Enum)
8052 Compression type used in qcow2 image file
8053 Values
8055 zlib zlib compression, see <http://zlib.net/>
8056 zstd (If: CONFIG_ZSTD)
8058 zstd compression, see <http://github.com/facebook/zstd>
8059 Since
8061 5.1
8062 BlockdevCreateOptionsQcow2 (Object)
8064 Driver specific image creation options for qcow2.
8065 Members
8067 file: BlockdevRef
8068 Node to create the image format on
8069 data-file: BlockdevRef (optional)
8071 Node to use as an external data file in which all guest data is
8072 stored so that only metadata remains in the qcow2 file (since:
8073 4.0)
8074 data-file-raw: boolean (optional)
8076 True if the external data file must stay valid as a standalone
8077 (read-only) raw image without looking at qcow2 metadata (de‐
8078 fault: false; since: 4.0)
8079 extended-l2: boolean (optional)
8081 True to make the image have extended L2 entries (default: false;
8082 since 5.2)
8083 size: int
8085 Size of the virtual disk in bytes
8086 version: BlockdevQcow2Version (optional)
8088 Compatibility level (default: v3)
8089 backing-file: string (optional)
8091 File name of the backing file if a backing file should be used
8092 backing-fmt: BlockdevDriver (optional)
8094 Name of the block driver to use for the backing file
8095 encrypt: QCryptoBlockCreateOptions (optional)
8097 Encryption options if the image should be encrypted
8098 cluster-size: int (optional)
8100 qcow2 cluster size in bytes (default: 65536)
8101 preallocation: PreallocMode (optional)
8103 Preallocation mode for the new image (default: off; allowed val‐
8104 ues: off, falloc, full, metadata)
8105 lazy-refcounts: boolean (optional)
8107 True if refcounts may be updated lazily (default: off)
8108 refcount-bits: int (optional)
8110 Width of reference counts in bits (default: 16)
8111 compression-type: Qcow2CompressionType (optional)
8113 The image cluster compression method (default: zlib, since 5.1)
8114 Since
8116 2.12
8117 BlockdevCreateOptionsQed (Object)
8119 Driver specific image creation options for qed.
8120 Members
8122 file: BlockdevRef
8123 Node to create the image format on
8124 size: int
8126 Size of the virtual disk in bytes
8127 backing-file: string (optional)
8129 File name of the backing file if a backing file should be used
8130 backing-fmt: BlockdevDriver (optional)
8132 Name of the block driver to use for the backing file
8133 cluster-size: int (optional)
8135 Cluster size in bytes (default: 65536)
8136 table-size: int (optional)
8138 L1/L2 table size (in clusters)
8139 Since
8141 2.12
8142 BlockdevCreateOptionsRbd (Object)
8144 Driver specific image creation options for rbd/Ceph.
8145 Members
8147 location: BlockdevOptionsRbd
8148 Where to store the new image file. This location cannot point to
8149 a snapshot.
8150 size: int
8152 Size of the virtual disk in bytes
8153 cluster-size: int (optional)
8155 RBD object size
8156 encrypt: RbdEncryptionCreateOptions (optional)
8158 Image encryption options. (Since 6.1)
8159 Since
8161 2.12
8162 BlockdevVmdkSubformat (Enum)
8164 Subformat options for VMDK images
8165 Values
8167 monolithicSparse
8168 Single file image with sparse cluster allocation
8169 monolithicFlat
8171 Single flat data image and a descriptor file
8172 twoGbMaxExtentSparse
8174 Data is split into 2GB (per virtual LBA) sparse extent files, in
8175 addition to a descriptor file
8176 twoGbMaxExtentFlat
8178 Data is split into 2GB (per virtual LBA) flat extent files, in
8179 addition to a descriptor file
8180 streamOptimized
8182 Single file image sparse cluster allocation, optimized for
8183 streaming over network.
8184 Since
8186 4.0
8187 BlockdevVmdkAdapterType (Enum)
8189 Adapter type info for VMDK images
8190 Values
8192 ide Not documented
8193 buslogic
8195 Not documented
8196 lsilogic
8198 Not documented
8199 legacyESX
8201 Not documented
8202 Since
8204 4.0
8205 BlockdevCreateOptionsVmdk (Object)
8207 Driver specific image creation options for VMDK.
8208 Members
8210 file: BlockdevRef
8211 Where to store the new image file. This refers to the image file
8212 for monolithcSparse and streamOptimized format, or the descrip‐
8213 tor file for other formats.
8214 size: int
8216 Size of the virtual disk in bytes
8217 extents: array of BlockdevRef (optional)
8219 Where to store the data extents. Required for monolithcFlat,
8220 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
8221 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
8222 mats, the number of entries required is calculated as ex‐
8223 tent_number = virtual_size / 2GB. Providing more extents than
8224 will be used is an error.
8225 subformat: BlockdevVmdkSubformat (optional)
8227 The subformat of the VMDK image. Default: "monolithicSparse".
8228 backing-file: string (optional)
8230 The path of backing file. Default: no backing file is used.
8231 adapter-type: BlockdevVmdkAdapterType (optional)
8233 The adapter type used to fill in the descriptor. Default: ide.
8234 hwversion: string (optional)
8236 Hardware version. The meaningful options are "4" or "6". De‐
8237 fault: "4".
8238 toolsversion: string (optional)
8240 VMware guest tools version. Default: "2147483647" (Since 6.2)
8241 zeroed-grain: boolean (optional)
8243 Whether to enable zeroed-grain feature for sparse subformats.
8244 Default: false.
8245 Since
8247 4.0
8248 BlockdevCreateOptionsSsh (Object)
8250 Driver specific image creation options for SSH.
8251 Members
8253 location: BlockdevOptionsSsh
8254 Where to store the new image file
8255 size: int
8257 Size of the virtual disk in bytes
8258 Since
8260 2.12
8261 BlockdevCreateOptionsVdi (Object)
8263 Driver specific image creation options for VDI.
8264 Members
8266 file: BlockdevRef
8267 Node to create the image format on
8268 size: int
8270 Size of the virtual disk in bytes
8271 preallocation: PreallocMode (optional)
8273 Preallocation mode for the new image (default: off; allowed val‐
8274 ues: off, metadata)
8275 Since
8277 2.12
8278 BlockdevVhdxSubformat (Enum)
8280 Values
8281 dynamic
8282 Growing image file
8283 fixed Preallocated fixed-size image file
8285 Since
8287 2.12
8288 BlockdevCreateOptionsVhdx (Object)
8290 Driver specific image creation options for vhdx.
8291 Members
8293 file: BlockdevRef
8294 Node to create the image format on
8295 size: int
8297 Size of the virtual disk in bytes
8298 log-size: int (optional)
8300 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
8301 block-size: int (optional)
8303 Block size in bytes, must be a multiple of 1 MB and not larger
8304 than 256 MB (default: automatically choose a block size depend‐
8305 ing on the image size)
8306 subformat: BlockdevVhdxSubformat (optional)
8308 vhdx subformat (default: dynamic)
8309 block-state-zero: boolean (optional)
8311 Force use of payload blocks of type 'ZERO'. Non-standard, but
8312 default. Do not set to 'off' when using 'qemu-img convert' with
8313 subformat=dynamic.
8314 Since
8316 2.12
8317 BlockdevVpcSubformat (Enum)
8319 Values
8320 dynamic
8321 Growing image file
8322 fixed Preallocated fixed-size image file
8324 Since
8326 2.12
8327 BlockdevCreateOptionsVpc (Object)
8329 Driver specific image creation options for vpc (VHD).
8330 Members
8332 file: BlockdevRef
8333 Node to create the image format on
8334 size: int
8336 Size of the virtual disk in bytes
8337 subformat: BlockdevVpcSubformat (optional)
8339 vhdx subformat (default: dynamic)
8340 force-size: boolean (optional)
8342 Force use of the exact byte size instead of rounding to the next
8343 size that can be represented in CHS geometry (default: false)
8344 Since
8346 2.12
8347 BlockdevCreateOptions (Object)
8349 Options for creating an image format on a given node.
8350 Members
8352 driver: BlockdevDriver
8353 block driver to create the image format
8354 The members of BlockdevCreateOptionsFile when driver is "file"
8356 The members of BlockdevCreateOptionsGluster when driver is "gluster"
8358 The members of BlockdevCreateOptionsLUKS when driver is "luks"
8360 The members of BlockdevCreateOptionsNfs when driver is "nfs"
8362 The members of BlockdevCreateOptionsParallels when driver is "paral‐
8364 lels"
8365 The members of BlockdevCreateOptionsQcow when driver is "qcow"
8367 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
8369 The members of BlockdevCreateOptionsQed when driver is "qed"
8371 The members of BlockdevCreateOptionsRbd when driver is "rbd"
8373 The members of BlockdevCreateOptionsSsh when driver is "ssh"
8375 The members of BlockdevCreateOptionsVdi when driver is "vdi"
8377 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
8379 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
8381 The members of BlockdevCreateOptionsVpc when driver is "vpc"
8383 Since
8385 2.12
8386 blockdev-create (Command)
8388 Starts a job to create an image format on a given node. The job is au‐
8389 tomatically finalized, but a manual job-dismiss is required.
8390 Arguments
8392 job-id: string
8393 Identifier for the newly created job.
8394 options: BlockdevCreateOptions
8396 Options for the image creation.
8397 Since
8399 3.0
8400 BlockdevAmendOptionsLUKS (Object)
8402 Driver specific image amend options for LUKS.
8403 Members
8405 The members of QCryptoBlockAmendOptionsLUKS
8406 Since
8408 5.1
8409 BlockdevAmendOptionsQcow2 (Object)
8411 Driver specific image amend options for qcow2. For now, only encryp‐
8412 tion options can be amended
8413 encrypt Encryption options to be amended
8415 Members
8417 encrypt: QCryptoBlockAmendOptions (optional)
8418 Not documented
8419 Since
8421 5.1
8422 BlockdevAmendOptions (Object)
8424 Options for amending an image format
8425 Members
8427 driver: BlockdevDriver
8428 Block driver of the node to amend.
8429 The members of BlockdevAmendOptionsLUKS when driver is "luks"
8431 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
8433 Since
8435 5.1
8436 x-blockdev-amend (Command)
8438 Starts a job to amend format specific options of an existing open block
8439 device The job is automatically finalized, but a manual job-dismiss is
8440 required.
8441 Arguments
8443 job-id: string
8444 Identifier for the newly created job.
8445 node-name: string
8447 Name of the block node to work on
8448 options: BlockdevAmendOptions
8450 Options (driver specific)
8451 force: boolean (optional)
8453 Allow unsafe operations, format specific For luks that allows
8454 erase of the last active keyslot (permanent loss of data), and
8455 replacement of an active keyslot (possible loss of data if IO
8456 error happens)
8457 Features
8459 unstable
8460 This command is experimental.
8461 Since
8463 5.1
8464 BlockErrorAction (Enum)
8466 An enumeration of action that has been taken when a DISK I/O occurs
8467 Values
8469 ignore error has been ignored
8470 report error has been reported to the device
8472 stop error caused VM to be stopped
8474 Since
8476 2.1
8477 BLOCK_IMAGE_CORRUPTED (Event)
8479 Emitted when a disk image is being marked corrupt. The image can be
8480 identified by its device or node name. The 'device' field is always
8481 present for compatibility reasons, but it can be empty ("") if the im‐
8482 age does not have a device name associated.
8483 Arguments
8485 device: string
8486 device name. This is always present for compatibility reasons,
8487 but it can be empty ("") if the image does not have a device
8488 name associated.
8489 node-name: string (optional)
8491 node name (Since: 2.4)
8492 msg: string
8494 informative message for human consumption, such as the kind of
8495 corruption being detected. It should not be parsed by machine as
8496 it is not guaranteed to be stable
8497 offset: int (optional)
8499 if the corruption resulted from an image access, this is the
8500 host's access offset into the image
8501 size: int (optional)
8503 if the corruption resulted from an image access, this is the ac‐
8504 cess size
8505 fatal: boolean
8507 if set, the image is marked corrupt and therefore unusable after
8508 this event and must be repaired (Since 2.2; before, every
8509 BLOCK_IMAGE_CORRUPTED event was fatal)
8510 Note
8512 If action is "stop", a STOP event will eventually follow the
8513 BLOCK_IO_ERROR event.
8514 Example
8516 <- { "event": "BLOCK_IMAGE_CORRUPTED",
8517 "data": { "device": "", "node-name": "drive", "fatal": false,
8518 "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
8519 "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }
8520 Since
8522 1.7
8523 BLOCK_IO_ERROR (Event)
8525 Emitted when a disk I/O error occurs
8526 Arguments
8528 device: string
8529 device name. This is always present for compatibility reasons,
8530 but it can be empty ("") if the image does not have a device
8531 name associated.
8532 node-name: string (optional)
8534 node name. Note that errors may be reported for the root node
8535 that is directly attached to a guest device rather than for the
8536 node where the error occurred. The node name is not present if
8537 the drive is empty. (Since: 2.8)
8538 operation: IoOperationType
8540 I/O operation
8541 action: BlockErrorAction
8543 action that has been taken
8544 nospace: boolean (optional)
8546 true if I/O error was caused due to a no-space condition. This
8547 key is only present if query-block's io-status is present,
8548 please see query-block documentation for more information
8549 (since: 2.2)
8550 reason: string
8552 human readable string describing the error cause. (This field
8553 is a debugging aid for humans, it should not be parsed by appli‐
8554 cations) (since: 2.2)
8555 Note
8557 If action is "stop", a STOP event will eventually follow the
8558 BLOCK_IO_ERROR event
8559 Since
8561 0.13
8562 Example
8564 <- { "event": "BLOCK_IO_ERROR",
8565 "data": { "device": "ide0-hd1",
8566 "node-name": "#block212",
8567 "operation": "write",
8568 "action": "stop",
8569 "reason": "No space left on device" },
8570 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8571 BLOCK_JOB_COMPLETED (Event)
8573 Emitted when a block job has completed
8574 Arguments
8576 type: JobType
8577 job type
8578 device: string
8580 The job identifier. Originally the device name but other values
8581 are allowed since QEMU 2.7
8582 len: int
8584 maximum progress value
8585 offset: int
8587 current progress value. On success this is equal to len. On
8588 failure this is less than len
8589 speed: int
8591 rate limit, bytes per second
8592 error: string (optional)
8594 error message. Only present on failure. This field contains a
8595 human-readable error message. There are no semantics other than
8596 that streaming has failed and clients should not try to inter‐
8597 pret the error string
8598 Since
8600 1.1
8601 Example
8603 <- { "event": "BLOCK_JOB_COMPLETED",
8604 "data": { "type": "stream", "device": "virtio-disk0",
8605 "len": 10737418240, "offset": 10737418240,
8606 "speed": 0 },
8607 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
8608 BLOCK_JOB_CANCELLED (Event)
8610 Emitted when a block job has been cancelled
8611 Arguments
8613 type: JobType
8614 job type
8615 device: string
8617 The job identifier. Originally the device name but other values
8618 are allowed since QEMU 2.7
8619 len: int
8621 maximum progress value
8622 offset: int
8624 current progress value. On success this is equal to len. On
8625 failure this is less than len
8626 speed: int
8628 rate limit, bytes per second
8629 Since
8631 1.1
8632 Example
8634 <- { "event": "BLOCK_JOB_CANCELLED",
8635 "data": { "type": "stream", "device": "virtio-disk0",
8636 "len": 10737418240, "offset": 134217728,
8637 "speed": 0 },
8638 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
8639 BLOCK_JOB_ERROR (Event)
8641 Emitted when a block job encounters an error
8642 Arguments
8644 device: string
8645 The job identifier. Originally the device name but other values
8646 are allowed since QEMU 2.7
8647 operation: IoOperationType
8649 I/O operation
8650 action: BlockErrorAction
8652 action that has been taken
8653 Since
8655 1.3
8656 Example
8658 <- { "event": "BLOCK_JOB_ERROR",
8659 "data": { "device": "ide0-hd1",
8660 "operation": "write",
8661 "action": "stop" },
8662 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8663 BLOCK_JOB_READY (Event)
8665 Emitted when a block job is ready to complete
8666 Arguments
8668 type: JobType
8669 job type
8670 device: string
8672 The job identifier. Originally the device name but other values
8673 are allowed since QEMU 2.7
8674 len: int
8676 maximum progress value
8677 offset: int
8679 current progress value. On success this is equal to len. On
8680 failure this is less than len
8681 speed: int
8683 rate limit, bytes per second
8684 Note
8686 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
8687 event
8688 Since
8690 1.3
8691 Example
8693 <- { "event": "BLOCK_JOB_READY",
8694 "data": { "device": "drive0", "type": "mirror", "speed": 0,
8695 "len": 2097152, "offset": 2097152 },
8696 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8697 BLOCK_JOB_PENDING (Event)
8699 Emitted when a block job is awaiting explicit authorization to finalize
8700 graph changes via block-job-finalize. If this job is part of a transac‐
8701 tion, it will not emit this event until the transaction has converged
8702 first.
8703 Arguments
8705 type: JobType
8706 job type
8707 id: string
8709 The job identifier.
8710 Since
8712 2.12
8713 Example
8715 <- { "event": "BLOCK_JOB_PENDING",
8716 "data": { "type": "mirror", "id": "backup_1" },
8717 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8718 PreallocMode (Enum)
8720 Preallocation mode of QEMU image file
8721 Values
8723 off no preallocation
8724 metadata
8726 preallocate only for metadata
8727 falloc like full preallocation but allocate disk space by posix_fallo‐
8729 cate() rather than writing data.
8730 full preallocate all data by writing it to the device to ensure disk
8732 space is really available. This data may or may not be zero, de‐
8733 pending on the image format and storage. full preallocation
8734 also sets up metadata correctly.
8735 Since
8737 2.2
8738 BLOCK_WRITE_THRESHOLD (Event)
8740 Emitted when writes on block device reaches or exceeds the configured
8741 write threshold. For thin-provisioned devices, this means the device
8742 should be extended to avoid pausing for disk exhaustion. The event is
8743 one shot. Once triggered, it needs to be re-registered with another
8744 block-set-write-threshold command.
8745 Arguments
8747 node-name: string
8748 graph node name on which the threshold was exceeded.
8749 amount-exceeded: int
8751 amount of data which exceeded the threshold, in bytes.
8752 write-threshold: int
8754 last configured threshold, in bytes.
8755 Since
8757 2.3
8758 block-set-write-threshold (Command)
8760 Change the write threshold for a block drive. An event will be deliv‐
8761 ered if a write to this block drive crosses the configured threshold.
8762 The threshold is an offset, thus must be non-negative. Default is no
8763 write threshold. Setting the threshold to zero disables it.
8764 This is useful to transparently resize thin-provisioned drives without
8766 the guest OS noticing.
8767 Arguments
8769 node-name: string
8770 graph node name on which the threshold must be set.
8771 write-threshold: int
8773 configured threshold for the block device, bytes. Use 0 to dis‐
8774 able the threshold.
8775 Since
8777 2.3
8778 Example
8780 -> { "execute": "block-set-write-threshold",
8781 "arguments": { "node-name": "mydev",
8782 "write-threshold": 17179869184 } }
8783 <- { "return": {} }
8784 x-blockdev-change (Command)
8786 Dynamically reconfigure the block driver state graph. It can be used to
8787 add, remove, insert or replace a graph node. Currently only the Quorum
8788 driver implements this feature to add or remove its child. This is use‐
8789 ful to fix a broken quorum child.
8790 If node is specified, it will be inserted under parent. child may not
8792 be specified in this case. If both parent and child are specified but
8793 node is not, child will be detached from parent.
8794 Arguments
8796 parent: string
8797 the id or name of the parent node.
8798 child: string (optional)
8800 the name of a child under the given parent node.
8801 node: string (optional)
8803 the name of the node that will be added.
8804 Features
8806 unstable
8807 This command is experimental, and its API is not stable. It
8808 does not support all kinds of operations, all kinds of children,
8809 nor all block drivers.
8810 FIXME Removing children from a quorum node means introducing
8812 gaps in the child indices. This cannot be represented in the
8813 'children' list of BlockdevOptionsQuorum, as returned by
8814 .bdrv_refresh_filename().
8815 Warning: The data in a new quorum child MUST be consistent with
8817 that of the rest of the array.
8818 Since
8820 2.7
8821 Example
8823 1. Add a new node to a quorum
8824 -> { "execute": "blockdev-add",
8825 "arguments": {
8826 "driver": "raw",
8827 "node-name": "new_node",
8828 "file": { "driver": "file",
8829 "filename": "test.raw" } } }
8830 <- { "return": {} }
8831 -> { "execute": "x-blockdev-change",
8832 "arguments": { "parent": "disk1",
8833 "node": "new_node" } }
8834 <- { "return": {} }
8835 2. Delete a quorum's node
8837 -> { "execute": "x-blockdev-change",
8838 "arguments": { "parent": "disk1",
8839 "child": "children.1" } }
8840 <- { "return": {} }
8841 x-blockdev-set-iothread (Command)
8843 Move node and its children into the iothread. If iothread is null then
8844 move node and its children into the main loop.
8845 The node must not be attached to a BlockBackend.
8847 Arguments
8849 node-name: string
8850 the name of the block driver node
8851 iothread: StrOrNull
8853 the name of the IOThread object or null for the main loop
8854 force: boolean (optional)
8856 true if the node and its children should be moved when a Block‐
8857 Backend is already attached
8858 Features
8860 unstable
8861 This command is experimental and intended for test cases that
8862 need control over IOThreads only.
8863 Since
8865 2.12
8866 Example
8868 1. Move a node into an IOThread
8869 -> { "execute": "x-blockdev-set-iothread",
8870 "arguments": { "node-name": "disk1",
8871 "iothread": "iothread0" } }
8872 <- { "return": {} }
8873 2. Move a node into the main loop
8875 -> { "execute": "x-blockdev-set-iothread",
8876 "arguments": { "node-name": "disk1",
8877 "iothread": null } }
8878 <- { "return": {} }
8879 QuorumOpType (Enum)
8881 An enumeration of the quorum operation types
8882 Values
8884 read read operation
8885 write write operation
8887 flush flush operation
8889 Since
8891 2.6
8892 QUORUM_FAILURE (Event)
8894 Emitted by the Quorum block driver if it fails to establish a quorum
8895 Arguments
8897 reference: string
8898 device name if defined else node name
8899 sector-num: int
8901 number of the first sector of the failed read operation
8902 sectors-count: int
8904 failed read operation sector count
8905 Note
8907 This event is rate-limited.
8908 Since
8910 2.0
8911 Example
8913 <- { "event": "QUORUM_FAILURE",
8914 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
8915 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
8916 QUORUM_REPORT_BAD (Event)
8918 Emitted to report a corruption of a Quorum file
8919 Arguments
8921 type: QuorumOpType
8922 quorum operation type (Since 2.6)
8923 error: string (optional)
8925 error message. Only present on failure. This field contains a
8926 human-readable error message. There are no semantics other than
8927 that the block layer reported an error and clients should not
8928 try to interpret the error string.
8929 node-name: string
8931 the graph node name of the block driver state
8932 sector-num: int
8934 number of the first sector of the failed read operation
8935 sectors-count: int
8937 failed read operation sector count
8938 Note
8940 This event is rate-limited.
8941 Since
8943 2.0
8944 Example
8946 1. Read operation
8947 { "event": "QUORUM_REPORT_BAD",
8949 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
8950 "type": "read" },
8951 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
8952 2. Flush operation
8954 { "event": "QUORUM_REPORT_BAD",
8956 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
8957 "type": "flush", "error": "Broken pipe" },
8958 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
8959 BlockdevSnapshotInternal (Object)
8961 Members
8962 device: string
8963 the device name or node-name of a root node to generate the
8964 snapshot from
8965 name: string
8967 the name of the internal snapshot to be created
8968 Notes
8970 In transaction, if name is empty, or any snapshot matching name exists,
8971 the operation will fail. Only some image formats support it, for exam‐
8972 ple, qcow2, and rbd.
8973 Since
8975 1.7
8976 blockdev-snapshot-internal-sync (Command)
8978 Synchronously take an internal snapshot of a block device, when the
8979 format of the image used supports it. If the name is an empty string,
8980 or a snapshot with name already exists, the operation will fail.
8981 For the arguments, see the documentation of BlockdevSnapshotInternal.
8983 Returns
8985 • nothing on success
8986 • If device is not a valid block device, GenericError
8988 • If any snapshot matching name exists, or name is empty, GenericError
8990 • If the format of the image used does not support it, BlockFormatFea‐
8992 tureNotSupported
8993 Since
8995 1.7
8996 Example
8998 -> { "execute": "blockdev-snapshot-internal-sync",
8999 "arguments": { "device": "ide-hd0",
9000 "name": "snapshot0" }
9001 }
9002 <- { "return": {} }
9003 blockdev-snapshot-delete-internal-sync (Command)
9005 Synchronously delete an internal snapshot of a block device, when the
9006 format of the image used support it. The snapshot is identified by name
9007 or id or both. One of the name or id is required. Return SnapshotInfo
9008 for the successfully deleted snapshot.
9009 Arguments
9011 device: string
9012 the device name or node-name of a root node to delete the snap‐
9013 shot from
9014 id: string (optional)
9016 optional the snapshot's ID to be deleted
9017 name: string (optional)
9019 optional the snapshot's name to be deleted
9020 Returns
9022 • SnapshotInfo on success
9023 • If device is not a valid block device, GenericError
9025 • If snapshot not found, GenericError
9027 • If the format of the image used does not support it, BlockFormatFea‐
9029 tureNotSupported
9030 • If id and name are both not specified, GenericError
9032 Since
9034 1.7
9035 Example
9037 -> { "execute": "blockdev-snapshot-delete-internal-sync",
9038 "arguments": { "device": "ide-hd0",
9039 "name": "snapshot0" }
9040 }
9041 <- { "return": {
9042 "id": "1",
9043 "name": "snapshot0",
9044 "vm-state-size": 0,
9045 "date-sec": 1000012,
9046 "date-nsec": 10,
9047 "vm-clock-sec": 100,
9048 "vm-clock-nsec": 20,
9049 "icount": 220414
9050 }
9051 }
9052 Additional block stuff (VM related)
9054 BiosAtaTranslation (Enum)
9055 Policy that BIOS should use to interpret cylinder/head/sector ad‐
9056 dresses. Note that Bochs BIOS and SeaBIOS will not actually translate
9057 logical CHS to physical; instead, they will use logical block address‐
9058 ing.
9059 Values
9061 auto If cylinder/heads/sizes are passed, choose between none and LBA
9062 depending on the size of the disk. If they are not passed,
9063 choose none if QEMU can guess that the disk had 16 or fewer
9064 heads, large if QEMU can guess that the disk had 131072 or fewer
9065 tracks across all heads (i.e. cylinders*heads<131072), otherwise
9066 LBA.
9067 none The physical disk geometry is equal to the logical geometry.
9069 lba Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
9071 heads (if fewer than 255 are enough to cover the whole disk with
9072 1024 cylinders/head). The number of cylinders/head is then com‐
9073 puted based on the number of sectors and heads.
9074 large The number of cylinders per head is scaled down to 1024 by cor‐
9076 respondingly scaling up the number of heads.
9077 rechs Same as large, but first convert a 16-head geometry to 15-head,
9079 by proportionally scaling up the number of cylinders/head.
9080 Since
9082 2.0
9083 FloppyDriveType (Enum)
9085 Type of Floppy drive to be emulated by the Floppy Disk Controller.
9086 Values
9088 144 1.44MB 3.5" drive
9089 288 2.88MB 3.5" drive
9091 120 1.2MB 5.25" drive
9093 none No drive connected
9095 auto Automatically determined by inserted media at boot
9097 Since
9099 2.6
9100 PRManagerInfo (Object)
9102 Information about a persistent reservation manager
9103 Members
9105 id: string
9106 the identifier of the persistent reservation manager
9107 connected: boolean
9109 true if the persistent reservation manager is connected to the
9110 underlying storage or helper
9111 Since
9113 3.0
9114 query-pr-managers (Command)
9116 Returns a list of information about each persistent reservation man‐
9117 ager.
9118 Returns
9120 a list of PRManagerInfo for each persistent reservation manager
9121 Since
9123 3.0
9124 eject (Command)
9126 Ejects the medium from a removable drive.
9127 Arguments
9129 device: string (optional)
9130 Block device name
9131 id: string (optional)
9133 The name or QOM path of the guest device (since: 2.8)
9134 force: boolean (optional)
9136 If true, eject regardless of whether the drive is locked. If
9137 not specified, the default value is false.
9138 Features
9140 deprecated
9141 Member device is deprecated. Use id instead.
9142 Returns
9144 • Nothing on success
9145 • If device is not a valid block device, DeviceNotFound
9147 Notes
9149 Ejecting a device with no media results in success
9150 Since
9152 0.14
9153 Example
9155 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
9156 <- { "return": {} }
9157 blockdev-open-tray (Command)
9159 Opens a block device's tray. If there is a block driver state tree in‐
9160 serted as a medium, it will become inaccessible to the guest (but it
9161 will remain associated to the block device, so closing the tray will
9162 make it accessible again).
9163 If the tray was already open before, this will be a no-op.
9165 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
9167 cases in which no such event will be generated, these include:
9168 • if the guest has locked the tray, force is false and the guest does
9170 not respond to the eject request
9171 • if the BlockBackend denoted by device does not have a guest device
9173 attached to it
9174 • if the guest device does not have an actual tray
9176 Arguments
9178 device: string (optional)
9179 Block device name
9180 id: string (optional)
9182 The name or QOM path of the guest device (since: 2.8)
9183 force: boolean (optional)
9185 if false (the default), an eject request will be sent to the
9186 guest if it has locked the tray (and the tray will not be opened
9187 immediately); if true, the tray will be opened regardless of
9188 whether it is locked
9189 Features
9191 deprecated
9192 Member device is deprecated. Use id instead.
9193 Since
9195 2.5
9196 Example
9198 -> { "execute": "blockdev-open-tray",
9199 "arguments": { "id": "ide0-1-0" } }
9200 <- { "timestamp": { "seconds": 1418751016,
9202 "microseconds": 716996 },
9203 "event": "DEVICE_TRAY_MOVED",
9204 "data": { "device": "ide1-cd0",
9205 "id": "ide0-1-0",
9206 "tray-open": true } }
9207 <- { "return": {} }
9209 blockdev-close-tray (Command)
9211 Closes a block device's tray. If there is a block driver state tree as‐
9212 sociated with the block device (which is currently ejected), that tree
9213 will be loaded as the medium.
9214 If the tray was already closed before, this will be a no-op.
9216 Arguments
9218 device: string (optional)
9219 Block device name
9220 id: string (optional)
9222 The name or QOM path of the guest device (since: 2.8)
9223 Features
9225 deprecated
9226 Member device is deprecated. Use id instead.
9227 Since
9229 2.5
9230 Example
9232 -> { "execute": "blockdev-close-tray",
9233 "arguments": { "id": "ide0-1-0" } }
9234 <- { "timestamp": { "seconds": 1418751345,
9236 "microseconds": 272147 },
9237 "event": "DEVICE_TRAY_MOVED",
9238 "data": { "device": "ide1-cd0",
9239 "id": "ide0-1-0",
9240 "tray-open": false } }
9241 <- { "return": {} }
9243 blockdev-remove-medium (Command)
9245 Removes a medium (a block driver state tree) from a block device. That
9246 block device's tray must currently be open (unless there is no attached
9247 guest device).
9248 If the tray is open and there is no medium inserted, this will be a
9250 no-op.
9251 Arguments
9253 id: string
9254 The name or QOM path of the guest device
9255 Since
9257 2.12
9258 Example
9260 -> { "execute": "blockdev-remove-medium",
9261 "arguments": { "id": "ide0-1-0" } }
9262 <- { "error": { "class": "GenericError",
9264 "desc": "Tray of device 'ide0-1-0' is not open" } }
9265 -> { "execute": "blockdev-open-tray",
9267 "arguments": { "id": "ide0-1-0" } }
9268 <- { "timestamp": { "seconds": 1418751627,
9270 "microseconds": 549958 },
9271 "event": "DEVICE_TRAY_MOVED",
9272 "data": { "device": "ide1-cd0",
9273 "id": "ide0-1-0",
9274 "tray-open": true } }
9275 <- { "return": {} }
9277 -> { "execute": "blockdev-remove-medium",
9279 "arguments": { "id": "ide0-1-0" } }
9280 <- { "return": {} }
9282 blockdev-insert-medium (Command)
9284 Inserts a medium (a block driver state tree) into a block device. That
9285 block device's tray must currently be open (unless there is no attached
9286 guest device) and there must be no medium inserted already.
9287 Arguments
9289 id: string
9290 The name or QOM path of the guest device
9291 node-name: string
9293 name of a node in the block driver state graph
9294 Since
9296 2.12
9297 Example
9299 -> { "execute": "blockdev-add",
9300 "arguments": {
9301 "node-name": "node0",
9302 "driver": "raw",
9303 "file": { "driver": "file",
9304 "filename": "fedora.iso" } } }
9305 <- { "return": {} }
9306 -> { "execute": "blockdev-insert-medium",
9308 "arguments": { "id": "ide0-1-0",
9309 "node-name": "node0" } }
9310 <- { "return": {} }
9312 BlockdevChangeReadOnlyMode (Enum)
9314 Specifies the new read-only mode of a block device subject to the
9315 blockdev-change-medium command.
9316 Values
9318 retain Retains the current read-only mode
9319 read-only
9321 Makes the device read-only
9322 read-write
9324 Makes the device writable
9325 Since
9327 2.3
9328 blockdev-change-medium (Command)
9330 Changes the medium inserted into a block device by ejecting the current
9331 medium and loading a new image file which is inserted as the new medium
9332 (this command combines blockdev-open-tray, blockdev-remove-medium,
9333 blockdev-insert-medium and blockdev-close-tray).
9334 Arguments
9336 device: string (optional)
9337 Block device name
9338 id: string (optional)
9340 The name or QOM path of the guest device (since: 2.8)
9341 filename: string
9343 filename of the new image to be loaded
9344 format: string (optional)
9346 format to open the new image with (defaults to the probed for‐
9347 mat)
9348 read-only-mode: BlockdevChangeReadOnlyMode (optional)
9350 change the read-only mode of the device; defaults to 'retain'
9351 force: boolean (optional)
9353 if false (the default), an eject request through block‐
9354 dev-open-tray will be sent to the guest if it has locked the
9355 tray (and the tray will not be opened immediately); if true, the
9356 tray will be opened regardless of whether it is locked. (since
9357 7.1)
9358 Features
9360 deprecated
9361 Member device is deprecated. Use id instead.
9362 Since
9364 2.5
9365 Examples
9367 1. Change a removable medium
9368 -> { "execute": "blockdev-change-medium",
9370 "arguments": { "id": "ide0-1-0",
9371 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
9372 "format": "raw" } }
9373 <- { "return": {} }
9374 2. Load a read-only medium into a writable drive
9376 -> { "execute": "blockdev-change-medium",
9378 "arguments": { "id": "floppyA",
9379 "filename": "/srv/images/ro.img",
9380 "format": "raw",
9381 "read-only-mode": "retain" } }
9382 <- { "error":
9384 { "class": "GenericError",
9385 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
9386 -> { "execute": "blockdev-change-medium",
9388 "arguments": { "id": "floppyA",
9389 "filename": "/srv/images/ro.img",
9390 "format": "raw",
9391 "read-only-mode": "read-only" } }
9392 <- { "return": {} }
9394 DEVICE_TRAY_MOVED (Event)
9396 Emitted whenever the tray of a removable device is moved by the guest
9397 or by HMP/QMP commands
9398 Arguments
9400 device: string
9401 Block device name. This is always present for compatibility rea‐
9402 sons, but it can be empty ("") if the image does not have a de‐
9403 vice name associated.
9404 id: string
9406 The name or QOM path of the guest device (since 2.8)
9407 tray-open: boolean
9409 true if the tray has been opened or false if it has been closed
9410 Since
9412 1.1
9413 Example
9415 <- { "event": "DEVICE_TRAY_MOVED",
9416 "data": { "device": "ide1-cd0",
9417 "id": "/machine/unattached/device[22]",
9418 "tray-open": true
9419 },
9420 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
9421 PR_MANAGER_STATUS_CHANGED (Event)
9423 Emitted whenever the connected status of a persistent reservation man‐
9424 ager changes.
9425 Arguments
9427 id: string
9428 The id of the PR manager object
9429 connected: boolean
9431 true if the PR manager is connected to a backend
9432 Since
9434 3.0
9435 Example
9437 <- { "event": "PR_MANAGER_STATUS_CHANGED",
9438 "data": { "id": "pr-helper0",
9439 "connected": true
9440 },
9441 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
9442 block_set_io_throttle (Command)
9444 Change I/O throttle limits for a block drive.
9445 Since QEMU 2.4, each device with I/O limits is member of a throttle
9447 group.
9448 If two or more devices are members of the same group, the limits will
9450 apply to the combined I/O of the whole group in a round-robin fashion.
9451 Therefore, setting new I/O limits to a device will affect the whole
9452 group.
9453 The name of the group can be specified using the 'group' parameter. If
9455 the parameter is unset, it is assumed to be the current group of that
9456 device. If it's not in any group yet, the name of the device will be
9457 used as the name for its group.
9458 The 'group' parameter can also be used to move a device to a different
9460 group. In this case the limits specified in the parameters will be ap‐
9461 plied to the new group only.
9462 I/O limits can be disabled by setting all of them to 0. In this case
9464 the device will be removed from its group and the rest of its members
9465 will not be affected. The 'group' parameter is ignored.
9466 Arguments
9468 The members of BlockIOThrottle
9469 Returns
9471 • Nothing on success
9472 • If device is not a valid block device, DeviceNotFound
9474 Since
9476 1.1
9477 Example
9479 -> { "execute": "block_set_io_throttle",
9480 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
9481 "bps": 0,
9482 "bps_rd": 0,
9483 "bps_wr": 0,
9484 "iops": 512,
9485 "iops_rd": 0,
9486 "iops_wr": 0,
9487 "bps_max": 0,
9488 "bps_rd_max": 0,
9489 "bps_wr_max": 0,
9490 "iops_max": 0,
9491 "iops_rd_max": 0,
9492 "iops_wr_max": 0,
9493 "bps_max_length": 0,
9494 "iops_size": 0 } }
9495 <- { "return": {} }
9496 -> { "execute": "block_set_io_throttle",
9498 "arguments": { "id": "ide0-1-0",
9499 "bps": 1000000,
9500 "bps_rd": 0,
9501 "bps_wr": 0,
9502 "iops": 0,
9503 "iops_rd": 0,
9504 "iops_wr": 0,
9505 "bps_max": 8000000,
9506 "bps_rd_max": 0,
9507 "bps_wr_max": 0,
9508 "iops_max": 0,
9509 "iops_rd_max": 0,
9510 "iops_wr_max": 0,
9511 "bps_max_length": 60,
9512 "iops_size": 0 } }
9513 <- { "return": {} }
9514 block-latency-histogram-set (Command)
9516 Manage read, write and flush latency histograms for the device.
9517 If only id parameter is specified, remove all present latency his‐
9519 tograms for the device. Otherwise, add/reset some of (or all) latency
9520 histograms.
9521 Arguments
9523 id: string
9524 The name or QOM path of the guest device.
9525 boundaries: array of int (optional)
9527 list of interval boundary values (see description in BlockLaten‐
9528 cyHistogramInfo definition). If specified, all latency his‐
9529 tograms are removed, and empty ones created for all io types
9530 with intervals corresponding to boundaries (except for io types,
9531 for which specific boundaries are set through the following pa‐
9532 rameters).
9533 boundaries-read: array of int (optional)
9535 list of interval boundary values for read latency histogram. If
9536 specified, old read latency histogram is removed, and empty one
9537 created with intervals corresponding to boundaries-read. The pa‐
9538 rameter has higher priority then boundaries.
9539 boundaries-write: array of int (optional)
9541 list of interval boundary values for write latency histogram.
9542 boundaries-flush: array of int (optional)
9544 list of interval boundary values for flush latency histogram.
9545 Returns
9547 error if device is not found or any boundary arrays are invalid.
9548 Since
9550 4.0
9551 Example
9553 set new histograms for all io types with intervals
9554 [0, 10), [10, 50), [50, 100), [100, +inf):
9555 -> { "execute": "block-latency-histogram-set",
9557 "arguments": { "id": "drive0",
9558 "boundaries": [10, 50, 100] } }
9559 <- { "return": {} }
9560 Example
9562 set new histogram only for write, other histograms will remain
9563 not changed (or not created):
9564 -> { "execute": "block-latency-histogram-set",
9566 "arguments": { "id": "drive0",
9567 "boundaries-write": [10, 50, 100] } }
9568 <- { "return": {} }
9569 Example
9571 set new histograms with the following intervals:
9572 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
9573 write: [0, 1000), [1000, 5000), [5000, +inf)
9574 -> { "execute": "block-latency-histogram-set",
9576 "arguments": { "id": "drive0",
9577 "boundaries": [10, 50, 100],
9578 "boundaries-write": [1000, 5000] } }
9579 <- { "return": {} }
9580 Example
9582 remove all latency histograms:
9583 -> { "execute": "block-latency-histogram-set",
9585 "arguments": { "id": "drive0" } }
9586 <- { "return": {} }
9587 Block device exports
9589 NbdServerOptions (Object)
9590 Keep this type consistent with the nbd-server-start arguments. The only
9591 intended difference is using SocketAddress instead of SocketAddressLe‐
9592 gacy.
9593 Members
9595 addr: SocketAddress
9596 Address on which to listen.
9597 tls-creds: string (optional)
9599 ID of the TLS credentials object (since 2.6).
9600 tls-authz: string (optional)
9602 ID of the QAuthZ authorization object used to validate the
9603 client's x509 distinguished name. This object is is only re‐
9604 solved at time of use, so can be deleted and recreated on the
9605 fly while the NBD server is active. If missing, it will default
9606 to denying access (since 4.0).
9607 max-connections: int (optional)
9609 The maximum number of connections to allow at the same time, 0
9610 for unlimited. Setting this to 1 also stops the server from ad‐
9611 vertising multiple client support (since 5.2; default: 0)
9612 Since
9614 4.2
9615 nbd-server-start (Command)
9617 Start an NBD server listening on the given host and port. Block de‐
9618 vices can then be exported using nbd-server-add. The NBD server will
9619 present them as named exports; for example, another QEMU instance could
9620 refer to them as "nbd:HOST:PORT:exportname=NAME".
9621 Keep this type consistent with the NbdServerOptions type. The only in‐
9623 tended difference is using SocketAddressLegacy instead of SocketAd‐
9624 dress.
9625 Arguments
9627 addr: SocketAddressLegacy
9628 Address on which to listen.
9629 tls-creds: string (optional)
9631 ID of the TLS credentials object (since 2.6).
9632 tls-authz: string (optional)
9634 ID of the QAuthZ authorization object used to validate the
9635 client's x509 distinguished name. This object is is only re‐
9636 solved at time of use, so can be deleted and recreated on the
9637 fly while the NBD server is active. If missing, it will default
9638 to denying access (since 4.0).
9639 max-connections: int (optional)
9641 The maximum number of connections to allow at the same time, 0
9642 for unlimited. Setting this to 1 also stops the server from ad‐
9643 vertising multiple client support (since 5.2; default: 0).
9644 Returns
9646 error if the server is already running.
9647 Since
9649 1.3
9650 BlockExportOptionsNbdBase (Object)
9652 An NBD block export (common options shared between nbd-server-add and
9653 the NBD branch of block-export-add).
9654 Members
9656 name: string (optional)
9657 Export name. If unspecified, the device parameter is used as the
9658 export name. (Since 2.12)
9659 description: string (optional)
9661 Free-form description of the export, up to 4096 bytes. (Since
9662 5.0)
9663 Since
9665 5.0
9666 BlockExportOptionsNbd (Object)
9668 An NBD block export (distinct options used in the NBD branch of
9669 block-export-add).
9670 Members
9672 bitmaps: array of BlockDirtyBitmapOrStr (optional)
9673 Also export each of the named dirty bitmaps reachable from de‐
9674 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
9675 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
9676 each bitmap. Since 7.1 bitmap may be specified by node/name
9677 pair.
9678 allocation-depth: boolean (optional)
9680 Also export the allocation depth map for device, so the NBD
9681 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
9682 text name "qemu:allocation-depth" to inspect allocation details.
9683 (since 5.2)
9684 The members of BlockExportOptionsNbdBase
9686 Since
9688 5.2
9689 BlockExportOptionsVhostUserBlk (Object)
9691 A vhost-user-blk block export.
9692 Members
9694 addr: SocketAddress
9695 The vhost-user socket on which to listen. Both 'unix' and 'fd'
9696 SocketAddress types are supported. Passed fds must be UNIX do‐
9697 main sockets.
9698 logical-block-size: int (optional)
9700 Logical block size in bytes. Defaults to 512 bytes.
9701 num-queues: int (optional)
9703 Number of request virtqueues. Must be greater than 0. Defaults
9704 to 1.
9705 Since
9707 5.2
9708 FuseExportAllowOther (Enum)
9710 Possible allow_other modes for FUSE exports.
9711 Values
9713 off Do not pass allow_other as a mount option.
9714 on Pass allow_other as a mount option.
9716 auto Try mounting with allow_other first, and if that fails, retry
9718 without allow_other.
9719 Since
9721 6.1
9722 BlockExportOptionsFuse (Object)
9724 Options for exporting a block graph node on some (file) mountpoint as a
9725 raw image.
9726 Members
9728 mountpoint: string
9729 Path on which to export the block device via FUSE. This must
9730 point to an existing regular file.
9731 growable: boolean (optional)
9733 Whether writes beyond the EOF should grow the block node accord‐
9734 ingly. (default: false)
9735 allow-other: FuseExportAllowOther (optional)
9737 If this is off, only qemu's user is allowed access to this ex‐
9738 port. That cannot be changed even with chmod or chown. En‐
9739 abling this option will allow other users access to the export
9740 with the FUSE mount option "allow_other". Note that using al‐
9741 low_other as a non-root user requires user_allow_other to be en‐
9742 abled in the global fuse.conf configuration file. In auto mode
9743 (the default), the FUSE export driver will first attempt to
9744 mount the export with allow_other, and if that fails, try again
9745 without. (since 6.1; default: auto)
9746 Since
9748 6.0
9749 If
9751 CONFIG_FUSE
9752 BlockExportOptionsVduseBlk (Object)
9754 A vduse-blk block export.
9755 Members
9757 name: string
9758 the name of VDUSE device (must be unique across the host).
9759 num-queues: int (optional)
9761 the number of virtqueues. Defaults to 1.
9762 queue-size: int (optional)
9764 the size of virtqueue. Defaults to 256.
9765 logical-block-size: int (optional)
9767 Logical block size in bytes. Range [512, PAGE_SIZE] and must be
9768 power of 2. Defaults to 512 bytes.
9769 serial: string (optional)
9771 the serial number of virtio block device. Defaults to empty
9772 string.
9773 Since
9775 7.1
9776 NbdServerAddOptions (Object)
9778 An NBD block export, per legacy nbd-server-add command.
9779 Members
9781 device: string
9782 The device name or node name of the node to be exported
9783 writable: boolean (optional)
9785 Whether clients should be able to write to the device via the
9786 NBD connection (default false).
9787 bitmap: string (optional)
9789 Also export a single dirty bitmap reachable from device, so the
9790 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
9791 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
9792 (since 4.0).
9793 The members of BlockExportOptionsNbdBase
9795 Since
9797 5.0
9798 nbd-server-add (Command)
9800 Export a block node to QEMU's embedded NBD server.
9801 The export name will be used as the id for the resulting block export.
9803 Arguments
9805 The members of NbdServerAddOptions
9806 Features
9808 deprecated
9809 This command is deprecated. Use block-export-add instead.
9810 Returns
9812 error if the server is not running, or export with the same name al‐
9813 ready exists.
9814 Since
9816 1.3
9817 BlockExportRemoveMode (Enum)
9819 Mode for removing a block export.
9820 Values
9822 safe Remove export if there are no existing connections, fail other‐
9823 wise.
9824 hard Drop all connections immediately and remove export.
9826 TODO
9828 Potential additional modes to be added in the future:
9829 hide: Just hide export from new clients, leave existing connections as
9831 is. Remove export after all clients are disconnected.
9832 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
9834 ther requests from existing clients.
9835 Since
9837 2.12
9838 nbd-server-remove (Command)
9840 Remove NBD export by name.
9841 Arguments
9843 name: string
9844 Block export id.
9845 mode: BlockExportRemoveMode (optional)
9847 Mode of command operation. See BlockExportRemoveMode descrip‐
9848 tion. Default is 'safe'.
9849 Features
9851 deprecated
9852 This command is deprecated. Use block-export-del instead.
9853 Returns
9855 error if
9856 • the server is not running
9858 • export is not found
9860 • mode is 'safe' and there are existing connections
9862 Since
9864 2.12
9865 nbd-server-stop (Command)
9867 Stop QEMU's embedded NBD server, and unregister all devices previously
9868 added via nbd-server-add.
9869 Since
9871 1.3
9872 BlockExportType (Enum)
9874 An enumeration of block export types
9875 Values
9877 nbd NBD export
9878 vhost-user-blk (If: CONFIG_VHOST_USER_BLK_SERVER)
9880 vhost-user-blk export (since 5.2)
9881 fuse (If: CONFIG_FUSE)
9883 FUSE export (since: 6.0)
9884 vduse-blk (If: CONFIG_VDUSE_BLK_EXPORT)
9886 vduse-blk export (since 7.1)
9887 Since
9889 4.2
9890 BlockExportOptions (Object)
9892 Describes a block export, i.e. how single node should be exported on an
9893 external interface.
9894 Members
9896 id: string
9897 A unique identifier for the block export (across all export
9898 types)
9899 node-name: string
9901 The node name of the block node to be exported (since: 5.2)
9902 writable: boolean (optional)
9904 True if clients should be able to write to the export (default
9905 false)
9906 writethrough: boolean (optional)
9908 If true, caches are flushed after every write request to the ex‐
9909 port before completion is signalled. (since: 5.2; default:
9910 false)
9911 iothread: string (optional)
9913 The name of the iothread object where the export will run. The
9914 default is to use the thread currently associated with the block
9915 node. (since: 5.2)
9916 fixed-iothread: boolean (optional)
9918 True prevents the block node from being moved to another thread
9919 while the export is active. If true and iothread is given, ex‐
9920 port creation fails if the block node cannot be moved to the io‐
9921 thread. The default is false. (since: 5.2)
9922 type: BlockExportType
9924 Not documented
9925 The members of BlockExportOptionsNbd when type is "nbd"
9927 The members of BlockExportOptionsVhostUserBlk when type is
9929 "vhost-user-blk" (If: CONFIG_VHOST_USER_BLK_SERVER)
9930 The members of BlockExportOptionsFuse when type is "fuse" (If: CON‐
9932 FIG_FUSE)
9933 The members of BlockExportOptionsVduseBlk when type is "vduse-blk" (If:
9935 CONFIG_VDUSE_BLK_EXPORT)
9936 Since
9938 4.2
9939 block-export-add (Command)
9941 Creates a new block export.
9942 Arguments
9944 The members of BlockExportOptions
9945 Since
9947 5.2
9948 block-export-del (Command)
9950 Request to remove a block export. This drops the user's reference to
9951 the export, but the export may still stay around after this command re‐
9952 turns until the shutdown of the export has completed.
9953 Arguments
9955 id: string
9956 Block export id.
9957 mode: BlockExportRemoveMode (optional)
9959 Mode of command operation. See BlockExportRemoveMode descrip‐
9960 tion. Default is 'safe'.
9961 Returns
9963 Error if the export is not found or mode is 'safe' and the export is
9964 still in use (e.g. by existing client connections)
9965 Since
9967 5.2
9968 BLOCK_EXPORT_DELETED (Event)
9970 Emitted when a block export is removed and its id can be reused.
9971 Arguments
9973 id: string
9974 Block export id.
9975 Since
9977 5.2
9978 BlockExportInfo (Object)
9980 Information about a single block export.
9981 Members
9983 id: string
9984 The unique identifier for the block export
9985 type: BlockExportType
9987 The block export type
9988 node-name: string
9990 The node name of the block node that is exported
9991 shutting-down: boolean
9993 True if the export is shutting down (e.g. after a block-ex‐
9994 port-del command, but before the shutdown has completed)
9995 Since
9997 5.2
9998 query-block-exports (Command)
10000 Returns
10001 A list of BlockExportInfo describing all block exports
10002 Since
10004 5.2
10005
10007 ChardevInfo (Object)
10008 Information about a character device.
10009 Members
10011 label: string
10012 the label of the character device
10013 filename: string
10015 the filename of the character device
10016 frontend-open: boolean
10018 shows whether the frontend device attached to this backend (eg.
10019 with the chardev=... option) is in open or closed state (since
10020 2.1)
10021 Notes
10023 filename is encoded using the QEMU command line character device encod‐
10024 ing. See the QEMU man page for details.
10025 Since
10027 0.14
10028 query-chardev (Command)
10030 Returns information about current character devices.
10031 Returns
10033 a list of ChardevInfo
10034 Since
10036 0.14
10037 Example
10039 -> { "execute": "query-chardev" }
10040 <- {
10041 "return": [
10042 {
10043 "label": "charchannel0",
10044 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
10045 "frontend-open": false
10046 },
10047 {
10048 "label": "charmonitor",
10049 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
10050 "frontend-open": true
10051 },
10052 {
10053 "label": "charserial0",
10054 "filename": "pty:/dev/pts/2",
10055 "frontend-open": true
10056 }
10057 ]
10058 }
10059 ChardevBackendInfo (Object)
10061 Information about a character device backend
10062 Members
10064 name: string
10065 The backend name
10066 Since
10068 2.0
10069 query-chardev-backends (Command)
10071 Returns information about character device backends.
10072 Returns
10074 a list of ChardevBackendInfo
10075 Since
10077 2.0
10078 Example
10080 -> { "execute": "query-chardev-backends" }
10081 <- {
10082 "return":[
10083 {
10084 "name":"udp"
10085 },
10086 {
10087 "name":"tcp"
10088 },
10089 {
10090 "name":"unix"
10091 },
10092 {
10093 "name":"spiceport"
10094 }
10095 ]
10096 }
10097 DataFormat (Enum)
10099 An enumeration of data format.
10100 Values
10102 utf8 Data is a UTF-8 string (RFC 3629)
10103 base64 Data is Base64 encoded binary (RFC 3548)
10105 Since
10107 1.4
10108 ringbuf-write (Command)
10110 Write to a ring buffer character device.
10111 Arguments
10113 device: string
10114 the ring buffer character device name
10115 data: string
10117 data to write
10118 format: DataFormat (optional)
10120 data encoding (default 'utf8').
10121 • base64: data must be base64 encoded text. Its binary decoding
10123 gets written.
10124 • utf8: data's UTF-8 encoding is written
10126 • data itself is always Unicode regardless of format, like any
10128 other string.
10129 Returns
10131 Nothing on success
10132 Since
10134 1.4
10135 Example
10137 -> { "execute": "ringbuf-write",
10138 "arguments": { "device": "foo",
10139 "data": "abcdefgh",
10140 "format": "utf8" } }
10141 <- { "return": {} }
10142 ringbuf-read (Command)
10144 Read from a ring buffer character device.
10145 Arguments
10147 device: string
10148 the ring buffer character device name
10149 size: int
10151 how many bytes to read at most
10152 format: DataFormat (optional)
10154 data encoding (default 'utf8').
10155 • base64: the data read is returned in base64 encoding.
10157 • utf8: the data read is interpreted as UTF-8. Bug: can screw
10159 up when the buffer contains invalid UTF-8 sequences, NUL char‐
10160 acters, after the ring buffer lost data, and when reading
10161 stops because the size limit is reached.
10162 • The return value is always Unicode regardless of format, like
10164 any other string.
10165 Returns
10167 data read from the device
10168 Since
10170 1.4
10171 Example
10173 -> { "execute": "ringbuf-read",
10174 "arguments": { "device": "foo",
10175 "size": 1000,
10176 "format": "utf8" } }
10177 <- { "return": "abcdefgh" }
10178 ChardevCommon (Object)
10180 Configuration shared across all chardev backends
10181 Members
10183 logfile: string (optional)
10184 The name of a logfile to save output
10185 logappend: boolean (optional)
10187 true to append instead of truncate (default to false to trun‐
10188 cate)
10189 Since
10191 2.6
10192 ChardevFile (Object)
10194 Configuration info for file chardevs.
10195 Members
10197 in: string (optional)
10198 The name of the input file
10199 out: string
10201 The name of the output file
10202 append: boolean (optional)
10204 Open the file in append mode (default false to truncate) (Since
10205 2.6)
10206 The members of ChardevCommon
10208 Since
10210 1.4
10211 ChardevHostdev (Object)
10213 Configuration info for device and pipe chardevs.
10214 Members
10216 device: string
10217 The name of the special file for the device, i.e. /dev/ttyS0 on
10218 Unix or COM1: on Windows
10219 The members of ChardevCommon
10221 Since
10223 1.4
10224 ChardevSocket (Object)
10226 Configuration info for (stream) socket chardevs.
10227 Members
10229 addr: SocketAddressLegacy
10230 socket address to listen on (server=true) or connect to
10231 (server=false)
10232 tls-creds: string (optional)
10234 the ID of the TLS credentials object (since 2.6)
10235 tls-authz: string (optional)
10237 the ID of the QAuthZ authorization object against which the
10238 client's x509 distinguished name will be validated. This object
10239 is only resolved at time of use, so can be deleted and recreated
10240 on the fly while the chardev server is active. If missing, it
10241 will default to denying access (since 4.0)
10242 server: boolean (optional)
10244 create server socket (default: true)
10245 wait: boolean (optional)
10247 wait for incoming connection on server sockets (default: false).
10248 Silently ignored with server: false. This use is deprecated.
10249 nodelay: boolean (optional)
10251 set TCP_NODELAY socket option (default: false)
10252 telnet: boolean (optional)
10254 enable telnet protocol on server sockets (default: false)
10255 tn3270: boolean (optional)
10257 enable tn3270 protocol on server sockets (default: false)
10258 (Since: 2.10)
10259 websocket: boolean (optional)
10261 enable websocket protocol on server sockets (default: false)
10262 (Since: 3.1)
10263 reconnect: int (optional)
10265 For a client socket, if a socket is disconnected, then attempt a
10266 reconnect after the given number of seconds. Setting this to
10267 zero disables this function. (default: 0) (Since: 2.2)
10268 The members of ChardevCommon
10270 Since
10272 1.4
10273 ChardevUdp (Object)
10275 Configuration info for datagram socket chardevs.
10276 Members
10278 remote: SocketAddressLegacy
10279 remote address
10280 local: SocketAddressLegacy (optional)
10282 local address
10283 The members of ChardevCommon
10285 Since
10287 1.5
10288 ChardevMux (Object)
10290 Configuration info for mux chardevs.
10291 Members
10293 chardev: string
10294 name of the base chardev.
10295 The members of ChardevCommon
10297 Since
10299 1.5
10300 ChardevStdio (Object)
10302 Configuration info for stdio chardevs.
10303 Members
10305 signal: boolean (optional)
10306 Allow signals (such as SIGINT triggered by ^C) be delivered to
10307 qemu. Default: true.
10308 The members of ChardevCommon
10310 Since
10312 1.5
10313 ChardevSpiceChannel (Object)
10315 Configuration info for spice vm channel chardevs.
10316 Members
10318 type: string
10319 kind of channel (for example vdagent).
10320 The members of ChardevCommon
10322 Since
10324 1.5
10325 If
10327 CONFIG_SPICE
10328 ChardevSpicePort (Object)
10330 Configuration info for spice port chardevs.
10331 Members
10333 fqdn: string
10334 name of the channel (see docs/spice-port-fqdn.txt)
10335 The members of ChardevCommon
10337 Since
10339 1.5
10340 If
10342 CONFIG_SPICE
10343 ChardevDBus (Object)
10345 Configuration info for DBus chardevs.
10346 Members
10348 name: string
10349 name of the channel (following docs/spice-port-fqdn.txt)
10350 The members of ChardevCommon
10352 Since
10354 7.0
10355 If
10357 CONFIG_DBUS_DISPLAY
10358 ChardevVC (Object)
10360 Configuration info for virtual console chardevs.
10361 Members
10363 width: int (optional)
10364 console width, in pixels
10365 height: int (optional)
10367 console height, in pixels
10368 cols: int (optional)
10370 console width, in chars
10371 rows: int (optional)
10373 console height, in chars
10374 The members of ChardevCommon
10376 Since
10378 1.5
10379 ChardevRingbuf (Object)
10381 Configuration info for ring buffer chardevs.
10382 Members
10384 size: int (optional)
10385 ring buffer size, must be power of two, default is 65536
10386 The members of ChardevCommon
10388 Since
10390 1.5
10391 ChardevQemuVDAgent (Object)
10393 Configuration info for qemu vdagent implementation.
10394 Members
10396 mouse: boolean (optional)
10397 enable/disable mouse, default is enabled.
10398 clipboard: boolean (optional)
10400 enable/disable clipboard, default is disabled.
10401 The members of ChardevCommon
10403 Since
10405 6.1
10406 If
10408 CONFIG_SPICE_PROTOCOL
10409 ChardevBackendKind (Enum)
10411 Values
10412 pipe Since 1.5
10413 udp Since 1.5
10415 mux Since 1.5
10417 msmouse
10419 Since 1.5
10420 wctablet
10422 Since 2.9
10423 braille
10425 Since 1.5
10426 testdev
10428 Since 2.2
10429 stdio Since 1.5
10431 console
10433 Since 1.5
10434 spicevmc (If: CONFIG_SPICE)
10436 Since 1.5
10437 spiceport (If: CONFIG_SPICE)
10439 Since 1.5
10440 qemu-vdagent (If: CONFIG_SPICE_PROTOCOL)
10442 Since 6.1
10443 dbus (If: CONFIG_DBUS_DISPLAY)
10445 Since 7.0
10446 vc v1.5
10448 ringbuf
10450 Since 1.6
10451 memory Since 1.5
10453 file Not documented
10455 serial Not documented
10457 parallel
10459 Not documented
10460 socket Not documented
10462 pty Not documented
10464 null Not documented
10466 Since
10468 1.4
10469 ChardevFileWrapper (Object)
10471 Members
10472 data: ChardevFile
10473 Not documented
10474 Since
10476 1.4
10477 ChardevHostdevWrapper (Object)
10479 Members
10480 data: ChardevHostdev
10481 Not documented
10482 Since
10484 1.4
10485 ChardevSocketWrapper (Object)
10487 Members
10488 data: ChardevSocket
10489 Not documented
10490 Since
10492 1.4
10493 ChardevUdpWrapper (Object)
10495 Members
10496 data: ChardevUdp
10497 Not documented
10498 Since
10500 1.5
10501 ChardevCommonWrapper (Object)
10503 Members
10504 data: ChardevCommon
10505 Not documented
10506 Since
10508 2.6
10509 ChardevMuxWrapper (Object)
10511 Members
10512 data: ChardevMux
10513 Not documented
10514 Since
10516 1.5
10517 ChardevStdioWrapper (Object)
10519 Members
10520 data: ChardevStdio
10521 Not documented
10522 Since
10524 1.5
10525 ChardevSpiceChannelWrapper (Object)
10527 Members
10528 data: ChardevSpiceChannel
10529 Not documented
10530 Since
10532 1.5
10533 If
10535 CONFIG_SPICE
10536 ChardevSpicePortWrapper (Object)
10538 Members
10539 data: ChardevSpicePort
10540 Not documented
10541 Since
10543 1.5
10544 If
10546 CONFIG_SPICE
10547 ChardevQemuVDAgentWrapper (Object)
10549 Members
10550 data: ChardevQemuVDAgent
10551 Not documented
10552 Since
10554 6.1
10555 If
10557 CONFIG_SPICE_PROTOCOL
10558 ChardevDBusWrapper (Object)
10560 Members
10561 data: ChardevDBus
10562 Not documented
10563 Since
10565 7.0
10566 If
10568 CONFIG_DBUS_DISPLAY
10569 ChardevVCWrapper (Object)
10571 Members
10572 data: ChardevVC
10573 Not documented
10574 Since
10576 1.5
10577 ChardevRingbufWrapper (Object)
10579 Members
10580 data: ChardevRingbuf
10581 Not documented
10582 Since
10584 1.5
10585 ChardevBackend (Object)
10587 Configuration info for the new chardev backend.
10588 Members
10590 type: ChardevBackendKind
10591 Not documented
10592 The members of ChardevFileWrapper when type is "file"
10594 The members of ChardevHostdevWrapper when type is "serial"
10596 The members of ChardevHostdevWrapper when type is "parallel"
10598 The members of ChardevHostdevWrapper when type is "pipe"
10600 The members of ChardevSocketWrapper when type is "socket"
10602 The members of ChardevUdpWrapper when type is "udp"
10604 The members of ChardevCommonWrapper when type is "pty"
10606 The members of ChardevCommonWrapper when type is "null"
10608 The members of ChardevMuxWrapper when type is "mux"
10610 The members of ChardevCommonWrapper when type is "msmouse"
10612 The members of ChardevCommonWrapper when type is "wctablet"
10614 The members of ChardevCommonWrapper when type is "braille"
10616 The members of ChardevCommonWrapper when type is "testdev"
10618 The members of ChardevStdioWrapper when type is "stdio"
10620 The members of ChardevCommonWrapper when type is "console"
10622 The members of ChardevSpiceChannelWrapper when type is "spicevmc" (If:
10624 CONFIG_SPICE)
10625 The members of ChardevSpicePortWrapper when type is "spiceport" (If:
10627 CONFIG_SPICE)
10628 The members of ChardevQemuVDAgentWrapper when type is "qemu-vdagent"
10630 (If: CONFIG_SPICE_PROTOCOL)
10631 The members of ChardevDBusWrapper when type is "dbus" (If: CON‐
10633 FIG_DBUS_DISPLAY)
10634 The members of ChardevVCWrapper when type is "vc"
10636 The members of ChardevRingbufWrapper when type is "ringbuf"
10638 The members of ChardevRingbufWrapper when type is "memory"
10640 Since
10642 1.4
10643 ChardevReturn (Object)
10645 Return info about the chardev backend just created.
10646 Members
10648 pty: string (optional)
10649 name of the slave pseudoterminal device, present if and only if
10650 a chardev of type 'pty' was created
10651 Since
10653 1.4
10654 chardev-add (Command)
10656 Add a character device backend
10657 Arguments
10659 id: string
10660 the chardev's ID, must be unique
10661 backend: ChardevBackend
10663 backend type and parameters
10664 Returns
10666 ChardevReturn.
10667 Since
10669 1.4
10670 Example
10672 -> { "execute" : "chardev-add",
10673 "arguments" : { "id" : "foo",
10674 "backend" : { "type" : "null", "data" : {} } } }
10675 <- { "return": {} }
10676 -> { "execute" : "chardev-add",
10678 "arguments" : { "id" : "bar",
10679 "backend" : { "type" : "file",
10680 "data" : { "out" : "/tmp/bar.log" } } } }
10681 <- { "return": {} }
10682 -> { "execute" : "chardev-add",
10684 "arguments" : { "id" : "baz",
10685 "backend" : { "type" : "pty", "data" : {} } } }
10686 <- { "return": { "pty" : "/dev/pty/42" } }
10687 chardev-change (Command)
10689 Change a character device backend
10690 Arguments
10692 id: string
10693 the chardev's ID, must exist
10694 backend: ChardevBackend
10696 new backend type and parameters
10697 Returns
10699 ChardevReturn.
10700 Since
10702 2.10
10703 Example
10705 -> { "execute" : "chardev-change",
10706 "arguments" : { "id" : "baz",
10707 "backend" : { "type" : "pty", "data" : {} } } }
10708 <- { "return": { "pty" : "/dev/pty/42" } }
10709 -> {"execute" : "chardev-change",
10711 "arguments" : {
10712 "id" : "charchannel2",
10713 "backend" : {
10714 "type" : "socket",
10715 "data" : {
10716 "addr" : {
10717 "type" : "unix" ,
10718 "data" : {
10719 "path" : "/tmp/charchannel2.socket"
10720 }
10721 },
10722 "server" : true,
10723 "wait" : false }}}}
10724 <- {"return": {}}
10725 chardev-remove (Command)
10727 Remove a character device backend
10728 Arguments
10730 id: string
10731 the chardev's ID, must exist and not be in use
10732 Returns
10734 Nothing on success
10735 Since
10737 1.4
10738 Example
10740 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
10741 <- { "return": {} }
10742 chardev-send-break (Command)
10744 Send a break to a character device
10745 Arguments
10747 id: string
10748 the chardev's ID, must exist
10749 Returns
10751 Nothing on success
10752 Since
10754 2.10
10755 Example
10757 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
10758 <- { "return": {} }
10759 VSERPORT_CHANGE (Event)
10761 Emitted when the guest opens or closes a virtio-serial port.
10762 Arguments
10764 id: string
10765 device identifier of the virtio-serial port
10766 open: boolean
10768 true if the guest has opened the virtio-serial port
10769 Note
10771 This event is rate-limited.
10772 Since
10774 2.1
10775 Example
10777 <- { "event": "VSERPORT_CHANGE",
10778 "data": { "id": "channel0", "open": true },
10779 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
10780
10782 DumpGuestMemoryFormat (Enum)
10783 An enumeration of guest-memory-dump's format.
10784 Values
10786 elf elf format
10787 kdump-zlib
10789 kdump-compressed format with zlib-compressed
10790 kdump-lzo
10792 kdump-compressed format with lzo-compressed
10793 kdump-snappy
10795 kdump-compressed format with snappy-compressed
10796 win-dmp
10798 Windows full crashdump format, can be used instead of ELF con‐
10799 verting (since 2.13)
10800 Since
10802 2.0
10803 dump-guest-memory (Command)
10805 Dump guest's memory to vmcore. It is a synchronous operation that can
10806 take very long depending on the amount of guest memory.
10807 Arguments
10809 paging: boolean
10810 if true, do paging to get guest's memory mapping. This allows
10811 using gdb to process the core file.
10812 IMPORTANT: this option can make QEMU allocate several gigabytes
10814 of RAM. This can happen for a large guest, or a malicious guest
10815 pretending to be large.
10816 Also, paging=true has the following limitations:
10818 1. The guest may be in a catastrophic state or can have cor‐
10820 rupted memory, which cannot be trusted
10821 2. The guest can be in real-mode even if paging is enabled.
10823 For example, the guest uses ACPI to sleep, and ACPI sleep
10824 state goes in real-mode
10825 3. Currently only supported on i386 and x86_64.
10827 protocol: string
10829 the filename or file descriptor of the vmcore. The supported
10830 protocols are:
10831 1. file: the protocol starts with "file:", and the following
10833 string is the file's path.
10834 2. fd: the protocol starts with "fd:", and the following string
10836 is the fd's name.
10837 detach: boolean (optional)
10839 if true, QMP will return immediately rather than waiting for the
10840 dump to finish. The user can track progress using "query-dump".
10841 (since 2.6).
10842 begin: int (optional)
10844 if specified, the starting physical address.
10845 length: int (optional)
10847 if specified, the memory size, in bytes. If you don't want to
10848 dump all guest's memory, please specify the start begin and
10849 length
10850 format: DumpGuestMemoryFormat (optional)
10852 if specified, the format of guest memory dump. But non-elf for‐
10853 mat is conflict with paging and filter, ie. paging, begin and
10854 length is not allowed to be specified with non-elf format at the
10855 same time (since 2.0)
10856 Note
10858 All boolean arguments default to false
10859 Returns
10861 nothing on success
10862 Since
10864 1.2
10865 Example
10867 -> { "execute": "dump-guest-memory",
10868 "arguments": { "paging": false, "protocol": "fd:dump" } }
10869 <- { "return": {} }
10870 DumpStatus (Enum)
10872 Describe the status of a long-running background guest memory dump.
10873 Values
10875 none no dump-guest-memory has started yet.
10876 active there is one dump running in background.
10878 completed
10880 the last dump has finished successfully.
10881 failed the last dump has failed.
10883 Since
10885 2.6
10886 DumpQueryResult (Object)
10888 The result format for 'query-dump'.
10889 Members
10891 status: DumpStatus
10892 enum of DumpStatus, which shows current dump status
10893 completed: int
10895 bytes written in latest dump (uncompressed)
10896 total: int
10898 total bytes to be written in latest dump (uncompressed)
10899 Since
10901 2.6
10902 query-dump (Command)
10904 Query latest dump status.
10905 Returns
10907 A DumpStatus object showing the dump status.
10908 Since
10910 2.6
10911 Example
10913 -> { "execute": "query-dump" }
10914 <- { "return": { "status": "active", "completed": 1024000,
10915 "total": 2048000 } }
10916 DUMP_COMPLETED (Event)
10918 Emitted when background dump has completed
10919 Arguments
10921 result: DumpQueryResult
10922 final dump status
10923 error: string (optional)
10925 human-readable error string that provides hint on why dump
10926 failed. Only presents on failure. The user should not try to in‐
10927 terpret the error string.
10928 Since
10930 2.6
10931 Example
10933 <- { "event": "DUMP_COMPLETED",
10934 "data": { "result": { "total": 1090650112, "status": "completed",
10935 "completed": 1090650112 } },
10936 "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }
10937 DumpGuestMemoryCapability (Object)
10939 A list of the available formats for dump-guest-memory
10940 Members
10942 formats: array of DumpGuestMemoryFormat
10943 Not documented
10944 Since
10946 2.0
10947 query-dump-guest-memory-capability (Command)
10949 Returns the available formats for dump-guest-memory
10950 Returns
10952 A DumpGuestMemoryCapability object listing available formats for
10953 dump-guest-memory
10954 Since
10956 2.0
10957 Example
10959 -> { "execute": "query-dump-guest-memory-capability" }
10960 <- { "return": { "formats":
10961 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } }
10962
10964 set_link (Command)
10965 Sets the link status of a virtual network adapter.
10966 Arguments
10968 name: string
10969 the device name of the virtual network adapter
10970 up: boolean
10972 true to set the link status to be up
10973 Returns
10975 Nothing on success If name is not a valid network device, DeviceNot‐
10976 Found
10977 Since
10979 0.14
10980 Notes
10982 Not all network adapters support setting link status. This command
10983 will succeed even if the network adapter does not support link status
10984 notification.
10985 Example
10987 -> { "execute": "set_link",
10988 "arguments": { "name": "e1000.0", "up": false } }
10989 <- { "return": {} }
10990 netdev_add (Command)
10992 Add a network backend.
10993 Additional arguments depend on the type.
10995 Arguments
10997 The members of Netdev
10998 Since
11000 0.14
11001 Returns
11003 Nothing on success If type is not a valid network backend, DeviceNot‐
11004 Found
11005 Example
11007 -> { "execute": "netdev_add",
11008 "arguments": { "type": "user", "id": "netdev1",
11009 "dnssearch": [ { "str": "example.org" } ] } }
11010 <- { "return": {} }
11011 netdev_del (Command)
11013 Remove a network backend.
11014 Arguments
11016 id: string
11017 the name of the network backend to remove
11018 Returns
11020 Nothing on success If id is not a valid network backend, DeviceNotFound
11021 Since
11023 0.14
11024 Example
11026 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
11027 <- { "return": {} }
11028 NetLegacyNicOptions (Object)
11030 Create a new Network Interface Card.
11031 Members
11033 netdev: string (optional)
11034 id of -netdev to connect to
11035 macaddr: string (optional)
11037 MAC address
11038 model: string (optional)
11040 device model (e1000, rtl8139, virtio etc.)
11041 addr: string (optional)
11043 PCI device address
11044 vectors: int (optional)
11046 number of MSI-x vectors, 0 to disable MSI-X
11047 Since
11049 1.2
11050 NetdevUserOptions (Object)
11052 Use the user mode network stack which requires no administrator privi‐
11053 lege to run.
11054 Members
11056 hostname: string (optional)
11057 client hostname reported by the builtin DHCP server
11058 restrict: boolean (optional)
11060 isolate the guest from the host
11061 ipv4: boolean (optional)
11063 whether to support IPv4, default true for enabled (since 2.6)
11064 ipv6: boolean (optional)
11066 whether to support IPv6, default true for enabled (since 2.6)
11067 ip: string (optional)
11069 legacy parameter, use net= instead
11070 net: string (optional)
11072 IP network address that the guest will see, in the form
11073 addr[/netmask] The netmask is optional, and can be either in the
11074 form a.b.c.d or as a number of valid top-most bits. Default is
11075 10.0.2.0/24.
11076 host: string (optional)
11078 guest-visible address of the host
11079 tftp: string (optional)
11081 root directory of the built-in TFTP server
11082 bootfile: string (optional)
11084 BOOTP filename, for use with tftp=
11085 dhcpstart: string (optional)
11087 the first of the 16 IPs the built-in DHCP server can assign
11088 dns: string (optional)
11090 guest-visible address of the virtual nameserver
11091 dnssearch: array of String (optional)
11093 list of DNS suffixes to search, passed as DHCP option to the
11094 guest
11095 domainname: string (optional)
11097 guest-visible domain name of the virtual nameserver (since 3.0)
11098 ipv6-prefix: string (optional)
11100 IPv6 network prefix (default is fec0::) (since 2.6). The network
11101 prefix is given in the usual hexadecimal IPv6 address notation.
11102 ipv6-prefixlen: int (optional)
11104 IPv6 network prefix length (default is 64) (since 2.6)
11105 ipv6-host: string (optional)
11107 guest-visible IPv6 address of the host (since 2.6)
11108 ipv6-dns: string (optional)
11110 guest-visible IPv6 address of the virtual nameserver (since 2.6)
11111 smb: string (optional)
11113 root directory of the built-in SMB server
11114 smbserver: string (optional)
11116 IP address of the built-in SMB server
11117 hostfwd: array of String (optional)
11119 redirect incoming TCP or UDP host connections to guest endpoints
11120 guestfwd: array of String (optional)
11122 forward guest TCP connections
11123 tftp-server-name: string (optional)
11125 RFC2132 "TFTP server name" string (Since 3.1)
11126 Since
11128 1.2
11129 NetdevTapOptions (Object)
11131 Used to configure a host TAP network interface backend.
11132 Members
11134 ifname: string (optional)
11135 interface name
11136 fd: string (optional)
11138 file descriptor of an already opened tap
11139 fds: string (optional)
11141 multiple file descriptors of already opened multiqueue capable
11142 tap
11143 script: string (optional)
11145 script to initialize the interface
11146 downscript: string (optional)
11148 script to shut down the interface
11149 br: string (optional)
11151 bridge name (since 2.8)
11152 helper: string (optional)
11154 command to execute to configure bridge
11155 sndbuf: int (optional)
11157 send buffer limit. Understands [TGMKkb] suffixes.
11158 vnet_hdr: boolean (optional)
11160 enable the IFF_VNET_HDR flag on the tap interface
11161 vhost: boolean (optional)
11163 enable vhost-net network accelerator
11164 vhostfd: string (optional)
11166 file descriptor of an already opened vhost net device
11167 vhostfds: string (optional)
11169 file descriptors of multiple already opened vhost net devices
11170 vhostforce: boolean (optional)
11172 vhost on for non-MSIX virtio guests
11173 queues: int (optional)
11175 number of queues to be created for multiqueue capable tap
11176 poll-us: int (optional)
11178 maximum number of microseconds that could be spent on busy
11179 polling for tap (since 2.7)
11180 Since
11182 1.2
11183 NetdevSocketOptions (Object)
11185 Socket netdevs are used to establish a network connection to another
11186 QEMU virtual machine via a TCP socket.
11187 Members
11189 fd: string (optional)
11190 file descriptor of an already opened socket
11191 listen: string (optional)
11193 port number, and optional hostname, to listen on
11194 connect: string (optional)
11196 port number, and optional hostname, to connect to
11197 mcast: string (optional)
11199 UDP multicast address and port number
11200 localaddr: string (optional)
11202 source address and port for multicast and udp packets
11203 udp: string (optional)
11205 UDP unicast address and port number
11206 Since
11208 1.2
11209 NetdevL2TPv3Options (Object)
11211 Configure an Ethernet over L2TPv3 tunnel.
11212 Members
11214 src: string
11215 source address
11216 dst: string
11218 destination address
11219 srcport: string (optional)
11221 source port - mandatory for udp, optional for ip
11222 dstport: string (optional)
11224 destination port - mandatory for udp, optional for ip
11225 ipv6: boolean (optional)
11227 force the use of ipv6
11228 udp: boolean (optional)
11230 use the udp version of l2tpv3 encapsulation
11231 cookie64: boolean (optional)
11233 use 64 bit cookies
11234 counter: boolean (optional)
11236 have sequence counter
11237 pincounter: boolean (optional)
11239 pin sequence counter to zero - workaround for buggy implementa‐
11240 tions or networks with packet reorder
11241 txcookie: int (optional)
11243 32 or 64 bit transmit cookie
11244 rxcookie: int (optional)
11246 32 or 64 bit receive cookie
11247 txsession: int
11249 32 bit transmit session
11250 rxsession: int (optional)
11252 32 bit receive session - if not specified set to the same value
11253 as transmit
11254 offset: int (optional)
11256 additional offset - allows the insertion of additional applica‐
11257 tion-specific data before the packet payload
11258 Since
11260 2.1
11261 NetdevVdeOptions (Object)
11263 Connect to a vde switch running on the host.
11264 Members
11266 sock: string (optional)
11267 socket path
11268 port: int (optional)
11270 port number
11271 group: string (optional)
11273 group owner of socket
11274 mode: int (optional)
11276 permissions for socket
11277 Since
11279 1.2
11280 NetdevBridgeOptions (Object)
11282 Connect a host TAP network interface to a host bridge device.
11283 Members
11285 br: string (optional)
11286 bridge name
11287 helper: string (optional)
11289 command to execute to configure bridge
11290 Since
11292 1.2
11293 NetdevHubPortOptions (Object)
11295 Connect two or more net clients through a software hub.
11296 Members
11298 hubid: int
11299 hub identifier number
11300 netdev: string (optional)
11302 used to connect hub to a netdev instead of a device (since 2.12)
11303 Since
11305 1.2
11306 NetdevNetmapOptions (Object)
11308 Connect a client to a netmap-enabled NIC or to a VALE switch port
11309 Members
11311 ifname: string
11312 Either the name of an existing network interface supported by
11313 netmap, or the name of a VALE port (created on the fly). A VALE
11314 port name is in the form 'valeXXX:YYY', where XXX and YYY are
11315 non-negative integers. XXX identifies a switch and YYY identi‐
11316 fies a port of the switch. VALE ports having the same XXX are
11317 therefore connected to the same switch.
11318 devname: string (optional)
11320 path of the netmap device (default: '/dev/netmap').
11321 Since
11323 2.0
11324 NetdevVhostUserOptions (Object)
11326 Vhost-user network backend
11327 Members
11329 chardev: string
11330 name of a unix socket chardev
11331 vhostforce: boolean (optional)
11333 vhost on for non-MSIX virtio guests (default: false).
11334 queues: int (optional)
11336 number of queues to be created for multiqueue vhost-user (de‐
11337 fault: 1) (Since 2.5)
11338 Since
11340 2.1
11341 NetdevVhostVDPAOptions (Object)
11343 Vhost-vdpa network backend
11344 vDPA device is a device that uses a datapath which complies with the
11346 virtio specifications with a vendor specific control path.
11347 Members
11349 vhostdev: string (optional)
11350 path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
11351 vhostfd: string (optional)
11353 file descriptor of an already opened vhost vdpa device
11354 queues: int (optional)
11356 number of queues to be created for multiqueue vhost-vdpa (de‐
11357 fault: 1)
11358 x-svq: boolean (optional)
11360 Start device with (experimental) shadow virtqueue. (Since 7.1)
11361 (default: false)
11362 Features
11364 unstable
11365 Member x-svq is experimental.
11366 Since
11368 5.1
11369 NetdevVmnetHostOptions (Object)
11371 vmnet (host mode) network backend.
11372 Allows the vmnet interface to communicate with other vmnet interfaces
11374 that are in host mode and also with the host.
11375 Members
11377 start-address: string (optional)
11378 The starting IPv4 address to use for the interface. Must be in
11379 the private IP range (RFC 1918). Must be specified along with
11380 end-address and subnet-mask. This address is used as the gate‐
11381 way address. The subsequent address up to and including end-ad‐
11382 dress are placed in the DHCP pool.
11383 end-address: string (optional)
11385 The DHCP IPv4 range end address to use for the interface. Must
11386 be in the private IP range (RFC 1918). Must be specified along
11387 with start-address and subnet-mask.
11388 subnet-mask: string (optional)
11390 The IPv4 subnet mask to use on the interface. Must be specified
11391 along with start-address and subnet-mask.
11392 isolated: boolean (optional)
11394 Enable isolation for this interface. Interface isolation ensures
11395 that vmnet interface is not able to communicate with any other
11396 vmnet interfaces. Only communication with host is allowed. Re‐
11397 quires at least macOS Big Sur 11.0.
11398 net-uuid: string (optional)
11400 The identifier (UUID) to uniquely identify the isolated network
11401 vmnet interface should be added to. If set, no DHCP service is
11402 provided for this interface and network communication is allowed
11403 only with other interfaces added to this network identified by
11404 the UUID. Requires at least macOS Big Sur 11.0.
11405 Since
11407 7.1
11408 If
11410 CONFIG_VMNET
11411 NetdevVmnetSharedOptions (Object)
11413 vmnet (shared mode) network backend.
11414 Allows traffic originating from the vmnet interface to reach the Inter‐
11416 net through a network address translator (NAT). The vmnet interface
11417 can communicate with the host and with other shared mode interfaces on
11418 the same subnet. If no DHCP settings, subnet mask and IPv6 prefix spec‐
11419 ified, the interface can communicate with any of other interfaces in
11420 shared mode.
11421 Members
11423 start-address: string (optional)
11424 The starting IPv4 address to use for the interface. Must be in
11425 the private IP range (RFC 1918). Must be specified along with
11426 end-address and subnet-mask. This address is used as the gate‐
11427 way address. The subsequent address up to and including end-ad‐
11428 dress are placed in the DHCP pool.
11429 end-address: string (optional)
11431 The DHCP IPv4 range end address to use for the interface. Must
11432 be in the private IP range (RFC 1918). Must be specified along
11433 with start-address and subnet-mask.
11434 subnet-mask: string (optional)
11436 The IPv4 subnet mask to use on the interface. Must
11438 be specified along with start-address and subnet-mask.
11439 isolated: boolean (optional)
11441 Enable isolation for this interface. Interface isolation ensures
11442 that vmnet interface is not able to communicate with any other
11443 vmnet interfaces. Only communication with host is allowed. Re‐
11444 quires at least macOS Big Sur 11.0.
11445 nat66-prefix: string (optional)
11447 The IPv6 prefix to use into guest network. Must be a unique lo‐
11448 cal address i.e. start with fd00::/8 and have length of 64.
11449 Since
11451 7.1
11452 If
11454 CONFIG_VMNET
11455 NetdevVmnetBridgedOptions (Object)
11457 vmnet (bridged mode) network backend.
11458 Bridges the vmnet interface with a physical network interface.
11460 Members
11462 ifname: string
11463 The name of the physical interface to be bridged.
11464 isolated: boolean (optional)
11466 Enable isolation for this interface. Interface isolation ensures
11467 that vmnet interface is not able to communicate with any other
11468 vmnet interfaces. Only communication with host is allowed. Re‐
11469 quires at least macOS Big Sur 11.0.
11470 Since
11472 7.1
11473 If
11475 CONFIG_VMNET
11476 NetdevStreamOptions (Object)
11478 Configuration info for stream socket netdev
11479 Members
11481 addr: SocketAddress
11482 socket address to listen on (server=true) or connect to
11483 (server=false)
11484 server: boolean (optional)
11486 create server socket (default: false)
11487 Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
11488 Since
11490 7.2
11491 NetdevDgramOptions (Object)
11493 Configuration info for datagram socket netdev.
11494 Members
11496 remote: SocketAddress (optional)
11497 remote address
11498 local: SocketAddress (optional)
11500 local address
11501 Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
11502 If remote address is present and it's a multicast address, local ad‐
11504 dress is optional. Otherwise local address is required and remote ad‐
11505 dress is optional.
11506 Valid parameters combination table
11508 ┌──────────────┬─────────┬───────┐
11509 │remote │ local │ okay? │
11510 ├──────────────┼─────────┼───────┤
11511 │absent │ absent │ no │
11512 ├──────────────┼─────────┼───────┤
11513 │absent │ not fd │ no │
11514 ├──────────────┼─────────┼───────┤
11515 │absent │ fd │ yes │
11516 ├──────────────┼─────────┼───────┤
11517 │multicast │ absent │ yes │
11518 ├──────────────┼─────────┼───────┤
11519 │multicast │ present │ yes │
11520 ├──────────────┼─────────┼───────┤
11521 │not multicast │ absent │ no │
11522 ├──────────────┼─────────┼───────┤
11523 │not multicast │ present │ yes │
11524 └──────────────┴─────────┴───────┘
11525 Since
11527 7.2
11528 NetClientDriver (Enum)
11530 Available netdev drivers.
11531 Values
11533 none Not documented
11534 nic Not documented
11536 user Not documented
11538 tap Not documented
11540 l2tpv3 Not documented
11542 socket Not documented
11544 stream Not documented
11546 dgram Not documented
11548 vde Not documented
11550 bridge Not documented
11552 hubport
11554 Not documented
11555 netmap Not documented
11557 vhost-user
11559 Not documented
11560 vhost-vdpa
11562 Not documented
11563 vmnet-host (If: CONFIG_VMNET)
11565 Not documented
11566 vmnet-shared (If: CONFIG_VMNET)
11568 Not documented
11569 vmnet-bridged (If: CONFIG_VMNET)
11571 Not documented
11572 Since
11574 2.7
11575 vhost-vdpa since 5.1 vmnet-host since 7.1 vmnet-shared since 7.1 vm‐
11577 net-bridged since 7.1 stream since 7.2 dgram since 7.2
11578 Netdev (Object)
11580 Captures the configuration of a network device.
11581 Members
11583 id: string
11584 identifier for monitor commands.
11585 type: NetClientDriver
11587 Specify the driver used for interpreting remaining arguments.
11588 The members of NetLegacyNicOptions when type is "nic"
11590 The members of NetdevUserOptions when type is "user"
11592 The members of NetdevTapOptions when type is "tap"
11594 The members of NetdevL2TPv3Options when type is "l2tpv3"
11596 The members of NetdevSocketOptions when type is "socket"
11598 The members of NetdevStreamOptions when type is "stream"
11600 The members of NetdevDgramOptions when type is "dgram"
11602 The members of NetdevVdeOptions when type is "vde"
11604 The members of NetdevBridgeOptions when type is "bridge"
11606 The members of NetdevHubPortOptions when type is "hubport"
11608 The members of NetdevNetmapOptions when type is "netmap"
11610 The members of NetdevVhostUserOptions when type is "vhost-user"
11612 The members of NetdevVhostVDPAOptions when type is "vhost-vdpa"
11614 The members of NetdevVmnetHostOptions when type is "vmnet-host" (If:
11616 CONFIG_VMNET)
11617 The members of NetdevVmnetSharedOptions when type is "vmnet-shared"
11619 (If: CONFIG_VMNET)
11620 The members of NetdevVmnetBridgedOptions when type is "vmnet-bridged"
11622 (If: CONFIG_VMNET)
11623 Since
11625 1.2
11626 'l2tpv3' - since 2.1 'vmnet-host' - since 7.1 'vmnet-shared' - since
11628 7.1 'vmnet-bridged' - since 7.1 'stream' since 7.2 'dgram' since 7.2
11629 RxState (Enum)
11631 Packets receiving state
11632 Values
11634 normal filter assigned packets according to the mac-table
11635 none don't receive any assigned packet
11637 all receive all assigned packets
11639 Since
11641 1.6
11642 RxFilterInfo (Object)
11644 Rx-filter information for a NIC.
11645 Members
11647 name: string
11648 net client name
11649 promiscuous: boolean
11651 whether promiscuous mode is enabled
11652 multicast: RxState
11654 multicast receive state
11655 unicast: RxState
11657 unicast receive state
11658 vlan: RxState
11660 vlan receive state (Since 2.0)
11661 broadcast-allowed: boolean
11663 whether to receive broadcast
11664 multicast-overflow: boolean
11666 multicast table is overflowed or not
11667 unicast-overflow: boolean
11669 unicast table is overflowed or not
11670 main-mac: string
11672 the main macaddr string
11673 vlan-table: array of int
11675 a list of active vlan id
11676 unicast-table: array of string
11678 a list of unicast macaddr string
11679 multicast-table: array of string
11681 a list of multicast macaddr string
11682 Since
11684 1.6
11685 query-rx-filter (Command)
11687 Return rx-filter information for all NICs (or for the given NIC).
11688 Arguments
11690 name: string (optional)
11691 net client name
11692 Returns
11694 list of RxFilterInfo for all NICs (or for the given NIC). Returns an
11695 error if the given name doesn't exist, or given NIC doesn't support
11696 rx-filter querying, or given net client isn't a NIC.
11697 Since
11699 1.6
11700 Example
11702 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
11703 <- { "return": [
11704 {
11705 "promiscuous": true,
11706 "name": "vnet0",
11707 "main-mac": "52:54:00:12:34:56",
11708 "unicast": "normal",
11709 "vlan": "normal",
11710 "vlan-table": [
11711 4,
11712 0
11713 ],
11714 "unicast-table": [
11715 ],
11716 "multicast": "normal",
11717 "multicast-overflow": false,
11718 "unicast-overflow": false,
11719 "multicast-table": [
11720 "01:00:5e:00:00:01",
11721 "33:33:00:00:00:01",
11722 "33:33:ff:12:34:56"
11723 ],
11724 "broadcast-allowed": false
11725 }
11726 ]
11727 }
11728 NIC_RX_FILTER_CHANGED (Event)
11730 Emitted once until the 'query-rx-filter' command is executed, the first
11731 event will always be emitted
11732 Arguments
11734 name: string (optional)
11735 net client name
11736 path: string
11738 device path
11739 Since
11741 1.6
11742 Example
11744 <- { "event": "NIC_RX_FILTER_CHANGED",
11745 "data": { "name": "vnet0",
11746 "path": "/machine/peripheral/vnet0/virtio-backend" },
11747 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
11748 AnnounceParameters (Object)
11750 Parameters for self-announce timers
11751 Members
11753 initial: int
11754 Initial delay (in ms) before sending the first GARP/RARP an‐
11755 nouncement
11756 max: int
11758 Maximum delay (in ms) between GARP/RARP announcement packets
11759 rounds: int
11761 Number of self-announcement attempts
11762 step: int
11764 Delay increase (in ms) after each self-announcement attempt
11765 interfaces: array of string (optional)
11767 An optional list of interface names, which restricts the an‐
11768 nouncement to the listed interfaces. (Since 4.1)
11769 id: string (optional)
11771 A name to be used to identify an instance of announce-timers and
11772 to allow it to modified later. Not for use as part of the mi‐
11773 gration parameters. (Since 4.1)
11774 Since
11776 4.0
11777 announce-self (Command)
11779 Trigger generation of broadcast RARP frames to update network switches.
11780 This can be useful when network bonds fail-over the active slave.
11781 Arguments
11783 The members of AnnounceParameters
11784 Example
11786 -> { "execute": "announce-self",
11787 "arguments": {
11788 "initial": 50, "max": 550, "rounds": 10, "step": 50,
11789 "interfaces": ["vn2", "vn3"], "id": "bob" } }
11790 <- { "return": {} }
11791 Since
11793 4.0
11794 FAILOVER_NEGOTIATED (Event)
11796 Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotia‐
11797 tion. Failover primary devices which were hidden (not hotplugged when
11798 requested) before will now be hotplugged by the virtio-net standby de‐
11799 vice.
11800 Arguments
11802 device-id: string
11803 QEMU device id of the unplugged device
11804 Since
11806 4.2
11807 Example
11809 <- { "event": "FAILOVER_NEGOTIATED",
11810 "data": { "device-id": "net1" },
11811 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
11812 NETDEV_STREAM_CONNECTED (Event)
11814 Emitted when the netdev stream backend is connected
11815 Arguments
11817 netdev-id: string
11818 QEMU netdev id that is connected
11819 addr: SocketAddress
11821 The destination address
11822 Since
11824 7.2
11825 Example
11827 <- { "event": "NETDEV_STREAM_CONNECTED",
11828 "data": { "netdev-id": "netdev0",
11829 "addr": { "port": "47666", "ipv6": true,
11830 "host": "::1", "type": "inet" } },
11831 "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }
11832 or
11834 <- { "event": "NETDEV_STREAM_CONNECTED",
11836 "data": { "netdev-id": "netdev0",
11837 "addr": { "path": "/tmp/qemu0", "type": "unix" } },
11838 "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }
11839 NETDEV_STREAM_DISCONNECTED (Event)
11841 Emitted when the netdev stream backend is disconnected
11842 Arguments
11844 netdev-id: string
11845 QEMU netdev id that is disconnected
11846 Since
11848 7.2
11849 Example
11851 <- { 'event': 'NETDEV_STREAM_DISCONNECTED',
11852 'data': {'netdev-id': 'netdev0'},
11853 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} }
11854
11856 RDMA_GID_STATUS_CHANGED (Event)
11857 Emitted when guest driver adds/deletes GID to/from device
11858 Arguments
11860 netdev: string
11861 RoCE Network Device name
11862 gid-status: boolean
11864 Add or delete indication
11865 subnet-prefix: int
11867 Subnet Prefix
11868 interface-id: int
11870 Not documented
11871 interface-id : Interface ID
11872 Since
11874 4.0
11875 Example
11877 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
11878 "event": "RDMA_GID_STATUS_CHANGED",
11879 "data":
11880 {"netdev": "bridge0",
11881 "interface-id": 15880512517475447892,
11882 "gid-status": true,
11883 "subnet-prefix": 33022}}
11884
11886 RockerSwitch (Object)
11887 Rocker switch information.
11888 Members
11890 name: string
11891 switch name
11892 id: int
11894 switch ID
11895 ports: int
11897 number of front-panel ports
11898 Since
11900 2.4
11901 query-rocker (Command)
11903 Return rocker switch information.
11904 Arguments
11906 name: string
11907 Not documented
11908 Returns
11910 Rocker information
11911 Since
11913 2.4
11914 Example
11916 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
11917 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
11918 RockerPortDuplex (Enum)
11920 An eumeration of port duplex states.
11921 Values
11923 half half duplex
11924 full full duplex
11926 Since
11928 2.4
11929 RockerPortAutoneg (Enum)
11931 An eumeration of port autoneg states.
11932 Values
11934 off autoneg is off
11935 on autoneg is on
11937 Since
11939 2.4
11940 RockerPort (Object)
11942 Rocker switch port information.
11943 Members
11945 name: string
11946 port name
11947 enabled: boolean
11949 port is enabled for I/O
11950 link-up: boolean
11952 physical link is UP on port
11953 speed: int
11955 port link speed in Mbps
11956 duplex: RockerPortDuplex
11958 port link duplex
11959 autoneg: RockerPortAutoneg
11961 port link autoneg
11962 Since
11964 2.4
11965 query-rocker-ports (Command)
11967 Return rocker switch port information.
11968 Arguments
11970 name: string
11971 Not documented
11972 Returns
11974 a list of RockerPort information
11975 Since
11977 2.4
11978 Example
11980 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
11981 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
11982 "autoneg": "off", "link-up": true, "speed": 10000},
11983 {"duplex": "full", "enabled": true, "name": "sw1.2",
11984 "autoneg": "off", "link-up": true, "speed": 10000}
11985 ]}
11986 RockerOfDpaFlowKey (Object)
11988 Rocker switch OF-DPA flow key
11989 Members
11991 priority: int
11992 key priority, 0 being lowest priority
11993 tbl-id: int
11995 flow table ID
11996 in-pport: int (optional)
11998 physical input port
11999 tunnel-id: int (optional)
12001 tunnel ID
12002 vlan-id: int (optional)
12004 VLAN ID
12005 eth-type: int (optional)
12007 Ethernet header type
12008 eth-src: string (optional)
12010 Ethernet header source MAC address
12011 eth-dst: string (optional)
12013 Ethernet header destination MAC address
12014 ip-proto: int (optional)
12016 IP Header protocol field
12017 ip-tos: int (optional)
12019 IP header TOS field
12020 ip-dst: string (optional)
12022 IP header destination address
12023 Note
12025 optional members may or may not appear in the flow key depending if
12026 they're relevant to the flow key.
12027 Since
12029 2.4
12030 RockerOfDpaFlowMask (Object)
12032 Rocker switch OF-DPA flow mask
12033 Members
12035 in-pport: int (optional)
12036 physical input port
12037 tunnel-id: int (optional)
12039 tunnel ID
12040 vlan-id: int (optional)
12042 VLAN ID
12043 eth-src: string (optional)
12045 Ethernet header source MAC address
12046 eth-dst: string (optional)
12048 Ethernet header destination MAC address
12049 ip-proto: int (optional)
12051 IP Header protocol field
12052 ip-tos: int (optional)
12054 IP header TOS field
12055 Note
12057 optional members may or may not appear in the flow mask depending if
12058 they're relevant to the flow mask.
12059 Since
12061 2.4
12062 RockerOfDpaFlowAction (Object)
12064 Rocker switch OF-DPA flow action
12065 Members
12067 goto-tbl: int (optional)
12068 next table ID
12069 group-id: int (optional)
12071 group ID
12072 tunnel-lport: int (optional)
12074 tunnel logical port ID
12075 vlan-id: int (optional)
12077 VLAN ID
12078 new-vlan-id: int (optional)
12080 new VLAN ID
12081 out-pport: int (optional)
12083 physical output port
12084 Note
12086 optional members may or may not appear in the flow action depending if
12087 they're relevant to the flow action.
12088 Since
12090 2.4
12091 RockerOfDpaFlow (Object)
12093 Rocker switch OF-DPA flow
12094 Members
12096 cookie: int
12097 flow unique cookie ID
12098 hits: int
12100 count of matches (hits) on flow
12101 key: RockerOfDpaFlowKey
12103 flow key
12104 mask: RockerOfDpaFlowMask
12106 flow mask
12107 action: RockerOfDpaFlowAction
12109 flow action
12110 Since
12112 2.4
12113 query-rocker-of-dpa-flows (Command)
12115 Return rocker OF-DPA flow information.
12116 Arguments
12118 name: string
12119 switch name
12120 tbl-id: int (optional)
12122 flow table ID. If tbl-id is not specified, returns flow infor‐
12123 mation for all tables.
12124 Returns
12126 rocker OF-DPA flow information
12127 Since
12129 2.4
12130 Example
12132 -> { "execute": "query-rocker-of-dpa-flows",
12133 "arguments": { "name": "sw1" } }
12134 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
12135 "hits": 138,
12136 "cookie": 0,
12137 "action": {"goto-tbl": 10},
12138 "mask": {"in-pport": 4294901760}
12139 },
12140 {...more...},
12141 ]}
12142 RockerOfDpaGroup (Object)
12144 Rocker switch OF-DPA group
12145 Members
12147 id: int
12148 group unique ID
12149 type: int
12151 group type
12152 vlan-id: int (optional)
12154 VLAN ID
12155 pport: int (optional)
12157 physical port number
12158 index: int (optional)
12160 group index, unique with group type
12161 out-pport: int (optional)
12163 output physical port number
12164 group-id: int (optional)
12166 next group ID
12167 set-vlan-id: int (optional)
12169 VLAN ID to set
12170 pop-vlan: int (optional)
12172 pop VLAN headr from packet
12173 group-ids: array of int (optional)
12175 list of next group IDs
12176 set-eth-src: string (optional)
12178 set source MAC address in Ethernet header
12179 set-eth-dst: string (optional)
12181 set destination MAC address in Ethernet header
12182 ttl-check: int (optional)
12184 perform TTL check
12185 Note
12187 optional members may or may not appear in the group depending if
12188 they're relevant to the group type.
12189 Since
12191 2.4
12192 query-rocker-of-dpa-groups (Command)
12194 Return rocker OF-DPA group information.
12195 Arguments
12197 name: string
12198 switch name
12199 type: int (optional)
12201 group type. If type is not specified, returns group information
12202 for all group types.
12203 Returns
12205 rocker OF-DPA group information
12206 Since
12208 2.4
12209 Example
12211 -> { "execute": "query-rocker-of-dpa-groups",
12212 "arguments": { "name": "sw1" } }
12213 <- { "return": [ {"type": 0, "out-pport": 2,
12214 "pport": 2, "vlan-id": 3841,
12215 "pop-vlan": 1, "id": 251723778},
12216 {"type": 0, "out-pport": 0,
12217 "pport": 0, "vlan-id": 3841,
12218 "pop-vlan": 1, "id": 251723776},
12219 {"type": 0, "out-pport": 1,
12220 "pport": 1, "vlan-id": 3840,
12221 "pop-vlan": 1, "id": 251658241},
12222 {"type": 0, "out-pport": 0,
12223 "pport": 0, "vlan-id": 3840,
12224 "pop-vlan": 1, "id": 251658240}
12225 ]}
12226
12228 TpmModel (Enum)
12229 An enumeration of TPM models
12230 Values
12232 tpm-tis
12233 TPM TIS model
12234 tpm-crb
12236 TPM CRB model (since 2.12)
12237 tpm-spapr
12239 TPM SPAPR model (since 5.0)
12240 Since
12242 1.5
12243 If
12245 CONFIG_TPM
12246 query-tpm-models (Command)
12248 Return a list of supported TPM models
12249 Returns
12251 a list of TpmModel
12252 Since
12254 1.5
12255 Example
12257 -> { "execute": "query-tpm-models" }
12258 <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
12259 If
12261 CONFIG_TPM
12262 TpmType (Enum)
12264 An enumeration of TPM types
12265 Values
12267 passthrough
12268 TPM passthrough type
12269 emulator
12271 Software Emulator TPM type Since: 2.11
12272 Since
12274 1.5
12275 If
12277 CONFIG_TPM
12278 query-tpm-types (Command)
12280 Return a list of supported TPM types
12281 Returns
12283 a list of TpmType
12284 Since
12286 1.5
12287 Example
12289 -> { "execute": "query-tpm-types" }
12290 <- { "return": [ "passthrough", "emulator" ] }
12291 If
12293 CONFIG_TPM
12294 TPMPassthroughOptions (Object)
12296 Information about the TPM passthrough type
12297 Members
12299 path: string (optional)
12300 string describing the path used for accessing the TPM device
12301 cancel-path: string (optional)
12303 string showing the TPM's sysfs cancel file for cancellation of
12304 TPM commands while they are executing
12305 Since
12307 1.5
12308 If
12310 CONFIG_TPM
12311 TPMEmulatorOptions (Object)
12313 Information about the TPM emulator type
12314 Members
12316 chardev: string
12317 Name of a unix socket chardev
12318 Since
12320 2.11
12321 If
12323 CONFIG_TPM
12324 TPMPassthroughOptionsWrapper (Object)
12326 Members
12327 data: TPMPassthroughOptions
12328 Not documented
12329 Since
12331 1.5
12332 If
12334 CONFIG_TPM
12335 TPMEmulatorOptionsWrapper (Object)
12337 Members
12338 data: TPMEmulatorOptions
12339 Not documented
12340 Since
12342 2.11
12343 If
12345 CONFIG_TPM
12346 TpmTypeOptions (Object)
12348 A union referencing different TPM backend types' configuration options
12349 Members
12351 type: TpmType
12352 • 'passthrough' The configuration options for the TPM
12354 passthrough type
12355 • 'emulator' The configuration options for TPM emulator backend
12357 type
12358 The members of TPMPassthroughOptionsWrapper when type is "passthrough"
12360 The members of TPMEmulatorOptionsWrapper when type is "emulator"
12362 Since
12364 1.5
12365 If
12367 CONFIG_TPM
12368 TPMInfo (Object)
12370 Information about the TPM
12371 Members
12373 id: string
12374 The Id of the TPM
12375 model: TpmModel
12377 The TPM frontend model
12378 options: TpmTypeOptions
12380 The TPM (backend) type configuration options
12381 Since
12383 1.5
12384 If
12386 CONFIG_TPM
12387 query-tpm (Command)
12389 Return information about the TPM device
12390 Returns
12392 TPMInfo on success
12393 Since
12395 1.5
12396 Example
12398 -> { "execute": "query-tpm" }
12399 <- { "return":
12400 [
12401 { "model": "tpm-tis",
12402 "options":
12403 { "type": "passthrough",
12404 "data":
12405 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
12406 "path": "/dev/tpm0"
12407 }
12408 },
12409 "id": "tpm0"
12410 }
12411 ]
12412 }
12413 If
12415 CONFIG_TPM
12416
12418 DisplayProtocol (Enum)
12419 Display protocols which support changing password options.
12420 Values
12422 vnc Not documented
12423 spice Not documented
12425 Since
12427 7.0
12428 SetPasswordAction (Enum)
12430 An action to take on changing a password on a connection with active
12431 clients.
12432 Values
12434 keep maintain existing clients
12435 fail fail the command if clients are connected
12437 disconnect
12439 disconnect existing clients
12440 Since
12442 7.0
12443 SetPasswordOptions (Object)
12445 Options for set_password.
12446 Members
12448 protocol: DisplayProtocol
12449 • 'vnc' to modify the VNC server password
12451 • 'spice' to modify the Spice server password
12453 password: string
12455 the new password
12456 connected: SetPasswordAction (optional)
12458 How to handle existing clients when changing the password. If
12459 nothing is specified, defaults to 'keep'. For VNC, only 'keep'
12460 is currently implemented.
12461 The members of SetPasswordOptionsVnc when protocol is "vnc"
12463 Since
12465 7.0
12466 SetPasswordOptionsVnc (Object)
12468 Options for set_password specific to the VNC procotol.
12469 Members
12471 display: string (optional)
12472 The id of the display where the password should be changed. De‐
12473 faults to the first.
12474 Since
12476 7.0
12477 set_password (Command)
12479 Set the password of a remote display server.
12480 Arguments
12482 The members of SetPasswordOptions
12483 Returns
12485 • Nothing on success
12486 • If Spice is not enabled, DeviceNotFound
12488 Since
12490 0.14
12491 Example
12493 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
12494 "password": "secret" } }
12495 <- { "return": {} }
12496 ExpirePasswordOptions (Object)
12498 General options for expire_password.
12499 Members
12501 protocol: DisplayProtocol
12502 • 'vnc' to modify the VNC server expiration
12504 • 'spice' to modify the Spice server expiration
12506 time: string
12508 when to expire the password.
12509 • 'now' to expire the password immediately
12511 • 'never' to cancel password expiration
12513 • '+INT' where INT is the number of seconds from now (integer)
12515 • 'INT' where INT is the absolute time in seconds
12517 The members of ExpirePasswordOptionsVnc when protocol is "vnc"
12519 Notes
12521 Time is relative to the server and currently there is no way to coordi‐
12522 nate server time with client time. It is not recommended to use the
12523 absolute time version of the time parameter unless you're sure you are
12524 on the same machine as the QEMU instance.
12525 Since
12527 7.0
12528 ExpirePasswordOptionsVnc (Object)
12530 Options for expire_password specific to the VNC procotol.
12531 Members
12533 display: string (optional)
12534 The id of the display where the expiration should be changed.
12535 Defaults to the first.
12536 Since
12538 7.0
12539 expire_password (Command)
12541 Expire the password of a remote display server.
12542 Arguments
12544 The members of ExpirePasswordOptions
12545 Returns
12547 • Nothing on success
12548 • If protocol is 'spice' and Spice is not active, DeviceNotFound
12550 Since
12552 0.14
12553 Example
12555 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
12556 "time": "+60" } }
12557 <- { "return": {} }
12558 ImageFormat (Enum)
12560 Supported image format types.
12561 Values
12563 png PNG format
12564 ppm PPM format
12566 Since
12568 7.1
12569 screendump (Command)
12571 Capture the contents of a screen and write it to a file.
12572 Arguments
12574 filename: string
12575 the path of a new file to store the image
12576 device: string (optional)
12578 ID of the display device that should be dumped. If this parame‐
12579 ter is missing, the primary display will be used. (Since 2.12)
12580 head: int (optional)
12582 head to use in case the device supports multiple heads. If this
12583 parameter is missing, head #0 will be used. Also note that the
12584 head can only be specified in conjunction with the device ID.
12585 (Since 2.12)
12586 format: ImageFormat (optional)
12588 image format for screendump. (default: ppm) (Since 7.1)
12589 Returns
12591 Nothing on success
12592 Since
12594 0.14
12595 Example
12597 -> { "execute": "screendump",
12598 "arguments": { "filename": "/tmp/image" } }
12599 <- { "return": {} }
12600 Spice
12602 SpiceBasicInfo (Object)
12603 The basic information for SPICE network connection
12604 Members
12606 host: string
12607 IP address
12608 port: string
12610 port number
12611 family: NetworkAddressFamily
12613 address family
12614 Since
12616 2.1
12617 If
12619 CONFIG_SPICE
12620 SpiceServerInfo (Object)
12622 Information about a SPICE server
12623 Members
12625 auth: string (optional)
12626 authentication method
12627 The members of SpiceBasicInfo
12629 Since
12631 2.1
12632 If
12634 CONFIG_SPICE
12635 SpiceChannel (Object)
12637 Information about a SPICE client channel.
12638 Members
12640 connection-id: int
12641 SPICE connection id number. All channels with the same id be‐
12642 long to the same SPICE session.
12643 channel-type: int
12645 SPICE channel type number. "1" is the main control channel,
12646 filter for this one if you want to track spice sessions only
12647 channel-id: int
12649 SPICE channel ID number. Usually "0", might be different when
12650 multiple channels of the same type exist, such as multiple dis‐
12651 play channels in a multihead setup
12652 tls: boolean
12654 true if the channel is encrypted, false otherwise.
12655 The members of SpiceBasicInfo
12657 Since
12659 0.14
12660 If
12662 CONFIG_SPICE
12663 SpiceQueryMouseMode (Enum)
12665 An enumeration of Spice mouse states.
12666 Values
12668 client Mouse cursor position is determined by the client.
12669 server Mouse cursor position is determined by the server.
12671 unknown
12673 No information is available about mouse mode used by the spice
12674 server.
12675 Note
12677 spice/enums.h has a SpiceMouseMode already, hence the name.
12678 Since
12680 1.1
12681 If
12683 CONFIG_SPICE
12684 SpiceInfo (Object)
12686 Information about the SPICE session.
12687 Members
12689 enabled: boolean
12690 true if the SPICE server is enabled, false otherwise
12691 migrated: boolean
12693 true if the last guest migration completed and spice migration
12694 had completed as well. false otherwise. (since 1.4)
12695 host: string (optional)
12697 The hostname the SPICE server is bound to. This depends on the
12698 name resolution on the host and may be an IP address.
12699 port: int (optional)
12701 The SPICE server's port number.
12702 compiled-version: string (optional)
12704 SPICE server version.
12705 tls-port: int (optional)
12707 The SPICE server's TLS port number.
12708 auth: string (optional)
12710 the current authentication type used by the server
12711 • 'none' if no authentication is being used
12713 • 'spice' uses SASL or direct TLS authentication, depending on
12715 command line options
12716 mouse-mode: SpiceQueryMouseMode
12718 The mode in which the mouse cursor is displayed currently. Can
12719 be determined by the client or the server, or unknown if spice
12720 server doesn't provide this information. (since: 1.1)
12721 channels: array of SpiceChannel (optional)
12723 a list of SpiceChannel for each active spice channel
12724 Since
12726 0.14
12727 If
12729 CONFIG_SPICE
12730 query-spice (Command)
12732 Returns information about the current SPICE server
12733 Returns
12735 SpiceInfo
12736 Since
12738 0.14
12739 Example
12741 -> { "execute": "query-spice" }
12742 <- { "return": {
12743 "enabled": true,
12744 "auth": "spice",
12745 "port": 5920,
12746 "migrated":false,
12747 "tls-port": 5921,
12748 "host": "0.0.0.0",
12749 "mouse-mode":"client",
12750 "channels": [
12751 {
12752 "port": "54924",
12753 "family": "ipv4",
12754 "channel-type": 1,
12755 "connection-id": 1804289383,
12756 "host": "127.0.0.1",
12757 "channel-id": 0,
12758 "tls": true
12759 },
12760 {
12761 "port": "36710",
12762 "family": "ipv4",
12763 "channel-type": 4,
12764 "connection-id": 1804289383,
12765 "host": "127.0.0.1",
12766 "channel-id": 0,
12767 "tls": false
12768 },
12769 [ ... more channels follow ... ]
12770 ]
12771 }
12772 }
12773 If
12775 CONFIG_SPICE
12776 SPICE_CONNECTED (Event)
12778 Emitted when a SPICE client establishes a connection
12779 Arguments
12781 server: SpiceBasicInfo
12782 server information
12783 client: SpiceBasicInfo
12785 client information
12786 Since
12788 0.14
12789 Example
12791 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
12792 "event": "SPICE_CONNECTED",
12793 "data": {
12794 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
12795 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
12796 }}
12797 If
12799 CONFIG_SPICE
12800 SPICE_INITIALIZED (Event)
12802 Emitted after initial handshake and authentication takes place (if any)
12803 and the SPICE channel is up and running
12804 Arguments
12806 server: SpiceServerInfo
12807 server information
12808 client: SpiceChannel
12810 client information
12811 Since
12813 0.14
12814 Example
12816 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
12817 "event": "SPICE_INITIALIZED",
12818 "data": {"server": {"auth": "spice", "port": "5921",
12819 "family": "ipv4", "host": "127.0.0.1"},
12820 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
12821 "connection-id": 1804289383, "host": "127.0.0.1",
12822 "channel-id": 0, "tls": true}
12823 }}
12824 If
12826 CONFIG_SPICE
12827 SPICE_DISCONNECTED (Event)
12829 Emitted when the SPICE connection is closed
12830 Arguments
12832 server: SpiceBasicInfo
12833 server information
12834 client: SpiceBasicInfo
12836 client information
12837 Since
12839 0.14
12840 Example
12842 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
12843 "event": "SPICE_DISCONNECTED",
12844 "data": {
12845 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
12846 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
12847 }}
12848 If
12850 CONFIG_SPICE
12851 SPICE_MIGRATE_COMPLETED (Event)
12853 Emitted when SPICE migration has completed
12854 Since
12856 1.3
12857 Example
12859 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
12860 "event": "SPICE_MIGRATE_COMPLETED" }
12861 If
12863 CONFIG_SPICE
12864 VNC
12866 VncBasicInfo (Object)
12867 The basic information for vnc network connection
12868 Members
12870 host: string
12871 IP address
12872 service: string
12874 The service name of the vnc port. This may depend on the host
12875 system's service database so symbolic names should not be relied
12876 on.
12877 family: NetworkAddressFamily
12879 address family
12880 websocket: boolean
12882 true in case the socket is a websocket (since 2.3).
12883 Since
12885 2.1
12886 If
12888 CONFIG_VNC
12889 VncServerInfo (Object)
12891 The network connection information for server
12892 Members
12894 auth: string (optional)
12895 authentication method used for the plain (non-websocket) VNC
12896 server
12897 The members of VncBasicInfo
12899 Since
12901 2.1
12902 If
12904 CONFIG_VNC
12905 VncClientInfo (Object)
12907 Information about a connected VNC client.
12908 Members
12910 x509_dname: string (optional)
12911 If x509 authentication is in use, the Distinguished Name of the
12912 client.
12913 sasl_username: string (optional)
12915 If SASL authentication is in use, the SASL username used for au‐
12916 thentication.
12917 The members of VncBasicInfo
12919 Since
12921 0.14
12922 If
12924 CONFIG_VNC
12925 VncInfo (Object)
12927 Information about the VNC session.
12928 Members
12930 enabled: boolean
12931 true if the VNC server is enabled, false otherwise
12932 host: string (optional)
12934 The hostname the VNC server is bound to. This depends on the
12935 name resolution on the host and may be an IP address.
12936 family: NetworkAddressFamily (optional)
12938 • 'ipv6' if the host is listening for IPv6 connections
12940 • 'ipv4' if the host is listening for IPv4 connections
12942 • 'unix' if the host is listening on a unix domain socket
12944 • 'unknown' otherwise
12946 service: string (optional)
12948 The service name of the server's port. This may depends on the
12949 host system's service database so symbolic names should not be
12950 relied on.
12951 auth: string (optional)
12953 the current authentication type used by the server
12954 • 'none' if no authentication is being used
12956 • 'vnc' if VNC authentication is being used
12958 • 'vencrypt+plain' if VEncrypt is used with plain text authenti‐
12960 cation
12961 • 'vencrypt+tls+none' if VEncrypt is used with TLS and no au‐
12963 thentication
12964 • 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC au‐
12966 thentication
12967 • 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain
12969 text auth
12970 • 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
12972 • 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
12974 • 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain
12976 text auth
12977 • 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
12979 • 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
12981 auth
12982 clients: array of VncClientInfo (optional)
12984 a list of VncClientInfo of all currently connected clients
12985 Since
12987 0.14
12988 If
12990 CONFIG_VNC
12991 VncPrimaryAuth (Enum)
12993 vnc primary authentication method.
12994 Values
12996 none Not documented
12997 vnc Not documented
12999 ra2 Not documented
13001 ra2ne Not documented
13003 tight Not documented
13005 ultra Not documented
13007 tls Not documented
13009 vencrypt
13011 Not documented
13012 sasl Not documented
13014 Since
13016 2.3
13017 If
13019 CONFIG_VNC
13020 VncVencryptSubAuth (Enum)
13022 vnc sub authentication method with vencrypt.
13023 Values
13025 plain Not documented
13026 tls-none
13028 Not documented
13029 x509-none
13031 Not documented
13032 tls-vnc
13034 Not documented
13035 x509-vnc
13037 Not documented
13038 tls-plain
13040 Not documented
13041 x509-plain
13043 Not documented
13044 tls-sasl
13046 Not documented
13047 x509-sasl
13049 Not documented
13050 Since
13052 2.3
13053 If
13055 CONFIG_VNC
13056 VncServerInfo2 (Object)
13058 The network connection information for server
13059 Members
13061 auth: VncPrimaryAuth
13062 The current authentication type used by the servers
13063 vencrypt: VncVencryptSubAuth (optional)
13065 The vencrypt sub authentication type used by the servers, only
13066 specified in case auth == vencrypt.
13067 The members of VncBasicInfo
13069 Since
13071 2.9
13072 If
13074 CONFIG_VNC
13075 VncInfo2 (Object)
13077 Information about a vnc server
13078 Members
13080 id: string
13081 vnc server name.
13082 server: array of VncServerInfo2
13084 A list of VncBasincInfo describing all listening sockets. The
13085 list can be empty (in case the vnc server is disabled). It also
13086 may have multiple entries: normal + websocket, possibly also
13087 ipv4 + ipv6 in the future.
13088 clients: array of VncClientInfo
13090 A list of VncClientInfo of all currently connected clients. The
13091 list can be empty, for obvious reasons.
13092 auth: VncPrimaryAuth
13094 The current authentication type used by the non-websockets
13095 servers
13096 vencrypt: VncVencryptSubAuth (optional)
13098 The vencrypt authentication type used by the servers, only spec‐
13099 ified in case auth == vencrypt.
13100 display: string (optional)
13102 The display device the vnc server is linked to.
13103 Since
13105 2.3
13106 If
13108 CONFIG_VNC
13109 query-vnc (Command)
13111 Returns information about the current VNC server
13112 Returns
13114 VncInfo
13115 Since
13117 0.14
13118 Example
13120 -> { "execute": "query-vnc" }
13121 <- { "return": {
13122 "enabled":true,
13123 "host":"0.0.0.0",
13124 "service":"50402",
13125 "auth":"vnc",
13126 "family":"ipv4",
13127 "clients":[
13128 {
13129 "host":"127.0.0.1",
13130 "service":"50401",
13131 "family":"ipv4",
13132 "websocket":false
13133 }
13134 ]
13135 }
13136 }
13137 If
13139 CONFIG_VNC
13140 query-vnc-servers (Command)
13142 Returns a list of vnc servers. The list can be empty.
13143 Returns
13145 a list of VncInfo2
13146 Since
13148 2.3
13149 If
13151 CONFIG_VNC
13152 change-vnc-password (Command)
13154 Change the VNC server password.
13155 Arguments
13157 password: string
13158 the new password to use with VNC authentication
13159 Since
13161 1.1
13162 Notes
13164 An empty password in this command will set the password to the empty
13165 string. Existing clients are unaffected by executing this command.
13166 If
13168 CONFIG_VNC
13169 VNC_CONNECTED (Event)
13171 Emitted when a VNC client establishes a connection
13172 Arguments
13174 server: VncServerInfo
13175 server information
13176 client: VncBasicInfo
13178 client information
13179 Note
13181 This event is emitted before any authentication takes place, thus the
13182 authentication ID is not provided
13183 Since
13185 0.13
13186 Example
13188 <- { "event": "VNC_CONNECTED",
13189 "data": {
13190 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
13191 "service": "5901", "host": "0.0.0.0" },
13192 "client": { "family": "ipv4", "service": "58425",
13193 "host": "127.0.0.1", "websocket": false } },
13194 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
13195 If
13197 CONFIG_VNC
13198 VNC_INITIALIZED (Event)
13200 Emitted after authentication takes place (if any) and the VNC session
13201 is made active
13202 Arguments
13204 server: VncServerInfo
13205 server information
13206 client: VncClientInfo
13208 client information
13209 Since
13211 0.13
13212 Example
13214 <- { "event": "VNC_INITIALIZED",
13215 "data": {
13216 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
13217 "service": "5901", "host": "0.0.0.0"},
13218 "client": { "family": "ipv4", "service": "46089", "websocket": false,
13219 "host": "127.0.0.1", "sasl_username": "luiz" } },
13220 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
13221 If
13223 CONFIG_VNC
13224 VNC_DISCONNECTED (Event)
13226 Emitted when the connection is closed
13227 Arguments
13229 server: VncServerInfo
13230 server information
13231 client: VncClientInfo
13233 client information
13234 Since
13236 0.13
13237 Example
13239 <- { "event": "VNC_DISCONNECTED",
13240 "data": {
13241 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
13242 "service": "5901", "host": "0.0.0.0" },
13243 "client": { "family": "ipv4", "service": "58425", "websocket": false,
13244 "host": "127.0.0.1", "sasl_username": "luiz" } },
13245 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
13246 If
13248 CONFIG_VNC
13249
13251 MouseInfo (Object)
13252 Information about a mouse device.
13253 Members
13255 name: string
13256 the name of the mouse device
13257 index: int
13259 the index of the mouse device
13260 current: boolean
13262 true if this device is currently receiving mouse events
13263 absolute: boolean
13265 true if this device supports absolute coordinates as input
13266 Since
13268 0.14
13269 query-mice (Command)
13271 Returns information about each active mouse device
13272 Returns
13274 a list of MouseInfo for each device
13275 Since
13277 0.14
13278 Example
13280 -> { "execute": "query-mice" }
13281 <- { "return": [
13282 {
13283 "name":"QEMU Microsoft Mouse",
13284 "index":0,
13285 "current":false,
13286 "absolute":false
13287 },
13288 {
13289 "name":"QEMU PS/2 Mouse",
13290 "index":1,
13291 "current":true,
13292 "absolute":true
13293 }
13294 ]
13295 }
13296 QKeyCode (Enum)
13298 An enumeration of key name.
13299 This is used by the send-key command.
13301 Values
13303 unmapped
13304 since 2.0
13305 pause since 2.0
13307 ro since 2.4
13309 kp_comma
13311 since 2.4
13312 kp_equals
13314 since 2.6
13315 power since 2.6
13317 hiragana
13319 since 2.9
13320 henkan since 2.9
13322 yen since 2.9
13324 sleep since 2.10
13326 wake since 2.10
13328 audionext
13330 since 2.10
13331 audioprev
13333 since 2.10
13334 audiostop
13336 since 2.10
13337 audioplay
13339 since 2.10
13340 audiomute
13342 since 2.10
13343 volumeup
13345 since 2.10
13346 volumedown
13348 since 2.10
13349 mediaselect
13351 since 2.10
13352 mail since 2.10
13354 calculator
13356 since 2.10
13357 computer
13359 since 2.10
13360 ac_home
13362 since 2.10
13363 ac_back
13365 since 2.10
13366 ac_forward
13368 since 2.10
13369 ac_refresh
13371 since 2.10
13372 ac_bookmarks
13374 since 2.10
13375 muhenkan
13377 since 2.12
13378 katakanahiragana
13380 since 2.12
13381 lang1 since 6.1
13383 lang2 since 6.1
13385 shift Not documented
13387 shift_r
13389 Not documented
13390 alt Not documented
13392 alt_r Not documented
13394 ctrl Not documented
13396 ctrl_r Not documented
13398 menu Not documented
13400 esc Not documented
13402 1 Not documented
13404 2 Not documented
13406 3 Not documented
13408 4 Not documented
13410 5 Not documented
13412 6 Not documented
13414 7 Not documented
13416 8 Not documented
13418 9 Not documented
13420 0 Not documented
13422 minus Not documented
13424 equal Not documented
13426 backspace
13428 Not documented
13429 tab Not documented
13431 q Not documented
13433 w Not documented
13435 e Not documented
13437 r Not documented
13439 t Not documented
13441 y Not documented
13443 u Not documented
13445 i Not documented
13447 o Not documented
13449 p Not documented
13451 bracket_left
13453 Not documented
13454 bracket_right
13456 Not documented
13457 ret Not documented
13459 a Not documented
13461 s Not documented
13463 d Not documented
13465 f Not documented
13467 g Not documented
13469 h Not documented
13471 j Not documented
13473 k Not documented
13475 l Not documented
13477 semicolon
13479 Not documented
13480 apostrophe
13482 Not documented
13483 grave_accent
13485 Not documented
13486 backslash
13488 Not documented
13489 z Not documented
13491 x Not documented
13493 c Not documented
13495 v Not documented
13497 b Not documented
13499 n Not documented
13501 m Not documented
13503 comma Not documented
13505 dot Not documented
13507 slash Not documented
13509 asterisk
13511 Not documented
13512 spc Not documented
13514 caps_lock
13516 Not documented
13517 f1 Not documented
13519 f2 Not documented
13521 f3 Not documented
13523 f4 Not documented
13525 f5 Not documented
13527 f6 Not documented
13529 f7 Not documented
13531 f8 Not documented
13533 f9 Not documented
13535 f10 Not documented
13537 num_lock
13539 Not documented
13540 scroll_lock
13542 Not documented
13543 kp_divide
13545 Not documented
13546 kp_multiply
13548 Not documented
13549 kp_subtract
13551 Not documented
13552 kp_add Not documented
13554 kp_enter
13556 Not documented
13557 kp_decimal
13559 Not documented
13560 sysrq Not documented
13562 kp_0 Not documented
13564 kp_1 Not documented
13566 kp_2 Not documented
13568 kp_3 Not documented
13570 kp_4 Not documented
13572 kp_5 Not documented
13574 kp_6 Not documented
13576 kp_7 Not documented
13578 kp_8 Not documented
13580 kp_9 Not documented
13582 less Not documented
13584 f11 Not documented
13586 f12 Not documented
13588 print Not documented
13590 home Not documented
13592 pgup Not documented
13594 pgdn Not documented
13596 end Not documented
13598 left Not documented
13600 up Not documented
13602 down Not documented
13604 right Not documented
13606 insert Not documented
13608 delete Not documented
13610 stop Not documented
13612 again Not documented
13614 props Not documented
13616 undo Not documented
13618 front Not documented
13620 copy Not documented
13622 open Not documented
13624 paste Not documented
13626 find Not documented
13628 cut Not documented
13630 lf Not documented
13632 help Not documented
13634 meta_l Not documented
13636 meta_r Not documented
13638 compose
13640 Not documented
13641 'sysrq' was mistakenly added to hack around the fact that the ps2
13642 driver was not generating correct scancodes sequences when 'alt+print'
13643 was pressed. This flaw is now fixed and the 'sysrq' key serves no fur‐
13644 ther purpose. Any further use of 'sysrq' will be transparently changed
13645 to 'print', so they are effectively synonyms.
13646 Since
13648 1.3
13649 KeyValueKind (Enum)
13651 Values
13652 number Not documented
13653 qcode Not documented
13655 Since
13657 1.3
13658 IntWrapper (Object)
13660 Members
13661 data: int
13662 Not documented
13663 Since
13665 1.3
13666 QKeyCodeWrapper (Object)
13668 Members
13669 data: QKeyCode
13670 Not documented
13671 Since
13673 1.3
13674 KeyValue (Object)
13676 Represents a keyboard key.
13677 Members
13679 type: KeyValueKind
13680 Not documented
13681 The members of IntWrapper when type is "number"
13683 The members of QKeyCodeWrapper when type is "qcode"
13685 Since
13687 1.3
13688 send-key (Command)
13690 Send keys to guest.
13691 Arguments
13693 keys: array of KeyValue
13694 An array of KeyValue elements. All KeyValues in this array are
13695 simultaneously sent to the guest. A KeyValue.number value is
13696 sent directly to the guest, while KeyValue.qcode must be a valid
13697 QKeyCode value
13698 hold-time: int (optional)
13700 time to delay key up events, milliseconds. Defaults to 100
13701 Returns
13703 • Nothing on success
13704 • If key is unknown or redundant, InvalidParameter
13706 Since
13708 1.3
13709 Example
13711 -> { "execute": "send-key",
13712 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
13713 { "type": "qcode", "data": "alt" },
13714 { "type": "qcode", "data": "delete" } ] } }
13715 <- { "return": {} }
13716 InputButton (Enum)
13718 Button of a pointer input device (mouse, tablet).
13719 Values
13721 side front side button of a 5-button mouse (since 2.9)
13722 extra rear side button of a 5-button mouse (since 2.9)
13724 left Not documented
13726 middle Not documented
13728 right Not documented
13730 wheel-up
13732 Not documented
13733 wheel-down
13735 Not documented
13736 wheel-left
13738 Not documented
13739 wheel-right
13741 Not documented
13742 Since
13744 2.0
13745 InputAxis (Enum)
13747 Position axis of a pointer input device (mouse, tablet).
13748 Values
13750 x Not documented
13751 y Not documented
13753 Since
13755 2.0
13756 InputKeyEvent (Object)
13758 Keyboard input event.
13759 Members
13761 key: KeyValue
13762 Which key this event is for.
13763 down: boolean
13765 True for key-down and false for key-up events.
13766 Since
13768 2.0
13769 InputBtnEvent (Object)
13771 Pointer button input event.
13772 Members
13774 button: InputButton
13775 Which button this event is for.
13776 down: boolean
13778 True for key-down and false for key-up events.
13779 Since
13781 2.0
13782 InputMoveEvent (Object)
13784 Pointer motion input event.
13785 Members
13787 axis: InputAxis
13788 Which axis is referenced by value.
13789 value: int
13791 Pointer position. For absolute coordinates the valid range is 0
13792 -> 0x7ffff
13793 Since
13795 2.0
13796 InputEventKind (Enum)
13798 Values
13799 key Not documented
13800 btn Not documented
13802 rel Not documented
13804 abs Not documented
13806 Since
13808 2.0
13809 InputKeyEventWrapper (Object)
13811 Members
13812 data: InputKeyEvent
13813 Not documented
13814 Since
13816 2.0
13817 InputBtnEventWrapper (Object)
13819 Members
13820 data: InputBtnEvent
13821 Not documented
13822 Since
13824 2.0
13825 InputMoveEventWrapper (Object)
13827 Members
13828 data: InputMoveEvent
13829 Not documented
13830 Since
13832 2.0
13833 InputEvent (Object)
13835 Input event union.
13836 Members
13838 type: InputEventKind
13839 the input type, one of:
13840 • 'key': Input event of Keyboard
13842 • 'btn': Input event of pointer buttons
13844 • 'rel': Input event of relative pointer motion
13846 • 'abs': Input event of absolute pointer motion
13848 The members of InputKeyEventWrapper when type is "key"
13850 The members of InputBtnEventWrapper when type is "btn"
13852 The members of InputMoveEventWrapper when type is "rel"
13854 The members of InputMoveEventWrapper when type is "abs"
13856 Since
13858 2.0
13859 input-send-event (Command)
13861 Send input event(s) to guest.
13862 The device and head parameters can be used to send the input event to
13864 specific input devices in case (a) multiple input devices of the same
13865 kind are added to the virtual machine and (b) you have configured input
13866 routing (see docs/multiseat.txt) for those input devices. The parame‐
13867 ters work exactly like the device and head properties of input devices.
13868 If device is missing, only devices that have no input routing config
13869 are admissible. If device is specified, both input devices with and
13870 without input routing config are admissible, but devices with input
13871 routing config take precedence.
13872 Arguments
13874 device: string (optional)
13875 display device to send event(s) to.
13876 head: int (optional)
13878 head to send event(s) to, in case the display device supports
13879 multiple scanouts.
13880 events: array of InputEvent
13882 List of InputEvent union.
13883 Returns
13885 Nothing on success.
13886 Since
13888 2.6
13889 Note
13891 The consoles are visible in the qom tree, under /backend/console[$in‐
13892 dex]. They have a device link and head property, so it is possible to
13893 map which console belongs to which device and display.
13894 Example
13896 1. Press left mouse button.
13897 -> { "execute": "input-send-event",
13899 "arguments": { "device": "video0",
13900 "events": [ { "type": "btn",
13901 "data" : { "down": true, "button": "left" } } ] } }
13902 <- { "return": {} }
13903 -> { "execute": "input-send-event",
13905 "arguments": { "device": "video0",
13906 "events": [ { "type": "btn",
13907 "data" : { "down": false, "button": "left" } } ] } }
13908 <- { "return": {} }
13909 2. Press ctrl-alt-del.
13911 -> { "execute": "input-send-event",
13913 "arguments": { "events": [
13914 { "type": "key", "data" : { "down": true,
13915 "key": {"type": "qcode", "data": "ctrl" } } },
13916 { "type": "key", "data" : { "down": true,
13917 "key": {"type": "qcode", "data": "alt" } } },
13918 { "type": "key", "data" : { "down": true,
13919 "key": {"type": "qcode", "data": "delete" } } } ] } }
13920 <- { "return": {} }
13921 3. Move mouse pointer to absolute coordinates (20000, 400).
13923 -> { "execute": "input-send-event" ,
13925 "arguments": { "events": [
13926 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
13927 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
13928 <- { "return": {} }
13929 DisplayGTK (Object)
13931 GTK display options.
13932 Members
13934 grab-on-hover: boolean (optional)
13935 Grab keyboard input on mouse hover.
13936 zoom-to-fit: boolean (optional)
13938 Zoom guest display to fit into the host window. When turned off
13939 the host window will be resized instead. In case the display
13940 device can notify the guest on window resizes (virtio-gpu) this
13941 will default to "on", assuming the guest will resize the display
13942 to match the window size then. Otherwise it defaults to "off".
13943 Since 3.1
13944 show-tabs: boolean (optional)
13946 Display the tab bar for switching between the various graphical
13947 interfaces (e.g. VGA and virtual console character devices) by
13948 default. Since 7.1
13949 show-menubar: boolean (optional)
13951 Display the main window menubar. Defaults to "on". Since 8.0
13952 Since
13954 2.12
13955 DisplayEGLHeadless (Object)
13957 EGL headless display options.
13958 Members
13960 rendernode: string (optional)
13961 Which DRM render node should be used. Default is the first
13962 available node on the host.
13963 Since
13965 3.1
13966 DisplayDBus (Object)
13968 DBus display options.
13969 Members
13971 addr: string (optional)
13972 The D-Bus bus address (default to the session bus).
13973 rendernode: string (optional)
13975 Which DRM render node should be used. Default is the first
13976 available node on the host.
13977 p2p: boolean (optional)
13979 Whether to use peer-to-peer connections (accepted through
13980 add_client).
13981 audiodev: string (optional)
13983 Use the specified DBus audiodev to export audio.
13984 Since
13986 7.0
13987 DisplayGLMode (Enum)
13989 Display OpenGL mode.
13990 Values
13992 off Disable OpenGL (default).
13993 on Use OpenGL, pick context type automatically. Would better be
13995 named 'auto' but is called 'on' for backward compatibility with
13996 bool type.
13997 core Use OpenGL with Core (desktop) Context.
13999 es Use OpenGL with ES (embedded systems) Context.
14001 Since
14003 3.0
14004 DisplayCurses (Object)
14006 Curses display options.
14007 Members
14009 charset: string (optional)
14010 Font charset used by guest (default: CP437).
14011 Since
14013 4.0
14014 DisplayCocoa (Object)
14016 Cocoa display options.
14017 Members
14019 left-command-key: boolean (optional)
14020 Enable/disable forwarding of left command key to guest. Allows
14021 command-tab window switching on the host without sending this
14022 key to the guest when "off". Defaults to "on"
14023 full-grab: boolean (optional)
14025 Capture all key presses, including system combos. This requires
14026 accessibility permissions, since it performs a global grab on
14027 key events. (default: off) See
14028 https://support.apple.com/en-in/guide/mac-help/mh32356/mac
14029 swap-opt-cmd: boolean (optional)
14031 Swap the Option and Command keys so that their key codes match
14032 their position on non-Mac keyboards and you can use Meta/Super
14033 and Alt where you expect them. (default: off)
14034 Since
14036 7.0
14037 HotKeyMod (Enum)
14039 Set of modifier keys that need to be held for shortcut key actions.
14040 Values
14042 lctrl-lalt
14043 Not documented
14044 lshift-lctrl-lalt
14046 Not documented
14047 rctrl Not documented
14049 Since
14051 7.1
14052 DisplaySDL (Object)
14054 SDL2 display options.
14055 Members
14057 grab-mod: HotKeyMod (optional)
14058 Modifier keys that should be pressed together with the "G" key
14059 to release the mouse grab.
14060 Since
14062 7.1
14063 DisplayType (Enum)
14065 Display (user interface) type.
14066 Values
14068 default
14069 The default user interface, selecting from the first available
14070 of gtk, sdl, cocoa, and vnc.
14071 none No user interface or video output display. The guest will still
14073 see an emulated graphics card, but its output will not be dis‐
14074 played to the QEMU user.
14075 gtk (If: CONFIG_GTK)
14077 The GTK user interface.
14078 sdl (If: CONFIG_SDL)
14080 The SDL user interface.
14081 egl-headless (If: CONFIG_OPENGL and CONFIG_GBM)
14083 No user interface, offload GL operations to a local DRI device.
14084 Graphical display need to be paired with VNC or Spice. (Since
14085 3.1)
14086 curses (If: CONFIG_CURSES)
14088 Display video output via curses. For graphics device models
14089 which support a text mode, QEMU can display this output using a
14090 curses/ncurses interface. Nothing is displayed when the graphics
14091 device is in graphical mode or if the graphics device does not
14092 support a text mode. Generally only the VGA device models sup‐
14093 port text mode.
14094 cocoa (If: CONFIG_COCOA)
14096 The Cocoa user interface.
14097 spice-app (If: CONFIG_SPICE)
14099 Set up a Spice server and run the default associated application
14100 to connect to it. The server will redirect the serial console
14101 and QEMU monitors. (Since 4.0)
14102 dbus (If: CONFIG_DBUS_DISPLAY)
14104 Start a D-Bus service for the display. (Since 7.0)
14105 Since
14107 2.12
14108 DisplayOptions (Object)
14110 Display (user interface) options.
14111 Members
14113 type: DisplayType
14114 Which DisplayType qemu should use.
14115 full-screen: boolean (optional)
14117 Start user interface in fullscreen mode (default: off).
14118 window-close: boolean (optional)
14120 Allow to quit qemu with window close button (default: on).
14121 show-cursor: boolean (optional)
14123 Force showing the mouse cursor (default: off). (since: 5.0)
14124 gl: DisplayGLMode (optional)
14126 Enable OpenGL support (default: off).
14127 The members of DisplayGTK when type is "gtk" (If: CONFIG_GTK)
14129 The members of DisplayCocoa when type is "cocoa" (If: CONFIG_COCOA)
14131 The members of DisplayCurses when type is "curses" (If: CONFIG_CURSES)
14133 The members of DisplayEGLHeadless when type is "egl-headless" (If: CON‐
14135 FIG_OPENGL and CONFIG_GBM)
14136 The members of DisplayDBus when type is "dbus" (If: CONFIG_DBUS_DIS‐
14138 PLAY)
14139 The members of DisplaySDL when type is "sdl" (If: CONFIG_SDL)
14141 Since
14143 2.12
14144 query-display-options (Command)
14146 Returns information about display configuration
14147 Returns
14149 DisplayOptions
14150 Since
14152 3.1
14153 DisplayReloadType (Enum)
14155 Available DisplayReload types.
14156 Values
14158 vnc VNC display
14159 Since
14161 6.0
14162 DisplayReloadOptionsVNC (Object)
14164 Specify the VNC reload options.
14165 Members
14167 tls-certs: boolean (optional)
14168 reload tls certs or not.
14169 Since
14171 6.0
14172 DisplayReloadOptions (Object)
14174 Options of the display configuration reload.
14175 Members
14177 type: DisplayReloadType
14178 Specify the display type.
14179 The members of DisplayReloadOptionsVNC when type is "vnc"
14181 Since
14183 6.0
14184 display-reload (Command)
14186 Reload display configuration.
14187 Arguments
14189 The members of DisplayReloadOptions
14190 Returns
14192 Nothing on success.
14193 Since
14195 6.0
14196 Example
14198 -> { "execute": "display-reload",
14199 "arguments": { "type": "vnc", "tls-certs": true } }
14200 <- { "return": {} }
14201 DisplayUpdateType (Enum)
14203 Available DisplayUpdate types.
14204 Values
14206 vnc VNC display
14207 Since
14209 7.1
14210 DisplayUpdateOptionsVNC (Object)
14212 Specify the VNC reload options.
14213 Members
14215 addresses: array of SocketAddress (optional)
14216 If specified, change set of addresses to listen for connections.
14217 Addresses configured for websockets are not touched.
14218 Since
14220 7.1
14221 DisplayUpdateOptions (Object)
14223 Options of the display configuration reload.
14224 Members
14226 type: DisplayUpdateType
14227 Specify the display type.
14228 The members of DisplayUpdateOptionsVNC when type is "vnc"
14230 Since
14232 7.1
14233 display-update (Command)
14235 Update display configuration.
14236 Arguments
14238 The members of DisplayUpdateOptions
14239 Returns
14241 Nothing on success.
14242 Since
14244 7.1
14245 Example
14247 -> { "execute": "display-update",
14248 "arguments": { "type": "vnc", "addresses":
14249 [ { "type": "inet", "host": "0.0.0.0",
14250 "port": "5901" } ] } }
14251 <- { "return": {} }
14252
14254 QAuthZListPolicy (Enum)
14255 The authorization policy result
14256 Values
14258 deny deny access
14259 allow allow access
14261 Since
14263 4.0
14264 QAuthZListFormat (Enum)
14266 The authorization policy match format
14267 Values
14269 exact an exact string match
14270 glob string with ? and * shell wildcard support
14272 Since
14274 4.0
14275 QAuthZListRule (Object)
14277 A single authorization rule.
14278 Members
14280 match: string
14281 a string or glob to match against a user identity
14282 policy: QAuthZListPolicy
14284 the result to return if match evaluates to true
14285 format: QAuthZListFormat (optional)
14287 the format of the match rule (default 'exact')
14288 Since
14290 4.0
14291 AuthZListProperties (Object)
14293 Properties for authz-list objects.
14294 Members
14296 policy: QAuthZListPolicy (optional)
14297 Default policy to apply when no rule matches (default: deny)
14298 rules: array of QAuthZListRule (optional)
14300 Authorization rules based on matching user
14301 Since
14303 4.0
14304 AuthZListFileProperties (Object)
14306 Properties for authz-listfile objects.
14307 Members
14309 filename: string
14310 File name to load the configuration from. The file must contain
14311 valid JSON for AuthZListProperties.
14312 refresh: boolean (optional)
14314 If true, inotify is used to monitor the file, automatically
14315 reloading changes. If an error occurs during reloading, all au‐
14316 thorizations will fail until the file is next successfully
14317 loaded. (default: true if the binary was built with CONFIG_INO‐
14318 TIFY1, false otherwise)
14319 Since
14321 4.0
14322 AuthZPAMProperties (Object)
14324 Properties for authz-pam objects.
14325 Members
14327 service: string
14328 PAM service name to use for authorization
14329 Since
14331 4.0
14332 AuthZSimpleProperties (Object)
14334 Properties for authz-simple objects.
14335 Members
14337 identity: string
14338 Identifies the allowed user. Its format depends on the network
14339 service that authorization object is associated with. For autho‐
14340 rizing based on TLS x509 certificates, the identity must be the
14341 x509 distinguished name.
14342 Since
14344 4.0
14345
14347 MigrationStats (Object)
14348 Detailed migration status.
14349 Members
14351 transferred: int
14352 amount of bytes already transferred to the target VM
14353 remaining: int
14355 amount of bytes remaining to be transferred to the target VM
14356 total: int
14358 total amount of bytes involved in the migration process
14359 duplicate: int
14361 number of duplicate (zero) pages (since 1.2)
14362 skipped: int
14364 number of skipped zero pages (since 1.5)
14365 normal: int
14367 number of normal pages (since 1.2)
14368 normal-bytes: int
14370 number of normal bytes sent (since 1.2)
14371 dirty-pages-rate: int
14373 number of pages dirtied by second by the guest (since 1.3)
14374 mbps: number
14376 throughput in megabits/sec. (since 1.6)
14377 dirty-sync-count: int
14379 number of times that dirty ram was synchronized (since 2.1)
14380 postcopy-requests: int
14382 The number of page requests received from the destination (since
14383 2.7)
14384 page-size: int
14386 The number of bytes per page for the various page-based statis‐
14387 tics (since 2.10)
14388 multifd-bytes: int
14390 The number of bytes sent through multifd (since 3.0)
14391 pages-per-second: int
14393 the number of memory pages transferred per second (Since 4.0)
14394 precopy-bytes: int
14396 The number of bytes sent in the pre-copy phase (since 7.0).
14397 downtime-bytes: int
14399 The number of bytes sent while the guest is paused (since 7.0).
14400 postcopy-bytes: int
14402 The number of bytes sent during the post-copy phase (since 7.0).
14403 dirty-sync-missed-zero-copy: int
14405 Number of times dirty RAM synchronization could not avoid copy‐
14406 ing dirty pages. This is between 0 and dirty-sync-count * mul‐
14407 tifd-channels. (since 7.1)
14408 Since
14410 0.14
14411 XBZRLECacheStats (Object)
14413 Detailed XBZRLE migration cache statistics
14414 Members
14416 cache-size: int
14417 XBZRLE cache size
14418 bytes: int
14420 amount of bytes already transferred to the target VM
14421 pages: int
14423 amount of pages transferred to the target VM
14424 cache-miss: int
14426 number of cache miss
14427 cache-miss-rate: number
14429 rate of cache miss (since 2.1)
14430 encoding-rate: number
14432 rate of encoded bytes (since 5.1)
14433 overflow: int
14435 number of overflows
14436 Since
14438 1.2
14439 CompressionStats (Object)
14441 Detailed migration compression statistics
14442 Members
14444 pages: int
14445 amount of pages compressed and transferred to the target VM
14446 busy: int
14448 count of times that no free thread was available to compress
14449 data
14450 busy-rate: number
14452 rate of thread busy
14453 compressed-size: int
14455 amount of bytes after compression
14456 compression-rate: number
14458 rate of compressed size
14459 Since
14461 3.1
14462 MigrationStatus (Enum)
14464 An enumeration of migration status.
14465 Values
14467 none no migration has ever happened.
14468 setup migration process has been initiated.
14470 cancelling
14472 in the process of cancelling migration.
14473 cancelled
14475 cancelling migration is finished.
14476 active in the process of doing migration.
14478 postcopy-active
14480 like active, but now in postcopy mode. (since 2.5)
14481 postcopy-paused
14483 during postcopy but paused. (since 3.0)
14484 postcopy-recover
14486 trying to recover from a paused postcopy. (since 3.0)
14487 completed
14489 migration is finished.
14490 failed some error occurred during migration process.
14492 colo VM is in the process of fault tolerance, VM can not get into
14494 this state unless colo capability is enabled for migration.
14495 (since 2.8)
14496 pre-switchover
14498 Paused before device serialisation. (since 2.11)
14499 device During device serialisation when pause-before-switchover is en‐
14501 abled (since 2.11)
14502 wait-unplug
14504 wait for device unplug request by guest OS to be completed.
14505 (since 4.2)
14506 Since
14508 2.3
14509 VfioStats (Object)
14511 Detailed VFIO devices migration statistics
14512 Members
14514 transferred: int
14515 amount of bytes transferred to the target VM by VFIO devices
14516 Since
14518 5.2
14519 MigrationInfo (Object)
14521 Information about current migration process.
14522 Members
14524 status: MigrationStatus (optional)
14525 MigrationStatus describing the current migration status. If
14526 this field is not returned, no migration process has been initi‐
14527 ated
14528 ram: MigrationStats (optional)
14530 MigrationStats containing detailed migration status, only re‐
14531 turned if status is 'active' or 'completed'(since 1.2)
14532 disk: MigrationStats (optional)
14534 MigrationStats containing detailed disk migration status, only
14535 returned if status is 'active' and it is a block migration
14536 xbzrle-cache: XBZRLECacheStats (optional)
14538 XBZRLECacheStats containing detailed XBZRLE migration statis‐
14539 tics, only returned if XBZRLE feature is on and status is 'ac‐
14540 tive' or 'completed' (since 1.2)
14541 total-time: int (optional)
14543 total amount of milliseconds since migration started. If migra‐
14544 tion has ended, it returns the total migration time. (since 1.2)
14545 downtime: int (optional)
14547 only present when migration finishes correctly total downtime in
14548 milliseconds for the guest. (since 1.3)
14549 expected-downtime: int (optional)
14551 only present while migration is active expected downtime in mil‐
14552 liseconds for the guest in last walk of the dirty bitmap. (since
14553 1.3)
14554 setup-time: int (optional)
14556 amount of setup time in milliseconds before the iterations begin
14557 but after the QMP command is issued. This is designed to provide
14558 an accounting of any activities (such as RDMA pinning) which may
14559 be expensive, but do not actually occur during the iterative mi‐
14560 gration rounds themselves. (since 1.6)
14561 cpu-throttle-percentage: int (optional)
14563 percentage of time guest cpus are being throttled during
14564 auto-converge. This is only present when auto-converge has
14565 started throttling guest cpus. (Since 2.7)
14566 error-desc: string (optional)
14568 the human readable error description string, when status is
14569 'failed'. Clients should not attempt to parse the error strings.
14570 (Since 2.7)
14571 postcopy-blocktime: int (optional)
14573 total time when all vCPU were blocked during postcopy live mi‐
14574 gration. This is only present when the postcopy-blocktime migra‐
14575 tion capability is enabled. (Since 3.0)
14576 postcopy-vcpu-blocktime: array of int (optional)
14578 list of the postcopy blocktime per vCPU. This is only present
14579 when the postcopy-blocktime migration capability is enabled.
14580 (Since 3.0)
14581 compression: CompressionStats (optional)
14583 migration compression statistics, only returned if compression
14584 feature is on and status is 'active' or 'completed' (Since 3.1)
14585 socket-address: array of SocketAddress (optional)
14587 Only used for tcp, to know what the real port is (Since 4.0)
14588 vfio: VfioStats (optional)
14590 VfioStats containing detailed VFIO devices migration statistics,
14591 only returned if VFIO device is present, migration is supported
14592 by all VFIO devices and status is 'active' or 'completed' (since
14593 5.2)
14594 blocked-reasons: array of string (optional)
14596 A list of reasons an outgoing migration is blocked. Present and
14597 non-empty when migration is blocked. (since 6.0)
14598 Since
14600 0.14
14601 query-migrate (Command)
14603 Returns information about current migration process. If migration is
14604 active there will be another json-object with RAM migration status and
14605 if block migration is active another one with block migration status.
14606 Returns
14608 MigrationInfo
14609 Since
14611 0.14
14612 Example
14614 1. Before the first migration
14615 -> { "execute": "query-migrate" }
14617 <- { "return": {} }
14618 2. Migration is done and has succeeded
14620 -> { "execute": "query-migrate" }
14622 <- { "return": {
14623 "status": "completed",
14624 "total-time":12345,
14625 "setup-time":12345,
14626 "downtime":12345,
14627 "ram":{
14628 "transferred":123,
14629 "remaining":123,
14630 "total":246,
14631 "duplicate":123,
14632 "normal":123,
14633 "normal-bytes":123456,
14634 "dirty-sync-count":15
14635 }
14636 }
14637 }
14638 3. Migration is done and has failed
14640 -> { "execute": "query-migrate" }
14642 <- { "return": { "status": "failed" } }
14643 4. Migration is being performed and is not a block migration:
14645 -> { "execute": "query-migrate" }
14647 <- {
14648 "return":{
14649 "status":"active",
14650 "total-time":12345,
14651 "setup-time":12345,
14652 "expected-downtime":12345,
14653 "ram":{
14654 "transferred":123,
14655 "remaining":123,
14656 "total":246,
14657 "duplicate":123,
14658 "normal":123,
14659 "normal-bytes":123456,
14660 "dirty-sync-count":15
14661 }
14662 }
14663 }
14664 5. Migration is being performed and is a block migration:
14666 -> { "execute": "query-migrate" }
14668 <- {
14669 "return":{
14670 "status":"active",
14671 "total-time":12345,
14672 "setup-time":12345,
14673 "expected-downtime":12345,
14674 "ram":{
14675 "total":1057024,
14676 "remaining":1053304,
14677 "transferred":3720,
14678 "duplicate":123,
14679 "normal":123,
14680 "normal-bytes":123456,
14681 "dirty-sync-count":15
14682 },
14683 "disk":{
14684 "total":20971520,
14685 "remaining":20880384,
14686 "transferred":91136
14687 }
14688 }
14689 }
14690 6. Migration is being performed and XBZRLE is active:
14692 -> { "execute": "query-migrate" }
14694 <- {
14695 "return":{
14696 "status":"active",
14697 "total-time":12345,
14698 "setup-time":12345,
14699 "expected-downtime":12345,
14700 "ram":{
14701 "total":1057024,
14702 "remaining":1053304,
14703 "transferred":3720,
14704 "duplicate":10,
14705 "normal":3333,
14706 "normal-bytes":3412992,
14707 "dirty-sync-count":15
14708 },
14709 "xbzrle-cache":{
14710 "cache-size":67108864,
14711 "bytes":20971520,
14712 "pages":2444343,
14713 "cache-miss":2244,
14714 "cache-miss-rate":0.123,
14715 "encoding-rate":80.1,
14716 "overflow":34434
14717 }
14718 }
14719 }
14720 MigrationCapability (Enum)
14722 Migration capabilities enumeration
14723 Values
14725 xbzrle Migration supports xbzrle (Xor Based Zero Run Length Encoding).
14726 This feature allows us to minimize migration traffic for certain
14727 work loads, by sending compressed difference of the pages
14728 rdma-pin-all
14730 Controls whether or not the entire VM memory footprint is
14731 mlock()'d on demand or all at once. Refer to docs/rdma.txt for
14732 usage. Disabled by default. (since 2.0)
14733 zero-blocks
14735 During storage migration encode blocks of zeroes efficiently.
14736 This essentially saves 1MB of zeroes per block on the wire. En‐
14737 abling requires source and target VM to support this feature. To
14738 enable it is sufficient to enable the capability on the source
14739 VM. The feature is disabled by default. (since 1.6)
14740 compress
14742 Use multiple compression threads to accelerate live migration.
14743 This feature can help to reduce the migration traffic, by send‐
14744 ing compressed pages. Please note that if compress and xbzrle
14745 are both on, compress only takes effect in the ram bulk stage,
14746 after that, it will be disabled and only xbzrle takes effect,
14747 this can help to minimize migration traffic. The feature is dis‐
14748 abled by default. (since 2.4 )
14749 events generate events for each migration state change (since 2.4 )
14751 auto-converge
14753 If enabled, QEMU will automatically throttle down the guest to
14754 speed up convergence of RAM migration. (since 1.6)
14755 postcopy-ram
14757 Start executing on the migration target before all of RAM has
14758 been migrated, pulling the remaining pages along as needed. The
14759 capacity must have the same setting on both source and target or
14760 migration will not even start. NOTE: If the migration fails dur‐
14761 ing postcopy the VM will fail. (since 2.6)
14762 x-colo If enabled, migration will never end, and the state of the VM on
14764 the primary side will be migrated continuously to the VM on sec‐
14765 ondary side, this process is called COarse-Grain LOck Stepping
14766 (COLO) for Non-stop Service. (since 2.8)
14767 release-ram
14769 if enabled, qemu will free the migrated ram pages on the source
14770 during postcopy-ram migration. (since 2.9)
14771 block If enabled, QEMU will also migrate the contents of all block de‐
14773 vices. Default is disabled. A possible alternative uses mirror
14774 jobs to a builtin NBD server on the destination, which offers
14775 more flexibility. (Since 2.10)
14776 return-path
14778 If enabled, migration will use the return path even for precopy.
14779 (since 2.10)
14780 pause-before-switchover
14782 Pause outgoing migration before serialising device state and be‐
14783 fore disabling block IO (since 2.11)
14784 multifd
14786 Use more than one fd for migration (since 4.0)
14787 dirty-bitmaps
14789 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
14790 postcopy-blocktime
14792 Calculate downtime for postcopy live migration (since 3.0)
14793 late-block-activate
14795 If enabled, the destination will not activate block devices (and
14796 thus take locks) immediately at the end of migration. (since
14797 3.0)
14798 x-ignore-shared
14800 If enabled, QEMU will not migrate shared memory (since 4.0)
14801 validate-uuid
14803 Send the UUID of the source to allow the destination to ensure
14804 it is the same. (since 4.2)
14805 background-snapshot
14807 If enabled, the migration stream will be a snapshot of the VM
14808 exactly at the point when the migration procedure starts. The VM
14809 RAM is saved with running VM. (since 6.0)
14810 zero-copy-send
14812 Controls behavior on sending memory pages on migration. When
14813 true, enables a zero-copy mechanism for sending memory pages, if
14814 host supports it. Requires that QEMU be permitted to use locked
14815 memory for guest RAM pages. (since 7.1)
14816 postcopy-preempt
14818 If enabled, the migration process will allow postcopy requests
14819 to preempt precopy stream, so postcopy requests will be handled
14820 faster. This is a performance feature and should not affect the
14821 correctness of postcopy migration. (since 7.1)
14822 Features
14824 unstable
14825 Members x-colo and x-ignore-shared are experimental.
14826 Since
14828 1.2
14829 MigrationCapabilityStatus (Object)
14831 Migration capability information
14832 Members
14834 capability: MigrationCapability
14835 capability enum
14836 state: boolean
14838 capability state bool
14839 Since
14841 1.2
14842 migrate-set-capabilities (Command)
14844 Enable/Disable the following migration capabilities (like xbzrle)
14845 Arguments
14847 capabilities: array of MigrationCapabilityStatus
14848 json array of capability modifications to make
14849 Since
14851 1.2
14852 Example
14854 -> { "execute": "migrate-set-capabilities" , "arguments":
14855 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
14856 query-migrate-capabilities (Command)
14858 Returns information about the current migration capabilities status
14859 Returns
14861 MigrationCapabilitiesStatus
14862 Since
14864 1.2
14865 Example
14867 -> { "execute": "query-migrate-capabilities" }
14868 <- { "return": [
14869 {"state": false, "capability": "xbzrle"},
14870 {"state": false, "capability": "rdma-pin-all"},
14871 {"state": false, "capability": "auto-converge"},
14872 {"state": false, "capability": "zero-blocks"},
14873 {"state": false, "capability": "compress"},
14874 {"state": true, "capability": "events"},
14875 {"state": false, "capability": "postcopy-ram"},
14876 {"state": false, "capability": "x-colo"}
14877 ]}
14878 MultiFDCompression (Enum)
14880 An enumeration of multifd compression methods.
14881 Values
14883 none no compression.
14884 zlib use zlib compression method.
14886 zstd (If: CONFIG_ZSTD)
14888 use zstd compression method.
14889 Since
14891 5.0
14892 BitmapMigrationBitmapAliasTransform (Object)
14894 Members
14895 persistent: boolean (optional)
14896 If present, the bitmap will be made persistent or transient de‐
14897 pending on this parameter.
14898 Since
14900 6.0
14901 BitmapMigrationBitmapAlias (Object)
14903 Members
14904 name: string
14905 The name of the bitmap.
14906 alias: string
14908 An alias name for migration (for example the bitmap name on the
14909 opposite site).
14910 transform: BitmapMigrationBitmapAliasTransform (optional)
14912 Allows the modification of the migrated bitmap. (since 6.0)
14913 Since
14915 5.2
14916 BitmapMigrationNodeAlias (Object)
14918 Maps a block node name and the bitmaps it has to aliases for dirty bit‐
14919 map migration.
14920 Members
14922 node-name: string
14923 A block node name.
14924 alias: string
14926 An alias block node name for migration (for example the node
14927 name on the opposite site).
14928 bitmaps: array of BitmapMigrationBitmapAlias
14930 Mappings for the bitmaps on this node.
14931 Since
14933 5.2
14934 MigrationParameter (Enum)
14936 Migration parameters enumeration
14937 Values
14939 announce-initial
14940 Initial delay (in milliseconds) before sending the first an‐
14941 nounce (Since 4.0)
14942 announce-max
14944 Maximum delay (in milliseconds) between packets in the announce‐
14945 ment (Since 4.0)
14946 announce-rounds
14948 Number of self-announce packets sent after migration (Since 4.0)
14949 announce-step
14951 Increase in delay (in milliseconds) between subsequent packets
14952 in the announcement (Since 4.0)
14953 compress-level
14955 Set the compression level to be used in live migration, the com‐
14956 pression level is an integer between 0 and 9, where 0 means no
14957 compression, 1 means the best compression speed, and 9 means
14958 best compression ratio which will consume more CPU.
14959 compress-threads
14961 Set compression thread count to be used in live migration, the
14962 compression thread count is an integer between 1 and 255.
14963 compress-wait-thread
14965 Controls behavior when all compression threads are currently
14966 busy. If true (default), wait for a free compression thread to
14967 become available; otherwise, send the page uncompressed. (Since
14968 3.1)
14969 decompress-threads
14971 Set decompression thread count to be used in live migration, the
14972 decompression thread count is an integer between 1 and 255. Usu‐
14973 ally, decompression is at least 4 times as fast as compression,
14974 so set the decompress-threads to the number about 1/4 of com‐
14975 press-threads is adequate.
14976 throttle-trigger-threshold
14978 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
14979 throttling. It is expressed as percentage. The default value is
14980 50. (Since 5.0)
14981 cpu-throttle-initial
14983 Initial percentage of time guest cpus are throttled when migra‐
14984 tion auto-converge is activated. The default value is 20. (Since
14985 2.7)
14986 cpu-throttle-increment
14988 throttle percentage increase each time auto-converge detects
14989 that migration is not making progress. The default value is 10.
14990 (Since 2.7)
14991 cpu-throttle-tailslow
14993 Make CPU throttling slower at tail stage At the tail stage of
14994 throttling, the Guest is very sensitive to CPU percentage while
14995 the cpu-throttle -increment is excessive usually at tail stage.
14996 If this parameter is true, we will compute the ideal CPU per‐
14997 centage used by the Guest, which may exactly make the dirty rate
14998 match the dirty rate threshold. Then we will choose a smaller
14999 throttle increment between the one specified by cpu-throttle-in‐
15000 crement and the one generated by ideal CPU percentage. There‐
15001 fore, it is compatible to traditional throttling, meanwhile the
15002 throttle increment won't be excessive at tail stage. The de‐
15003 fault value is false. (Since 5.1)
15004 tls-creds
15006 ID of the 'tls-creds' object that provides credentials for es‐
15007 tablishing a TLS connection over the migration data channel. On
15008 the outgoing side of the migration, the credentials must be for
15009 a 'client' endpoint, while for the incoming side the credentials
15010 must be for a 'server' endpoint. Setting this will enable TLS
15011 for all migrations. The default is unset, resulting in unsecured
15012 migration at the QEMU level. (Since 2.7)
15013 tls-hostname
15015 hostname of the target host for the migration. This is required
15016 when using x509 based TLS credentials and the migration URI does
15017 not already include a hostname. For example if using fd: or
15018 exec: based migration, the hostname must be provided so that the
15019 server's x509 certificate identity can be validated. (Since 2.7)
15020 tls-authz
15022 ID of the 'authz' object subclass that provides access control
15023 checking of the TLS x509 certificate distinguished name. This
15024 object is only resolved at time of use, so can be deleted and
15025 recreated on the fly while the migration server is active. If
15026 missing, it will default to denying access (Since 4.0)
15027 max-bandwidth
15029 to set maximum speed for migration. maximum speed in bytes per
15030 second. (Since 2.8)
15031 downtime-limit
15033 set maximum tolerated downtime for migration. maximum downtime
15034 in milliseconds (Since 2.8)
15035 x-checkpoint-delay
15037 The delay time (in ms) between two COLO checkpoints in periodic
15038 mode. (Since 2.8)
15039 block-incremental
15041 Affects how much storage is migrated when the block migration
15042 capability is enabled. When false, the entire storage backing
15043 chain is migrated into a flattened image at the destination;
15044 when true, only the active qcow2 layer is migrated and the des‐
15045 tination must already have access to the same backing chain as
15046 was used on the source. (since 2.10)
15047 multifd-channels
15049 Number of channels used to migrate data in parallel. This is the
15050 same number that the number of sockets used for migration. The
15051 default value is 2 (since 4.0)
15052 xbzrle-cache-size
15054 cache size to be used by XBZRLE migration. It needs to be a
15055 multiple of the target page size and a power of 2 (Since 2.11)
15056 max-postcopy-bandwidth
15058 Background transfer bandwidth during postcopy. Defaults to 0
15059 (unlimited). In bytes per second. (Since 3.0)
15060 max-cpu-throttle
15062 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
15063 multifd-compression
15065 Which compression method to use. Defaults to none. (Since 5.0)
15066 multifd-zlib-level
15068 Set the compression level to be used in live migration, the com‐
15069 pression level is an integer between 0 and 9, where 0 means no
15070 compression, 1 means the best compression speed, and 9 means
15071 best compression ratio which will consume more CPU. Defaults to
15072 1. (Since 5.0)
15073 multifd-zstd-level
15075 Set the compression level to be used in live migration, the com‐
15076 pression level is an integer between 0 and 20, where 0 means no
15077 compression, 1 means the best compression speed, and 20 means
15078 best compression ratio which will consume more CPU. Defaults to
15079 1. (Since 5.0)
15080 block-bitmap-mapping
15082 Maps block nodes and bitmaps on them to aliases for the purpose
15083 of dirty bitmap migration. Such aliases may for example be the
15084 corresponding names on the opposite site. The mapping must be
15085 one-to-one, but not necessarily complete: On the source, un‐
15086 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
15087 nored. On the destination, encountering an unmapped alias in
15088 the incoming migration stream will result in a report, and all
15089 further bitmap migration data will then be discarded. Note that
15090 the destination does not know about bitmaps it does not receive,
15091 so there is no limitation or requirement regarding the number of
15092 bitmaps received, or how they are named, or on which nodes they
15093 are placed. By default (when this parameter has never been
15094 set), bitmap names are mapped to themselves. Nodes are mapped
15095 to their block device name if there is one, and to their node
15096 name otherwise. (Since 5.2)
15097 Features
15099 unstable
15100 Member x-checkpoint-delay is experimental.
15101 Since
15103 2.4
15104 MigrateSetParameters (Object)
15106 Members
15107 announce-initial: int (optional)
15108 Initial delay (in milliseconds) before sending the first an‐
15109 nounce (Since 4.0)
15110 announce-max: int (optional)
15112 Maximum delay (in milliseconds) between packets in the announce‐
15113 ment (Since 4.0)
15114 announce-rounds: int (optional)
15116 Number of self-announce packets sent after migration (Since 4.0)
15117 announce-step: int (optional)
15119 Increase in delay (in milliseconds) between subsequent packets
15120 in the announcement (Since 4.0)
15121 compress-level: int (optional)
15123 compression level
15124 compress-threads: int (optional)
15126 compression thread count
15127 compress-wait-thread: boolean (optional)
15129 Controls behavior when all compression threads are currently
15130 busy. If true (default), wait for a free compression thread to
15131 become available; otherwise, send the page uncompressed. (Since
15132 3.1)
15133 decompress-threads: int (optional)
15135 decompression thread count
15136 throttle-trigger-threshold: int (optional)
15138 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
15139 throttling. It is expressed as percentage. The default value is
15140 50. (Since 5.0)
15141 cpu-throttle-initial: int (optional)
15143 Initial percentage of time guest cpus are throttled when migra‐
15144 tion auto-converge is activated. The default value is 20.
15145 (Since 2.7)
15146 cpu-throttle-increment: int (optional)
15148 throttle percentage increase each time auto-converge detects
15149 that migration is not making progress. The default value is 10.
15150 (Since 2.7)
15151 cpu-throttle-tailslow: boolean (optional)
15153 Make CPU throttling slower at tail stage At the tail stage of
15154 throttling, the Guest is very sensitive to CPU percentage while
15155 the cpu-throttle -increment is excessive usually at tail stage.
15156 If this parameter is true, we will compute the ideal CPU per‐
15157 centage used by the Guest, which may exactly make the dirty rate
15158 match the dirty rate threshold. Then we will choose a smaller
15159 throttle increment between the one specified by cpu-throttle-in‐
15160 crement and the one generated by ideal CPU percentage. There‐
15161 fore, it is compatible to traditional throttling, meanwhile the
15162 throttle increment won't be excessive at tail stage. The de‐
15163 fault value is false. (Since 5.1)
15164 tls-creds: StrOrNull (optional)
15166 ID of the 'tls-creds' object that provides credentials for es‐
15167 tablishing a TLS connection over the migration data channel. On
15168 the outgoing side of the migration, the credentials must be for
15169 a 'client' endpoint, while for the incoming side the credentials
15170 must be for a 'server' endpoint. Setting this to a non-empty
15171 string enables TLS for all migrations. An empty string means
15172 that QEMU will use plain text mode for migration, rather than
15173 TLS (Since 2.9) Previously (since 2.7), this was reported by
15174 omitting tls-creds instead.
15175 tls-hostname: StrOrNull (optional)
15177 hostname of the target host for the migration. This is required
15178 when using x509 based TLS credentials and the migration URI does
15179 not already include a hostname. For example if using fd: or
15180 exec: based migration, the hostname must be provided so that the
15181 server's x509 certificate identity can be validated. (Since 2.7)
15182 An empty string means that QEMU will use the hostname associated
15183 with the migration URI, if any. (Since 2.9) Previously (since
15184 2.7), this was reported by omitting tls-hostname instead.
15185 max-bandwidth: int (optional)
15187 to set maximum speed for migration. maximum speed in bytes per
15188 second. (Since 2.8)
15189 downtime-limit: int (optional)
15191 set maximum tolerated downtime for migration. maximum downtime
15192 in milliseconds (Since 2.8)
15193 x-checkpoint-delay: int (optional)
15195 the delay time between two COLO checkpoints. (Since 2.8)
15196 block-incremental: boolean (optional)
15198 Affects how much storage is migrated when the block migration
15199 capability is enabled. When false, the entire storage backing
15200 chain is migrated into a flattened image at the destination;
15201 when true, only the active qcow2 layer is migrated and the des‐
15202 tination must already have access to the same backing chain as
15203 was used on the source. (since 2.10)
15204 multifd-channels: int (optional)
15206 Number of channels used to migrate data in parallel. This is the
15207 same number that the number of sockets used for migration. The
15208 default value is 2 (since 4.0)
15209 xbzrle-cache-size: int (optional)
15211 cache size to be used by XBZRLE migration. It needs to be a
15212 multiple of the target page size and a power of 2 (Since 2.11)
15213 max-postcopy-bandwidth: int (optional)
15215 Background transfer bandwidth during postcopy. Defaults to 0
15216 (unlimited). In bytes per second. (Since 3.0)
15217 max-cpu-throttle: int (optional)
15219 maximum cpu throttle percentage. The default value is 99.
15220 (Since 3.1)
15221 multifd-compression: MultiFDCompression (optional)
15223 Which compression method to use. Defaults to none. (Since 5.0)
15224 multifd-zlib-level: int (optional)
15226 Set the compression level to be used in live migration, the com‐
15227 pression level is an integer between 0 and 9, where 0 means no
15228 compression, 1 means the best compression speed, and 9 means
15229 best compression ratio which will consume more CPU. Defaults to
15230 1. (Since 5.0)
15231 multifd-zstd-level: int (optional)
15233 Set the compression level to be used in live migration, the com‐
15234 pression level is an integer between 0 and 20, where 0 means no
15235 compression, 1 means the best compression speed, and 20 means
15236 best compression ratio which will consume more CPU. Defaults to
15237 1. (Since 5.0)
15238 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
15240 Maps block nodes and bitmaps on them to aliases for the purpose
15241 of dirty bitmap migration. Such aliases may for example be the
15242 corresponding names on the opposite site. The mapping must be
15243 one-to-one, but not necessarily complete: On the source, un‐
15244 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
15245 nored. On the destination, encountering an unmapped alias in
15246 the incoming migration stream will result in a report, and all
15247 further bitmap migration data will then be discarded. Note that
15248 the destination does not know about bitmaps it does not receive,
15249 so there is no limitation or requirement regarding the number of
15250 bitmaps received, or how they are named, or on which nodes they
15251 are placed. By default (when this parameter has never been
15252 set), bitmap names are mapped to themselves. Nodes are mapped
15253 to their block device name if there is one, and to their node
15254 name otherwise. (Since 5.2)
15255 tls-authz: StrOrNull (optional)
15257 Not documented
15258 Features
15260 unstable
15261 Member x-checkpoint-delay is experimental.
15262 Since
15264 2.4
15265 migrate-set-parameters (Command)
15267 Set various migration parameters.
15268 Arguments
15270 The members of MigrateSetParameters
15271 Since
15273 2.4
15274 Example
15276 -> { "execute": "migrate-set-parameters" ,
15277 "arguments": { "compress-level": 1 } }
15278 MigrationParameters (Object)
15280 The optional members aren't actually optional.
15281 Members
15283 announce-initial: int (optional)
15284 Initial delay (in milliseconds) before sending the first an‐
15285 nounce (Since 4.0)
15286 announce-max: int (optional)
15288 Maximum delay (in milliseconds) between packets in the announce‐
15289 ment (Since 4.0)
15290 announce-rounds: int (optional)
15292 Number of self-announce packets sent after migration (Since 4.0)
15293 announce-step: int (optional)
15295 Increase in delay (in milliseconds) between subsequent packets
15296 in the announcement (Since 4.0)
15297 compress-level: int (optional)
15299 compression level
15300 compress-threads: int (optional)
15302 compression thread count
15303 compress-wait-thread: boolean (optional)
15305 Controls behavior when all compression threads are currently
15306 busy. If true (default), wait for a free compression thread to
15307 become available; otherwise, send the page uncompressed. (Since
15308 3.1)
15309 decompress-threads: int (optional)
15311 decompression thread count
15312 throttle-trigger-threshold: int (optional)
15314 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
15315 throttling. It is expressed as percentage. The default value is
15316 50. (Since 5.0)
15317 cpu-throttle-initial: int (optional)
15319 Initial percentage of time guest cpus are throttled when migra‐
15320 tion auto-converge is activated. (Since 2.7)
15321 cpu-throttle-increment: int (optional)
15323 throttle percentage increase each time auto-converge detects
15324 that migration is not making progress. (Since 2.7)
15325 cpu-throttle-tailslow: boolean (optional)
15327 Make CPU throttling slower at tail stage At the tail stage of
15328 throttling, the Guest is very sensitive to CPU percentage while
15329 the cpu-throttle -increment is excessive usually at tail stage.
15330 If this parameter is true, we will compute the ideal CPU per‐
15331 centage used by the Guest, which may exactly make the dirty rate
15332 match the dirty rate threshold. Then we will choose a smaller
15333 throttle increment between the one specified by cpu-throttle-in‐
15334 crement and the one generated by ideal CPU percentage. There‐
15335 fore, it is compatible to traditional throttling, meanwhile the
15336 throttle increment won't be excessive at tail stage. The de‐
15337 fault value is false. (Since 5.1)
15338 tls-creds: string (optional)
15340 ID of the 'tls-creds' object that provides credentials for es‐
15341 tablishing a TLS connection over the migration data channel. On
15342 the outgoing side of the migration, the credentials must be for
15343 a 'client' endpoint, while for the incoming side the credentials
15344 must be for a 'server' endpoint. An empty string means that
15345 QEMU will use plain text mode for migration, rather than TLS
15346 (Since 2.7) Note: 2.8 reports this by omitting tls-creds in‐
15347 stead.
15348 tls-hostname: string (optional)
15350 hostname of the target host for the migration. This is required
15351 when using x509 based TLS credentials and the migration URI does
15352 not already include a hostname. For example if using fd: or
15353 exec: based migration, the hostname must be provided so that the
15354 server's x509 certificate identity can be validated. (Since 2.7)
15355 An empty string means that QEMU will use the hostname associated
15356 with the migration URI, if any. (Since 2.9) Note: 2.8 reports
15357 this by omitting tls-hostname instead.
15358 tls-authz: string (optional)
15360 ID of the 'authz' object subclass that provides access control
15361 checking of the TLS x509 certificate distinguished name. (Since
15362 4.0)
15363 max-bandwidth: int (optional)
15365 to set maximum speed for migration. maximum speed in bytes per
15366 second. (Since 2.8)
15367 downtime-limit: int (optional)
15369 set maximum tolerated downtime for migration. maximum downtime
15370 in milliseconds (Since 2.8)
15371 x-checkpoint-delay: int (optional)
15373 the delay time between two COLO checkpoints. (Since 2.8)
15374 block-incremental: boolean (optional)
15376 Affects how much storage is migrated when the block migration
15377 capability is enabled. When false, the entire storage backing
15378 chain is migrated into a flattened image at the destination;
15379 when true, only the active qcow2 layer is migrated and the des‐
15380 tination must already have access to the same backing chain as
15381 was used on the source. (since 2.10)
15382 multifd-channels: int (optional)
15384 Number of channels used to migrate data in parallel. This is the
15385 same number that the number of sockets used for migration. The
15386 default value is 2 (since 4.0)
15387 xbzrle-cache-size: int (optional)
15389 cache size to be used by XBZRLE migration. It needs to be a
15390 multiple of the target page size and a power of 2 (Since 2.11)
15391 max-postcopy-bandwidth: int (optional)
15393 Background transfer bandwidth during postcopy. Defaults to 0
15394 (unlimited). In bytes per second. (Since 3.0)
15395 max-cpu-throttle: int (optional)
15397 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
15398 multifd-compression: MultiFDCompression (optional)
15400 Which compression method to use. Defaults to none. (Since 5.0)
15401 multifd-zlib-level: int (optional)
15403 Set the compression level to be used in live migration, the com‐
15404 pression level is an integer between 0 and 9, where 0 means no
15405 compression, 1 means the best compression speed, and 9 means
15406 best compression ratio which will consume more CPU. Defaults to
15407 1. (Since 5.0)
15408 multifd-zstd-level: int (optional)
15410 Set the compression level to be used in live migration, the com‐
15411 pression level is an integer between 0 and 20, where 0 means no
15412 compression, 1 means the best compression speed, and 20 means
15413 best compression ratio which will consume more CPU. Defaults to
15414 1. (Since 5.0)
15415 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
15417 Maps block nodes and bitmaps on them to aliases for the purpose
15418 of dirty bitmap migration. Such aliases may for example be the
15419 corresponding names on the opposite site. The mapping must be
15420 one-to-one, but not necessarily complete: On the source, un‐
15421 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
15422 nored. On the destination, encountering an unmapped alias in
15423 the incoming migration stream will result in a report, and all
15424 further bitmap migration data will then be discarded. Note that
15425 the destination does not know about bitmaps it does not receive,
15426 so there is no limitation or requirement regarding the number of
15427 bitmaps received, or how they are named, or on which nodes they
15428 are placed. By default (when this parameter has never been
15429 set), bitmap names are mapped to themselves. Nodes are mapped
15430 to their block device name if there is one, and to their node
15431 name otherwise. (Since 5.2)
15432 Features
15434 unstable
15435 Member x-checkpoint-delay is experimental.
15436 Since
15438 2.4
15439 query-migrate-parameters (Command)
15441 Returns information about the current migration parameters
15442 Returns
15444 MigrationParameters
15445 Since
15447 2.4
15448 Example
15450 -> { "execute": "query-migrate-parameters" }
15451 <- { "return": {
15452 "decompress-threads": 2,
15453 "cpu-throttle-increment": 10,
15454 "compress-threads": 8,
15455 "compress-level": 1,
15456 "cpu-throttle-initial": 20,
15457 "max-bandwidth": 33554432,
15458 "downtime-limit": 300
15459 }
15460 }
15461 client_migrate_info (Command)
15463 Set migration information for remote display. This makes the server
15464 ask the client to automatically reconnect using the new parameters once
15465 migration finished successfully. Only implemented for SPICE.
15466 Arguments
15468 protocol: string
15469 must be "spice"
15470 hostname: string
15472 migration target hostname
15473 port: int (optional)
15475 spice tcp port for plaintext channels
15476 tls-port: int (optional)
15478 spice tcp port for tls-secured channels
15479 cert-subject: string (optional)
15481 server certificate subject
15482 Since
15484 0.14
15485 Example
15487 -> { "execute": "client_migrate_info",
15488 "arguments": { "protocol": "spice",
15489 "hostname": "virt42.lab.kraxel.org",
15490 "port": 1234 } }
15491 <- { "return": {} }
15492 migrate-start-postcopy (Command)
15494 Followup to a migration command to switch the migration to postcopy
15495 mode. The postcopy-ram capability must be set on both source and des‐
15496 tination before the original migration command.
15497 Since
15499 2.5
15500 Example
15502 -> { "execute": "migrate-start-postcopy" }
15503 <- { "return": {} }
15504 MIGRATION (Event)
15506 Emitted when a migration event happens
15507 Arguments
15509 status: MigrationStatus
15510 MigrationStatus describing the current migration status.
15511 Since
15513 2.4
15514 Example
15516 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
15517 "event": "MIGRATION",
15518 "data": {"status": "completed"} }
15519 MIGRATION_PASS (Event)
15521 Emitted from the source side of a migration at the start of each pass
15522 (when it syncs the dirty bitmap)
15523 Arguments
15525 pass: int
15526 An incrementing count (starting at 1 on the first pass)
15527 Since
15529 2.6
15530 Example
15532 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
15533 "event": "MIGRATION_PASS", "data": {"pass": 2} }
15534 COLOMessage (Enum)
15536 The message transmission between Primary side and Secondary side.
15537 Values
15539 checkpoint-ready
15540 Secondary VM (SVM) is ready for checkpointing
15541 checkpoint-request
15543 Primary VM (PVM) tells SVM to prepare for checkpointing
15544 checkpoint-reply
15546 SVM gets PVM's checkpoint request
15547 vmstate-send
15549 VM's state will be sent by PVM.
15550 vmstate-size
15552 The total size of VMstate.
15553 vmstate-received
15555 VM's state has been received by SVM.
15556 vmstate-loaded
15558 VM's state has been loaded by SVM.
15559 Since
15561 2.8
15562 COLOMode (Enum)
15564 The COLO current mode.
15565 Values
15567 none COLO is disabled.
15568 primary
15570 COLO node in primary side.
15571 secondary
15573 COLO node in slave side.
15574 Since
15576 2.8
15577 FailoverStatus (Enum)
15579 An enumeration of COLO failover status
15580 Values
15582 none no failover has ever happened
15583 require
15585 got failover requirement but not handled
15586 active in the process of doing failover
15588 completed
15590 finish the process of failover
15591 relaunch
15593 restart the failover process, from 'none' -> 'completed' (Since
15594 2.9)
15595 Since
15597 2.8
15598 COLO_EXIT (Event)
15600 Emitted when VM finishes COLO mode due to some errors happening or at
15601 the request of users.
15602 Arguments
15604 mode: COLOMode
15605 report COLO mode when COLO exited.
15606 reason: COLOExitReason
15608 describes the reason for the COLO exit.
15609 Since
15611 3.1
15612 Example
15614 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
15615 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
15616 COLOExitReason (Enum)
15618 The reason for a COLO exit.
15619 Values
15621 none failover has never happened. This state does not occur in the
15622 COLO_EXIT event, and is only visible in the result of
15623 query-colo-status.
15624 request
15626 COLO exit is due to an external request.
15627 error COLO exit is due to an internal error.
15629 processing
15631 COLO is currently handling a failover (since 4.0).
15632 Since
15634 3.1
15635 x-colo-lost-heartbeat (Command)
15637 Tell qemu that heartbeat is lost, request it to do takeover procedures.
15638 If this command is sent to the PVM, the Primary side will exit COLO
15639 mode. If sent to the Secondary, the Secondary side will run failover
15640 work, then takes over server operation to become the service VM.
15641 Features
15643 unstable
15644 This command is experimental.
15645 Since
15647 2.8
15648 Example
15650 -> { "execute": "x-colo-lost-heartbeat" }
15651 <- { "return": {} }
15652 migrate_cancel (Command)
15654 Cancel the current executing migration process.
15655 Returns
15657 nothing on success
15658 Notes
15660 This command succeeds even if there is no migration process running.
15661 Since
15663 0.14
15664 Example
15666 -> { "execute": "migrate_cancel" }
15667 <- { "return": {} }
15668 migrate-continue (Command)
15670 Continue migration when it's in a paused state.
15671 Arguments
15673 state: MigrationStatus
15674 The state the migration is currently expected to be in
15675 Returns
15677 nothing on success
15678 Since
15680 2.11
15681 Example
15683 -> { "execute": "migrate-continue" , "arguments":
15684 { "state": "pre-switchover" } }
15685 <- { "return": {} }
15686 migrate (Command)
15688 Migrates the current running guest to another Virtual Machine.
15689 Arguments
15691 uri: string
15692 the Uniform Resource Identifier of the destination VM
15693 blk: boolean (optional)
15695 do block migration (full disk copy)
15696 inc: boolean (optional)
15698 incremental disk copy migration
15699 detach: boolean (optional)
15701 this argument exists only for compatibility reasons and is ig‐
15702 nored by QEMU
15703 resume: boolean (optional)
15705 resume one paused migration, default "off". (since 3.0)
15706 Returns
15708 nothing on success
15709 Since
15711 0.14
15712 Notes
15714 1. The 'query-migrate' command should be used to check migration's
15715 progress and final result (this information is provided by the 'sta‐
15716 tus' member)
15717 2. All boolean arguments default to false
15719 3. The user Monitor's "detach" argument is invalid in QMP and should
15721 not be used
15722 Example
15724 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
15725 <- { "return": {} }
15726 migrate-incoming (Command)
15728 Start an incoming migration, the qemu must have been started with -in‐
15729 coming defer
15730 Arguments
15732 uri: string
15733 The Uniform Resource Identifier identifying the source or ad‐
15734 dress to listen on
15735 Returns
15737 nothing on success
15738 Since
15740 2.3
15741 Notes
15743 1. It's a bad idea to use a string for the uri, but it needs to stay
15744 compatible with -incoming and the format of the uri is already ex‐
15745 posed above libvirt.
15746 2. QEMU must be started with -incoming defer to allow migrate-incoming
15748 to be used.
15749 3. The uri format is the same as for -incoming
15751 Example
15753 -> { "execute": "migrate-incoming",
15754 "arguments": { "uri": "tcp::4446" } }
15755 <- { "return": {} }
15756 xen-save-devices-state (Command)
15758 Save the state of all devices to file. The RAM and the block devices of
15759 the VM are not saved by this command.
15760 Arguments
15762 filename: string
15763 the file to save the state of the devices to as binary data. See
15764 xen-save-devices-state.txt for a description of the binary for‐
15765 mat.
15766 live: boolean (optional)
15768 Optional argument to ask QEMU to treat this command as part of a
15769 live migration. Default to true. (since 2.11)
15770 Returns
15772 Nothing on success
15773 Since
15775 1.1
15776 Example
15778 -> { "execute": "xen-save-devices-state",
15779 "arguments": { "filename": "/tmp/save" } }
15780 <- { "return": {} }
15781 xen-set-global-dirty-log (Command)
15783 Enable or disable the global dirty log mode.
15784 Arguments
15786 enable: boolean
15787 true to enable, false to disable.
15788 Returns
15790 nothing
15791 Since
15793 1.3
15794 Example
15796 -> { "execute": "xen-set-global-dirty-log",
15797 "arguments": { "enable": true } }
15798 <- { "return": {} }
15799 xen-load-devices-state (Command)
15801 Load the state of all devices from file. The RAM and the block devices
15802 of the VM are not loaded by this command.
15803 Arguments
15805 filename: string
15806 the file to load the state of the devices from as binary data.
15807 See xen-save-devices-state.txt for a description of the binary
15808 format.
15809 Since
15811 2.7
15812 Example
15814 -> { "execute": "xen-load-devices-state",
15815 "arguments": { "filename": "/tmp/resume" } }
15816 <- { "return": {} }
15817 xen-set-replication (Command)
15819 Enable or disable replication.
15820 Arguments
15822 enable: boolean
15823 true to enable, false to disable.
15824 primary: boolean
15826 true for primary or false for secondary.
15827 failover: boolean (optional)
15829 true to do failover, false to stop. but cannot be specified if
15830 'enable' is true. default value is false.
15831 Returns
15833 nothing.
15834 Example
15836 -> { "execute": "xen-set-replication",
15837 "arguments": {"enable": true, "primary": false} }
15838 <- { "return": {} }
15839 Since
15841 2.9
15842 If
15844 CONFIG_REPLICATION
15845 ReplicationStatus (Object)
15847 The result format for 'query-xen-replication-status'.
15848 Members
15850 error: boolean
15851 true if an error happened, false if replication is normal.
15852 desc: string (optional)
15854 the human readable error description string, when error is
15855 'true'.
15856 Since
15858 2.9
15859 If
15861 CONFIG_REPLICATION
15862 query-xen-replication-status (Command)
15864 Query replication status while the vm is running.
15865 Returns
15867 A ReplicationStatus object showing the status.
15868 Example
15870 -> { "execute": "query-xen-replication-status" }
15871 <- { "return": { "error": false } }
15872 Since
15874 2.9
15875 If
15877 CONFIG_REPLICATION
15878 xen-colo-do-checkpoint (Command)
15880 Xen uses this command to notify replication to trigger a checkpoint.
15881 Returns
15883 nothing.
15884 Example
15886 -> { "execute": "xen-colo-do-checkpoint" }
15887 <- { "return": {} }
15888 Since
15890 2.9
15891 If
15893 CONFIG_REPLICATION
15894 COLOStatus (Object)
15896 The result format for 'query-colo-status'.
15897 Members
15899 mode: COLOMode
15900 COLO running mode. If COLO is running, this field will return
15901 'primary' or 'secondary'.
15902 last-mode: COLOMode
15904 COLO last running mode. If COLO is running, this field will re‐
15905 turn same like mode field, after failover we can use this field
15906 to get last colo mode. (since 4.0)
15907 reason: COLOExitReason
15909 describes the reason for the COLO exit.
15910 Since
15912 3.1
15913 query-colo-status (Command)
15915 Query COLO status while the vm is running.
15916 Returns
15918 A COLOStatus object showing the status.
15919 Example
15921 -> { "execute": "query-colo-status" }
15922 <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } }
15923 Since
15925 3.1
15926 migrate-recover (Command)
15928 Provide a recovery migration stream URI.
15929 Arguments
15931 uri: string
15932 the URI to be used for the recovery of migration stream.
15933 Returns
15935 nothing.
15936 Example
15938 -> { "execute": "migrate-recover",
15939 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
15940 <- { "return": {} }
15941 Since
15943 3.0
15944 migrate-pause (Command)
15946 Pause a migration. Currently it only supports postcopy.
15947 Returns
15949 nothing.
15950 Example
15952 -> { "execute": "migrate-pause" }
15953 <- { "return": {} }
15954 Since
15956 3.0
15957 UNPLUG_PRIMARY (Event)
15959 Emitted from source side of a migration when migration state is
15960 WAIT_UNPLUG. Device was unplugged by guest operating system. Device
15961 resources in QEMU are kept on standby to be able to re-plug it in case
15962 of migration failure.
15963 Arguments
15965 device-id: string
15966 QEMU device id of the unplugged device
15967 Since
15969 4.2
15970 Example
15972 <- { "event": "UNPLUG_PRIMARY",
15973 "data": { "device-id": "hostdev0" },
15974 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
15975 DirtyRateVcpu (Object)
15977 Dirty rate of vcpu.
15978 Members
15980 id: int
15981 vcpu index.
15982 dirty-rate: int
15984 dirty rate.
15985 Since
15987 6.2
15988 DirtyRateStatus (Enum)
15990 An enumeration of dirtyrate status.
15991 Values
15993 unstarted
15994 the dirtyrate thread has not been started.
15995 measuring
15997 the dirtyrate thread is measuring.
15998 measured
16000 the dirtyrate thread has measured and results are available.
16001 Since
16003 5.2
16004 DirtyRateMeasureMode (Enum)
16006 An enumeration of mode of measuring dirtyrate.
16007 Values
16009 page-sampling
16010 calculate dirtyrate by sampling pages.
16011 dirty-ring
16013 calculate dirtyrate by dirty ring.
16014 dirty-bitmap
16016 calculate dirtyrate by dirty bitmap.
16017 Since
16019 6.2
16020 DirtyRateInfo (Object)
16022 Information about current dirty page rate of vm.
16023 Members
16025 dirty-rate: int (optional)
16026 an estimate of the dirty page rate of the VM in units of MB/s,
16027 present only when estimating the rate has completed.
16028 status: DirtyRateStatus
16030 status containing dirtyrate query status includes 'unstarted' or
16031 'measuring' or 'measured'
16032 start-time: int
16034 start time in units of second for calculation
16035 calc-time: int
16037 time in units of second for sample dirty pages
16038 sample-pages: int
16040 page count per GB for sample dirty pages the default value is
16041 512 (since 6.1)
16042 mode: DirtyRateMeasureMode
16044 mode containing method of calculate dirtyrate includes
16045 'page-sampling' and 'dirty-ring' (Since 6.2)
16046 vcpu-dirty-rate: array of DirtyRateVcpu (optional)
16048 dirtyrate for each vcpu if dirty-ring mode specified (Since 6.2)
16049 Since
16051 5.2
16052 calc-dirty-rate (Command)
16054 start calculating dirty page rate for vm
16055 Arguments
16057 calc-time: int
16058 time in units of second for sample dirty pages
16059 sample-pages: int (optional)
16061 page count per GB for sample dirty pages the default value is
16062 512 (since 6.1)
16063 mode: DirtyRateMeasureMode (optional)
16065 mechanism of calculating dirtyrate includes 'page-sampling' and
16066 'dirty-ring' (Since 6.1)
16067 Since
16069 5.2
16070 Example
16072 {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
16073 'sample-pages': 512} }
16074 query-dirty-rate (Command)
16076 query dirty page rate in units of MB/s for vm
16077 Since
16079 5.2
16080 DirtyLimitInfo (Object)
16082 Dirty page rate limit information of a virtual CPU.
16083 Members
16085 cpu-index: int
16086 index of a virtual CPU.
16087 limit-rate: int
16089 upper limit of dirty page rate (MB/s) for a virtual CPU, 0 means
16090 unlimited.
16091 current-rate: int
16093 current dirty page rate (MB/s) for a virtual CPU.
16094 Since
16096 7.1
16097 set-vcpu-dirty-limit (Command)
16099 Set the upper limit of dirty page rate for virtual CPUs.
16100 Requires KVM with accelerator property "dirty-ring-size" set. A vir‐
16102 tual CPU's dirty page rate is a measure of its memory load. To observe
16103 dirty page rates, use calc-dirty-rate.
16104 Arguments
16106 cpu-index: int (optional)
16107 index of a virtual CPU, default is all.
16108 dirty-rate: int
16110 upper limit of dirty page rate (MB/s) for virtual CPUs.
16111 Since
16113 7.1
16114 Example
16116 {"execute": "set-vcpu-dirty-limit"}
16117 "arguments": { "dirty-rate": 200,
16118 "cpu-index": 1 } }
16119 cancel-vcpu-dirty-limit (Command)
16121 Cancel the upper limit of dirty page rate for virtual CPUs.
16122 Cancel the dirty page limit for the vCPU which has been set with
16124 set-vcpu-dirty-limit command. Note that this command requires support
16125 from dirty ring, same as the "set-vcpu-dirty-limit".
16126 Arguments
16128 cpu-index: int (optional)
16129 index of a virtual CPU, default is all.
16130 Since
16132 7.1
16133 Example
16135 {"execute": "cancel-vcpu-dirty-limit"}
16136 "arguments": { "cpu-index": 1 } }
16137 query-vcpu-dirty-limit (Command)
16139 Returns information about virtual CPU dirty page rate limits, if any.
16140 Since
16142 7.1
16143 Example
16145 {"execute": "query-vcpu-dirty-limit"}
16146 snapshot-save (Command)
16148 Save a VM snapshot
16149 Arguments
16151 job-id: string
16152 identifier for the newly created job
16153 tag: string
16155 name of the snapshot to create
16156 vmstate: string
16158 block device node name to save vmstate to
16159 devices: array of string
16161 list of block device node names to save a snapshot to
16162 Applications should not assume that the snapshot save is complete when
16163 this command returns. The job commands / events must be used to deter‐
16164 mine completion and to fetch details of any errors that arise.
16165 Note that execution of the guest CPUs may be stopped during the time it
16167 takes to save the snapshot. A future version of QEMU may ensure CPUs
16168 are executing continuously.
16169 It is strongly recommended that devices contain all writable block de‐
16171 vice nodes if a consistent snapshot is required.
16172 If tag already exists, an error will be reported
16174 Returns
16176 nothing
16177 Example
16179 -> { "execute": "snapshot-save",
16180 "arguments": {
16181 "job-id": "snapsave0",
16182 "tag": "my-snap",
16183 "vmstate": "disk0",
16184 "devices": ["disk0", "disk1"]
16185 }
16186 }
16187 <- { "return": { } }
16188 <- {"event": "JOB_STATUS_CHANGE",
16189 "timestamp": {"seconds": 1432121972, "microseconds": 744001},
16190 "data": {"status": "created", "id": "snapsave0"}}
16191 <- {"event": "JOB_STATUS_CHANGE",
16192 "timestamp": {"seconds": 1432122172, "microseconds": 744001},
16193 "data": {"status": "running", "id": "snapsave0"}}
16194 <- {"event": "STOP",
16195 "timestamp": {"seconds": 1432122372, "microseconds": 744001} }
16196 <- {"event": "RESUME",
16197 "timestamp": {"seconds": 1432122572, "microseconds": 744001} }
16198 <- {"event": "JOB_STATUS_CHANGE",
16199 "timestamp": {"seconds": 1432122772, "microseconds": 744001},
16200 "data": {"status": "waiting", "id": "snapsave0"}}
16201 <- {"event": "JOB_STATUS_CHANGE",
16202 "timestamp": {"seconds": 1432122972, "microseconds": 744001},
16203 "data": {"status": "pending", "id": "snapsave0"}}
16204 <- {"event": "JOB_STATUS_CHANGE",
16205 "timestamp": {"seconds": 1432123172, "microseconds": 744001},
16206 "data": {"status": "concluded", "id": "snapsave0"}}
16207 -> {"execute": "query-jobs"}
16208 <- {"return": [{"current-progress": 1,
16209 "status": "concluded",
16210 "total-progress": 1,
16211 "type": "snapshot-save",
16212 "id": "snapsave0"}]}
16213 Since
16215 6.0
16216 snapshot-load (Command)
16218 Load a VM snapshot
16219 Arguments
16221 job-id: string
16222 identifier for the newly created job
16223 tag: string
16225 name of the snapshot to load.
16226 vmstate: string
16228 block device node name to load vmstate from
16229 devices: array of string
16231 list of block device node names to load a snapshot from
16232 Applications should not assume that the snapshot load is complete when
16233 this command returns. The job commands / events must be used to deter‐
16234 mine completion and to fetch details of any errors that arise.
16235 Note that execution of the guest CPUs will be stopped during the time
16237 it takes to load the snapshot.
16238 It is strongly recommended that devices contain all writable block de‐
16240 vice nodes that can have changed since the original snapshot-save com‐
16241 mand execution.
16242 Returns
16244 nothing
16245 Example
16247 -> { "execute": "snapshot-load",
16248 "arguments": {
16249 "job-id": "snapload0",
16250 "tag": "my-snap",
16251 "vmstate": "disk0",
16252 "devices": ["disk0", "disk1"]
16253 }
16254 }
16255 <- { "return": { } }
16256 <- {"event": "JOB_STATUS_CHANGE",
16257 "timestamp": {"seconds": 1472124172, "microseconds": 744001},
16258 "data": {"status": "created", "id": "snapload0"}}
16259 <- {"event": "JOB_STATUS_CHANGE",
16260 "timestamp": {"seconds": 1472125172, "microseconds": 744001},
16261 "data": {"status": "running", "id": "snapload0"}}
16262 <- {"event": "STOP",
16263 "timestamp": {"seconds": 1472125472, "microseconds": 744001} }
16264 <- {"event": "RESUME",
16265 "timestamp": {"seconds": 1472125872, "microseconds": 744001} }
16266 <- {"event": "JOB_STATUS_CHANGE",
16267 "timestamp": {"seconds": 1472126172, "microseconds": 744001},
16268 "data": {"status": "waiting", "id": "snapload0"}}
16269 <- {"event": "JOB_STATUS_CHANGE",
16270 "timestamp": {"seconds": 1472127172, "microseconds": 744001},
16271 "data": {"status": "pending", "id": "snapload0"}}
16272 <- {"event": "JOB_STATUS_CHANGE",
16273 "timestamp": {"seconds": 1472128172, "microseconds": 744001},
16274 "data": {"status": "concluded", "id": "snapload0"}}
16275 -> {"execute": "query-jobs"}
16276 <- {"return": [{"current-progress": 1,
16277 "status": "concluded",
16278 "total-progress": 1,
16279 "type": "snapshot-load",
16280 "id": "snapload0"}]}
16281 Since
16283 6.0
16284 snapshot-delete (Command)
16286 Delete a VM snapshot
16287 Arguments
16289 job-id: string
16290 identifier for the newly created job
16291 tag: string
16293 name of the snapshot to delete.
16294 devices: array of string
16296 list of block device node names to delete a snapshot from
16297 Applications should not assume that the snapshot delete is complete
16298 when this command returns. The job commands / events must be used to
16299 determine completion and to fetch details of any errors that arise.
16300 Returns
16302 nothing
16303 Example
16305 -> { "execute": "snapshot-delete",
16306 "arguments": {
16307 "job-id": "snapdelete0",
16308 "tag": "my-snap",
16309 "devices": ["disk0", "disk1"]
16310 }
16311 }
16312 <- { "return": { } }
16313 <- {"event": "JOB_STATUS_CHANGE",
16314 "timestamp": {"seconds": 1442124172, "microseconds": 744001},
16315 "data": {"status": "created", "id": "snapdelete0"}}
16316 <- {"event": "JOB_STATUS_CHANGE",
16317 "timestamp": {"seconds": 1442125172, "microseconds": 744001},
16318 "data": {"status": "running", "id": "snapdelete0"}}
16319 <- {"event": "JOB_STATUS_CHANGE",
16320 "timestamp": {"seconds": 1442126172, "microseconds": 744001},
16321 "data": {"status": "waiting", "id": "snapdelete0"}}
16322 <- {"event": "JOB_STATUS_CHANGE",
16323 "timestamp": {"seconds": 1442127172, "microseconds": 744001},
16324 "data": {"status": "pending", "id": "snapdelete0"}}
16325 <- {"event": "JOB_STATUS_CHANGE",
16326 "timestamp": {"seconds": 1442128172, "microseconds": 744001},
16327 "data": {"status": "concluded", "id": "snapdelete0"}}
16328 -> {"execute": "query-jobs"}
16329 <- {"return": [{"current-progress": 1,
16330 "status": "concluded",
16331 "total-progress": 1,
16332 "type": "snapshot-delete",
16333 "id": "snapdelete0"}]}
16334 Since
16336 6.0
16337
16339 Abort (Object)
16340 This action can be used to test transaction failure.
16341 Since
16343 1.6
16344 ActionCompletionMode (Enum)
16346 An enumeration of Transactional completion modes.
16347 Values
16349 individual
16350 Do not attempt to cancel any other Actions if any Actions fail
16351 after the Transaction request succeeds. All Actions that can
16352 complete successfully will do so without waiting on others.
16353 This is the default.
16354 grouped
16356 If any Action fails after the Transaction succeeds, cancel all
16357 Actions. Actions do not complete until all Actions are ready to
16358 complete. May be rejected by Actions that do not support this
16359 completion mode.
16360 Since
16362 2.5
16363 TransactionActionKind (Enum)
16365 Values
16366 abort Since 1.6
16367 block-dirty-bitmap-add
16369 Since 2.5
16370 block-dirty-bitmap-remove
16372 Since 4.2
16373 block-dirty-bitmap-clear
16375 Since 2.5
16376 block-dirty-bitmap-enable
16378 Since 4.0
16379 block-dirty-bitmap-disable
16381 Since 4.0
16382 block-dirty-bitmap-merge
16384 Since 4.0
16385 blockdev-backup
16387 Since 2.3
16388 blockdev-snapshot
16390 Since 2.5
16391 blockdev-snapshot-internal-sync
16393 Since 1.7
16394 blockdev-snapshot-sync
16396 since 1.1
16397 drive-backup
16399 Since 1.6
16400 Features
16402 deprecated
16403 Member drive-backup is deprecated. Use member blockdev-backup
16404 instead.
16405 Since
16407 1.1
16408 AbortWrapper (Object)
16410 Members
16411 data: Abort
16412 Not documented
16413 Since
16415 1.6
16416 BlockDirtyBitmapAddWrapper (Object)
16418 Members
16419 data: BlockDirtyBitmapAdd
16420 Not documented
16421 Since
16423 2.5
16424 BlockDirtyBitmapWrapper (Object)
16426 Members
16427 data: BlockDirtyBitmap
16428 Not documented
16429 Since
16431 2.5
16432 BlockDirtyBitmapMergeWrapper (Object)
16434 Members
16435 data: BlockDirtyBitmapMerge
16436 Not documented
16437 Since
16439 4.0
16440 BlockdevBackupWrapper (Object)
16442 Members
16443 data: BlockdevBackup
16444 Not documented
16445 Since
16447 2.3
16448 BlockdevSnapshotWrapper (Object)
16450 Members
16451 data: BlockdevSnapshot
16452 Not documented
16453 Since
16455 2.5
16456 BlockdevSnapshotInternalWrapper (Object)
16458 Members
16459 data: BlockdevSnapshotInternal
16460 Not documented
16461 Since
16463 1.7
16464 BlockdevSnapshotSyncWrapper (Object)
16466 Members
16467 data: BlockdevSnapshotSync
16468 Not documented
16469 Since
16471 1.1
16472 DriveBackupWrapper (Object)
16474 Members
16475 data: DriveBackup
16476 Not documented
16477 Since
16479 1.6
16480 TransactionAction (Object)
16482 A discriminated record of operations that can be performed with trans‐
16483 action.
16484 Members
16486 type: TransactionActionKind
16487 Not documented
16488 The members of AbortWrapper when type is "abort"
16490 The members of BlockDirtyBitmapAddWrapper when type is
16492 "block-dirty-bitmap-add"
16493 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
16495 map-remove"
16496 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
16498 map-clear"
16499 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
16501 map-enable"
16502 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
16504 map-disable"
16505 The members of BlockDirtyBitmapMergeWrapper when type is
16507 "block-dirty-bitmap-merge"
16508 The members of BlockdevBackupWrapper when type is "blockdev-backup"
16510 The members of BlockdevSnapshotWrapper when type is "blockdev-snapshot"
16512 The members of BlockdevSnapshotInternalWrapper when type is "block‐
16514 dev-snapshot-internal-sync"
16515 The members of BlockdevSnapshotSyncWrapper when type is "blockdev-snap‐
16517 shot-sync"
16518 The members of DriveBackupWrapper when type is "drive-backup"
16520 Since
16522 1.1
16523 TransactionProperties (Object)
16525 Optional arguments to modify the behavior of a Transaction.
16526 Members
16528 completion-mode: ActionCompletionMode (optional)
16529 Controls how jobs launched asynchronously by Actions will com‐
16530 plete or fail as a group. See ActionCompletionMode for details.
16531 Since
16533 2.5
16534 transaction (Command)
16536 Executes a number of transactionable QMP commands atomically. If any
16537 operation fails, then the entire set of actions will be abandoned and
16538 the appropriate error returned.
16539 For external snapshots, the dictionary contains the device, the file to
16541 use for the new snapshot, and the format. The default format, if not
16542 specified, is qcow2.
16543 Each new snapshot defaults to being created by QEMU (wiping any con‐
16545 tents if the file already exists), but it is also possible to reuse an
16546 externally-created file. In the latter case, you should ensure that
16547 the new image file has the same contents as the current one; QEMU can‐
16548 not perform any meaningful check. Typically this is achieved by using
16549 the current image file as the backing file for the new image.
16550 On failure, the original disks pre-snapshot attempt will be used.
16552 For internal snapshots, the dictionary contains the device and the
16554 snapshot's name. If an internal snapshot matching name already exists,
16555 the request will be rejected. Only some image formats support it, for
16556 example, qcow2, and rbd,
16557 On failure, qemu will try delete the newly created internal snapshot in
16559 the transaction. When an I/O error occurs during deletion, the user
16560 needs to fix it later with qemu-img or other command.
16561 Arguments
16563 actions: array of TransactionAction
16564 List of TransactionAction; information needed for the respective
16565 operations.
16566 properties: TransactionProperties (optional)
16568 structure of additional options to control the execution of the
16569 transaction. See TransactionProperties for additional detail.
16570 Returns
16572 nothing on success
16573 Errors depend on the operations of the transaction
16575 Note
16577 The transaction aborts on the first failure. Therefore, there will be
16578 information on only one failed operation returned in an error condi‐
16579 tion, and subsequent actions will not have been attempted.
16580 Since
16582 1.1
16583 Example
16585 -> { "execute": "transaction",
16586 "arguments": { "actions": [
16587 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
16588 "snapshot-file": "/some/place/my-image",
16589 "format": "qcow2" } },
16590 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
16591 "snapshot-file": "/some/place/my-image2",
16592 "snapshot-node-name": "node3432",
16593 "mode": "existing",
16594 "format": "qcow2" } },
16595 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
16596 "snapshot-file": "/some/place/my-image2",
16597 "mode": "existing",
16598 "format": "qcow2" } },
16599 { "type": "blockdev-snapshot-internal-sync", "data" : {
16600 "device": "ide-hd2",
16601 "name": "snapshot0" } } ] } }
16602 <- { "return": {} }
16603
16605 TraceEventState (Enum)
16606 State of a tracing event.
16607 Values
16609 unavailable
16610 The event is statically disabled.
16611 disabled
16613 The event is dynamically disabled.
16614 enabled
16616 The event is dynamically enabled.
16617 Since
16619 2.2
16620 TraceEventInfo (Object)
16622 Information of a tracing event.
16623 Members
16625 name: string
16626 Event name.
16627 state: TraceEventState
16629 Tracing state.
16630 vcpu: boolean
16632 Whether this is a per-vCPU event (since 2.7).
16633 An event is per-vCPU if it has the "vcpu" property in the
16634 "trace-events" files.
16635 Since
16637 2.2
16638 trace-event-get-state (Command)
16640 Query the state of events.
16641 Arguments
16643 name: string
16644 Event name pattern (case-sensitive glob).
16645 vcpu: int (optional)
16647 The vCPU to query (any by default; since 2.7).
16648 Returns
16650 a list of TraceEventInfo for the matching events
16651 An event is returned if:
16653 • its name matches the name pattern, and
16655 • if vcpu is given, the event has the "vcpu" property.
16657 Therefore, if vcpu is given, the operation will only match per-vCPU
16659 events, returning their state on the specified vCPU. Special case: if
16660 name is an exact match, vcpu is given and the event does not have the
16661 "vcpu" property, an error is returned.
16662 Since
16664 2.2
16665 Example
16667 -> { "execute": "trace-event-get-state",
16668 "arguments": { "name": "qemu_memalign" } }
16669 <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }
16670 trace-event-set-state (Command)
16672 Set the dynamic tracing state of events.
16673 Arguments
16675 name: string
16676 Event name pattern (case-sensitive glob).
16677 enable: boolean
16679 Whether to enable tracing.
16680 ignore-unavailable: boolean (optional)
16682 Do not match unavailable events with name.
16683 vcpu: int (optional)
16685 The vCPU to act upon (all by default; since 2.7).
16686 An event's state is modified if: - its name matches the name pattern,
16687 and - if vcpu is given, the event has the "vcpu" property.
16688 Therefore, if vcpu is given, the operation will only match per-vCPU
16690 events, setting their state on the specified vCPU. Special case: if
16691 name is an exact match, vcpu is given and the event does not have the
16692 "vcpu" property, an error is returned.
16693 Since
16695 2.2
16696 Example
16698 -> { "execute": "trace-event-set-state",
16699 "arguments": { "name": "qemu_memalign", "enable": true } }
16700 <- { "return": {} }
16701
16703 CompatPolicyInput (Enum)
16704 Policy for handling "funny" input.
16705 Values
16707 accept Accept silently
16708 reject Reject with an error
16710 crash abort() the process
16712 Since
16714 6.0
16715 CompatPolicyOutput (Enum)
16717 Policy for handling "funny" output.
16718 Values
16720 accept Pass on unchanged
16721 hide Filter out
16723 Since
16725 6.0
16726 CompatPolicy (Object)
16728 Policy for handling deprecated management interfaces.
16729 This is intended for testing users of the management interfaces.
16731 Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
16733 with feature 'deprecated'. We may want to extend it to cover semantic
16734 aspects and CLI.
16735 Limitation: deprecated-output policy hide is not implemented for enu‐
16737 meration values. They behave the same as with policy accept.
16738 Members
16740 deprecated-input: CompatPolicyInput (optional)
16741 how to handle deprecated input (default 'accept')
16742 deprecated-output: CompatPolicyOutput (optional)
16744 how to handle deprecated output (default 'accept')
16745 unstable-input: CompatPolicyInput (optional)
16747 how to handle unstable input (default 'accept') (since 6.2)
16748 unstable-output: CompatPolicyOutput (optional)
16750 how to handle unstable output (default 'accept') (since 6.2)
16751 Since
16753 6.0
16754
16756 qmp_capabilities (Command)
16757 Enable QMP capabilities.
16758 Arguments:
16760 Arguments
16762 enable: array of QMPCapability (optional)
16763 An optional list of QMPCapability values to enable. The client
16764 must not enable any capability that is not mentioned in the QMP
16765 greeting message. If the field is not provided, it means no QMP
16766 capabilities will be enabled. (since 2.12)
16767 Example
16769 -> { "execute": "qmp_capabilities",
16770 "arguments": { "enable": [ "oob" ] } }
16771 <- { "return": {} }
16772 Notes
16774 This command is valid exactly when first connecting: it must be issued
16775 before any other command will be accepted, and will fail once the moni‐
16776 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
16777 The QMP client needs to explicitly enable QMP capabilities, otherwise
16779 all the QMP capabilities will be turned off by default.
16780 Since
16782 0.13
16783 QMPCapability (Enum)
16785 Enumeration of capabilities to be advertised during initial client con‐
16786 nection, used for agreeing on particular QMP extension behaviors.
16787 Values
16789 oob QMP ability to support out-of-band requests. (Please refer to
16790 qmp-spec.txt for more information on OOB)
16791 Since
16793 2.12
16794 VersionTriple (Object)
16796 A three-part version number.
16797 Members
16799 major: int
16800 The major version number.
16801 minor: int
16803 The minor version number.
16804 micro: int
16806 The micro version number.
16807 Since
16809 2.4
16810 VersionInfo (Object)
16812 A description of QEMU's version.
16813 Members
16815 qemu: VersionTriple
16816 The version of QEMU. By current convention, a micro version of
16817 50 signifies a development branch. A micro version greater than
16818 or equal to 90 signifies a release candidate for the next minor
16819 version. A micro version of less than 50 signifies a stable re‐
16820 lease.
16821 package: string
16823 QEMU will always set this field to an empty string. Downstream
16824 versions of QEMU should set this to a non-empty string. The ex‐
16825 act format depends on the downstream however it highly recom‐
16826 mended that a unique name is used.
16827 Since
16829 0.14
16830 query-version (Command)
16832 Returns the current version of QEMU.
16833 Returns
16835 A VersionInfo object describing the current version of QEMU.
16836 Since
16838 0.14
16839 Example
16841 -> { "execute": "query-version" }
16842 <- {
16843 "return":{
16844 "qemu":{
16845 "major":0,
16846 "minor":11,
16847 "micro":5
16848 },
16849 "package":""
16850 }
16851 }
16852 CommandInfo (Object)
16854 Information about a QMP command
16855 Members
16857 name: string
16858 The command name
16859 Since
16861 0.14
16862 query-commands (Command)
16864 Return a list of supported QMP commands by this server
16865 Returns
16867 A list of CommandInfo for all supported commands
16868 Since
16870 0.14
16871 Example
16873 -> { "execute": "query-commands" }
16874 <- {
16875 "return":[
16876 {
16877 "name":"query-balloon"
16878 },
16879 {
16880 "name":"system_powerdown"
16881 }
16882 ]
16883 }
16884 Note
16886 This example has been shortened as the real response is too long.
16887 quit (Command)
16889 This command will cause the QEMU process to exit gracefully. While ev‐
16890 ery attempt is made to send the QMP response before terminating, this
16891 is not guaranteed. When using this interface, a premature EOF would
16892 not be unexpected.
16893 Since
16895 0.14
16896 Example
16898 -> { "execute": "quit" }
16899 <- { "return": {} }
16900 MonitorMode (Enum)
16902 An enumeration of monitor modes.
16903 Values
16905 readline
16906 HMP monitor (human-oriented command line interface)
16907 control
16909 QMP monitor (JSON-based machine interface)
16910 Since
16912 5.0
16913 MonitorOptions (Object)
16915 Options to be used for adding a new monitor.
16916 Members
16918 id: string (optional)
16919 Name of the monitor
16920 mode: MonitorMode (optional)
16922 Selects the monitor mode (default: readline in the system
16924 emulator, control in qemu-storage-daemon)
16925 pretty: boolean (optional)
16927 Enables pretty printing (QMP only)
16928 chardev: string
16930 Name of a character device to expose the monitor on
16931 Since
16933 5.0
16934
16936 query-qmp-schema (Command)
16937 Command query-qmp-schema exposes the QMP wire ABI as an array of
16938 SchemaInfo. This lets QMP clients figure out what commands and events
16939 are available in this QEMU, and their parameters and results.
16940 However, the SchemaInfo can't reflect all the rules and restrictions
16942 that apply to QMP. It's interface introspection (figuring out what's
16943 there), not interface specification. The specification is in the QAPI
16944 schema.
16945 Furthermore, while we strive to keep the QMP wire format backwards-com‐
16947 patible across qemu versions, the introspection output is not guaran‐
16948 teed to have the same stability. For example, one version of qemu may
16949 list an object member as an optional non-variant, while another lists
16950 the same member only through the object's variants; or the type of a
16951 member may change from a generic string into a specific enum or from
16952 one specific type into an alternate that includes the original type
16953 alongside something else.
16954 Returns
16956 array of SchemaInfo, where each element describes an entity in the ABI:
16957 command, event, type, ...
16958 The order of the various SchemaInfo is unspecified; however, all names
16960 are guaranteed to be unique (no name will be duplicated with different
16961 meta-types).
16962 Note
16964 the QAPI schema is also used to help define internal interfaces, by
16965 defining QAPI types. These are not part of the QMP wire ABI, and
16966 therefore not returned by this command.
16967 Since
16969 2.5
16970 SchemaMetaType (Enum)
16972 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
16973 Values
16975 builtin
16976 a predefined type such as 'int' or 'bool'.
16977 enum an enumeration type
16979 array an array type
16981 object an object type (struct or union)
16983 alternate
16985 an alternate type
16986 command
16988 a QMP command
16989 event a QMP event
16991 Since
16993 2.5
16994 SchemaInfo (Object)
16996 Members
16997 name: string
16998 the entity's name, inherited from base. The SchemaInfo is al‐
16999 ways referenced by this name. Commands and events have the name
17000 defined in the QAPI schema. Unlike command and event names,
17001 type names are not part of the wire ABI. Consequently, type
17002 names are meaningless strings here, although they are still
17003 guaranteed unique regardless of meta-type.
17004 meta-type: SchemaMetaType
17006 the entity's meta type, inherited from base.
17007 features: array of string (optional)
17009 names of features associated with the entity, in no particular
17010 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
17011 the rest)
17012 The members of SchemaInfoBuiltin when meta-type is "builtin"
17014 The members of SchemaInfoEnum when meta-type is "enum"
17016 The members of SchemaInfoArray when meta-type is "array"
17018 The members of SchemaInfoObject when meta-type is "object"
17020 The members of SchemaInfoAlternate when meta-type is "alternate"
17022 The members of SchemaInfoCommand when meta-type is "command"
17024 The members of SchemaInfoEvent when meta-type is "event"
17026 Additional members depend on the value of meta-type.
17027 Since
17029 2.5
17030 SchemaInfoBuiltin (Object)
17032 Additional SchemaInfo members for meta-type 'builtin'.
17033 Members
17035 json-type: JSONType
17036 the JSON type used for this type on the wire.
17037 Since
17039 2.5
17040 JSONType (Enum)
17042 The four primitive and two structured types according to RFC 8259 sec‐
17043 tion 1, plus 'int' (split off 'number'), plus the obvious top type
17044 'value'.
17045 Values
17047 string Not documented
17048 number Not documented
17050 int Not documented
17052 boolean
17054 Not documented
17055 null Not documented
17057 object Not documented
17059 array Not documented
17061 value Not documented
17063 Since
17065 2.5
17066 SchemaInfoEnum (Object)
17068 Additional SchemaInfo members for meta-type 'enum'.
17069 Members
17071 members: array of SchemaInfoEnumMember
17072 the enum type's members, in no particular order (since 6.2).
17073 values: array of string
17075 the enumeration type's member names, in no particular order.
17076 Redundant with members. Just for backward compatibility.
17077 Features
17079 deprecated
17080 Member values is deprecated. Use members instead.
17081 Values of this type are JSON string on the wire.
17082 Since
17084 2.5
17085 SchemaInfoEnumMember (Object)
17087 An object member.
17088 Members
17090 name: string
17091 the member's name, as defined in the QAPI schema.
17092 features: array of string (optional)
17094 names of features associated with the member, in no particular
17095 order.
17096 Since
17098 6.2
17099 SchemaInfoArray (Object)
17101 Additional SchemaInfo members for meta-type 'array'.
17102 Members
17104 element-type: string
17105 the array type's element type.
17106 Values of this type are JSON array on the wire.
17107 Since
17109 2.5
17110 SchemaInfoObject (Object)
17112 Additional SchemaInfo members for meta-type 'object'.
17113 Members
17115 members: array of SchemaInfoObjectMember
17116 the object type's (non-variant) members, in no particular order.
17117 tag: string (optional)
17119 the name of the member serving as type tag. An element of mem‐
17120 bers with this name must exist.
17121 variants: array of SchemaInfoObjectVariant (optional)
17123 variant members, i.e. additional members that depend on the type
17124 tag's value. Present exactly when tag is present. The variants
17125 are in no particular order, and may even differ from the order
17126 of the values of the enum type of the tag.
17127 Values of this type are JSON object on the wire.
17128 Since
17130 2.5
17131 SchemaInfoObjectMember (Object)
17133 An object member.
17134 Members
17136 name: string
17137 the member's name, as defined in the QAPI schema.
17138 type: string
17140 the name of the member's type.
17141 default: value (optional)
17143 default when used as command parameter. If absent, the parame‐
17144 ter is mandatory. If present, the value must be null. The pa‐
17145 rameter is optional, and behavior when it's missing is not spec‐
17146 ified here. Future extension: if present and non-null, the pa‐
17147 rameter is optional, and defaults to this value.
17148 features: array of string (optional)
17150 names of features associated with the member, in no particular
17151 order. (since 5.0)
17152 Since
17154 2.5
17155 SchemaInfoObjectVariant (Object)
17157 The variant members for a value of the type tag.
17158 Members
17160 case: string
17161 a value of the type tag.
17162 type: string
17164 the name of the object type that provides the variant members
17165 when the type tag has value case.
17166 Since
17168 2.5
17169 SchemaInfoAlternate (Object)
17171 Additional SchemaInfo members for meta-type 'alternate'.
17172 Members
17174 members: array of SchemaInfoAlternateMember
17175 the alternate type's members, in no particular order. The mem‐
17176 bers' wire encoding is distinct, see docs/de‐
17177 vel/qapi-code-gen.txt section Alternate types.
17178 On the wire, this can be any of the members.
17179 Since
17181 2.5
17182 SchemaInfoAlternateMember (Object)
17184 An alternate member.
17185 Members
17187 type: string
17188 the name of the member's type.
17189 Since
17191 2.5
17192 SchemaInfoCommand (Object)
17194 Additional SchemaInfo members for meta-type 'command'.
17195 Members
17197 arg-type: string
17198 the name of the object type that provides the command's parame‐
17199 ters.
17200 ret-type: string
17202 the name of the command's result type.
17203 allow-oob: boolean (optional)
17205 whether the command allows out-of-band execution, defaults to
17206 false (Since: 2.12)
17207 TODO
17209 success-response (currently irrelevant, because it's QGA, not QMP)
17210 Since
17212 2.5
17213 SchemaInfoEvent (Object)
17215 Additional SchemaInfo members for meta-type 'event'.
17216 Members
17218 arg-type: string
17219 the name of the object type that provides the event's parame‐
17220 ters.
17221 Since
17223 2.5
17224
17226 ObjectPropertyInfo (Object)
17227 Members
17228 name: string
17229 the name of the property
17230 type: string
17232 the type of the property. This will typically come in one of
17233 four forms:
17234 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
17236 ble'. These types are mapped to the appropriate JSON type.
17237 2. A child type in the form 'child<subtype>' where subtype is a
17239 qdev device type name. Child properties create the composi‐
17240 tion tree.
17241 3. A link type in the form 'link<subtype>' where subtype is a
17243 qdev device type name. Link properties form the device model
17244 graph.
17245 description: string (optional)
17247 if specified, the description of the property.
17248 default-value: value (optional)
17250 the default value, if any (since 5.0)
17251 Since
17253 1.2
17254 qom-list (Command)
17256 This command will list any properties of a object given a path in the
17257 object model.
17258 Arguments
17260 path: string
17261 the path within the object model. See qom-get for a description
17262 of this parameter.
17263 Returns
17265 a list of ObjectPropertyInfo that describe the properties of the ob‐
17266 ject.
17267 Since
17269 1.2
17270 Example
17272 -> { "execute": "qom-list",
17273 "arguments": { "path": "/chardevs" } }
17274 <- { "return": [ { "name": "type", "type": "string" },
17275 { "name": "parallel0", "type": "child<chardev-vc>" },
17276 { "name": "serial0", "type": "child<chardev-vc>" },
17277 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
17278 qom-get (Command)
17280 This command will get a property from a object model path and return
17281 the value.
17282 Arguments
17284 path: string
17285 The path within the object model. There are two forms of sup‐
17286 ported paths--absolute and partial paths.
17287 Absolute paths are derived from the root object and can follow
17289 child<> or link<> properties. Since they can follow link<>
17290 properties, they can be arbitrarily long. Absolute paths look
17291 like absolute filenames and are prefixed with a leading slash.
17292 Partial paths look like relative filenames. They do not begin
17294 with a prefix. The matching rules for partial paths are subtle
17295 but designed to make specifying objects easy. At each level of
17296 the composition tree, the partial path is matched as an absolute
17297 path. The first match is not returned. At least two matches
17298 are searched for. A successful result is only returned if only
17299 one match is found. If more than one match is found, a flag is
17300 return to indicate that the match was ambiguous.
17301 property: string
17303 The property name to read
17304 Returns
17306 The property value. The type depends on the property type. child<> and
17307 link<> properties are returned as #str pathnames. All integer property
17308 types (u8, u16, etc) are returned as #int.
17309 Since
17311 1.2
17312 Example
17314 1. Use absolute path
17315 -> { "execute": "qom-get",
17317 "arguments": { "path": "/machine/unattached/device[0]",
17318 "property": "hotplugged" } }
17319 <- { "return": false }
17320 2. Use partial path
17322 -> { "execute": "qom-get",
17324 "arguments": { "path": "unattached/sysbus",
17325 "property": "type" } }
17326 <- { "return": "System" }
17327 qom-set (Command)
17329 This command will set a property from a object model path.
17330 Arguments
17332 path: string
17333 see qom-get for a description of this parameter
17334 property: string
17336 the property name to set
17337 value: value
17339 a value who's type is appropriate for the property type. See
17340 qom-get for a description of type mapping.
17341 Since
17343 1.2
17344 Example
17346 -> { "execute": "qom-set",
17347 "arguments": { "path": "/machine",
17348 "property": "graphics",
17349 "value": false } }
17350 <- { "return": {} }
17351 ObjectTypeInfo (Object)
17353 This structure describes a search result from qom-list-types
17354 Members
17356 name: string
17357 the type name found in the search
17358 abstract: boolean (optional)
17360 the type is abstract and can't be directly instantiated. Omit‐
17361 ted if false. (since 2.10)
17362 parent: string (optional)
17364 Name of parent type, if any (since 2.10)
17365 Since
17367 1.1
17368 qom-list-types (Command)
17370 This command will return a list of types given search parameters
17371 Arguments
17373 implements: string (optional)
17374 if specified, only return types that implement this type name
17375 abstract: boolean (optional)
17377 if true, include abstract types in the results
17378 Returns
17380 a list of ObjectTypeInfo or an empty list if no results are found
17381 Since
17383 1.1
17384 qom-list-properties (Command)
17386 List properties associated with a QOM object.
17387 Arguments
17389 typename: string
17390 the type name of an object
17391 Note
17393 objects can create properties at runtime, for example to describe links
17394 between different devices and/or objects. These properties are not in‐
17395 cluded in the output of this command.
17396 Returns
17398 a list of ObjectPropertyInfo describing object properties
17399 Since
17401 2.12
17402 CanHostSocketcanProperties (Object)
17404 Properties for can-host-socketcan objects.
17405 Members
17407 if: string
17408 interface name of the host system CAN bus to connect to
17409 canbus: string
17411 object ID of the can-bus object to connect to the host interface
17412 Since
17414 2.12
17415 ColoCompareProperties (Object)
17417 Properties for colo-compare objects.
17418 Members
17420 primary_in: string
17421 name of the character device backend to use for the primary in‐
17422 put (incoming packets are redirected to outdev)
17423 secondary_in: string
17425 name of the character device backend to use for secondary input
17426 (incoming packets are only compared to the input on primary_in
17427 and then dropped)
17428 outdev: string
17430 name of the character device backend to use for output
17431 iothread: string
17433 name of the iothread to run in
17434 notify_dev: string (optional)
17436 name of the character device backend to be used to communicate
17437 with the remote colo-frame (only for Xen COLO)
17438 compare_timeout: int (optional)
17440 the maximum time to hold a packet from primary_in for comparison
17441 with an incoming packet on secondary_in in milliseconds (de‐
17442 fault: 3000)
17443 expired_scan_cycle: int (optional)
17445 the interval at which colo-compare checks whether packets from
17446 primary have timed out, in milliseconds (default: 3000)
17447 max_queue_size: int (optional)
17449 the maximum number of packets to keep in the queue for comparing
17450 with incoming packets from secondary_in. If the queue is full
17451 and additional packets are received, the additional packets are
17452 dropped. (default: 1024)
17453 vnet_hdr_support: boolean (optional)
17455 if true, vnet header support is enabled (default: false)
17456 Since
17458 2.8
17459 CryptodevBackendProperties (Object)
17461 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
17462 Members
17464 queues: int (optional)
17465 the number of queues for the cryptodev backend. Ignored for
17466 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
17467 (default: 1)
17468 Since
17470 2.8
17471 CryptodevVhostUserProperties (Object)
17473 Properties for cryptodev-vhost-user objects.
17474 Members
17476 chardev: string
17477 the name of a Unix domain socket character device that connects
17478 to the vhost-user server
17479 The members of CryptodevBackendProperties
17481 Since
17483 2.12
17484 DBusVMStateProperties (Object)
17486 Properties for dbus-vmstate objects.
17487 Members
17489 addr: string
17490 the name of the DBus bus to connect to
17491 id-list: string (optional)
17493 a comma separated list of DBus IDs of helpers whose data should
17494 be included in the VM state on migration
17495 Since
17497 5.0
17498 NetfilterInsert (Enum)
17500 Indicates where to insert a netfilter relative to a given other filter.
17501 Values
17503 before insert before the specified filter
17504 behind insert behind the specified filter
17506 Since
17508 5.0
17509 NetfilterProperties (Object)
17511 Properties for objects of classes derived from netfilter.
17512 Members
17514 netdev: string
17515 id of the network device backend to filter
17516 queue: NetFilterDirection (optional)
17518 indicates which queue(s) to filter (default: all)
17519 status: string (optional)
17521 indicates whether the filter is enabled ("on") or disabled
17522 ("off") (default: "on")
17523 position: string (optional)
17525 specifies where the filter should be inserted in the filter
17526 list. "head" means the filter is inserted at the head of the
17527 filter list, before any existing filters. "tail" means the fil‐
17528 ter is inserted at the tail of the filter list, behind any ex‐
17529 isting filters (default). "id=<id>" means the filter is in‐
17530 serted before or behind the filter specified by <id>, depending
17531 on the insert property. (default: "tail")
17532 insert: NetfilterInsert (optional)
17534 where to insert the filter relative to the filter given in posi‐
17535 tion. Ignored if position is "head" or "tail". (default: be‐
17536 hind)
17537 Since
17539 2.5
17540 FilterBufferProperties (Object)
17542 Properties for filter-buffer objects.
17543 Members
17545 interval: int
17546 a non-zero interval in microseconds. All packets arriving in
17547 the given interval are delayed until the end of the interval.
17548 The members of NetfilterProperties
17550 Since
17552 2.5
17553 FilterDumpProperties (Object)
17555 Properties for filter-dump objects.
17556 Members
17558 file: string
17559 the filename where the dumped packets should be stored
17560 maxlen: int (optional)
17562 maximum number of bytes in a packet that are stored (default:
17563 65536)
17564 The members of NetfilterProperties
17566 Since
17568 2.5
17569 FilterMirrorProperties (Object)
17571 Properties for filter-mirror objects.
17572 Members
17574 outdev: string
17575 the name of a character device backend to which all incoming
17576 packets are mirrored
17577 vnet_hdr_support: boolean (optional)
17579 if true, vnet header support is enabled (default: false)
17580 The members of NetfilterProperties
17582 Since
17584 2.6
17585 FilterRedirectorProperties (Object)
17587 Properties for filter-redirector objects.
17588 At least one of indev or outdev must be present. If both are present,
17590 they must not refer to the same character device backend.
17591 Members
17593 indev: string (optional)
17594 the name of a character device backend from which packets are
17595 received and redirected to the filtered network device
17596 outdev: string (optional)
17598 the name of a character device backend to which all incoming
17599 packets are redirected
17600 vnet_hdr_support: boolean (optional)
17602 if true, vnet header support is enabled (default: false)
17603 The members of NetfilterProperties
17605 Since
17607 2.6
17608 FilterRewriterProperties (Object)
17610 Properties for filter-rewriter objects.
17611 Members
17613 vnet_hdr_support: boolean (optional)
17614 if true, vnet header support is enabled (default: false)
17615 The members of NetfilterProperties
17617 Since
17619 2.8
17620 InputBarrierProperties (Object)
17622 Properties for input-barrier objects.
17623 Members
17625 name: string
17626 the screen name as declared in the screens section of bar‐
17627 rier.conf
17628 server: string (optional)
17630 hostname of the Barrier server (default: "localhost")
17631 port: string (optional)
17633 TCP port of the Barrier server (default: "24800")
17634 x-origin: string (optional)
17636 x coordinate of the leftmost pixel on the guest screen (default:
17637 "0")
17638 y-origin: string (optional)
17640 y coordinate of the topmost pixel on the guest screen (default:
17641 "0")
17642 width: string (optional)
17644 the width of secondary screen in pixels (default: "1920")
17645 height: string (optional)
17647 the height of secondary screen in pixels (default: "1080")
17648 Since
17650 4.2
17651 InputLinuxProperties (Object)
17653 Properties for input-linux objects.
17654 Members
17656 evdev: string
17657 the path of the host evdev device to use
17658 grab_all: boolean (optional)
17660 if true, grab is toggled for all devices (e.g. both keyboard and
17661 mouse) instead of just one device (default: false)
17662 repeat: boolean (optional)
17664 enables auto-repeat events (default: false)
17665 grab-toggle: GrabToggleKeys (optional)
17667 the key or key combination that toggles device grab (default:
17668 ctrl-ctrl)
17669 Since
17671 2.6
17672 EventLoopBaseProperties (Object)
17674 Common properties for event loops
17675 Members
17677 aio-max-batch: int (optional)
17678 maximum number of requests in a batch for the AIO engine, 0
17679 means that the engine will use its default. (default: 0)
17680 thread-pool-min: int (optional)
17682 minimum number of threads reserved in the thread pool (de‐
17683 fault:0)
17684 thread-pool-max: int (optional)
17686 maximum number of threads the thread pool can contain (de‐
17687 fault:64)
17688 Since
17690 7.1
17691 IothreadProperties (Object)
17693 Properties for iothread objects.
17694 Members
17696 poll-max-ns: int (optional)
17697 the maximum number of nanoseconds to busy wait for events. 0
17698 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
17699 erwise)
17700 poll-grow: int (optional)
17702 the multiplier used to increase the polling time when the algo‐
17703 rithm detects it is missing events due to not polling long
17704 enough. 0 selects a default behaviour (default: 0)
17705 poll-shrink: int (optional)
17707 the divisor used to decrease the polling time when the algorithm
17708 detects it is spending too long polling without encountering
17709 events. 0 selects a default behaviour (default: 0)
17710 The members of EventLoopBaseProperties
17712 The aio-max-batch option is available since 6.1.
17713 Since
17715 2.0
17716 MainLoopProperties (Object)
17718 Properties for the main-loop object.
17719 Members
17721 The members of EventLoopBaseProperties
17722 Since
17724 7.1
17725 MemoryBackendProperties (Object)
17727 Properties for objects of classes derived from memory-backend.
17728 Members
17730 merge: boolean (optional)
17731 if true, mark the memory as mergeable (default depends on the
17732 machine type)
17733 dump: boolean (optional)
17735 if true, include the memory in core dumps (default depends on
17736 the machine type)
17737 host-nodes: array of int (optional)
17739 the list of NUMA host nodes to bind the memory to
17740 policy: HostMemPolicy (optional)
17742 the NUMA policy (default: 'default')
17743 prealloc: boolean (optional)
17745 if true, preallocate memory (default: false)
17746 prealloc-threads: int (optional)
17748 number of CPU threads to use for prealloc (default: 1)
17749 prealloc-context: string (optional)
17751 thread context to use for creation of preallocation threads (de‐
17752 fault: none) (since 7.2)
17753 share: boolean (optional)
17755 if false, the memory is private to QEMU; if true, it is shared
17756 (default: false)
17757 reserve: boolean (optional)
17759 if true, reserve swap space (or huge pages) if applicable (de‐
17760 fault: true) (since 6.1)
17761 size: int
17763 size of the memory region in bytes
17764 x-use-canonical-path-for-ramblock-id: boolean (optional)
17766 if true, the canonical path is used for ramblock-id. Disable
17767 this for 4.0 machine types or older to allow migration with
17768 newer QEMU versions. (default: false generally, but true for
17769 machine types <= 4.0)
17770 Note
17772 prealloc=true and reserve=false cannot be set at the same time. With
17773 reserve=true, the behavior depends on the operating system: for exam‐
17774 ple, Linux will not reserve swap space for shared file mappings -- "not
17775 applicable". In contrast, reserve=false will bail out if it cannot be
17776 configured accordingly.
17777 Since
17779 2.1
17780 MemoryBackendFileProperties (Object)
17782 Properties for memory-backend-file objects.
17783 Members
17785 align: int (optional)
17786 the base address alignment when QEMU mmap(2)s mem-path. Some
17787 backend stores specified by mem-path require an alignment dif‐
17788 ferent than the default one used by QEMU, e.g. the device DAX
17789 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
17790 users can specify the required alignment via this option. 0 se‐
17791 lects a default alignment (currently the page size). (default:
17792 0)
17793 discard-data: boolean (optional)
17795 if true, the file contents can be destroyed when QEMU exits, to
17796 avoid unnecessarily flushing data to the backing file. Note that
17797 discard-data is only an optimization, and QEMU might not discard
17798 file contents if it aborts unexpectedly or is terminated using
17799 SIGKILL. (default: false)
17800 mem-path: string
17802 the path to either a shared memory or huge page filesystem mount
17803 pmem: boolean (optional) (If: CONFIG_LIBPMEM)
17805 specifies whether the backing file specified by mem-path is in
17806 host persistent memory that can be accessed using the SNIA NVM
17807 programming model (e.g. Intel NVDIMM).
17808 readonly: boolean (optional)
17810 if true, the backing file is opened read-only; if false, it is
17811 opened read-write. (default: false)
17812 The members of MemoryBackendProperties
17814 Since
17816 2.1
17817 MemoryBackendMemfdProperties (Object)
17819 Properties for memory-backend-memfd objects.
17820 The share boolean option is true by default with memfd.
17822 Members
17824 hugetlb: boolean (optional)
17825 if true, the file to be created resides in the hugetlbfs
17826 filesystem (default: false)
17827 hugetlbsize: int (optional)
17829 the hugetlb page size on systems that support multiple hugetlb
17830 page sizes (it must be a power of 2 value supported by the sys‐
17831 tem). 0 selects a default page size. This option is ignored if
17832 hugetlb is false. (default: 0)
17833 seal: boolean (optional)
17835 if true, create a sealed-file, which will block further resizing
17836 of the memory (default: true)
17837 The members of MemoryBackendProperties
17839 Since
17841 2.12
17842 MemoryBackendEpcProperties (Object)
17844 Properties for memory-backend-epc objects.
17845 The share boolean option is true by default with epc
17847 The merge boolean option is false by default with epc
17849 The dump boolean option is false by default with epc
17851 Members
17853 The members of MemoryBackendProperties
17854 Since
17856 6.2
17857 PrManagerHelperProperties (Object)
17859 Properties for pr-manager-helper objects.
17860 Members
17862 path: string
17863 the path to a Unix domain socket for connecting to the external
17864 helper
17865 Since
17867 2.11
17868 QtestProperties (Object)
17870 Properties for qtest objects.
17871 Members
17873 chardev: string
17874 the chardev to be used to receive qtest commands on.
17875 log: string (optional)
17877 the path to a log file
17878 Since
17880 6.0
17881 RemoteObjectProperties (Object)
17883 Properties for x-remote-object objects.
17884 Members
17886 fd: string
17887 file descriptor name previously passed via 'getfd' command
17888 devid: string
17890 the id of the device to be associated with the file descriptor
17891 Since
17893 6.0
17894 VfioUserServerProperties (Object)
17896 Properties for x-vfio-user-server objects.
17897 Members
17899 socket: SocketAddress
17900 socket to be used by the libvfio-user library
17901 device: string
17903 the ID of the device to be emulated at the server
17904 Since
17906 7.1
17907 RngProperties (Object)
17909 Properties for objects of classes derived from rng.
17910 Members
17912 opened: boolean (optional)
17913 if true, the device is opened immediately when applying this op‐
17914 tion and will probably fail when processing the next option.
17915 Don't use; only provided for compatibility. (default: false)
17916 Features
17918 deprecated
17919 Member opened is deprecated. Setting true doesn't make sense,
17920 and false is already the default.
17921 Since
17923 1.3
17924 RngEgdProperties (Object)
17926 Properties for rng-egd objects.
17927 Members
17929 chardev: string
17930 the name of a character device backend that provides the connec‐
17931 tion to the RNG daemon
17932 The members of RngProperties
17934 Since
17936 1.3
17937 RngRandomProperties (Object)
17939 Properties for rng-random objects.
17940 Members
17942 filename: string (optional)
17943 the filename of the device on the host to obtain entropy from
17944 (default: "/dev/urandom")
17945 The members of RngProperties
17947 Since
17949 1.3
17950 SevGuestProperties (Object)
17952 Properties for sev-guest objects.
17953 Members
17955 sev-device: string (optional)
17956 SEV device to use (default: "/dev/sev")
17957 dh-cert-file: string (optional)
17959 guest owners DH certificate (encoded with base64)
17960 session-file: string (optional)
17962 guest owners session parameters (encoded with base64)
17963 policy: int (optional)
17965 SEV policy value (default: 0x1)
17966 handle: int (optional)
17968 SEV firmware handle (default: 0)
17969 cbitpos: int (optional)
17971 C-bit location in page table entry (default: 0)
17972 reduced-phys-bits: int
17974 number of bits in physical addresses that become unavailable
17975 when SEV is enabled
17976 kernel-hashes: boolean (optional)
17978 if true, add hashes of kernel/initrd/cmdline to a designated
17979 guest firmware page for measured boot with -kernel (default:
17980 false) (since 6.2)
17981 Since
17983 2.12
17984 ThreadContextProperties (Object)
17986 Properties for thread context objects.
17987 Members
17989 cpu-affinity: array of int (optional)
17990 the list of host CPU numbers used as CPU affinity for all
17991 threads created in the thread context (default: QEMU main thread
17992 CPU affinity)
17993 node-affinity: array of int (optional)
17995 the list of host node numbers that will be resolved to a list of
17996 host CPU numbers used as CPU affinity. This is a shortcut for
17997 specifying the list of host CPU numbers belonging to the host
17998 nodes manually by setting cpu-affinity. (default: QEMU main
17999 thread affinity)
18000 Since
18002 7.2
18003 ObjectType (Enum)
18005 Values
18006 authz-list
18007 Not documented
18008 authz-listfile
18010 Not documented
18011 authz-pam
18013 Not documented
18014 authz-simple
18016 Not documented
18017 can-bus
18019 Not documented
18020 can-host-socketcan (If: CONFIG_LINUX)
18022 Not documented
18023 colo-compare
18025 Not documented
18026 cryptodev-backend
18028 Not documented
18029 cryptodev-backend-builtin
18031 Not documented
18032 cryptodev-backend-lkcf
18034 Not documented
18035 cryptodev-vhost-user (If: CONFIG_VHOST_CRYPTO)
18037 Not documented
18038 dbus-vmstate
18040 Not documented
18041 filter-buffer
18043 Not documented
18044 filter-dump
18046 Not documented
18047 filter-mirror
18049 Not documented
18050 filter-redirector
18052 Not documented
18053 filter-replay
18055 Not documented
18056 filter-rewriter
18058 Not documented
18059 input-barrier
18061 Not documented
18062 input-linux (If: CONFIG_LINUX)
18064 Not documented
18065 iothread
18067 Not documented
18068 main-loop
18070 Not documented
18071 memory-backend-epc (If: CONFIG_LINUX)
18073 Not documented
18074 memory-backend-file
18076 Not documented
18077 memory-backend-memfd (If: CONFIG_LINUX)
18079 Not documented
18080 memory-backend-ram
18082 Not documented
18083 pef-guest
18085 Not documented
18086 pr-manager-helper (If: CONFIG_LINUX)
18088 Not documented
18089 qtest Not documented
18091 rng-builtin
18093 Not documented
18094 rng-egd
18096 Not documented
18097 rng-random (If: CONFIG_POSIX)
18099 Not documented
18100 secret Not documented
18102 secret_keyring (If: CONFIG_SECRET_KEYRING)
18104 Not documented
18105 sev-guest
18107 Not documented
18108 thread-context
18110 Not documented
18111 s390-pv-guest
18113 Not documented
18114 throttle-group
18116 Not documented
18117 tls-creds-anon
18119 Not documented
18120 tls-creds-psk
18122 Not documented
18123 tls-creds-x509
18125 Not documented
18126 tls-cipher-suites
18128 Not documented
18129 x-remote-object
18131 Not documented
18132 x-vfio-user-server
18134 Not documented
18135 Features
18137 unstable
18138 Member x-remote-object is experimental.
18139 Since
18141 6.0
18142 ObjectOptions (Object)
18144 Describes the options of a user creatable QOM object.
18145 Members
18147 qom-type: ObjectType
18148 the class name for the object to be created
18149 id: string
18151 the name of the new object
18152 The members of AuthZListProperties when qom-type is "authz-list"
18154 The members of AuthZListFileProperties when qom-type is "authz-list‐
18156 file"
18157 The members of AuthZPAMProperties when qom-type is "authz-pam"
18159 The members of AuthZSimpleProperties when qom-type is "authz-simple"
18161 The members of CanHostSocketcanProperties when qom-type is
18163 "can-host-socketcan" (If: CONFIG_LINUX)
18164 The members of ColoCompareProperties when qom-type is "colo-compare"
18166 The members of CryptodevBackendProperties when qom-type is "cryp‐
18168 todev-backend"
18169 The members of CryptodevBackendProperties when qom-type is "cryp‐
18171 todev-backend-builtin"
18172 The members of CryptodevBackendProperties when qom-type is "cryp‐
18174 todev-backend-lkcf"
18175 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
18177 todev-vhost-user" (If: CONFIG_VHOST_CRYPTO)
18178 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
18180 The members of FilterBufferProperties when qom-type is "filter-buffer"
18182 The members of FilterDumpProperties when qom-type is "filter-dump"
18184 The members of FilterMirrorProperties when qom-type is "filter-mirror"
18186 The members of FilterRedirectorProperties when qom-type is "fil‐
18188 ter-redirector"
18189 The members of NetfilterProperties when qom-type is "filter-replay"
18191 The members of FilterRewriterProperties when qom-type is "fil‐
18193 ter-rewriter"
18194 The members of InputBarrierProperties when qom-type is "input-barrier"
18196 The members of InputLinuxProperties when qom-type is "input-linux" (If:
18198 CONFIG_LINUX)
18199 The members of IothreadProperties when qom-type is "iothread"
18201 The members of MainLoopProperties when qom-type is "main-loop"
18203 The members of MemoryBackendEpcProperties when qom-type is "mem‐
18205 ory-backend-epc" (If: CONFIG_LINUX)
18206 The members of MemoryBackendFileProperties when qom-type is "mem‐
18208 ory-backend-file"
18209 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
18211 ory-backend-memfd" (If: CONFIG_LINUX)
18212 The members of MemoryBackendProperties when qom-type is "memory-back‐
18214 end-ram"
18215 The members of PrManagerHelperProperties when qom-type is "pr-man‐
18217 ager-helper" (If: CONFIG_LINUX)
18218 The members of QtestProperties when qom-type is "qtest"
18220 The members of RngProperties when qom-type is "rng-builtin"
18222 The members of RngEgdProperties when qom-type is "rng-egd"
18224 The members of RngRandomProperties when qom-type is "rng-random" (If:
18226 CONFIG_POSIX)
18227 The members of SecretProperties when qom-type is "secret"
18229 The members of SecretKeyringProperties when qom-type is "se‐
18231 cret_keyring" (If: CONFIG_SECRET_KEYRING)
18232 The members of SevGuestProperties when qom-type is "sev-guest"
18234 The members of ThreadContextProperties when qom-type is "thread-con‐
18236 text"
18237 The members of ThrottleGroupProperties when qom-type is "throt‐
18239 tle-group"
18240 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
18242 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
18244 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
18246 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
18248 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
18250 ject"
18251 The members of VfioUserServerProperties when qom-type is
18253 "x-vfio-user-server"
18254 Since
18256 6.0
18257 object-add (Command)
18259 Create a QOM object.
18260 Arguments
18262 The members of ObjectOptions
18263 Returns
18265 Nothing on success Error if qom-type is not a valid class name
18266 Since
18268 2.0
18269 Example
18271 -> { "execute": "object-add",
18272 "arguments": { "qom-type": "rng-random", "id": "rng1",
18273 "filename": "/dev/hwrng" } }
18274 <- { "return": {} }
18275 object-del (Command)
18277 Remove a QOM object.
18278 Arguments
18280 id: string
18281 the name of the QOM object to remove
18282 Returns
18284 Nothing on success Error if id is not a valid id for a QOM object
18285 Since
18287 2.0
18288 Example
18290 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
18291 <- { "return": {} }
18292
18294 device-list-properties (Command)
18295 List properties associated with a device.
18296 Arguments
18298 typename: string
18299 the type name of a device
18300 Returns
18302 a list of ObjectPropertyInfo describing a devices properties
18303 Note
18305 objects can create properties at runtime, for example to describe links
18306 between different devices and/or objects. These properties are not in‐
18307 cluded in the output of this command.
18308 Since
18310 1.2
18311 device_add (Command)
18313 Add a device.
18314 Arguments
18316 driver: string
18317 the name of the new device's driver
18318 bus: string (optional)
18320 the device's parent bus (device tree path)
18321 id: string (optional)
18323 the device's ID, must be unique
18324 Features
18326 json-cli
18327 If present, the "-device" command line option supports JSON syn‐
18328 tax with a structure identical to the arguments of this command.
18329 json-cli-hotplug
18331 If present, the "-device" command line option supports JSON syn‐
18332 tax without the reference counting leak that broke hot-unplug
18333 Notes
18335 Additional arguments depend on the type.
18336 1. For detailed information about this command, please refer to the
18338 'docs/qdev-device-use.txt' file.
18339 2. It's possible to list device properties by running QEMU with the
18341 "-device DEVICE,help" command-line argument, where DEVICE is the de‐
18342 vice's name
18343 Example
18345 -> { "execute": "device_add",
18346 "arguments": { "driver": "e1000", "id": "net1",
18347 "bus": "pci.0",
18348 "mac": "52:54:00:12:34:56" } }
18349 <- { "return": {} }
18350 TODO
18352 This command effectively bypasses QAPI completely due to its "addi‐
18353 tional arguments" business. It shouldn't have been added to the schema
18354 in this form. It should be qapified properly, or replaced by a prop‐
18355 erly qapified command.
18356 Since
18358 0.13
18359 device_del (Command)
18361 Remove a device from a guest
18362 Arguments
18364 id: string
18365 the device's ID or QOM path
18366 Returns
18368 Nothing on success If id is not a valid device, DeviceNotFound
18369 Notes
18371 When this command completes, the device may not be removed from the
18372 guest. Hot removal is an operation that requires guest cooperation.
18373 This command merely requests that the guest begin the hot removal
18374 process. Completion of the device removal process is signaled with a
18375 DEVICE_DELETED event. Guest reset will automatically complete removal
18376 for all devices. If a guest-side error in the hot removal process is
18377 detected, the device will not be removed and a DEVICE_UNPLUG_GUEST_ER‐
18378 ROR event is sent. Some errors cannot be detected.
18379 Since
18381 0.14
18382 Example
18384 -> { "execute": "device_del",
18385 "arguments": { "id": "net1" } }
18386 <- { "return": {} }
18387 -> { "execute": "device_del",
18389 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
18390 <- { "return": {} }
18391 DEVICE_DELETED (Event)
18393 Emitted whenever the device removal completion is acknowledged by the
18394 guest. At this point, it's safe to reuse the specified device ID. De‐
18395 vice removal can be initiated by the guest or by HMP/QMP commands.
18396 Arguments
18398 device: string (optional)
18399 the device's ID if it has one
18400 path: string
18402 the device's QOM path
18403 Since
18405 1.5
18406 Example
18408 <- { "event": "DEVICE_DELETED",
18409 "data": { "device": "virtio-net-pci-0",
18410 "path": "/machine/peripheral/virtio-net-pci-0" },
18411 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
18412 DEVICE_UNPLUG_GUEST_ERROR (Event)
18414 Emitted when a device hot unplug fails due to a guest reported error.
18415 Arguments
18417 device: string (optional)
18418 the device's ID if it has one
18419 path: string
18421 the device's QOM path
18422 Since
18424 6.2
18425 Example
18427 <- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
18428 "data": { "device": "core1",
18429 "path": "/machine/peripheral/core1" },
18430 "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
18431
18433 SysEmuTarget (Enum)
18434 The comprehensive enumeration of QEMU system emulation ("softmmu") tar‐
18435 gets. Run "./configure --help" in the project root directory, and look
18436 for the *-softmmu targets near the "--target-list" option. The individ‐
18437 ual target constants are not documented here, for the time being.
18438 Values
18440 rx since 5.0
18441 avr since 5.1
18443 aarch64
18445 Not documented
18446 alpha Not documented
18448 arm Not documented
18450 cris Not documented
18452 hppa Not documented
18454 i386 Not documented
18456 loongarch64
18458 Not documented
18459 m68k Not documented
18461 microblaze
18463 Not documented
18464 microblazeel
18466 Not documented
18467 mips Not documented
18469 mips64 Not documented
18471 mips64el
18473 Not documented
18474 mipsel Not documented
18476 nios2 Not documented
18478 or1k Not documented
18480 ppc Not documented
18482 ppc64 Not documented
18484 riscv32
18486 Not documented
18487 riscv64
18489 Not documented
18490 s390x Not documented
18492 sh4 Not documented
18494 sh4eb Not documented
18496 sparc Not documented
18498 sparc64
18500 Not documented
18501 tricore
18503 Not documented
18504 x86_64 Not documented
18506 xtensa Not documented
18508 xtensaeb
18510 Not documented
18511 Notes
18513 The resulting QMP strings can be appended to the "qemu-system-" prefix
18514 to produce the corresponding QEMU executable name. This is true even
18515 for "qemu-system-x86_64".
18516 Since
18518 3.0
18519 CpuS390State (Enum)
18521 An enumeration of cpu states that can be assumed by a virtual S390 CPU
18522 Values
18524 uninitialized
18525 Not documented
18526 stopped
18528 Not documented
18529 check-stop
18531 Not documented
18532 operating
18534 Not documented
18535 load Not documented
18537 Since
18539 2.12
18540 CpuInfoS390 (Object)
18542 Additional information about a virtual S390 CPU
18543 Members
18545 cpu-state: CpuS390State
18546 the virtual CPU's state
18547 Since
18549 2.12
18550 CpuInfoFast (Object)
18552 Information about a virtual CPU
18553 Members
18555 cpu-index: int
18556 index of the virtual CPU
18557 qom-path: string
18559 path to the CPU object in the QOM tree
18560 thread-id: int
18562 ID of the underlying host thread
18563 props: CpuInstanceProperties (optional)
18565 properties describing to which node/socket/core/thread virtual
18566 CPU belongs to, provided if supported by board
18567 target: SysEmuTarget
18569 the QEMU system emulation target, which determines which addi‐
18570 tional fields will be listed (since 3.0)
18571 The members of CpuInfoS390 when target is "s390x"
18573 Since
18575 2.12
18576 query-cpus-fast (Command)
18578 Returns information about all virtual CPUs.
18579 Returns
18581 list of CpuInfoFast
18582 Since
18584 2.12
18585 Example
18587 -> { "execute": "query-cpus-fast" }
18588 <- { "return": [
18589 {
18590 "thread-id": 25627,
18591 "props": {
18592 "core-id": 0,
18593 "thread-id": 0,
18594 "socket-id": 0
18595 },
18596 "qom-path": "/machine/unattached/device[0]",
18597 "target":"x86_64",
18598 "cpu-index": 0
18599 },
18600 {
18601 "thread-id": 25628,
18602 "props": {
18603 "core-id": 0,
18604 "thread-id": 0,
18605 "socket-id": 1
18606 },
18607 "qom-path": "/machine/unattached/device[2]",
18608 "target":"x86_64",
18609 "cpu-index": 1
18610 }
18611 ]
18612 }
18613 MachineInfo (Object)
18615 Information describing a machine.
18616 Members
18618 name: string
18619 the name of the machine
18620 alias: string (optional)
18622 an alias for the machine name
18623 is-default: boolean (optional)
18625 whether the machine is default
18626 cpu-max: int
18628 maximum number of CPUs supported by the machine type (since 1.5)
18629 hotpluggable-cpus: boolean
18631 cpu hotplug via -device is supported (since 2.7)
18632 numa-mem-supported: boolean
18634 true if '-numa node,mem' option is supported by the machine type
18635 and false otherwise (since 4.1)
18636 deprecated: boolean
18638 if true, the machine type is deprecated and may be removed in
18639 future versions of QEMU according to the QEMU deprecation policy
18640 (since 4.1)
18641 default-cpu-type: string (optional)
18643 default CPU model typename if none is requested via the -cpu ar‐
18644 gument. (since 4.2)
18645 default-ram-id: string (optional)
18647 the default ID of initial RAM memory backend (since 5.2)
18648 Since
18650 1.2
18651 query-machines (Command)
18653 Return a list of supported machines
18654 Returns
18656 a list of MachineInfo
18657 Since
18659 1.2
18660 CurrentMachineParams (Object)
18662 Information describing the running machine parameters.
18663 Members
18665 wakeup-suspend-support: boolean
18666 true if the machine supports wake up from suspend
18667 Since
18669 4.0
18670 query-current-machine (Command)
18672 Return information on the current virtual machine.
18673 Returns
18675 CurrentMachineParams
18676 Since
18678 4.0
18679 TargetInfo (Object)
18681 Information describing the QEMU target.
18682 Members
18684 arch: SysEmuTarget
18685 the target architecture
18686 Since
18688 1.2
18689 query-target (Command)
18691 Return information about the target for this QEMU
18692 Returns
18694 TargetInfo
18695 Since
18697 1.2
18698 UuidInfo (Object)
18700 Guest UUID information (Universally Unique Identifier).
18701 Members
18703 UUID: string
18704 the UUID of the guest
18705 Since
18707 0.14
18708 Notes
18710 If no UUID was specified for the guest, a null UUID is returned.
18711 query-uuid (Command)
18713 Query the guest UUID information.
18714 Returns
18716 The UuidInfo for the guest
18717 Since
18719 0.14
18720 Example
18722 -> { "execute": "query-uuid" }
18723 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
18724 GuidInfo (Object)
18726 GUID information.
18727 Members
18729 guid: string
18730 the globally unique identifier
18731 Since
18733 2.9
18734 query-vm-generation-id (Command)
18736 Show Virtual Machine Generation ID
18737 Since
18739 2.9
18740 system_reset (Command)
18742 Performs a hard reset of a guest.
18743 Since
18745 0.14
18746 Example
18748 -> { "execute": "system_reset" }
18749 <- { "return": {} }
18750 system_powerdown (Command)
18752 Requests that a guest perform a powerdown operation.
18753 Since
18755 0.14
18756 Notes
18758 A guest may or may not respond to this command. This command returning
18759 does not indicate that a guest has accepted the request or that it has
18760 shut down. Many guests will respond to this command by prompting the
18761 user in some way.
18762 Example
18764 -> { "execute": "system_powerdown" }
18765 <- { "return": {} }
18766 system_wakeup (Command)
18768 Wake up guest from suspend. If the guest has wake-up from suspend sup‐
18769 port enabled (wakeup-suspend-support flag from query-current-machine),
18770 wake-up guest from suspend if the guest is in SUSPENDED state. Return
18771 an error otherwise.
18772 Since
18774 1.1
18775 Returns
18777 nothing.
18778 Note
18780 prior to 4.0, this command does nothing in case the guest isn't sus‐
18781 pended.
18782 Example
18784 -> { "execute": "system_wakeup" }
18785 <- { "return": {} }
18786 LostTickPolicy (Enum)
18788 Policy for handling lost ticks in timer devices. Ticks end up getting
18789 lost when, for example, the guest is paused.
18790 Values
18792 discard
18793 throw away the missed ticks and continue with future injection
18794 normally. The guest OS will see the timer jump ahead by a po‐
18795 tentially quite significant amount all at once, as if the inter‐
18796 vening chunk of time had simply not existed; needless to say,
18797 such a sudden jump can easily confuse a guest OS which is not
18798 specifically prepared to deal with it. Assuming the guest OS
18799 can deal correctly with the time jump, the time in the guest and
18800 in the host should now match.
18801 delay continue to deliver ticks at the normal rate. The guest OS will
18803 not notice anything is amiss, as from its point of view time
18804 will have continued to flow normally. The time in the guest
18805 should now be behind the time in the host by exactly the amount
18806 of time during which ticks have been missed.
18807 slew deliver ticks at a higher rate to catch up with the missed
18809 ticks. The guest OS will not notice anything is amiss, as from
18810 its point of view time will have continued to flow normally.
18811 Once the timer has managed to catch up with all the missing
18812 ticks, the time in the guest and in the host should match.
18813 Since
18815 2.0
18816 inject-nmi (Command)
18818 Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all
18819 CPUs (ppc64). The command fails when the guest doesn't support inject‐
18820 ing.
18821 Returns
18823 If successful, nothing
18824 Since
18826 0.14
18827 Note
18829 prior to 2.1, this command was only supported for x86 and s390 VMs
18830 Example
18832 -> { "execute": "inject-nmi" }
18833 <- { "return": {} }
18834 KvmInfo (Object)
18836 Information about support for KVM acceleration
18837 Members
18839 enabled: boolean
18840 true if KVM acceleration is active
18841 present: boolean
18843 true if KVM acceleration is built into this executable
18844 Since
18846 0.14
18847 query-kvm (Command)
18849 Returns information about KVM acceleration
18850 Returns
18852 KvmInfo
18853 Since
18855 0.14
18856 Example
18858 -> { "execute": "query-kvm" }
18859 <- { "return": { "enabled": true, "present": true } }
18860 NumaOptionsType (Enum)
18862 Values
18863 node NUMA nodes configuration
18864 dist NUMA distance configuration (since 2.10)
18866 cpu property based CPU(s) to node mapping (Since: 2.10)
18868 hmat-lb
18870 memory latency and bandwidth information (Since: 5.0)
18871 hmat-cache
18873 memory side cache information (Since: 5.0)
18874 Since
18876 2.1
18877 NumaOptions (Object)
18879 A discriminated record of NUMA options. (for OptsVisitor)
18880 Members
18882 type: NumaOptionsType
18883 Not documented
18884 The members of NumaNodeOptions when type is "node"
18886 The members of NumaDistOptions when type is "dist"
18888 The members of NumaCpuOptions when type is "cpu"
18890 The members of NumaHmatLBOptions when type is "hmat-lb"
18892 The members of NumaHmatCacheOptions when type is "hmat-cache"
18894 Since
18896 2.1
18897 NumaNodeOptions (Object)
18899 Create a guest NUMA node. (for OptsVisitor)
18900 Members
18902 nodeid: int (optional)
18903 NUMA node ID (increase by 1 from 0 if omitted)
18904 cpus: array of int (optional)
18906 VCPUs belonging to this node (assign VCPUS round-robin
18908 if omitted)
18909 mem: int (optional)
18911 memory size of this node; mutually exclusive with memdev.
18912 Equally divide total memory among nodes if both mem and memdev
18913 are omitted.
18914 memdev: string (optional)
18916 memory backend object. If specified for one node, it must be
18917 specified for all nodes.
18918 initiator: int (optional)
18920 defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the
18921 nodeid which has the memory controller responsible for this NUMA
18922 node. This field provides additional information as to the ini‐
18923 tiator node that is closest (as in directly attached) to this
18924 node, and therefore has the best performance (since 5.0)
18925 Since
18927 2.1
18928 NumaDistOptions (Object)
18930 Set the distance between 2 NUMA nodes.
18931 Members
18933 src: int
18934 source NUMA node.
18935 dst: int
18937 destination NUMA node.
18938 val: int
18940 NUMA distance from source node to destination node. When a node
18941 is unreachable from another node, set the distance between them
18942 to 255.
18943 Since
18945 2.10
18946 CXLFixedMemoryWindowOptions (Object)
18948 Create a CXL Fixed Memory Window
18949 Members
18951 size: int
18952 Size of the Fixed Memory Window in bytes. Must be a multiple of
18953 256MiB.
18954 interleave-granularity: int (optional)
18956 Number of contiguous bytes for which accesses will go to a given
18957 interleave target. Accepted values [256, 512, 1k, 2k, 4k, 8k,
18958 16k]
18959 targets: array of string
18961 Target root bridge IDs from -device ...,id=<ID> for each root
18962 bridge.
18963 Since 7.1
18964 CXLFMWProperties (Object)
18966 List of CXL Fixed Memory Windows.
18967 Members
18969 cxl-fmw: array of CXLFixedMemoryWindowOptions
18970 List of CXLFixedMemoryWindowOptions
18971 Since 7.1
18972 X86CPURegister32 (Enum)
18974 A X86 32-bit register
18975 Values
18977 EAX Not documented
18978 EBX Not documented
18980 ECX Not documented
18982 EDX Not documented
18984 ESP Not documented
18986 EBP Not documented
18988 ESI Not documented
18990 EDI Not documented
18992 Since
18994 1.5
18995 X86CPUFeatureWordInfo (Object)
18997 Information about a X86 CPU feature word
18998 Members
19000 cpuid-input-eax: int
19001 Input EAX value for CPUID instruction for that feature word
19002 cpuid-input-ecx: int (optional)
19004 Input ECX value for CPUID instruction for that feature word
19005 cpuid-register: X86CPURegister32
19007 Output register containing the feature bits
19008 features: int
19010 value of output register, containing the feature bits
19011 Since
19013 1.5
19014 DummyForceArrays (Object)
19016 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList inter‐
19017 nally
19018 Members
19020 unused: array of X86CPUFeatureWordInfo
19021 Not documented
19022 Since
19024 2.5
19025 NumaCpuOptions (Object)
19027 Option "-numa cpu" overrides default cpu to node mapping. It accepts
19028 the same set of cpu properties as returned by query-hotplug‐
19029 gable-cpus[].props, where node-id could be used to override default
19030 node mapping.
19031 Members
19033 The members of CpuInstanceProperties
19034 Since
19036 2.10
19037 HmatLBMemoryHierarchy (Enum)
19039 The memory hierarchy in the System Locality Latency and Bandwidth In‐
19040 formation Structure of HMAT (Heterogeneous Memory Attribute Table)
19041 For more information about HmatLBMemoryHierarchy, see chapter 5.2.27.4:
19043 Table 5-146: Field "Flags" of ACPI 6.3 spec.
19044 Values
19046 memory the structure represents the memory performance
19047 first-level
19049 first level of memory side cache
19050 second-level
19052 second level of memory side cache
19053 third-level
19055 third level of memory side cache
19056 Since
19058 5.0
19059 HmatLBDataType (Enum)
19061 Data type in the System Locality Latency and Bandwidth Information
19062 Structure of HMAT (Heterogeneous Memory Attribute Table)
19063 For more information about HmatLBDataType, see chapter 5.2.27.4: Table
19065 5-146: Field "Data Type" of ACPI 6.3 spec.
19066 Values
19068 access-latency
19069 access latency (nanoseconds)
19070 read-latency
19072 read latency (nanoseconds)
19073 write-latency
19075 write latency (nanoseconds)
19076 access-bandwidth
19078 access bandwidth (Bytes per second)
19079 read-bandwidth
19081 read bandwidth (Bytes per second)
19082 write-bandwidth
19084 write bandwidth (Bytes per second)
19085 Since
19087 5.0
19088 NumaHmatLBOptions (Object)
19090 Set the system locality latency and bandwidth information between Ini‐
19091 tiator and Target proximity Domains.
19092 For more information about NumaHmatLBOptions, see chapter 5.2.27.4: Ta‐
19094 ble 5-146 of ACPI 6.3 spec.
19095 Members
19097 initiator: int
19098 the Initiator Proximity Domain.
19099 target: int
19101 the Target Proximity Domain.
19102 hierarchy: HmatLBMemoryHierarchy
19104 the Memory Hierarchy. Indicates the performance of memory or
19105 side cache.
19106 data-type: HmatLBDataType
19108 presents the type of data, access/read/write latency or hit la‐
19109 tency.
19110 latency: int (optional)
19112 the value of latency from initiator to target proximity domain,
19113 the latency unit is "ns(nanosecond)".
19114 bandwidth: int (optional)
19116 the value of bandwidth between initiator and target proximity
19117 domain, the bandwidth unit is "Bytes per second".
19118 Since
19120 5.0
19121 HmatCacheAssociativity (Enum)
19123 Cache associativity in the Memory Side Cache Information Structure of
19124 HMAT
19125 For more information of HmatCacheAssociativity, see chapter 5.2.27.5:
19127 Table 5-147 of ACPI 6.3 spec.
19128 Values
19130 none
19131 None (no memory side cache in this proximity domain,
19133 or cache associativity unknown)
19134 direct Direct Mapped
19136 complex
19138 Complex Cache Indexing (implementation specific)
19139 Since
19141 5.0
19142 HmatCacheWritePolicy (Enum)
19144 Cache write policy in the Memory Side Cache Information Structure of
19145 HMAT
19146 For more information of HmatCacheWritePolicy, see chapter 5.2.27.5: Ta‐
19148 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
19149 Values
19151 none None (no memory side cache in this proximity domain, or cache
19152 write policy unknown)
19153 write-back
19155 Write Back (WB)
19156 write-through
19158 Write Through (WT)
19159 Since
19161 5.0
19162 NumaHmatCacheOptions (Object)
19164 Set the memory side cache information for a given memory domain.
19165 For more information of NumaHmatCacheOptions, see chapter 5.2.27.5: Ta‐
19167 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
19168 Members
19170 node-id: int
19171 the memory proximity domain to which the memory belongs.
19172 size: int
19174 the size of memory side cache in bytes.
19175 level: int
19177 the cache level described in this structure.
19178 associativity: HmatCacheAssociativity
19180 the cache associativity, none/direct-mapped/complex(complex
19181 cache indexing).
19182 policy: HmatCacheWritePolicy
19184 the write policy, none/write-back/write-through.
19185 line: int
19187 the cache Line size in bytes.
19188 Since
19190 5.0
19191 memsave (Command)
19193 Save a portion of guest memory to a file.
19194 Arguments
19196 val: int
19197 the virtual address of the guest to start from
19198 size: int
19200 the size of memory region to save
19201 filename: string
19203 the file to save the memory to as binary data
19204 cpu-index: int (optional)
19206 the index of the virtual CPU to use for translating the virtual
19207 address (defaults to CPU 0)
19208 Returns
19210 Nothing on success
19211 Since
19213 0.14
19214 Notes
19216 Errors were not reliably returned until 1.1
19217 Example
19219 -> { "execute": "memsave",
19220 "arguments": { "val": 10,
19221 "size": 100,
19222 "filename": "/tmp/virtual-mem-dump" } }
19223 <- { "return": {} }
19224 pmemsave (Command)
19226 Save a portion of guest physical memory to a file.
19227 Arguments
19229 val: int
19230 the physical address of the guest to start from
19231 size: int
19233 the size of memory region to save
19234 filename: string
19236 the file to save the memory to as binary data
19237 Returns
19239 Nothing on success
19240 Since
19242 0.14
19243 Notes
19245 Errors were not reliably returned until 1.1
19246 Example
19248 -> { "execute": "pmemsave",
19249 "arguments": { "val": 10,
19250 "size": 100,
19251 "filename": "/tmp/physical-mem-dump" } }
19252 <- { "return": {} }
19253 Memdev (Object)
19255 Information about memory backend
19256 Members
19258 id: string (optional)
19259 backend's ID if backend has 'id' property (since 2.9)
19260 size: int
19262 memory backend size
19263 merge: boolean
19265 whether memory merge support is enabled
19266 dump: boolean
19268 whether memory backend's memory is included in a core dump
19269 prealloc: boolean
19271 whether memory was preallocated
19272 share: boolean
19274 whether memory is private to QEMU or shared (since 6.1)
19275 reserve: boolean (optional)
19277 whether swap space (or huge pages) was reserved if applicable.
19278 This corresponds to the user configuration and not the actual
19279 behavior implemented in the OS to perform the reservation. For
19280 example, Linux will never reserve swap space for shared file
19281 mappings. (since 6.1)
19282 host-nodes: array of int
19284 host nodes for its memory policy
19285 policy: HostMemPolicy
19287 memory policy of memory backend
19288 Since
19290 2.1
19291 query-memdev (Command)
19293 Returns information for all memory backends.
19294 Returns
19296 a list of Memdev.
19297 Since
19299 2.1
19300 Example
19302 -> { "execute": "query-memdev" }
19303 <- { "return": [
19304 {
19305 "id": "mem1",
19306 "size": 536870912,
19307 "merge": false,
19308 "dump": true,
19309 "prealloc": false,
19310 "share": false,
19311 "host-nodes": [0, 1],
19312 "policy": "bind"
19313 },
19314 {
19315 "size": 536870912,
19316 "merge": false,
19317 "dump": true,
19318 "prealloc": true,
19319 "share": false,
19320 "host-nodes": [2, 3],
19321 "policy": "preferred"
19322 }
19323 ]
19324 }
19325 CpuInstanceProperties (Object)
19327 List of properties to be used for hotplugging a CPU instance, it should
19328 be passed by management with device_add command when a CPU is being
19329 hotplugged.
19330 Members
19332 node-id: int (optional)
19333 NUMA node ID the CPU belongs to
19334 socket-id: int (optional)
19336 socket number within node/board the CPU belongs to
19337 die-id: int (optional)
19339 die number within socket the CPU belongs to (since 4.1)
19340 cluster-id: int (optional)
19342 cluster number within die the CPU belongs to (since 7.1)
19343 core-id: int (optional)
19345 core number within cluster the CPU belongs to
19346 thread-id: int (optional)
19348 thread number within core the CPU belongs to
19349 Note
19351 currently there are 6 properties that could be present but management
19352 should be prepared to pass through other properties with device_add
19353 command to allow for future interface extension. This also requires the
19354 filed names to be kept in sync with the properties passed to -de‐
19355 vice/device_add.
19356 Since
19358 2.7
19359 HotpluggableCPU (Object)
19361 Members
19362 type: string
19363 CPU object type for usage with device_add command
19364 props: CpuInstanceProperties
19366 list of properties to be used for hotplugging CPU
19367 vcpus-count: int
19369 number of logical VCPU threads HotpluggableCPU provides
19370 qom-path: string (optional)
19372 link to existing CPU object if CPU is present or omitted if CPU
19373 is not present.
19374 Since
19376 2.7
19377 query-hotpluggable-cpus (Command)
19379 TODO
19380 Better documentation; currently there is none.
19381 Returns
19383 a list of HotpluggableCPU objects.
19384 Since
19386 2.7
19387 Example
19389 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
19390 -> { "execute": "query-hotpluggable-cpus" }
19392 <- {"return": [
19393 { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
19394 "vcpus-count": 1 },
19395 { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
19396 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
19397 ]}'
19398 For pc machine type started with -smp 1,maxcpus=2:
19400 -> { "execute": "query-hotpluggable-cpus" }
19402 <- {"return": [
19403 {
19404 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
19405 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
19406 },
19407 {
19408 "qom-path": "/machine/unattached/device[0]",
19409 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
19410 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
19411 }
19412 ]}
19413 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
19415 (Since: 2.11):
19416 -> { "execute": "query-hotpluggable-cpus" }
19418 <- {"return": [
19419 {
19420 "type": "qemu-s390x-cpu", "vcpus-count": 1,
19421 "props": { "core-id": 1 }
19422 },
19423 {
19424 "qom-path": "/machine/unattached/device[0]",
19425 "type": "qemu-s390x-cpu", "vcpus-count": 1,
19426 "props": { "core-id": 0 }
19427 }
19428 ]}
19429 set-numa-node (Command)
19431 Runtime equivalent of '-numa' CLI option, available at preconfigure
19432 stage to configure numa mapping before initializing machine.
19433 Arguments
19435 The members of NumaOptions
19436 Since
19438 3.0
19439 balloon (Command)
19441 Request the balloon driver to change its balloon size.
19442 Arguments
19444 value: int
19445 the target logical size of the VM in bytes. We can deduce the
19446 size of the balloon using this formula:
19447 logical_vm_size = vm_ram_size - balloon_size
19448 From it we have: balloon_size = vm_ram_size - value
19450 Returns
19452 • Nothing on success
19453 • If the balloon driver is enabled but not functional because the KVM
19455 kernel module cannot support it, KvmMissingCap
19456 • If no balloon device is present, DeviceNotActive
19458 Notes
19460 This command just issues a request to the guest. When it returns, the
19461 balloon size may not have changed. A guest can change the balloon size
19462 independent of this command.
19463 Since
19465 0.14
19466 Example
19468 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
19469 <- { "return": {} }
19470 With a 2.5GiB guest this command inflated the ballon to 3GiB.
19472 BalloonInfo (Object)
19474 Information about the guest balloon device.
19475 Members
19477 actual: int
19478 the logical size of the VM in bytes Formula used: logi‐
19479 cal_vm_size = vm_ram_size - balloon_size
19480 Since
19482 0.14
19483 query-balloon (Command)
19485 Return information about the balloon device.
19486 Returns
19488 • BalloonInfo on success
19489 • If the balloon driver is enabled but not functional because the KVM
19491 kernel module cannot support it, KvmMissingCap
19492 • If no balloon device is present, DeviceNotActive
19494 Since
19496 0.14
19497 Example
19499 -> { "execute": "query-balloon" }
19500 <- { "return": {
19501 "actual": 1073741824
19502 }
19503 }
19504 BALLOON_CHANGE (Event)
19506 Emitted when the guest changes the actual BALLOON level. This value is
19507 equivalent to the actual field return by the 'query-balloon' command
19508 Arguments
19510 actual: int
19511 the logical size of the VM in bytes Formula used: logi‐
19512 cal_vm_size = vm_ram_size - balloon_size
19513 Note
19515 this event is rate-limited.
19516 Since
19518 1.2
19519 Example
19521 <- { "event": "BALLOON_CHANGE",
19522 "data": { "actual": 944766976 },
19523 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
19524 MemoryInfo (Object)
19526 Actual memory information in bytes.
19527 Members
19529 base-memory: int
19530 size of "base" memory specified with command line option -m.
19531 plugged-memory: int (optional)
19533 size of memory that can be hot-unplugged. This field is omitted
19534 if target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE
19535 not defined at build time).
19536 Since
19538 2.11
19539 query-memory-size-summary (Command)
19541 Return the amount of initially allocated and present hotpluggable (if
19542 enabled) memory in bytes.
19543 Example
19545 -> { "execute": "query-memory-size-summary" }
19546 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
19547 Since
19549 2.11
19550 PCDIMMDeviceInfo (Object)
19552 PCDIMMDevice state information
19553 Members
19555 id: string (optional)
19556 device's ID
19557 addr: int
19559 physical address, where device is mapped
19560 size: int
19562 size of memory that the device provides
19563 slot: int
19565 slot number at which device is plugged in
19566 node: int
19568 NUMA node number where device is plugged in
19569 memdev: string
19571 memory backend linked with device
19572 hotplugged: boolean
19574 true if device was hotplugged
19575 hotpluggable: boolean
19577 true if device if could be added/removed while machine is run‐
19578 ning
19579 Since
19581 2.1
19582 VirtioPMEMDeviceInfo (Object)
19584 VirtioPMEM state information
19585 Members
19587 id: string (optional)
19588 device's ID
19589 memaddr: int
19591 physical address in memory, where device is mapped
19592 size: int
19594 size of memory that the device provides
19595 memdev: string
19597 memory backend linked with device
19598 Since
19600 4.1
19601 VirtioMEMDeviceInfo (Object)
19603 VirtioMEMDevice state information
19604 Members
19606 id: string (optional)
19607 device's ID
19608 memaddr: int
19610 physical address in memory, where device is mapped
19611 requested-size: int
19613 the user requested size of the device
19614 size: int
19616 the (current) size of memory that the device provides
19617 max-size: int
19619 the maximum size of memory that the device can provide
19620 block-size: int
19622 the block size of memory that the device provides
19623 node: int
19625 NUMA node number where device is assigned to
19626 memdev: string
19628 memory backend linked with the region
19629 Since
19631 5.1
19632 SgxEPCDeviceInfo (Object)
19634 Sgx EPC state information
19635 Members
19637 id: string (optional)
19638 device's ID
19639 memaddr: int
19641 physical address in memory, where device is mapped
19642 size: int
19644 size of memory that the device provides
19645 memdev: string
19647 memory backend linked with device
19648 node: int
19650 the numa node (Since: 7.0)
19651 Since
19653 6.2
19654 MemoryDeviceInfoKind (Enum)
19656 Values
19657 dimm Not documented
19658 nvdimm Not documented
19660 virtio-pmem
19662 Not documented
19663 virtio-mem
19665 Not documented
19666 sgx-epc
19668 Not documented
19669 Since
19671 2.1
19672 PCDIMMDeviceInfoWrapper (Object)
19674 Members
19675 data: PCDIMMDeviceInfo
19676 Not documented
19677 Since
19679 2.1
19680 VirtioPMEMDeviceInfoWrapper (Object)
19682 Members
19683 data: VirtioPMEMDeviceInfo
19684 Not documented
19685 Since
19687 2.1
19688 VirtioMEMDeviceInfoWrapper (Object)
19690 Members
19691 data: VirtioMEMDeviceInfo
19692 Not documented
19693 Since
19695 2.1
19696 SgxEPCDeviceInfoWrapper (Object)
19698 Members
19699 data: SgxEPCDeviceInfo
19700 Not documented
19701 Since
19703 6.2
19704 MemoryDeviceInfo (Object)
19706 Union containing information about a memory device
19707 nvdimm is included since 2.12. virtio-pmem is included since 4.1. vir‐
19709 tio-mem is included since 5.1. sgx-epc is included since 6.2.
19710 Members
19712 type: MemoryDeviceInfoKind
19713 Not documented
19714 The members of PCDIMMDeviceInfoWrapper when type is "dimm"
19716 The members of PCDIMMDeviceInfoWrapper when type is "nvdimm"
19718 The members of VirtioPMEMDeviceInfoWrapper when type is "virtio-pmem"
19720 The members of VirtioMEMDeviceInfoWrapper when type is "virtio-mem"
19722 The members of SgxEPCDeviceInfoWrapper when type is "sgx-epc"
19724 Since
19726 2.1
19727 SgxEPC (Object)
19729 Sgx EPC cmdline information
19730 Members
19732 memdev: string
19733 memory backend linked with device
19734 node: int
19736 the numa node (Since: 7.0)
19737 Since
19739 6.2
19740 SgxEPCProperties (Object)
19742 SGX properties of machine types.
19743 Members
19745 sgx-epc: array of SgxEPC
19746 list of ids of memory-backend-epc objects.
19747 Since
19749 6.2
19750 query-memory-devices (Command)
19752 Lists available memory devices and their state
19753 Since
19755 2.1
19756 Example
19758 -> { "execute": "query-memory-devices" }
19759 <- { "return": [ { "data":
19760 { "addr": 5368709120,
19761 "hotpluggable": true,
19762 "hotplugged": true,
19763 "id": "d1",
19764 "memdev": "/objects/memX",
19765 "node": 0,
19766 "size": 1073741824,
19767 "slot": 0},
19768 "type": "dimm"
19769 } ] }
19770 MEMORY_DEVICE_SIZE_CHANGE (Event)
19772 Emitted when the size of a memory device changes. Only emitted for mem‐
19773 ory devices that can actually change the size (e.g., virtio-mem due to
19774 guest action).
19775 Arguments
19777 id: string (optional)
19778 device's ID
19779 size: int
19781 the new size of memory that the device provides
19782 qom-path: string
19784 path to the device object in the QOM tree (since 6.2)
19785 Note
19787 this event is rate-limited.
19788 Since
19790 5.1
19791 Example
19793 <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
19794 "data": { "id": "vm0", "size": 1073741824,
19795 "qom-path": "/machine/unattached/device[2]" },
19796 "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
19797 MEM_UNPLUG_ERROR (Event)
19799 Emitted when memory hot unplug error occurs.
19800 Arguments
19802 device: string
19803 device name
19804 msg: string
19806 Informative message
19807 Features
19809 deprecated
19810 This event is deprecated. Use DEVICE_UNPLUG_GUEST_ERROR instead.
19811 Since
19813 2.4
19814 Example
19816 <- { "event": "MEM_UNPLUG_ERROR",
19817 "data": { "device": "dimm1",
19818 "msg": "acpi: device unplug for unsupported device"
19819 },
19820 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
19821 BootConfiguration (Object)
19823 Schema for virtual machine boot configuration.
19824 Members
19826 order: string (optional)
19827 Boot order (a=floppy, c=hard disk, d=CD-ROM, n=network)
19828 once: string (optional)
19830 Boot order to apply on first boot
19831 menu: boolean (optional)
19833 Whether to show a boot menu
19834 splash: string (optional)
19836 The name of the file to be passed to the firmware as logo pic‐
19837 ture, if menu is true.
19838 splash-time: int (optional)
19840 How long to show the logo picture, in milliseconds
19841 reboot-timeout: int (optional)
19843 Timeout before guest reboots after boot fails
19844 strict: boolean (optional)
19846 Whether to attempt booting from devices not included in the boot
19847 order
19848 Since
19850 7.1
19851 SMPConfiguration (Object)
19853 Schema for CPU topology configuration. A missing value lets QEMU fig‐
19854 ure out a suitable value based on the ones that are provided.
19855 Members
19857 cpus: int (optional)
19858 number of virtual CPUs in the virtual machine
19859 sockets: int (optional)
19861 number of sockets in the CPU topology
19862 dies: int (optional)
19864 number of dies per socket in the CPU topology
19865 clusters: int (optional)
19867 number of clusters per die in the CPU topology (since 7.0)
19868 cores: int (optional)
19870 number of cores per cluster in the CPU topology
19871 threads: int (optional)
19873 number of threads per core in the CPU topology
19874 maxcpus: int (optional)
19876 maximum number of hotpluggable virtual CPUs in the virtual ma‐
19877 chine
19878 Since
19880 6.1
19881 x-query-irq (Command)
19883 Query interrupt statistics
19884 Features
19886 unstable
19887 This command is meant for debugging.
19888 Returns
19890 interrupt statistics
19891 Since
19893 6.2
19894 x-query-jit (Command)
19896 Query TCG compiler statistics
19897 Features
19899 unstable
19900 This command is meant for debugging.
19901 Returns
19903 TCG compiler statistics
19904 Since
19906 6.2
19907 If
19909 CONFIG_TCG
19910 x-query-numa (Command)
19912 Query NUMA topology information
19913 Features
19915 unstable
19916 This command is meant for debugging.
19917 Returns
19919 topology information
19920 Since
19922 6.2
19923 x-query-opcount (Command)
19925 Query TCG opcode counters
19926 Features
19928 unstable
19929 This command is meant for debugging.
19930 Returns
19932 TCG opcode counters
19933 Since
19935 6.2
19936 If
19938 CONFIG_TCG
19939 x-query-profile (Command)
19941 Query TCG profiling information
19942 Features
19944 unstable
19945 This command is meant for debugging.
19946 Returns
19948 profile information
19949 Since
19951 6.2
19952 If
19954 CONFIG_TCG
19955 x-query-ramblock (Command)
19957 Query system ramblock information
19958 Features
19960 unstable
19961 This command is meant for debugging.
19962 Returns
19964 system ramblock information
19965 Since
19967 6.2
19968 x-query-rdma (Command)
19970 Query RDMA state
19971 Features
19973 unstable
19974 This command is meant for debugging.
19975 Returns
19977 RDMA state
19978 Since
19980 6.2
19981 x-query-roms (Command)
19983 Query information on the registered ROMS
19984 Features
19986 unstable
19987 This command is meant for debugging.
19988 Returns
19990 registered ROMs
19991 Since
19993 6.2
19994 x-query-usb (Command)
19996 Query information on the USB devices
19997 Features
19999 unstable
20000 This command is meant for debugging.
20001 Returns
20003 USB device information
20004 Since
20006 6.2
20007 SmbiosEntryPointType (Enum)
20009 Values
20010 32 SMBIOS version 2.1 (32-bit) Entry Point
20011 64 SMBIOS version 3.0 (64-bit) Entry Point
20013 Since
20015 7.0
20016 MemorySizeConfiguration (Object)
20018 Schema for memory size configuration.
20019 Members
20021 size: int (optional)
20022 memory size in bytes
20023 max-size: int (optional)
20025 maximum hotpluggable memory size in bytes
20026 slots: int (optional)
20028 number of available memory slots for hotplug
20029 Since
20031 7.1
20032 dumpdtb (Command)
20034 Save the FDT in dtb format.
20035 Arguments
20037 filename: string
20038 name of the dtb file to be created
20039 Since
20041 7.2
20042 Example
20044 {"execute": "dumpdtb"}
20045 "arguments": { "filename": "fdt.dtb" } }
20046 If
20048 CONFIG_FDT
20049 CpuModelInfo (Object)
20051 Virtual CPU model.
20052 A CPU model consists of the name of a CPU definition, to which delta
20054 changes are applied (e.g. features added/removed). Most magic values
20055 that an architecture might require should be hidden behind the name.
20056 However, if required, architectures can expose relevant properties.
20057 Members
20059 name: string
20060 the name of the CPU definition the model is based on
20061 props: value (optional)
20063 a dictionary of QOM properties to be applied
20064 Since
20066 2.8
20067 CpuModelExpansionType (Enum)
20069 An enumeration of CPU model expansion types.
20070 Values
20072 static Expand to a static CPU model, a combination of a static base
20073 model name and property delta changes. As the static base model
20074 will never change, the expanded CPU model will be the same, in‐
20075 dependent of QEMU version, machine type, machine options, and
20076 accelerator options. Therefore, the resulting model can be used
20077 by tooling without having to specify a compatibility machine -
20078 e.g. when displaying the "host" model. The static CPU models are
20079 migration-safe.
20080 full Expand all properties. The produced model is not guaranteed to
20082 be migration-safe, but allows tooling to get an insight and work
20083 with model details.
20084 Note
20086 When a non-migration-safe CPU model is expanded in static mode, some
20087 features enabled by the CPU model may be omitted, because they can't be
20088 implemented by a static CPU model definition (e.g. cache info
20089 passthrough and PMU passthrough in x86). If you need an accurate repre‐
20090 sentation of the features enabled by a non-migration-safe CPU model,
20091 use full. If you need a static representation that will keep ABI com‐
20092 patibility even when changing QEMU version or machine-type, use static
20093 (but keep in mind that some features may be omitted).
20094 Since
20096 2.8
20097 CpuModelCompareResult (Enum)
20099 An enumeration of CPU model comparison results. The result is usually
20100 calculated using e.g. CPU features or CPU generations.
20101 Values
20103 incompatible
20104 If model A is incompatible to model B, model A is not guaranteed
20105 to run where model B runs and the other way around.
20106 identical
20108 If model A is identical to model B, model A is guaranteed to run
20109 where model B runs and the other way around.
20110 superset
20112 If model A is a superset of model B, model B is guaranteed to
20113 run where model A runs. There are no guarantees about the other
20114 way.
20115 subset If model A is a subset of model B, model A is guaranteed to run
20117 where model B runs. There are no guarantees about the other way.
20118 Since
20120 2.8
20121 CpuModelBaselineInfo (Object)
20123 The result of a CPU model baseline.
20124 Members
20126 model: CpuModelInfo
20127 the baselined CpuModelInfo.
20128 Since
20130 2.8
20131 If
20133 TARGET_S390X
20134 CpuModelCompareInfo (Object)
20136 The result of a CPU model comparison.
20137 Members
20139 result: CpuModelCompareResult
20140 The result of the compare operation.
20141 responsible-properties: array of string
20143 List of properties that led to the comparison result not being
20144 identical.
20145 responsible-properties is a list of QOM property names that led to both
20146 CPUs not being detected as identical. For identical models, this list
20147 is empty. If a QOM property is read-only, that means there's no known
20148 way to make the CPU models identical. If the special property name
20149 "type" is included, the models are by definition not identical and can‐
20150 not be made identical.
20151 Since
20153 2.8
20154 If
20156 TARGET_S390X
20157 query-cpu-model-comparison (Command)
20159 Compares two CPU models, returning how they compare in a specific con‐
20160 figuration. The results indicates how both models compare regarding
20161 runnability. This result can be used by tooling to make decisions if a
20162 certain CPU model will run in a certain configuration or if a compati‐
20163 ble CPU model has to be created by baselining.
20164 Usually, a CPU model is compared against the maximum possible CPU model
20166 of a certain configuration (e.g. the "host" model for KVM). If that CPU
20167 model is identical or a subset, it will run in that configuration.
20168 The result returned by this command may be affected by:
20170 • QEMU version: CPU models may look different depending on the QEMU
20172 version. (Except for CPU models reported as "static" in
20173 query-cpu-definitions.)
20174 • machine-type: CPU model may look different depending on the ma‐
20176 chine-type. (Except for CPU models reported as "static" in
20177 query-cpu-definitions.)
20178 • machine options (including accelerator): in some architectures, CPU
20180 models may look different depending on machine and accelerator op‐
20181 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
20182 nitions.)
20183 • "-cpu" arguments and global properties: arguments to the -cpu option
20185 and global properties may affect expansion of CPU models. Using
20186 query-cpu-model-expansion while using these is not advised.
20187 Some architectures may not support comparing CPU models. s390x supports
20189 comparing CPU models.
20190 Arguments
20192 modela: CpuModelInfo
20193 Not documented
20194 modelb: CpuModelInfo
20196 Not documented
20197 Returns
20199 a CpuModelBaselineInfo. Returns an error if comparing CPU models is not
20200 supported, if a model cannot be used, if a model contains an unknown
20201 cpu definition name, unknown properties or properties with wrong types.
20202 Note
20204 this command isn't specific to s390x, but is only implemented on this
20205 architecture currently.
20206 Since
20208 2.8
20209 If
20211 TARGET_S390X
20212 query-cpu-model-baseline (Command)
20214 Baseline two CPU models, creating a compatible third model. The created
20215 model will always be a static, migration-safe CPU model (see "static"
20216 CPU model expansion for details).
20217 This interface can be used by tooling to create a compatible CPU model
20219 out two CPU models. The created CPU model will be identical to or a
20220 subset of both CPU models when comparing them. Therefore, the created
20221 CPU model is guaranteed to run where the given CPU models run.
20222 The result returned by this command may be affected by:
20224 • QEMU version: CPU models may look different depending on the QEMU
20226 version. (Except for CPU models reported as "static" in
20227 query-cpu-definitions.)
20228 • machine-type: CPU model may look different depending on the ma‐
20230 chine-type. (Except for CPU models reported as "static" in
20231 query-cpu-definitions.)
20232 • machine options (including accelerator): in some architectures, CPU
20234 models may look different depending on machine and accelerator op‐
20235 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
20236 nitions.)
20237 • "-cpu" arguments and global properties: arguments to the -cpu option
20239 and global properties may affect expansion of CPU models. Using
20240 query-cpu-model-expansion while using these is not advised.
20241 Some architectures may not support baselining CPU models. s390x sup‐
20243 ports baselining CPU models.
20244 Arguments
20246 modela: CpuModelInfo
20247 Not documented
20248 modelb: CpuModelInfo
20250 Not documented
20251 Returns
20253 a CpuModelBaselineInfo. Returns an error if baselining CPU models is
20254 not supported, if a model cannot be used, if a model contains an un‐
20255 known cpu definition name, unknown properties or properties with wrong
20256 types.
20257 Note
20259 this command isn't specific to s390x, but is only implemented on this
20260 architecture currently.
20261 Since
20263 2.8
20264 If
20266 TARGET_S390X
20267 CpuModelExpansionInfo (Object)
20269 The result of a cpu model expansion.
20270 Members
20272 model: CpuModelInfo
20273 the expanded CpuModelInfo.
20274 Since
20276 2.8
20277 If
20279 TARGET_S390X or TARGET_I386 or TARGET_ARM
20280 query-cpu-model-expansion (Command)
20282 Expands a given CPU model (or a combination of CPU model + additional
20283 options) to different granularities, allowing tooling to get an under‐
20284 standing what a specific CPU model looks like in QEMU under a certain
20285 configuration.
20286 This interface can be used to query the "host" CPU model.
20288 The data returned by this command may be affected by:
20290 • QEMU version: CPU models may look different depending on the QEMU
20292 version. (Except for CPU models reported as "static" in
20293 query-cpu-definitions.)
20294 • machine-type: CPU model may look different depending on the ma‐
20296 chine-type. (Except for CPU models reported as "static" in
20297 query-cpu-definitions.)
20298 • machine options (including accelerator): in some architectures, CPU
20300 models may look different depending on machine and accelerator op‐
20301 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
20302 nitions.)
20303 • "-cpu" arguments and global properties: arguments to the -cpu option
20305 and global properties may affect expansion of CPU models. Using
20306 query-cpu-model-expansion while using these is not advised.
20307 Some architectures may not support all expansion types. s390x supports
20309 "full" and "static". Arm only supports "full".
20310 Arguments
20312 type: CpuModelExpansionType
20313 Not documented
20314 model: CpuModelInfo
20316 Not documented
20317 Returns
20319 a CpuModelExpansionInfo. Returns an error if expanding CPU models is
20320 not supported, if the model cannot be expanded, if the model contains
20321 an unknown CPU definition name, unknown properties or properties with a
20322 wrong type. Also returns an error if an expansion type is not sup‐
20323 ported.
20324 Since
20326 2.8
20327 If
20329 TARGET_S390X or TARGET_I386 or TARGET_ARM
20330 CpuDefinitionInfo (Object)
20332 Virtual CPU definition.
20333 Members
20335 name: string
20336 the name of the CPU definition
20337 migration-safe: boolean (optional)
20339 whether a CPU definition can be safely used for migration in
20340 combination with a QEMU compatibility machine when migrating be‐
20341 tween different QEMU versions and between hosts with different
20342 sets of (hardware or software) capabilities. If not provided,
20343 information is not available and callers should not assume the
20344 CPU definition to be migration-safe. (since 2.8)
20345 static: boolean
20347 whether a CPU definition is static and will not change depending
20348 on QEMU version, machine type, machine options and accelerator
20349 options. A static model is always migration-safe. (since 2.8)
20350 unavailable-features: array of string (optional)
20352 List of properties that prevent the CPU model from running in
20353 the current host. (since 2.8)
20354 typename: string
20356 Type name that can be used as argument to device-list-proper‐
20357 ties, to introspect properties configurable using -cpu or
20358 -global. (since 2.9)
20359 alias-of: string (optional)
20361 Name of CPU model this model is an alias for. The target of the
20362 CPU model alias may change depending on the machine type. Man‐
20363 agement software is supposed to translate CPU model aliases in
20364 the VM configuration, because aliases may stop being migra‐
20365 tion-safe in the future (since 4.1)
20366 deprecated: boolean
20368 If true, this CPU model is deprecated and may be removed in in
20369 some future version of QEMU according to the QEMU deprecation
20370 policy. (since 5.2)
20371 unavailable-features is a list of QOM property names that represent CPU
20372 model attributes that prevent the CPU from running. If the QOM prop‐
20373 erty is read-only, that means there's no known way to make the CPU
20374 model run in the current host. Implementations that choose not to pro‐
20375 vide specific information return the property name "type". If the
20376 property is read-write, it means that it MAY be possible to run the CPU
20377 model in the current host if that property is changed. Management soft‐
20378 ware can use it as hints to suggest or choose an alternative for the
20379 user, or just to generate meaningful error messages explaining why the
20380 CPU model can't be used. If unavailable-features is an empty list, the
20381 CPU model is runnable using the current host and machine-type. If un‐
20382 available-features is not present, runnability information for the CPU
20383 is not available.
20384 Since
20386 1.2
20387 If
20389 TARGET_PPC or TARGET_ARM or TARGET_I386 or TARGET_S390X or TARGET_MIPS
20390 or TARGET_LOONGARCH64
20391 query-cpu-definitions (Command)
20393 Return a list of supported virtual CPU definitions
20394 Returns
20396 a list of CpuDefInfo
20397 Since
20399 1.2
20400 If
20402 TARGET_PPC or TARGET_ARM or TARGET_I386 or TARGET_S390X or TARGET_MIPS
20403 or TARGET_LOONGARCH64
20404
20406 ReplayMode (Enum)
20407 Mode of the replay subsystem.
20408 Values
20410 none normal execution mode. Replay or record are not enabled.
20411 record record mode. All non-deterministic data is written into the re‐
20413 play log.
20414 play replay mode. Non-deterministic data required for system execu‐
20416 tion is read from the log.
20417 Since
20419 2.5
20420 ReplayInfo (Object)
20422 Record/replay information.
20423 Members
20425 mode: ReplayMode
20426 current mode.
20427 filename: string (optional)
20429 name of the record/replay log file. It is present only in
20430 record or replay modes, when the log is recorded or replayed.
20431 icount: int
20433 current number of executed instructions.
20434 Since
20436 5.2
20437 query-replay (Command)
20439 Retrieve the record/replay information. It includes current instruc‐
20440 tion count which may be used for replay-break and replay-seek commands.
20441 Returns
20443 record/replay information.
20444 Since
20446 5.2
20447 Example
20449 -> { "execute": "query-replay" }
20450 <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
20451 replay-break (Command)
20453 Set replay breakpoint at instruction count icount. Execution stops
20454 when the specified instruction is reached. There can be at most one
20455 breakpoint. When breakpoint is set, any prior one is removed. The
20456 breakpoint may be set only in replay mode and only "in the future",
20457 i.e. at instruction counts greater than the current one. The current
20458 instruction count can be observed with query-replay.
20459 Arguments
20461 icount: int
20462 instruction count to stop at
20463 Since
20465 5.2
20466 Example
20468 -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
20469 replay-delete-break (Command)
20471 Remove replay breakpoint which was set with replay-break. The command
20472 is ignored when there are no replay breakpoints.
20473 Since
20475 5.2
20476 Example
20478 -> { "execute": "replay-delete-break" }
20479 replay-seek (Command)
20481 Automatically proceed to the instruction count icount, when replaying
20482 the execution. The command automatically loads nearest snapshot and re‐
20483 plays the execution to find the desired instruction. When there is no
20484 preceding snapshot or the execution is not replayed, then the command
20485 fails. icount for the reference may be obtained with query-replay com‐
20486 mand.
20487 Arguments
20489 icount: int
20490 target instruction count
20491 Since
20493 5.2
20494 Example
20496 -> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
20497
20499 YankInstanceType (Enum)
20500 An enumeration of yank instance types. See YankInstance for more infor‐
20501 mation.
20502 Values
20504 block-node
20505 Not documented
20506 chardev
20508 Not documented
20509 migration
20511 Not documented
20512 Since
20514 6.0
20515 YankInstanceBlockNode (Object)
20517 Specifies which block graph node to yank. See YankInstance for more in‐
20518 formation.
20519 Members
20521 node-name: string
20522 the name of the block graph node
20523 Since
20525 6.0
20526 YankInstanceChardev (Object)
20528 Specifies which character device to yank. See YankInstance for more in‐
20529 formation.
20530 Members
20532 id: string
20533 the chardev's ID
20534 Since
20536 6.0
20537 YankInstance (Object)
20539 A yank instance can be yanked with the yank qmp command to recover from
20540 a hanging QEMU.
20541 Currently implemented yank instances:
20543 • nbd block device: Yanking it will shut down the connection to
20545 the nbd server without attempting to reconnect.
20546 • socket chardev: Yanking it will shut down the connected
20548 socket.
20549 • migration: Yanking it will shut down all migration connec‐
20551 tions. Unlike migrate_cancel, it will not notify the migration
20552 process, so migration will go into failed state, instead of
20553 cancelled state. yank should be used to recover from hangs.
20554 Members
20556 type: YankInstanceType
20557 Not documented
20558 The members of YankInstanceBlockNode when type is "block-node"
20560 The members of YankInstanceChardev when type is "chardev"
20562 Since
20564 6.0
20565 yank (Command)
20567 Try to recover from hanging QEMU by yanking the specified instances.
20568 See YankInstance for more information.
20569 Takes a list of YankInstance as argument.
20571 Arguments
20573 instances: array of YankInstance
20574 Not documented
20575 Returns
20577 • Nothing on success
20578 • DeviceNotFound error, if any of the YankInstances doesn't exist
20580 Example
20582 -> { "execute": "yank",
20583 "arguments": {
20584 "instances": [
20585 { "type": "block-node",
20586 "node-name": "nbd0" }
20587 ] } }
20588 <- { "return": {} }
20589 Since
20591 6.0
20592 query-yank (Command)
20594 Query yank instances. See YankInstance for more information.
20595 Returns
20597 list of YankInstance
20598 Example
20600 -> { "execute": "query-yank" }
20601 <- { "return": [
20602 { "type": "block-node",
20603 "node-name": "nbd0" }
20604 ] }
20605 Since
20607 6.0
20608
20610 add_client (Command)
20611 Allow client connections for VNC, Spice and socket based character de‐
20612 vices to be passed in to QEMU via SCM_RIGHTS.
20613 Arguments
20615 protocol: string
20616 protocol name. Valid names are "vnc", "spice", "dbus-display" or
20617 the name of a character device (eg. from -chardev id=XXXX)
20618 fdname: string
20620 file descriptor name previously passed via 'getfd' command
20621 skipauth: boolean (optional)
20623 whether to skip authentication. Only applies to "vnc" and
20624 "spice" protocols
20625 tls: boolean (optional)
20627 whether to perform TLS. Only applies to the "spice" protocol
20628 Returns
20630 nothing on success.
20631 Since
20633 0.14
20634 Example
20636 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
20637 "fdname": "myclient" } }
20638 <- { "return": {} }
20639 NameInfo (Object)
20641 Guest name information.
20642 Members
20644 name: string (optional)
20645 The name of the guest
20646 Since
20648 0.14
20649 query-name (Command)
20651 Return the name information of a guest.
20652 Returns
20654 NameInfo of the guest
20655 Since
20657 0.14
20658 Example
20660 -> { "execute": "query-name" }
20661 <- { "return": { "name": "qemu-name" } }
20662 IOThreadInfo (Object)
20664 Information about an iothread
20665 Members
20667 id: string
20668 the identifier of the iothread
20669 thread-id: int
20671 ID of the underlying host thread
20672 poll-max-ns: int
20674 maximum polling time in ns, 0 means polling is disabled (since
20675 2.9)
20676 poll-grow: int
20678 how many ns will be added to polling time, 0 means that it's not
20679 configured (since 2.9)
20680 poll-shrink: int
20682 how many ns will be removed from polling time, 0 means that it's
20683 not configured (since 2.9)
20684 aio-max-batch: int
20686 maximum number of requests in a batch for the AIO engine, 0
20687 means that the engine will use its default (since 6.1)
20688 Since
20690 2.0
20691 query-iothreads (Command)
20693 Returns a list of information about each iothread.
20694 Note
20696 this list excludes the QEMU main loop thread, which is not declared us‐
20697 ing the -object iothread command-line option. It is always the main
20698 thread of the process.
20699 Returns
20701 a list of IOThreadInfo for each iothread
20702 Since
20704 2.0
20705 Example
20707 -> { "execute": "query-iothreads" }
20708 <- { "return": [
20709 {
20710 "id":"iothread0",
20711 "thread-id":3134
20712 },
20713 {
20714 "id":"iothread1",
20715 "thread-id":3135
20716 }
20717 ]
20718 }
20719 stop (Command)
20721 Stop all guest VCPU execution.
20722 Since
20724 0.14
20725 Notes
20727 This function will succeed even if the guest is already in the stopped
20728 state. In "inmigrate" state, it will ensure that the guest remains
20729 paused once migration finishes, as if the -S option was passed on the
20730 command line.
20731 Example
20733 -> { "execute": "stop" }
20734 <- { "return": {} }
20735 cont (Command)
20737 Resume guest VCPU execution.
20738 Since
20740 0.14
20741 Returns
20743 If successful, nothing
20744 Notes
20746 This command will succeed if the guest is currently running. It will
20747 also succeed if the guest is in the "inmigrate" state; in this case,
20748 the effect of the command is to make sure the guest starts once migra‐
20749 tion finishes, removing the effect of the -S command line option if it
20750 was passed.
20751 Example
20753 -> { "execute": "cont" }
20754 <- { "return": {} }
20755 x-exit-preconfig (Command)
20757 Exit from "preconfig" state
20758 This command makes QEMU exit the preconfig state and proceed with VM
20760 initialization using configuration data provided on the command line
20761 and via the QMP monitor during the preconfig state. The command is only
20762 available during the preconfig state (i.e. when the --preconfig command
20763 line option was in use).
20764 Features
20766 unstable
20767 This command is experimental.
20768 Since
20770 3.0
20771 Returns
20773 nothing
20774 Example
20776 -> { "execute": "x-exit-preconfig" }
20777 <- { "return": {} }
20778 human-monitor-command (Command)
20780 Execute a command on the human monitor and return the output.
20781 Arguments
20783 command-line: string
20784 the command to execute in the human monitor
20785 cpu-index: int (optional)
20787 The CPU to use for commands that require an implicit CPU
20788 Features
20790 savevm-monitor-nodes
20791 If present, HMP command savevm only snapshots monitor-owned
20792 nodes if they have no parents. This allows the use of 'savevm'
20793 with -blockdev. (since 4.2)
20794 Returns
20796 the output of the command as a string
20797 Since
20799 0.14
20800 Notes
20802 This command only exists as a stop-gap. Its use is highly discouraged.
20803 The semantics of this command are not guaranteed: this means that com‐
20804 mand names, arguments and responses can change or be removed at ANY
20805 time. Applications that rely on long term stability guarantees should
20806 NOT use this command.
20807 Known limitations:
20809 • This command is stateless, this means that commands that depend on
20811 state information (such as getfd) might not work
20812 • Commands that prompt the user for data don't currently work
20814 Example
20816 -> { "execute": "human-monitor-command",
20817 "arguments": { "command-line": "info kvm" } }
20818 <- { "return": "kvm support: enabled\r\n" }
20819 getfd (Command)
20821 Receive a file descriptor via SCM rights and assign it a name
20822 Arguments
20824 fdname: string
20825 file descriptor name
20826 Returns
20828 Nothing on success
20829 Since
20831 0.14
20832 Notes
20834 If fdname already exists, the file descriptor assigned to it will be
20835 closed and replaced by the received file descriptor.
20836 The 'closefd' command can be used to explicitly close the file descrip‐
20838 tor when it is no longer needed.
20839 Example
20841 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
20842 <- { "return": {} }
20843 closefd (Command)
20845 Close a file descriptor previously passed via SCM rights
20846 Arguments
20848 fdname: string
20849 file descriptor name
20850 Returns
20852 Nothing on success
20853 Since
20855 0.14
20856 Example
20858 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
20859 <- { "return": {} }
20860 AddfdInfo (Object)
20862 Information about a file descriptor that was added to an fd set.
20863 Members
20865 fdset-id: int
20866 The ID of the fd set that fd was added to.
20867 fd: int
20869 The file descriptor that was received via SCM rights and added
20870 to the fd set.
20871 Since
20873 1.2
20874 add-fd (Command)
20876 Add a file descriptor, that was passed via SCM rights, to an fd set.
20877 Arguments
20879 fdset-id: int (optional)
20880 The ID of the fd set to add the file descriptor to.
20881 opaque: string (optional)
20883 A free-form string that can be used to describe the fd.
20884 Returns
20886 • AddfdInfo on success
20887 • If file descriptor was not received, FdNotSupplied
20889 • If fdset-id is a negative value, InvalidParameterValue
20891 Notes
20893 The list of fd sets is shared by all monitor connections.
20894 If fdset-id is not specified, a new fd set will be created.
20896 Since
20898 1.2
20899 Example
20901 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
20902 <- { "return": { "fdset-id": 1, "fd": 3 } }
20903 remove-fd (Command)
20905 Remove a file descriptor from an fd set.
20906 Arguments
20908 fdset-id: int
20909 The ID of the fd set that the file descriptor belongs to.
20910 fd: int (optional)
20912 The file descriptor that is to be removed.
20913 Returns
20915 • Nothing on success
20916 • If fdset-id or fd is not found, FdNotFound
20918 Since
20920 1.2
20921 Notes
20923 The list of fd sets is shared by all monitor connections.
20924 If fd is not specified, all file descriptors in fdset-id will be re‐
20926 moved.
20927 Example
20929 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
20930 <- { "return": {} }
20931 FdsetFdInfo (Object)
20933 Information about a file descriptor that belongs to an fd set.
20934 Members
20936 fd: int
20937 The file descriptor value.
20938 opaque: string (optional)
20940 A free-form string that can be used to describe the fd.
20941 Since
20943 1.2
20944 FdsetInfo (Object)
20946 Information about an fd set.
20947 Members
20949 fdset-id: int
20950 The ID of the fd set.
20951 fds: array of FdsetFdInfo
20953 A list of file descriptors that belong to this fd set.
20954 Since
20956 1.2
20957 query-fdsets (Command)
20959 Return information describing all fd sets.
20960 Returns
20962 A list of FdsetInfo
20963 Since
20965 1.2
20966 Note
20968 The list of fd sets is shared by all monitor connections.
20969 Example
20971 -> { "execute": "query-fdsets" }
20972 <- { "return": [
20973 {
20974 "fds": [
20975 {
20976 "fd": 30,
20977 "opaque": "rdonly:/path/to/file"
20978 },
20979 {
20980 "fd": 24,
20981 "opaque": "rdwr:/path/to/file"
20982 }
20983 ],
20984 "fdset-id": 1
20985 },
20986 {
20987 "fds": [
20988 {
20989 "fd": 28
20990 },
20991 {
20992 "fd": 29
20993 }
20994 ],
20995 "fdset-id": 0
20996 }
20997 ]
20998 }
20999 CommandLineParameterType (Enum)
21001 Possible types for an option parameter.
21002 Values
21004 string accepts a character string
21005 boolean
21007 accepts "on" or "off"
21008 number accepts a number
21010 size accepts a number followed by an optional suffix (K)ilo, (M)ega,
21012 (G)iga, (T)era
21013 Since
21015 1.5
21016 CommandLineParameterInfo (Object)
21018 Details about a single parameter of a command line option.
21019 Members
21021 name: string
21022 parameter name
21023 type: CommandLineParameterType
21025 parameter CommandLineParameterType
21026 help: string (optional)
21028 human readable text string, not suitable for parsing.
21029 default: string (optional)
21031 default value string (since 2.1)
21032 Since
21034 1.5
21035 CommandLineOptionInfo (Object)
21037 Details about a command line option, including its list of parameter
21038 details
21039 Members
21041 option: string
21042 option name
21043 parameters: array of CommandLineParameterInfo
21045 an array of CommandLineParameterInfo
21046 Since
21048 1.5
21049 query-command-line-options (Command)
21051 Query command line option schema.
21052 Arguments
21054 option: string (optional)
21055 option name
21056 Returns
21058 list of CommandLineOptionInfo for all options (or for the given op‐
21059 tion). Returns an error if the given option doesn't exist.
21060 Since
21062 1.5
21063 Example
21065 -> { "execute": "query-command-line-options",
21066 "arguments": { "option": "option-rom" } }
21067 <- { "return": [
21068 {
21069 "parameters": [
21070 {
21071 "name": "romfile",
21072 "type": "string"
21073 },
21074 {
21075 "name": "bootindex",
21076 "type": "number"
21077 }
21078 ],
21079 "option": "option-rom"
21080 }
21081 ]
21082 }
21083 RTC_CHANGE (Event)
21085 Emitted when the guest changes the RTC time.
21086 Arguments
21088 offset: int
21089 offset in seconds between base RTC clock (as specified by -rtc
21090 base), and new RTC clock value
21091 qom-path: string
21093 path to the RTC object in the QOM tree
21094 Note
21096 This event is rate-limited. It is not guaranteed that the RTC in the
21097 system implements this event, or even that the system has an RTC at
21098 all.
21099 Since
21101 0.13
21102 Example
21104 <- { "event": "RTC_CHANGE",
21105 "data": { "offset": 78 },
21106 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
21107 VFU_CLIENT_HANGUP (Event)
21109 Emitted when the client of a TYPE_VFIO_USER_SERVER closes the communi‐
21110 cation channel
21111 Arguments
21113 vfu-id: string
21114 ID of the TYPE_VFIO_USER_SERVER object. It is the last component
21115 of vfu-qom-path referenced below
21116 vfu-qom-path: string
21118 path to the TYPE_VFIO_USER_SERVER object in the QOM tree
21119 dev-id: string
21121 ID of attached PCI device
21122 dev-qom-path: string
21124 path to attached PCI device in the QOM tree
21125 Since
21127 7.1
21128 Example
21130 <- { "event": "VFU_CLIENT_HANGUP",
21131 "data": { "vfu-id": "vfu1",
21132 "vfu-qom-path": "/objects/vfu1",
21133 "dev-id": "sas1",
21134 "dev-qom-path": "/machine/peripheral/sas1" },
21135 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
21136 rtc-reset-reinjection (Command)
21138 This command will reset the RTC interrupt reinjection backlog. Can be
21139 used if another mechanism to synchronize guest time is in effect, for
21140 example QEMU guest agent's guest-set-time command.
21141 Since
21143 2.1
21144 Example
21146 -> { "execute": "rtc-reset-reinjection" }
21147 <- { "return": {} }
21148 If
21150 TARGET_I386
21151 SevState (Enum)
21153 An enumeration of SEV state information used during query-sev.
21154 Values
21156 uninit The guest is uninitialized.
21157 launch-update
21159 The guest is currently being launched; plaintext data and regis‐
21160 ter state is being imported.
21161 launch-secret
21163 The guest is currently being launched; ciphertext data is being
21164 imported.
21165 running
21167 The guest is fully launched or migrated in.
21168 send-update
21170 The guest is currently being migrated out to another machine.
21171 receive-update
21173 The guest is currently being migrated from another machine.
21174 Since
21176 2.12
21177 If
21179 TARGET_I386
21180 SevInfo (Object)
21182 Information about Secure Encrypted Virtualization (SEV) support
21183 Members
21185 enabled: boolean
21186 true if SEV is active
21187 api-major: int
21189 SEV API major version
21190 api-minor: int
21192 SEV API minor version
21193 build-id: int
21195 SEV FW build id
21196 policy: int
21198 SEV policy value
21199 state: SevState
21201 SEV guest state
21202 handle: int
21204 SEV firmware handle
21205 Since
21207 2.12
21208 If
21210 TARGET_I386
21211 query-sev (Command)
21213 Returns information about SEV
21214 Returns
21216 SevInfo
21217 Since
21219 2.12
21220 Example
21222 -> { "execute": "query-sev" }
21223 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
21224 "build-id" : 0, "policy" : 0, "state" : "running",
21225 "handle" : 1 } }
21226 If
21228 TARGET_I386
21229 SevLaunchMeasureInfo (Object)
21231 SEV Guest Launch measurement information
21232 Members
21234 data: string
21235 the measurement value encoded in base64
21236 Since
21238 2.12
21239 If
21241 TARGET_I386
21242 query-sev-launch-measure (Command)
21244 Query the SEV guest launch information.
21245 Returns
21247 The SevLaunchMeasureInfo for the guest
21248 Since
21250 2.12
21251 Example
21253 -> { "execute": "query-sev-launch-measure" }
21254 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
21255 If
21257 TARGET_I386
21258 SevCapability (Object)
21260 The struct describes capability for a Secure Encrypted Virtualization
21261 feature.
21262 Members
21264 pdh: string
21265 Platform Diffie-Hellman key (base64 encoded)
21266 cert-chain: string
21268 PDH certificate chain (base64 encoded)
21269 cpu0-id: string
21271 Unique ID of CPU0 (base64 encoded) (since 7.1)
21272 cbitpos: int
21274 C-bit location in page table entry
21275 reduced-phys-bits: int
21277 Number of physical Address bit reduction when SEV is enabled
21278 Since
21280 2.12
21281 If
21283 TARGET_I386
21284 query-sev-capabilities (Command)
21286 This command is used to get the SEV capabilities, and is supported on
21287 AMD X86 platforms only.
21288 Returns
21290 SevCapability objects.
21291 Since
21293 2.12
21294 Example
21296 -> { "execute": "query-sev-capabilities" }
21297 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
21298 "cpu0-id": "2lvmGwo+...61iEinw==",
21299 "cbitpos": 47, "reduced-phys-bits": 5}}
21300 If
21302 TARGET_I386
21303 sev-inject-launch-secret (Command)
21305 This command injects a secret blob into memory of SEV guest.
21306 Arguments
21308 packet-header: string
21309 the launch secret packet header encoded in base64
21310 secret: string
21312 the launch secret data to be injected encoded in base64
21313 gpa: int (optional)
21315 the guest physical address where secret will be injected.
21316 Since
21318 6.0
21319 If
21321 TARGET_I386
21322 SevAttestationReport (Object)
21324 The struct describes attestation report for a Secure Encrypted Virtual‐
21325 ization feature.
21326 Members
21328 data: string
21329 guest attestation report (base64 encoded)
21330 Since
21332 6.1
21333 If
21335 TARGET_I386
21336 query-sev-attestation-report (Command)
21338 This command is used to get the SEV attestation report, and is sup‐
21339 ported on AMD X86 platforms only.
21340 Arguments
21342 mnonce: string
21343 a random 16 bytes value encoded in base64 (it will be included
21344 in report)
21345 Returns
21347 SevAttestationReport objects.
21348 Since
21350 6.1
21351 Example
21353 -> { "execute" : "query-sev-attestation-report",
21354 "arguments": { "mnonce": "aaaaaaa" } }
21355 <- { "return" : { "data": "aaaaaaaabbbddddd"} }
21356 If
21358 TARGET_I386
21359 dump-skeys (Command)
21361 Dump guest's storage keys
21362 Arguments
21364 filename: string
21365 the path to the file to dump to
21366 This command is only supported on s390 architecture.
21367 Since
21369 2.5
21370 Example
21372 -> { "execute": "dump-skeys",
21373 "arguments": { "filename": "/tmp/skeys" } }
21374 <- { "return": {} }
21375 If
21377 TARGET_S390X
21378 GICCapability (Object)
21380 The struct describes capability for a specific GIC (Generic Interrupt
21381 Controller) version. These bits are not only decided by QEMU/KVM soft‐
21382 ware version, but also decided by the hardware that the program is run‐
21383 ning upon.
21384 Members
21386 version: int
21387 version of GIC to be described. Currently, only 2 and 3 are sup‐
21388 ported.
21389 emulated: boolean
21391 whether current QEMU/hardware supports emulated GIC device in
21392 user space.
21393 kernel: boolean
21395 whether current QEMU/hardware supports hardware accelerated GIC
21396 device in kernel.
21397 Since
21399 2.6
21400 If
21402 TARGET_ARM
21403 query-gic-capabilities (Command)
21405 This command is ARM-only. It will return a list of GICCapability ob‐
21406 jects that describe its capability bits.
21407 Returns
21409 a list of GICCapability objects.
21410 Since
21412 2.6
21413 Example
21415 -> { "execute": "query-gic-capabilities" }
21416 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
21417 { "version": 3, "emulated": false, "kernel": true } ] }
21418 If
21420 TARGET_ARM
21421 SGXEPCSection (Object)
21423 Information about intel SGX EPC section info
21424 Members
21426 node: int
21427 the numa node
21428 size: int
21430 the size of EPC section
21431 Since
21433 7.0
21434 SGXInfo (Object)
21436 Information about intel Safe Guard eXtension (SGX) support
21437 Members
21439 sgx: boolean
21440 true if SGX is supported
21441 sgx1: boolean
21443 true if SGX1 is supported
21444 sgx2: boolean
21446 true if SGX2 is supported
21447 flc: boolean
21449 true if FLC is supported
21450 section-size: int
21452 The EPC section size for guest Redundant with sections. Just
21453 for backward compatibility.
21454 sections: array of SGXEPCSection
21456 The EPC sections info for guest (Since: 7.0)
21457 Features
21459 deprecated
21460 Member section-size is deprecated. Use sections instead.
21461 Since
21463 6.2
21464 If
21466 TARGET_I386
21467 query-sgx (Command)
21469 Returns information about SGX
21470 Returns
21472 SGXInfo
21473 Since
21475 6.2
21476 Example
21478 -> { "execute": "query-sgx" }
21479 <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
21480 "flc": true, "section-size" : 96468992,
21481 "sections": [{"node": 0, "size": 67108864},
21482 {"node": 1, "size": 29360128}]} }
21483 If
21485 TARGET_I386
21486 query-sgx-capabilities (Command)
21488 Returns information from host SGX capabilities
21489 Returns
21491 SGXInfo
21492 Since
21494 6.2
21495 Example
21497 -> { "execute": "query-sgx-capabilities" }
21498 <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
21499 "flc": true, "section-size" : 96468992,
21500 "section" : [{"node": 0, "size": 67108864},
21501 {"node": 1, "size": 29360128}]} }
21502 If
21504 TARGET_I386
21505
21507 AudiodevPerDirectionOptions (Object)
21508 General audio backend options that are used for both playback and
21509 recording.
21510 Members
21512 mixing-engine: boolean (optional)
21513 use QEMU's mixing engine to mix all streams inside QEMU and con‐
21514 vert audio formats when not supported by the backend. When set
21515 to off, fixed-settings must be also off (default on, since 4.2)
21516 fixed-settings: boolean (optional)
21518 use fixed settings for host input/output. When off, frequency,
21519 channels and format must not be specified (default true)
21520 frequency: int (optional)
21522 frequency to use when using fixed settings (default 44100)
21523 channels: int (optional)
21525 number of channels when using fixed settings (default 2)
21526 voices: int (optional)
21528 number of voices to use (default 1)
21529 format: AudioFormat (optional)
21531 sample format to use when using fixed settings (default s16)
21532 buffer-length: int (optional)
21534 the buffer length in microseconds
21535 Since
21537 4.0
21538 AudiodevGenericOptions (Object)
21540 Generic driver-specific options.
21541 Members
21543 in: AudiodevPerDirectionOptions (optional)
21544 options of the capture stream
21545 out: AudiodevPerDirectionOptions (optional)
21547 options of the playback stream
21548 Since
21550 4.0
21551 AudiodevAlsaPerDirectionOptions (Object)
21553 Options of the ALSA backend that are used for both playback and record‐
21554 ing.
21555 Members
21557 dev: string (optional)
21558 the name of the ALSA device to use (default 'default')
21559 period-length: int (optional)
21561 the period length in microseconds
21562 try-poll: boolean (optional)
21564 attempt to use poll mode, falling back to non-polling access on
21565 failure (default true)
21566 The members of AudiodevPerDirectionOptions
21568 Since
21570 4.0
21571 AudiodevAlsaOptions (Object)
21573 Options of the ALSA audio backend.
21574 Members
21576 in: AudiodevAlsaPerDirectionOptions (optional)
21577 options of the capture stream
21578 out: AudiodevAlsaPerDirectionOptions (optional)
21580 options of the playback stream
21581 threshold: int (optional)
21583 set the threshold (in microseconds) when playback starts
21584 Since
21586 4.0
21587 AudiodevSndioOptions (Object)
21589 Options of the sndio audio backend.
21590 Members
21592 in: AudiodevPerDirectionOptions (optional)
21593 options of the capture stream
21594 out: AudiodevPerDirectionOptions (optional)
21596 options of the playback stream
21597 dev: string (optional)
21599 the name of the sndio device to use (default 'default')
21600 latency: int (optional)
21602 play buffer size (in microseconds)
21603 Since
21605 7.2
21606 AudiodevCoreaudioPerDirectionOptions (Object)
21608 Options of the Core Audio backend that are used for both playback and
21609 recording.
21610 Members
21612 buffer-count: int (optional)
21613 number of buffers
21614 The members of AudiodevPerDirectionOptions
21616 Since
21618 4.0
21619 AudiodevCoreaudioOptions (Object)
21621 Options of the coreaudio audio backend.
21622 Members
21624 in: AudiodevCoreaudioPerDirectionOptions (optional)
21625 options of the capture stream
21626 out: AudiodevCoreaudioPerDirectionOptions (optional)
21628 options of the playback stream
21629 Since
21631 4.0
21632 AudiodevDsoundOptions (Object)
21634 Options of the DirectSound audio backend.
21635 Members
21637 in: AudiodevPerDirectionOptions (optional)
21638 options of the capture stream
21639 out: AudiodevPerDirectionOptions (optional)
21641 options of the playback stream
21642 latency: int (optional)
21644 add extra latency to playback in microseconds (default 10000)
21645 Since
21647 4.0
21648 AudiodevJackPerDirectionOptions (Object)
21650 Options of the JACK backend that are used for both playback and record‐
21651 ing.
21652 Members
21654 server-name: string (optional)
21655 select from among several possible concurrent server instances
21656 (default: environment variable $JACK_DEFAULT_SERVER if set, else
21657 "default")
21658 client-name: string (optional)
21660 the client name to use. The server will modify this name to cre‐
21661 ate a unique variant, if needed unless exact-name is true (de‐
21662 fault: the guest's name)
21663 connect-ports: string (optional)
21665 if set, a regular expression of JACK client port name(s) to mon‐
21666 itor for and automatically connect to
21667 start-server: boolean (optional)
21669 start a jack server process if one is not already present (de‐
21670 fault: false)
21671 exact-name: boolean (optional)
21673 use the exact name requested otherwise JACK automatically gener‐
21674 ates a unique one, if needed (default: false)
21675 The members of AudiodevPerDirectionOptions
21677 Since
21679 5.1
21680 AudiodevJackOptions (Object)
21682 Options of the JACK audio backend.
21683 Members
21685 in: AudiodevJackPerDirectionOptions (optional)
21686 options of the capture stream
21687 out: AudiodevJackPerDirectionOptions (optional)
21689 options of the playback stream
21690 Since
21692 5.1
21693 AudiodevOssPerDirectionOptions (Object)
21695 Options of the OSS backend that are used for both playback and record‐
21696 ing.
21697 Members
21699 dev: string (optional)
21700 file name of the OSS device (default '/dev/dsp')
21701 buffer-count: int (optional)
21703 number of buffers
21704 try-poll: boolean (optional)
21706 attempt to use poll mode, falling back to non-polling access on
21707 failure (default true)
21708 The members of AudiodevPerDirectionOptions
21710 Since
21712 4.0
21713 AudiodevOssOptions (Object)
21715 Options of the OSS audio backend.
21716 Members
21718 in: AudiodevOssPerDirectionOptions (optional)
21719 options of the capture stream
21720 out: AudiodevOssPerDirectionOptions (optional)
21722 options of the playback stream
21723 try-mmap: boolean (optional)
21725 try using memory-mapped access, falling back to non-mem‐
21726 ory-mapped access on failure (default true)
21727 exclusive: boolean (optional)
21729 open device in exclusive mode (vmix won't work) (default false)
21730 dsp-policy: int (optional)
21732 set the timing policy of the device (between 0 and 10, where
21733 smaller number means smaller latency but higher CPU usage) or -1
21734 to use fragment mode (option ignored on some platforms) (default
21735 5)
21736 Since
21738 4.0
21739 AudiodevPaPerDirectionOptions (Object)
21741 Options of the Pulseaudio backend that are used for both playback and
21742 recording.
21743 Members
21745 name: string (optional)
21746 name of the sink/source to use
21747 stream-name: string (optional)
21749 name of the PulseAudio stream created by qemu. Can be used to
21750 identify the stream in PulseAudio when you create multiple
21751 PulseAudio devices or run multiple qemu instances (default: au‐
21752 diodev's id, since 4.2)
21753 latency: int (optional)
21755 latency you want PulseAudio to achieve in microseconds (default
21756 15000)
21757 The members of AudiodevPerDirectionOptions
21759 Since
21761 4.0
21762 AudiodevPaOptions (Object)
21764 Options of the PulseAudio audio backend.
21765 Members
21767 in: AudiodevPaPerDirectionOptions (optional)
21768 options of the capture stream
21769 out: AudiodevPaPerDirectionOptions (optional)
21771 options of the playback stream
21772 server: string (optional)
21774 PulseAudio server address (default: let PulseAudio choose)
21775 Since
21777 4.0
21778 AudiodevSdlPerDirectionOptions (Object)
21780 Options of the SDL audio backend that are used for both playback and
21781 recording.
21782 Members
21784 buffer-count: int (optional)
21785 number of buffers (default 4)
21786 The members of AudiodevPerDirectionOptions
21788 Since
21790 6.0
21791 AudiodevSdlOptions (Object)
21793 Options of the SDL audio backend.
21794 Members
21796 in: AudiodevSdlPerDirectionOptions (optional)
21797 options of the recording stream
21798 out: AudiodevSdlPerDirectionOptions (optional)
21800 options of the playback stream
21801 Since
21803 6.0
21804 AudiodevWavOptions (Object)
21806 Options of the wav audio backend.
21807 Members
21809 in: AudiodevPerDirectionOptions (optional)
21810 options of the capture stream
21811 out: AudiodevPerDirectionOptions (optional)
21813 options of the playback stream
21814 path: string (optional)
21816 name of the wav file to record (default 'qemu.wav')
21817 Since
21819 4.0
21820 AudioFormat (Enum)
21822 An enumeration of possible audio formats.
21823 Values
21825 u8 unsigned 8 bit integer
21826 s8 signed 8 bit integer
21828 u16 unsigned 16 bit integer
21830 s16 signed 16 bit integer
21832 u32 unsigned 32 bit integer
21834 s32 signed 32 bit integer
21836 f32 single precision floating-point (since 5.0)
21838 Since
21840 4.0
21841 AudiodevDriver (Enum)
21843 An enumeration of possible audio backend drivers.
21844 Values
21846 jack JACK audio backend (since 5.1)
21847 none Not documented
21849 alsa Not documented
21851 coreaudio
21853 Not documented
21854 dbus Not documented
21856 dsound Not documented
21858 oss Not documented
21860 pa Not documented
21862 sdl Not documented
21864 sndio Not documented
21866 spice Not documented
21868 wav Not documented
21870 Since
21872 4.0
21873 Audiodev (Object)
21875 Options of an audio backend.
21876 Members
21878 id: string
21879 identifier of the backend
21880 driver: AudiodevDriver
21882 the backend driver to use
21883 timer-period: int (optional)
21885 timer period (in microseconds, 0: use lowest possible)
21886 The members of AudiodevGenericOptions when driver is "none"
21888 The members of AudiodevAlsaOptions when driver is "alsa"
21890 The members of AudiodevCoreaudioOptions when driver is "coreaudio"
21892 The members of AudiodevGenericOptions when driver is "dbus"
21894 The members of AudiodevDsoundOptions when driver is "dsound"
21896 The members of AudiodevJackOptions when driver is "jack"
21898 The members of AudiodevOssOptions when driver is "oss"
21900 The members of AudiodevPaOptions when driver is "pa"
21902 The members of AudiodevSdlOptions when driver is "sdl"
21904 The members of AudiodevSndioOptions when driver is "sndio"
21906 The members of AudiodevGenericOptions when driver is "spice"
21908 The members of AudiodevWavOptions when driver is "wav"
21910 Since
21912 4.0
21913
21915 AcpiTableOptions (Object)
21916 Specify an ACPI table on the command line to load.
21917 At most one of file and data can be specified. The list of files speci‐
21919 fied by any one of them is loaded and concatenated in order. If both
21920 are omitted, data is implied.
21921 Other fields / optargs can be used to override fields of the generic
21923 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
21924 System Description Table Header. If a header field is not overridden,
21925 then the corresponding value from the concatenated blob is used (in
21926 case of file), or it is filled in with a hard-coded value (in case of
21927 data).
21928 String fields are copied into the matching ACPI member from lowest ad‐
21930 dress upwards, and silently truncated / NUL-padded to length.
21931 Members
21933 sig: string (optional)
21934 table signature / identifier (4 bytes)
21935 rev: int (optional)
21937 table revision number (dependent on signature, 1 byte)
21938 oem_id: string (optional)
21940 OEM identifier (6 bytes)
21941 oem_table_id: string (optional)
21943 OEM table identifier (8 bytes)
21944 oem_rev: int (optional)
21946 OEM-supplied revision number (4 bytes)
21947 asl_compiler_id: string (optional)
21949 identifier of the utility that created the table (4 bytes)
21950 asl_compiler_rev: int (optional)
21952 revision number of the utility that created the table (4 bytes)
21953 file: string (optional)
21955 colon (:) separated list of pathnames to load and concatenate as
21956 table data. The resultant binary blob is expected to have an
21957 ACPI table header. At least one file is required. This field ex‐
21958 cludes data.
21959 data: string (optional)
21961 colon (:) separated list of pathnames to load and concatenate as
21962 table data. The resultant binary blob must not have an ACPI ta‐
21963 ble header. At least one file is required. This field excludes
21964 file.
21965 Since
21967 1.5
21968 ACPISlotType (Enum)
21970 Values
21971 DIMM memory slot
21972 CPU logical CPU slot (since 2.7)
21974 ACPIOSTInfo (Object)
21976 OSPM Status Indication for a device For description of possible values
21977 of source and status fields see "_OST (OSPM Status Indication)" chapter
21978 of ACPI5.0 spec.
21979 Members
21981 device: string (optional)
21982 device ID associated with slot
21983 slot: string
21985 slot ID, unique per slot of a given slot-type
21986 slot-type: ACPISlotType
21988 type of the slot
21989 source: int
21991 an integer containing the source event
21992 status: int
21994 an integer containing the status code
21995 Since
21997 2.1
21998 query-acpi-ospm-status (Command)
22000 Return a list of ACPIOSTInfo for devices that support status reporting
22001 via ACPI _OST method.
22002 Since
22004 2.1
22005 Example
22007 -> { "execute": "query-acpi-ospm-status" }
22008 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
22009 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
22010 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
22011 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
22012 ]}
22013 ACPI_DEVICE_OST (Event)
22015 Emitted when guest executes ACPI _OST method.
22016 Arguments
22018 info: ACPIOSTInfo
22019 OSPM Status Indication
22020 Since
22022 2.1
22023 Example
22025 <- { "event": "ACPI_DEVICE_OST",
22026 "data": { "info": { "device": "d1", "slot": "0",
22027 "slot-type": "DIMM", "source": 1, "status": 0 } },
22028 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
22029
22031 PciMemoryRange (Object)
22032 A PCI device memory region
22033 Members
22035 base: int
22036 the starting address (guest physical)
22037 limit: int
22039 the ending address (guest physical)
22040 Since
22042 0.14
22043 PciMemoryRegion (Object)
22045 Information about a PCI device I/O region.
22046 Members
22048 bar: int
22049 the index of the Base Address Register for this region
22050 type: string
22052 • 'io' if the region is a PIO region
22054 • 'memory' if the region is a MMIO region
22056 size: int
22058 memory size
22059 prefetch: boolean (optional)
22061 if type is 'memory', true if the memory is prefetchable
22062 mem_type_64: boolean (optional)
22064 if type is 'memory', true if the BAR is 64-bit
22065 address: int
22067 Not documented
22068 Since
22070 0.14
22071 PciBusInfo (Object)
22073 Information about a bus of a PCI Bridge device
22074 Members
22076 number: int
22077 primary bus interface number. This should be the number of the
22078 bus the device resides on.
22079 secondary: int
22081 secondary bus interface number. This is the number of the main
22082 bus for the bridge
22083 subordinate: int
22085 This is the highest number bus that resides below the bridge.
22086 io_range: PciMemoryRange
22088 The PIO range for all devices on this bridge
22089 memory_range: PciMemoryRange
22091 The MMIO range for all devices on this bridge
22092 prefetchable_range: PciMemoryRange
22094 The range of prefetchable MMIO for all devices on this bridge
22095 Since
22097 2.4
22098 PciBridgeInfo (Object)
22100 Information about a PCI Bridge device
22101 Members
22103 bus: PciBusInfo
22104 information about the bus the device resides on
22105 devices: array of PciDeviceInfo (optional)
22107 a list of PciDeviceInfo for each device on this bridge
22108 Since
22110 0.14
22111 PciDeviceClass (Object)
22113 Information about the Class of a PCI device
22114 Members
22116 desc: string (optional)
22117 a string description of the device's class
22118 class: int
22120 the class code of the device
22121 Since
22123 2.4
22124 PciDeviceId (Object)
22126 Information about the Id of a PCI device
22127 Members
22129 device: int
22130 the PCI device id
22131 vendor: int
22133 the PCI vendor id
22134 subsystem: int (optional)
22136 the PCI subsystem id (since 3.1)
22137 subsystem-vendor: int (optional)
22139 the PCI subsystem vendor id (since 3.1)
22140 Since
22142 2.4
22143 PciDeviceInfo (Object)
22145 Information about a PCI device
22146 Members
22148 bus: int
22149 the bus number of the device
22150 slot: int
22152 the slot the device is located in
22153 function: int
22155 the function of the slot used by the device
22156 class_info: PciDeviceClass
22158 the class of the device
22159 id: PciDeviceId
22161 the PCI device id
22162 irq: int (optional)
22164 if an IRQ is assigned to the device, the IRQ number
22165 irq_pin: int
22167 the IRQ pin, zero means no IRQ (since 5.1)
22168 qdev_id: string
22170 the device name of the PCI device
22171 pci_bridge: PciBridgeInfo (optional)
22173 if the device is a PCI bridge, the bridge information
22174 regions: array of PciMemoryRegion
22176 a list of the PCI I/O regions associated with the device
22177 Notes
22179 the contents of class_info.desc are not stable and should only be
22180 treated as informational.
22181 Since
22183 0.14
22184 PciInfo (Object)
22186 Information about a PCI bus
22187 Members
22189 bus: int
22190 the bus index
22191 devices: array of PciDeviceInfo
22193 a list of devices on this bus
22194 Since
22196 0.14
22197 query-pci (Command)
22199 Return information about the PCI bus topology of the guest.
22200 Returns
22202 a list of PciInfo for each PCI bus. Each bus is represented by a
22203 json-object, which has a key with a json-array of all PCI devices at‐
22204 tached to it. Each device is represented by a json-object.
22205 Since
22207 0.14
22208 Example
22210 -> { "execute": "query-pci" }
22211 <- { "return": [
22212 {
22213 "bus": 0,
22214 "devices": [
22215 {
22216 "bus": 0,
22217 "qdev_id": "",
22218 "slot": 0,
22219 "class_info": {
22220 "class": 1536,
22221 "desc": "Host bridge"
22222 },
22223 "id": {
22224 "device": 32902,
22225 "vendor": 4663
22226 },
22227 "function": 0,
22228 "regions": [
22229 ]
22230 },
22231 {
22232 "bus": 0,
22233 "qdev_id": "",
22234 "slot": 1,
22235 "class_info": {
22236 "class": 1537,
22237 "desc": "ISA bridge"
22238 },
22239 "id": {
22240 "device": 32902,
22241 "vendor": 28672
22242 },
22243 "function": 0,
22244 "regions": [
22245 ]
22246 },
22247 {
22248 "bus": 0,
22249 "qdev_id": "",
22250 "slot": 1,
22251 "class_info": {
22252 "class": 257,
22253 "desc": "IDE controller"
22254 },
22255 "id": {
22256 "device": 32902,
22257 "vendor": 28688
22258 },
22259 "function": 1,
22260 "regions": [
22261 {
22262 "bar": 4,
22263 "size": 16,
22264 "address": 49152,
22265 "type": "io"
22266 }
22267 ]
22268 },
22269 {
22270 "bus": 0,
22271 "qdev_id": "",
22272 "slot": 2,
22273 "class_info": {
22274 "class": 768,
22275 "desc": "VGA controller"
22276 },
22277 "id": {
22278 "device": 4115,
22279 "vendor": 184
22280 },
22281 "function": 0,
22282 "regions": [
22283 {
22284 "prefetch": true,
22285 "mem_type_64": false,
22286 "bar": 0,
22287 "size": 33554432,
22288 "address": 4026531840,
22289 "type": "memory"
22290 },
22291 {
22292 "prefetch": false,
22293 "mem_type_64": false,
22294 "bar": 1,
22295 "size": 4096,
22296 "address": 4060086272,
22297 "type": "memory"
22298 },
22299 {
22300 "prefetch": false,
22301 "mem_type_64": false,
22302 "bar": 6,
22303 "size": 65536,
22304 "address": -1,
22305 "type": "memory"
22306 }
22307 ]
22308 },
22309 {
22310 "bus": 0,
22311 "qdev_id": "",
22312 "irq": 11,
22313 "slot": 4,
22314 "class_info": {
22315 "class": 1280,
22316 "desc": "RAM controller"
22317 },
22318 "id": {
22319 "device": 6900,
22320 "vendor": 4098
22321 },
22322 "function": 0,
22323 "regions": [
22324 {
22325 "bar": 0,
22326 "size": 32,
22327 "address": 49280,
22328 "type": "io"
22329 }
22330 ]
22331 }
22332 ]
22333 }
22334 ]
22335 }
22336 Note
22338 This example has been shortened as the real response is too long.
22339
22341 StatsType (Enum)
22342 Enumeration of statistics types
22343 Values
22345 cumulative
22346 stat is cumulative; value can only increase.
22347 instant
22349 stat is instantaneous; value can increase or decrease.
22350 peak stat is the peak value; value can only increase.
22352 linear-histogram
22354 stat is a linear histogram.
22355 log2-histogram
22357 stat is a logarithmic histogram, with one bucket for each power
22358 of two.
22359 Since
22361 7.1
22362 StatsUnit (Enum)
22364 Enumeration of unit of measurement for statistics
22365 Values
22367 bytes stat reported in bytes.
22368 seconds
22370 stat reported in seconds.
22371 cycles stat reported in clock cycles.
22373 boolean
22375 stat is a boolean value.
22376 Since
22378 7.1
22379 StatsProvider (Enum)
22381 Enumeration of statistics providers.
22382 Values
22384 kvm Not documented
22385 Since
22387 7.1
22388 StatsTarget (Enum)
22390 The kinds of objects on which one can request statistics.
22391 Values
22393 vm statistics that apply to the entire virtual machine or the en‐
22394 tire QEMU process.
22395 vcpu statistics that apply to a single virtual CPU.
22397 Since
22399 7.1
22400 StatsRequest (Object)
22402 Indicates a set of statistics that should be returned by query-stats.
22403 Members
22405 provider: StatsProvider
22406 provider for which to return statistics.
22407 names: array of string (optional)
22409 statistics to be returned (all if omitted).
22410 Since
22412 7.1
22413 StatsVCPUFilter (Object)
22415 Members
22416 vcpus: array of string (optional)
22417 list of QOM paths for the desired vCPU objects.
22418 Since
22420 7.1
22421 StatsFilter (Object)
22423 The arguments to the query-stats command; specifies a target for which
22424 to request statistics and optionally the required subset of information
22425 for that target: - which vCPUs to request statistics for - which
22426 providers to request statistics from - which named values to return
22427 within each provider
22428 Members
22430 target: StatsTarget
22431 Not documented
22432 providers: array of StatsRequest (optional)
22434 Not documented
22435 The members of StatsVCPUFilter when target is "vcpu"
22437 Since
22439 7.1
22440 StatsValue (Alternate)
22442 Members
22443 scalar: int
22444 single unsigned 64-bit integers.
22445 list: array of int
22447 list of unsigned 64-bit integers (used for histograms).
22448 boolean: boolean
22450 Not documented
22451 Since
22453 7.1
22454 Stats (Object)
22456 Members
22457 name: string
22458 name of stat.
22459 value: StatsValue
22461 stat value.
22462 Since
22464 7.1
22465 StatsResult (Object)
22467 Members
22468 provider: StatsProvider
22469 provider for this set of statistics.
22470 qom-path: string (optional)
22472 Path to the object for which the statistics are returned, if the
22473 object is exposed in the QOM tree
22474 stats: array of Stats
22476 list of statistics.
22477 Since
22479 7.1
22480 query-stats (Command)
22482 Return runtime-collected statistics for objects such as the VM or its
22483 vCPUs.
22484 The arguments are a StatsFilter and specify the provider and objects to
22486 return statistics about.
22487 Arguments
22489 The members of StatsFilter
22490 Returns
22492 a list of StatsResult, one for each provider and object (e.g., for each
22493 vCPU).
22494 Since
22496 7.1
22497 StatsSchemaValue (Object)
22499 Schema for a single statistic.
22500 Members
22502 name: string
22503 name of the statistic; each element of the schema is uniquely
22504 identified by a target, a provider (both available in StatsS‐
22505 chema) and the name.
22506 type: StatsType
22508 kind of statistic.
22509 unit: StatsUnit (optional)
22511 basic unit of measure for the statistic; if missing, the statis‐
22512 tic is a simple number or counter.
22513 base: int (optional)
22515 base for the multiple of unit in which the statistic is mea‐
22516 sured. Only present if exponent is non-zero; base and exponent
22517 together form a SI prefix (e.g., _nano-_ for base=10 and expo‐
22518 nent=-9) or IEC binary prefix (e.g. _kibi-_ for base=2 and expo‐
22519 nent=10)
22520 exponent: int
22522 exponent for the multiple of unit in which the statistic is ex‐
22523 pressed, or 0 for the basic unit
22524 bucket-size: int (optional)
22526 Present when type is "linear-histogram", contains the width of
22527 each bucket of the histogram.
22528 Since
22530 7.1
22531 StatsSchema (Object)
22533 Schema for all available statistics for a provider and target.
22534 Members
22536 provider: StatsProvider
22537 provider for this set of statistics.
22538 target: StatsTarget
22540 the kind of object that can be queried through the provider.
22541 stats: array of StatsSchemaValue
22543 list of statistics.
22544 Since
22546 7.1
22547 query-stats-schemas (Command)
22549 Return the schema for all available runtime-collected statistics.
22550 Arguments
22552 provider: StatsProvider (optional)
22553 Not documented
22554 Note
22556 runtime-collected statistics and their names fall outside QEMU's usual
22557 deprecation policies. QEMU will try to keep the set of available data
22558 stable, together with their names, but will not guarantee stability at
22559 all costs; the same is true of providers that source statistics exter‐
22560 nally, e.g. from Linux. For example, if the same value is being
22561 tracked with different names on different architectures or by different
22562 providers, one of them might be renamed. A statistic might go away if
22563 an algorithm is changed or some code is removed; changing a default
22564 might cause previously useful statistics to always report 0. Such
22565 changes, however, are expected to be rare.
22566 Since
22568 7.1
22569
22571 VirtioInfo (Object)
22572 Basic information about a given VirtIODevice
22573 Members
22575 path: string
22576 The VirtIODevice's canonical QOM path
22577 name: string
22579 Name of the VirtIODevice
22580 Since
22582 7.2
22583 x-query-virtio (Command)
22585 Returns a list of all realized VirtIODevices
22586 Features
22588 unstable
22589 This command is meant for debugging.
22590 Returns
22592 List of gathered VirtIODevices
22593 Since
22595 7.2
22596 Example
22598 -> { "execute": "x-query-virtio" }
22599 <- { "return": [
22600 {
22601 "name": "virtio-input",
22602 "path": "/machine/peripheral-anon/device[4]/virtio-backend"
22603 },
22604 {
22605 "name": "virtio-crypto",
22606 "path": "/machine/peripheral/crypto0/virtio-backend"
22607 },
22608 {
22609 "name": "virtio-scsi",
22610 "path": "/machine/peripheral-anon/device[2]/virtio-backend"
22611 },
22612 {
22613 "name": "virtio-net",
22614 "path": "/machine/peripheral-anon/device[1]/virtio-backend"
22615 },
22616 {
22617 "name": "virtio-serial",
22618 "path": "/machine/peripheral-anon/device[0]/virtio-backend"
22619 }
22620 ]
22621 }
22622 VhostStatus (Object)
22624 Information about a vhost device. This information will only be dis‐
22625 played if the vhost device is active.
22626 Members
22628 n-mem-sections: int
22629 vhost_dev n_mem_sections
22630 n-tmp-sections: int
22632 vhost_dev n_tmp_sections
22633 nvqs: int
22635 vhost_dev nvqs (number of virtqueues being used)
22636 vq-index: int
22638 vhost_dev vq_index
22639 features: VirtioDeviceFeatures
22641 vhost_dev features
22642 acked-features: VirtioDeviceFeatures
22644 vhost_dev acked_features
22645 backend-features: VirtioDeviceFeatures
22647 vhost_dev backend_features
22648 protocol-features: VhostDeviceProtocols
22650 vhost_dev protocol_features
22651 max-queues: int
22653 vhost_dev max_queues
22654 backend-cap: int
22656 vhost_dev backend_cap
22657 log-enabled: boolean
22659 vhost_dev log_enabled flag
22660 log-size: int
22662 vhost_dev log_size
22663 Since
22665 7.2
22666 VirtioStatus (Object)
22668 Full status of the virtio device with most VirtIODevice members. Also
22669 includes the full status of the corresponding vhost device if the vhost
22670 device is active.
22671 Members
22673 name: string
22674 VirtIODevice name
22675 device-id: int
22677 VirtIODevice ID
22678 vhost-started: boolean
22680 VirtIODevice vhost_started flag
22681 guest-features: VirtioDeviceFeatures
22683 VirtIODevice guest_features
22684 host-features: VirtioDeviceFeatures
22686 VirtIODevice host_features
22687 backend-features: VirtioDeviceFeatures
22689 VirtIODevice backend_features
22690 device-endian: string
22692 VirtIODevice device_endian
22693 num-vqs: int
22695 VirtIODevice virtqueue count. This is the number of active
22696 virtqueues being used by the VirtIODevice.
22697 status: VirtioDeviceStatus
22699 VirtIODevice configuration status (VirtioDeviceStatus)
22700 isr: int
22702 VirtIODevice ISR
22703 queue-sel: int
22705 VirtIODevice queue_sel
22706 vm-running: boolean
22708 VirtIODevice vm_running flag
22709 broken: boolean
22711 VirtIODevice broken flag
22712 disabled: boolean
22714 VirtIODevice disabled flag
22715 use-started: boolean
22717 VirtIODevice use_started flag
22718 started: boolean
22720 VirtIODevice started flag
22721 start-on-kick: boolean
22723 VirtIODevice start_on_kick flag
22724 disable-legacy-check: boolean
22726 VirtIODevice disabled_legacy_check flag
22727 bus-name: string
22729 VirtIODevice bus_name
22730 use-guest-notifier-mask: boolean
22732 VirtIODevice use_guest_notifier_mask flag
22733 vhost-dev: VhostStatus (optional)
22735 Corresponding vhost device info for a given VirtIODevice.
22736 Present if the given VirtIODevice has an active vhost device.
22737 Since
22739 7.2
22740 x-query-virtio-status (Command)
22742 Poll for a comprehensive status of a given virtio device
22743 Arguments
22745 path: string
22746 Canonical QOM path of the VirtIODevice
22747 Features
22749 unstable
22750 This command is meant for debugging.
22751 Returns
22753 VirtioStatus of the virtio device
22754 Since
22756 7.2
22757 Examples
22759 1. Poll for the status of virtio-crypto (no vhost-crypto active)
22760 -> { "execute": "x-query-virtio-status",
22762 "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
22763 }
22764 <- { "return": {
22765 "device-endian": "little",
22766 "bus-name": "",
22767 "disable-legacy-check": false,
22768 "name": "virtio-crypto",
22769 "started": true,
22770 "device-id": 20,
22771 "backend-features": {
22772 "transports": [],
22773 "dev-features": []
22774 },
22775 "start-on-kick": false,
22776 "isr": 1,
22777 "broken": false,
22778 "status": {
22779 "statuses": [
22780 "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
22781 "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
22782 "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
22783 "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
22784 ]
22785 },
22786 "num-vqs": 2,
22787 "guest-features": {
22788 "dev-features": [],
22789 "transports": [
22790 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
22791 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
22792 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
22793 ]
22794 },
22795 "host-features": {
22796 "unknown-dev-features": 1073741824,
22797 "dev-features": [],
22798 "transports": [
22799 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
22800 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
22801 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
22802 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
22803 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
22804 ]
22805 },
22806 "use-guest-notifier-mask": true,
22807 "vm-running": true,
22808 "queue-sel": 1,
22809 "disabled": false,
22810 "vhost-started": false,
22811 "use-started": true
22812 }
22813 }
22814 2. Poll for the status of virtio-net (vhost-net is active)
22816 -> { "execute": "x-query-virtio-status",
22818 "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
22819 }
22820 <- { "return": {
22821 "device-endian": "little",
22822 "bus-name": "",
22823 "disabled-legacy-check": false,
22824 "name": "virtio-net",
22825 "started": true,
22826 "device-id": 1,
22827 "vhost-dev": {
22828 "n-tmp-sections": 4,
22829 "n-mem-sections": 4,
22830 "max-queues": 1,
22831 "backend-cap": 2,
22832 "log-size": 0,
22833 "backend-features": {
22834 "dev-features": [],
22835 "transports": []
22836 },
22837 "nvqs": 2,
22838 "protocol-features": {
22839 "protocols": []
22840 },
22841 "vq-index": 0,
22842 "log-enabled": false,
22843 "acked-features": {
22844 "dev-features": [
22845 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
22846 ],
22847 "transports": [
22848 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
22849 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
22850 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
22851 ]
22852 },
22853 "features": {
22854 "dev-features": [
22855 "VHOST_F_LOG_ALL: Logging write descriptors supported",
22856 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
22857 ],
22858 "transports": [
22859 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
22860 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
22861 "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform",
22862 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
22863 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
22864 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
22865 ]
22866 }
22867 },
22868 "backend-features": {
22869 "dev-features": [
22870 "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
22871 "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
22872 "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
22873 "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
22874 "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
22875 "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
22876 "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
22877 "VIRTIO_NET_F_CTRL_VQ: Control channel available",
22878 "VIRTIO_NET_F_STATUS: Configuration status field available",
22879 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
22880 "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
22881 "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
22882 "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
22883 "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
22884 "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
22885 "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
22886 "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
22887 "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
22888 "VIRTIO_NET_F_MAC: Device has given MAC address",
22889 "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
22890 "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
22891 "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
22892 ],
22893 "transports": [
22894 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
22895 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
22896 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
22897 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
22898 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
22899 ]
22900 },
22901 "start-on-kick": false,
22902 "isr": 1,
22903 "broken": false,
22904 "status": {
22905 "statuses": [
22906 "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
22907 "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
22908 "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
22909 "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
22910 ]
22911 },
22912 "num-vqs": 3,
22913 "guest-features": {
22914 "dev-features": [
22915 "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
22916 "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
22917 "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
22918 "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
22919 "VIRTIO_NET_F_CTRL_VQ: Control channel available",
22920 "VIRTIO_NET_F_STATUS: Configuration status field available",
22921 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
22922 "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
22923 "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
22924 "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
22925 "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
22926 "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
22927 "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
22928 "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
22929 "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
22930 "VIRTIO_NET_F_MAC: Device has given MAC address",
22931 "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
22932 "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
22933 "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
22934 ],
22935 "transports": [
22936 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
22937 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
22938 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
22939 ]
22940 },
22941 "host-features": {
22942 "dev-features": [
22943 "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
22944 "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
22945 "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
22946 "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
22947 "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
22948 "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
22949 "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
22950 "VIRTIO_NET_F_CTRL_VQ: Control channel available",
22951 "VIRTIO_NET_F_STATUS: Configuration status field available",
22952 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
22953 "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
22954 "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
22955 "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
22956 "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
22957 "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
22958 "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
22959 "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
22960 "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
22961 "VIRTIO_NET_F_MAC: Device has given MAC address",
22962 "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
22963 "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
22964 "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
22965 ],
22966 "transports": [
22967 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
22968 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
22969 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
22970 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
22971 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
22972 ]
22973 },
22974 "use-guest-notifier-mask": true,
22975 "vm-running": true,
22976 "queue-sel": 2,
22977 "disabled": false,
22978 "vhost-started": true,
22979 "use-started": true
22980 }
22981 }
22982 VirtioDeviceStatus (Object)
22984 A structure defined to list the configuration statuses of a virtio de‐
22985 vice
22986 Members
22988 statuses: array of string
22989 List of decoded configuration statuses of the virtio device
22990 unknown-statuses: int (optional)
22992 Virtio device statuses bitmap that have not been decoded
22993 Since
22995 7.2
22996 VhostDeviceProtocols (Object)
22998 A structure defined to list the vhost user protocol features of a Vhost
22999 User device
23000 Members
23002 protocols: array of string
23003 List of decoded vhost user protocol features of a vhost user de‐
23004 vice
23005 unknown-protocols: int (optional)
23007 Vhost user device protocol features bitmap that have not been
23008 decoded
23009 Since
23011 7.2
23012 VirtioDeviceFeatures (Object)
23014 The common fields that apply to most Virtio devices. Some devices may
23015 not have their own device-specific features (e.g. virtio-rng).
23016 Members
23018 transports: array of string
23019 List of transport features of the virtio device
23020 dev-features: array of string (optional)
23022 List of device-specific features (if the device has unique fea‐
23023 tures)
23024 unknown-dev-features: int (optional)
23026 Virtio device features bitmap that have not been decoded
23027 Since
23029 7.2
23030 VirtQueueStatus (Object)
23032 Information of a VirtIODevice VirtQueue, including most members of the
23033 VirtQueue data structure.
23034 Members
23036 name: string
23037 Name of the VirtIODevice that uses this VirtQueue
23038 queue-index: int
23040 VirtQueue queue_index
23041 inuse: int
23043 VirtQueue inuse
23044 vring-num: int
23046 VirtQueue vring.num
23047 vring-num-default: int
23049 VirtQueue vring.num_default
23050 vring-align: int
23052 VirtQueue vring.align
23053 vring-desc: int
23055 VirtQueue vring.desc (descriptor area)
23056 vring-avail: int
23058 VirtQueue vring.avail (driver area)
23059 vring-used: int
23061 VirtQueue vring.used (device area)
23062 last-avail-idx: int (optional)
23064 VirtQueue last_avail_idx or return of vhost_dev
23065 vhost_get_vring_base (if vhost active)
23066 shadow-avail-idx: int (optional)
23068 VirtQueue shadow_avail_idx
23069 used-idx: int
23071 VirtQueue used_idx
23072 signalled-used: int
23074 VirtQueue signalled_used
23075 signalled-used-valid: boolean
23077 VirtQueue signalled_used_valid flag
23078 Since
23080 7.2
23081 x-query-virtio-queue-status (Command)
23083 Return the status of a given VirtIODevice's VirtQueue
23084 Arguments
23086 path: string
23087 VirtIODevice canonical QOM path
23088 queue: int
23090 VirtQueue index to examine
23091 Features
23093 unstable
23094 This command is meant for debugging.
23095 Returns
23097 VirtQueueStatus of the VirtQueue
23098 Notes
23100 last_avail_idx will not be displayed in the case where the selected
23101 VirtIODevice has a running vhost device and the VirtIODevice VirtQueue
23102 index (queue) does not exist for the corresponding vhost device
23103 vhost_virtqueue. Also, shadow_avail_idx will not be displayed in the
23104 case where the selected VirtIODevice has a running vhost device.
23105 Since
23107 7.2
23108 Examples
23110 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
23111 -> { "execute": "x-query-virtio-queue-status",
23113 "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
23114 "queue": 1 }
23115 }
23116 <- { "return": {
23117 "signalled-used": 0,
23118 "inuse": 0,
23119 "name": "vhost-vsock",
23120 "vring-align": 4096,
23121 "vring-desc": 5217370112,
23122 "signalled-used-valid": false,
23123 "vring-num-default": 128,
23124 "vring-avail": 5217372160,
23125 "queue-index": 1,
23126 "last-avail-idx": 0,
23127 "vring-used": 5217372480,
23128 "used-idx": 0,
23129 "vring-num": 128
23130 }
23131 }
23132 2. Get VirtQueueStatus for virtio-serial (no vhost)
23134 -> { "execute": "x-query-virtio-queue-status",
23136 "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
23137 "queue": 20 }
23138 }
23139 <- { "return": {
23140 "signalled-used": 0,
23141 "inuse": 0,
23142 "name": "virtio-serial",
23143 "vring-align": 4096,
23144 "vring-desc": 5182074880,
23145 "signalled-used-valid": false,
23146 "vring-num-default": 128,
23147 "vring-avail": 5182076928,
23148 "queue-index": 20,
23149 "last-avail-idx": 0,
23150 "vring-used": 5182077248,
23151 "used-idx": 0,
23152 "shadow-avail-idx": 0,
23153 "vring-num": 128
23154 }
23155 }
23156 VirtVhostQueueStatus (Object)
23158 Information of a vhost device's vhost_virtqueue, including most members
23159 of the vhost_dev vhost_virtqueue data structure.
23160 Members
23162 name: string
23163 Name of the VirtIODevice that uses this vhost_virtqueue
23164 kick: int
23166 vhost_virtqueue kick
23167 call: int
23169 vhost_virtqueue call
23170 desc: int
23172 vhost_virtqueue desc
23173 avail: int
23175 vhost_virtqueue avail
23176 used: int
23178 vhost_virtqueue used
23179 num: int
23181 vhost_virtqueue num
23182 desc-phys: int
23184 vhost_virtqueue desc_phys (descriptor area phys. addr.)
23185 desc-size: int
23187 vhost_virtqueue desc_size
23188 avail-phys: int
23190 vhost_virtqueue avail_phys (driver area phys. addr.)
23191 avail-size: int
23193 vhost_virtqueue avail_size
23194 used-phys: int
23196 vhost_virtqueue used_phys (device area phys. addr.)
23197 used-size: int
23199 vhost_virtqueue used_size
23200 Since
23202 7.2
23203 x-query-virtio-vhost-queue-status (Command)
23205 Return information of a given vhost device's vhost_virtqueue
23206 Arguments
23208 path: string
23209 VirtIODevice canonical QOM path
23210 queue: int
23212 vhost_virtqueue index to examine
23213 Features
23215 unstable
23216 This command is meant for debugging.
23217 Returns
23219 VirtVhostQueueStatus of the vhost_virtqueue
23220 Since
23222 7.2
23223 Examples
23225 1. Get vhost_virtqueue status for vhost-crypto
23226 -> { "execute": "x-query-virtio-vhost-queue-status",
23228 "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
23229 "queue": 0 }
23230 }
23231 <- { "return": {
23232 "avail-phys": 5216124928,
23233 "name": "virtio-crypto",
23234 "used-phys": 5216127040,
23235 "avail-size": 2054,
23236 "desc-size": 16384,
23237 "used-size": 8198,
23238 "desc": 140141447430144,
23239 "num": 1024,
23240 "call": 0,
23241 "avail": 140141447446528,
23242 "desc-phys": 5216108544,
23243 "used": 140141447448640,
23244 "kick": 0
23245 }
23246 }
23247 2. Get vhost_virtqueue status for vhost-vsock
23249 -> { "execute": "x-query-virtio-vhost-queue-status",
23251 "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
23252 "queue": 0 }
23253 }
23254 <- { "return": {
23255 "avail-phys": 5182261248,
23256 "name": "vhost-vsock",
23257 "used-phys": 5182261568,
23258 "avail-size": 262,
23259 "desc-size": 2048,
23260 "used-size": 1030,
23261 "desc": 140141413580800,
23262 "num": 128,
23263 "call": 0,
23264 "avail": 140141413582848,
23265 "desc-phys": 5182259200,
23266 "used": 140141413583168,
23267 "kick": 0
23268 }
23269 }
23270 VirtioRingDesc (Object)
23272 Information regarding the vring descriptor area
23273 Members
23275 addr: int
23276 Guest physical address of the descriptor area
23277 len: int
23279 Length of the descriptor area
23280 flags: array of string
23282 List of descriptor flags
23283 Since
23285 7.2
23286 VirtioRingAvail (Object)
23288 Information regarding the avail vring (a.k.a. driver area)
23289 Members
23291 flags: int
23292 VRingAvail flags
23293 idx: int
23295 VRingAvail index
23296 ring: int
23298 VRingAvail ring[] entry at provided index
23299 Since
23301 7.2
23302 VirtioRingUsed (Object)
23304 Information regarding the used vring (a.k.a. device area)
23305 Members
23307 flags: int
23308 VRingUsed flags
23309 idx: int
23311 VRingUsed index
23312 Since
23314 7.2
23315 VirtioQueueElement (Object)
23317 Information regarding a VirtQueue's VirtQueueElement including descrip‐
23318 tor, driver, and device areas
23319 Members
23321 name: string
23322 Name of the VirtIODevice that uses this VirtQueue
23323 index: int
23325 Index of the element in the queue
23326 descs: array of VirtioRingDesc
23328 List of descriptors (VirtioRingDesc)
23329 avail: VirtioRingAvail
23331 VRingAvail info
23332 used: VirtioRingUsed
23334 VRingUsed info
23335 Since
23337 7.2
23338 x-query-virtio-queue-element (Command)
23340 Return the information about a VirtQueue's VirtQueueElement
23341 Arguments
23343 path: string
23344 VirtIODevice canonical QOM path
23345 queue: int
23347 VirtQueue index to examine
23348 index: int (optional)
23350 Index of the element in the queue (default: head of the queue)
23351 Features
23353 unstable
23354 This command is meant for debugging.
23355 Returns
23357 VirtioQueueElement information
23358 Since
23360 7.2
23361 Examples
23363 1. Introspect on virtio-net's VirtQueue 0 at index 5
23364 -> { "execute": "x-query-virtio-queue-element",
23366 "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
23367 "queue": 0,
23368 "index": 5 }
23369 }
23370 <- { "return": {
23371 "index": 5,
23372 "name": "virtio-net",
23373 "descs": [
23374 {
23375 "flags": ["write"],
23376 "len": 1536,
23377 "addr": 5257305600
23378 }
23379 ],
23380 "avail": {
23381 "idx": 256,
23382 "flags": 0,
23383 "ring": 5
23384 },
23385 "used": {
23386 "idx": 13,
23387 "flags": 0
23388 }
23389 }
23390 }
23391 2. Introspect on virtio-crypto's VirtQueue 1 at head
23393 -> { "execute": "x-query-virtio-queue-element",
23395 "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
23396 "queue": 1 }
23397 }
23398 <- { "return": {
23399 "index": 0,
23400 "name": "virtio-crypto",
23401 "descs": [
23402 {
23403 "flags": [],
23404 "len": 0,
23405 "addr": 8080268923184214134
23406 }
23407 ],
23408 "avail": {
23409 "idx": 280,
23410 "flags": 0,
23411 "ring": 0
23412 },
23413 "used": {
23414 "idx": 280,
23415 "flags": 0
23416 }
23417 }
23418 }
23419 3. Introspect on virtio-scsi's VirtQueue 2 at head
23421 -> { "execute": "x-query-virtio-queue-element",
23423 "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
23424 "queue": 2 }
23425 }
23426 <- { "return": {
23427 "index": 19,
23428 "name": "virtio-scsi",
23429 "descs": [
23430 {
23431 "flags": ["used", "indirect", "write"],
23432 "len": 4099327944,
23433 "addr": 12055409292258155293
23434 }
23435 ],
23436 "avail": {
23437 "idx": 1147,
23438 "flags": 0,
23439 "ring": 19
23440 },
23441 "used": {
23442 "idx": 280,
23443 "flags": 0
23444 }
23445 }
23446 }
23447
23449 2023, The QEMU Project Developers
234507.2.6 Sep 26, 2023 QEMU-QMP-REF(7)