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 • QMP errors
16 • QapiErrorClass (Enum)
18 • Common data types
20 • IoOperationType (Enum)
22 • OnOffAuto (Enum)
24 • OnOffSplit (Enum)
26 • String (Object)
28 • StrOrNull (Alternate)
30 • OffAutoPCIBAR (Enum)
32 • PCIELinkSpeed (Enum)
34 • PCIELinkWidth (Enum)
36 • HostMemPolicy (Enum)
38 • NetFilterDirection (Enum)
40 • GrabToggleKeys (Enum)
42 • HumanReadableText (Object)
44 • Socket data types
46 • NetworkAddressFamily (Enum)
48 • InetSocketAddressBase (Object)
50 • InetSocketAddress (Object)
52 • UnixSocketAddress (Object)
54 • VsockSocketAddress (Object)
56 • InetSocketAddressWrapper (Object)
58 • UnixSocketAddressWrapper (Object)
60 • VsockSocketAddressWrapper (Object)
62 • StringWrapper (Object)
64 • SocketAddressLegacy (Object)
66 • SocketAddressType (Enum)
68 • SocketAddress (Object)
70 • VM run state
72 • RunState (Enum)
74 • ShutdownCause (Enum)
76 • StatusInfo (Object)
78 • query-status (Command)
80 • SHUTDOWN (Event)
82 • POWERDOWN (Event)
84 • RESET (Event)
86 • STOP (Event)
88 • RESUME (Event)
90 • SUSPEND (Event)
92 • SUSPEND_DISK (Event)
94 • WAKEUP (Event)
96 • WATCHDOG (Event)
98 • WatchdogAction (Enum)
100 • RebootAction (Enum)
102 • ShutdownAction (Enum)
104 • PanicAction (Enum)
106 • watchdog-set-action (Command)
108 • set-action (Command)
110 • GUEST_PANICKED (Event)
112 • GUEST_CRASHLOADED (Event)
114 • GuestPanicAction (Enum)
116 • GuestPanicInformationType (Enum)
118 • GuestPanicInformation (Object)
120 • GuestPanicInformationHyperV (Object)
122 • S390CrashReason (Enum)
124 • GuestPanicInformationS390 (Object)
126 • MEMORY_FAILURE (Event)
128 • MemoryFailureRecipient (Enum)
130 • MemoryFailureAction (Enum)
132 • MemoryFailureFlags (Object)
134 • NotifyVmexitOption (Enum)
136 • Cryptography
138 • QCryptoTLSCredsEndpoint (Enum)
140 • QCryptoSecretFormat (Enum)
142 • QCryptoHashAlgorithm (Enum)
144 • QCryptoCipherAlgorithm (Enum)
146 • QCryptoCipherMode (Enum)
148 • QCryptoIVGenAlgorithm (Enum)
150 • QCryptoBlockFormat (Enum)
152 • QCryptoBlockOptionsBase (Object)
154 • QCryptoBlockOptionsQCow (Object)
156 • QCryptoBlockOptionsLUKS (Object)
158 • QCryptoBlockCreateOptionsLUKS (Object)
160 • QCryptoBlockOpenOptions (Object)
162 • QCryptoBlockCreateOptions (Object)
164 • QCryptoBlockInfoBase (Object)
166 • QCryptoBlockInfoLUKSSlot (Object)
168 • QCryptoBlockInfoLUKS (Object)
170 • QCryptoBlockInfo (Object)
172 • QCryptoBlockLUKSKeyslotState (Enum)
174 • QCryptoBlockAmendOptionsLUKS (Object)
176 • QCryptoBlockAmendOptions (Object)
178 • SecretCommonProperties (Object)
180 • SecretProperties (Object)
182 • SecretKeyringProperties (Object)
184 • TlsCredsProperties (Object)
186 • TlsCredsAnonProperties (Object)
188 • TlsCredsPskProperties (Object)
190 • TlsCredsX509Properties (Object)
192 • QCryptoAkCipherAlgorithm (Enum)
194 • QCryptoAkCipherKeyType (Enum)
196 • QCryptoRSAPaddingAlgorithm (Enum)
198 • QCryptoAkCipherOptionsRSA (Object)
200 • QCryptoAkCipherOptions (Object)
202 • Background jobs
204 • JobType (Enum)
206 • JobStatus (Enum)
208 • JobVerb (Enum)
210 • JOB_STATUS_CHANGE (Event)
212 • job-pause (Command)
214 • job-resume (Command)
216 • job-cancel (Command)
218 • job-complete (Command)
220 • job-dismiss (Command)
222 • job-finalize (Command)
224 • JobInfo (Object)
226 • query-jobs (Command)
228 • Block devices
230 • Block core (VM unrelated)
232 • Additional block stuff (VM related)
234 • Block device exports
236 • Character devices
238 • ChardevInfo (Object)
240 • query-chardev (Command)
242 • ChardevBackendInfo (Object)
244 • query-chardev-backends (Command)
246 • DataFormat (Enum)
248 • ringbuf-write (Command)
250 • ringbuf-read (Command)
252 • ChardevCommon (Object)
254 • ChardevFile (Object)
256 • ChardevHostdev (Object)
258 • ChardevSocket (Object)
260 • ChardevUdp (Object)
262 • ChardevMux (Object)
264 • ChardevStdio (Object)
266 • ChardevSpiceChannel (Object)
268 • ChardevSpicePort (Object)
270 • ChardevDBus (Object)
272 • ChardevVC (Object)
274 • ChardevRingbuf (Object)
276 • ChardevQemuVDAgent (Object)
278 • ChardevBackendKind (Enum)
280 • ChardevFileWrapper (Object)
282 • ChardevHostdevWrapper (Object)
284 • ChardevSocketWrapper (Object)
286 • ChardevUdpWrapper (Object)
288 • ChardevCommonWrapper (Object)
290 • ChardevMuxWrapper (Object)
292 • ChardevStdioWrapper (Object)
294 • ChardevSpiceChannelWrapper (Object)
296 • ChardevSpicePortWrapper (Object)
298 • ChardevQemuVDAgentWrapper (Object)
300 • ChardevDBusWrapper (Object)
302 • ChardevVCWrapper (Object)
304 • ChardevRingbufWrapper (Object)
306 • ChardevBackend (Object)
308 • ChardevReturn (Object)
310 • chardev-add (Command)
312 • chardev-change (Command)
314 • chardev-remove (Command)
316 • chardev-send-break (Command)
318 • VSERPORT_CHANGE (Event)
320 • Dump guest memory
322 • DumpGuestMemoryFormat (Enum)
324 • dump-guest-memory (Command)
326 • DumpStatus (Enum)
328 • DumpQueryResult (Object)
330 • query-dump (Command)
332 • DUMP_COMPLETED (Event)
334 • DumpGuestMemoryCapability (Object)
336 • query-dump-guest-memory-capability (Command)
338 • Net devices
340 • set_link (Command)
342 • netdev_add (Command)
344 • netdev_del (Command)
346 • NetLegacyNicOptions (Object)
348 • NetdevUserOptions (Object)
350 • NetdevTapOptions (Object)
352 • NetdevSocketOptions (Object)
354 • NetdevL2TPv3Options (Object)
356 • NetdevVdeOptions (Object)
358 • NetdevBridgeOptions (Object)
360 • NetdevHubPortOptions (Object)
362 • NetdevNetmapOptions (Object)
364 • NetdevVhostUserOptions (Object)
366 • NetdevVhostVDPAOptions (Object)
368 • NetdevVmnetHostOptions (Object)
370 • NetdevVmnetSharedOptions (Object)
372 • NetdevVmnetBridgedOptions (Object)
374 • NetdevStreamOptions (Object)
376 • NetdevDgramOptions (Object)
378 • NetClientDriver (Enum)
380 • Netdev (Object)
382 • RxState (Enum)
384 • RxFilterInfo (Object)
386 • query-rx-filter (Command)
388 • NIC_RX_FILTER_CHANGED (Event)
390 • AnnounceParameters (Object)
392 • announce-self (Command)
394 • FAILOVER_NEGOTIATED (Event)
396 • NETDEV_STREAM_CONNECTED (Event)
398 • NETDEV_STREAM_DISCONNECTED (Event)
400 • RDMA device
402 • RDMA_GID_STATUS_CHANGED (Event)
404 • Rocker switch device
406 • RockerSwitch (Object)
408 • query-rocker (Command)
410 • RockerPortDuplex (Enum)
412 • RockerPortAutoneg (Enum)
414 • RockerPort (Object)
416 • query-rocker-ports (Command)
418 • RockerOfDpaFlowKey (Object)
420 • RockerOfDpaFlowMask (Object)
422 • RockerOfDpaFlowAction (Object)
424 • RockerOfDpaFlow (Object)
426 • query-rocker-of-dpa-flows (Command)
428 • RockerOfDpaGroup (Object)
430 • query-rocker-of-dpa-groups (Command)
432 • TPM (trusted platform module) devices
434 • TpmModel (Enum)
436 • query-tpm-models (Command)
438 • TpmType (Enum)
440 • query-tpm-types (Command)
442 • TPMPassthroughOptions (Object)
444 • TPMEmulatorOptions (Object)
446 • TPMPassthroughOptionsWrapper (Object)
448 • TPMEmulatorOptionsWrapper (Object)
450 • TpmTypeOptions (Object)
452 • TPMInfo (Object)
454 • query-tpm (Command)
456 • Remote desktop
458 • DisplayProtocol (Enum)
460 • SetPasswordAction (Enum)
462 • SetPasswordOptions (Object)
464 • SetPasswordOptionsVnc (Object)
466 • set_password (Command)
468 • ExpirePasswordOptions (Object)
470 • ExpirePasswordOptionsVnc (Object)
472 • expire_password (Command)
474 • ImageFormat (Enum)
476 • screendump (Command)
478 • Spice
480 • VNC
482 • Input
484 • MouseInfo (Object)
486 • query-mice (Command)
488 • QKeyCode (Enum)
490 • KeyValueKind (Enum)
492 • IntWrapper (Object)
494 • QKeyCodeWrapper (Object)
496 • KeyValue (Object)
498 • send-key (Command)
500 • InputButton (Enum)
502 • InputAxis (Enum)
504 • InputMultiTouchType (Enum)
506 • InputKeyEvent (Object)
508 • InputBtnEvent (Object)
510 • InputMoveEvent (Object)
512 • InputMultiTouchEvent (Object)
514 • InputEventKind (Enum)
516 • InputKeyEventWrapper (Object)
518 • InputBtnEventWrapper (Object)
520 • InputMoveEventWrapper (Object)
522 • InputMultiTouchEventWrapper (Object)
524 • InputEvent (Object)
526 • input-send-event (Command)
528 • DisplayGTK (Object)
530 • DisplayEGLHeadless (Object)
532 • DisplayDBus (Object)
534 • DisplayGLMode (Enum)
536 • DisplayCurses (Object)
538 • DisplayCocoa (Object)
540 • HotKeyMod (Enum)
542 • DisplaySDL (Object)
544 • DisplayType (Enum)
546 • DisplayOptions (Object)
548 • query-display-options (Command)
550 • DisplayReloadType (Enum)
552 • DisplayReloadOptionsVNC (Object)
554 • DisplayReloadOptions (Object)
556 • display-reload (Command)
558 • DisplayUpdateType (Enum)
560 • DisplayUpdateOptionsVNC (Object)
562 • DisplayUpdateOptions (Object)
564 • display-update (Command)
566 • client_migrate_info (Command)
568 • User authorization
570 • QAuthZListPolicy (Enum)
572 • QAuthZListFormat (Enum)
574 • QAuthZListRule (Object)
576 • AuthZListProperties (Object)
578 • AuthZListFileProperties (Object)
580 • AuthZPAMProperties (Object)
582 • AuthZSimpleProperties (Object)
584 • Migration
586 • MigrationStats (Object)
588 • XBZRLECacheStats (Object)
590 • CompressionStats (Object)
592 • MigrationStatus (Enum)
594 • VfioStats (Object)
596 • MigrationInfo (Object)
598 • query-migrate (Command)
600 • MigrationCapability (Enum)
602 • MigrationCapabilityStatus (Object)
604 • migrate-set-capabilities (Command)
606 • query-migrate-capabilities (Command)
608 • MultiFDCompression (Enum)
610 • BitmapMigrationBitmapAliasTransform (Object)
612 • BitmapMigrationBitmapAlias (Object)
614 • BitmapMigrationNodeAlias (Object)
616 • MigrationParameter (Enum)
618 • MigrateSetParameters (Object)
620 • migrate-set-parameters (Command)
622 • MigrationParameters (Object)
624 • query-migrate-parameters (Command)
626 • migrate-start-postcopy (Command)
628 • MIGRATION (Event)
630 • MIGRATION_PASS (Event)
632 • COLOMessage (Enum)
634 • COLOMode (Enum)
636 • FailoverStatus (Enum)
638 • COLO_EXIT (Event)
640 • COLOExitReason (Enum)
642 • x-colo-lost-heartbeat (Command)
644 • migrate_cancel (Command)
646 • migrate-continue (Command)
648 • migrate (Command)
650 • migrate-incoming (Command)
652 • xen-save-devices-state (Command)
654 • xen-set-global-dirty-log (Command)
656 • xen-load-devices-state (Command)
658 • xen-set-replication (Command)
660 • ReplicationStatus (Object)
662 • query-xen-replication-status (Command)
664 • xen-colo-do-checkpoint (Command)
666 • COLOStatus (Object)
668 • query-colo-status (Command)
670 • migrate-recover (Command)
672 • migrate-pause (Command)
674 • UNPLUG_PRIMARY (Event)
676 • DirtyRateVcpu (Object)
678 • DirtyRateStatus (Enum)
680 • DirtyRateMeasureMode (Enum)
682 • DirtyRateInfo (Object)
684 • calc-dirty-rate (Command)
686 • query-dirty-rate (Command)
688 • DirtyLimitInfo (Object)
690 • set-vcpu-dirty-limit (Command)
692 • cancel-vcpu-dirty-limit (Command)
694 • query-vcpu-dirty-limit (Command)
696 • MigrationThreadInfo (Object)
698 • query-migrationthreads (Command)
700 • snapshot-save (Command)
702 • snapshot-load (Command)
704 • snapshot-delete (Command)
706 • Transactions
708 • Abort (Object)
710 • ActionCompletionMode (Enum)
712 • TransactionActionKind (Enum)
714 • AbortWrapper (Object)
716 • BlockDirtyBitmapAddWrapper (Object)
718 • BlockDirtyBitmapWrapper (Object)
720 • BlockDirtyBitmapMergeWrapper (Object)
722 • BlockdevBackupWrapper (Object)
724 • BlockdevSnapshotWrapper (Object)
726 • BlockdevSnapshotInternalWrapper (Object)
728 • BlockdevSnapshotSyncWrapper (Object)
730 • DriveBackupWrapper (Object)
732 • TransactionAction (Object)
734 • TransactionProperties (Object)
736 • transaction (Command)
738 • Tracing
740 • TraceEventState (Enum)
742 • TraceEventInfo (Object)
744 • trace-event-get-state (Command)
746 • trace-event-set-state (Command)
748 • Compatibility policy
750 • CompatPolicyInput (Enum)
752 • CompatPolicyOutput (Enum)
754 • CompatPolicy (Object)
756 • QMP monitor control
758 • qmp_capabilities (Command)
760 • QMPCapability (Enum)
762 • VersionTriple (Object)
764 • VersionInfo (Object)
766 • query-version (Command)
768 • CommandInfo (Object)
770 • query-commands (Command)
772 • quit (Command)
774 • MonitorMode (Enum)
776 • MonitorOptions (Object)
778 • QMP introspection
780 • query-qmp-schema (Command)
782 • SchemaMetaType (Enum)
784 • SchemaInfo (Object)
786 • SchemaInfoBuiltin (Object)
788 • JSONType (Enum)
790 • SchemaInfoEnum (Object)
792 • SchemaInfoEnumMember (Object)
794 • SchemaInfoArray (Object)
796 • SchemaInfoObject (Object)
798 • SchemaInfoObjectMember (Object)
800 • SchemaInfoObjectVariant (Object)
802 • SchemaInfoAlternate (Object)
804 • SchemaInfoAlternateMember (Object)
806 • SchemaInfoCommand (Object)
808 • SchemaInfoEvent (Object)
810 • QEMU Object Model (QOM)
812 • ObjectPropertyInfo (Object)
814 • qom-list (Command)
816 • qom-get (Command)
818 • qom-set (Command)
820 • ObjectTypeInfo (Object)
822 • qom-list-types (Command)
824 • qom-list-properties (Command)
826 • CanHostSocketcanProperties (Object)
828 • ColoCompareProperties (Object)
830 • CryptodevBackendProperties (Object)
832 • CryptodevVhostUserProperties (Object)
834 • DBusVMStateProperties (Object)
836 • NetfilterInsert (Enum)
838 • NetfilterProperties (Object)
840 • FilterBufferProperties (Object)
842 • FilterDumpProperties (Object)
844 • FilterMirrorProperties (Object)
846 • FilterRedirectorProperties (Object)
848 • FilterRewriterProperties (Object)
850 • InputBarrierProperties (Object)
852 • InputLinuxProperties (Object)
854 • EventLoopBaseProperties (Object)
856 • IothreadProperties (Object)
858 • MainLoopProperties (Object)
860 • MemoryBackendProperties (Object)
862 • MemoryBackendFileProperties (Object)
864 • MemoryBackendMemfdProperties (Object)
866 • MemoryBackendEpcProperties (Object)
868 • PrManagerHelperProperties (Object)
870 • QtestProperties (Object)
872 • RemoteObjectProperties (Object)
874 • VfioUserServerProperties (Object)
876 • RngProperties (Object)
878 • RngEgdProperties (Object)
880 • RngRandomProperties (Object)
882 • SevGuestProperties (Object)
884 • ThreadContextProperties (Object)
886 • ObjectType (Enum)
888 • ObjectOptions (Object)
890 • object-add (Command)
892 • object-del (Command)
894 • Device infrastructure (qdev)
896 • device-list-properties (Command)
898 • device_add (Command)
900 • device_del (Command)
902 • DEVICE_DELETED (Event)
904 • DEVICE_UNPLUG_GUEST_ERROR (Event)
906 • Machines
908 • SysEmuTarget (Enum)
910 • CpuS390State (Enum)
912 • CpuInfoS390 (Object)
914 • CpuInfoFast (Object)
916 • query-cpus-fast (Command)
918 • MachineInfo (Object)
920 • query-machines (Command)
922 • CurrentMachineParams (Object)
924 • query-current-machine (Command)
926 • TargetInfo (Object)
928 • query-target (Command)
930 • UuidInfo (Object)
932 • query-uuid (Command)
934 • GuidInfo (Object)
936 • query-vm-generation-id (Command)
938 • system_reset (Command)
940 • system_powerdown (Command)
942 • system_wakeup (Command)
944 • LostTickPolicy (Enum)
946 • inject-nmi (Command)
948 • KvmInfo (Object)
950 • query-kvm (Command)
952 • NumaOptionsType (Enum)
954 • NumaOptions (Object)
956 • NumaNodeOptions (Object)
958 • NumaDistOptions (Object)
960 • CXLFixedMemoryWindowOptions (Object)
962 • CXLFMWProperties (Object)
964 • X86CPURegister32 (Enum)
966 • X86CPUFeatureWordInfo (Object)
968 • DummyForceArrays (Object)
970 • NumaCpuOptions (Object)
972 • HmatLBMemoryHierarchy (Enum)
974 • HmatLBDataType (Enum)
976 • NumaHmatLBOptions (Object)
978 • HmatCacheAssociativity (Enum)
980 • HmatCacheWritePolicy (Enum)
982 • NumaHmatCacheOptions (Object)
984 • memsave (Command)
986 • pmemsave (Command)
988 • Memdev (Object)
990 • query-memdev (Command)
992 • CpuInstanceProperties (Object)
994 • HotpluggableCPU (Object)
996 • query-hotpluggable-cpus (Command)
998 • set-numa-node (Command)
1000 • balloon (Command)
1002 • BalloonInfo (Object)
1004 • query-balloon (Command)
1006 • BALLOON_CHANGE (Event)
1008 • MemoryInfo (Object)
1010 • query-memory-size-summary (Command)
1012 • PCDIMMDeviceInfo (Object)
1014 • VirtioPMEMDeviceInfo (Object)
1016 • VirtioMEMDeviceInfo (Object)
1018 • SgxEPCDeviceInfo (Object)
1020 • MemoryDeviceInfoKind (Enum)
1022 • PCDIMMDeviceInfoWrapper (Object)
1024 • VirtioPMEMDeviceInfoWrapper (Object)
1026 • VirtioMEMDeviceInfoWrapper (Object)
1028 • SgxEPCDeviceInfoWrapper (Object)
1030 • MemoryDeviceInfo (Object)
1032 • SgxEPC (Object)
1034 • SgxEPCProperties (Object)
1036 • query-memory-devices (Command)
1038 • MEMORY_DEVICE_SIZE_CHANGE (Event)
1040 • MEM_UNPLUG_ERROR (Event)
1042 • BootConfiguration (Object)
1044 • SMPConfiguration (Object)
1046 • x-query-irq (Command)
1048 • x-query-jit (Command)
1050 • x-query-numa (Command)
1052 • x-query-opcount (Command)
1054 • x-query-ramblock (Command)
1056 • x-query-rdma (Command)
1058 • x-query-roms (Command)
1060 • x-query-usb (Command)
1062 • SmbiosEntryPointType (Enum)
1064 • MemorySizeConfiguration (Object)
1066 • dumpdtb (Command)
1068 • CpuModelInfo (Object)
1070 • CpuModelExpansionType (Enum)
1072 • CpuModelCompareResult (Enum)
1074 • CpuModelBaselineInfo (Object)
1076 • CpuModelCompareInfo (Object)
1078 • query-cpu-model-comparison (Command)
1080 • query-cpu-model-baseline (Command)
1082 • CpuModelExpansionInfo (Object)
1084 • query-cpu-model-expansion (Command)
1086 • CpuDefinitionInfo (Object)
1088 • query-cpu-definitions (Command)
1090 • Record/replay
1092 • ReplayMode (Enum)
1094 • ReplayInfo (Object)
1096 • query-replay (Command)
1098 • replay-break (Command)
1100 • replay-delete-break (Command)
1102 • replay-seek (Command)
1104 • Yank feature
1106 • YankInstanceType (Enum)
1108 • YankInstanceBlockNode (Object)
1110 • YankInstanceChardev (Object)
1112 • YankInstance (Object)
1114 • yank (Command)
1116 • query-yank (Command)
1118 • Miscellanea
1120 • add_client (Command)
1122 • NameInfo (Object)
1124 • query-name (Command)
1126 • IOThreadInfo (Object)
1128 • query-iothreads (Command)
1130 • stop (Command)
1132 • cont (Command)
1134 • x-exit-preconfig (Command)
1136 • human-monitor-command (Command)
1138 • getfd (Command)
1140 • get-win32-socket (Command)
1142 • closefd (Command)
1144 • AddfdInfo (Object)
1146 • add-fd (Command)
1148 • remove-fd (Command)
1150 • FdsetFdInfo (Object)
1152 • FdsetInfo (Object)
1154 • query-fdsets (Command)
1156 • CommandLineParameterType (Enum)
1158 • CommandLineParameterInfo (Object)
1160 • CommandLineOptionInfo (Object)
1162 • query-command-line-options (Command)
1164 • RTC_CHANGE (Event)
1166 • VFU_CLIENT_HANGUP (Event)
1168 • rtc-reset-reinjection (Command)
1170 • SevState (Enum)
1172 • SevInfo (Object)
1174 • query-sev (Command)
1176 • SevLaunchMeasureInfo (Object)
1178 • query-sev-launch-measure (Command)
1180 • SevCapability (Object)
1182 • query-sev-capabilities (Command)
1184 • sev-inject-launch-secret (Command)
1186 • SevAttestationReport (Object)
1188 • query-sev-attestation-report (Command)
1190 • dump-skeys (Command)
1192 • GICCapability (Object)
1194 • query-gic-capabilities (Command)
1196 • SGXEPCSection (Object)
1198 • SGXInfo (Object)
1200 • query-sgx (Command)
1202 • query-sgx-capabilities (Command)
1204 • EvtchnPortType (Enum)
1206 • EvtchnInfo (Object)
1208 • xen-event-list (Command)
1210 • xen-event-inject (Command)
1212 • Audio
1214 • AudiodevPerDirectionOptions (Object)
1216 • AudiodevGenericOptions (Object)
1218 • AudiodevAlsaPerDirectionOptions (Object)
1220 • AudiodevAlsaOptions (Object)
1222 • AudiodevSndioOptions (Object)
1224 • AudiodevCoreaudioPerDirectionOptions (Object)
1226 • AudiodevCoreaudioOptions (Object)
1228 • AudiodevDsoundOptions (Object)
1230 • AudiodevJackPerDirectionOptions (Object)
1232 • AudiodevJackOptions (Object)
1234 • AudiodevOssPerDirectionOptions (Object)
1236 • AudiodevOssOptions (Object)
1238 • AudiodevPaPerDirectionOptions (Object)
1240 • AudiodevPaOptions (Object)
1242 • AudiodevPipewirePerDirectionOptions (Object)
1244 • AudiodevPipewireOptions (Object)
1246 • AudiodevSdlPerDirectionOptions (Object)
1248 • AudiodevSdlOptions (Object)
1250 • AudiodevWavOptions (Object)
1252 • AudioFormat (Enum)
1254 • AudiodevDriver (Enum)
1256 • Audiodev (Object)
1258 • query-audiodevs (Command)
1260 • ACPI
1262 • AcpiTableOptions (Object)
1264 • ACPISlotType (Enum)
1266 • ACPIOSTInfo (Object)
1268 • query-acpi-ospm-status (Command)
1270 • ACPI_DEVICE_OST (Event)
1272 • PCI
1274 • PciMemoryRange (Object)
1276 • PciMemoryRegion (Object)
1278 • PciBusInfo (Object)
1280 • PciBridgeInfo (Object)
1282 • PciDeviceClass (Object)
1284 • PciDeviceId (Object)
1286 • PciDeviceInfo (Object)
1288 • PciInfo (Object)
1290 • query-pci (Command)
1292 • Statistics
1294 • StatsType (Enum)
1296 • StatsUnit (Enum)
1298 • StatsProvider (Enum)
1300 • StatsTarget (Enum)
1302 • StatsRequest (Object)
1304 • StatsVCPUFilter (Object)
1306 • StatsFilter (Object)
1308 • StatsValue (Alternate)
1310 • Stats (Object)
1312 • StatsResult (Object)
1314 • query-stats (Command)
1316 • StatsSchemaValue (Object)
1318 • StatsSchema (Object)
1320 • query-stats-schemas (Command)
1322 • Virtio devices
1324 • VirtioInfo (Object)
1326 • x-query-virtio (Command)
1328 • VhostStatus (Object)
1330 • VirtioStatus (Object)
1332 • x-query-virtio-status (Command)
1334 • VirtioDeviceStatus (Object)
1336 • VhostDeviceProtocols (Object)
1338 • VirtioDeviceFeatures (Object)
1340 • VirtQueueStatus (Object)
1342 • x-query-virtio-queue-status (Command)
1344 • VirtVhostQueueStatus (Object)
1346 • x-query-virtio-vhost-queue-status (Command)
1348 • VirtioRingDesc (Object)
1350 • VirtioRingAvail (Object)
1352 • VirtioRingUsed (Object)
1354 • VirtioQueueElement (Object)
1356 • x-query-virtio-queue-element (Command)
1358 • Cryptography devices
1360 • QCryptodevBackendAlgType (Enum)
1362 • QCryptodevBackendServiceType (Enum)
1364 • QCryptodevBackendType (Enum)
1366 • QCryptodevBackendClient (Object)
1368 • QCryptodevInfo (Object)
1370 • query-cryptodev (Command)
1372 • CXL devices
1374 • CxlEventLog (Enum)
1376 • cxl-inject-general-media-event (Command)
1378 • cxl-inject-dram-event (Command)
1380 • cxl-inject-memory-module-event (Command)
1382 • cxl-inject-poison (Command)
1384 • CxlUncorErrorType (Enum)
1386 • CXLUncorErrorRecord (Object)
1388 • cxl-inject-uncorrectable-errors (Command)
1390 • CxlCorErrorType (Enum)
1392 • cxl-inject-correctable-error (Command)
1394
1396 This document describes all commands currently supported by QMP.
1397 Most of the time their usage is exactly the same as in the user Moni‐
1399 tor, this means that any other document which also describe commands
1400 (the manpage, QEMU's manual, etc) can and should be consulted.
1401 QMP has two types of commands: regular and query commands. Regular
1403 commands usually change the Virtual Machine's state someway, while
1404 query commands just return information. The sections below are divided
1405 accordingly.
1406 It's important to observe that all communication examples are formatted
1408 in a reader-friendly way, so that they're easier to understand. How‐
1409 ever, in real protocol usage, they're emitted as a single line.
1410 Also, the following notation is used to denote data flow:
1412 Example:
1414 -> data issued by the Client
1416 <- Server data response
1417 Please refer to the QEMU Machine Protocol Specification for detailed
1419 information on the Server command and response formats.
1420
1422 QapiErrorClass (Enum)
1423 QEMU error classes
1424 Values
1426 GenericError
1427 this is used for errors that don't require a specific error
1428 class. This should be the default case for most errors
1429 CommandNotFound
1431 the requested command has not been found
1432 DeviceNotActive
1434 a device has failed to be become active
1435 DeviceNotFound
1437 the requested device has not been found
1438 KVMMissingCap
1440 the requested operation can't be fulfilled because a required
1441 KVM capability is missing
1442 Since
1444 1.2
1445
1447 IoOperationType (Enum)
1448 An enumeration of the I/O operation types
1449 Values
1451 read read operation
1452 write write operation
1454 Since
1456 2.1
1457 OnOffAuto (Enum)
1459 An enumeration of three options: on, off, and auto
1460 Values
1462 auto QEMU selects the value between on and off
1463 on Enabled
1465 off Disabled
1467 Since
1469 2.2
1470 OnOffSplit (Enum)
1472 An enumeration of three values: on, off, and split
1473 Values
1475 on Enabled
1476 off Disabled
1478 split Mixed
1480 Since
1482 2.6
1483 String (Object)
1485 A fat type wrapping 'str', to be embedded in lists.
1486 Members
1488 str: string
1489 Not documented
1490 Since
1492 1.2
1493 StrOrNull (Alternate)
1495 This is a string value or the explicit lack of a string (null pointer
1496 in C). Intended for cases when 'optional absent' already has a differ‐
1497 ent meaning.
1498 Members
1500 s: string
1501 the string value
1502 n: null
1504 no string value
1505 Since
1507 2.10
1508 OffAutoPCIBAR (Enum)
1510 An enumeration of options for specifying a PCI BAR
1511 Values
1513 off The specified feature is disabled
1514 auto The PCI BAR for the feature is automatically selected
1516 bar0 PCI BAR0 is used for the feature
1518 bar1 PCI BAR1 is used for the feature
1520 bar2 PCI BAR2 is used for the feature
1522 bar3 PCI BAR3 is used for the feature
1524 bar4 PCI BAR4 is used for the feature
1526 bar5 PCI BAR5 is used for the feature
1528 Since
1530 2.12
1531 PCIELinkSpeed (Enum)
1533 An enumeration of PCIe link speeds in units of GT/s
1534 Values
1536 2_5 2.5GT/s
1537 5 5.0GT/s
1539 8 8.0GT/s
1541 16 16.0GT/s
1543 Since
1545 4.0
1546 PCIELinkWidth (Enum)
1548 An enumeration of PCIe link width
1549 Values
1551 1 x1
1552 2 x2
1554 4 x4
1556 8 x8
1558 12 x12
1560 16 x16
1562 32 x32
1564 Since
1566 4.0
1567 HostMemPolicy (Enum)
1569 Host memory policy types
1570 Values
1572 default
1573 restore default policy, remove any nondefault policy
1574 preferred
1576 set the preferred host nodes for allocation
1577 bind a strict policy that restricts memory allocation to the host
1579 nodes specified
1580 interleave
1582 memory allocations are interleaved across the set of host nodes
1583 specified
1584 Since
1586 2.1
1587 NetFilterDirection (Enum)
1589 Indicates whether a netfilter is attached to a netdev's transmit queue
1590 or receive queue or both.
1591 Values
1593 all the filter is attached both to the receive and the transmit
1594 queue of the netdev (default).
1595 rx the filter is attached to the receive queue of the netdev, where
1597 it will receive packets sent to the netdev.
1598 tx the filter is attached to the transmit queue of the netdev,
1600 where it will receive packets sent by the netdev.
1601 Since
1603 2.5
1604 GrabToggleKeys (Enum)
1606 Keys to toggle input-linux between host and guest.
1607 Values
1609 ctrl-ctrl
1610 Not documented
1611 alt-alt
1613 Not documented
1614 shift-shift
1616 Not documented
1617 meta-meta
1619 Not documented
1620 scrolllock
1622 Not documented
1623 ctrl-scrolllock
1625 Not documented
1626 Since
1628 4.0
1629 HumanReadableText (Object)
1631 Members
1632 human-readable-text: string
1633 Formatted output intended for humans.
1634 Since
1636 6.2
1637
1639 NetworkAddressFamily (Enum)
1640 The network address family
1641 Values
1643 ipv4 IPV4 family
1644 ipv6 IPV6 family
1646 unix unix socket
1648 vsock vsock family (since 2.8)
1650 unknown
1652 otherwise
1653 Since
1655 2.1
1656 InetSocketAddressBase (Object)
1658 Members
1659 host: string
1660 host part of the address
1661 port: string
1663 port part of the address
1664 InetSocketAddress (Object)
1666 Captures a socket address or address range in the Internet namespace.
1667 Members
1669 numeric: boolean (optional)
1670 true if the host/port are guaranteed to be numeric, false if
1671 name resolution should be attempted. Defaults to false. (Since
1672 2.9)
1673 to: int (optional)
1675 If present, this is range of possible addresses, with port be‐
1676 tween port and to.
1677 ipv4: boolean (optional)
1679 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1680 ipv6: boolean (optional)
1682 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1683 keep-alive: boolean (optional)
1685 enable keep-alive when connecting to this socket. Not supported
1686 for passive sockets. (Since 4.2)
1687 mptcp: boolean (optional) (If: HAVE_IPPROTO_MPTCP)
1689 enable multi-path TCP. (Since 6.1)
1690 The members of InetSocketAddressBase
1692 Since
1694 1.3
1695 UnixSocketAddress (Object)
1697 Captures a socket address in the local ("Unix socket") namespace.
1698 Members
1700 path: string
1701 filesystem path to use
1702 abstract: boolean (optional) (If: CONFIG_LINUX)
1704 if true, this is a Linux abstract socket address. path will be
1705 prefixed by a null byte, and optionally padded with null bytes.
1706 Defaults to false. (Since 5.1)
1707 tight: boolean (optional) (If: CONFIG_LINUX)
1709 if false, pad an abstract socket address with enough null bytes
1710 to make it fill struct sockaddr_un member sun_path. Defaults to
1711 true. (Since 5.1)
1712 Since
1714 1.3
1715 VsockSocketAddress (Object)
1717 Captures a socket address in the vsock namespace.
1718 Members
1720 cid: string
1721 unique host identifier
1722 port: string
1724 port
1725 Note
1727 string types are used to allow for possible future hostname or service
1728 resolution support.
1729 Since
1731 2.8
1732 InetSocketAddressWrapper (Object)
1734 Members
1735 data: InetSocketAddress
1736 Not documented
1737 Since
1739 1.3
1740 UnixSocketAddressWrapper (Object)
1742 Members
1743 data: UnixSocketAddress
1744 Not documented
1745 Since
1747 1.3
1748 VsockSocketAddressWrapper (Object)
1750 Members
1751 data: VsockSocketAddress
1752 Not documented
1753 Since
1755 2.8
1756 StringWrapper (Object)
1758 Members
1759 data: String
1760 Not documented
1761 Since
1763 1.3
1764 SocketAddressLegacy (Object)
1766 Captures the address of a socket, which could also be a named file de‐
1767 scriptor
1768 Members
1770 type: SocketAddressType
1771 Not documented
1772 The members of InetSocketAddressWrapper when type is "inet"
1774 The members of UnixSocketAddressWrapper when type is "unix"
1776 The members of VsockSocketAddressWrapper when type is "vsock"
1778 The members of StringWrapper when type is "fd"
1780 Note
1782 This type is deprecated in favor of SocketAddress. The difference be‐
1783 tween SocketAddressLegacy and SocketAddress is that the latter has
1784 fewer {} on the wire.
1785 Since
1787 1.3
1788 SocketAddressType (Enum)
1790 Available SocketAddress types
1791 Values
1793 inet Internet address
1794 unix Unix domain socket
1796 vsock VMCI address
1798 fd decimal is for file descriptor number, otherwise a file descrip‐
1800 tor name. Named file descriptors are permitted in monitor com‐
1801 mands, in combination with the 'getfd' command. Decimal file
1802 descriptors are permitted at startup or other contexts where no
1803 monitor context is active.
1804 Since
1806 2.9
1807 SocketAddress (Object)
1809 Captures the address of a socket, which could also be a named file de‐
1810 scriptor
1811 Members
1813 type: SocketAddressType
1814 Transport type
1815 The members of InetSocketAddress when type is "inet"
1817 The members of UnixSocketAddress when type is "unix"
1819 The members of VsockSocketAddress when type is "vsock"
1821 The members of String when type is "fd"
1823 Since
1825 2.9
1826
1828 RunState (Enum)
1829 An enumeration of VM run states.
1830 Values
1832 debug QEMU is running on a debugger
1833 finish-migrate
1835 guest is paused to finish the migration process
1836 inmigrate
1838 guest is paused waiting for an incoming migration. Note that
1839 this state does not tell whether the machine will start at the
1840 end of the migration. This depends on the command-line -S op‐
1841 tion and any invocation of 'stop' or 'cont' that has happened
1842 since QEMU was started.
1843 internal-error
1845 An internal error that prevents further guest execution has oc‐
1846 curred
1847 io-error
1849 the last IOP has failed and the device is configured to pause on
1850 I/O errors
1851 paused guest has been paused via the 'stop' command
1853 postmigrate
1855 guest is paused following a successful 'migrate'
1856 prelaunch
1858 QEMU was started with -S and guest has not started
1859 restore-vm
1861 guest is paused to restore VM state
1862 running
1864 guest is actively running
1865 save-vm
1867 guest is paused to save the VM state
1868 shutdown
1870 guest is shut down (and -no-shutdown is in use)
1871 suspended
1873 guest is suspended (ACPI S3)
1874 watchdog
1876 the watchdog action is configured to pause and has been trig‐
1877 gered
1878 guest-panicked
1880 guest has been panicked as a result of guest OS panic
1881 colo guest is paused to save/restore VM state under colo checkpoint,
1883 VM can not get into this state unless colo capability is enabled
1884 for migration. (since 2.8)
1885 ShutdownCause (Enum)
1887 An enumeration of reasons for a Shutdown.
1888 Values
1890 none No shutdown request pending
1891 host-error
1893 An error prevents further use of guest
1894 host-qmp-quit
1896 Reaction to the QMP command 'quit'
1897 host-qmp-system-reset
1899 Reaction to the QMP command 'system_reset'
1900 host-signal
1902 Reaction to a signal, such as SIGINT
1903 host-ui
1905 Reaction to a UI event, like window close
1906 guest-shutdown
1908 Guest shutdown/suspend request, via ACPI or other hardware-spe‐
1909 cific means
1910 guest-reset
1912 Guest reset request, and command line turns that into a shutdown
1913 guest-panic
1915 Guest panicked, and command line turns that into a shutdown
1916 subsystem-reset
1918 Partial guest reset that does not trigger QMP events and ignores
1919 --no-reboot. This is useful for sanitizing hypercalls on s390
1920 that are used during kexec/kdump/boot
1921 snapshot-load
1923 A snapshot is being loaded by the record & replay subsystem.
1924 This value is used only within QEMU. It doesn't occur in QMP.
1925 (since 7.2)
1926 StatusInfo (Object)
1928 Information about VCPU run state
1929 Members
1931 running: boolean
1932 true if all VCPUs are runnable, false if not runnable
1933 singlestep: boolean
1935 true if using TCG with one guest instruction per translation
1936 block
1937 status: RunState
1939 the virtual machine RunState
1940 Features
1942 deprecated
1943 Member 'singlestep' is deprecated (with no replacement).
1944 Since
1946 0.14
1947 Notes
1949 singlestep is enabled on the command line with '-accel
1950 tcg,one-insn-per-tb=on', or with the HMP 'one-insn-per-tb' command.
1951 query-status (Command)
1953 Query the run status of all VCPUs
1954 Returns
1956 StatusInfo reflecting all VCPUs
1957 Since
1959 0.14
1960 Example
1962 -> { "execute": "query-status" }
1963 <- { "return": { "running": true,
1964 "singlestep": false,
1965 "status": "running" } }
1966 SHUTDOWN (Event)
1968 Emitted when the virtual machine has shut down, indicating that qemu is
1969 about to exit.
1970 Arguments
1972 guest: boolean
1973 If true, the shutdown was triggered by a guest request (such as
1974 a guest-initiated ACPI shutdown request or other hardware-spe‐
1975 cific action) rather than a host request (such as sending qemu a
1976 SIGINT). (since 2.10)
1977 reason: ShutdownCause
1979 The ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
1980 Note
1982 If the command-line option "-no-shutdown" has been specified, qemu will
1983 not exit, and a STOP event will eventually follow the SHUTDOWN event
1984 Since
1986 0.12
1987 Example
1989 <- { "event": "SHUTDOWN",
1990 "data": { "guest": true, "reason": "guest-shutdown" },
1991 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1992 POWERDOWN (Event)
1994 Emitted when the virtual machine is powered down through the power con‐
1995 trol system, such as via ACPI.
1996 Since
1998 0.12
1999 Example
2001 <- { "event": "POWERDOWN",
2002 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
2003 RESET (Event)
2005 Emitted when the virtual machine is reset
2006 Arguments
2008 guest: boolean
2009 If true, the reset was triggered by a guest request (such as a
2010 guest-initiated ACPI reboot request or other hardware-specific
2011 action) rather than a host request (such as the QMP command sys‐
2012 tem_reset). (since 2.10)
2013 reason: ShutdownCause
2015 The ShutdownCause of the RESET. (since 4.0)
2016 Since
2018 0.12
2019 Example
2021 <- { "event": "RESET",
2022 "data": { "guest": false, "reason": "guest-reset" },
2023 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
2024 STOP (Event)
2026 Emitted when the virtual machine is stopped
2027 Since
2029 0.12
2030 Example
2032 <- { "event": "STOP",
2033 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
2034 RESUME (Event)
2036 Emitted when the virtual machine resumes execution
2037 Since
2039 0.12
2040 Example
2042 <- { "event": "RESUME",
2043 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
2044 SUSPEND (Event)
2046 Emitted when guest enters a hardware suspension state, for example, S3
2047 state, which is sometimes called standby state
2048 Since
2050 1.1
2051 Example
2053 <- { "event": "SUSPEND",
2054 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
2055 SUSPEND_DISK (Event)
2057 Emitted when guest enters a hardware suspension state with data saved
2058 on disk, for example, S4 state, which is sometimes called hibernate
2059 state
2060 Note
2062 QEMU shuts down (similar to event SHUTDOWN) when entering this state
2063 Since
2065 1.2
2066 Example
2068 <- { "event": "SUSPEND_DISK",
2069 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
2070 WAKEUP (Event)
2072 Emitted when the guest has woken up from suspend state and is running
2073 Since
2075 1.1
2076 Example
2078 <- { "event": "WAKEUP",
2079 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
2080 WATCHDOG (Event)
2082 Emitted when the watchdog device's timer is expired
2083 Arguments
2085 action: WatchdogAction
2086 action that has been taken
2087 Note
2089 If action is "reset", "shutdown", or "pause" the WATCHDOG event is fol‐
2090 lowed respectively by the RESET, SHUTDOWN, or STOP events
2091 Note
2093 This event is rate-limited.
2094 Since
2096 0.13
2097 Example
2099 <- { "event": "WATCHDOG",
2100 "data": { "action": "reset" },
2101 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
2102 WatchdogAction (Enum)
2104 An enumeration of the actions taken when the watchdog device's timer is
2105 expired
2106 Values
2108 reset system resets
2109 shutdown
2111 system shutdown, note that it is similar to powerdown, which
2112 tries to set to system status and notify guest
2113 poweroff
2115 system poweroff, the emulator program exits
2116 pause system pauses, similar to stop
2118 debug system enters debug state
2120 none nothing is done
2122 inject-nmi
2124 a non-maskable interrupt is injected into the first VCPU (all
2125 VCPUS on x86) (since 2.4)
2126 Since
2128 2.1
2129 RebootAction (Enum)
2131 Possible QEMU actions upon guest reboot
2132 Values
2134 reset Reset the VM
2135 shutdown
2137 Shutdown the VM and exit, according to the shutdown action
2138 Since
2140 6.0
2141 ShutdownAction (Enum)
2143 Possible QEMU actions upon guest shutdown
2144 Values
2146 poweroff
2147 Shutdown the VM and exit
2148 pause pause the VM
2150 Since
2152 6.0
2153 PanicAction (Enum)
2155 Values
2156 none Continue VM execution
2157 pause Pause the VM
2159 shutdown
2161 Shutdown the VM and exit, according to the shutdown action
2162 exit-failure
2164 Shutdown the VM and exit with nonzero status (since 7.1)
2165 Since
2167 6.0
2168 watchdog-set-action (Command)
2170 Set watchdog action
2171 Arguments
2173 action: WatchdogAction
2174 Not documented
2175 Since
2177 2.11
2178 set-action (Command)
2180 Set the actions that will be taken by the emulator in response to guest
2181 events.
2182 Arguments
2184 reboot: RebootAction (optional)
2185 RebootAction action taken on guest reboot.
2186 shutdown: ShutdownAction (optional)
2188 ShutdownAction action taken on guest shutdown.
2189 panic: PanicAction (optional)
2191 PanicAction action taken on guest panic.
2192 watchdog: WatchdogAction (optional)
2194 WatchdogAction action taken when watchdog timer expires .
2195 Returns
2197 Nothing on success.
2198 Since
2200 6.0
2201 Example
2203 -> { "execute": "set-action",
2204 "arguments": { "reboot": "shutdown",
2205 "shutdown" : "pause",
2206 "panic": "pause",
2207 "watchdog": "inject-nmi" } }
2208 <- { "return": {} }
2209 GUEST_PANICKED (Event)
2211 Emitted when guest OS panic is detected
2212 Arguments
2214 action: GuestPanicAction
2215 action that has been taken, currently always "pause"
2216 info: GuestPanicInformation (optional)
2218 information about a panic (since 2.9)
2219 Since
2221 1.5
2222 Example
2224 <- { "event": "GUEST_PANICKED",
2225 "data": { "action": "pause" },
2226 "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
2227 GUEST_CRASHLOADED (Event)
2229 Emitted when guest OS crash loaded is detected
2230 Arguments
2232 action: GuestPanicAction
2233 action that has been taken, currently always "run"
2234 info: GuestPanicInformation (optional)
2236 information about a panic
2237 Since
2239 5.0
2240 Example
2242 <- { "event": "GUEST_CRASHLOADED",
2243 "data": { "action": "run" },
2244 "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
2245 GuestPanicAction (Enum)
2247 An enumeration of the actions taken when guest OS panic is detected
2248 Values
2250 pause system pauses
2251 poweroff
2253 system powers off (since 2.8)
2254 run system continues to run (since 5.0)
2256 Since
2258 2.1
2259 GuestPanicInformationType (Enum)
2261 An enumeration of the guest panic information types
2262 Values
2264 hyper-v
2265 hyper-v guest panic information type
2266 s390 s390 guest panic information type (Since: 2.12)
2268 Since
2270 2.9
2271 GuestPanicInformation (Object)
2273 Information about a guest panic
2274 Members
2276 type: GuestPanicInformationType
2277 Crash type that defines the hypervisor specific information
2278 The members of GuestPanicInformationHyperV when type is "hyper-v"
2280 The members of GuestPanicInformationS390 when type is "s390"
2282 Since
2284 2.9
2285 GuestPanicInformationHyperV (Object)
2287 Hyper-V specific guest panic information (HV crash MSRs)
2288 Members
2290 arg1: int
2291 Not documented
2292 arg2: int
2294 Not documented
2295 arg3: int
2297 Not documented
2298 arg4: int
2300 Not documented
2301 arg5: int
2303 Not documented
2304 Since
2306 2.9
2307 S390CrashReason (Enum)
2309 Reason why the CPU is in a crashed state.
2310 Values
2312 unknown
2313 no crash reason was set
2314 disabled-wait
2316 the CPU has entered a disabled wait state
2317 extint-loop
2319 clock comparator or cpu timer interrupt with new PSW enabled for
2320 external interrupts
2321 pgmint-loop
2323 program interrupt with BAD new PSW
2324 opint-loop
2326 operation exception interrupt with invalid code at the program
2327 interrupt new PSW
2328 Since
2330 2.12
2331 GuestPanicInformationS390 (Object)
2333 S390 specific guest panic information (PSW)
2334 Members
2336 core: int
2337 core id of the CPU that crashed
2338 psw-mask: int
2340 control fields of guest PSW
2341 psw-addr: int
2343 guest instruction address
2344 reason: S390CrashReason
2346 guest crash reason
2347 Since
2349 2.12
2350 MEMORY_FAILURE (Event)
2352 Emitted when a memory failure occurs on host side.
2353 Arguments
2355 recipient: MemoryFailureRecipient
2356 recipient is defined as MemoryFailureRecipient.
2357 action: MemoryFailureAction
2359 action that has been taken. action is defined as MemoryFailure‐
2360 Action.
2361 flags: MemoryFailureFlags
2363 flags for MemoryFailureAction. action is defined as MemoryFail‐
2364 ureFlags.
2365 Since
2367 5.2
2368 Example
2370 <- { "event": "MEMORY_FAILURE",
2371 "data": { "recipient": "hypervisor",
2372 "action": "fatal",
2373 "flags": { "action-required": false,
2374 "recursive": false } },
2375 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
2376 MemoryFailureRecipient (Enum)
2378 Hardware memory failure occurs, handled by recipient.
2379 Values
2381 hypervisor
2382 memory failure at QEMU process address space. (none guest mem‐
2383 ory, but used by QEMU itself).
2384 guest memory failure at guest memory,
2386 Since
2388 5.2
2389 MemoryFailureAction (Enum)
2391 Actions taken by QEMU in response to a hardware memory failure.
2392 Values
2394 ignore the memory failure could be ignored. This will only be the case
2395 for action-optional failures.
2396 inject memory failure occurred in guest memory, the guest enabled MCE
2398 handling mechanism, and QEMU could inject the MCE into the guest
2399 successfully.
2400 fatal the failure is unrecoverable. This occurs for action-required
2402 failures if the recipient is the hypervisor; QEMU will exit.
2403 reset the failure is unrecoverable but confined to the guest. This
2405 occurs if the recipient is a guest guest which is not ready to
2406 handle memory failures.
2407 Since
2409 5.2
2410 MemoryFailureFlags (Object)
2412 Additional information on memory failures.
2413 Members
2415 action-required: boolean
2416 whether a memory failure event is action-required or action-op‐
2417 tional (e.g. a failure during memory scrub).
2418 recursive: boolean
2420 whether the failure occurred while the previous failure was
2421 still in progress.
2422 Since
2424 5.2
2425 NotifyVmexitOption (Enum)
2427 An enumeration of the options specified when enabling notify VM exit
2428 Values
2430 run enable the feature, do nothing and continue if the notify VM
2431 exit happens.
2432 internal-error
2434 enable the feature, raise a internal error if the notify VM exit
2435 happens.
2436 disable
2438 disable the feature.
2439 Since
2441 7.2
2442
2444 QCryptoTLSCredsEndpoint (Enum)
2445 The type of network endpoint that will be using the credentials. Most
2446 types of credential require different setup / structures depending on
2447 whether they will be used in a server versus a client.
2448 Values
2450 client the network endpoint is acting as the client
2451 server the network endpoint is acting as the server
2453 Since
2455 2.5
2456 QCryptoSecretFormat (Enum)
2458 The data format that the secret is provided in
2459 Values
2461 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
2462 be used
2463 base64 arbitrary base64 encoded binary data
2465 Since
2467 2.6
2468 QCryptoHashAlgorithm (Enum)
2470 The supported algorithms for computing content digests
2471 Values
2473 md5 MD5. Should not be used in any new code, legacy compat only
2474 sha1 SHA-1. Should not be used in any new code, legacy compat only
2476 sha224 SHA-224. (since 2.7)
2478 sha256 SHA-256. Current recommended strong hash.
2480 sha384 SHA-384. (since 2.7)
2482 sha512 SHA-512. (since 2.7)
2484 ripemd160
2486 RIPEMD-160. (since 2.7)
2487 Since
2489 2.6
2490 QCryptoCipherAlgorithm (Enum)
2492 The supported algorithms for content encryption ciphers
2493 Values
2495 aes-128
2496 AES with 128 bit / 16 byte keys
2497 aes-192
2499 AES with 192 bit / 24 byte keys
2500 aes-256
2502 AES with 256 bit / 32 byte keys
2503 des DES with 56 bit / 8 byte keys. Do not use except in VNC.
2505 (since 6.1)
2506 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
2508 cast5-128
2510 Cast5 with 128 bit / 16 byte keys
2511 serpent-128
2513 Serpent with 128 bit / 16 byte keys
2514 serpent-192
2516 Serpent with 192 bit / 24 byte keys
2517 serpent-256
2519 Serpent with 256 bit / 32 byte keys
2520 twofish-128
2522 Twofish with 128 bit / 16 byte keys
2523 twofish-192
2525 Twofish with 192 bit / 24 byte keys
2526 twofish-256
2528 Twofish with 256 bit / 32 byte keys
2529 Since
2531 2.6
2532 QCryptoCipherMode (Enum)
2534 The supported modes for content encryption ciphers
2535 Values
2537 ecb Electronic Code Book
2538 cbc Cipher Block Chaining
2540 xts XEX with tweaked code book and ciphertext stealing
2542 ctr Counter (Since 2.8)
2544 Since
2546 2.6
2547 QCryptoIVGenAlgorithm (Enum)
2549 The supported algorithms for generating initialization vectors for full
2550 disk encryption. The 'plain' generator should not be used for disks
2551 with sector numbers larger than 2^32, except where compatibility with
2552 pre-existing Linux dm-crypt volumes is required.
2553 Values
2555 plain 64-bit sector number truncated to 32-bits
2556 plain64
2558 64-bit sector number
2559 essiv 64-bit sector number encrypted with a hash of the encryption key
2561 Since
2563 2.6
2564 QCryptoBlockFormat (Enum)
2566 The supported full disk encryption formats
2567 Values
2569 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
2570 data from old images.
2571 luks LUKS encryption format. Recommended for new images
2573 Since
2575 2.6
2576 QCryptoBlockOptionsBase (Object)
2578 The common options that apply to all full disk encryption formats
2579 Members
2581 format: QCryptoBlockFormat
2582 the encryption format
2583 Since
2585 2.6
2586 QCryptoBlockOptionsQCow (Object)
2588 The options that apply to QCow/QCow2 AES-CBC encryption format
2589 Members
2591 key-secret: string (optional)
2592 the ID of a QCryptoSecret object providing the decryption key.
2593 Mandatory except when probing image for metadata only.
2594 Since
2596 2.6
2597 QCryptoBlockOptionsLUKS (Object)
2599 The options that apply to LUKS encryption format
2600 Members
2602 key-secret: string (optional)
2603 the ID of a QCryptoSecret object providing the decryption key.
2604 Mandatory except when probing image for metadata only.
2605 Since
2607 2.6
2608 QCryptoBlockCreateOptionsLUKS (Object)
2610 The options that apply to LUKS encryption format initialization
2611 Members
2613 cipher-alg: QCryptoCipherAlgorithm (optional)
2614 the cipher algorithm for data encryption Currently defaults to
2615 'aes-256'.
2616 cipher-mode: QCryptoCipherMode (optional)
2618 the cipher mode for data encryption Currently defaults to 'xts'
2619 ivgen-alg: QCryptoIVGenAlgorithm (optional)
2621 the initialization vector generator Currently defaults to
2622 'plain64'
2623 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2625 the initialization vector generator hash Currently defaults to
2626 'sha256'
2627 hash-alg: QCryptoHashAlgorithm (optional)
2629 the master key hash algorithm Currently defaults to 'sha256'
2630 iter-time: int (optional)
2632 number of milliseconds to spend in PBKDF passphrase processing.
2633 Currently defaults to 2000. (since 2.8)
2634 The members of QCryptoBlockOptionsLUKS
2636 Since
2638 2.6
2639 QCryptoBlockOpenOptions (Object)
2641 The options that are available for all encryption formats when opening
2642 an existing volume
2643 Members
2645 The members of QCryptoBlockOptionsBase
2646 The members of QCryptoBlockOptionsQCow when format is "qcow"
2648 The members of QCryptoBlockOptionsLUKS when format is "luks"
2650 Since
2652 2.6
2653 QCryptoBlockCreateOptions (Object)
2655 The options that are available for all encryption formats when initial‐
2656 izing a new volume
2657 Members
2659 The members of QCryptoBlockOptionsBase
2660 The members of QCryptoBlockOptionsQCow when format is "qcow"
2662 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
2664 Since
2666 2.6
2667 QCryptoBlockInfoBase (Object)
2669 The common information that applies to all full disk encryption formats
2670 Members
2672 format: QCryptoBlockFormat
2673 the encryption format
2674 Since
2676 2.7
2677 QCryptoBlockInfoLUKSSlot (Object)
2679 Information about the LUKS block encryption key slot options
2680 Members
2682 active: boolean
2683 whether the key slot is currently in use
2684 key-offset: int
2686 offset to the key material in bytes
2687 iters: int (optional)
2689 number of PBKDF2 iterations for key material
2690 stripes: int (optional)
2692 number of stripes for splitting key material
2693 Since
2695 2.7
2696 QCryptoBlockInfoLUKS (Object)
2698 Information about the LUKS block encryption options
2699 Members
2701 cipher-alg: QCryptoCipherAlgorithm
2702 the cipher algorithm for data encryption
2703 cipher-mode: QCryptoCipherMode
2705 the cipher mode for data encryption
2706 ivgen-alg: QCryptoIVGenAlgorithm
2708 the initialization vector generator
2709 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2711 the initialization vector generator hash
2712 hash-alg: QCryptoHashAlgorithm
2714 the master key hash algorithm
2715 payload-offset: int
2717 offset to the payload data in bytes
2718 master-key-iters: int
2720 number of PBKDF2 iterations for key material
2721 uuid: string
2723 unique identifier for the volume
2724 slots: array of QCryptoBlockInfoLUKSSlot
2726 information about each key slot
2727 Since
2729 2.7
2730 QCryptoBlockInfo (Object)
2732 Information about the block encryption options
2733 Members
2735 The members of QCryptoBlockInfoBase
2736 The members of QCryptoBlockInfoLUKS when format is "luks"
2738 Since
2740 2.7
2741 QCryptoBlockLUKSKeyslotState (Enum)
2743 Defines state of keyslots that are affected by the update
2744 Values
2746 active The slots contain the given password and marked as active
2747 inactive
2749 The slots are erased (contain garbage) and marked as inactive
2750 Since
2752 5.1
2753 QCryptoBlockAmendOptionsLUKS (Object)
2755 This struct defines the update parameters that activate/de-activate set
2756 of keyslots
2757 Members
2759 state: QCryptoBlockLUKSKeyslotState
2760 the desired state of the keyslots
2761 new-secret: string (optional)
2763 The ID of a QCryptoSecret object providing the password to be
2764 written into added active keyslots
2765 old-secret: string (optional)
2767 Optional (for deactivation only) If given will deactivate all
2768 keyslots that match password located in QCryptoSecret with this
2769 ID
2770 iter-time: int (optional)
2772 Optional (for activation only) Number of milliseconds to spend
2773 in PBKDF passphrase processing for the newly activated keyslot.
2774 Currently defaults to 2000.
2775 keyslot: int (optional)
2777 Optional. ID of the keyslot to activate/deactivate. For
2778 keyslot activation, keyslot should not be active already (this
2779 is unsafe to update an active keyslot), but possible if 'force'
2780 parameter is given. If keyslot is not given, first free keyslot
2781 will be written.
2782 For keyslot deactivation, this parameter specifies the exact
2784 keyslot to deactivate
2785 secret: string (optional)
2787 Optional. The ID of a QCryptoSecret object providing the pass‐
2788 word to use to retrieve current master key. Defaults to the
2789 same secret that was used to open the image
2790 Since
2792 5.1
2793 QCryptoBlockAmendOptions (Object)
2795 The options that are available for all encryption formats when amending
2796 encryption settings
2797 Members
2799 The members of QCryptoBlockOptionsBase
2800 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
2802 Since
2804 5.1
2805 SecretCommonProperties (Object)
2807 Properties for objects of classes derived from secret-common.
2808 Members
2810 loaded: boolean (optional)
2811 if true, the secret is loaded immediately when applying this op‐
2812 tion and will probably fail when processing the next option.
2813 Don't use; only provided for compatibility. (default: false)
2814 format: QCryptoSecretFormat (optional)
2816 the data format that the secret is provided in (default: raw)
2817 keyid: string (optional)
2819 the name of another secret that should be used to decrypt the
2820 provided data. If not present, the data is assumed to be unen‐
2821 crypted.
2822 iv: string (optional)
2824 the random initialization vector used for encryption of this
2825 particular secret. Should be a base64 encrypted string of the
2826 16-byte IV. Mandatory if keyid is given. Ignored if keyid is
2827 absent.
2828 Features
2830 deprecated
2831 Member loaded is deprecated. Setting true doesn't make sense,
2832 and false is already the default.
2833 Since
2835 2.6
2836 SecretProperties (Object)
2838 Properties for secret objects.
2839 Either data or file must be provided, but not both.
2841 Members
2843 data: string (optional)
2844 the associated with the secret from
2845 file: string (optional)
2847 the filename to load the data associated with the secret from
2848 The members of SecretCommonProperties
2850 Since
2852 2.6
2853 SecretKeyringProperties (Object)
2855 Properties for secret_keyring objects.
2856 Members
2858 serial: int
2859 serial number that identifies a key to get from the kernel
2860 The members of SecretCommonProperties
2862 Since
2864 5.1
2865 TlsCredsProperties (Object)
2867 Properties for objects of classes derived from tls-creds.
2868 Members
2870 verify-peer: boolean (optional)
2871 if true the peer credentials will be verified once the handshake
2872 is completed. This is a no-op for anonymous credentials. (de‐
2873 fault: true)
2874 dir: string (optional)
2876 the path of the directory that contains the credential files
2877 endpoint: QCryptoTLSCredsEndpoint (optional)
2879 whether the QEMU network backend that uses the credentials will
2880 be acting as a client or as a server (default: client)
2881 priority: string (optional)
2883 a gnutls priority string as described at
2884 https://gnutls.org/manual/html_node/Priority-Strings.html
2885 Since
2887 2.5
2888 TlsCredsAnonProperties (Object)
2890 Properties for tls-creds-anon objects.
2891 Members
2893 loaded: boolean (optional)
2894 if true, the credentials are loaded immediately when applying
2895 this option and will ignore options that are processed later.
2896 Don't use; only provided for compatibility. (default: false)
2897 The members of TlsCredsProperties
2899 Features
2901 deprecated
2902 Member loaded is deprecated. Setting true doesn't make sense,
2903 and false is already the default.
2904 Since
2906 2.5
2907 TlsCredsPskProperties (Object)
2909 Properties for tls-creds-psk objects.
2910 Members
2912 loaded: boolean (optional)
2913 if true, the credentials are loaded immediately when applying
2914 this option and will ignore options that are processed later.
2915 Don't use; only provided for compatibility. (default: false)
2916 username: string (optional)
2918 the username which will be sent to the server. For clients
2919 only. If absent, "qemu" is sent and the property will read back
2920 as an empty string.
2921 The members of TlsCredsProperties
2923 Features
2925 deprecated
2926 Member loaded is deprecated. Setting true doesn't make sense,
2927 and false is already the default.
2928 Since
2930 3.0
2931 TlsCredsX509Properties (Object)
2933 Properties for tls-creds-x509 objects.
2934 Members
2936 loaded: boolean (optional)
2937 if true, the credentials are loaded immediately when applying
2938 this option and will ignore options that are processed later.
2939 Don't use; only provided for compatibility. (default: false)
2940 sanity-check: boolean (optional)
2942 if true, perform some sanity checks before using the credentials
2943 (default: true)
2944 passwordid: string (optional)
2946 For the server-key.pem and client-key.pem files which contain
2947 sensitive private keys, it is possible to use an encrypted ver‐
2948 sion by providing the passwordid parameter. This provides the
2949 ID of a previously created secret object containing the password
2950 for decryption.
2951 The members of TlsCredsProperties
2953 Features
2955 deprecated
2956 Member loaded is deprecated. Setting true doesn't make sense,
2957 and false is already the default.
2958 Since
2960 2.5
2961 QCryptoAkCipherAlgorithm (Enum)
2963 The supported algorithms for asymmetric encryption ciphers
2964 Values
2966 rsa RSA algorithm
2967 Since
2969 7.1
2970 QCryptoAkCipherKeyType (Enum)
2972 The type of asymmetric keys.
2973 Values
2975 public Not documented
2976 private
2978 Not documented
2979 Since
2981 7.1
2982 QCryptoRSAPaddingAlgorithm (Enum)
2984 The padding algorithm for RSA.
2985 Values
2987 raw no padding used
2988 pkcs1 pkcs1#v1.5
2990 Since
2992 7.1
2993 QCryptoAkCipherOptionsRSA (Object)
2995 Specific parameters for RSA algorithm.
2996 Members
2998 hash-alg: QCryptoHashAlgorithm
2999 QCryptoHashAlgorithm
3000 padding-alg: QCryptoRSAPaddingAlgorithm
3002 QCryptoRSAPaddingAlgorithm
3003 Since
3005 7.1
3006 QCryptoAkCipherOptions (Object)
3008 The options that are available for all asymmetric key algorithms when
3009 creating a new QCryptoAkCipher.
3010 Members
3012 alg: QCryptoAkCipherAlgorithm
3013 Not documented
3014 The members of QCryptoAkCipherOptionsRSA when alg is "rsa"
3016 Since
3018 7.1
3019
3021 JobType (Enum)
3022 Type of a background job.
3023 Values
3025 commit block commit job type, see "block-commit"
3026 stream block stream job type, see "block-stream"
3028 mirror drive mirror job type, see "drive-mirror"
3030 backup drive backup job type, see "drive-backup"
3032 create image creation job type, see "blockdev-create" (since 3.0)
3034 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
3036 snapshot-load
3038 snapshot load job type, see "snapshot-load" (since 6.0)
3039 snapshot-save
3041 snapshot save job type, see "snapshot-save" (since 6.0)
3042 snapshot-delete
3044 snapshot delete job type, see "snapshot-delete" (since 6.0)
3045 Since
3047 1.7
3048 JobStatus (Enum)
3050 Indicates the present state of a given job in its lifetime.
3051 Values
3053 undefined
3054 Erroneous, default state. Should not ever be visible.
3055 created
3057 The job has been created, but not yet started.
3058 running
3060 The job is currently running.
3061 paused The job is running, but paused. The pause may be requested by
3063 either the QMP user or by internal processes.
3064 ready The job is running, but is ready for the user to signal comple‐
3066 tion. This is used for long-running jobs like mirror that are
3067 designed to run indefinitely.
3068 standby
3070 The job is ready, but paused. This is nearly identical to
3071 paused. The job may return to ready or otherwise be canceled.
3072 waiting
3074 The job is waiting for other jobs in the transaction to converge
3075 to the waiting state. This status will likely not be visible
3076 for the last job in a transaction.
3077 pending
3079 The job has finished its work, but has finalization steps that
3080 it needs to make prior to completing. These changes will re‐
3081 quire manual intervention via job-finalize if auto-finalize was
3082 set to false. These pending changes may still fail.
3083 aborting
3085 The job is in the process of being aborted, and will finish with
3086 an error. The job will afterwards report that it is concluded.
3087 This status may not be visible to the management process.
3088 concluded
3090 The job has finished all work. If auto-dismiss was set to
3091 false, the job will remain in the query list until it is dis‐
3092 missed via job-dismiss.
3093 null The job is in the process of being dismantled. This state
3095 should not ever be visible externally.
3096 Since
3098 2.12
3099 JobVerb (Enum)
3101 Represents command verbs that can be applied to a job.
3102 Values
3104 cancel see job-cancel
3105 pause see job-pause
3107 resume see job-resume
3109 set-speed
3111 see block-job-set-speed
3112 complete
3114 see job-complete
3115 dismiss
3117 see job-dismiss
3118 finalize
3120 see job-finalize
3121 Since
3123 2.12
3124 JOB_STATUS_CHANGE (Event)
3126 Emitted when a job transitions to a different status.
3127 Arguments
3129 id: string
3130 The job identifier
3131 status: JobStatus
3133 The new job status
3134 Since
3136 3.0
3137 job-pause (Command)
3139 Pause an active job.
3140 This command returns immediately after marking the active job for paus‐
3142 ing. Pausing an already paused job is an error.
3143 The job will pause as soon as possible, which means transitioning into
3145 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
3146 The corresponding JOB_STATUS_CHANGE event will be emitted.
3147 Cancelling a paused job automatically resumes it.
3149 Arguments
3151 id: string
3152 The job identifier.
3153 Since
3155 3.0
3156 job-resume (Command)
3158 Resume a paused job.
3159 This command returns immediately after resuming a paused job. Resuming
3161 an already running job is an error.
3162 Arguments
3164 id: string
3165 The job identifier.
3166 Since
3168 3.0
3169 job-cancel (Command)
3171 Instruct an active background job to cancel at the next opportunity.
3172 This command returns immediately after marking the active job for can‐
3173 cellation.
3174 The job will cancel as soon as possible and then emit a JOB_STA‐
3176 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
3177 is possible that a job successfully completes (e.g. because it was al‐
3178 most done and there was no opportunity to cancel earlier than complet‐
3179 ing the job) and transitions to PENDING instead.
3180 Arguments
3182 id: string
3183 The job identifier.
3184 Since
3186 3.0
3187 job-complete (Command)
3189 Manually trigger completion of an active job in the READY state.
3190 Arguments
3192 id: string
3193 The job identifier.
3194 Since
3196 3.0
3197 job-dismiss (Command)
3199 Deletes a job that is in the CONCLUDED state. This command only needs
3200 to be run explicitly for jobs that don't have automatic dismiss en‐
3201 abled.
3202 This command will refuse to operate on any job that has not yet reached
3204 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
3205 JOB_READY event, job-cancel or job-complete will still need to be used
3206 as appropriate.
3207 Arguments
3209 id: string
3210 The job identifier.
3211 Since
3213 3.0
3214 job-finalize (Command)
3216 Instructs all jobs in a transaction (or a single job if it is not part
3217 of any transaction) to finalize any graph changes and do any necessary
3218 cleanup. This command requires that all involved jobs are in the PEND‐
3219 ING state.
3220 For jobs in a transaction, instructing one job to finalize will force
3222 ALL jobs in the transaction to finalize, so it is only necessary to in‐
3223 struct a single member job to finalize.
3224 Arguments
3226 id: string
3227 The identifier of any job in the transaction, or of a job that
3228 is not part of any transaction.
3229 Since
3231 3.0
3232 JobInfo (Object)
3234 Information about a job.
3235 Members
3237 id: string
3238 The job identifier
3239 type: JobType
3241 The kind of job that is being performed
3242 status: JobStatus
3244 Current job state/status
3245 current-progress: int
3247 Progress made until now. The unit is arbitrary and the value
3248 can only meaningfully be used for the ratio of current-progress
3249 to total-progress. The value is monotonically increasing.
3250 total-progress: int
3252 Estimated current-progress value at the completion of the job.
3253 This value can arbitrarily change while the job is running, in
3254 both directions.
3255 error: string (optional)
3257 If this field is present, the job failed; if it is still missing
3258 in the CONCLUDED state, this indicates successful completion.
3259 The value is a human-readable error message to describe the rea‐
3261 son for the job failure. It should not be parsed by applica‐
3262 tions.
3263 Since
3265 3.0
3266 query-jobs (Command)
3268 Return information about jobs.
3269 Returns
3271 a list with a JobInfo for each active job
3272 Since
3274 3.0
3275
3277 Block core (VM unrelated)
3278 SnapshotInfo (Object)
3279 Members
3280 id: string
3281 unique snapshot id
3282 name: string
3284 user chosen name
3285 vm-state-size: int
3287 size of the VM state
3288 date-sec: int
3290 UTC date of the snapshot in seconds
3291 date-nsec: int
3293 fractional part in nano seconds to be used with date-sec
3294 vm-clock-sec: int
3296 VM clock relative to boot in seconds
3297 vm-clock-nsec: int
3299 fractional part in nano seconds to be used with vm-clock-sec
3300 icount: int (optional)
3302 Current instruction count. Appears when execution record/replay
3303 is enabled. Used for "time-traveling" to match the moment in
3304 the recorded execution with the snapshots. This counter may be
3305 obtained through query-replay command (since 5.2)
3306 Since
3308 1.3
3309 ImageInfoSpecificQCow2EncryptionBase (Object)
3311 Members
3312 format: BlockdevQcow2EncryptionFormat
3313 The encryption format
3314 Since
3316 2.10
3317 ImageInfoSpecificQCow2Encryption (Object)
3319 Members
3320 The members of ImageInfoSpecificQCow2EncryptionBase
3321 The members of QCryptoBlockInfoLUKS when format is "luks"
3323 Since
3325 2.10
3326 ImageInfoSpecificQCow2 (Object)
3328 Members
3329 compat: string
3330 compatibility level
3331 data-file: string (optional)
3333 the filename of the external data file that is stored in the im‐
3334 age and used as a default for opening the image (since: 4.0)
3335 data-file-raw: boolean (optional)
3337 True if the external data file must stay valid as a standalone
3338 (read-only) raw image without looking at qcow2 metadata (since:
3339 4.0)
3340 extended-l2: boolean (optional)
3342 true if the image has extended L2 entries; only valid for compat
3343 >= 1.1 (since 5.2)
3344 lazy-refcounts: boolean (optional)
3346 on or off; only valid for compat >= 1.1
3347 corrupt: boolean (optional)
3349 true if the image has been marked corrupt; only valid for compat
3350 >= 1.1 (since 2.2)
3351 refcount-bits: int
3353 width of a refcount entry in bits (since 2.3)
3354 encrypt: ImageInfoSpecificQCow2Encryption (optional)
3356 details about encryption parameters; only set if image is en‐
3357 crypted (since 2.10)
3358 bitmaps: array of Qcow2BitmapInfo (optional)
3360 A list of qcow2 bitmap details (since 4.0)
3361 compression-type: Qcow2CompressionType
3363 the image cluster compression method (since 5.1)
3364 Since
3366 1.7
3367 ImageInfoSpecificVmdk (Object)
3369 Members
3370 create-type: string
3371 The create type of VMDK image
3372 cid: int
3374 Content id of image
3375 parent-cid: int
3377 Parent VMDK image's cid
3378 extents: array of VmdkExtentInfo
3380 List of extent files
3381 Since
3383 1.7
3384 VmdkExtentInfo (Object)
3386 Information about a VMDK extent file
3387 Members
3389 filename: string
3390 Name of the extent file
3391 format: string
3393 Extent type (e.g. FLAT or SPARSE)
3394 virtual-size: int
3396 Number of bytes covered by this extent
3397 cluster-size: int (optional)
3399 Cluster size in bytes (for non-flat extents)
3400 compressed: boolean (optional)
3402 Whether this extent contains compressed data
3403 Since
3405 8.0
3406 ImageInfoSpecificRbd (Object)
3408 Members
3409 encryption-format: RbdImageEncryptionFormat (optional)
3410 Image encryption format
3411 Since
3413 6.1
3414 ImageInfoSpecificFile (Object)
3416 Members
3417 extent-size-hint: int (optional)
3418 Extent size hint (if available)
3419 Since
3421 8.0
3422 ImageInfoSpecificKind (Enum)
3424 Values
3425 luks Since 2.7
3426 rbd Since 6.1
3428 file Since 8.0
3430 qcow2 Not documented
3432 vmdk Not documented
3434 Since
3436 1.7
3437 ImageInfoSpecificQCow2Wrapper (Object)
3439 Members
3440 data: ImageInfoSpecificQCow2
3441 Not documented
3442 Since
3444 1.7
3445 ImageInfoSpecificVmdkWrapper (Object)
3447 Members
3448 data: ImageInfoSpecificVmdk
3449 Not documented
3450 Since
3452 6.1
3453 ImageInfoSpecificLUKSWrapper (Object)
3455 Members
3456 data: QCryptoBlockInfoLUKS
3457 Not documented
3458 Since
3460 2.7
3461 ImageInfoSpecificRbdWrapper (Object)
3463 Members
3464 data: ImageInfoSpecificRbd
3465 Not documented
3466 Since
3468 6.1
3469 ImageInfoSpecificFileWrapper (Object)
3471 Members
3472 data: ImageInfoSpecificFile
3473 Not documented
3474 Since
3476 8.0
3477 ImageInfoSpecific (Object)
3479 A discriminated record of image format specific information structures.
3480 Members
3482 type: ImageInfoSpecificKind
3483 Not documented
3484 The members of ImageInfoSpecificQCow2Wrapper when type is "qcow2"
3486 The members of ImageInfoSpecificVmdkWrapper when type is "vmdk"
3488 The members of ImageInfoSpecificLUKSWrapper when type is "luks"
3490 The members of ImageInfoSpecificRbdWrapper when type is "rbd"
3492 The members of ImageInfoSpecificFileWrapper when type is "file"
3494 Since
3496 1.7
3497 BlockNodeInfo (Object)
3499 Information about a QEMU image file
3500 Members
3502 filename: string
3503 name of the image file
3504 format: string
3506 format of the image file
3507 virtual-size: int
3509 maximum capacity in bytes of the image
3510 actual-size: int (optional)
3512 actual size on disk in bytes of the image
3513 dirty-flag: boolean (optional)
3515 true if image is not cleanly closed
3516 cluster-size: int (optional)
3518 size of a cluster in bytes
3519 encrypted: boolean (optional)
3521 true if the image is encrypted
3522 compressed: boolean (optional)
3524 true if the image is compressed (Since 1.7)
3525 backing-filename: string (optional)
3527 name of the backing file
3528 full-backing-filename: string (optional)
3530 full path of the backing file
3531 backing-filename-format: string (optional)
3533 the format of the backing file
3534 snapshots: array of SnapshotInfo (optional)
3536 list of VM snapshots
3537 format-specific: ImageInfoSpecific (optional)
3539 structure supplying additional format-specific information
3540 (since 1.7)
3541 Since
3543 8.0
3544 ImageInfo (Object)
3546 Information about a QEMU image file, and potentially its backing image
3547 Members
3549 backing-image: ImageInfo (optional)
3550 info of the backing image
3551 The members of BlockNodeInfo
3553 Since
3555 1.3
3556 BlockChildInfo (Object)
3558 Information about all nodes in the block graph starting at some node,
3559 annotated with information about that node in relation to its parent.
3560 Members
3562 name: string
3563 Child name of the root node in the BlockGraphInfo struct, in its
3564 role as the child of some undescribed parent node
3565 info: BlockGraphInfo
3567 Block graph information starting at this node
3568 Since
3570 8.0
3571 BlockGraphInfo (Object)
3573 Information about all nodes in a block (sub)graph in the form of Bloc‐
3574 kNodeInfo data. The base BlockNodeInfo struct contains the information
3575 for the (sub)graph's root node.
3576 Members
3578 children: array of BlockChildInfo
3579 Array of links to this node's child nodes' information
3580 The members of BlockNodeInfo
3582 Since
3584 8.0
3585 ImageCheck (Object)
3587 Information about a QEMU image file check
3588 Members
3590 filename: string
3591 name of the image file checked
3592 format: string
3594 format of the image file checked
3595 check-errors: int
3597 number of unexpected errors occurred during check
3598 image-end-offset: int (optional)
3600 offset (in bytes) where the image ends, this field is present if
3601 the driver for the image format supports it
3602 corruptions: int (optional)
3604 number of corruptions found during the check if any
3605 leaks: int (optional)
3607 number of leaks found during the check if any
3608 corruptions-fixed: int (optional)
3610 number of corruptions fixed during the check if any
3611 leaks-fixed: int (optional)
3613 number of leaks fixed during the check if any
3614 total-clusters: int (optional)
3616 total number of clusters, this field is present if the driver
3617 for the image format supports it
3618 allocated-clusters: int (optional)
3620 total number of allocated clusters, this field is present if the
3621 driver for the image format supports it
3622 fragmented-clusters: int (optional)
3624 total number of fragmented clusters, this field is present if
3625 the driver for the image format supports it
3626 compressed-clusters: int (optional)
3628 total number of compressed clusters, this field is present if
3629 the driver for the image format supports it
3630 Since
3632 1.4
3633 MapEntry (Object)
3635 Mapping information from a virtual block range to a host file range
3636 Members
3638 start: int
3639 virtual (guest) offset of the first byte described by this entry
3640 length: int
3642 the number of bytes of the mapped virtual range
3643 data: boolean
3645 reading the image will actually read data from a file (in par‐
3646 ticular, if offset is present this means that the sectors are
3647 not simply preallocated, but contain actual data in raw format)
3648 zero: boolean
3650 whether the virtual blocks read as zeroes
3651 depth: int
3653 number of layers (0 = top image, 1 = top image's backing file,
3654 ..., n - 1 = bottom image (where n is the number of images in
3655 the chain)) before reaching one for which the range is allocated
3656 present: boolean
3658 true if this layer provides the data, false if adding a backing
3659 layer could impact this region (since 6.1)
3660 offset: int (optional)
3662 if present, the image file stores the data for this range in raw
3663 format at the given (host) offset
3664 filename: string (optional)
3666 filename that is referred to by offset
3667 Since
3669 2.6
3670 BlockdevCacheInfo (Object)
3672 Cache mode information for a block device
3673 Members
3675 writeback: boolean
3676 true if writeback mode is enabled
3677 direct: boolean
3679 true if the host page cache is bypassed (O_DIRECT)
3680 no-flush: boolean
3682 true if flush requests are ignored for the device
3683 Since
3685 2.3
3686 BlockDeviceInfo (Object)
3688 Information about the backing device for a block device.
3689 Members
3691 file: string
3692 the filename of the backing device
3693 node-name: string (optional)
3695 the name of the block driver node (Since 2.0)
3696 ro: boolean
3698 true if the backing device was open read-only
3699 drv: string
3701 the name of the block format used to open the backing device.
3702 As of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow',
3703 'dmg', 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_de‐
3704 vice', 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow',
3705 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago'
3706 added, 'cow' dropped 2.3: 'host_floppy' deprecated 2.5:
3707 'host_floppy' dropped 2.6: 'luks' added 2.8: 'replication'
3708 added, 'tftp' dropped 2.9: 'archipelago' dropped
3709 backing_file: string (optional)
3711 the name of the backing file (for copy-on-write)
3712 backing_file_depth: int
3714 number of files in the backing file chain (since: 1.2)
3715 encrypted: boolean
3717 true if the backing device is encrypted
3718 detect_zeroes: BlockdevDetectZeroesOptions
3720 detect and optimize zero writes (Since 2.1)
3721 bps: int
3723 total throughput limit in bytes per second is specified
3724 bps_rd: int
3726 read throughput limit in bytes per second is specified
3727 bps_wr: int
3729 write throughput limit in bytes per second is specified
3730 iops: int
3732 total I/O operations per second is specified
3733 iops_rd: int
3735 read I/O operations per second is specified
3736 iops_wr: int
3738 write I/O operations per second is specified
3739 image: ImageInfo
3741 the info of image used (since: 1.6)
3742 bps_max: int (optional)
3744 total throughput limit during bursts, in bytes (Since 1.7)
3745 bps_rd_max: int (optional)
3747 read throughput limit during bursts, in bytes (Since 1.7)
3748 bps_wr_max: int (optional)
3750 write throughput limit during bursts, in bytes (Since 1.7)
3751 iops_max: int (optional)
3753 total I/O operations per second during bursts, in bytes (Since
3754 1.7)
3755 iops_rd_max: int (optional)
3757 read I/O operations per second during bursts, in bytes (Since
3758 1.7)
3759 iops_wr_max: int (optional)
3761 write I/O operations per second during bursts, in bytes (Since
3762 1.7)
3763 bps_max_length: int (optional)
3765 maximum length of the bps_max burst period, in seconds. (Since
3766 2.6)
3767 bps_rd_max_length: int (optional)
3769 maximum length of the bps_rd_max burst period, in seconds.
3770 (Since 2.6)
3771 bps_wr_max_length: int (optional)
3773 maximum length of the bps_wr_max burst period, in seconds.
3774 (Since 2.6)
3775 iops_max_length: int (optional)
3777 maximum length of the iops burst period, in seconds. (Since
3778 2.6)
3779 iops_rd_max_length: int (optional)
3781 maximum length of the iops_rd_max burst period, in seconds.
3782 (Since 2.6)
3783 iops_wr_max_length: int (optional)
3785 maximum length of the iops_wr_max burst period, in seconds.
3786 (Since 2.6)
3787 iops_size: int (optional)
3789 an I/O size in bytes (Since 1.7)
3790 group: string (optional)
3792 throttle group name (Since 2.4)
3793 cache: BlockdevCacheInfo
3795 the cache mode used for the block device (since: 2.3)
3796 write_threshold: int
3798 configured write threshold for the device. 0 if disabled.
3799 (Since 2.3)
3800 dirty-bitmaps: array of BlockDirtyInfo (optional)
3802 dirty bitmaps information (only present if node has one or more
3803 dirty bitmaps) (Since 4.2)
3804 Since
3806 0.14
3807 BlockDeviceIoStatus (Enum)
3809 An enumeration of block device I/O status.
3810 Values
3812 ok The last I/O operation has succeeded
3813 failed The last I/O operation has failed
3815 nospace
3817 The last I/O operation has failed due to a no-space condition
3818 Since
3820 1.0
3821 BlockDirtyInfo (Object)
3823 Block dirty bitmap information.
3824 Members
3826 name: string (optional)
3827 the name of the dirty bitmap (Since 2.4)
3828 count: int
3830 number of dirty bytes according to the dirty bitmap
3831 granularity: int
3833 granularity of the dirty bitmap in bytes (since 1.4)
3834 recording: boolean
3836 true if the bitmap is recording new writes from the guest.
3837 (since 4.0)
3838 busy: boolean
3840 true if the bitmap is in-use by some operation (NBD or jobs) and
3841 cannot be modified via QMP or used by another operation. (since
3842 4.0)
3843 persistent: boolean
3845 true if the bitmap was stored on disk, is scheduled to be stored
3846 on disk, or both. (since 4.0)
3847 inconsistent: boolean (optional)
3849 true if this is a persistent bitmap that was improperly stored.
3850 Implies persistent to be true; recording and busy to be false.
3851 This bitmap cannot be used. To remove it, use block-dirty-bit‐
3852 map-remove. (Since 4.0)
3853 Since
3855 1.3
3856 Qcow2BitmapInfoFlags (Enum)
3858 An enumeration of flags that a bitmap can report to the user.
3859 Values
3861 in-use This flag is set by any process actively modifying the qcow2
3862 file, and cleared when the updated bitmap is flushed to the
3863 qcow2 image. The presence of this flag in an offline image
3864 means that the bitmap was not saved correctly after its last us‐
3865 age, and may contain inconsistent data.
3866 auto The bitmap must reflect all changes of the virtual disk by any
3868 application that would write to this qcow2 file.
3869 Since
3871 4.0
3872 Qcow2BitmapInfo (Object)
3874 Qcow2 bitmap information.
3875 Members
3877 name: string
3878 the name of the bitmap
3879 granularity: int
3881 granularity of the bitmap in bytes
3882 flags: array of Qcow2BitmapInfoFlags
3884 flags of the bitmap
3885 Since
3887 4.0
3888 BlockLatencyHistogramInfo (Object)
3890 Block latency histogram.
3891 Members
3893 boundaries: array of int
3894 list of interval boundary values in nanoseconds, all greater
3895 than zero and in ascending order. For example, the list [10,
3896 50, 100] produces the following histogram intervals: [0, 10),
3897 [10, 50), [50, 100), [100, +inf).
3898 bins: array of int
3900 list of io request counts corresponding to histogram intervals,
3901 one more element than boundaries has. For the example above,
3902 bins may be something like [3, 1, 5, 2], and corresponding his‐
3903 togram looks like:
3904 5| *
3906 4| *
3907 3| * *
3908 2| * * *
3909 1| * * * *
3910 +------------------
3911 10 50 100
3912 Since
3914 4.0
3915 BlockInfo (Object)
3917 Block device information. This structure describes a virtual device
3918 and the backing device associated with it.
3919 Members
3921 device: string
3922 The device name associated with the virtual device.
3923 qdev: string (optional)
3925 The qdev ID, or if no ID is assigned, the QOM path of the block
3926 device. (since 2.10)
3927 type: string
3929 This field is returned only for compatibility reasons, it should
3930 not be used (always returns 'unknown')
3931 removable: boolean
3933 True if the device supports removable media.
3934 locked: boolean
3936 True if the guest has locked this device from having its media
3937 removed
3938 tray_open: boolean (optional)
3940 True if the device's tray is open (only present if it has a
3941 tray)
3942 io-status: BlockDeviceIoStatus (optional)
3944 BlockDeviceIoStatus. Only present if the device supports it and
3945 the VM is configured to stop on errors (supported device models:
3946 virtio-blk, IDE, SCSI except scsi-generic)
3947 inserted: BlockDeviceInfo (optional)
3949 BlockDeviceInfo describing the device if media is present
3950 Since
3952 0.14
3953 BlockMeasureInfo (Object)
3955 Image file size calculation information. This structure describes the
3956 size requirements for creating a new image file.
3957 The size requirements depend on the new image file format. File size
3959 always equals virtual disk size for the 'raw' format, even for sparse
3960 POSIX files. Compact formats such as 'qcow2' represent unallocated and
3961 zero regions efficiently so file size may be smaller than virtual disk
3962 size.
3963 The values are upper bounds that are guaranteed to fit the new image
3965 file. Subsequent modification, such as internal snapshot or further
3966 bitmap creation, may require additional space and is not covered here.
3967 Members
3969 required: int
3970 Size required for a new image file, in bytes, when copying just
3971 allocated guest-visible contents.
3972 fully-allocated: int
3974 Image file size, in bytes, once data has been written to all
3975 sectors, when copying just guest-visible contents.
3976 bitmaps: int (optional)
3978 Additional size required if all the top-level bitmap metadata in
3979 the source image were to be copied to the destination, present
3980 only when source and destination both support persistent bit‐
3981 maps. (since 5.1)
3982 Since
3984 2.10
3985 query-block (Command)
3987 Get a list of BlockInfo for all virtual block devices.
3988 Returns
3990 a list of BlockInfo describing each virtual block device. Filter nodes
3991 that were created implicitly are skipped over.
3992 Since
3994 0.14
3995 Example
3997 -> { "execute": "query-block" }
3998 <- {
3999 "return":[
4000 {
4001 "io-status": "ok",
4002 "device":"ide0-hd0",
4003 "locked":false,
4004 "removable":false,
4005 "inserted":{
4006 "ro":false,
4007 "drv":"qcow2",
4008 "encrypted":false,
4009 "file":"disks/test.qcow2",
4010 "backing_file_depth":1,
4011 "bps":1000000,
4012 "bps_rd":0,
4013 "bps_wr":0,
4014 "iops":1000000,
4015 "iops_rd":0,
4016 "iops_wr":0,
4017 "bps_max": 8000000,
4018 "bps_rd_max": 0,
4019 "bps_wr_max": 0,
4020 "iops_max": 0,
4021 "iops_rd_max": 0,
4022 "iops_wr_max": 0,
4023 "iops_size": 0,
4024 "detect_zeroes": "on",
4025 "write_threshold": 0,
4026 "image":{
4027 "filename":"disks/test.qcow2",
4028 "format":"qcow2",
4029 "virtual-size":2048000,
4030 "backing_file":"base.qcow2",
4031 "full-backing-filename":"disks/base.qcow2",
4032 "backing-filename-format":"qcow2",
4033 "snapshots":[
4034 {
4035 "id": "1",
4036 "name": "snapshot1",
4037 "vm-state-size": 0,
4038 "date-sec": 10000200,
4039 "date-nsec": 12,
4040 "vm-clock-sec": 206,
4041 "vm-clock-nsec": 30
4042 }
4043 ],
4044 "backing-image":{
4045 "filename":"disks/base.qcow2",
4046 "format":"qcow2",
4047 "virtual-size":2048000
4048 }
4049 }
4050 },
4051 "qdev": "ide_disk",
4052 "type":"unknown"
4053 },
4054 {
4055 "io-status": "ok",
4056 "device":"ide1-cd0",
4057 "locked":false,
4058 "removable":true,
4059 "qdev": "/machine/unattached/device[23]",
4060 "tray_open": false,
4061 "type":"unknown"
4062 },
4063 {
4064 "device":"floppy0",
4065 "locked":false,
4066 "removable":true,
4067 "qdev": "/machine/unattached/device[20]",
4068 "type":"unknown"
4069 },
4070 {
4071 "device":"sd0",
4072 "locked":false,
4073 "removable":true,
4074 "type":"unknown"
4075 }
4076 ]
4077 }
4078 BlockDeviceTimedStats (Object)
4080 Statistics of a block device during a given interval of time.
4081 Members
4083 interval_length: int
4084 Interval used for calculating the statistics, in seconds.
4085 min_rd_latency_ns: int
4087 Minimum latency of read operations in the defined interval, in
4088 nanoseconds.
4089 min_wr_latency_ns: int
4091 Minimum latency of write operations in the defined interval, in
4092 nanoseconds.
4093 min_zone_append_latency_ns: int
4095 Minimum latency of zone append operations in the defined inter‐
4096 val, in nanoseconds (since 8.1)
4097 min_flush_latency_ns: int
4099 Minimum latency of flush operations in the defined interval, in
4100 nanoseconds.
4101 max_rd_latency_ns: int
4103 Maximum latency of read operations in the defined interval, in
4104 nanoseconds.
4105 max_wr_latency_ns: int
4107 Maximum latency of write operations in the defined interval, in
4108 nanoseconds.
4109 max_zone_append_latency_ns: int
4111 Maximum latency of zone append operations in the defined inter‐
4112 val, in nanoseconds (since 8.1)
4113 max_flush_latency_ns: int
4115 Maximum latency of flush operations in the defined interval, in
4116 nanoseconds.
4117 avg_rd_latency_ns: int
4119 Average latency of read operations in the defined interval, in
4120 nanoseconds.
4121 avg_wr_latency_ns: int
4123 Average latency of write operations in the defined interval, in
4124 nanoseconds.
4125 avg_zone_append_latency_ns: int
4127 Average latency of zone append operations in the defined inter‐
4128 val, in nanoseconds (since 8.1)
4129 avg_flush_latency_ns: int
4131 Average latency of flush operations in the defined interval, in
4132 nanoseconds.
4133 avg_rd_queue_depth: number
4135 Average number of pending read operations in the defined inter‐
4136 val.
4137 avg_wr_queue_depth: number
4139 Average number of pending write operations in the defined inter‐
4140 val.
4141 avg_zone_append_queue_depth: number
4143 Average number of pending zone append operations in the defined
4144 interval (since 8.1).
4145 Since
4147 2.5
4148 BlockDeviceStats (Object)
4150 Statistics of a virtual block device or a block backing device.
4151 Members
4153 rd_bytes: int
4154 The number of bytes read by the device.
4155 wr_bytes: int
4157 The number of bytes written by the device.
4158 zone_append_bytes: int
4160 The number of bytes appended by the zoned devices (since 8.1)
4161 unmap_bytes: int
4163 The number of bytes unmapped by the device (Since 4.2)
4164 rd_operations: int
4166 The number of read operations performed by the device.
4167 wr_operations: int
4169 The number of write operations performed by the device.
4170 zone_append_operations: int
4172 The number of zone append operations performed by the zoned de‐
4173 vices (since 8.1)
4174 flush_operations: int
4176 The number of cache flush operations performed by the device
4177 (since 0.15)
4178 unmap_operations: int
4180 The number of unmap operations performed by the device (Since
4181 4.2)
4182 rd_total_time_ns: int
4184 Total time spent on reads in nanoseconds (since 0.15).
4185 wr_total_time_ns: int
4187 Total time spent on writes in nanoseconds (since 0.15).
4188 zone_append_total_time_ns: int
4190 Total time spent on zone append writes in nanoseconds (since
4191 8.1)
4192 flush_total_time_ns: int
4194 Total time spent on cache flushes in nanoseconds (since 0.15).
4195 unmap_total_time_ns: int
4197 Total time spent on unmap operations in nanoseconds (Since 4.2)
4198 wr_highest_offset: int
4200 The offset after the greatest byte written to the device. The
4201 intended use of this information is for growable sparse files
4202 (like qcow2) that are used on top of a physical device.
4203 rd_merged: int
4205 Number of read requests that have been merged into another re‐
4206 quest (Since 2.3).
4207 wr_merged: int
4209 Number of write requests that have been merged into another re‐
4210 quest (Since 2.3).
4211 zone_append_merged: int
4213 Number of zone append requests that have been merged into an‐
4214 other request (since 8.1)
4215 unmap_merged: int
4217 Number of unmap requests that have been merged into another re‐
4218 quest (Since 4.2)
4219 idle_time_ns: int (optional)
4221 Time since the last I/O operation, in nanoseconds. If the field
4222 is absent it means that there haven't been any operations yet
4223 (Since 2.5).
4224 failed_rd_operations: int
4226 The number of failed read operations performed by the device
4227 (Since 2.5)
4228 failed_wr_operations: int
4230 The number of failed write operations performed by the device
4231 (Since 2.5)
4232 failed_zone_append_operations: int
4234 The number of failed zone append write operations performed by
4235 the zoned devices (since 8.1)
4236 failed_flush_operations: int
4238 The number of failed flush operations performed by the device
4239 (Since 2.5)
4240 failed_unmap_operations: int
4242 The number of failed unmap operations performed by the device
4243 (Since 4.2)
4244 invalid_rd_operations: int
4246 The number of invalid read operations performed by the device
4247 (Since 2.5)
4248 invalid_wr_operations: int
4250 The number of invalid write operations performed by the device
4251 (Since 2.5)
4252 invalid_zone_append_operations: int
4254 The number of invalid zone append operations performed by the
4255 zoned device (since 8.1)
4256 invalid_flush_operations: int
4258 The number of invalid flush operations performed by the device
4259 (Since 2.5)
4260 invalid_unmap_operations: int
4262 The number of invalid unmap operations performed by the device
4263 (Since 4.2)
4264 account_invalid: boolean
4266 Whether invalid operations are included in the last access sta‐
4267 tistics (Since 2.5)
4268 account_failed: boolean
4270 Whether failed operations are included in the latency and last
4271 access statistics (Since 2.5)
4272 timed_stats: array of BlockDeviceTimedStats
4274 Statistics specific to the set of previously defined intervals
4275 of time (Since 2.5)
4276 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
4278 BlockLatencyHistogramInfo. (Since 4.0)
4279 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
4281 BlockLatencyHistogramInfo. (Since 4.0)
4282 zone_append_latency_histogram: BlockLatencyHistogramInfo (optional)
4284 BlockLatencyHistogramInfo. (since 8.1)
4285 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
4287 BlockLatencyHistogramInfo. (Since 4.0)
4288 Since
4290 0.14
4291 BlockStatsSpecificFile (Object)
4293 File driver statistics
4294 Members
4296 discard-nb-ok: int
4297 The number of successful discard operations performed by the
4298 driver.
4299 discard-nb-failed: int
4301 The number of failed discard operations performed by the driver.
4302 discard-bytes-ok: int
4304 The number of bytes discarded by the driver.
4305 Since
4307 4.2
4308 BlockStatsSpecificNvme (Object)
4310 NVMe driver statistics
4311 Members
4313 completion-errors: int
4314 The number of completion errors.
4315 aligned-accesses: int
4317 The number of aligned accesses performed by the driver.
4318 unaligned-accesses: int
4320 The number of unaligned accesses performed by the driver.
4321 Since
4323 5.2
4324 BlockStatsSpecific (Object)
4326 Block driver specific statistics
4327 Members
4329 driver: BlockdevDriver
4330 Not documented
4331 The members of BlockStatsSpecificFile when driver is "file"
4333 The members of BlockStatsSpecificFile when driver is "host_device" (If:
4335 HAVE_HOST_BLOCK_DEVICE)
4336 The members of BlockStatsSpecificNvme when driver is "nvme"
4338 Since
4340 4.2
4341 BlockStats (Object)
4343 Statistics of a virtual block device or a block backing device.
4344 Members
4346 device: string (optional)
4347 If the stats are for a virtual block device, the name corre‐
4348 sponding to the virtual block device.
4349 node-name: string (optional)
4351 The node name of the device. (Since 2.3)
4352 qdev: string (optional)
4354 The qdev ID, or if no ID is assigned, the QOM path of the block
4355 device. (since 3.0)
4356 stats: BlockDeviceStats
4358 A BlockDeviceStats for the device.
4359 driver-specific: BlockStatsSpecific (optional)
4361 Optional driver-specific stats. (Since 4.2)
4362 parent: BlockStats (optional)
4364 This describes the file block device if it has one. Contains
4365 recursively the statistics of the underlying protocol (e.g. the
4366 host file for a qcow2 image). If there is no underlying proto‐
4367 col, this field is omitted
4368 backing: BlockStats (optional)
4370 This describes the backing block device if it has one. (Since
4371 2.0)
4372 Since
4374 0.14
4375 query-blockstats (Command)
4377 Query the BlockStats for all virtual block devices.
4378 Arguments
4380 query-nodes: boolean (optional)
4381 If true, the command will query all the block nodes that have a
4382 node name, in a list which will include "parent" information,
4383 but not "backing". If false or omitted, the behavior is as be‐
4384 fore - query all the device backends, recursively including
4385 their "parent" and "backing". Filter nodes that were created im‐
4386 plicitly are skipped over in this mode. (Since 2.3)
4387 Returns
4389 A list of BlockStats for each virtual block devices.
4390 Since
4392 0.14
4393 Example
4395 -> { "execute": "query-blockstats" }
4396 <- {
4397 "return":[
4398 {
4399 "device":"ide0-hd0",
4400 "parent":{
4401 "stats":{
4402 "wr_highest_offset":3686448128,
4403 "wr_bytes":9786368,
4404 "wr_operations":751,
4405 "rd_bytes":122567168,
4406 "rd_operations":36772
4407 "wr_total_times_ns":313253456
4408 "rd_total_times_ns":3465673657
4409 "flush_total_times_ns":49653
4410 "flush_operations":61,
4411 "rd_merged":0,
4412 "wr_merged":0,
4413 "idle_time_ns":2953431879,
4414 "account_invalid":true,
4415 "account_failed":false
4416 }
4417 },
4418 "stats":{
4419 "wr_highest_offset":2821110784,
4420 "wr_bytes":9786368,
4421 "wr_operations":692,
4422 "rd_bytes":122739200,
4423 "rd_operations":36604
4424 "flush_operations":51,
4425 "wr_total_times_ns":313253456
4426 "rd_total_times_ns":3465673657
4427 "flush_total_times_ns":49653,
4428 "rd_merged":0,
4429 "wr_merged":0,
4430 "idle_time_ns":2953431879,
4431 "account_invalid":true,
4432 "account_failed":false
4433 },
4434 "qdev": "/machine/unattached/device[23]"
4435 },
4436 {
4437 "device":"ide1-cd0",
4438 "stats":{
4439 "wr_highest_offset":0,
4440 "wr_bytes":0,
4441 "wr_operations":0,
4442 "rd_bytes":0,
4443 "rd_operations":0
4444 "flush_operations":0,
4445 "wr_total_times_ns":0
4446 "rd_total_times_ns":0
4447 "flush_total_times_ns":0,
4448 "rd_merged":0,
4449 "wr_merged":0,
4450 "account_invalid":false,
4451 "account_failed":false
4452 },
4453 "qdev": "/machine/unattached/device[24]"
4454 },
4455 {
4456 "device":"floppy0",
4457 "stats":{
4458 "wr_highest_offset":0,
4459 "wr_bytes":0,
4460 "wr_operations":0,
4461 "rd_bytes":0,
4462 "rd_operations":0
4463 "flush_operations":0,
4464 "wr_total_times_ns":0
4465 "rd_total_times_ns":0
4466 "flush_total_times_ns":0,
4467 "rd_merged":0,
4468 "wr_merged":0,
4469 "account_invalid":false,
4470 "account_failed":false
4471 },
4472 "qdev": "/machine/unattached/device[16]"
4473 },
4474 {
4475 "device":"sd0",
4476 "stats":{
4477 "wr_highest_offset":0,
4478 "wr_bytes":0,
4479 "wr_operations":0,
4480 "rd_bytes":0,
4481 "rd_operations":0
4482 "flush_operations":0,
4483 "wr_total_times_ns":0
4484 "rd_total_times_ns":0
4485 "flush_total_times_ns":0,
4486 "rd_merged":0,
4487 "wr_merged":0,
4488 "account_invalid":false,
4489 "account_failed":false
4490 }
4491 }
4492 ]
4493 }
4494 BlockdevOnError (Enum)
4496 An enumeration of possible behaviors for errors on I/O operations. The
4497 exact meaning depends on whether the I/O was initiated by a guest or by
4498 a block job
4499 Values
4501 report for guest operations, report the error to the guest; for jobs,
4502 cancel the job
4503 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
4505 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
4506 the failing request later and may still complete successfully.
4507 The stream block job continues to stream and will complete with
4508 an error.
4509 enospc same as stop on ENOSPC, same as report otherwise.
4511 stop for guest operations, stop the virtual machine; for jobs, pause
4513 the job
4514 auto inherit the error handling policy of the backend (since: 2.7)
4516 Since
4518 1.3
4519 MirrorSyncMode (Enum)
4521 An enumeration of possible behaviors for the initial synchronization
4522 phase of storage mirroring.
4523 Values
4525 top copies data in the topmost image to the destination
4526 full copies data from all images to the destination
4528 none only copy data written from now on
4530 incremental
4532 only copy data described by the dirty bitmap. (since: 2.4)
4533 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
4535 havior on completion is determined by the BitmapSyncMode.
4536 Since
4538 1.3
4539 BitmapSyncMode (Enum)
4541 An enumeration of possible behaviors for the synchronization of a bit‐
4542 map when used for data copy operations.
4543 Values
4545 on-success
4546 The bitmap is only synced when the operation is successful.
4547 This is the behavior always used for 'INCREMENTAL' backups.
4548 never The bitmap is never synchronized with the operation, and is
4550 treated solely as a read-only manifest of blocks to copy.
4551 always The bitmap is always synchronized with the operation, regardless
4553 of whether or not the operation was successful.
4554 Since
4556 4.2
4557 MirrorCopyMode (Enum)
4559 An enumeration whose values tell the mirror block job when to trigger
4560 writes to the target.
4561 Values
4563 background
4564 copy data in background only.
4565 write-blocking
4567 when data is written to the source, write it (synchronously) to
4568 the target as well. In addition, data is copied in background
4569 just like in background mode.
4570 Since
4572 3.0
4573 BlockJobInfo (Object)
4575 Information about a long-running block device operation.
4576 Members
4578 type: string
4579 the job type ('stream' for image streaming)
4580 device: string
4582 The job identifier. Originally the device name but other values
4583 are allowed since QEMU 2.7
4584 len: int
4586 Estimated offset value at the completion of the job. This value
4587 can arbitrarily change while the job is running, in both direc‐
4588 tions.
4589 offset: int
4591 Progress made until now. The unit is arbitrary and the value
4592 can only meaningfully be used for the ratio of offset to len.
4593 The value is monotonically increasing.
4594 busy: boolean
4596 false if the job is known to be in a quiescent state, with no
4597 pending I/O. (Since 1.3)
4598 paused: boolean
4600 whether the job is paused or, if busy is true, will pause itself
4601 as soon as possible. (Since 1.3)
4602 speed: int
4604 the rate limit, bytes per second
4605 io-status: BlockDeviceIoStatus
4607 the status of the job (since 1.3)
4608 ready: boolean
4610 true if the job may be completed (since 2.2)
4611 status: JobStatus
4613 Current job state/status (since 2.12)
4614 auto-finalize: boolean
4616 Job will finalize itself when PENDING, moving to the CONCLUDED
4617 state. (since 2.12)
4618 auto-dismiss: boolean
4620 Job will dismiss itself when CONCLUDED, moving to the NULL state
4621 and disappearing from the query list. (since 2.12)
4622 error: string (optional)
4624 Error information if the job did not complete successfully. Not
4625 set if the job completed successfully. (since 2.12.1)
4626 Since
4628 1.1
4629 query-block-jobs (Command)
4631 Return information about long-running block device operations.
4632 Returns
4634 a list of BlockJobInfo for each active block job
4635 Since
4637 1.1
4638 block_resize (Command)
4640 Resize a block image while a guest is running.
4641 Either device or node-name must be set but not both.
4643 Arguments
4645 device: string (optional)
4646 the name of the device to get the image resized
4647 node-name: string (optional)
4649 graph node name to get the image resized (Since 2.0)
4650 size: int
4652 new image size in bytes
4653 Returns
4655 • nothing on success
4656 • If device is not a valid block device, DeviceNotFound
4658 Since
4660 0.14
4661 Example
4663 -> { "execute": "block_resize",
4664 "arguments": { "device": "scratch", "size": 1073741824 } }
4665 <- { "return": {} }
4666 NewImageMode (Enum)
4668 An enumeration that tells QEMU how to set the backing file path in a
4669 new image file.
4670 Values
4672 existing
4673 QEMU should look for an existing image file.
4674 absolute-paths
4676 QEMU should create a new image with absolute paths for the back‐
4677 ing file. If there is no backing file available, the new image
4678 will not be backed either.
4679 Since
4681 1.1
4682 BlockdevSnapshotSync (Object)
4684 Either device or node-name must be set but not both.
4685 Members
4687 device: string (optional)
4688 the name of the device to take a snapshot of.
4689 node-name: string (optional)
4691 graph node name to generate the snapshot from (Since 2.0)
4692 snapshot-file: string
4694 the target of the new overlay image. If the file exists, or if
4695 it is a device, the overlay will be created in the existing
4696 file/device. Otherwise, a new file will be created.
4697 snapshot-node-name: string (optional)
4699 the graph node name of the new image (Since 2.0)
4700 format: string (optional)
4702 the format of the overlay image, default is 'qcow2'.
4703 mode: NewImageMode (optional)
4705 whether and how QEMU should create a new image, default is 'ab‐
4706 solute-paths'.
4707 BlockdevSnapshot (Object)
4709 Members
4710 node: string
4711 device or node name that will have a snapshot taken.
4712 overlay: string
4714 reference to the existing block device that will become the
4715 overlay of node, as part of taking the snapshot. It must not
4716 have a current backing file (this can be achieved by passing
4717 "backing": null to blockdev-add).
4718 Since
4720 2.5
4721 BackupPerf (Object)
4723 Optional parameters for backup. These parameters don't affect func‐
4724 tionality, but may significantly affect performance.
4725 Members
4727 use-copy-range: boolean (optional)
4728 Use copy offloading. Default false.
4729 max-workers: int (optional)
4731 Maximum number of parallel requests for the sustained background
4732 copying process. Doesn't influence copy-before-write opera‐
4733 tions. Default 64.
4734 max-chunk: int (optional)
4736 Maximum request length for the sustained background copying
4737 process. Doesn't influence copy-before-write operations. 0
4738 means unlimited. If max-chunk is non-zero then it should not be
4739 less than job cluster size which is calculated as maximum of
4740 target image cluster size and 64k. Default 0.
4741 Since
4743 6.0
4744 BackupCommon (Object)
4746 Members
4747 job-id: string (optional)
4748 identifier for the newly-created block job. If omitted, the de‐
4749 vice name will be used. (Since 2.7)
4750 device: string
4752 the device name or node-name of a root node which should be
4753 copied.
4754 sync: MirrorSyncMode
4756 what parts of the disk image should be copied to the destination
4757 (all the disk, only the sectors allocated in the topmost image,
4758 from a dirty bitmap, or only new I/O).
4759 speed: int (optional)
4761 the maximum speed, in bytes per second. The default is 0, for
4762 unlimited.
4763 bitmap: string (optional)
4765 The name of a dirty bitmap to use. Must be present if sync is
4766 "bitmap" or "incremental". Can be present if sync is "full" or
4767 "top". Must not be present otherwise. (Since 2.4
4768 (drive-backup), 3.1 (blockdev-backup))
4769 bitmap-mode: BitmapSyncMode (optional)
4771 Specifies the type of data the bitmap should contain after the
4772 operation concludes. Must be present if a bitmap was provided,
4773 Must NOT be present otherwise. (Since 4.2)
4774 compress: boolean (optional)
4776 true to compress data, if the target format supports it. (de‐
4777 fault: false) (since 2.8)
4778 on-source-error: BlockdevOnError (optional)
4780 the action to take on an error on the source, default 'report'.
4781 'stop' and 'enospc' can only be used if the block device sup‐
4782 ports io-status (see BlockInfo).
4783 on-target-error: BlockdevOnError (optional)
4785 the action to take on an error on the target, default 'report'
4786 (no limitations, since this applies to a different block device
4787 than device).
4788 auto-finalize: boolean (optional)
4790 When false, this job will wait in a PENDING state after it has
4791 finished its work, waiting for block-job-finalize before making
4792 any block graph changes. When true, this job will automatically
4793 perform its abort or commit actions. Defaults to true. (Since
4794 2.12)
4795 auto-dismiss: boolean (optional)
4797 When false, this job will wait in a CONCLUDED state after it has
4798 completely ceased all work, and awaits block-job-dismiss. When
4799 true, this job will automatically disappear from the query list
4800 without user intervention. Defaults to true. (Since 2.12)
4801 filter-node-name: string (optional)
4803 the node name that should be assigned to the filter driver that
4804 the backup job inserts into the graph above node specified by
4805 drive. If this option is not given, a node name is autogener‐
4806 ated. (Since: 4.2)
4807 x-perf: BackupPerf (optional)
4809 Performance options. (Since 6.0)
4810 Features
4812 unstable
4813 Member x-perf is experimental.
4814 Note
4816 on-source-error and on-target-error only affect background I/O. If an
4817 error occurs during a guest write request, the device's rerror/werror
4818 actions will be used.
4819 Since
4821 4.2
4822 DriveBackup (Object)
4824 Members
4825 target: string
4826 the target of the new image. If the file exists, or if it is a
4827 device, the existing file/device will be used as the new desti‐
4828 nation. If it does not exist, a new file will be created.
4829 format: string (optional)
4831 the format of the new destination, default is to probe if mode
4832 is 'existing', else the format of the source
4833 mode: NewImageMode (optional)
4835 whether and how QEMU should create a new image, default is 'ab‐
4836 solute-paths'.
4837 The members of BackupCommon
4839 Since
4841 1.6
4842 BlockdevBackup (Object)
4844 Members
4845 target: string
4846 the device name or node-name of the backup target node.
4847 The members of BackupCommon
4849 Since
4851 2.3
4852 blockdev-snapshot-sync (Command)
4854 Takes a synchronous snapshot of a block device.
4855 For the arguments, see the documentation of BlockdevSnapshotSync.
4857 Returns
4859 • nothing on success
4860 • If device is not a valid block device, DeviceNotFound
4862 Since
4864 0.14
4865 Example
4867 -> { "execute": "blockdev-snapshot-sync",
4868 "arguments": { "device": "ide-hd0",
4869 "snapshot-file":
4870 "/some/place/my-image",
4871 "format": "qcow2" } }
4872 <- { "return": {} }
4873 blockdev-snapshot (Command)
4875 Takes a snapshot of a block device.
4876 Take a snapshot, by installing 'node' as the backing image of 'over‐
4878 lay'. Additionally, if 'node' is associated with a block device, the
4879 block device changes to using 'overlay' as its new active image.
4880 For the arguments, see the documentation of BlockdevSnapshot.
4882 Features
4884 allow-write-only-overlay
4885 If present, the check whether this operation is safe was relaxed
4886 so that it can be used to change backing file of a destination
4887 of a blockdev-mirror. (since 5.0)
4888 Since
4890 2.5
4891 Example
4893 -> { "execute": "blockdev-add",
4894 "arguments": { "driver": "qcow2",
4895 "node-name": "node1534",
4896 "file": { "driver": "file",
4897 "filename": "hd1.qcow2" },
4898 "backing": null } }
4899 <- { "return": {} }
4901 -> { "execute": "blockdev-snapshot",
4903 "arguments": { "node": "ide-hd0",
4904 "overlay": "node1534" } }
4905 <- { "return": {} }
4906 change-backing-file (Command)
4908 Change the backing file in the image file metadata. This does not
4909 cause QEMU to reopen the image file to reparse the backing filename (it
4910 may, however, perform a reopen to change permissions from r/o -> r/w ->
4911 r/o, if needed). The new backing file string is written into the image
4912 file metadata, and the QEMU internal strings are updated.
4913 Arguments
4915 image-node-name: string
4916 The name of the block driver state node of the image to modify.
4917 The "device" argument is used to verify "image-node-name" is in
4918 the chain described by "device".
4919 device: string
4921 The device name or node-name of the root node that owns im‐
4922 age-node-name.
4923 backing-file: string
4925 The string to write as the backing file. This string is not
4926 validated, so care should be taken when specifying the string or
4927 the image chain may not be able to be reopened again.
4928 Returns
4930 • Nothing on success
4931 • If "device" does not exist or cannot be determined, DeviceNotFound
4933 Since
4935 2.1
4936 block-commit (Command)
4938 Live commit of data from overlay image nodes into backing nodes - i.e.,
4939 writes data between 'top' and 'base' into 'base'.
4940 If top == base, that is an error. If top has no overlays on top of it,
4942 or if it is in use by a writer, the job will not be completed by it‐
4943 self. The user needs to complete the job with the block-job-complete
4944 command after getting the ready event. (Since 2.0)
4945 If the base image is smaller than top, then the base image will be re‐
4947 sized to be the same size as top. If top is smaller than the base im‐
4948 age, the base will not be truncated. If you want the base image size
4949 to match the size of the smaller top, you can safely truncate it your‐
4950 self once the commit operation successfully completes.
4951 Arguments
4953 job-id: string (optional)
4954 identifier for the newly-created block job. If omitted, the de‐
4955 vice name will be used. (Since 2.7)
4956 device: string
4958 the device name or node-name of a root node
4959 base-node: string (optional)
4961 The node name of the backing image to write data into. If not
4962 specified, this is the deepest backing image. (since: 3.1)
4963 base: string (optional)
4965 Same as base-node, except that it is a file name rather than a
4966 node name. This must be the exact filename string that was used
4967 to open the node; other strings, even if addressing the same
4968 file, are not accepted
4969 top-node: string (optional)
4971 The node name of the backing image within the image chain which
4972 contains the topmost data to be committed down. If not speci‐
4973 fied, this is the active layer. (since: 3.1)
4974 top: string (optional)
4976 Same as top-node, except that it is a file name rather than a
4977 node name. This must be the exact filename string that was used
4978 to open the node; other strings, even if addressing the same
4979 file, are not accepted
4980 backing-file: string (optional)
4982 The backing file string to write into the overlay image of
4983 'top'. If 'top' does not have an overlay image, or if 'top' is
4984 in use by a writer, specifying a backing file string is an er‐
4985 ror.
4986 This filename is not validated. If a pathname string is such
4988 that it cannot be resolved by QEMU, that means that subsequent
4989 QMP or HMP commands must use node-names for the image in ques‐
4990 tion, as filename lookup methods will fail.
4991 If not specified, QEMU will automatically determine the backing
4993 file string to use, or error out if there is no obvious choice.
4994 Care should be taken when specifying the string, to specify a
4995 valid filename or protocol. (Since 2.1)
4996 speed: int (optional)
4998 the maximum speed, in bytes per second
4999 on-error: BlockdevOnError (optional)
5001 the action to take on an error. 'ignore' means that the request
5002 should be retried. (default: report; Since: 5.0)
5003 filter-node-name: string (optional)
5005 the node name that should be assigned to the filter driver that
5006 the commit job inserts into the graph above top. If this option
5007 is not given, a node name is autogenerated. (Since: 2.9)
5008 auto-finalize: boolean (optional)
5010 When false, this job will wait in a PENDING state after it has
5011 finished its work, waiting for block-job-finalize before making
5012 any block graph changes. When true, this job will automatically
5013 perform its abort or commit actions. Defaults to true. (Since
5014 3.1)
5015 auto-dismiss: boolean (optional)
5017 When false, this job will wait in a CONCLUDED state after it has
5018 completely ceased all work, and awaits block-job-dismiss. When
5019 true, this job will automatically disappear from the query list
5020 without user intervention. Defaults to true. (Since 3.1)
5021 Features
5023 deprecated
5024 Members base and top are deprecated. Use base-node and top-node
5025 instead.
5026 Returns
5028 • Nothing on success
5029 • If device does not exist, DeviceNotFound
5031 • Any other error returns a GenericError.
5033 Since
5035 1.3
5036 Example
5038 -> { "execute": "block-commit",
5039 "arguments": { "device": "virtio0",
5040 "top": "/tmp/snap1.qcow2" } }
5041 <- { "return": {} }
5042 drive-backup (Command)
5044 Start a point-in-time copy of a block device to a new destination. The
5045 status of ongoing drive-backup operations can be checked with
5046 query-block-jobs where the BlockJobInfo.type field has the value
5047 'backup'. The operation can be stopped before it has completed using
5048 the block-job-cancel command.
5049 Arguments
5051 The members of DriveBackup
5052 Features
5054 deprecated
5055 This command is deprecated. Use blockdev-backup instead.
5056 Returns
5058 • nothing on success
5059 • If device is not a valid block device, GenericError
5061 Since
5063 1.6
5064 Example
5066 -> { "execute": "drive-backup",
5067 "arguments": { "device": "drive0",
5068 "sync": "full",
5069 "target": "backup.img" } }
5070 <- { "return": {} }
5071 blockdev-backup (Command)
5073 Start a point-in-time copy of a block device to a new destination. The
5074 status of ongoing blockdev-backup operations can be checked with
5075 query-block-jobs where the BlockJobInfo.type field has the value
5076 'backup'. The operation can be stopped before it has completed using
5077 the block-job-cancel command.
5078 Arguments
5080 The members of BlockdevBackup
5081 Returns
5083 • nothing on success
5084 • If device is not a valid block device, DeviceNotFound
5086 Since
5088 2.3
5089 Example
5091 -> { "execute": "blockdev-backup",
5092 "arguments": { "device": "src-id",
5093 "sync": "full",
5094 "target": "tgt-id" } }
5095 <- { "return": {} }
5096 query-named-block-nodes (Command)
5098 Get the named block driver list
5099 Arguments
5101 flat: boolean (optional)
5102 Omit the nested data about backing image ("backing-image" key)
5103 if true. Default is false (Since 5.0)
5104 Returns
5106 the list of BlockDeviceInfo
5107 Since
5109 2.0
5110 Example
5112 -> { "execute": "query-named-block-nodes" }
5113 <- { "return": [ { "ro":false,
5114 "drv":"qcow2",
5115 "encrypted":false,
5116 "file":"disks/test.qcow2",
5117 "node-name": "my-node",
5118 "backing_file_depth":1,
5119 "detect_zeroes":"off",
5120 "bps":1000000,
5121 "bps_rd":0,
5122 "bps_wr":0,
5123 "iops":1000000,
5124 "iops_rd":0,
5125 "iops_wr":0,
5126 "bps_max": 8000000,
5127 "bps_rd_max": 0,
5128 "bps_wr_max": 0,
5129 "iops_max": 0,
5130 "iops_rd_max": 0,
5131 "iops_wr_max": 0,
5132 "iops_size": 0,
5133 "write_threshold": 0,
5134 "image":{
5135 "filename":"disks/test.qcow2",
5136 "format":"qcow2",
5137 "virtual-size":2048000,
5138 "backing_file":"base.qcow2",
5139 "full-backing-filename":"disks/base.qcow2",
5140 "backing-filename-format":"qcow2",
5141 "snapshots":[
5142 {
5143 "id": "1",
5144 "name": "snapshot1",
5145 "vm-state-size": 0,
5146 "date-sec": 10000200,
5147 "date-nsec": 12,
5148 "vm-clock-sec": 206,
5149 "vm-clock-nsec": 30
5150 }
5151 ],
5152 "backing-image":{
5153 "filename":"disks/base.qcow2",
5154 "format":"qcow2",
5155 "virtual-size":2048000
5156 }
5157 } } ] }
5158 XDbgBlockGraphNodeType (Enum)
5160 Values
5161 block-backend
5162 corresponds to BlockBackend
5163 block-job
5165 corresponds to BlockJob
5166 block-driver
5168 corresponds to BlockDriverState
5169 Since
5171 4.0
5172 XDbgBlockGraphNode (Object)
5174 Members
5175 id: int
5176 Block graph node identifier. This id is generated only for
5177 x-debug-query-block-graph and does not relate to any other iden‐
5178 tifiers in Qemu.
5179 type: XDbgBlockGraphNodeType
5181 Type of graph node. Can be one of block-backend, block-job or
5182 block-driver-state.
5183 name: string
5185 Human readable name of the node. Corresponds to node-name for
5186 block-driver-state nodes; is not guaranteed to be unique in the
5187 whole graph (with block-jobs and block-backends).
5188 Since
5190 4.0
5191 BlockPermission (Enum)
5193 Enum of base block permissions.
5194 Values
5196 consistent-read
5197 A user that has the "permission" of consistent reads is guaran‐
5198 teed that their view of the contents of the block device is com‐
5199 plete and self-consistent, representing the contents of a disk
5200 at a specific point. For most block devices (including their
5201 backing files) this is true, but the property cannot be main‐
5202 tained in a few situations like for intermediate nodes of a com‐
5203 mit block job.
5204 write This permission is required to change the visible disk contents.
5206 write-unchanged
5208 This permission (which is weaker than BLK_PERM_WRITE) is both
5209 enough and required for writes to the block node when the caller
5210 promises that the visible disk content doesn't change. As the
5211 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
5212 cient to perform an unchanging write.
5213 resize This permission is required to change the size of a block node.
5215 Since
5217 4.0
5218 XDbgBlockGraphEdge (Object)
5220 Block Graph edge description for x-debug-query-block-graph.
5221 Members
5223 parent: int
5224 parent id
5225 child: int
5227 child id
5228 name: string
5230 name of the relation (examples are 'file' and 'backing')
5231 perm: array of BlockPermission
5233 granted permissions for the parent operating on the child
5234 shared-perm: array of BlockPermission
5236 permissions that can still be granted to other users of the
5237 child while it is still attached to this parent
5238 Since
5240 4.0
5241 XDbgBlockGraph (Object)
5243 Block Graph - list of nodes and list of edges.
5244 Members
5246 nodes: array of XDbgBlockGraphNode
5247 Not documented
5248 edges: array of XDbgBlockGraphEdge
5250 Not documented
5251 Since
5253 4.0
5254 x-debug-query-block-graph (Command)
5256 Get the block graph.
5257 Features
5259 unstable
5260 This command is meant for debugging.
5261 Since
5263 4.0
5264 drive-mirror (Command)
5266 Start mirroring a block device's writes to a new destination. target
5267 specifies the target of the new image. If the file exists, or if it is
5268 a device, it will be used as the new destination for writes. If it
5269 does not exist, a new file will be created. format specifies the for‐
5270 mat of the mirror image, default is to probe if mode='existing', else
5271 the format of the source.
5272 Arguments
5274 The members of DriveMirror
5275 Returns
5277 • nothing on success
5278 • If device is not a valid block device, GenericError
5280 Since
5282 1.3
5283 Example
5285 -> { "execute": "drive-mirror",
5286 "arguments": { "device": "ide-hd0",
5287 "target": "/some/place/my-image",
5288 "sync": "full",
5289 "format": "qcow2" } }
5290 <- { "return": {} }
5291 DriveMirror (Object)
5293 A set of parameters describing drive mirror setup.
5294 Members
5296 job-id: string (optional)
5297 identifier for the newly-created block job. If omitted, the de‐
5298 vice name will be used. (Since 2.7)
5299 device: string
5301 the device name or node-name of a root node whose writes should
5302 be mirrored.
5303 target: string
5305 the target of the new image. If the file exists, or if it is a
5306 device, the existing file/device will be used as the new desti‐
5307 nation. If it does not exist, a new file will be created.
5308 format: string (optional)
5310 the format of the new destination, default is to probe if mode
5311 is 'existing', else the format of the source
5312 node-name: string (optional)
5314 the new block driver state node name in the graph (Since 2.1)
5315 replaces: string (optional)
5317 with sync=full graph node name to be replaced by the new image
5318 when a whole image copy is done. This can be used to repair
5319 broken Quorum files. By default, device is replaced, although
5320 implicitly created filters on it are kept. (Since 2.1)
5321 mode: NewImageMode (optional)
5323 whether and how QEMU should create a new image, default is 'ab‐
5324 solute-paths'.
5325 speed: int (optional)
5327 the maximum speed, in bytes per second
5328 sync: MirrorSyncMode
5330 what parts of the disk image should be copied to the destination
5331 (all the disk, only the sectors allocated in the topmost image,
5332 or only new I/O).
5333 granularity: int (optional)
5335 granularity of the dirty bitmap, default is 64K if the image
5336 format doesn't have clusters, 4K if the clusters are smaller
5337 than that, else the cluster size. Must be a power of 2 between
5338 512 and 64M (since 1.4).
5339 buf-size: int (optional)
5341 maximum amount of data in flight from source to target (since
5342 1.4).
5343 on-source-error: BlockdevOnError (optional)
5345 the action to take on an error on the source, default 'report'.
5346 'stop' and 'enospc' can only be used if the block device sup‐
5347 ports io-status (see BlockInfo).
5348 on-target-error: BlockdevOnError (optional)
5350 the action to take on an error on the target, default 'report'
5351 (no limitations, since this applies to a different block device
5352 than device).
5353 unmap: boolean (optional)
5355 Whether to try to unmap target sectors where source has only
5356 zero. If true, and target unallocated sectors will read as
5357 zero, target image sectors will be unmapped; otherwise, zeroes
5358 will be written. Both will result in identical contents. De‐
5359 fault is true. (Since 2.4)
5360 copy-mode: MirrorCopyMode (optional)
5362 when to copy data to the destination; defaults to 'background'
5363 (Since: 3.0)
5364 auto-finalize: boolean (optional)
5366 When false, this job will wait in a PENDING state after it has
5367 finished its work, waiting for block-job-finalize before making
5368 any block graph changes. When true, this job will automatically
5369 perform its abort or commit actions. Defaults to true. (Since
5370 3.1)
5371 auto-dismiss: boolean (optional)
5373 When false, this job will wait in a CONCLUDED state after it has
5374 completely ceased all work, and awaits block-job-dismiss. When
5375 true, this job will automatically disappear from the query list
5376 without user intervention. Defaults to true. (Since 3.1)
5377 Since
5379 1.3
5380 BlockDirtyBitmap (Object)
5382 Members
5383 node: string
5384 name of device/node which the bitmap is tracking
5385 name: string
5387 name of the dirty bitmap
5388 Since
5390 2.4
5391 BlockDirtyBitmapAdd (Object)
5393 Members
5394 node: string
5395 name of device/node which the bitmap is tracking
5396 name: string
5398 name of the dirty bitmap (must be less than 1024 bytes)
5399 granularity: int (optional)
5401 the bitmap granularity, default is 64k for block-dirty-bit‐
5402 map-add
5403 persistent: boolean (optional)
5405 the bitmap is persistent, i.e. it will be saved to the corre‐
5406 sponding block device image file on its close. For now only
5407 Qcow2 disks support persistent bitmaps. Default is false for
5408 block-dirty-bitmap-add. (Since: 2.10)
5409 disabled: boolean (optional)
5411 the bitmap is created in the disabled state, which means that it
5412 will not track drive changes. The bitmap may be enabled with
5413 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
5414 Since
5416 2.4
5417 BlockDirtyBitmapOrStr (Alternate)
5419 Members
5420 local: string
5421 name of the bitmap, attached to the same node as target bitmap.
5422 external: BlockDirtyBitmap
5424 bitmap with specified node
5425 Since
5427 4.1
5428 BlockDirtyBitmapMerge (Object)
5430 Members
5431 node: string
5432 name of device/node which the target bitmap is tracking
5433 target: string
5435 name of the destination dirty bitmap
5436 bitmaps: array of BlockDirtyBitmapOrStr
5438 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
5439 ified BlockDirtyBitmap elements. The latter are supported since
5440 4.1.
5441 Since
5443 4.0
5444 block-dirty-bitmap-add (Command)
5446 Create a dirty bitmap with a name on the node, and start tracking the
5447 writes.
5448 Returns
5450 • nothing on success
5451 • If node is not a valid block device or node, DeviceNotFound
5453 • If name is already taken, GenericError with an explanation
5455 Since
5457 2.4
5458 Example
5460 -> { "execute": "block-dirty-bitmap-add",
5461 "arguments": { "node": "drive0", "name": "bitmap0" } }
5462 <- { "return": {} }
5463 block-dirty-bitmap-remove (Command)
5465 Stop write tracking and remove the dirty bitmap that was created with
5466 block-dirty-bitmap-add. If the bitmap is persistent, remove it from
5467 its storage too.
5468 Returns
5470 • nothing on success
5471 • If node is not a valid block device or node, DeviceNotFound
5473 • If name is not found, GenericError with an explanation
5475 • if name is frozen by an operation, GenericError
5477 Since
5479 2.4
5480 Example
5482 -> { "execute": "block-dirty-bitmap-remove",
5483 "arguments": { "node": "drive0", "name": "bitmap0" } }
5484 <- { "return": {} }
5485 block-dirty-bitmap-clear (Command)
5487 Clear (reset) a dirty bitmap on the device, so that an incremental
5488 backup from this point in time forward will only backup clusters modi‐
5489 fied after this clear operation.
5490 Returns
5492 • nothing on success
5493 • If node is not a valid block device, DeviceNotFound
5495 • If name is not found, GenericError with an explanation
5497 Since
5499 2.4
5500 Example
5502 -> { "execute": "block-dirty-bitmap-clear",
5503 "arguments": { "node": "drive0", "name": "bitmap0" } }
5504 <- { "return": {} }
5505 block-dirty-bitmap-enable (Command)
5507 Enables a dirty bitmap so that it will begin tracking disk changes.
5508 Returns
5510 • nothing on success
5511 • If node is not a valid block device, DeviceNotFound
5513 • If name is not found, GenericError with an explanation
5515 Since
5517 4.0
5518 Example
5520 -> { "execute": "block-dirty-bitmap-enable",
5521 "arguments": { "node": "drive0", "name": "bitmap0" } }
5522 <- { "return": {} }
5523 block-dirty-bitmap-disable (Command)
5525 Disables a dirty bitmap so that it will stop tracking disk changes.
5526 Returns
5528 • nothing on success
5529 • If node is not a valid block device, DeviceNotFound
5531 • If name is not found, GenericError with an explanation
5533 Since
5535 4.0
5536 Example
5538 -> { "execute": "block-dirty-bitmap-disable",
5539 "arguments": { "node": "drive0", "name": "bitmap0" } }
5540 <- { "return": {} }
5541 block-dirty-bitmap-merge (Command)
5543 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
5544 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
5545 as the target bitmap. Any bits already set in target will still be set
5546 after the merge, i.e., this operation does not clear the target. On
5547 error, target is unchanged.
5548 The resulting bitmap will count as dirty any clusters that were dirty
5550 in any of the source bitmaps. This can be used to achieve backup
5551 checkpoints, or in simpler usages, to copy bitmaps.
5552 Returns
5554 • nothing on success
5555 • If node is not a valid block device, DeviceNotFound
5557 • If any bitmap in bitmaps or target is not found, GenericError
5559 • If any of the bitmaps have different sizes or granularities, Gener‐
5561 icError
5562 Since
5564 4.0
5565 Example
5567 -> { "execute": "block-dirty-bitmap-merge",
5568 "arguments": { "node": "drive0", "target": "bitmap0",
5569 "bitmaps": ["bitmap1"] } }
5570 <- { "return": {} }
5571 BlockDirtyBitmapSha256 (Object)
5573 SHA256 hash of dirty bitmap data
5574 Members
5576 sha256: string
5577 ASCII representation of SHA256 bitmap hash
5578 Since
5580 2.10
5581 x-debug-block-dirty-bitmap-sha256 (Command)
5583 Get bitmap SHA256.
5584 Features
5586 unstable
5587 This command is meant for debugging.
5588 Returns
5590 • BlockDirtyBitmapSha256 on success
5591 • If node is not a valid block device, DeviceNotFound
5593 • If name is not found or if hashing has failed, GenericError with an
5595 explanation
5596 Since
5598 2.10
5599 blockdev-mirror (Command)
5601 Start mirroring a block device's writes to a new destination.
5602 Arguments
5604 job-id: string (optional)
5605 identifier for the newly-created block job. If omitted, the de‐
5606 vice name will be used. (Since 2.7)
5607 device: string
5609 The device name or node-name of a root node whose writes should
5610 be mirrored.
5611 target: string
5613 the id or node-name of the block device to mirror to. This
5614 mustn't be attached to guest.
5615 replaces: string (optional)
5617 with sync=full graph node name to be replaced by the new image
5618 when a whole image copy is done. This can be used to repair
5619 broken Quorum files. By default, device is replaced, although
5620 implicitly created filters on it are kept.
5621 speed: int (optional)
5623 the maximum speed, in bytes per second
5624 sync: MirrorSyncMode
5626 what parts of the disk image should be copied to the destination
5627 (all the disk, only the sectors allocated in the topmost image,
5628 or only new I/O).
5629 granularity: int (optional)
5631 granularity of the dirty bitmap, default is 64K if the image
5632 format doesn't have clusters, 4K if the clusters are smaller
5633 than that, else the cluster size. Must be a power of 2 between
5634 512 and 64M
5635 buf-size: int (optional)
5637 maximum amount of data in flight from source to target
5638 on-source-error: BlockdevOnError (optional)
5640 the action to take on an error on the source, default 'report'.
5641 'stop' and 'enospc' can only be used if the block device sup‐
5642 ports io-status (see BlockInfo).
5643 on-target-error: BlockdevOnError (optional)
5645 the action to take on an error on the target, default 'report'
5646 (no limitations, since this applies to a different block device
5647 than device).
5648 filter-node-name: string (optional)
5650 the node name that should be assigned to the filter driver that
5651 the mirror job inserts into the graph above device. If this op‐
5652 tion is not given, a node name is autogenerated. (Since: 2.9)
5653 copy-mode: MirrorCopyMode (optional)
5655 when to copy data to the destination; defaults to 'background'
5656 (Since: 3.0)
5657 auto-finalize: boolean (optional)
5659 When false, this job will wait in a PENDING state after it has
5660 finished its work, waiting for block-job-finalize before making
5661 any block graph changes. When true, this job will automatically
5662 perform its abort or commit actions. Defaults to true. (Since
5663 3.1)
5664 auto-dismiss: boolean (optional)
5666 When false, this job will wait in a CONCLUDED state after it has
5667 completely ceased all work, and awaits block-job-dismiss. When
5668 true, this job will automatically disappear from the query list
5669 without user intervention. Defaults to true. (Since 3.1)
5670 Returns
5672 nothing on success.
5673 Since
5675 2.6
5676 Example
5678 -> { "execute": "blockdev-mirror",
5679 "arguments": { "device": "ide-hd0",
5680 "target": "target0",
5681 "sync": "full" } }
5682 <- { "return": {} }
5683 BlockIOThrottle (Object)
5685 A set of parameters describing block throttling.
5686 Members
5688 device: string (optional)
5689 Block device name
5690 id: string (optional)
5692 The name or QOM path of the guest device (since: 2.8)
5693 bps: int
5695 total throughput limit in bytes per second
5696 bps_rd: int
5698 read throughput limit in bytes per second
5699 bps_wr: int
5701 write throughput limit in bytes per second
5702 iops: int
5704 total I/O operations per second
5705 iops_rd: int
5707 read I/O operations per second
5708 iops_wr: int
5710 write I/O operations per second
5711 bps_max: int (optional)
5713 total throughput limit during bursts, in bytes (Since 1.7)
5714 bps_rd_max: int (optional)
5716 read throughput limit during bursts, in bytes (Since 1.7)
5717 bps_wr_max: int (optional)
5719 write throughput limit during bursts, in bytes (Since 1.7)
5720 iops_max: int (optional)
5722 total I/O operations per second during bursts, in bytes (Since
5723 1.7)
5724 iops_rd_max: int (optional)
5726 read I/O operations per second during bursts, in bytes (Since
5727 1.7)
5728 iops_wr_max: int (optional)
5730 write I/O operations per second during bursts, in bytes (Since
5731 1.7)
5732 bps_max_length: int (optional)
5734 maximum length of the bps_max burst period, in seconds. It must
5735 only be set if bps_max is set as well. Defaults to 1. (Since
5736 2.6)
5737 bps_rd_max_length: int (optional)
5739 maximum length of the bps_rd_max burst period, in seconds. It
5740 must only be set if bps_rd_max is set as well. Defaults to 1.
5741 (Since 2.6)
5742 bps_wr_max_length: int (optional)
5744 maximum length of the bps_wr_max burst period, in seconds. It
5745 must only be set if bps_wr_max is set as well. Defaults to 1.
5746 (Since 2.6)
5747 iops_max_length: int (optional)
5749 maximum length of the iops burst period, in seconds. It must
5750 only be set if iops_max is set as well. Defaults to 1. (Since
5751 2.6)
5752 iops_rd_max_length: int (optional)
5754 maximum length of the iops_rd_max burst period, in seconds. It
5755 must only be set if iops_rd_max is set as well. Defaults to 1.
5756 (Since 2.6)
5757 iops_wr_max_length: int (optional)
5759 maximum length of the iops_wr_max burst period, in seconds. It
5760 must only be set if iops_wr_max is set as well. Defaults to 1.
5761 (Since 2.6)
5762 iops_size: int (optional)
5764 an I/O size in bytes (Since 1.7)
5765 group: string (optional)
5767 throttle group name (Since 2.4)
5768 Features
5770 deprecated
5771 Member device is deprecated. Use id instead.
5772 Since
5774 1.1
5775 ThrottleLimits (Object)
5777 Limit parameters for throttling. Since some limit combinations are il‐
5778 legal, limits should always be set in one transaction. All fields are
5779 optional. When setting limits, if a field is missing the current value
5780 is not changed.
5781 Members
5783 iops-total: int (optional)
5784 limit total I/O operations per second
5785 iops-total-max: int (optional)
5787 I/O operations burst
5788 iops-total-max-length: int (optional)
5790 length of the iops-total-max burst period, in seconds It must
5791 only be set if iops-total-max is set as well.
5792 iops-read: int (optional)
5794 limit read operations per second
5795 iops-read-max: int (optional)
5797 I/O operations read burst
5798 iops-read-max-length: int (optional)
5800 length of the iops-read-max burst period, in seconds It must
5801 only be set if iops-read-max is set as well.
5802 iops-write: int (optional)
5804 limit write operations per second
5805 iops-write-max: int (optional)
5807 I/O operations write burst
5808 iops-write-max-length: int (optional)
5810 length of the iops-write-max burst period, in seconds It must
5811 only be set if iops-write-max is set as well.
5812 bps-total: int (optional)
5814 limit total bytes per second
5815 bps-total-max: int (optional)
5817 total bytes burst
5818 bps-total-max-length: int (optional)
5820 length of the bps-total-max burst period, in seconds. It must
5821 only be set if bps-total-max is set as well.
5822 bps-read: int (optional)
5824 limit read bytes per second
5825 bps-read-max: int (optional)
5827 total bytes read burst
5828 bps-read-max-length: int (optional)
5830 length of the bps-read-max burst period, in seconds It must only
5831 be set if bps-read-max is set as well.
5832 bps-write: int (optional)
5834 limit write bytes per second
5835 bps-write-max: int (optional)
5837 total bytes write burst
5838 bps-write-max-length: int (optional)
5840 length of the bps-write-max burst period, in seconds It must
5841 only be set if bps-write-max is set as well.
5842 iops-size: int (optional)
5844 when limiting by iops max size of an I/O in bytes
5845 Since
5847 2.11
5848 ThrottleGroupProperties (Object)
5850 Properties for throttle-group objects.
5851 Members
5853 limits: ThrottleLimits (optional)
5854 limits to apply for this throttle group
5855 x-iops-total: int (optional)
5857 Not documented
5858 x-iops-total-max: int (optional)
5860 Not documented
5861 x-iops-total-max-length: int (optional)
5863 Not documented
5864 x-iops-read: int (optional)
5866 Not documented
5867 x-iops-read-max: int (optional)
5869 Not documented
5870 x-iops-read-max-length: int (optional)
5872 Not documented
5873 x-iops-write: int (optional)
5875 Not documented
5876 x-iops-write-max: int (optional)
5878 Not documented
5879 x-iops-write-max-length: int (optional)
5881 Not documented
5882 x-bps-total: int (optional)
5884 Not documented
5885 x-bps-total-max: int (optional)
5887 Not documented
5888 x-bps-total-max-length: int (optional)
5890 Not documented
5891 x-bps-read: int (optional)
5893 Not documented
5894 x-bps-read-max: int (optional)
5896 Not documented
5897 x-bps-read-max-length: int (optional)
5899 Not documented
5900 x-bps-write: int (optional)
5902 Not documented
5903 x-bps-write-max: int (optional)
5905 Not documented
5906 x-bps-write-max-length: int (optional)
5908 Not documented
5909 x-iops-size: int (optional)
5911 Not documented
5912 Features
5914 unstable
5915 All members starting with x- are aliases for the same key with‐
5916 out x- in the limits object. This is not a stable interface and
5917 may be removed or changed incompatibly in the future. Use lim‐
5918 its for a supported stable interface.
5919 Since
5921 2.11
5922 block-stream (Command)
5924 Copy data from a backing file into a block device.
5925 The block streaming operation is performed in the background until the
5927 entire backing file has been copied. This command returns immediately
5928 once streaming has started. The status of ongoing block streaming op‐
5929 erations can be checked with query-block-jobs. The operation can be
5930 stopped before it has completed using the block-job-cancel command.
5931 The node that receives the data is called the top image, can be located
5933 in any part of the chain (but always above the base image; see below)
5934 and can be specified using its device or node name. Earlier qemu ver‐
5935 sions only allowed 'device' to name the top level node; presence of the
5936 'base-node' parameter during introspection can be used as a witness of
5937 the enhanced semantics of 'device'.
5938 If a base file is specified then sectors are not copied from that base
5940 file and its backing chain. This can be used to stream a subset of the
5941 backing file chain instead of flattening the entire image. When
5942 streaming completes the image file will have the base file as its back‐
5943 ing file, unless that node was changed while the job was running. In
5944 that case, base's parent's backing (or filtered, whichever exists)
5945 child (i.e., base at the beginning of the job) will be the new backing
5946 file.
5947 On successful completion the image file is updated to drop the backing
5949 file and the BLOCK_JOB_COMPLETED event is emitted.
5950 In case device is a filter node, block-stream modifies the first
5952 non-filter overlay node below it to point to the new backing node in‐
5953 stead of modifying device itself.
5954 Arguments
5956 job-id: string (optional)
5957 identifier for the newly-created block job. If omitted, the de‐
5958 vice name will be used. (Since 2.7)
5959 device: string
5961 the device or node name of the top image
5962 base: string (optional)
5964 the common backing file name. It cannot be set if base-node or
5965 bottom is also set.
5966 base-node: string (optional)
5968 the node name of the backing file. It cannot be set if base or
5969 bottom is also set. (Since 2.8)
5970 bottom: string (optional)
5972 the last node in the chain that should be streamed into top. It
5973 cannot be set if base or base-node is also set. It cannot be
5974 filter node. (Since 6.0)
5975 backing-file: string (optional)
5977 The backing file string to write into the top image. This file‐
5978 name is not validated.
5979 If a pathname string is such that it cannot be resolved by QEMU,
5981 that means that subsequent QMP or HMP commands must use
5982 node-names for the image in question, as filename lookup methods
5983 will fail.
5984 If not specified, QEMU will automatically determine the backing
5986 file string to use, or error out if there is no obvious choice.
5987 Care should be taken when specifying the string, to specify a
5988 valid filename or protocol. (Since 2.1)
5989 speed: int (optional)
5991 the maximum speed, in bytes per second
5992 on-error: BlockdevOnError (optional)
5994 the action to take on an error (default report). 'stop' and
5995 'enospc' can only be used if the block device supports io-status
5996 (see BlockInfo). (Since 1.3)
5997 filter-node-name: string (optional)
5999 the node name that should be assigned to the filter driver that
6000 the stream job inserts into the graph above device. If this op‐
6001 tion is not given, a node name is autogenerated. (Since: 6.0)
6002 auto-finalize: boolean (optional)
6004 When false, this job will wait in a PENDING state after it has
6005 finished its work, waiting for block-job-finalize before making
6006 any block graph changes. When true, this job will automatically
6007 perform its abort or commit actions. Defaults to true. (Since
6008 3.1)
6009 auto-dismiss: boolean (optional)
6011 When false, this job will wait in a CONCLUDED state after it has
6012 completely ceased all work, and awaits block-job-dismiss. When
6013 true, this job will automatically disappear from the query list
6014 without user intervention. Defaults to true. (Since 3.1)
6015 Returns
6017 • Nothing on success.
6018 • If device does not exist, DeviceNotFound.
6020 Since
6022 1.1
6023 Example
6025 -> { "execute": "block-stream",
6026 "arguments": { "device": "virtio0",
6027 "base": "/tmp/master.qcow2" } }
6028 <- { "return": {} }
6029 block-job-set-speed (Command)
6031 Set maximum speed for a background block operation.
6032 This command can only be issued when there is an active block job.
6034 Throttling can be disabled by setting the speed to 0.
6036 Arguments
6038 device: string
6039 The job identifier. This used to be a device name (hence the
6040 name of the parameter), but since QEMU 2.7 it can have other
6041 values.
6042 speed: int
6044 the maximum speed, in bytes per second, or 0 for unlimited. De‐
6045 faults to 0.
6046 Returns
6048 • Nothing on success
6049 • If no background operation is active on this device, DeviceNotActive
6051 Since
6053 1.1
6054 block-job-cancel (Command)
6056 Stop an active background block operation.
6057 This command returns immediately after marking the active background
6059 block operation for cancellation. It is an error to call this command
6060 if no operation is in progress.
6061 The operation will cancel as soon as possible and then emit the
6063 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
6064 ble when enumerated using query-block-jobs.
6065 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
6067 dicated (via the event BLOCK_JOB_READY) that the source and destination
6068 are synchronized, then the event triggered by this command changes to
6069 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
6070 destination now has a point-in-time copy tied to the time of the can‐
6071 cellation.
6072 For streaming, the image file retains its backing file unless the
6074 streaming operation happens to complete just as it is being cancelled.
6075 A new streaming operation can be started at a later time to finish
6076 copying all data from the backing file.
6077 Arguments
6079 device: string
6080 The job identifier. This used to be a device name (hence the
6081 name of the parameter), but since QEMU 2.7 it can have other
6082 values.
6083 force: boolean (optional)
6085 If true, and the job has already emitted the event
6086 BLOCK_JOB_READY, abandon the job immediately (even if it is
6087 paused) instead of waiting for the destination to complete its
6088 final synchronization (since 1.3)
6089 Returns
6091 • Nothing on success
6092 • If no background operation is active on this device, DeviceNotActive
6094 Since
6096 1.1
6097 block-job-pause (Command)
6099 Pause an active background block operation.
6100 This command returns immediately after marking the active background
6102 block operation for pausing. It is an error to call this command if no
6103 operation is in progress or if the job is already paused.
6104 The operation will pause as soon as possible. No event is emitted when
6106 the operation is actually paused. Cancelling a paused job automati‐
6107 cally resumes it.
6108 Arguments
6110 device: string
6111 The job identifier. This used to be a device name (hence the
6112 name of the parameter), but since QEMU 2.7 it can have other
6113 values.
6114 Returns
6116 • Nothing on success
6117 • If no background operation is active on this device, DeviceNotActive
6119 Since
6121 1.3
6122 block-job-resume (Command)
6124 Resume an active background block operation.
6125 This command returns immediately after resuming a paused background
6127 block operation. It is an error to call this command if no operation
6128 is in progress or if the job is not paused.
6129 This command also clears the error status of the job.
6131 Arguments
6133 device: string
6134 The job identifier. This used to be a device name (hence the
6135 name of the parameter), but since QEMU 2.7 it can have other
6136 values.
6137 Returns
6139 • Nothing on success
6140 • If no background operation is active on this device, DeviceNotActive
6142 Since
6144 1.3
6145 block-job-complete (Command)
6147 Manually trigger completion of an active background block operation.
6148 This is supported for drive mirroring, where it also switches the de‐
6149 vice to write to the target path only. The ability to complete is sig‐
6150 naled with a BLOCK_JOB_READY event.
6151 This command completes an active background block operation syn‐
6153 chronously. The ordering of this command's return with the
6154 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
6155 occurs during the processing of this command: 1) the command itself
6156 will fail; 2) the error will be processed according to the rerror/wer‐
6157 ror arguments that were specified when starting the operation.
6158 A cancelled or paused job cannot be completed.
6160 Arguments
6162 device: string
6163 The job identifier. This used to be a device name (hence the
6164 name of the parameter), but since QEMU 2.7 it can have other
6165 values.
6166 Returns
6168 • Nothing on success
6169 • If no background operation is active on this device, DeviceNotActive
6171 Since
6173 1.3
6174 block-job-dismiss (Command)
6176 For jobs that have already concluded, remove them from the
6177 block-job-query list. This command only needs to be run for jobs which
6178 were started with QEMU 2.12+ job lifetime management semantics.
6179 This command will refuse to operate on any job that has not yet reached
6181 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
6182 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
6183 still need to be used as appropriate.
6184 Arguments
6186 id: string
6187 The job identifier.
6188 Returns
6190 Nothing on success
6191 Since
6193 2.12
6194 block-job-finalize (Command)
6196 Once a job that has manual=true reaches the pending state, it can be
6197 instructed to finalize any graph changes and do any necessary cleanup
6198 via this command. For jobs in a transaction, instructing one job to
6199 finalize will force ALL jobs in the transaction to finalize, so it is
6200 only necessary to instruct a single member job to finalize.
6201 Arguments
6203 id: string
6204 The job identifier.
6205 Returns
6207 Nothing on success
6208 Since
6210 2.12
6211 BlockdevDiscardOptions (Enum)
6213 Determines how to handle discard requests.
6214 Values
6216 ignore Ignore the request
6217 unmap Forward as an unmap request
6219 Since
6221 2.9
6222 BlockdevDetectZeroesOptions (Enum)
6224 Describes the operation mode for the automatic conversion of plain zero
6225 writes by the OS to driver specific optimized zero write commands.
6226 Values
6228 off Disabled (default)
6229 on Enabled
6231 unmap Enabled and even try to unmap blocks if possible. This requires
6233 also that BlockdevDiscardOptions is set to unmap for this de‐
6234 vice.
6235 Since
6237 2.1
6238 BlockdevAioOptions (Enum)
6240 Selects the AIO backend to handle I/O requests
6241 Values
6243 threads
6244 Use qemu's thread pool
6245 native Use native AIO backend (only Linux and Windows)
6247 io_uring (If: CONFIG_LINUX_IO_URING)
6249 Use linux io_uring (since 5.0)
6250 Since
6252 2.9
6253 BlockdevCacheOptions (Object)
6255 Includes cache-related options for block devices
6256 Members
6258 direct: boolean (optional)
6259 enables use of O_DIRECT (bypass the host page cache; default:
6260 false)
6261 no-flush: boolean (optional)
6263 ignore any flush requests for the device (default: false)
6264 Since
6266 2.9
6267 BlockdevDriver (Enum)
6269 Drivers that are supported in block device operations.
6270 Values
6272 throttle
6273 Since 2.11
6274 nvme Since 2.12
6276 copy-on-read
6278 Since 3.0
6279 blklogwrites
6281 Since 3.0
6282 blkreplay
6284 Since 4.2
6285 compress
6287 Since 5.0
6288 copy-before-write
6290 Since 6.2
6291 snapshot-access
6293 Since 7.0
6294 blkdebug
6296 Not documented
6297 blkverify
6299 Not documented
6300 bochs Not documented
6302 cloop Not documented
6304 dmg Not documented
6306 file Not documented
6308 ftp Not documented
6310 ftps Not documented
6312 gluster
6314 Not documented
6315 host_cdrom (If: HAVE_HOST_BLOCK_DEVICE)
6317 Not documented
6318 host_device (If: HAVE_HOST_BLOCK_DEVICE)
6320 Not documented
6321 http Not documented
6323 https Not documented
6325 io_uring (If: CONFIG_BLKIO)
6327 Not documented
6328 iscsi Not documented
6330 luks Not documented
6332 nbd Not documented
6334 nfs Not documented
6336 null-aio
6338 Not documented
6339 null-co
6341 Not documented
6342 nvme-io_uring (If: CONFIG_BLKIO)
6344 Not documented
6345 parallels
6347 Not documented
6348 preallocate
6350 Not documented
6351 qcow Not documented
6353 qcow2 Not documented
6355 qed Not documented
6357 quorum Not documented
6359 raw Not documented
6361 rbd Not documented
6363 replication (If: CONFIG_REPLICATION)
6365 Not documented
6366 ssh Not documented
6368 vdi Not documented
6370 vhdx Not documented
6372 virtio-blk-vfio-pci (If: CONFIG_BLKIO)
6374 Not documented
6375 virtio-blk-vhost-user (If: CONFIG_BLKIO)
6377 Not documented
6378 virtio-blk-vhost-vdpa (If: CONFIG_BLKIO)
6380 Not documented
6381 vmdk Not documented
6383 vpc Not documented
6385 vvfat Not documented
6387 Since
6389 2.9
6390 BlockdevOptionsFile (Object)
6392 Driver specific block device options for the file backend.
6393 Members
6395 filename: string
6396 path to the image file
6397 pr-manager: string (optional)
6399 the id for the object that will handle persistent reservations
6400 for this device (default: none, forward the commands via SG_IO;
6401 since 2.11)
6402 aio: BlockdevAioOptions (optional)
6404 AIO backend (default: threads) (since: 2.8)
6405 aio-max-batch: int (optional)
6407 maximum number of requests to batch together into a single sub‐
6408 mission in the AIO backend. The smallest value between this and
6409 the aio-max-batch value of the IOThread object is chosen. 0
6410 means that the AIO backend will handle it automatically. (de‐
6411 fault: 0, since 6.2)
6412 locking: OnOffAuto (optional)
6414 whether to enable file locking. If set to 'auto', only enable
6415 when Open File Descriptor (OFD) locking API is available (de‐
6416 fault: auto, since 2.10)
6417 drop-cache: boolean (optional) (If: CONFIG_LINUX)
6419 invalidate page cache during live migration. This prevents
6420 stale data on the migration destination with cache.direct=off.
6421 Currently only supported on Linux hosts. (default: on, since:
6422 4.0)
6423 x-check-cache-dropped: boolean (optional)
6425 whether to check that page cache was dropped on live migration.
6426 May cause noticeable delays if the image file is large, do not
6427 use in production. (default: off) (since: 3.0)
6428 Features
6430 dynamic-auto-read-only
6431 If present, enabled auto-read-only means that the driver will
6432 open the image read-only at first, dynamically reopen the image
6433 file read-write when the first writer is attached to the node
6434 and reopen read-only when the last writer is detached. This al‐
6435 lows giving QEMU write permissions only on demand when an opera‐
6436 tion actually needs write access.
6437 unstable
6439 Member x-check-cache-dropped is meant for debugging.
6440 Since
6442 2.9
6443 BlockdevOptionsNull (Object)
6445 Driver specific block device options for the null backend.
6446 Members
6448 size: int (optional)
6449 size of the device in bytes.
6450 latency-ns: int (optional)
6452 emulated latency (in nanoseconds) in processing requests. De‐
6453 fault to zero which completes requests immediately. (Since 2.4)
6454 read-zeroes: boolean (optional)
6456 if true, reads from the device produce zeroes; if false, the
6457 buffer is left unchanged. (default: false; since: 4.1)
6458 Since
6460 2.9
6461 BlockdevOptionsNVMe (Object)
6463 Driver specific block device options for the NVMe backend.
6464 Members
6466 device: string
6467 PCI controller address of the NVMe device in format hhhh:bb:ss.f
6468 (host:bus:slot.function)
6469 namespace: int
6471 namespace number of the device, starting from 1.
6472 Note that the PCI device must have been unbound from any host kernel
6473 driver before instructing QEMU to add the blockdev.
6474 Since
6476 2.12
6477 BlockdevOptionsVVFAT (Object)
6479 Driver specific block device options for the vvfat protocol.
6480 Members
6482 dir: string
6483 directory to be exported as FAT image
6484 fat-type: int (optional)
6486 FAT type: 12, 16 or 32
6487 floppy: boolean (optional)
6489 whether to export a floppy image (true) or partitioned hard disk
6490 (false; default)
6491 label: string (optional)
6493 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
6494 ditionally have some restrictions on labels, which are ignored
6495 by most operating systems. Defaults to "QEMU VVFAT". (since
6496 2.4)
6497 rw: boolean (optional)
6499 whether to allow write operations (default: false)
6500 Since
6502 2.9
6503 BlockdevOptionsGenericFormat (Object)
6505 Driver specific block device options for image format that have no op‐
6506 tion besides their data source.
6507 Members
6509 file: BlockdevRef
6510 reference to or definition of the data source block device
6511 Since
6513 2.9
6514 BlockdevOptionsLUKS (Object)
6516 Driver specific block device options for LUKS.
6517 Members
6519 key-secret: string (optional)
6520 the ID of a QCryptoSecret object providing the decryption key
6521 (since 2.6). Mandatory except when doing a metadata-only probe
6522 of the image.
6523 The members of BlockdevOptionsGenericFormat
6525 Since
6527 2.9
6528 BlockdevOptionsGenericCOWFormat (Object)
6530 Driver specific block device options for image format that have no op‐
6531 tion besides their data source and an optional backing file.
6532 Members
6534 backing: BlockdevRefOrNull (optional)
6535 reference to or definition of the backing file block device,
6536 null disables the backing file entirely. Defaults to the back‐
6537 ing file stored the image file.
6538 The members of BlockdevOptionsGenericFormat
6540 Since
6542 2.9
6543 Qcow2OverlapCheckMode (Enum)
6545 General overlap check modes.
6546 Values
6548 none Do not perform any checks
6549 constant
6551 Perform only checks which can be done in constant time and with‐
6552 out reading anything from disk
6553 cached Perform only checks which can be done without reading anything
6555 from disk
6556 all Perform all available overlap checks
6558 Since
6560 2.9
6561 Qcow2OverlapCheckFlags (Object)
6563 Structure of flags for each metadata structure. Setting a field to
6564 'true' makes qemu guard that structure against unintended overwriting.
6565 The default value is chosen according to the template given.
6566 Members
6568 template: Qcow2OverlapCheckMode (optional)
6569 Specifies a template mode which can be adjusted using the other
6570 flags, defaults to 'cached'
6571 bitmap-directory: boolean (optional)
6573 since 3.0
6574 main-header: boolean (optional)
6576 Not documented
6577 active-l1: boolean (optional)
6579 Not documented
6580 active-l2: boolean (optional)
6582 Not documented
6583 refcount-table: boolean (optional)
6585 Not documented
6586 refcount-block: boolean (optional)
6588 Not documented
6589 snapshot-table: boolean (optional)
6591 Not documented
6592 inactive-l1: boolean (optional)
6594 Not documented
6595 inactive-l2: boolean (optional)
6597 Not documented
6598 Since
6600 2.9
6601 Qcow2OverlapChecks (Alternate)
6603 Specifies which metadata structures should be guarded against unin‐
6604 tended overwriting.
6605 Members
6607 flags: Qcow2OverlapCheckFlags
6608 set of flags for separate specification of each metadata struc‐
6609 ture type
6610 mode: Qcow2OverlapCheckMode
6612 named mode which chooses a specific set of flags
6613 Since
6615 2.9
6616 BlockdevQcowEncryptionFormat (Enum)
6618 Values
6619 aes AES-CBC with plain64 initialization vectors
6620 Since
6622 2.10
6623 BlockdevQcowEncryption (Object)
6625 Members
6626 format: BlockdevQcowEncryptionFormat
6627 Not documented
6628 The members of QCryptoBlockOptionsQCow when format is "aes"
6630 Since
6632 2.10
6633 BlockdevOptionsQcow (Object)
6635 Driver specific block device options for qcow.
6636 Members
6638 encrypt: BlockdevQcowEncryption (optional)
6639 Image decryption options. Mandatory for encrypted images, ex‐
6640 cept when doing a metadata-only probe of the image.
6641 The members of BlockdevOptionsGenericCOWFormat
6643 Since
6645 2.10
6646 BlockdevQcow2EncryptionFormat (Enum)
6648 Values
6649 aes AES-CBC with plain64 initialization vectors
6650 luks Not documented
6652 Since
6654 2.10
6655 BlockdevQcow2Encryption (Object)
6657 Members
6658 format: BlockdevQcow2EncryptionFormat
6659 Not documented
6660 The members of QCryptoBlockOptionsQCow when format is "aes"
6662 The members of QCryptoBlockOptionsLUKS when format is "luks"
6664 Since
6666 2.10
6667 BlockdevOptionsPreallocate (Object)
6669 Filter driver intended to be inserted between format and protocol node
6670 and do preallocation in protocol node on write.
6671 Members
6673 prealloc-align: int (optional)
6674 on preallocation, align file length to this number, default
6675 1048576 (1M)
6676 prealloc-size: int (optional)
6678 how much to preallocate, default 134217728 (128M)
6679 The members of BlockdevOptionsGenericFormat
6681 Since
6683 6.0
6684 BlockdevOptionsQcow2 (Object)
6686 Driver specific block device options for qcow2.
6687 Members
6689 lazy-refcounts: boolean (optional)
6690 whether to enable the lazy refcounts feature (default is taken
6691 from the image file)
6692 pass-discard-request: boolean (optional)
6694 whether discard requests to the qcow2 device should be forwarded
6695 to the data source
6696 pass-discard-snapshot: boolean (optional)
6698 whether discard requests for the data source should be issued
6699 when a snapshot operation (e.g. deleting a snapshot) frees clus‐
6700 ters in the qcow2 file
6701 pass-discard-other: boolean (optional)
6703 whether discard requests for the data source should be issued on
6704 other occasions where a cluster gets freed
6705 discard-no-unref: boolean (optional)
6707 when enabled, data clusters will remain preallocated when they
6708 are no longer used, e.g. because they are discarded or converted
6709 to zero clusters. As usual, whether the old data is discarded
6710 or kept on the protocol level (i.e. in the image file) depends
6711 on the setting of the pass-discard-request option. Keeping the
6712 clusters preallocated prevents qcow2 fragmentation that would
6713 otherwise be caused by freeing and re-allocating them later.
6714 Besides potential performance degradation, such fragmentation
6715 can lead to increased allocation of clusters past the end of the
6716 image file, resulting in image files whose file length can grow
6717 much larger than their guest disk size would suggest. If image
6718 file length is of concern (e.g. when storing qcow2 images di‐
6719 rectly on block devices), you should consider enabling this op‐
6720 tion. (since 8.1)
6721 overlap-check: Qcow2OverlapChecks (optional)
6723 which overlap checks to perform for writes to the image, de‐
6724 faults to 'cached' (since 2.2)
6725 cache-size: int (optional)
6727 the maximum total size of the L2 table and refcount block caches
6728 in bytes (since 2.2)
6729 l2-cache-size: int (optional)
6731 the maximum size of the L2 table cache in bytes (since 2.2)
6732 l2-cache-entry-size: int (optional)
6734 the size of each entry in the L2 cache in bytes. It must be a
6735 power of two between 512 and the cluster size. The default
6736 value is the cluster size (since 2.12)
6737 refcount-cache-size: int (optional)
6739 the maximum size of the refcount block cache in bytes (since
6740 2.2)
6741 cache-clean-interval: int (optional)
6743 clean unused entries in the L2 and refcount caches. The inter‐
6744 val is in seconds. The default value is 600 on supporting plat‐
6745 forms, and 0 on other platforms. 0 disables this feature.
6746 (since 2.5)
6747 encrypt: BlockdevQcow2Encryption (optional)
6749 Image decryption options. Mandatory for encrypted images, ex‐
6750 cept when doing a metadata-only probe of the image. (since
6751 2.10)
6752 data-file: BlockdevRef (optional)
6754 reference to or definition of the external data file. This may
6755 only be specified for images that require an external data file.
6756 If it is not specified for such an image, the data file name is
6757 loaded from the image file. (since 4.0)
6758 The members of BlockdevOptionsGenericCOWFormat
6760 Since
6762 2.9
6763 SshHostKeyCheckMode (Enum)
6765 Values
6766 none Don't check the host key at all
6767 hash Compare the host key with a given hash
6769 known_hosts
6771 Check the host key against the known_hosts file
6772 Since
6774 2.12
6775 SshHostKeyCheckHashType (Enum)
6777 Values
6778 md5 The given hash is an md5 hash
6779 sha1 The given hash is an sha1 hash
6781 sha256 The given hash is an sha256 hash
6783 Since
6785 2.12
6786 SshHostKeyHash (Object)
6788 Members
6789 type: SshHostKeyCheckHashType
6790 The hash algorithm used for the hash
6791 hash: string
6793 The expected hash value
6794 Since
6796 2.12
6797 SshHostKeyCheck (Object)
6799 Members
6800 mode: SshHostKeyCheckMode
6801 Not documented
6802 The members of SshHostKeyHash when mode is "hash"
6804 Since
6806 2.12
6807 BlockdevOptionsSsh (Object)
6809 Members
6810 server: InetSocketAddress
6811 host address
6812 path: string
6814 path to the image on the host
6815 user: string (optional)
6817 user as which to connect, defaults to current local user name
6818 host-key-check: SshHostKeyCheck (optional)
6820 Defines how and what to check the host key against (default:
6821 known_hosts)
6822 Since
6824 2.9
6825 BlkdebugEvent (Enum)
6827 Trigger events supported by blkdebug.
6828 Values
6830 l1_shrink_write_table
6831 write zeros to the l1 table to shrink image. (since 2.11)
6832 l1_shrink_free_l2_clusters
6834 discard the l2 tables. (since 2.11)
6835 cor_write
6837 a write due to copy-on-read (since 2.11)
6838 cluster_alloc_space
6840 an allocation of file space for a cluster (since 4.1)
6841 none triggers once at creation of the blkdebug node (since 4.1)
6843 l1_update
6845 Not documented
6846 l1_grow_alloc_table
6848 Not documented
6849 l1_grow_write_table
6851 Not documented
6852 l1_grow_activate_table
6854 Not documented
6855 l2_load
6857 Not documented
6858 l2_update
6860 Not documented
6861 l2_update_compressed
6863 Not documented
6864 l2_alloc_cow_read
6866 Not documented
6867 l2_alloc_write
6869 Not documented
6870 read_aio
6872 Not documented
6873 read_backing_aio
6875 Not documented
6876 read_compressed
6878 Not documented
6879 write_aio
6881 Not documented
6882 write_compressed
6884 Not documented
6885 vmstate_load
6887 Not documented
6888 vmstate_save
6890 Not documented
6891 cow_read
6893 Not documented
6894 cow_write
6896 Not documented
6897 reftable_load
6899 Not documented
6900 reftable_grow
6902 Not documented
6903 reftable_update
6905 Not documented
6906 refblock_load
6908 Not documented
6909 refblock_update
6911 Not documented
6912 refblock_update_part
6914 Not documented
6915 refblock_alloc
6917 Not documented
6918 refblock_alloc_hookup
6920 Not documented
6921 refblock_alloc_write
6923 Not documented
6924 refblock_alloc_write_blocks
6926 Not documented
6927 refblock_alloc_write_table
6929 Not documented
6930 refblock_alloc_switch_table
6932 Not documented
6933 cluster_alloc
6935 Not documented
6936 cluster_alloc_bytes
6938 Not documented
6939 cluster_free
6941 Not documented
6942 flush_to_os
6944 Not documented
6945 flush_to_disk
6947 Not documented
6948 pwritev_rmw_head
6950 Not documented
6951 pwritev_rmw_after_head
6953 Not documented
6954 pwritev_rmw_tail
6956 Not documented
6957 pwritev_rmw_after_tail
6959 Not documented
6960 pwritev
6962 Not documented
6963 pwritev_zero
6965 Not documented
6966 pwritev_done
6968 Not documented
6969 empty_image_prepare
6971 Not documented
6972 Since
6974 2.9
6975 BlkdebugIOType (Enum)
6977 Kinds of I/O that blkdebug can inject errors in.
6978 Values
6980 read .bdrv_co_preadv()
6981 write .bdrv_co_pwritev()
6983 write-zeroes
6985 .bdrv_co_pwrite_zeroes()
6986 discard
6988 .bdrv_co_pdiscard()
6989 flush .bdrv_co_flush_to_disk()
6991 block-status
6993 .bdrv_co_block_status()
6994 Since
6996 4.1
6997 BlkdebugInjectErrorOptions (Object)
6999 Describes a single error injection for blkdebug.
7000 Members
7002 event: BlkdebugEvent
7003 trigger event
7004 state: int (optional)
7006 the state identifier blkdebug needs to be in to actually trigger
7007 the event; defaults to "any"
7008 iotype: BlkdebugIOType (optional)
7010 the type of I/O operations on which this error should be in‐
7011 jected; defaults to "all read, write, write-zeroes, discard, and
7012 flush operations" (since: 4.1)
7013 errno: int (optional)
7015 error identifier (errno) to be returned; defaults to EIO
7016 sector: int (optional)
7018 specifies the sector index which has to be affected in order to
7019 actually trigger the event; defaults to "any sector"
7020 once: boolean (optional)
7022 disables further events after this one has been triggered; de‐
7023 faults to false
7024 immediately: boolean (optional)
7026 fail immediately; defaults to false
7027 Since
7029 2.9
7030 BlkdebugSetStateOptions (Object)
7032 Describes a single state-change event for blkdebug.
7033 Members
7035 event: BlkdebugEvent
7036 trigger event
7037 state: int (optional)
7039 the current state identifier blkdebug needs to be in; defaults
7040 to "any"
7041 new_state: int
7043 the state identifier blkdebug is supposed to assume if this
7044 event is triggered
7045 Since
7047 2.9
7048 BlockdevOptionsBlkdebug (Object)
7050 Driver specific block device options for blkdebug.
7051 Members
7053 image: BlockdevRef
7054 underlying raw block device (or image file)
7055 config: string (optional)
7057 filename of the configuration file
7058 align: int (optional)
7060 required alignment for requests in bytes, must be positive power
7061 of 2, or 0 for default
7062 max-transfer: int (optional)
7064 maximum size for I/O transfers in bytes, must be positive multi‐
7065 ple of align and of the underlying file's request alignment (but
7066 need not be a power of 2), or 0 for default (since 2.10)
7067 opt-write-zero: int (optional)
7069 preferred alignment for write zero requests in bytes, must be
7070 positive multiple of align and of the underlying file's request
7071 alignment (but need not be a power of 2), or 0 for default
7072 (since 2.10)
7073 max-write-zero: int (optional)
7075 maximum size for write zero requests in bytes, must be positive
7076 multiple of align, of opt-write-zero, and of the underlying
7077 file's request alignment (but need not be a power of 2), or 0
7078 for default (since 2.10)
7079 opt-discard: int (optional)
7081 preferred alignment for discard requests in bytes, must be posi‐
7082 tive multiple of align and of the underlying file's request
7083 alignment (but need not be a power of 2), or 0 for default
7084 (since 2.10)
7085 max-discard: int (optional)
7087 maximum size for discard requests in bytes, must be positive
7088 multiple of align, of opt-discard, and of the underlying file's
7089 request alignment (but need not be a power of 2), or 0 for de‐
7090 fault (since 2.10)
7091 inject-error: array of BlkdebugInjectErrorOptions (optional)
7093 array of error injection descriptions
7094 set-state: array of BlkdebugSetStateOptions (optional)
7096 array of state-change descriptions
7097 take-child-perms: array of BlockPermission (optional)
7099 Permissions to take on image in addition to what is necessary
7100 anyway (which depends on how the blkdebug node is used). De‐
7101 faults to none. (since 5.0)
7102 unshare-child-perms: array of BlockPermission (optional)
7104 Permissions not to share on image in addition to what cannot be
7105 shared anyway (which depends on how the blkdebug node is used).
7106 Defaults to none. (since 5.0)
7107 Since
7109 2.9
7110 BlockdevOptionsBlklogwrites (Object)
7112 Driver specific block device options for blklogwrites.
7113 Members
7115 file: BlockdevRef
7116 block device
7117 log: BlockdevRef
7119 block device used to log writes to file
7120 log-sector-size: int (optional)
7122 sector size used in logging writes to file, determines granular‐
7123 ity of offsets and sizes of writes (default: 512)
7124 log-append: boolean (optional)
7126 append to an existing log (default: false)
7127 log-super-update-interval: int (optional)
7129 interval of write requests after which the log super block is
7130 updated to disk (default: 4096)
7131 Since
7133 3.0
7134 BlockdevOptionsBlkverify (Object)
7136 Driver specific block device options for blkverify.
7137 Members
7139 test: BlockdevRef
7140 block device to be tested
7141 raw: BlockdevRef
7143 raw image used for verification
7144 Since
7146 2.9
7147 BlockdevOptionsBlkreplay (Object)
7149 Driver specific block device options for blkreplay.
7150 Members
7152 image: BlockdevRef
7153 disk image which should be controlled with blkreplay
7154 Since
7156 4.2
7157 QuorumReadPattern (Enum)
7159 An enumeration of quorum read patterns.
7160 Values
7162 quorum read all the children and do a quorum vote on reads
7163 fifo read only from the first child that has not failed
7165 Since
7167 2.9
7168 BlockdevOptionsQuorum (Object)
7170 Driver specific block device options for Quorum
7171 Members
7173 blkverify: boolean (optional)
7174 true if the driver must print content mismatch set to false by
7175 default
7176 children: array of BlockdevRef
7178 the children block devices to use
7179 vote-threshold: int
7181 the vote limit under which a read will fail
7182 rewrite-corrupted: boolean (optional)
7184 rewrite corrupted data when quorum is reached (Since 2.1)
7185 read-pattern: QuorumReadPattern (optional)
7187 choose read pattern and set to quorum by default (Since 2.2)
7188 Since
7190 2.9
7191 BlockdevOptionsGluster (Object)
7193 Driver specific block device options for Gluster
7194 Members
7196 volume: string
7197 name of gluster volume where VM image resides
7198 path: string
7200 absolute path to image file in gluster volume
7201 server: array of SocketAddress
7203 gluster servers description
7204 debug: int (optional)
7206 libgfapi log level (default '4' which is Error) (Since 2.8)
7207 logfile: string (optional)
7209 libgfapi log file (default /dev/stderr) (Since 2.8)
7210 Since
7212 2.9
7213 BlockdevOptionsIoUring (Object)
7215 Driver specific block device options for the io_uring backend.
7216 Members
7218 filename: string
7219 path to the image file
7220 Since
7222 7.2
7223 If
7225 CONFIG_BLKIO
7226 BlockdevOptionsNvmeIoUring (Object)
7228 Driver specific block device options for the nvme-io_uring backend.
7229 Members
7231 path: string
7232 path to the NVMe namespace's character device (e.g.
7233 /dev/ng0n1).
7234 Since
7236 7.2
7237 If
7239 CONFIG_BLKIO
7240 BlockdevOptionsVirtioBlkVfioPci (Object)
7242 Driver specific block device options for the virtio-blk-vfio-pci back‐
7243 end.
7244 Members
7246 path: string
7247 path to the PCI device's sysfs directory (e.g. /sys/bus/pci/de‐
7248 vices/0000:00:01.0).
7249 Since
7251 7.2
7252 If
7254 CONFIG_BLKIO
7255 BlockdevOptionsVirtioBlkVhostUser (Object)
7257 Driver specific block device options for the virtio-blk-vhost-user
7258 backend.
7259 Members
7261 path: string
7262 path to the vhost-user UNIX domain socket.
7263 Since
7265 7.2
7266 If
7268 CONFIG_BLKIO
7269 BlockdevOptionsVirtioBlkVhostVdpa (Object)
7271 Driver specific block device options for the virtio-blk-vhost-vdpa
7272 backend.
7273 Members
7275 path: string
7276 path to the vhost-vdpa character device.
7277 Features
7279 fdset Member path supports the special "/dev/fdset/N" path (since 8.1)
7280 Since
7282 7.2
7283 If
7285 CONFIG_BLKIO
7286 IscsiTransport (Enum)
7288 An enumeration of libiscsi transport types
7289 Values
7291 tcp Not documented
7292 iser Not documented
7294 Since
7296 2.9
7297 IscsiHeaderDigest (Enum)
7299 An enumeration of header digests supported by libiscsi
7300 Values
7302 crc32c Not documented
7303 none Not documented
7305 crc32c-none
7307 Not documented
7308 none-crc32c
7310 Not documented
7311 Since
7313 2.9
7314 BlockdevOptionsIscsi (Object)
7316 Members
7317 transport: IscsiTransport
7318 The iscsi transport type
7319 portal: string
7321 The address of the iscsi portal
7322 target: string
7324 The target iqn name
7325 lun: int (optional)
7327 LUN to connect to. Defaults to 0.
7328 user: string (optional)
7330 User name to log in with. If omitted, no CHAP authentication is
7331 performed.
7332 password-secret: string (optional)
7334 The ID of a QCryptoSecret object providing the password for the
7335 login. This option is required if user is specified.
7336 initiator-name: string (optional)
7338 The iqn name we want to identify to the target as. If this op‐
7339 tion is not specified, an initiator name is generated automati‐
7340 cally.
7341 header-digest: IscsiHeaderDigest (optional)
7343 The desired header digest. Defaults to none-crc32c.
7344 timeout: int (optional)
7346 Timeout in seconds after which a request will timeout. 0 means
7347 no timeout and is the default.
7348 Driver specific block device options for iscsi
7349 Since
7351 2.9
7352 RbdAuthMode (Enum)
7354 Values
7355 cephx Not documented
7356 none Not documented
7358 Since
7360 3.0
7361 RbdImageEncryptionFormat (Enum)
7363 Values
7364 luks-any
7365 Used for opening either luks or luks2 (Since 8.0)
7366 luks Not documented
7368 luks2 Not documented
7370 Since
7372 6.1
7373 RbdEncryptionOptionsLUKSBase (Object)
7375 Members
7376 key-secret: string
7377 ID of a QCryptoSecret object providing a passphrase for unlock‐
7378 ing the encryption
7379 Since
7381 6.1
7382 RbdEncryptionCreateOptionsLUKSBase (Object)
7384 Members
7385 cipher-alg: QCryptoCipherAlgorithm (optional)
7386 The encryption algorithm
7387 The members of RbdEncryptionOptionsLUKSBase
7389 Since
7391 6.1
7392 RbdEncryptionOptionsLUKS (Object)
7394 Members
7395 The members of RbdEncryptionOptionsLUKSBase
7396 Since
7398 6.1
7399 RbdEncryptionOptionsLUKS2 (Object)
7401 Members
7402 The members of RbdEncryptionOptionsLUKSBase
7403 Since
7405 6.1
7406 RbdEncryptionOptionsLUKSAny (Object)
7408 Members
7409 The members of RbdEncryptionOptionsLUKSBase
7410 Since
7412 8.0
7413 RbdEncryptionCreateOptionsLUKS (Object)
7415 Members
7416 The members of RbdEncryptionCreateOptionsLUKSBase
7417 Since
7419 6.1
7420 RbdEncryptionCreateOptionsLUKS2 (Object)
7422 Members
7423 The members of RbdEncryptionCreateOptionsLUKSBase
7424 Since
7426 6.1
7427 RbdEncryptionOptions (Object)
7429 Members
7430 format: RbdImageEncryptionFormat
7431 Encryption format.
7432 parent: RbdEncryptionOptions (optional)
7434 Parent image encryption options (for cloned images). Can be
7435 left unspecified if this cloned image is encrypted using the
7436 same format and secret as its parent image (i.e. not explicitly
7437 formatted) or if its parent image is not encrypted. (Since 8.0)
7438 The members of RbdEncryptionOptionsLUKS when format is "luks"
7440 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
7442 The members of RbdEncryptionOptionsLUKSAny when format is "luks-any"
7444 Since
7446 6.1
7447 RbdEncryptionCreateOptions (Object)
7449 Members
7450 format: RbdImageEncryptionFormat
7451 Not documented
7452 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
7454 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
7456 Since
7458 6.1
7459 BlockdevOptionsRbd (Object)
7461 Members
7462 pool: string
7463 Ceph pool name.
7464 namespace: string (optional)
7466 Rados namespace name in the Ceph pool. (Since 5.0)
7467 image: string
7469 Image name in the Ceph pool.
7470 conf: string (optional)
7472 path to Ceph configuration file. Values in the configuration
7473 file will be overridden by options specified via QAPI.
7474 snapshot: string (optional)
7476 Ceph snapshot name.
7477 encrypt: RbdEncryptionOptions (optional)
7479 Image encryption options. (Since 6.1)
7480 user: string (optional)
7482 Ceph id name.
7483 auth-client-required: array of RbdAuthMode (optional)
7485 Acceptable authentication modes. This maps to Ceph configura‐
7486 tion option "auth_client_required". (Since 3.0)
7487 key-secret: string (optional)
7489 ID of a QCryptoSecret object providing a key for cephx authenti‐
7490 cation. This maps to Ceph configuration option "key". (Since
7491 3.0)
7492 server: array of InetSocketAddressBase (optional)
7494 Monitor host address and port. This maps to the "mon_host" Ceph
7495 option.
7496 Since
7498 2.9
7499 ReplicationMode (Enum)
7501 An enumeration of replication modes.
7502 Values
7504 primary
7505 Primary mode, the vm's state will be sent to secondary QEMU.
7506 secondary
7508 Secondary mode, receive the vm's state from primary QEMU.
7509 Since
7511 2.9
7512 If
7514 CONFIG_REPLICATION
7515 BlockdevOptionsReplication (Object)
7517 Driver specific block device options for replication
7518 Members
7520 mode: ReplicationMode
7521 the replication mode
7522 top-id: string (optional)
7524 In secondary mode, node name or device ID of the root node who
7525 owns the replication node chain. Must not be given in primary
7526 mode.
7527 The members of BlockdevOptionsGenericFormat
7529 Since
7531 2.9
7532 If
7534 CONFIG_REPLICATION
7535 NFSTransport (Enum)
7537 An enumeration of NFS transport types
7538 Values
7540 inet TCP transport
7541 Since
7543 2.9
7544 NFSServer (Object)
7546 Captures the address of the socket
7547 Members
7549 type: NFSTransport
7550 transport type used for NFS (only TCP supported)
7551 host: string
7553 host address for NFS server
7554 Since
7556 2.9
7557 BlockdevOptionsNfs (Object)
7559 Driver specific block device option for NFS
7560 Members
7562 server: NFSServer
7563 host address
7564 path: string
7566 path of the image on the host
7567 user: int (optional)
7569 UID value to use when talking to the server (defaults to 65534
7570 on Windows and getuid() on unix)
7571 group: int (optional)
7573 GID value to use when talking to the server (defaults to 65534
7574 on Windows and getgid() in unix)
7575 tcp-syn-count: int (optional)
7577 number of SYNs during the session establishment (defaults to
7578 libnfs default)
7579 readahead-size: int (optional)
7581 set the readahead size in bytes (defaults to libnfs default)
7582 page-cache-size: int (optional)
7584 set the pagecache size in bytes (defaults to libnfs default)
7585 debug: int (optional)
7587 set the NFS debug level (max 2) (defaults to libnfs default)
7588 Since
7590 2.9
7591 BlockdevOptionsCurlBase (Object)
7593 Driver specific block device options shared by all protocols supported
7594 by the curl backend.
7595 Members
7597 url: string
7598 URL of the image file
7599 readahead: int (optional)
7601 Size of the read-ahead cache; must be a multiple of 512 (de‐
7602 faults to 256 kB)
7603 timeout: int (optional)
7605 Timeout for connections, in seconds (defaults to 5)
7606 username: string (optional)
7608 Username for authentication (defaults to none)
7609 password-secret: string (optional)
7611 ID of a QCryptoSecret object providing a password for authenti‐
7612 cation (defaults to no password)
7613 proxy-username: string (optional)
7615 Username for proxy authentication (defaults to none)
7616 proxy-password-secret: string (optional)
7618 ID of a QCryptoSecret object providing a password for proxy au‐
7619 thentication (defaults to no password)
7620 Since
7622 2.9
7623 BlockdevOptionsCurlHttp (Object)
7625 Driver specific block device options for HTTP connections over the curl
7626 backend. URLs must start with "http://".
7627 Members
7629 cookie: string (optional)
7630 List of cookies to set; format is "name1=content1; name2=con‐
7631 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
7632 ies.
7633 cookie-secret: string (optional)
7635 ID of a QCryptoSecret object providing the cookie data in a se‐
7636 cure way. See cookie for the format. (since 2.10)
7637 The members of BlockdevOptionsCurlBase
7639 Since
7641 2.9
7642 BlockdevOptionsCurlHttps (Object)
7644 Driver specific block device options for HTTPS connections over the
7645 curl backend. URLs must start with "https://".
7646 Members
7648 cookie: string (optional)
7649 List of cookies to set; format is "name1=content1; name2=con‐
7650 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
7651 ies.
7652 sslverify: boolean (optional)
7654 Whether to verify the SSL certificate's validity (defaults to
7655 true)
7656 cookie-secret: string (optional)
7658 ID of a QCryptoSecret object providing the cookie data in a se‐
7659 cure way. See cookie for the format. (since 2.10)
7660 The members of BlockdevOptionsCurlBase
7662 Since
7664 2.9
7665 BlockdevOptionsCurlFtp (Object)
7667 Driver specific block device options for FTP connections over the curl
7668 backend. URLs must start with "ftp://".
7669 Members
7671 The members of BlockdevOptionsCurlBase
7672 Since
7674 2.9
7675 BlockdevOptionsCurlFtps (Object)
7677 Driver specific block device options for FTPS connections over the curl
7678 backend. URLs must start with "ftps://".
7679 Members
7681 sslverify: boolean (optional)
7682 Whether to verify the SSL certificate's validity (defaults to
7683 true)
7684 The members of BlockdevOptionsCurlBase
7686 Since
7688 2.9
7689 BlockdevOptionsNbd (Object)
7691 Driver specific block device options for NBD.
7692 Members
7694 server: SocketAddress
7695 NBD server address
7696 export: string (optional)
7698 export name
7699 tls-creds: string (optional)
7701 TLS credentials ID
7702 tls-hostname: string (optional)
7704 TLS hostname override for certificate validation (Since 7.0)
7705 x-dirty-bitmap: string (optional)
7707 A metadata context name such as "qemu:dirty-bitmap:NAME" or
7708 "qemu:allocation-depth" to query in place of the traditional
7709 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
7710 the NBD protocol; and yes, naming this option x-context would
7711 have made more sense) (since 3.0)
7712 reconnect-delay: int (optional)
7714 On an unexpected disconnect, the nbd client tries to connect
7715 again until succeeding or encountering a serious error. During
7716 the first reconnect-delay seconds, all requests are paused and
7717 will be rerun on a successful reconnect. After that time, any
7718 delayed requests and all future requests before a successful re‐
7719 connect will immediately fail. Default 0 (Since 4.2)
7720 open-timeout: int (optional)
7722 In seconds. If zero, the nbd driver tries the connection only
7723 once, and fails to open if the connection fails. If non-zero,
7724 the nbd driver will repeat connection attempts until successful
7725 or until open-timeout seconds have elapsed. Default 0 (Since
7726 7.0)
7727 Features
7729 unstable
7730 Member x-dirty-bitmap is experimental.
7731 Since
7733 2.9
7734 BlockdevOptionsRaw (Object)
7736 Driver specific block device options for the raw driver.
7737 Members
7739 offset: int (optional)
7740 position where the block device starts
7741 size: int (optional)
7743 the assumed size of the device
7744 The members of BlockdevOptionsGenericFormat
7746 Since
7748 2.9
7749 BlockdevOptionsThrottle (Object)
7751 Driver specific block device options for the throttle driver
7752 Members
7754 throttle-group: string
7755 the name of the throttle-group object to use. It must already
7756 exist.
7757 file: BlockdevRef
7759 reference to or definition of the data source block device
7760 Since
7762 2.11
7763 BlockdevOptionsCor (Object)
7765 Driver specific block device options for the copy-on-read driver.
7766 Members
7768 bottom: string (optional)
7769 The name of a non-filter node (allocation-bearing layer) that
7770 limits the COR operations in the backing chain (inclusive), so
7771 that no data below this node will be copied by this filter. If
7772 option is absent, the limit is not applied, so that data from
7773 all backing layers may be copied.
7774 The members of BlockdevOptionsGenericFormat
7776 Since
7778 6.0
7779 OnCbwError (Enum)
7781 An enumeration of possible behaviors for copy-before-write operation
7782 failures.
7783 Values
7785 break-guest-write
7786 report the error to the guest. This way, the guest will not be
7787 able to overwrite areas that cannot be backed up, so the backup
7788 process remains valid.
7789 break-snapshot
7791 continue guest write. Doing so will make the provided snapshot
7792 state invalid and any backup or export process based on it will
7793 finally fail.
7794 Since
7796 7.1
7797 BlockdevOptionsCbw (Object)
7799 Driver specific block device options for the copy-before-write driver,
7800 which does so called copy-before-write operations: when data is written
7801 to the filter, the filter first reads corresponding blocks from its
7802 file child and copies them to target child. After successfully copy‐
7803 ing, the write request is propagated to file child. If copying fails,
7804 the original write request is failed too and no data is written to file
7805 child.
7806 Members
7808 target: BlockdevRef
7809 The target for copy-before-write operations.
7810 bitmap: BlockDirtyBitmap (optional)
7812 If specified, copy-before-write filter will do copy-before-write
7813 operations only for dirty regions of the bitmap. Bitmap size
7814 must be equal to length of file and target child of the filter.
7815 Note also, that bitmap is used only to initialize internal bit‐
7816 map of the process, so further modifications (or removing) of
7817 specified bitmap doesn't influence the filter. (Since 7.0)
7818 on-cbw-error: OnCbwError (optional)
7820 Behavior on failure of copy-before-write operation. Default is
7821 break-guest-write. (Since 7.1)
7822 cbw-timeout: int (optional)
7824 Zero means no limit. Non-zero sets the timeout in seconds for
7825 copy-before-write operation. When a timeout occurs, the respec‐
7826 tive copy-before-write operation will fail, and the on-cbw-error
7827 parameter will decide how this failure is handled. Default 0.
7828 (Since 7.1)
7829 The members of BlockdevOptionsGenericFormat
7831 Since
7833 6.2
7834 BlockdevOptions (Object)
7836 Options for creating a block device. Many options are available for
7837 all block devices, independent of the block driver:
7838 Members
7840 driver: BlockdevDriver
7841 block driver name
7842 node-name: string (optional)
7844 the node name of the new node (Since 2.0). This option is re‐
7845 quired on the top level of blockdev-add. Valid node names start
7846 with an alphabetic character and may contain only alphanumeric
7847 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
7848 ters.
7849 discard: BlockdevDiscardOptions (optional)
7851 discard-related options (default: ignore)
7852 cache: BlockdevCacheOptions (optional)
7854 cache-related options
7855 read-only: boolean (optional)
7857 whether the block device should be read-only (default: false).
7858 Note that some block drivers support only read-only access, ei‐
7859 ther generally or in certain configurations. In this case, the
7860 default value does not work and the option must be specified ex‐
7861 plicitly.
7862 auto-read-only: boolean (optional)
7864 if true and read-only is false, QEMU may automatically decide
7865 not to open the image read-write as requested, but fall back to
7866 read-only instead (and switch between the modes later), e.g. de‐
7867 pending on whether the image file is writable or whether a writ‐
7868 ing user is attached to the node (default: false, since 3.1)
7869 detect-zeroes: BlockdevDetectZeroesOptions (optional)
7871 detect and optimize zero writes (Since 2.1) (default: off)
7872 force-share: boolean (optional)
7874 force share all permission on added nodes. Requires
7875 read-only=true. (Since 2.10)
7876 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
7878 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
7880 writes"
7881 The members of BlockdevOptionsBlkverify when driver is "blkverify"
7883 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
7885 The members of BlockdevOptionsGenericFormat when driver is "bochs"
7887 The members of BlockdevOptionsGenericFormat when driver is "cloop"
7889 The members of BlockdevOptionsGenericFormat when driver is "compress"
7891 The members of BlockdevOptionsCbw when driver is "copy-before-write"
7893 The members of BlockdevOptionsCor when driver is "copy-on-read"
7895 The members of BlockdevOptionsGenericFormat when driver is "dmg"
7897 The members of BlockdevOptionsFile when driver is "file"
7899 The members of BlockdevOptionsCurlFtp when driver is "ftp"
7901 The members of BlockdevOptionsCurlFtps when driver is "ftps"
7903 The members of BlockdevOptionsGluster when driver is "gluster"
7905 The members of BlockdevOptionsFile when driver is "host_cdrom" (If:
7907 HAVE_HOST_BLOCK_DEVICE)
7908 The members of BlockdevOptionsFile when driver is "host_device" (If:
7910 HAVE_HOST_BLOCK_DEVICE)
7911 The members of BlockdevOptionsCurlHttp when driver is "http"
7913 The members of BlockdevOptionsCurlHttps when driver is "https"
7915 The members of BlockdevOptionsIoUring when driver is "io_uring" (If:
7917 CONFIG_BLKIO)
7918 The members of BlockdevOptionsIscsi when driver is "iscsi"
7920 The members of BlockdevOptionsLUKS when driver is "luks"
7922 The members of BlockdevOptionsNbd when driver is "nbd"
7924 The members of BlockdevOptionsNfs when driver is "nfs"
7926 The members of BlockdevOptionsNull when driver is "null-aio"
7928 The members of BlockdevOptionsNull when driver is "null-co"
7930 The members of BlockdevOptionsNVMe when driver is "nvme"
7932 The members of BlockdevOptionsNvmeIoUring when driver is "nvme-io_ur‐
7934 ing" (If: CONFIG_BLKIO)
7935 The members of BlockdevOptionsGenericFormat when driver is "parallels"
7937 The members of BlockdevOptionsPreallocate when driver is "preallocate"
7939 The members of BlockdevOptionsQcow2 when driver is "qcow2"
7941 The members of BlockdevOptionsQcow when driver is "qcow"
7943 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
7945 The members of BlockdevOptionsQuorum when driver is "quorum"
7947 The members of BlockdevOptionsRaw when driver is "raw"
7949 The members of BlockdevOptionsRbd when driver is "rbd"
7951 The members of BlockdevOptionsReplication when driver is "replication"
7953 (If: CONFIG_REPLICATION)
7954 The members of BlockdevOptionsGenericFormat when driver is "snap‐
7956 shot-access"
7957 The members of BlockdevOptionsSsh when driver is "ssh"
7959 The members of BlockdevOptionsThrottle when driver is "throttle"
7961 The members of BlockdevOptionsGenericFormat when driver is "vdi"
7963 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
7965 The members of BlockdevOptionsVirtioBlkVfioPci when driver is "vir‐
7967 tio-blk-vfio-pci" (If: CONFIG_BLKIO)
7968 The members of BlockdevOptionsVirtioBlkVhostUser when driver is "vir‐
7970 tio-blk-vhost-user" (If: CONFIG_BLKIO)
7971 The members of BlockdevOptionsVirtioBlkVhostVdpa when driver is "vir‐
7973 tio-blk-vhost-vdpa" (If: CONFIG_BLKIO)
7974 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
7976 The members of BlockdevOptionsGenericFormat when driver is "vpc"
7978 The members of BlockdevOptionsVVFAT when driver is "vvfat"
7980 Remaining options are determined by the block driver.
7981 Since
7983 2.9
7984 BlockdevRef (Alternate)
7986 Reference to a block device.
7987 Members
7989 definition: BlockdevOptions
7990 defines a new block device inline
7991 reference: string
7993 references the ID of an existing block device
7994 Since
7996 2.9
7997 BlockdevRefOrNull (Alternate)
7999 Reference to a block device.
8000 Members
8002 definition: BlockdevOptions
8003 defines a new block device inline
8004 reference: string
8006 references the ID of an existing block device. An empty string
8007 means that no block device should be referenced. Deprecated;
8008 use null instead.
8009 null: null
8011 No block device should be referenced (since 2.10)
8012 Since
8014 2.9
8015 blockdev-add (Command)
8017 Creates a new block device.
8018 Arguments
8020 The members of BlockdevOptions
8021 Since
8023 2.9
8024 Examples
8026 -> { "execute": "blockdev-add",
8027 "arguments": {
8028 "driver": "qcow2",
8029 "node-name": "test1",
8030 "file": {
8031 "driver": "file",
8032 "filename": "test.qcow2"
8033 }
8034 }
8035 }
8036 <- { "return": {} }
8037 -> { "execute": "blockdev-add",
8039 "arguments": {
8040 "driver": "qcow2",
8041 "node-name": "node0",
8042 "discard": "unmap",
8043 "cache": {
8044 "direct": true
8045 },
8046 "file": {
8047 "driver": "file",
8048 "filename": "/tmp/test.qcow2"
8049 },
8050 "backing": {
8051 "driver": "raw",
8052 "file": {
8053 "driver": "file",
8054 "filename": "/dev/fdset/4"
8055 }
8056 }
8057 }
8058 }
8059 <- { "return": {} }
8061 blockdev-reopen (Command)
8063 Reopens one or more block devices using the given set of options. Any
8064 option not specified will be reset to its default value regardless of
8065 its previous status. If an option cannot be changed or a particular
8066 driver does not support reopening then the command will return an er‐
8067 ror. All devices in the list are reopened in one transaction, so if
8068 one of them fails then the whole transaction is cancelled.
8069 The command receives a list of block devices to reopen. For each one
8071 of them, the top-level node-name option (from BlockdevOptions) must be
8072 specified and is used to select the block device to be reopened. Other
8073 node-name options must be either omitted or set to the current name of
8074 the appropriate node. This command won't change any node name and any
8075 attempt to do it will result in an error.
8076 In the case of options that refer to child nodes, the behavior of this
8078 command depends on the value:
8079 1. A set of options (BlockdevOptions): the child is reopened with
8081 the specified set of options.
8082 2. A reference to the current child: the child is reopened using its
8084 existing set of options.
8085 3. A reference to a different node: the current child is replaced
8087 with the specified one.
8088 4. NULL: the current child (if any) is detached.
8090 Options (1) and (2) are supported in all cases. Option (3) is sup‐
8092 ported for file and backing, and option (4) for backing only.
8093 Unlike with blockdev-add, the backing option must always be present un‐
8095 less the node being reopened does not have a backing file and its image
8096 does not have a default backing file name as part of its metadata.
8097 Arguments
8099 options: array of BlockdevOptions
8100 Not documented
8101 Since
8103 6.1
8104 blockdev-del (Command)
8106 Deletes a block device that has been added using blockdev-add. The
8107 command will fail if the node is attached to a device or is otherwise
8108 being used.
8109 Arguments
8111 node-name: string
8112 Name of the graph node to delete.
8113 Since
8115 2.9
8116 Example
8118 -> { "execute": "blockdev-add",
8119 "arguments": {
8120 "driver": "qcow2",
8121 "node-name": "node0",
8122 "file": {
8123 "driver": "file",
8124 "filename": "test.qcow2"
8125 }
8126 }
8127 }
8128 <- { "return": {} }
8129 -> { "execute": "blockdev-del",
8131 "arguments": { "node-name": "node0" }
8132 }
8133 <- { "return": {} }
8134 BlockdevCreateOptionsFile (Object)
8136 Driver specific image creation options for file.
8137 Members
8139 filename: string
8140 Filename for the new image file
8141 size: int
8143 Size of the virtual disk in bytes
8144 preallocation: PreallocMode (optional)
8146 Preallocation mode for the new image (default: off; allowed val‐
8147 ues: off, falloc (if CONFIG_POSIX_FALLOCATE), full (if CON‐
8148 FIG_POSIX))
8149 nocow: boolean (optional)
8151 Turn off copy-on-write (valid only on btrfs; default: off)
8152 extent-size-hint: int (optional)
8154 Extent size hint to add to the image file; 0 for not adding an
8155 extent size hint (default: 1 MB, since 5.1)
8156 Since
8158 2.12
8159 BlockdevCreateOptionsGluster (Object)
8161 Driver specific image creation options for gluster.
8162 Members
8164 location: BlockdevOptionsGluster
8165 Where to store the new image file
8166 size: int
8168 Size of the virtual disk in bytes
8169 preallocation: PreallocMode (optional)
8171 Preallocation mode for the new image (default: off; allowed val‐
8172 ues: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), full (if CON‐
8173 FIG_GLUSTERFS_ZEROFILL))
8174 Since
8176 2.12
8177 BlockdevCreateOptionsLUKS (Object)
8179 Driver specific image creation options for LUKS.
8180 Members
8182 file: BlockdevRef
8183 Node to create the image format on
8184 size: int
8186 Size of the virtual disk in bytes
8187 preallocation: PreallocMode (optional)
8189 Preallocation mode for the new image (since: 4.2) (default: off;
8190 allowed values: off, metadata, falloc, full)
8191 The members of QCryptoBlockCreateOptionsLUKS
8193 Since
8195 2.12
8196 BlockdevCreateOptionsNfs (Object)
8198 Driver specific image creation options for NFS.
8199 Members
8201 location: BlockdevOptionsNfs
8202 Where to store the new image file
8203 size: int
8205 Size of the virtual disk in bytes
8206 Since
8208 2.12
8209 BlockdevCreateOptionsParallels (Object)
8211 Driver specific image creation options for parallels.
8212 Members
8214 file: BlockdevRef
8215 Node to create the image format on
8216 size: int
8218 Size of the virtual disk in bytes
8219 cluster-size: int (optional)
8221 Cluster size in bytes (default: 1 MB)
8222 Since
8224 2.12
8225 BlockdevCreateOptionsQcow (Object)
8227 Driver specific image creation options for qcow.
8228 Members
8230 file: BlockdevRef
8231 Node to create the image format on
8232 size: int
8234 Size of the virtual disk in bytes
8235 backing-file: string (optional)
8237 File name of the backing file if a backing file should be used
8238 encrypt: QCryptoBlockCreateOptions (optional)
8240 Encryption options if the image should be encrypted
8241 Since
8243 2.12
8244 BlockdevQcow2Version (Enum)
8246 Values
8247 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
8248 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
8250 Since
8252 2.12
8253 Qcow2CompressionType (Enum)
8255 Compression type used in qcow2 image file
8256 Values
8258 zlib zlib compression, see <http://zlib.net/>
8259 zstd (If: CONFIG_ZSTD)
8261 zstd compression, see <http://github.com/facebook/zstd>
8262 Since
8264 5.1
8265 BlockdevCreateOptionsQcow2 (Object)
8267 Driver specific image creation options for qcow2.
8268 Members
8270 file: BlockdevRef
8271 Node to create the image format on
8272 data-file: BlockdevRef (optional)
8274 Node to use as an external data file in which all guest data is
8275 stored so that only metadata remains in the qcow2 file (since:
8276 4.0)
8277 data-file-raw: boolean (optional)
8279 True if the external data file must stay valid as a standalone
8280 (read-only) raw image without looking at qcow2 metadata (de‐
8281 fault: false; since: 4.0)
8282 extended-l2: boolean (optional)
8284 True to make the image have extended L2 entries (default: false;
8285 since 5.2)
8286 size: int
8288 Size of the virtual disk in bytes
8289 version: BlockdevQcow2Version (optional)
8291 Compatibility level (default: v3)
8292 backing-file: string (optional)
8294 File name of the backing file if a backing file should be used
8295 backing-fmt: BlockdevDriver (optional)
8297 Name of the block driver to use for the backing file
8298 encrypt: QCryptoBlockCreateOptions (optional)
8300 Encryption options if the image should be encrypted
8301 cluster-size: int (optional)
8303 qcow2 cluster size in bytes (default: 65536)
8304 preallocation: PreallocMode (optional)
8306 Preallocation mode for the new image (default: off; allowed val‐
8307 ues: off, falloc, full, metadata)
8308 lazy-refcounts: boolean (optional)
8310 True if refcounts may be updated lazily (default: off)
8311 refcount-bits: int (optional)
8313 Width of reference counts in bits (default: 16)
8314 compression-type: Qcow2CompressionType (optional)
8316 The image cluster compression method (default: zlib, since 5.1)
8317 Since
8319 2.12
8320 BlockdevCreateOptionsQed (Object)
8322 Driver specific image creation options for qed.
8323 Members
8325 file: BlockdevRef
8326 Node to create the image format on
8327 size: int
8329 Size of the virtual disk in bytes
8330 backing-file: string (optional)
8332 File name of the backing file if a backing file should be used
8333 backing-fmt: BlockdevDriver (optional)
8335 Name of the block driver to use for the backing file
8336 cluster-size: int (optional)
8338 Cluster size in bytes (default: 65536)
8339 table-size: int (optional)
8341 L1/L2 table size (in clusters)
8342 Since
8344 2.12
8345 BlockdevCreateOptionsRbd (Object)
8347 Driver specific image creation options for rbd/Ceph.
8348 Members
8350 location: BlockdevOptionsRbd
8351 Where to store the new image file. This location cannot point
8352 to a snapshot.
8353 size: int
8355 Size of the virtual disk in bytes
8356 cluster-size: int (optional)
8358 RBD object size
8359 encrypt: RbdEncryptionCreateOptions (optional)
8361 Image encryption options. (Since 6.1)
8362 Since
8364 2.12
8365 BlockdevVmdkSubformat (Enum)
8367 Subformat options for VMDK images
8368 Values
8370 monolithicSparse
8371 Single file image with sparse cluster allocation
8372 monolithicFlat
8374 Single flat data image and a descriptor file
8375 twoGbMaxExtentSparse
8377 Data is split into 2GB (per virtual LBA) sparse extent files, in
8378 addition to a descriptor file
8379 twoGbMaxExtentFlat
8381 Data is split into 2GB (per virtual LBA) flat extent files, in
8382 addition to a descriptor file
8383 streamOptimized
8385 Single file image sparse cluster allocation, optimized for
8386 streaming over network.
8387 Since
8389 4.0
8390 BlockdevVmdkAdapterType (Enum)
8392 Adapter type info for VMDK images
8393 Values
8395 ide Not documented
8396 buslogic
8398 Not documented
8399 lsilogic
8401 Not documented
8402 legacyESX
8404 Not documented
8405 Since
8407 4.0
8408 BlockdevCreateOptionsVmdk (Object)
8410 Driver specific image creation options for VMDK.
8411 Members
8413 file: BlockdevRef
8414 Where to store the new image file. This refers to the image
8415 file for monolithcSparse and streamOptimized format, or the de‐
8416 scriptor file for other formats.
8417 size: int
8419 Size of the virtual disk in bytes
8420 extents: array of BlockdevRef (optional)
8422 Where to store the data extents. Required for monolithcFlat,
8423 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
8424 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
8425 mats, the number of entries required is calculated as ex‐
8426 tent_number = virtual_size / 2GB. Providing more extents than
8427 will be used is an error.
8428 subformat: BlockdevVmdkSubformat (optional)
8430 The subformat of the VMDK image. Default: "monolithicSparse".
8431 backing-file: string (optional)
8433 The path of backing file. Default: no backing file is used.
8434 adapter-type: BlockdevVmdkAdapterType (optional)
8436 The adapter type used to fill in the descriptor. Default: ide.
8437 hwversion: string (optional)
8439 Hardware version. The meaningful options are "4" or "6". De‐
8440 fault: "4".
8441 toolsversion: string (optional)
8443 VMware guest tools version. Default: "2147483647" (Since 6.2)
8444 zeroed-grain: boolean (optional)
8446 Whether to enable zeroed-grain feature for sparse subformats.
8447 Default: false.
8448 Since
8450 4.0
8451 BlockdevCreateOptionsSsh (Object)
8453 Driver specific image creation options for SSH.
8454 Members
8456 location: BlockdevOptionsSsh
8457 Where to store the new image file
8458 size: int
8460 Size of the virtual disk in bytes
8461 Since
8463 2.12
8464 BlockdevCreateOptionsVdi (Object)
8466 Driver specific image creation options for VDI.
8467 Members
8469 file: BlockdevRef
8470 Node to create the image format on
8471 size: int
8473 Size of the virtual disk in bytes
8474 preallocation: PreallocMode (optional)
8476 Preallocation mode for the new image (default: off; allowed val‐
8477 ues: off, metadata)
8478 Since
8480 2.12
8481 BlockdevVhdxSubformat (Enum)
8483 Values
8484 dynamic
8485 Growing image file
8486 fixed Preallocated fixed-size image file
8488 Since
8490 2.12
8491 BlockdevCreateOptionsVhdx (Object)
8493 Driver specific image creation options for vhdx.
8494 Members
8496 file: BlockdevRef
8497 Node to create the image format on
8498 size: int
8500 Size of the virtual disk in bytes
8501 log-size: int (optional)
8503 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
8504 block-size: int (optional)
8506 Block size in bytes, must be a multiple of 1 MB and not larger
8507 than 256 MB (default: automatically choose a block size depend‐
8508 ing on the image size)
8509 subformat: BlockdevVhdxSubformat (optional)
8511 vhdx subformat (default: dynamic)
8512 block-state-zero: boolean (optional)
8514 Force use of payload blocks of type 'ZERO'. Non-standard, but
8515 default. Do not set to 'off' when using 'qemu-img convert' with
8516 subformat=dynamic.
8517 Since
8519 2.12
8520 BlockdevVpcSubformat (Enum)
8522 Values
8523 dynamic
8524 Growing image file
8525 fixed Preallocated fixed-size image file
8527 Since
8529 2.12
8530 BlockdevCreateOptionsVpc (Object)
8532 Driver specific image creation options for vpc (VHD).
8533 Members
8535 file: BlockdevRef
8536 Node to create the image format on
8537 size: int
8539 Size of the virtual disk in bytes
8540 subformat: BlockdevVpcSubformat (optional)
8542 vhdx subformat (default: dynamic)
8543 force-size: boolean (optional)
8545 Force use of the exact byte size instead of rounding to the next
8546 size that can be represented in CHS geometry (default: false)
8547 Since
8549 2.12
8550 BlockdevCreateOptions (Object)
8552 Options for creating an image format on a given node.
8553 Members
8555 driver: BlockdevDriver
8556 block driver to create the image format
8557 The members of BlockdevCreateOptionsFile when driver is "file"
8559 The members of BlockdevCreateOptionsGluster when driver is "gluster"
8561 The members of BlockdevCreateOptionsLUKS when driver is "luks"
8563 The members of BlockdevCreateOptionsNfs when driver is "nfs"
8565 The members of BlockdevCreateOptionsParallels when driver is "paral‐
8567 lels"
8568 The members of BlockdevCreateOptionsQcow when driver is "qcow"
8570 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
8572 The members of BlockdevCreateOptionsQed when driver is "qed"
8574 The members of BlockdevCreateOptionsRbd when driver is "rbd"
8576 The members of BlockdevCreateOptionsSsh when driver is "ssh"
8578 The members of BlockdevCreateOptionsVdi when driver is "vdi"
8580 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
8582 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
8584 The members of BlockdevCreateOptionsVpc when driver is "vpc"
8586 Since
8588 2.12
8589 blockdev-create (Command)
8591 Starts a job to create an image format on a given node. The job is au‐
8592 tomatically finalized, but a manual job-dismiss is required.
8593 Arguments
8595 job-id: string
8596 Identifier for the newly created job.
8597 options: BlockdevCreateOptions
8599 Options for the image creation.
8600 Since
8602 3.0
8603 BlockdevAmendOptionsLUKS (Object)
8605 Driver specific image amend options for LUKS.
8606 Members
8608 The members of QCryptoBlockAmendOptionsLUKS
8609 Since
8611 5.1
8612 BlockdevAmendOptionsQcow2 (Object)
8614 Driver specific image amend options for qcow2. For now, only encryption
8615 options can be amended
8616 Members
8618 encrypt: QCryptoBlockAmendOptions (optional)
8619 Encryption options to be amended
8620 Since
8622 5.1
8623 BlockdevAmendOptions (Object)
8625 Options for amending an image format
8626 Members
8628 driver: BlockdevDriver
8629 Block driver of the node to amend.
8630 The members of BlockdevAmendOptionsLUKS when driver is "luks"
8632 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
8634 Since
8636 5.1
8637 x-blockdev-amend (Command)
8639 Starts a job to amend format specific options of an existing open block
8640 device The job is automatically finalized, but a manual job-dismiss is
8641 required.
8642 Arguments
8644 job-id: string
8645 Identifier for the newly created job.
8646 node-name: string
8648 Name of the block node to work on
8649 options: BlockdevAmendOptions
8651 Options (driver specific)
8652 force: boolean (optional)
8654 Allow unsafe operations, format specific For luks that allows
8655 erase of the last active keyslot (permanent loss of data), and
8656 replacement of an active keyslot (possible loss of data if IO
8657 error happens)
8658 Features
8660 unstable
8661 This command is experimental.
8662 Since
8664 5.1
8665 BlockErrorAction (Enum)
8667 An enumeration of action that has been taken when a DISK I/O occurs
8668 Values
8670 ignore error has been ignored
8671 report error has been reported to the device
8673 stop error caused VM to be stopped
8675 Since
8677 2.1
8678 BLOCK_IMAGE_CORRUPTED (Event)
8680 Emitted when a disk image is being marked corrupt. The image can be
8681 identified by its device or node name. The 'device' field is always
8682 present for compatibility reasons, but it can be empty ("") if the im‐
8683 age does not have a device name associated.
8684 Arguments
8686 device: string
8687 device name. This is always present for compatibility reasons,
8688 but it can be empty ("") if the image does not have a device
8689 name associated.
8690 node-name: string (optional)
8692 node name (Since: 2.4)
8693 msg: string
8695 informative message for human consumption, such as the kind of
8696 corruption being detected. It should not be parsed by machine
8697 as it is not guaranteed to be stable
8698 offset: int (optional)
8700 if the corruption resulted from an image access, this is the
8701 host's access offset into the image
8702 size: int (optional)
8704 if the corruption resulted from an image access, this is the ac‐
8705 cess size
8706 fatal: boolean
8708 if set, the image is marked corrupt and therefore unusable after
8709 this event and must be repaired (Since 2.2; before, every
8710 BLOCK_IMAGE_CORRUPTED event was fatal)
8711 Note
8713 If action is "stop", a STOP event will eventually follow the
8714 BLOCK_IO_ERROR event.
8715 Example
8717 <- { "event": "BLOCK_IMAGE_CORRUPTED",
8718 "data": { "device": "", "node-name": "drive", "fatal": false,
8719 "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
8720 "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }
8721 Since
8723 1.7
8724 BLOCK_IO_ERROR (Event)
8726 Emitted when a disk I/O error occurs
8727 Arguments
8729 device: string
8730 device name. This is always present for compatibility reasons,
8731 but it can be empty ("") if the image does not have a device
8732 name associated.
8733 node-name: string (optional)
8735 node name. Note that errors may be reported for the root node
8736 that is directly attached to a guest device rather than for the
8737 node where the error occurred. The node name is not present if
8738 the drive is empty. (Since: 2.8)
8739 operation: IoOperationType
8741 I/O operation
8742 action: BlockErrorAction
8744 action that has been taken
8745 nospace: boolean (optional)
8747 true if I/O error was caused due to a no-space condition. This
8748 key is only present if query-block's io-status is present,
8749 please see query-block documentation for more information
8750 (since: 2.2)
8751 reason: string
8753 human readable string describing the error cause. (This field
8754 is a debugging aid for humans, it should not be parsed by appli‐
8755 cations) (since: 2.2)
8756 Note
8758 If action is "stop", a STOP event will eventually follow the
8759 BLOCK_IO_ERROR event
8760 Since
8762 0.13
8763 Example
8765 <- { "event": "BLOCK_IO_ERROR",
8766 "data": { "device": "ide0-hd1",
8767 "node-name": "#block212",
8768 "operation": "write",
8769 "action": "stop",
8770 "reason": "No space left on device" },
8771 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8772 BLOCK_JOB_COMPLETED (Event)
8774 Emitted when a block job has completed
8775 Arguments
8777 type: JobType
8778 job type
8779 device: string
8781 The job identifier. Originally the device name but other values
8782 are allowed since QEMU 2.7
8783 len: int
8785 maximum progress value
8786 offset: int
8788 current progress value. On success this is equal to len. On
8789 failure this is less than len
8790 speed: int
8792 rate limit, bytes per second
8793 error: string (optional)
8795 error message. Only present on failure. This field contains a
8796 human-readable error message. There are no semantics other than
8797 that streaming has failed and clients should not try to inter‐
8798 pret the error string
8799 Since
8801 1.1
8802 Example
8804 <- { "event": "BLOCK_JOB_COMPLETED",
8805 "data": { "type": "stream", "device": "virtio-disk0",
8806 "len": 10737418240, "offset": 10737418240,
8807 "speed": 0 },
8808 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
8809 BLOCK_JOB_CANCELLED (Event)
8811 Emitted when a block job has been cancelled
8812 Arguments
8814 type: JobType
8815 job type
8816 device: string
8818 The job identifier. Originally the device name but other values
8819 are allowed since QEMU 2.7
8820 len: int
8822 maximum progress value
8823 offset: int
8825 current progress value. On success this is equal to len. On
8826 failure this is less than len
8827 speed: int
8829 rate limit, bytes per second
8830 Since
8832 1.1
8833 Example
8835 <- { "event": "BLOCK_JOB_CANCELLED",
8836 "data": { "type": "stream", "device": "virtio-disk0",
8837 "len": 10737418240, "offset": 134217728,
8838 "speed": 0 },
8839 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
8840 BLOCK_JOB_ERROR (Event)
8842 Emitted when a block job encounters an error
8843 Arguments
8845 device: string
8846 The job identifier. Originally the device name but other values
8847 are allowed since QEMU 2.7
8848 operation: IoOperationType
8850 I/O operation
8851 action: BlockErrorAction
8853 action that has been taken
8854 Since
8856 1.3
8857 Example
8859 <- { "event": "BLOCK_JOB_ERROR",
8860 "data": { "device": "ide0-hd1",
8861 "operation": "write",
8862 "action": "stop" },
8863 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8864 BLOCK_JOB_READY (Event)
8866 Emitted when a block job is ready to complete
8867 Arguments
8869 type: JobType
8870 job type
8871 device: string
8873 The job identifier. Originally the device name but other values
8874 are allowed since QEMU 2.7
8875 len: int
8877 maximum progress value
8878 offset: int
8880 current progress value. On success this is equal to len. On
8881 failure this is less than len
8882 speed: int
8884 rate limit, bytes per second
8885 Note
8887 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
8888 event
8889 Since
8891 1.3
8892 Example
8894 <- { "event": "BLOCK_JOB_READY",
8895 "data": { "device": "drive0", "type": "mirror", "speed": 0,
8896 "len": 2097152, "offset": 2097152 },
8897 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8898 BLOCK_JOB_PENDING (Event)
8900 Emitted when a block job is awaiting explicit authorization to finalize
8901 graph changes via block-job-finalize. If this job is part of a trans‐
8902 action, it will not emit this event until the transaction has converged
8903 first.
8904 Arguments
8906 type: JobType
8907 job type
8908 id: string
8910 The job identifier.
8911 Since
8913 2.12
8914 Example
8916 <- { "event": "BLOCK_JOB_PENDING",
8917 "data": { "type": "mirror", "id": "backup_1" },
8918 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8919 PreallocMode (Enum)
8921 Preallocation mode of QEMU image file
8922 Values
8924 off no preallocation
8925 metadata
8927 preallocate only for metadata
8928 falloc like full preallocation but allocate disk space by posix_fallo‐
8930 cate() rather than writing data.
8931 full preallocate all data by writing it to the device to ensure disk
8933 space is really available. This data may or may not be zero,
8934 depending on the image format and storage. full preallocation
8935 also sets up metadata correctly.
8936 Since
8938 2.2
8939 BLOCK_WRITE_THRESHOLD (Event)
8941 Emitted when writes on block device reaches or exceeds the configured
8942 write threshold. For thin-provisioned devices, this means the device
8943 should be extended to avoid pausing for disk exhaustion. The event is
8944 one shot. Once triggered, it needs to be re-registered with another
8945 block-set-write-threshold command.
8946 Arguments
8948 node-name: string
8949 graph node name on which the threshold was exceeded.
8950 amount-exceeded: int
8952 amount of data which exceeded the threshold, in bytes.
8953 write-threshold: int
8955 last configured threshold, in bytes.
8956 Since
8958 2.3
8959 block-set-write-threshold (Command)
8961 Change the write threshold for a block drive. An event will be deliv‐
8962 ered if a write to this block drive crosses the configured threshold.
8963 The threshold is an offset, thus must be non-negative. Default is no
8964 write threshold. Setting the threshold to zero disables it.
8965 This is useful to transparently resize thin-provisioned drives without
8967 the guest OS noticing.
8968 Arguments
8970 node-name: string
8971 graph node name on which the threshold must be set.
8972 write-threshold: int
8974 configured threshold for the block device, bytes. Use 0 to dis‐
8975 able the threshold.
8976 Since
8978 2.3
8979 Example
8981 -> { "execute": "block-set-write-threshold",
8982 "arguments": { "node-name": "mydev",
8983 "write-threshold": 17179869184 } }
8984 <- { "return": {} }
8985 x-blockdev-change (Command)
8987 Dynamically reconfigure the block driver state graph. It can be used
8988 to add, remove, insert or replace a graph node. Currently only the
8989 Quorum driver implements this feature to add or remove its child. This
8990 is useful to fix a broken quorum child.
8991 If node is specified, it will be inserted under parent. child may not
8993 be specified in this case. If both parent and child are specified but
8994 node is not, child will be detached from parent.
8995 Arguments
8997 parent: string
8998 the id or name of the parent node.
8999 child: string (optional)
9001 the name of a child under the given parent node.
9002 node: string (optional)
9004 the name of the node that will be added.
9005 Features
9007 unstable
9008 This command is experimental, and its API is not stable. It
9009 does not support all kinds of operations, all kinds of children,
9010 nor all block drivers.
9011 FIXME Removing children from a quorum node means introducing
9013 gaps in the child indices. This cannot be represented in the
9014 'children' list of BlockdevOptionsQuorum, as returned by
9015 .bdrv_refresh_filename().
9016 Warning: The data in a new quorum child MUST be consistent with
9018 that of the rest of the array.
9019 Since
9021 2.7
9022 Examples
9024 1. Add a new node to a quorum
9025 -> { "execute": "blockdev-add",
9027 "arguments": {
9028 "driver": "raw",
9029 "node-name": "new_node",
9030 "file": { "driver": "file",
9031 "filename": "test.raw" } } }
9032 <- { "return": {} }
9033 -> { "execute": "x-blockdev-change",
9034 "arguments": { "parent": "disk1",
9035 "node": "new_node" } }
9036 <- { "return": {} }
9037 2. Delete a quorum's node
9039 -> { "execute": "x-blockdev-change",
9041 "arguments": { "parent": "disk1",
9042 "child": "children.1" } }
9043 <- { "return": {} }
9044 x-blockdev-set-iothread (Command)
9046 Move node and its children into the iothread. If iothread is null then
9047 move node and its children into the main loop.
9048 The node must not be attached to a BlockBackend.
9050 Arguments
9052 node-name: string
9053 the name of the block driver node
9054 iothread: StrOrNull
9056 the name of the IOThread object or null for the main loop
9057 force: boolean (optional)
9059 true if the node and its children should be moved when a Block‐
9060 Backend is already attached
9061 Features
9063 unstable
9064 This command is experimental and intended for test cases that
9065 need control over IOThreads only.
9066 Since
9068 2.12
9069 Examples
9071 1. Move a node into an IOThread
9072 -> { "execute": "x-blockdev-set-iothread",
9074 "arguments": { "node-name": "disk1",
9075 "iothread": "iothread0" } }
9076 <- { "return": {} }
9077 2. Move a node into the main loop
9079 -> { "execute": "x-blockdev-set-iothread",
9081 "arguments": { "node-name": "disk1",
9082 "iothread": null } }
9083 <- { "return": {} }
9084 QuorumOpType (Enum)
9086 An enumeration of the quorum operation types
9087 Values
9089 read read operation
9090 write write operation
9092 flush flush operation
9094 Since
9096 2.6
9097 QUORUM_FAILURE (Event)
9099 Emitted by the Quorum block driver if it fails to establish a quorum
9100 Arguments
9102 reference: string
9103 device name if defined else node name
9104 sector-num: int
9106 number of the first sector of the failed read operation
9107 sectors-count: int
9109 failed read operation sector count
9110 Note
9112 This event is rate-limited.
9113 Since
9115 2.0
9116 Example
9118 <- { "event": "QUORUM_FAILURE",
9119 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
9120 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
9121 QUORUM_REPORT_BAD (Event)
9123 Emitted to report a corruption of a Quorum file
9124 Arguments
9126 type: QuorumOpType
9127 quorum operation type (Since 2.6)
9128 error: string (optional)
9130 error message. Only present on failure. This field contains a
9131 human-readable error message. There are no semantics other than
9132 that the block layer reported an error and clients should not
9133 try to interpret the error string.
9134 node-name: string
9136 the graph node name of the block driver state
9137 sector-num: int
9139 number of the first sector of the failed read operation
9140 sectors-count: int
9142 failed read operation sector count
9143 Note
9145 This event is rate-limited.
9146 Since
9148 2.0
9149 Examples
9151 1. Read operation
9152 <- { "event": "QUORUM_REPORT_BAD",
9154 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
9155 "type": "read" },
9156 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
9157 2. Flush operation
9159 <- { "event": "QUORUM_REPORT_BAD",
9161 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
9162 "type": "flush", "error": "Broken pipe" },
9163 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
9164 BlockdevSnapshotInternal (Object)
9166 Members
9167 device: string
9168 the device name or node-name of a root node to generate the
9169 snapshot from
9170 name: string
9172 the name of the internal snapshot to be created
9173 Notes
9175 In transaction, if name is empty, or any snapshot matching name exists,
9176 the operation will fail. Only some image formats support it, for exam‐
9177 ple, qcow2, and rbd.
9178 Since
9180 1.7
9181 blockdev-snapshot-internal-sync (Command)
9183 Synchronously take an internal snapshot of a block device, when the
9184 format of the image used supports it. If the name is an empty string,
9185 or a snapshot with name already exists, the operation will fail.
9186 For the arguments, see the documentation of BlockdevSnapshotInternal.
9188 Returns
9190 • nothing on success
9191 • If device is not a valid block device, GenericError
9193 • If any snapshot matching name exists, or name is empty, GenericError
9195 • If the format of the image used does not support it, GenericError
9197 Since
9199 1.7
9200 Example
9202 -> { "execute": "blockdev-snapshot-internal-sync",
9203 "arguments": { "device": "ide-hd0",
9204 "name": "snapshot0" }
9205 }
9206 <- { "return": {} }
9207 blockdev-snapshot-delete-internal-sync (Command)
9209 Synchronously delete an internal snapshot of a block device, when the
9210 format of the image used support it. The snapshot is identified by
9211 name or id or both. One of the name or id is required. Return Snap‐
9212 shotInfo for the successfully deleted snapshot.
9213 Arguments
9215 device: string
9216 the device name or node-name of a root node to delete the snap‐
9217 shot from
9218 id: string (optional)
9220 optional the snapshot's ID to be deleted
9221 name: string (optional)
9223 optional the snapshot's name to be deleted
9224 Returns
9226 • SnapshotInfo on success
9227 • If device is not a valid block device, GenericError
9229 • If snapshot not found, GenericError
9231 • If the format of the image used does not support it, GenericError
9233 • If id and name are both not specified, GenericError
9235 Since
9237 1.7
9238 Example
9240 -> { "execute": "blockdev-snapshot-delete-internal-sync",
9241 "arguments": { "device": "ide-hd0",
9242 "name": "snapshot0" }
9243 }
9244 <- { "return": {
9245 "id": "1",
9246 "name": "snapshot0",
9247 "vm-state-size": 0,
9248 "date-sec": 1000012,
9249 "date-nsec": 10,
9250 "vm-clock-sec": 100,
9251 "vm-clock-nsec": 20,
9252 "icount": 220414
9253 }
9254 }
9255 DummyBlockCoreForceArrays (Object)
9257 Not used by QMP; hack to let us use BlockGraphInfoList internally
9258 Members
9260 unused-block-graph-info: array of BlockGraphInfo
9261 Not documented
9262 Since
9264 8.0
9265 Additional block stuff (VM related)
9267 BiosAtaTranslation (Enum)
9268 Policy that BIOS should use to interpret cylinder/head/sector ad‐
9269 dresses. Note that Bochs BIOS and SeaBIOS will not actually translate
9270 logical CHS to physical; instead, they will use logical block address‐
9271 ing.
9272 Values
9274 auto If cylinder/heads/sizes are passed, choose between none and LBA
9275 depending on the size of the disk. If they are not passed,
9276 choose none if QEMU can guess that the disk had 16 or fewer
9277 heads, large if QEMU can guess that the disk had 131072 or fewer
9278 tracks across all heads (i.e. cylinders*heads<131072), otherwise
9279 LBA.
9280 none The physical disk geometry is equal to the logical geometry.
9282 lba Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
9284 heads (if fewer than 255 are enough to cover the whole disk with
9285 1024 cylinders/head). The number of cylinders/head is then com‐
9286 puted based on the number of sectors and heads.
9287 large The number of cylinders per head is scaled down to 1024 by cor‐
9289 respondingly scaling up the number of heads.
9290 rechs Same as large, but first convert a 16-head geometry to 15-head,
9292 by proportionally scaling up the number of cylinders/head.
9293 Since
9295 2.0
9296 FloppyDriveType (Enum)
9298 Type of Floppy drive to be emulated by the Floppy Disk Controller.
9299 Values
9301 144 1.44MB 3.5" drive
9302 288 2.88MB 3.5" drive
9304 120 1.2MB 5.25" drive
9306 none No drive connected
9308 auto Automatically determined by inserted media at boot
9310 Since
9312 2.6
9313 PRManagerInfo (Object)
9315 Information about a persistent reservation manager
9316 Members
9318 id: string
9319 the identifier of the persistent reservation manager
9320 connected: boolean
9322 true if the persistent reservation manager is connected to the
9323 underlying storage or helper
9324 Since
9326 3.0
9327 query-pr-managers (Command)
9329 Returns a list of information about each persistent reservation man‐
9330 ager.
9331 Returns
9333 a list of PRManagerInfo for each persistent reservation manager
9334 Since
9336 3.0
9337 eject (Command)
9339 Ejects the medium from a removable drive.
9340 Arguments
9342 device: string (optional)
9343 Block device name
9344 id: string (optional)
9346 The name or QOM path of the guest device (since: 2.8)
9347 force: boolean (optional)
9349 If true, eject regardless of whether the drive is locked. If
9350 not specified, the default value is false.
9351 Features
9353 deprecated
9354 Member device is deprecated. Use id instead.
9355 Returns
9357 • Nothing on success
9358 • If device is not a valid block device, DeviceNotFound
9360 Notes
9362 Ejecting a device with no media results in success
9363 Since
9365 0.14
9366 Example
9368 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
9369 <- { "return": {} }
9370 blockdev-open-tray (Command)
9372 Opens a block device's tray. If there is a block driver state tree in‐
9373 serted as a medium, it will become inaccessible to the guest (but it
9374 will remain associated to the block device, so closing the tray will
9375 make it accessible again).
9376 If the tray was already open before, this will be a no-op.
9378 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
9380 cases in which no such event will be generated, these include:
9381 • if the guest has locked the tray, force is false and the guest does
9383 not respond to the eject request
9384 • if the BlockBackend denoted by device does not have a guest device
9386 attached to it
9387 • if the guest device does not have an actual tray
9389 Arguments
9391 device: string (optional)
9392 Block device name
9393 id: string (optional)
9395 The name or QOM path of the guest device (since: 2.8)
9396 force: boolean (optional)
9398 if false (the default), an eject request will be sent to the
9399 guest if it has locked the tray (and the tray will not be opened
9400 immediately); if true, the tray will be opened regardless of
9401 whether it is locked
9402 Features
9404 deprecated
9405 Member device is deprecated. Use id instead.
9406 Since
9408 2.5
9409 Example
9411 -> { "execute": "blockdev-open-tray",
9412 "arguments": { "id": "ide0-1-0" } }
9413 <- { "timestamp": { "seconds": 1418751016,
9415 "microseconds": 716996 },
9416 "event": "DEVICE_TRAY_MOVED",
9417 "data": { "device": "ide1-cd0",
9418 "id": "ide0-1-0",
9419 "tray-open": true } }
9420 <- { "return": {} }
9422 blockdev-close-tray (Command)
9424 Closes a block device's tray. If there is a block driver state tree
9425 associated with the block device (which is currently ejected), that
9426 tree will be loaded as the medium.
9427 If the tray was already closed before, this will be a no-op.
9429 Arguments
9431 device: string (optional)
9432 Block device name
9433 id: string (optional)
9435 The name or QOM path of the guest device (since: 2.8)
9436 Features
9438 deprecated
9439 Member device is deprecated. Use id instead.
9440 Since
9442 2.5
9443 Example
9445 -> { "execute": "blockdev-close-tray",
9446 "arguments": { "id": "ide0-1-0" } }
9447 <- { "timestamp": { "seconds": 1418751345,
9449 "microseconds": 272147 },
9450 "event": "DEVICE_TRAY_MOVED",
9451 "data": { "device": "ide1-cd0",
9452 "id": "ide0-1-0",
9453 "tray-open": false } }
9454 <- { "return": {} }
9456 blockdev-remove-medium (Command)
9458 Removes a medium (a block driver state tree) from a block device. That
9459 block device's tray must currently be open (unless there is no attached
9460 guest device).
9461 If the tray is open and there is no medium inserted, this will be a
9463 no-op.
9464 Arguments
9466 id: string
9467 The name or QOM path of the guest device
9468 Since
9470 2.12
9471 Example
9473 -> { "execute": "blockdev-remove-medium",
9474 "arguments": { "id": "ide0-1-0" } }
9475 <- { "error": { "class": "GenericError",
9477 "desc": "Tray of device 'ide0-1-0' is not open" } }
9478 -> { "execute": "blockdev-open-tray",
9480 "arguments": { "id": "ide0-1-0" } }
9481 <- { "timestamp": { "seconds": 1418751627,
9483 "microseconds": 549958 },
9484 "event": "DEVICE_TRAY_MOVED",
9485 "data": { "device": "ide1-cd0",
9486 "id": "ide0-1-0",
9487 "tray-open": true } }
9488 <- { "return": {} }
9490 -> { "execute": "blockdev-remove-medium",
9492 "arguments": { "id": "ide0-1-0" } }
9493 <- { "return": {} }
9495 blockdev-insert-medium (Command)
9497 Inserts a medium (a block driver state tree) into a block device. That
9498 block device's tray must currently be open (unless there is no attached
9499 guest device) and there must be no medium inserted already.
9500 Arguments
9502 id: string
9503 The name or QOM path of the guest device
9504 node-name: string
9506 name of a node in the block driver state graph
9507 Since
9509 2.12
9510 Example
9512 -> { "execute": "blockdev-add",
9513 "arguments": {
9514 "node-name": "node0",
9515 "driver": "raw",
9516 "file": { "driver": "file",
9517 "filename": "fedora.iso" } } }
9518 <- { "return": {} }
9519 -> { "execute": "blockdev-insert-medium",
9521 "arguments": { "id": "ide0-1-0",
9522 "node-name": "node0" } }
9523 <- { "return": {} }
9525 BlockdevChangeReadOnlyMode (Enum)
9527 Specifies the new read-only mode of a block device subject to the
9528 blockdev-change-medium command.
9529 Values
9531 retain Retains the current read-only mode
9532 read-only
9534 Makes the device read-only
9535 read-write
9537 Makes the device writable
9538 Since
9540 2.3
9541 blockdev-change-medium (Command)
9543 Changes the medium inserted into a block device by ejecting the current
9544 medium and loading a new image file which is inserted as the new medium
9545 (this command combines blockdev-open-tray, blockdev-remove-medium,
9546 blockdev-insert-medium and blockdev-close-tray).
9547 Arguments
9549 device: string (optional)
9550 Block device name
9551 id: string (optional)
9553 The name or QOM path of the guest device (since: 2.8)
9554 filename: string
9556 filename of the new image to be loaded
9557 format: string (optional)
9559 format to open the new image with (defaults to the probed for‐
9560 mat)
9561 read-only-mode: BlockdevChangeReadOnlyMode (optional)
9563 change the read-only mode of the device; defaults to 'retain'
9564 force: boolean (optional)
9566 if false (the default), an eject request through block‐
9567 dev-open-tray will be sent to the guest if it has locked the
9568 tray (and the tray will not be opened immediately); if true, the
9569 tray will be opened regardless of whether it is locked. (since
9570 7.1)
9571 Features
9573 deprecated
9574 Member device is deprecated. Use id instead.
9575 Since
9577 2.5
9578 Examples
9580 1. Change a removable medium
9581 -> { "execute": "blockdev-change-medium",
9583 "arguments": { "id": "ide0-1-0",
9584 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
9585 "format": "raw" } }
9586 <- { "return": {} }
9587 2. Load a read-only medium into a writable drive
9589 -> { "execute": "blockdev-change-medium",
9591 "arguments": { "id": "floppyA",
9592 "filename": "/srv/images/ro.img",
9593 "format": "raw",
9594 "read-only-mode": "retain" } }
9595 <- { "error":
9597 { "class": "GenericError",
9598 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
9599 -> { "execute": "blockdev-change-medium",
9601 "arguments": { "id": "floppyA",
9602 "filename": "/srv/images/ro.img",
9603 "format": "raw",
9604 "read-only-mode": "read-only" } }
9605 <- { "return": {} }
9607 DEVICE_TRAY_MOVED (Event)
9609 Emitted whenever the tray of a removable device is moved by the guest
9610 or by HMP/QMP commands
9611 Arguments
9613 device: string
9614 Block device name. This is always present for compatibility
9615 reasons, but it can be empty ("") if the image does not have a
9616 device name associated.
9617 id: string
9619 The name or QOM path of the guest device (since 2.8)
9620 tray-open: boolean
9622 true if the tray has been opened or false if it has been closed
9623 Since
9625 1.1
9626 Example
9628 <- { "event": "DEVICE_TRAY_MOVED",
9629 "data": { "device": "ide1-cd0",
9630 "id": "/machine/unattached/device[22]",
9631 "tray-open": true
9632 },
9633 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
9634 PR_MANAGER_STATUS_CHANGED (Event)
9636 Emitted whenever the connected status of a persistent reservation man‐
9637 ager changes.
9638 Arguments
9640 id: string
9641 The id of the PR manager object
9642 connected: boolean
9644 true if the PR manager is connected to a backend
9645 Since
9647 3.0
9648 Example
9650 <- { "event": "PR_MANAGER_STATUS_CHANGED",
9651 "data": { "id": "pr-helper0",
9652 "connected": true
9653 },
9654 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
9655 block_set_io_throttle (Command)
9657 Change I/O throttle limits for a block drive.
9658 Since QEMU 2.4, each device with I/O limits is member of a throttle
9660 group.
9661 If two or more devices are members of the same group, the limits will
9663 apply to the combined I/O of the whole group in a round-robin fashion.
9664 Therefore, setting new I/O limits to a device will affect the whole
9665 group.
9666 The name of the group can be specified using the 'group' parameter. If
9668 the parameter is unset, it is assumed to be the current group of that
9669 device. If it's not in any group yet, the name of the device will be
9670 used as the name for its group.
9671 The 'group' parameter can also be used to move a device to a different
9673 group. In this case the limits specified in the parameters will be ap‐
9674 plied to the new group only.
9675 I/O limits can be disabled by setting all of them to 0. In this case
9677 the device will be removed from its group and the rest of its members
9678 will not be affected. The 'group' parameter is ignored.
9679 Arguments
9681 The members of BlockIOThrottle
9682 Returns
9684 • Nothing on success
9685 • If device is not a valid block device, DeviceNotFound
9687 Since
9689 1.1
9690 Examples
9692 -> { "execute": "block_set_io_throttle",
9693 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
9694 "bps": 0,
9695 "bps_rd": 0,
9696 "bps_wr": 0,
9697 "iops": 512,
9698 "iops_rd": 0,
9699 "iops_wr": 0,
9700 "bps_max": 0,
9701 "bps_rd_max": 0,
9702 "bps_wr_max": 0,
9703 "iops_max": 0,
9704 "iops_rd_max": 0,
9705 "iops_wr_max": 0,
9706 "bps_max_length": 0,
9707 "iops_size": 0 } }
9708 <- { "return": {} }
9709 -> { "execute": "block_set_io_throttle",
9711 "arguments": { "id": "ide0-1-0",
9712 "bps": 1000000,
9713 "bps_rd": 0,
9714 "bps_wr": 0,
9715 "iops": 0,
9716 "iops_rd": 0,
9717 "iops_wr": 0,
9718 "bps_max": 8000000,
9719 "bps_rd_max": 0,
9720 "bps_wr_max": 0,
9721 "iops_max": 0,
9722 "iops_rd_max": 0,
9723 "iops_wr_max": 0,
9724 "bps_max_length": 60,
9725 "iops_size": 0 } }
9726 <- { "return": {} }
9727 block-latency-histogram-set (Command)
9729 Manage read, write and flush latency histograms for the device.
9730 If only id parameter is specified, remove all present latency his‐
9732 tograms for the device. Otherwise, add/reset some of (or all) latency
9733 histograms.
9734 Arguments
9736 id: string
9737 The name or QOM path of the guest device.
9738 boundaries: array of int (optional)
9740 list of interval boundary values (see description in BlockLaten‐
9741 cyHistogramInfo definition). If specified, all latency his‐
9742 tograms are removed, and empty ones created for all io types
9743 with intervals corresponding to boundaries (except for io types,
9744 for which specific boundaries are set through the following pa‐
9745 rameters).
9746 boundaries-read: array of int (optional)
9748 list of interval boundary values for read latency histogram. If
9749 specified, old read latency histogram is removed, and empty one
9750 created with intervals corresponding to boundaries-read. The
9751 parameter has higher priority then boundaries.
9752 boundaries-write: array of int (optional)
9754 list of interval boundary values for write latency histogram.
9755 boundaries-zap: array of int (optional)
9757 list of interval boundary values for zone append write latency
9758 histogram.
9759 boundaries-flush: array of int (optional)
9761 list of interval boundary values for flush latency histogram.
9762 Returns
9764 error if device is not found or any boundary arrays are invalid.
9765 Since
9767 4.0
9768 Example
9770 Set new histograms for all io types with intervals [0, 10), [10,
9771 50), [50, 100), [100, +inf):
9772 -> { "execute": "block-latency-histogram-set",
9774 "arguments": { "id": "drive0",
9775 "boundaries": [10, 50, 100] } }
9776 <- { "return": {} }
9777 Example
9779 Set new histogram only for write, other histograms will remain not
9780 changed (or not created):
9781 -> { "execute": "block-latency-histogram-set",
9783 "arguments": { "id": "drive0",
9784 "boundaries-write": [10, 50, 100] } }
9785 <- { "return": {} }
9786 Example
9788 Set new histograms with the following intervals: read, flush: [0,
9789 10), [10, 50), [50, 100), [100, +inf) write: [0, 1000), [1000,
9790 5000), [5000, +inf)
9791 -> { "execute": "block-latency-histogram-set",
9793 "arguments": { "id": "drive0",
9794 "boundaries": [10, 50, 100],
9795 "boundaries-write": [1000, 5000] } }
9796 <- { "return": {} }
9797 Example
9799 Remove all latency histograms:
9800 -> { "execute": "block-latency-histogram-set",
9802 "arguments": { "id": "drive0" } }
9803 <- { "return": {} }
9804 Block device exports
9806 NbdServerOptions (Object)
9807 Keep this type consistent with the nbd-server-start arguments. The
9808 only intended difference is using SocketAddress instead of SocketAd‐
9809 dressLegacy.
9810 Members
9812 addr: SocketAddress
9813 Address on which to listen.
9814 tls-creds: string (optional)
9816 ID of the TLS credentials object (since 2.6).
9817 tls-authz: string (optional)
9819 ID of the QAuthZ authorization object used to validate the
9820 client's x509 distinguished name. This object is is only re‐
9821 solved at time of use, so can be deleted and recreated on the
9822 fly while the NBD server is active. If missing, it will default
9823 to denying access (since 4.0).
9824 max-connections: int (optional)
9826 The maximum number of connections to allow at the same time, 0
9827 for unlimited. Setting this to 1 also stops the server from ad‐
9828 vertising multiple client support (since 5.2; default: 0)
9829 Since
9831 4.2
9832 nbd-server-start (Command)
9834 Start an NBD server listening on the given host and port. Block de‐
9835 vices can then be exported using nbd-server-add. The NBD server will
9836 present them as named exports; for example, another QEMU instance could
9837 refer to them as "nbd:HOST:PORT:exportname=NAME".
9838 Keep this type consistent with the NbdServerOptions type. The only in‐
9840 tended difference is using SocketAddressLegacy instead of SocketAd‐
9841 dress.
9842 Arguments
9844 addr: SocketAddressLegacy
9845 Address on which to listen.
9846 tls-creds: string (optional)
9848 ID of the TLS credentials object (since 2.6).
9849 tls-authz: string (optional)
9851 ID of the QAuthZ authorization object used to validate the
9852 client's x509 distinguished name. This object is is only re‐
9853 solved at time of use, so can be deleted and recreated on the
9854 fly while the NBD server is active. If missing, it will default
9855 to denying access (since 4.0).
9856 max-connections: int (optional)
9858 The maximum number of connections to allow at the same time, 0
9859 for unlimited. Setting this to 1 also stops the server from ad‐
9860 vertising multiple client support (since 5.2; default: 0).
9861 Returns
9863 error if the server is already running.
9864 Since
9866 1.3
9867 BlockExportOptionsNbdBase (Object)
9869 An NBD block export (common options shared between nbd-server-add and
9870 the NBD branch of block-export-add).
9871 Members
9873 name: string (optional)
9874 Export name. If unspecified, the device parameter is used as
9875 the export name. (Since 2.12)
9876 description: string (optional)
9878 Free-form description of the export, up to 4096 bytes. (Since
9879 5.0)
9880 Since
9882 5.0
9883 BlockExportOptionsNbd (Object)
9885 An NBD block export (distinct options used in the NBD branch of
9886 block-export-add).
9887 Members
9889 bitmaps: array of BlockDirtyBitmapOrStr (optional)
9890 Also export each of the named dirty bitmaps reachable from de‐
9891 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
9892 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
9893 each bitmap. Since 7.1 bitmap may be specified by node/name
9894 pair.
9895 allocation-depth: boolean (optional)
9897 Also export the allocation depth map for device, so the NBD
9898 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
9899 text name "qemu:allocation-depth" to inspect allocation details.
9900 (since 5.2)
9901 The members of BlockExportOptionsNbdBase
9903 Since
9905 5.2
9906 BlockExportOptionsVhostUserBlk (Object)
9908 A vhost-user-blk block export.
9909 Members
9911 addr: SocketAddress
9912 The vhost-user socket on which to listen. Both 'unix' and 'fd'
9913 SocketAddress types are supported. Passed fds must be UNIX do‐
9914 main sockets.
9915 logical-block-size: int (optional)
9917 Logical block size in bytes. Defaults to 512 bytes.
9918 num-queues: int (optional)
9920 Number of request virtqueues. Must be greater than 0. Defaults
9921 to 1.
9922 Since
9924 5.2
9925 FuseExportAllowOther (Enum)
9927 Possible allow_other modes for FUSE exports.
9928 Values
9930 off Do not pass allow_other as a mount option.
9931 on Pass allow_other as a mount option.
9933 auto Try mounting with allow_other first, and if that fails, retry
9935 without allow_other.
9936 Since
9938 6.1
9939 BlockExportOptionsFuse (Object)
9941 Options for exporting a block graph node on some (file) mountpoint as a
9942 raw image.
9943 Members
9945 mountpoint: string
9946 Path on which to export the block device via FUSE. This must
9947 point to an existing regular file.
9948 growable: boolean (optional)
9950 Whether writes beyond the EOF should grow the block node accord‐
9951 ingly. (default: false)
9952 allow-other: FuseExportAllowOther (optional)
9954 If this is off, only qemu's user is allowed access to this ex‐
9955 port. That cannot be changed even with chmod or chown. En‐
9956 abling this option will allow other users access to the export
9957 with the FUSE mount option "allow_other". Note that using al‐
9958 low_other as a non-root user requires user_allow_other to be en‐
9959 abled in the global fuse.conf configuration file. In auto mode
9960 (the default), the FUSE export driver will first attempt to
9961 mount the export with allow_other, and if that fails, try again
9962 without. (since 6.1; default: auto)
9963 Since
9965 6.0
9966 If
9968 CONFIG_FUSE
9969 BlockExportOptionsVduseBlk (Object)
9971 A vduse-blk block export.
9972 Members
9974 name: string
9975 the name of VDUSE device (must be unique across the host).
9976 num-queues: int (optional)
9978 the number of virtqueues. Defaults to 1.
9979 queue-size: int (optional)
9981 the size of virtqueue. Defaults to 256.
9982 logical-block-size: int (optional)
9984 Logical block size in bytes. Range [512, PAGE_SIZE] and must be
9985 power of 2. Defaults to 512 bytes.
9986 serial: string (optional)
9988 the serial number of virtio block device. Defaults to empty
9989 string.
9990 Since
9992 7.1
9993 NbdServerAddOptions (Object)
9995 An NBD block export, per legacy nbd-server-add command.
9996 Members
9998 device: string
9999 The device name or node name of the node to be exported
10000 writable: boolean (optional)
10002 Whether clients should be able to write to the device via the
10003 NBD connection (default false).
10004 bitmap: string (optional)
10006 Also export a single dirty bitmap reachable from device, so the
10007 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
10008 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
10009 (since 4.0).
10010 The members of BlockExportOptionsNbdBase
10012 Since
10014 5.0
10015 nbd-server-add (Command)
10017 Export a block node to QEMU's embedded NBD server.
10018 The export name will be used as the id for the resulting block export.
10020 Arguments
10022 The members of NbdServerAddOptions
10023 Features
10025 deprecated
10026 This command is deprecated. Use block-export-add instead.
10027 Returns
10029 error if the server is not running, or export with the same name al‐
10030 ready exists.
10031 Since
10033 1.3
10034 BlockExportRemoveMode (Enum)
10036 Mode for removing a block export.
10037 Values
10039 safe Remove export if there are no existing connections, fail other‐
10040 wise.
10041 hard Drop all connections immediately and remove export.
10043 Potential additional modes to be added in the future:
10044 hide: Just hide export from new clients, leave existing connections as
10046 is. Remove export after all clients are disconnected.
10047 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
10049 ther requests from existing clients.
10050 Since
10052 2.12
10053 nbd-server-remove (Command)
10055 Remove NBD export by name.
10056 Arguments
10058 name: string
10059 Block export id.
10060 mode: BlockExportRemoveMode (optional)
10062 Mode of command operation. See BlockExportRemoveMode descrip‐
10063 tion. Default is 'safe'.
10064 Features
10066 deprecated
10067 This command is deprecated. Use block-export-del instead.
10068 Returns
10070 error if
10071 • the server is not running
10073 • export is not found
10075 • mode is 'safe' and there are existing connections
10077 Since
10079 2.12
10080 nbd-server-stop (Command)
10082 Stop QEMU's embedded NBD server, and unregister all devices previously
10083 added via nbd-server-add.
10084 Since
10086 1.3
10087 BlockExportType (Enum)
10089 An enumeration of block export types
10090 Values
10092 nbd NBD export
10093 vhost-user-blk (If: CONFIG_VHOST_USER_BLK_SERVER)
10095 vhost-user-blk export (since 5.2)
10096 fuse (If: CONFIG_FUSE)
10098 FUSE export (since: 6.0)
10099 vduse-blk (If: CONFIG_VDUSE_BLK_EXPORT)
10101 vduse-blk export (since 7.1)
10102 Since
10104 4.2
10105 BlockExportOptions (Object)
10107 Describes a block export, i.e. how single node should be exported on an
10108 external interface.
10109 Members
10111 id: string
10112 A unique identifier for the block export (across all export
10113 types)
10114 node-name: string
10116 The node name of the block node to be exported (since: 5.2)
10117 writable: boolean (optional)
10119 True if clients should be able to write to the export (default
10120 false)
10121 writethrough: boolean (optional)
10123 If true, caches are flushed after every write request to the ex‐
10124 port before completion is signalled. (since: 5.2; default:
10125 false)
10126 iothread: string (optional)
10128 The name of the iothread object where the export will run. The
10129 default is to use the thread currently associated with the block
10130 node. (since: 5.2)
10131 fixed-iothread: boolean (optional)
10133 True prevents the block node from being moved to another thread
10134 while the export is active. If true and iothread is given, ex‐
10135 port creation fails if the block node cannot be moved to the io‐
10136 thread. The default is false. (since: 5.2)
10137 type: BlockExportType
10139 Not documented
10140 The members of BlockExportOptionsNbd when type is "nbd"
10142 The members of BlockExportOptionsVhostUserBlk when type is
10144 "vhost-user-blk" (If: CONFIG_VHOST_USER_BLK_SERVER)
10145 The members of BlockExportOptionsFuse when type is "fuse" (If: CON‐
10147 FIG_FUSE)
10148 The members of BlockExportOptionsVduseBlk when type is "vduse-blk" (If:
10150 CONFIG_VDUSE_BLK_EXPORT)
10151 Since
10153 4.2
10154 block-export-add (Command)
10156 Creates a new block export.
10157 Arguments
10159 The members of BlockExportOptions
10160 Since
10162 5.2
10163 block-export-del (Command)
10165 Request to remove a block export. This drops the user's reference to
10166 the export, but the export may still stay around after this command re‐
10167 turns until the shutdown of the export has completed.
10168 Arguments
10170 id: string
10171 Block export id.
10172 mode: BlockExportRemoveMode (optional)
10174 Mode of command operation. See BlockExportRemoveMode descrip‐
10175 tion. Default is 'safe'.
10176 Returns
10178 Error if the export is not found or mode is 'safe' and the export is
10179 still in use (e.g. by existing client connections)
10180 Since
10182 5.2
10183 BLOCK_EXPORT_DELETED (Event)
10185 Emitted when a block export is removed and its id can be reused.
10186 Arguments
10188 id: string
10189 Block export id.
10190 Since
10192 5.2
10193 BlockExportInfo (Object)
10195 Information about a single block export.
10196 Members
10198 id: string
10199 The unique identifier for the block export
10200 type: BlockExportType
10202 The block export type
10203 node-name: string
10205 The node name of the block node that is exported
10206 shutting-down: boolean
10208 True if the export is shutting down (e.g. after a block-ex‐
10209 port-del command, but before the shutdown has completed)
10210 Since
10212 5.2
10213 query-block-exports (Command)
10215 Returns
10216 A list of BlockExportInfo describing all block exports
10217 Since
10219 5.2
10220
10222 ChardevInfo (Object)
10223 Information about a character device.
10224 Members
10226 label: string
10227 the label of the character device
10228 filename: string
10230 the filename of the character device
10231 frontend-open: boolean
10233 shows whether the frontend device attached to this backend (e.g.
10234 with the chardev=... option) is in open or closed state (since
10235 2.1)
10236 Notes
10238 filename is encoded using the QEMU command line character device encod‐
10239 ing. See the QEMU man page for details.
10240 Since
10242 0.14
10243 query-chardev (Command)
10245 Returns information about current character devices.
10246 Returns
10248 a list of ChardevInfo
10249 Since
10251 0.14
10252 Example
10254 -> { "execute": "query-chardev" }
10255 <- {
10256 "return": [
10257 {
10258 "label": "charchannel0",
10259 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
10260 "frontend-open": false
10261 },
10262 {
10263 "label": "charmonitor",
10264 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
10265 "frontend-open": true
10266 },
10267 {
10268 "label": "charserial0",
10269 "filename": "pty:/dev/pts/2",
10270 "frontend-open": true
10271 }
10272 ]
10273 }
10274 ChardevBackendInfo (Object)
10276 Information about a character device backend
10277 Members
10279 name: string
10280 The backend name
10281 Since
10283 2.0
10284 query-chardev-backends (Command)
10286 Returns information about character device backends.
10287 Returns
10289 a list of ChardevBackendInfo
10290 Since
10292 2.0
10293 Example
10295 -> { "execute": "query-chardev-backends" }
10296 <- {
10297 "return":[
10298 {
10299 "name":"udp"
10300 },
10301 {
10302 "name":"tcp"
10303 },
10304 {
10305 "name":"unix"
10306 },
10307 {
10308 "name":"spiceport"
10309 }
10310 ]
10311 }
10312 DataFormat (Enum)
10314 An enumeration of data format.
10315 Values
10317 utf8 Data is a UTF-8 string (RFC 3629)
10318 base64 Data is Base64 encoded binary (RFC 3548)
10320 Since
10322 1.4
10323 ringbuf-write (Command)
10325 Write to a ring buffer character device.
10326 Arguments
10328 device: string
10329 the ring buffer character device name
10330 data: string
10332 data to write
10333 format: DataFormat (optional)
10335 data encoding (default 'utf8').
10336 • base64: data must be base64 encoded text. Its binary decoding
10338 gets written.
10339 • utf8: data's UTF-8 encoding is written
10341 • data itself is always Unicode regardless of format, like any
10343 other string.
10344 Returns
10346 Nothing on success
10347 Since
10349 1.4
10350 Example
10352 -> { "execute": "ringbuf-write",
10353 "arguments": { "device": "foo",
10354 "data": "abcdefgh",
10355 "format": "utf8" } }
10356 <- { "return": {} }
10357 ringbuf-read (Command)
10359 Read from a ring buffer character device.
10360 Arguments
10362 device: string
10363 the ring buffer character device name
10364 size: int
10366 how many bytes to read at most
10367 format: DataFormat (optional)
10369 data encoding (default 'utf8').
10370 • base64: the data read is returned in base64 encoding.
10372 • utf8: the data read is interpreted as UTF-8. Bug: can screw
10374 up when the buffer contains invalid UTF-8 sequences, NUL char‐
10375 acters, after the ring buffer lost data, and when reading
10376 stops because the size limit is reached.
10377 • The return value is always Unicode regardless of format, like
10379 any other string.
10380 Returns
10382 data read from the device
10383 Since
10385 1.4
10386 Example
10388 -> { "execute": "ringbuf-read",
10389 "arguments": { "device": "foo",
10390 "size": 1000,
10391 "format": "utf8" } }
10392 <- { "return": "abcdefgh" }
10393 ChardevCommon (Object)
10395 Configuration shared across all chardev backends
10396 Members
10398 logfile: string (optional)
10399 The name of a logfile to save output
10400 logappend: boolean (optional)
10402 true to append instead of truncate (default to false to trun‐
10403 cate)
10404 Since
10406 2.6
10407 ChardevFile (Object)
10409 Configuration info for file chardevs.
10410 Members
10412 in: string (optional)
10413 The name of the input file
10414 out: string
10416 The name of the output file
10417 append: boolean (optional)
10419 Open the file in append mode (default false to truncate) (Since
10420 2.6)
10421 The members of ChardevCommon
10423 Since
10425 1.4
10426 ChardevHostdev (Object)
10428 Configuration info for device and pipe chardevs.
10429 Members
10431 device: string
10432 The name of the special file for the device, i.e. /dev/ttyS0 on
10433 Unix or COM1: on Windows
10434 The members of ChardevCommon
10436 Since
10438 1.4
10439 ChardevSocket (Object)
10441 Configuration info for (stream) socket chardevs.
10442 Members
10444 addr: SocketAddressLegacy
10445 socket address to listen on (server=true) or connect to
10446 (server=false)
10447 tls-creds: string (optional)
10449 the ID of the TLS credentials object (since 2.6)
10450 tls-authz: string (optional)
10452 the ID of the QAuthZ authorization object against which the
10453 client's x509 distinguished name will be validated. This object
10454 is only resolved at time of use, so can be deleted and recreated
10455 on the fly while the chardev server is active. If missing, it
10456 will default to denying access (since 4.0)
10457 server: boolean (optional)
10459 create server socket (default: true)
10460 wait: boolean (optional)
10462 wait for incoming connection on server sockets (default: false).
10463 Silently ignored with server: false. This use is deprecated.
10464 nodelay: boolean (optional)
10466 set TCP_NODELAY socket option (default: false)
10467 telnet: boolean (optional)
10469 enable telnet protocol on server sockets (default: false)
10470 tn3270: boolean (optional)
10472 enable tn3270 protocol on server sockets (default: false)
10473 (Since: 2.10)
10474 websocket: boolean (optional)
10476 enable websocket protocol on server sockets (default: false)
10477 (Since: 3.1)
10478 reconnect: int (optional)
10480 For a client socket, if a socket is disconnected, then attempt a
10481 reconnect after the given number of seconds. Setting this to
10482 zero disables this function. (default: 0) (Since: 2.2)
10483 The members of ChardevCommon
10485 Since
10487 1.4
10488 ChardevUdp (Object)
10490 Configuration info for datagram socket chardevs.
10491 Members
10493 remote: SocketAddressLegacy
10494 remote address
10495 local: SocketAddressLegacy (optional)
10497 local address
10498 The members of ChardevCommon
10500 Since
10502 1.5
10503 ChardevMux (Object)
10505 Configuration info for mux chardevs.
10506 Members
10508 chardev: string
10509 name of the base chardev.
10510 The members of ChardevCommon
10512 Since
10514 1.5
10515 ChardevStdio (Object)
10517 Configuration info for stdio chardevs.
10518 Members
10520 signal: boolean (optional)
10521 Allow signals (such as SIGINT triggered by ^C) be delivered to
10522 qemu. Default: true.
10523 The members of ChardevCommon
10525 Since
10527 1.5
10528 ChardevSpiceChannel (Object)
10530 Configuration info for spice vm channel chardevs.
10531 Members
10533 type: string
10534 kind of channel (for example vdagent).
10535 The members of ChardevCommon
10537 Since
10539 1.5
10540 If
10542 CONFIG_SPICE
10543 ChardevSpicePort (Object)
10545 Configuration info for spice port chardevs.
10546 Members
10548 fqdn: string
10549 name of the channel (see docs/spice-port-fqdn.txt)
10550 The members of ChardevCommon
10552 Since
10554 1.5
10555 If
10557 CONFIG_SPICE
10558 ChardevDBus (Object)
10560 Configuration info for DBus chardevs.
10561 Members
10563 name: string
10564 name of the channel (following docs/spice-port-fqdn.txt)
10565 The members of ChardevCommon
10567 Since
10569 7.0
10570 If
10572 CONFIG_DBUS_DISPLAY
10573 ChardevVC (Object)
10575 Configuration info for virtual console chardevs.
10576 Members
10578 width: int (optional)
10579 console width, in pixels
10580 height: int (optional)
10582 console height, in pixels
10583 cols: int (optional)
10585 console width, in chars
10586 rows: int (optional)
10588 console height, in chars
10589 The members of ChardevCommon
10591 Since
10593 1.5
10594 ChardevRingbuf (Object)
10596 Configuration info for ring buffer chardevs.
10597 Members
10599 size: int (optional)
10600 ring buffer size, must be power of two, default is 65536
10601 The members of ChardevCommon
10603 Since
10605 1.5
10606 ChardevQemuVDAgent (Object)
10608 Configuration info for qemu vdagent implementation.
10609 Members
10611 mouse: boolean (optional)
10612 enable/disable mouse, default is enabled.
10613 clipboard: boolean (optional)
10615 enable/disable clipboard, default is disabled.
10616 The members of ChardevCommon
10618 Since
10620 6.1
10621 If
10623 CONFIG_SPICE_PROTOCOL
10624 ChardevBackendKind (Enum)
10626 Values
10627 pipe Since 1.5
10628 udp Since 1.5
10630 mux Since 1.5
10632 msmouse
10634 Since 1.5
10635 wctablet
10637 Since 2.9
10638 braille
10640 Since 1.5
10641 testdev
10643 Since 2.2
10644 stdio Since 1.5
10646 console
10648 Since 1.5
10649 spicevmc (If: CONFIG_SPICE)
10651 Since 1.5
10652 spiceport (If: CONFIG_SPICE)
10654 Since 1.5
10655 qemu-vdagent (If: CONFIG_SPICE_PROTOCOL)
10657 Since 6.1
10658 dbus (If: CONFIG_DBUS_DISPLAY)
10660 Since 7.0
10661 vc v1.5
10663 ringbuf
10665 Since 1.6
10666 memory Since 1.5
10668 file Not documented
10670 serial Not documented
10672 parallel
10674 Not documented
10675 socket Not documented
10677 pty Not documented
10679 null Not documented
10681 Since
10683 1.4
10684 ChardevFileWrapper (Object)
10686 Members
10687 data: ChardevFile
10688 Not documented
10689 Since
10691 1.4
10692 ChardevHostdevWrapper (Object)
10694 Members
10695 data: ChardevHostdev
10696 Not documented
10697 Since
10699 1.4
10700 ChardevSocketWrapper (Object)
10702 Members
10703 data: ChardevSocket
10704 Not documented
10705 Since
10707 1.4
10708 ChardevUdpWrapper (Object)
10710 Members
10711 data: ChardevUdp
10712 Not documented
10713 Since
10715 1.5
10716 ChardevCommonWrapper (Object)
10718 Members
10719 data: ChardevCommon
10720 Not documented
10721 Since
10723 2.6
10724 ChardevMuxWrapper (Object)
10726 Members
10727 data: ChardevMux
10728 Not documented
10729 Since
10731 1.5
10732 ChardevStdioWrapper (Object)
10734 Members
10735 data: ChardevStdio
10736 Not documented
10737 Since
10739 1.5
10740 ChardevSpiceChannelWrapper (Object)
10742 Members
10743 data: ChardevSpiceChannel
10744 Not documented
10745 Since
10747 1.5
10748 If
10750 CONFIG_SPICE
10751 ChardevSpicePortWrapper (Object)
10753 Members
10754 data: ChardevSpicePort
10755 Not documented
10756 Since
10758 1.5
10759 If
10761 CONFIG_SPICE
10762 ChardevQemuVDAgentWrapper (Object)
10764 Members
10765 data: ChardevQemuVDAgent
10766 Not documented
10767 Since
10769 6.1
10770 If
10772 CONFIG_SPICE_PROTOCOL
10773 ChardevDBusWrapper (Object)
10775 Members
10776 data: ChardevDBus
10777 Not documented
10778 Since
10780 7.0
10781 If
10783 CONFIG_DBUS_DISPLAY
10784 ChardevVCWrapper (Object)
10786 Members
10787 data: ChardevVC
10788 Not documented
10789 Since
10791 1.5
10792 ChardevRingbufWrapper (Object)
10794 Members
10795 data: ChardevRingbuf
10796 Not documented
10797 Since
10799 1.5
10800 ChardevBackend (Object)
10802 Configuration info for the new chardev backend.
10803 Members
10805 type: ChardevBackendKind
10806 Not documented
10807 The members of ChardevFileWrapper when type is "file"
10809 The members of ChardevHostdevWrapper when type is "serial"
10811 The members of ChardevHostdevWrapper when type is "parallel"
10813 The members of ChardevHostdevWrapper when type is "pipe"
10815 The members of ChardevSocketWrapper when type is "socket"
10817 The members of ChardevUdpWrapper when type is "udp"
10819 The members of ChardevCommonWrapper when type is "pty"
10821 The members of ChardevCommonWrapper when type is "null"
10823 The members of ChardevMuxWrapper when type is "mux"
10825 The members of ChardevCommonWrapper when type is "msmouse"
10827 The members of ChardevCommonWrapper when type is "wctablet"
10829 The members of ChardevCommonWrapper when type is "braille"
10831 The members of ChardevCommonWrapper when type is "testdev"
10833 The members of ChardevStdioWrapper when type is "stdio"
10835 The members of ChardevCommonWrapper when type is "console"
10837 The members of ChardevSpiceChannelWrapper when type is "spicevmc" (If:
10839 CONFIG_SPICE)
10840 The members of ChardevSpicePortWrapper when type is "spiceport" (If:
10842 CONFIG_SPICE)
10843 The members of ChardevQemuVDAgentWrapper when type is "qemu-vdagent"
10845 (If: CONFIG_SPICE_PROTOCOL)
10846 The members of ChardevDBusWrapper when type is "dbus" (If: CON‐
10848 FIG_DBUS_DISPLAY)
10849 The members of ChardevVCWrapper when type is "vc"
10851 The members of ChardevRingbufWrapper when type is "ringbuf"
10853 The members of ChardevRingbufWrapper when type is "memory"
10855 Since
10857 1.4
10858 ChardevReturn (Object)
10860 Return info about the chardev backend just created.
10861 Members
10863 pty: string (optional)
10864 name of the slave pseudoterminal device, present if and only if
10865 a chardev of type 'pty' was created
10866 Since
10868 1.4
10869 chardev-add (Command)
10871 Add a character device backend
10872 Arguments
10874 id: string
10875 the chardev's ID, must be unique
10876 backend: ChardevBackend
10878 backend type and parameters
10879 Returns
10881 ChardevReturn.
10882 Since
10884 1.4
10885 Examples
10887 -> { "execute" : "chardev-add",
10888 "arguments" : { "id" : "foo",
10889 "backend" : { "type" : "null", "data" : {} } } }
10890 <- { "return": {} }
10891 -> { "execute" : "chardev-add",
10893 "arguments" : { "id" : "bar",
10894 "backend" : { "type" : "file",
10895 "data" : { "out" : "/tmp/bar.log" } } } }
10896 <- { "return": {} }
10897 -> { "execute" : "chardev-add",
10899 "arguments" : { "id" : "baz",
10900 "backend" : { "type" : "pty", "data" : {} } } }
10901 <- { "return": { "pty" : "/dev/pty/42" } }
10902 chardev-change (Command)
10904 Change a character device backend
10905 Arguments
10907 id: string
10908 the chardev's ID, must exist
10909 backend: ChardevBackend
10911 new backend type and parameters
10912 Returns
10914 ChardevReturn.
10915 Since
10917 2.10
10918 Examples
10920 -> { "execute" : "chardev-change",
10921 "arguments" : { "id" : "baz",
10922 "backend" : { "type" : "pty", "data" : {} } } }
10923 <- { "return": { "pty" : "/dev/pty/42" } }
10924 -> {"execute" : "chardev-change",
10926 "arguments" : {
10927 "id" : "charchannel2",
10928 "backend" : {
10929 "type" : "socket",
10930 "data" : {
10931 "addr" : {
10932 "type" : "unix" ,
10933 "data" : {
10934 "path" : "/tmp/charchannel2.socket"
10935 }
10936 },
10937 "server" : true,
10938 "wait" : false }}}}
10939 <- {"return": {}}
10940 chardev-remove (Command)
10942 Remove a character device backend
10943 Arguments
10945 id: string
10946 the chardev's ID, must exist and not be in use
10947 Returns
10949 Nothing on success
10950 Since
10952 1.4
10953 Example
10955 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
10956 <- { "return": {} }
10957 chardev-send-break (Command)
10959 Send a break to a character device
10960 Arguments
10962 id: string
10963 the chardev's ID, must exist
10964 Returns
10966 Nothing on success
10967 Since
10969 2.10
10970 Example
10972 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
10973 <- { "return": {} }
10974 VSERPORT_CHANGE (Event)
10976 Emitted when the guest opens or closes a virtio-serial port.
10977 Arguments
10979 id: string
10980 device identifier of the virtio-serial port
10981 open: boolean
10983 true if the guest has opened the virtio-serial port
10984 Note
10986 This event is rate-limited.
10987 Since
10989 2.1
10990 Example
10992 <- { "event": "VSERPORT_CHANGE",
10993 "data": { "id": "channel0", "open": true },
10994 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
10995
10997 DumpGuestMemoryFormat (Enum)
10998 An enumeration of guest-memory-dump's format.
10999 Values
11001 elf elf format
11002 kdump-zlib
11004 kdump-compressed format with zlib-compressed
11005 kdump-lzo
11007 kdump-compressed format with lzo-compressed
11008 kdump-snappy
11010 kdump-compressed format with snappy-compressed
11011 win-dmp
11013 Windows full crashdump format, can be used instead of ELF con‐
11014 verting (since 2.13)
11015 Since
11017 2.0
11018 dump-guest-memory (Command)
11020 Dump guest's memory to vmcore. It is a synchronous operation that can
11021 take very long depending on the amount of guest memory.
11022 Arguments
11024 paging: boolean
11025 if true, do paging to get guest's memory mapping. This allows
11026 using gdb to process the core file.
11027 IMPORTANT: this option can make QEMU allocate several gigabytes
11029 of RAM. This can happen for a large guest, or a malicious guest
11030 pretending to be large.
11031 Also, paging=true has the following limitations:
11033 1. The guest may be in a catastrophic state or can have cor‐
11035 rupted memory, which cannot be trusted
11036 2. The guest can be in real-mode even if paging is enabled. For
11038 example, the guest uses ACPI to sleep, and ACPI sleep state
11039 goes in real-mode
11040 3. Currently only supported on i386 and x86_64.
11042 protocol: string
11044 the filename or file descriptor of the vmcore. The supported
11045 protocols are:
11046 1. file: the protocol starts with "file:", and the following
11048 string is the file's path.
11049 2. fd: the protocol starts with "fd:", and the following string
11051 is the fd's name.
11052 detach: boolean (optional)
11054 if true, QMP will return immediately rather than waiting for the
11055 dump to finish. The user can track progress using "query-dump".
11056 (since 2.6).
11057 begin: int (optional)
11059 if specified, the starting physical address.
11060 length: int (optional)
11062 if specified, the memory size, in bytes. If you don't want to
11063 dump all guest's memory, please specify the start begin and
11064 length
11065 format: DumpGuestMemoryFormat (optional)
11067 if specified, the format of guest memory dump. But non-elf for‐
11068 mat is conflict with paging and filter, ie. paging, begin and
11069 length is not allowed to be specified with non-elf format at the
11070 same time (since 2.0)
11071 Note
11073 All boolean arguments default to false
11074 Returns
11076 nothing on success
11077 Since
11079 1.2
11080 Example
11082 -> { "execute": "dump-guest-memory",
11083 "arguments": { "paging": false, "protocol": "fd:dump" } }
11084 <- { "return": {} }
11085 DumpStatus (Enum)
11087 Describe the status of a long-running background guest memory dump.
11088 Values
11090 none no dump-guest-memory has started yet.
11091 active there is one dump running in background.
11093 completed
11095 the last dump has finished successfully.
11096 failed the last dump has failed.
11098 Since
11100 2.6
11101 DumpQueryResult (Object)
11103 The result format for 'query-dump'.
11104 Members
11106 status: DumpStatus
11107 enum of DumpStatus, which shows current dump status
11108 completed: int
11110 bytes written in latest dump (uncompressed)
11111 total: int
11113 total bytes to be written in latest dump (uncompressed)
11114 Since
11116 2.6
11117 query-dump (Command)
11119 Query latest dump status.
11120 Returns
11122 A DumpStatus object showing the dump status.
11123 Since
11125 2.6
11126 Example
11128 -> { "execute": "query-dump" }
11129 <- { "return": { "status": "active", "completed": 1024000,
11130 "total": 2048000 } }
11131 DUMP_COMPLETED (Event)
11133 Emitted when background dump has completed
11134 Arguments
11136 result: DumpQueryResult
11137 final dump status
11138 error: string (optional)
11140 human-readable error string that provides hint on why dump
11141 failed. Only presents on failure. The user should not try to
11142 interpret the error string.
11143 Since
11145 2.6
11146 Example
11148 <- { "event": "DUMP_COMPLETED",
11149 "data": { "result": { "total": 1090650112, "status": "completed",
11150 "completed": 1090650112 } },
11151 "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }
11152 DumpGuestMemoryCapability (Object)
11154 A list of the available formats for dump-guest-memory
11155 Members
11157 formats: array of DumpGuestMemoryFormat
11158 Not documented
11159 Since
11161 2.0
11162 query-dump-guest-memory-capability (Command)
11164 Returns the available formats for dump-guest-memory
11165 Returns
11167 A DumpGuestMemoryCapability object listing available formats for
11168 dump-guest-memory
11169 Since
11171 2.0
11172 Example
11174 -> { "execute": "query-dump-guest-memory-capability" }
11175 <- { "return": { "formats":
11176 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } }
11177
11179 set_link (Command)
11180 Sets the link status of a virtual network adapter.
11181 Arguments
11183 name: string
11184 the device name of the virtual network adapter
11185 up: boolean
11187 true to set the link status to be up
11188 Returns
11190 Nothing on success If name is not a valid network device, DeviceNot‐
11191 Found
11192 Since
11194 0.14
11195 Notes
11197 Not all network adapters support setting link status. This command
11198 will succeed even if the network adapter does not support link status
11199 notification.
11200 Example
11202 -> { "execute": "set_link",
11203 "arguments": { "name": "e1000.0", "up": false } }
11204 <- { "return": {} }
11205 netdev_add (Command)
11207 Add a network backend.
11208 Additional arguments depend on the type.
11210 Arguments
11212 The members of Netdev
11213 Since
11215 0.14
11216 Returns
11218 Nothing on success If type is not a valid network backend, DeviceNot‐
11219 Found
11220 Example
11222 -> { "execute": "netdev_add",
11223 "arguments": { "type": "user", "id": "netdev1",
11224 "dnssearch": [ { "str": "example.org" } ] } }
11225 <- { "return": {} }
11226 netdev_del (Command)
11228 Remove a network backend.
11229 Arguments
11231 id: string
11232 the name of the network backend to remove
11233 Returns
11235 Nothing on success If id is not a valid network backend, DeviceNotFound
11236 Since
11238 0.14
11239 Example
11241 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
11242 <- { "return": {} }
11243 NetLegacyNicOptions (Object)
11245 Create a new Network Interface Card.
11246 Members
11248 netdev: string (optional)
11249 id of -netdev to connect to
11250 macaddr: string (optional)
11252 MAC address
11253 model: string (optional)
11255 device model (e1000, rtl8139, virtio etc.)
11256 addr: string (optional)
11258 PCI device address
11259 vectors: int (optional)
11261 number of MSI-x vectors, 0 to disable MSI-X
11262 Since
11264 1.2
11265 NetdevUserOptions (Object)
11267 Use the user mode network stack which requires no administrator privi‐
11268 lege to run.
11269 Members
11271 hostname: string (optional)
11272 client hostname reported by the builtin DHCP server
11273 restrict: boolean (optional)
11275 isolate the guest from the host
11276 ipv4: boolean (optional)
11278 whether to support IPv4, default true for enabled (since 2.6)
11279 ipv6: boolean (optional)
11281 whether to support IPv6, default true for enabled (since 2.6)
11282 ip: string (optional)
11284 legacy parameter, use net= instead
11285 net: string (optional)
11287 IP network address that the guest will see, in the form
11288 addr[/netmask] The netmask is optional, and can be either in the
11289 form a.b.c.d or as a number of valid top-most bits. Default is
11290 10.0.2.0/24.
11291 host: string (optional)
11293 guest-visible address of the host
11294 tftp: string (optional)
11296 root directory of the built-in TFTP server
11297 bootfile: string (optional)
11299 BOOTP filename, for use with tftp=
11300 dhcpstart: string (optional)
11302 the first of the 16 IPs the built-in DHCP server can assign
11303 dns: string (optional)
11305 guest-visible address of the virtual nameserver
11306 dnssearch: array of String (optional)
11308 list of DNS suffixes to search, passed as DHCP option to the
11309 guest
11310 domainname: string (optional)
11312 guest-visible domain name of the virtual nameserver (since 3.0)
11313 ipv6-prefix: string (optional)
11315 IPv6 network prefix (default is fec0::) (since 2.6). The net‐
11316 work prefix is given in the usual hexadecimal IPv6 address nota‐
11317 tion.
11318 ipv6-prefixlen: int (optional)
11320 IPv6 network prefix length (default is 64) (since 2.6)
11321 ipv6-host: string (optional)
11323 guest-visible IPv6 address of the host (since 2.6)
11324 ipv6-dns: string (optional)
11326 guest-visible IPv6 address of the virtual nameserver (since 2.6)
11327 smb: string (optional)
11329 root directory of the built-in SMB server
11330 smbserver: string (optional)
11332 IP address of the built-in SMB server
11333 hostfwd: array of String (optional)
11335 redirect incoming TCP or UDP host connections to guest endpoints
11336 guestfwd: array of String (optional)
11338 forward guest TCP connections
11339 tftp-server-name: string (optional)
11341 RFC2132 "TFTP server name" string (Since 3.1)
11342 Since
11344 1.2
11345 NetdevTapOptions (Object)
11347 Used to configure a host TAP network interface backend.
11348 Members
11350 ifname: string (optional)
11351 interface name
11352 fd: string (optional)
11354 file descriptor of an already opened tap
11355 fds: string (optional)
11357 multiple file descriptors of already opened multiqueue capable
11358 tap
11359 script: string (optional)
11361 script to initialize the interface
11362 downscript: string (optional)
11364 script to shut down the interface
11365 br: string (optional)
11367 bridge name (since 2.8)
11368 helper: string (optional)
11370 command to execute to configure bridge
11371 sndbuf: int (optional)
11373 send buffer limit. Understands [TGMKkb] suffixes.
11374 vnet_hdr: boolean (optional)
11376 enable the IFF_VNET_HDR flag on the tap interface
11377 vhost: boolean (optional)
11379 enable vhost-net network accelerator
11380 vhostfd: string (optional)
11382 file descriptor of an already opened vhost net device
11383 vhostfds: string (optional)
11385 file descriptors of multiple already opened vhost net devices
11386 vhostforce: boolean (optional)
11388 vhost on for non-MSIX virtio guests
11389 queues: int (optional)
11391 number of queues to be created for multiqueue capable tap
11392 poll-us: int (optional)
11394 maximum number of microseconds that could be spent on busy
11395 polling for tap (since 2.7)
11396 Since
11398 1.2
11399 NetdevSocketOptions (Object)
11401 Socket netdevs are used to establish a network connection to another
11402 QEMU virtual machine via a TCP socket.
11403 Members
11405 fd: string (optional)
11406 file descriptor of an already opened socket
11407 listen: string (optional)
11409 port number, and optional hostname, to listen on
11410 connect: string (optional)
11412 port number, and optional hostname, to connect to
11413 mcast: string (optional)
11415 UDP multicast address and port number
11416 localaddr: string (optional)
11418 source address and port for multicast and udp packets
11419 udp: string (optional)
11421 UDP unicast address and port number
11422 Since
11424 1.2
11425 NetdevL2TPv3Options (Object)
11427 Configure an Ethernet over L2TPv3 tunnel.
11428 Members
11430 src: string
11431 source address
11432 dst: string
11434 destination address
11435 srcport: string (optional)
11437 source port - mandatory for udp, optional for ip
11438 dstport: string (optional)
11440 destination port - mandatory for udp, optional for ip
11441 ipv6: boolean (optional)
11443 force the use of ipv6
11444 udp: boolean (optional)
11446 use the udp version of l2tpv3 encapsulation
11447 cookie64: boolean (optional)
11449 use 64 bit cookies
11450 counter: boolean (optional)
11452 have sequence counter
11453 pincounter: boolean (optional)
11455 pin sequence counter to zero - workaround for buggy implementa‐
11456 tions or networks with packet reorder
11457 txcookie: int (optional)
11459 32 or 64 bit transmit cookie
11460 rxcookie: int (optional)
11462 32 or 64 bit receive cookie
11463 txsession: int
11465 32 bit transmit session
11466 rxsession: int (optional)
11468 32 bit receive session - if not specified set to the same value
11469 as transmit
11470 offset: int (optional)
11472 additional offset - allows the insertion of additional applica‐
11473 tion-specific data before the packet payload
11474 Since
11476 2.1
11477 NetdevVdeOptions (Object)
11479 Connect to a vde switch running on the host.
11480 Members
11482 sock: string (optional)
11483 socket path
11484 port: int (optional)
11486 port number
11487 group: string (optional)
11489 group owner of socket
11490 mode: int (optional)
11492 permissions for socket
11493 Since
11495 1.2
11496 NetdevBridgeOptions (Object)
11498 Connect a host TAP network interface to a host bridge device.
11499 Members
11501 br: string (optional)
11502 bridge name
11503 helper: string (optional)
11505 command to execute to configure bridge
11506 Since
11508 1.2
11509 NetdevHubPortOptions (Object)
11511 Connect two or more net clients through a software hub.
11512 Members
11514 hubid: int
11515 hub identifier number
11516 netdev: string (optional)
11518 used to connect hub to a netdev instead of a device (since 2.12)
11519 Since
11521 1.2
11522 NetdevNetmapOptions (Object)
11524 Connect a client to a netmap-enabled NIC or to a VALE switch port
11525 Members
11527 ifname: string
11528 Either the name of an existing network interface supported by
11529 netmap, or the name of a VALE port (created on the fly). A VALE
11530 port name is in the form 'valeXXX:YYY', where XXX and YYY are
11531 non-negative integers. XXX identifies a switch and YYY identi‐
11532 fies a port of the switch. VALE ports having the same XXX are
11533 therefore connected to the same switch.
11534 devname: string (optional)
11536 path of the netmap device (default: '/dev/netmap').
11537 Since
11539 2.0
11540 NetdevVhostUserOptions (Object)
11542 Vhost-user network backend
11543 Members
11545 chardev: string
11546 name of a unix socket chardev
11547 vhostforce: boolean (optional)
11549 vhost on for non-MSIX virtio guests (default: false).
11550 queues: int (optional)
11552 number of queues to be created for multiqueue vhost-user (de‐
11553 fault: 1) (Since 2.5)
11554 Since
11556 2.1
11557 NetdevVhostVDPAOptions (Object)
11559 Vhost-vdpa network backend
11560 vDPA device is a device that uses a datapath which complies with the
11562 virtio specifications with a vendor specific control path.
11563 Members
11565 vhostdev: string (optional)
11566 path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
11567 vhostfd: string (optional)
11569 file descriptor of an already opened vhost vdpa device
11570 queues: int (optional)
11572 number of queues to be created for multiqueue vhost-vdpa (de‐
11573 fault: 1)
11574 x-svq: boolean (optional)
11576 Start device with (experimental) shadow virtqueue. (Since 7.1)
11577 (default: false)
11578 Features
11580 unstable
11581 Member x-svq is experimental.
11582 Since
11584 5.1
11585 NetdevVmnetHostOptions (Object)
11587 vmnet (host mode) network backend.
11588 Allows the vmnet interface to communicate with other vmnet interfaces
11590 that are in host mode and also with the host.
11591 Members
11593 start-address: string (optional)
11594 The starting IPv4 address to use for the interface. Must be in
11595 the private IP range (RFC 1918). Must be specified along with
11596 end-address and subnet-mask. This address is used as the gate‐
11597 way address. The subsequent address up to and including end-ad‐
11598 dress are placed in the DHCP pool.
11599 end-address: string (optional)
11601 The DHCP IPv4 range end address to use for the interface. Must
11602 be in the private IP range (RFC 1918). Must be specified along
11603 with start-address and subnet-mask.
11604 subnet-mask: string (optional)
11606 The IPv4 subnet mask to use on the interface. Must be specified
11607 along with start-address and subnet-mask.
11608 isolated: boolean (optional)
11610 Enable isolation for this interface. Interface isolation en‐
11611 sures that vmnet interface is not able to communicate with any
11612 other vmnet interfaces. Only communication with host is al‐
11613 lowed. Requires at least macOS Big Sur 11.0.
11614 net-uuid: string (optional)
11616 The identifier (UUID) to uniquely identify the isolated network
11617 vmnet interface should be added to. If set, no DHCP service is
11618 provided for this interface and network communication is allowed
11619 only with other interfaces added to this network identified by
11620 the UUID. Requires at least macOS Big Sur 11.0.
11621 Since
11623 7.1
11624 If
11626 CONFIG_VMNET
11627 NetdevVmnetSharedOptions (Object)
11629 vmnet (shared mode) network backend.
11630 Allows traffic originating from the vmnet interface to reach the Inter‐
11632 net through a network address translator (NAT). The vmnet interface can
11633 communicate with the host and with other shared mode interfaces on the
11634 same subnet. If no DHCP settings, subnet mask and IPv6 prefix speci‐
11635 fied, the interface can communicate with any of other interfaces in
11636 shared mode.
11637 Members
11639 start-address: string (optional)
11640 The starting IPv4 address to use for the interface. Must be in
11641 the private IP range (RFC 1918). Must be specified along with
11642 end-address and subnet-mask. This address is used as the gate‐
11643 way address. The subsequent address up to and including end-ad‐
11644 dress are placed in the DHCP pool.
11645 end-address: string (optional)
11647 The DHCP IPv4 range end address to use for the interface. Must
11648 be in the private IP range (RFC 1918). Must be specified along
11649 with start-address and subnet-mask.
11650 subnet-mask: string (optional)
11652 The IPv4 subnet mask to use on the interface. Must be specified
11653 along with start-address and subnet-mask.
11654 isolated: boolean (optional)
11656 Enable isolation for this interface. Interface isolation en‐
11657 sures that vmnet interface is not able to communicate with any
11658 other vmnet interfaces. Only communication with host is al‐
11659 lowed. Requires at least macOS Big Sur 11.0.
11660 nat66-prefix: string (optional)
11662 The IPv6 prefix to use into guest network. Must be a unique lo‐
11663 cal address i.e. start with fd00::/8 and have length of 64.
11664 Since
11666 7.1
11667 If
11669 CONFIG_VMNET
11670 NetdevVmnetBridgedOptions (Object)
11672 vmnet (bridged mode) network backend.
11673 Bridges the vmnet interface with a physical network interface.
11675 Members
11677 ifname: string
11678 The name of the physical interface to be bridged.
11679 isolated: boolean (optional)
11681 Enable isolation for this interface. Interface isolation en‐
11682 sures that vmnet interface is not able to communicate with any
11683 other vmnet interfaces. Only communication with host is al‐
11684 lowed. Requires at least macOS Big Sur 11.0.
11685 Since
11687 7.1
11688 If
11690 CONFIG_VMNET
11691 NetdevStreamOptions (Object)
11693 Configuration info for stream socket netdev
11694 Members
11696 addr: SocketAddress
11697 socket address to listen on (server=true) or connect to
11698 (server=false)
11699 server: boolean (optional)
11701 create server socket (default: false)
11702 reconnect: int (optional)
11704 For a client socket, if a socket is disconnected, then attempt a
11705 reconnect after the given number of seconds. Setting this to
11706 zero disables this function. (default: 0) (since 8.0)
11707 Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
11708 Since
11710 7.2
11711 NetdevDgramOptions (Object)
11713 Configuration info for datagram socket netdev.
11714 Members
11716 remote: SocketAddress (optional)
11717 remote address
11718 local: SocketAddress (optional)
11720 local address
11721 Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
11722 If remote address is present and it's a multicast address, local ad‐
11724 dress is optional. Otherwise local address is required and remote ad‐
11725 dress is optional.
11726 Valid parameters combination table
11728 ┌──────────────┬─────────┬───────┐
11729 │remote │ local │ okay? │
11730 ├──────────────┼─────────┼───────┤
11731 │absent │ absent │ no │
11732 ├──────────────┼─────────┼───────┤
11733 │absent │ not fd │ no │
11734 ├──────────────┼─────────┼───────┤
11735 │absent │ fd │ yes │
11736 ├──────────────┼─────────┼───────┤
11737 │multicast │ absent │ yes │
11738 ├──────────────┼─────────┼───────┤
11739 │multicast │ present │ yes │
11740 ├──────────────┼─────────┼───────┤
11741 │not multicast │ absent │ no │
11742 ├──────────────┼─────────┼───────┤
11743 │not multicast │ present │ yes │
11744 └──────────────┴─────────┴───────┘
11745 Since
11747 7.2
11748 NetClientDriver (Enum)
11750 Available netdev drivers.
11751 Values
11753 l2tpv3 since 2.1
11754 vhost-vdpa
11756 since 5.1
11757 vmnet-host (If: CONFIG_VMNET)
11759 since 7.1
11760 vmnet-shared (If: CONFIG_VMNET)
11762 since 7.1
11763 vmnet-bridged (If: CONFIG_VMNET)
11765 since 7.1
11766 stream since 7.2
11768 dgram since 7.2
11770 none Not documented
11772 nic Not documented
11774 user Not documented
11776 tap Not documented
11778 socket Not documented
11780 vde Not documented
11782 bridge Not documented
11784 hubport
11786 Not documented
11787 netmap Not documented
11789 vhost-user
11791 Not documented
11792 Since
11794 2.7
11795 Netdev (Object)
11797 Captures the configuration of a network device.
11798 Members
11800 id: string
11801 identifier for monitor commands.
11802 type: NetClientDriver
11804 Specify the driver used for interpreting remaining arguments.
11805 The members of NetLegacyNicOptions when type is "nic"
11807 The members of NetdevUserOptions when type is "user"
11809 The members of NetdevTapOptions when type is "tap"
11811 The members of NetdevL2TPv3Options when type is "l2tpv3"
11813 The members of NetdevSocketOptions when type is "socket"
11815 The members of NetdevStreamOptions when type is "stream"
11817 The members of NetdevDgramOptions when type is "dgram"
11819 The members of NetdevVdeOptions when type is "vde"
11821 The members of NetdevBridgeOptions when type is "bridge"
11823 The members of NetdevHubPortOptions when type is "hubport"
11825 The members of NetdevNetmapOptions when type is "netmap"
11827 The members of NetdevVhostUserOptions when type is "vhost-user"
11829 The members of NetdevVhostVDPAOptions when type is "vhost-vdpa"
11831 The members of NetdevVmnetHostOptions when type is "vmnet-host" (If:
11833 CONFIG_VMNET)
11834 The members of NetdevVmnetSharedOptions when type is "vmnet-shared"
11836 (If: CONFIG_VMNET)
11837 The members of NetdevVmnetBridgedOptions when type is "vmnet-bridged"
11839 (If: CONFIG_VMNET)
11840 Since
11842 1.2
11843 RxState (Enum)
11845 Packets receiving state
11846 Values
11848 normal filter assigned packets according to the mac-table
11849 none don't receive any assigned packet
11851 all receive all assigned packets
11853 Since
11855 1.6
11856 RxFilterInfo (Object)
11858 Rx-filter information for a NIC.
11859 Members
11861 name: string
11862 net client name
11863 promiscuous: boolean
11865 whether promiscuous mode is enabled
11866 multicast: RxState
11868 multicast receive state
11869 unicast: RxState
11871 unicast receive state
11872 vlan: RxState
11874 vlan receive state (Since 2.0)
11875 broadcast-allowed: boolean
11877 whether to receive broadcast
11878 multicast-overflow: boolean
11880 multicast table is overflowed or not
11881 unicast-overflow: boolean
11883 unicast table is overflowed or not
11884 main-mac: string
11886 the main macaddr string
11887 vlan-table: array of int
11889 a list of active vlan id
11890 unicast-table: array of string
11892 a list of unicast macaddr string
11893 multicast-table: array of string
11895 a list of multicast macaddr string
11896 Since
11898 1.6
11899 query-rx-filter (Command)
11901 Return rx-filter information for all NICs (or for the given NIC).
11902 Arguments
11904 name: string (optional)
11905 net client name
11906 Returns
11908 list of RxFilterInfo for all NICs (or for the given NIC). Returns an
11909 error if the given name doesn't exist, or given NIC doesn't support
11910 rx-filter querying, or given net client isn't a NIC.
11911 Since
11913 1.6
11914 Example
11916 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
11917 <- { "return": [
11918 {
11919 "promiscuous": true,
11920 "name": "vnet0",
11921 "main-mac": "52:54:00:12:34:56",
11922 "unicast": "normal",
11923 "vlan": "normal",
11924 "vlan-table": [
11925 4,
11926 0
11927 ],
11928 "unicast-table": [
11929 ],
11930 "multicast": "normal",
11931 "multicast-overflow": false,
11932 "unicast-overflow": false,
11933 "multicast-table": [
11934 "01:00:5e:00:00:01",
11935 "33:33:00:00:00:01",
11936 "33:33:ff:12:34:56"
11937 ],
11938 "broadcast-allowed": false
11939 }
11940 ]
11941 }
11942 NIC_RX_FILTER_CHANGED (Event)
11944 Emitted once until the 'query-rx-filter' command is executed, the first
11945 event will always be emitted
11946 Arguments
11948 name: string (optional)
11949 net client name
11950 path: string
11952 device path
11953 Since
11955 1.6
11956 Example
11958 <- { "event": "NIC_RX_FILTER_CHANGED",
11959 "data": { "name": "vnet0",
11960 "path": "/machine/peripheral/vnet0/virtio-backend" },
11961 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
11962 AnnounceParameters (Object)
11964 Parameters for self-announce timers
11965 Members
11967 initial: int
11968 Initial delay (in ms) before sending the first GARP/RARP an‐
11969 nouncement
11970 max: int
11972 Maximum delay (in ms) between GARP/RARP announcement packets
11973 rounds: int
11975 Number of self-announcement attempts
11976 step: int
11978 Delay increase (in ms) after each self-announcement attempt
11979 interfaces: array of string (optional)
11981 An optional list of interface names, which restricts the an‐
11982 nouncement to the listed interfaces. (Since 4.1)
11983 id: string (optional)
11985 A name to be used to identify an instance of announce-timers and
11986 to allow it to modified later. Not for use as part of the mi‐
11987 gration parameters. (Since 4.1)
11988 Since
11990 4.0
11991 announce-self (Command)
11993 Trigger generation of broadcast RARP frames to update network switches.
11994 This can be useful when network bonds fail-over the active slave.
11995 Arguments
11997 The members of AnnounceParameters
11998 Example
12000 -> { "execute": "announce-self",
12001 "arguments": {
12002 "initial": 50, "max": 550, "rounds": 10, "step": 50,
12003 "interfaces": ["vn2", "vn3"], "id": "bob" } }
12004 <- { "return": {} }
12005 Since
12007 4.0
12008 FAILOVER_NEGOTIATED (Event)
12010 Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotia‐
12011 tion. Failover primary devices which were hidden (not hotplugged when
12012 requested) before will now be hotplugged by the virtio-net standby de‐
12013 vice.
12014 Arguments
12016 device-id: string
12017 QEMU device id of the unplugged device
12018 Since
12020 4.2
12021 Example
12023 <- { "event": "FAILOVER_NEGOTIATED",
12024 "data": { "device-id": "net1" },
12025 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
12026 NETDEV_STREAM_CONNECTED (Event)
12028 Emitted when the netdev stream backend is connected
12029 Arguments
12031 netdev-id: string
12032 QEMU netdev id that is connected
12033 addr: SocketAddress
12035 The destination address
12036 Since
12038 7.2
12039 Examples
12041 <- { "event": "NETDEV_STREAM_CONNECTED",
12042 "data": { "netdev-id": "netdev0",
12043 "addr": { "port": "47666", "ipv6": true,
12044 "host": "::1", "type": "inet" } },
12045 "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }
12046 <- { "event": "NETDEV_STREAM_CONNECTED",
12048 "data": { "netdev-id": "netdev0",
12049 "addr": { "path": "/tmp/qemu0", "type": "unix" } },
12050 "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }
12051 NETDEV_STREAM_DISCONNECTED (Event)
12053 Emitted when the netdev stream backend is disconnected
12054 Arguments
12056 netdev-id: string
12057 QEMU netdev id that is disconnected
12058 Since
12060 7.2
12061 Example
12063 <- { 'event': 'NETDEV_STREAM_DISCONNECTED',
12064 'data': {'netdev-id': 'netdev0'},
12065 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} }
12066
12068 RDMA_GID_STATUS_CHANGED (Event)
12069 Emitted when guest driver adds/deletes GID to/from device
12070 Arguments
12072 netdev: string
12073 RoCE Network Device name
12074 gid-status: boolean
12076 Add or delete indication
12077 subnet-prefix: int
12079 Subnet Prefix
12080 interface-id: int
12082 Interface ID
12083 Since
12085 4.0
12086 Example
12088 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
12089 "event": "RDMA_GID_STATUS_CHANGED",
12090 "data":
12091 {"netdev": "bridge0",
12092 "interface-id": 15880512517475447892,
12093 "gid-status": true,
12094 "subnet-prefix": 33022}}
12095
12097 RockerSwitch (Object)
12098 Rocker switch information.
12099 Members
12101 name: string
12102 switch name
12103 id: int
12105 switch ID
12106 ports: int
12108 number of front-panel ports
12109 Since
12111 2.4
12112 query-rocker (Command)
12114 Return rocker switch information.
12115 Arguments
12117 name: string
12118 Not documented
12119 Returns
12121 Rocker information
12122 Since
12124 2.4
12125 Example
12127 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
12128 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
12129 RockerPortDuplex (Enum)
12131 An eumeration of port duplex states.
12132 Values
12134 half half duplex
12135 full full duplex
12137 Since
12139 2.4
12140 RockerPortAutoneg (Enum)
12142 An eumeration of port autoneg states.
12143 Values
12145 off autoneg is off
12146 on autoneg is on
12148 Since
12150 2.4
12151 RockerPort (Object)
12153 Rocker switch port information.
12154 Members
12156 name: string
12157 port name
12158 enabled: boolean
12160 port is enabled for I/O
12161 link-up: boolean
12163 physical link is UP on port
12164 speed: int
12166 port link speed in Mbps
12167 duplex: RockerPortDuplex
12169 port link duplex
12170 autoneg: RockerPortAutoneg
12172 port link autoneg
12173 Since
12175 2.4
12176 query-rocker-ports (Command)
12178 Return rocker switch port information.
12179 Arguments
12181 name: string
12182 Not documented
12183 Returns
12185 a list of RockerPort information
12186 Since
12188 2.4
12189 Example
12191 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
12192 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
12193 "autoneg": "off", "link-up": true, "speed": 10000},
12194 {"duplex": "full", "enabled": true, "name": "sw1.2",
12195 "autoneg": "off", "link-up": true, "speed": 10000}
12196 ]}
12197 RockerOfDpaFlowKey (Object)
12199 Rocker switch OF-DPA flow key
12200 Members
12202 priority: int
12203 key priority, 0 being lowest priority
12204 tbl-id: int
12206 flow table ID
12207 in-pport: int (optional)
12209 physical input port
12210 tunnel-id: int (optional)
12212 tunnel ID
12213 vlan-id: int (optional)
12215 VLAN ID
12216 eth-type: int (optional)
12218 Ethernet header type
12219 eth-src: string (optional)
12221 Ethernet header source MAC address
12222 eth-dst: string (optional)
12224 Ethernet header destination MAC address
12225 ip-proto: int (optional)
12227 IP Header protocol field
12228 ip-tos: int (optional)
12230 IP header TOS field
12231 ip-dst: string (optional)
12233 IP header destination address
12234 Note
12236 optional members may or may not appear in the flow key depending if
12237 they're relevant to the flow key.
12238 Since
12240 2.4
12241 RockerOfDpaFlowMask (Object)
12243 Rocker switch OF-DPA flow mask
12244 Members
12246 in-pport: int (optional)
12247 physical input port
12248 tunnel-id: int (optional)
12250 tunnel ID
12251 vlan-id: int (optional)
12253 VLAN ID
12254 eth-src: string (optional)
12256 Ethernet header source MAC address
12257 eth-dst: string (optional)
12259 Ethernet header destination MAC address
12260 ip-proto: int (optional)
12262 IP Header protocol field
12263 ip-tos: int (optional)
12265 IP header TOS field
12266 Note
12268 optional members may or may not appear in the flow mask depending if
12269 they're relevant to the flow mask.
12270 Since
12272 2.4
12273 RockerOfDpaFlowAction (Object)
12275 Rocker switch OF-DPA flow action
12276 Members
12278 goto-tbl: int (optional)
12279 next table ID
12280 group-id: int (optional)
12282 group ID
12283 tunnel-lport: int (optional)
12285 tunnel logical port ID
12286 vlan-id: int (optional)
12288 VLAN ID
12289 new-vlan-id: int (optional)
12291 new VLAN ID
12292 out-pport: int (optional)
12294 physical output port
12295 Note
12297 optional members may or may not appear in the flow action depending if
12298 they're relevant to the flow action.
12299 Since
12301 2.4
12302 RockerOfDpaFlow (Object)
12304 Rocker switch OF-DPA flow
12305 Members
12307 cookie: int
12308 flow unique cookie ID
12309 hits: int
12311 count of matches (hits) on flow
12312 key: RockerOfDpaFlowKey
12314 flow key
12315 mask: RockerOfDpaFlowMask
12317 flow mask
12318 action: RockerOfDpaFlowAction
12320 flow action
12321 Since
12323 2.4
12324 query-rocker-of-dpa-flows (Command)
12326 Return rocker OF-DPA flow information.
12327 Arguments
12329 name: string
12330 switch name
12331 tbl-id: int (optional)
12333 flow table ID. If tbl-id is not specified, returns flow infor‐
12334 mation for all tables.
12335 Returns
12337 rocker OF-DPA flow information
12338 Since
12340 2.4
12341 Example
12343 -> { "execute": "query-rocker-of-dpa-flows",
12344 "arguments": { "name": "sw1" } }
12345 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
12346 "hits": 138,
12347 "cookie": 0,
12348 "action": {"goto-tbl": 10},
12349 "mask": {"in-pport": 4294901760}
12350 },
12351 {...more...},
12352 ]}
12353 RockerOfDpaGroup (Object)
12355 Rocker switch OF-DPA group
12356 Members
12358 id: int
12359 group unique ID
12360 type: int
12362 group type
12363 vlan-id: int (optional)
12365 VLAN ID
12366 pport: int (optional)
12368 physical port number
12369 index: int (optional)
12371 group index, unique with group type
12372 out-pport: int (optional)
12374 output physical port number
12375 group-id: int (optional)
12377 next group ID
12378 set-vlan-id: int (optional)
12380 VLAN ID to set
12381 pop-vlan: int (optional)
12383 pop VLAN headr from packet
12384 group-ids: array of int (optional)
12386 list of next group IDs
12387 set-eth-src: string (optional)
12389 set source MAC address in Ethernet header
12390 set-eth-dst: string (optional)
12392 set destination MAC address in Ethernet header
12393 ttl-check: int (optional)
12395 perform TTL check
12396 Note
12398 optional members may or may not appear in the group depending if
12399 they're relevant to the group type.
12400 Since
12402 2.4
12403 query-rocker-of-dpa-groups (Command)
12405 Return rocker OF-DPA group information.
12406 Arguments
12408 name: string
12409 switch name
12410 type: int (optional)
12412 group type. If type is not specified, returns group information
12413 for all group types.
12414 Returns
12416 rocker OF-DPA group information
12417 Since
12419 2.4
12420 Example
12422 -> { "execute": "query-rocker-of-dpa-groups",
12423 "arguments": { "name": "sw1" } }
12424 <- { "return": [ {"type": 0, "out-pport": 2,
12425 "pport": 2, "vlan-id": 3841,
12426 "pop-vlan": 1, "id": 251723778},
12427 {"type": 0, "out-pport": 0,
12428 "pport": 0, "vlan-id": 3841,
12429 "pop-vlan": 1, "id": 251723776},
12430 {"type": 0, "out-pport": 1,
12431 "pport": 1, "vlan-id": 3840,
12432 "pop-vlan": 1, "id": 251658241},
12433 {"type": 0, "out-pport": 0,
12434 "pport": 0, "vlan-id": 3840,
12435 "pop-vlan": 1, "id": 251658240}
12436 ]}
12437
12439 TpmModel (Enum)
12440 An enumeration of TPM models
12441 Values
12443 tpm-tis
12444 TPM TIS model
12445 tpm-crb
12447 TPM CRB model (since 2.12)
12448 tpm-spapr
12450 TPM SPAPR model (since 5.0)
12451 Since
12453 1.5
12454 If
12456 CONFIG_TPM
12457 query-tpm-models (Command)
12459 Return a list of supported TPM models
12460 Returns
12462 a list of TpmModel
12463 Since
12465 1.5
12466 Example
12468 -> { "execute": "query-tpm-models" }
12469 <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
12470 If
12472 CONFIG_TPM
12473 TpmType (Enum)
12475 An enumeration of TPM types
12476 Values
12478 passthrough
12479 TPM passthrough type
12480 emulator
12482 Software Emulator TPM type (since 2.11)
12483 Since
12485 1.5
12486 If
12488 CONFIG_TPM
12489 query-tpm-types (Command)
12491 Return a list of supported TPM types
12492 Returns
12494 a list of TpmType
12495 Since
12497 1.5
12498 Example
12500 -> { "execute": "query-tpm-types" }
12501 <- { "return": [ "passthrough", "emulator" ] }
12502 If
12504 CONFIG_TPM
12505 TPMPassthroughOptions (Object)
12507 Information about the TPM passthrough type
12508 Members
12510 path: string (optional)
12511 string describing the path used for accessing the TPM device
12512 cancel-path: string (optional)
12514 string showing the TPM's sysfs cancel file for cancellation of
12515 TPM commands while they are executing
12516 Since
12518 1.5
12519 If
12521 CONFIG_TPM
12522 TPMEmulatorOptions (Object)
12524 Information about the TPM emulator type
12525 Members
12527 chardev: string
12528 Name of a unix socket chardev
12529 Since
12531 2.11
12532 If
12534 CONFIG_TPM
12535 TPMPassthroughOptionsWrapper (Object)
12537 Members
12538 data: TPMPassthroughOptions
12539 Not documented
12540 Since
12542 1.5
12543 If
12545 CONFIG_TPM
12546 TPMEmulatorOptionsWrapper (Object)
12548 Members
12549 data: TPMEmulatorOptions
12550 Not documented
12551 Since
12553 2.11
12554 If
12556 CONFIG_TPM
12557 TpmTypeOptions (Object)
12559 A union referencing different TPM backend types' configuration options
12560 Members
12562 type: TpmType
12563 • 'passthrough' The configuration options for the TPM
12565 passthrough type
12566 • 'emulator' The configuration options for TPM emulator backend
12568 type
12569 The members of TPMPassthroughOptionsWrapper when type is "passthrough"
12571 The members of TPMEmulatorOptionsWrapper when type is "emulator"
12573 Since
12575 1.5
12576 If
12578 CONFIG_TPM
12579 TPMInfo (Object)
12581 Information about the TPM
12582 Members
12584 id: string
12585 The Id of the TPM
12586 model: TpmModel
12588 The TPM frontend model
12589 options: TpmTypeOptions
12591 The TPM (backend) type configuration options
12592 Since
12594 1.5
12595 If
12597 CONFIG_TPM
12598 query-tpm (Command)
12600 Return information about the TPM device
12601 Returns
12603 TPMInfo on success
12604 Since
12606 1.5
12607 Example
12609 -> { "execute": "query-tpm" }
12610 <- { "return":
12611 [
12612 { "model": "tpm-tis",
12613 "options":
12614 { "type": "passthrough",
12615 "data":
12616 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
12617 "path": "/dev/tpm0"
12618 }
12619 },
12620 "id": "tpm0"
12621 }
12622 ]
12623 }
12624 If
12626 CONFIG_TPM
12627
12629 DisplayProtocol (Enum)
12630 Display protocols which support changing password options.
12631 Values
12633 vnc Not documented
12634 spice Not documented
12636 Since
12638 7.0
12639 SetPasswordAction (Enum)
12641 An action to take on changing a password on a connection with active
12642 clients.
12643 Values
12645 keep maintain existing clients
12646 fail fail the command if clients are connected
12648 disconnect
12650 disconnect existing clients
12651 Since
12653 7.0
12654 SetPasswordOptions (Object)
12656 Options for set_password.
12657 Members
12659 protocol: DisplayProtocol
12660 • 'vnc' to modify the VNC server password
12662 • 'spice' to modify the Spice server password
12664 password: string
12666 the new password
12667 connected: SetPasswordAction (optional)
12669 How to handle existing clients when changing the password. If
12670 nothing is specified, defaults to 'keep'. For VNC, only 'keep'
12671 is currently implemented.
12672 The members of SetPasswordOptionsVnc when protocol is "vnc"
12674 Since
12676 7.0
12677 SetPasswordOptionsVnc (Object)
12679 Options for set_password specific to the VNC procotol.
12680 Members
12682 display: string (optional)
12683 The id of the display where the password should be changed. De‐
12684 faults to the first.
12685 Since
12687 7.0
12688 set_password (Command)
12690 Set the password of a remote display server.
12691 Arguments
12693 The members of SetPasswordOptions
12694 Returns
12696 • Nothing on success
12697 • If Spice is not enabled, DeviceNotFound
12699 Since
12701 0.14
12702 Example
12704 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
12705 "password": "secret" } }
12706 <- { "return": {} }
12707 ExpirePasswordOptions (Object)
12709 General options for expire_password.
12710 Members
12712 protocol: DisplayProtocol
12713 • 'vnc' to modify the VNC server expiration
12715 • 'spice' to modify the Spice server expiration
12717 time: string
12719 when to expire the password.
12720 • 'now' to expire the password immediately
12722 • 'never' to cancel password expiration
12724 • '+INT' where INT is the number of seconds from now (integer)
12726 • 'INT' where INT is the absolute time in seconds
12728 The members of ExpirePasswordOptionsVnc when protocol is "vnc"
12730 Notes
12732 Time is relative to the server and currently there is no way to coordi‐
12733 nate server time with client time. It is not recommended to use the
12734 absolute time version of the time parameter unless you're sure you are
12735 on the same machine as the QEMU instance.
12736 Since
12738 7.0
12739 ExpirePasswordOptionsVnc (Object)
12741 Options for expire_password specific to the VNC procotol.
12742 Members
12744 display: string (optional)
12745 The id of the display where the expiration should be changed.
12746 Defaults to the first.
12747 Since
12749 7.0
12750 expire_password (Command)
12752 Expire the password of a remote display server.
12753 Arguments
12755 The members of ExpirePasswordOptions
12756 Returns
12758 • Nothing on success
12759 • If protocol is 'spice' and Spice is not active, DeviceNotFound
12761 Since
12763 0.14
12764 Example
12766 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
12767 "time": "+60" } }
12768 <- { "return": {} }
12769 ImageFormat (Enum)
12771 Supported image format types.
12772 Values
12774 png PNG format
12775 ppm PPM format
12777 Since
12779 7.1
12780 screendump (Command)
12782 Capture the contents of a screen and write it to a file.
12783 Arguments
12785 filename: string
12786 the path of a new file to store the image
12787 device: string (optional)
12789 ID of the display device that should be dumped. If this parame‐
12790 ter is missing, the primary display will be used. (Since 2.12)
12791 head: int (optional)
12793 head to use in case the device supports multiple heads. If this
12794 parameter is missing, head #0 will be used. Also note that the
12795 head can only be specified in conjunction with the device ID.
12796 (Since 2.12)
12797 format: ImageFormat (optional)
12799 image format for screendump. (default: ppm) (Since 7.1)
12800 Returns
12802 Nothing on success
12803 Since
12805 0.14
12806 Example
12808 -> { "execute": "screendump",
12809 "arguments": { "filename": "/tmp/image" } }
12810 <- { "return": {} }
12811 Spice
12813 SpiceBasicInfo (Object)
12814 The basic information for SPICE network connection
12815 Members
12817 host: string
12818 IP address
12819 port: string
12821 port number
12822 family: NetworkAddressFamily
12824 address family
12825 Since
12827 2.1
12828 If
12830 CONFIG_SPICE
12831 SpiceServerInfo (Object)
12833 Information about a SPICE server
12834 Members
12836 auth: string (optional)
12837 authentication method
12838 The members of SpiceBasicInfo
12840 Since
12842 2.1
12843 If
12845 CONFIG_SPICE
12846 SpiceChannel (Object)
12848 Information about a SPICE client channel.
12849 Members
12851 connection-id: int
12852 SPICE connection id number. All channels with the same id be‐
12853 long to the same SPICE session.
12854 channel-type: int
12856 SPICE channel type number. "1" is the main control channel,
12857 filter for this one if you want to track spice sessions only
12858 channel-id: int
12860 SPICE channel ID number. Usually "0", might be different when
12861 multiple channels of the same type exist, such as multiple dis‐
12862 play channels in a multihead setup
12863 tls: boolean
12865 true if the channel is encrypted, false otherwise.
12866 The members of SpiceBasicInfo
12868 Since
12870 0.14
12871 If
12873 CONFIG_SPICE
12874 SpiceQueryMouseMode (Enum)
12876 An enumeration of Spice mouse states.
12877 Values
12879 client Mouse cursor position is determined by the client.
12880 server Mouse cursor position is determined by the server.
12882 unknown
12884 No information is available about mouse mode used by the spice
12885 server.
12886 Note
12888 spice/enums.h has a SpiceMouseMode already, hence the name.
12889 Since
12891 1.1
12892 If
12894 CONFIG_SPICE
12895 SpiceInfo (Object)
12897 Information about the SPICE session.
12898 Members
12900 enabled: boolean
12901 true if the SPICE server is enabled, false otherwise
12902 migrated: boolean
12904 true if the last guest migration completed and spice migration
12905 had completed as well. false otherwise. (since 1.4)
12906 host: string (optional)
12908 The hostname the SPICE server is bound to. This depends on the
12909 name resolution on the host and may be an IP address.
12910 port: int (optional)
12912 The SPICE server's port number.
12913 compiled-version: string (optional)
12915 SPICE server version.
12916 tls-port: int (optional)
12918 The SPICE server's TLS port number.
12919 auth: string (optional)
12921 the current authentication type used by the server
12922 • 'none' if no authentication is being used
12924 • 'spice' uses SASL or direct TLS authentication, depending on
12926 command line options
12927 mouse-mode: SpiceQueryMouseMode
12929 The mode in which the mouse cursor is displayed currently. Can
12930 be determined by the client or the server, or unknown if spice
12931 server doesn't provide this information. (since: 1.1)
12932 channels: array of SpiceChannel (optional)
12934 a list of SpiceChannel for each active spice channel
12935 Since
12937 0.14
12938 If
12940 CONFIG_SPICE
12941 query-spice (Command)
12943 Returns information about the current SPICE server
12944 Returns
12946 SpiceInfo
12947 Since
12949 0.14
12950 Example
12952 -> { "execute": "query-spice" }
12953 <- { "return": {
12954 "enabled": true,
12955 "auth": "spice",
12956 "port": 5920,
12957 "migrated":false,
12958 "tls-port": 5921,
12959 "host": "0.0.0.0",
12960 "mouse-mode":"client",
12961 "channels": [
12962 {
12963 "port": "54924",
12964 "family": "ipv4",
12965 "channel-type": 1,
12966 "connection-id": 1804289383,
12967 "host": "127.0.0.1",
12968 "channel-id": 0,
12969 "tls": true
12970 },
12971 {
12972 "port": "36710",
12973 "family": "ipv4",
12974 "channel-type": 4,
12975 "connection-id": 1804289383,
12976 "host": "127.0.0.1",
12977 "channel-id": 0,
12978 "tls": false
12979 },
12980 [ ... more channels follow ... ]
12981 ]
12982 }
12983 }
12984 If
12986 CONFIG_SPICE
12987 SPICE_CONNECTED (Event)
12989 Emitted when a SPICE client establishes a connection
12990 Arguments
12992 server: SpiceBasicInfo
12993 server information
12994 client: SpiceBasicInfo
12996 client information
12997 Since
12999 0.14
13000 Example
13002 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
13003 "event": "SPICE_CONNECTED",
13004 "data": {
13005 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
13006 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
13007 }}
13008 If
13010 CONFIG_SPICE
13011 SPICE_INITIALIZED (Event)
13013 Emitted after initial handshake and authentication takes place (if any)
13014 and the SPICE channel is up and running
13015 Arguments
13017 server: SpiceServerInfo
13018 server information
13019 client: SpiceChannel
13021 client information
13022 Since
13024 0.14
13025 Example
13027 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
13028 "event": "SPICE_INITIALIZED",
13029 "data": {"server": {"auth": "spice", "port": "5921",
13030 "family": "ipv4", "host": "127.0.0.1"},
13031 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
13032 "connection-id": 1804289383, "host": "127.0.0.1",
13033 "channel-id": 0, "tls": true}
13034 }}
13035 If
13037 CONFIG_SPICE
13038 SPICE_DISCONNECTED (Event)
13040 Emitted when the SPICE connection is closed
13041 Arguments
13043 server: SpiceBasicInfo
13044 server information
13045 client: SpiceBasicInfo
13047 client information
13048 Since
13050 0.14
13051 Example
13053 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
13054 "event": "SPICE_DISCONNECTED",
13055 "data": {
13056 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
13057 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
13058 }}
13059 If
13061 CONFIG_SPICE
13062 SPICE_MIGRATE_COMPLETED (Event)
13064 Emitted when SPICE migration has completed
13065 Since
13067 1.3
13068 Example
13070 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
13071 "event": "SPICE_MIGRATE_COMPLETED" }
13072 If
13074 CONFIG_SPICE
13075 VNC
13077 VncBasicInfo (Object)
13078 The basic information for vnc network connection
13079 Members
13081 host: string
13082 IP address
13083 service: string
13085 The service name of the vnc port. This may depend on the host
13086 system's service database so symbolic names should not be relied
13087 on.
13088 family: NetworkAddressFamily
13090 address family
13091 websocket: boolean
13093 true in case the socket is a websocket (since 2.3).
13094 Since
13096 2.1
13097 If
13099 CONFIG_VNC
13100 VncServerInfo (Object)
13102 The network connection information for server
13103 Members
13105 auth: string (optional)
13106 authentication method used for the plain (non-websocket) VNC
13107 server
13108 The members of VncBasicInfo
13110 Since
13112 2.1
13113 If
13115 CONFIG_VNC
13116 VncClientInfo (Object)
13118 Information about a connected VNC client.
13119 Members
13121 x509_dname: string (optional)
13122 If x509 authentication is in use, the Distinguished Name of the
13123 client.
13124 sasl_username: string (optional)
13126 If SASL authentication is in use, the SASL username used for au‐
13127 thentication.
13128 The members of VncBasicInfo
13130 Since
13132 0.14
13133 If
13135 CONFIG_VNC
13136 VncInfo (Object)
13138 Information about the VNC session.
13139 Members
13141 enabled: boolean
13142 true if the VNC server is enabled, false otherwise
13143 host: string (optional)
13145 The hostname the VNC server is bound to. This depends on the
13146 name resolution on the host and may be an IP address.
13147 family: NetworkAddressFamily (optional)
13149 • 'ipv6' if the host is listening for IPv6 connections
13151 • 'ipv4' if the host is listening for IPv4 connections
13153 • 'unix' if the host is listening on a unix domain socket
13155 • 'unknown' otherwise
13157 service: string (optional)
13159 The service name of the server's port. This may depends on the
13160 host system's service database so symbolic names should not be
13161 relied on.
13162 auth: string (optional)
13164 the current authentication type used by the server
13165 • 'none' if no authentication is being used
13167 • 'vnc' if VNC authentication is being used
13169 • 'vencrypt+plain' if VEncrypt is used with plain text authenti‐
13171 cation
13172 • 'vencrypt+tls+none' if VEncrypt is used with TLS and no au‐
13174 thentication
13175 • 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC au‐
13177 thentication
13178 • 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain
13180 text auth
13181 • 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
13183 • 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
13185 • 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain
13187 text auth
13188 • 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
13190 • 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
13192 auth
13193 clients: array of VncClientInfo (optional)
13195 a list of VncClientInfo of all currently connected clients
13196 Since
13198 0.14
13199 If
13201 CONFIG_VNC
13202 VncPrimaryAuth (Enum)
13204 vnc primary authentication method.
13205 Values
13207 none Not documented
13208 vnc Not documented
13210 ra2 Not documented
13212 ra2ne Not documented
13214 tight Not documented
13216 ultra Not documented
13218 tls Not documented
13220 vencrypt
13222 Not documented
13223 sasl Not documented
13225 Since
13227 2.3
13228 If
13230 CONFIG_VNC
13231 VncVencryptSubAuth (Enum)
13233 vnc sub authentication method with vencrypt.
13234 Values
13236 plain Not documented
13237 tls-none
13239 Not documented
13240 x509-none
13242 Not documented
13243 tls-vnc
13245 Not documented
13246 x509-vnc
13248 Not documented
13249 tls-plain
13251 Not documented
13252 x509-plain
13254 Not documented
13255 tls-sasl
13257 Not documented
13258 x509-sasl
13260 Not documented
13261 Since
13263 2.3
13264 If
13266 CONFIG_VNC
13267 VncServerInfo2 (Object)
13269 The network connection information for server
13270 Members
13272 auth: VncPrimaryAuth
13273 The current authentication type used by the servers
13274 vencrypt: VncVencryptSubAuth (optional)
13276 The vencrypt sub authentication type used by the servers, only
13277 specified in case auth == vencrypt.
13278 The members of VncBasicInfo
13280 Since
13282 2.9
13283 If
13285 CONFIG_VNC
13286 VncInfo2 (Object)
13288 Information about a vnc server
13289 Members
13291 id: string
13292 vnc server name.
13293 server: array of VncServerInfo2
13295 A list of VncBasincInfo describing all listening sockets. The
13296 list can be empty (in case the vnc server is disabled). It also
13297 may have multiple entries: normal + websocket, possibly also
13298 ipv4 + ipv6 in the future.
13299 clients: array of VncClientInfo
13301 A list of VncClientInfo of all currently connected clients. The
13302 list can be empty, for obvious reasons.
13303 auth: VncPrimaryAuth
13305 The current authentication type used by the non-websockets
13306 servers
13307 vencrypt: VncVencryptSubAuth (optional)
13309 The vencrypt authentication type used by the servers, only spec‐
13310 ified in case auth == vencrypt.
13311 display: string (optional)
13313 The display device the vnc server is linked to.
13314 Since
13316 2.3
13317 If
13319 CONFIG_VNC
13320 query-vnc (Command)
13322 Returns information about the current VNC server
13323 Returns
13325 VncInfo
13326 Since
13328 0.14
13329 Example
13331 -> { "execute": "query-vnc" }
13332 <- { "return": {
13333 "enabled":true,
13334 "host":"0.0.0.0",
13335 "service":"50402",
13336 "auth":"vnc",
13337 "family":"ipv4",
13338 "clients":[
13339 {
13340 "host":"127.0.0.1",
13341 "service":"50401",
13342 "family":"ipv4",
13343 "websocket":false
13344 }
13345 ]
13346 }
13347 }
13348 If
13350 CONFIG_VNC
13351 query-vnc-servers (Command)
13353 Returns a list of vnc servers. The list can be empty.
13354 Returns
13356 a list of VncInfo2
13357 Since
13359 2.3
13360 If
13362 CONFIG_VNC
13363 change-vnc-password (Command)
13365 Change the VNC server password.
13366 Arguments
13368 password: string
13369 the new password to use with VNC authentication
13370 Since
13372 1.1
13373 Notes
13375 An empty password in this command will set the password to the empty
13376 string. Existing clients are unaffected by executing this command.
13377 If
13379 CONFIG_VNC
13380 VNC_CONNECTED (Event)
13382 Emitted when a VNC client establishes a connection
13383 Arguments
13385 server: VncServerInfo
13386 server information
13387 client: VncBasicInfo
13389 client information
13390 Note
13392 This event is emitted before any authentication takes place, thus the
13393 authentication ID is not provided
13394 Since
13396 0.13
13397 Example
13399 <- { "event": "VNC_CONNECTED",
13400 "data": {
13401 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
13402 "service": "5901", "host": "0.0.0.0" },
13403 "client": { "family": "ipv4", "service": "58425",
13404 "host": "127.0.0.1", "websocket": false } },
13405 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
13406 If
13408 CONFIG_VNC
13409 VNC_INITIALIZED (Event)
13411 Emitted after authentication takes place (if any) and the VNC session
13412 is made active
13413 Arguments
13415 server: VncServerInfo
13416 server information
13417 client: VncClientInfo
13419 client information
13420 Since
13422 0.13
13423 Example
13425 <- { "event": "VNC_INITIALIZED",
13426 "data": {
13427 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
13428 "service": "5901", "host": "0.0.0.0"},
13429 "client": { "family": "ipv4", "service": "46089", "websocket": false,
13430 "host": "127.0.0.1", "sasl_username": "luiz" } },
13431 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
13432 If
13434 CONFIG_VNC
13435 VNC_DISCONNECTED (Event)
13437 Emitted when the connection is closed
13438 Arguments
13440 server: VncServerInfo
13441 server information
13442 client: VncClientInfo
13444 client information
13445 Since
13447 0.13
13448 Example
13450 <- { "event": "VNC_DISCONNECTED",
13451 "data": {
13452 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
13453 "service": "5901", "host": "0.0.0.0" },
13454 "client": { "family": "ipv4", "service": "58425", "websocket": false,
13455 "host": "127.0.0.1", "sasl_username": "luiz" } },
13456 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
13457 If
13459 CONFIG_VNC
13460
13462 MouseInfo (Object)
13463 Information about a mouse device.
13464 Members
13466 name: string
13467 the name of the mouse device
13468 index: int
13470 the index of the mouse device
13471 current: boolean
13473 true if this device is currently receiving mouse events
13474 absolute: boolean
13476 true if this device supports absolute coordinates as input
13477 Since
13479 0.14
13480 query-mice (Command)
13482 Returns information about each active mouse device
13483 Returns
13485 a list of MouseInfo for each device
13486 Since
13488 0.14
13489 Example
13491 -> { "execute": "query-mice" }
13492 <- { "return": [
13493 {
13494 "name":"QEMU Microsoft Mouse",
13495 "index":0,
13496 "current":false,
13497 "absolute":false
13498 },
13499 {
13500 "name":"QEMU PS/2 Mouse",
13501 "index":1,
13502 "current":true,
13503 "absolute":true
13504 }
13505 ]
13506 }
13507 QKeyCode (Enum)
13509 An enumeration of key name.
13510 This is used by the send-key command.
13512 Values
13514 unmapped
13515 since 2.0
13516 pause since 2.0
13518 ro since 2.4
13520 kp_comma
13522 since 2.4
13523 kp_equals
13525 since 2.6
13526 power since 2.6
13528 hiragana
13530 since 2.9
13531 henkan since 2.9
13533 yen since 2.9
13535 sleep since 2.10
13537 wake since 2.10
13539 audionext
13541 since 2.10
13542 audioprev
13544 since 2.10
13545 audiostop
13547 since 2.10
13548 audioplay
13550 since 2.10
13551 audiomute
13553 since 2.10
13554 volumeup
13556 since 2.10
13557 volumedown
13559 since 2.10
13560 mediaselect
13562 since 2.10
13563 mail since 2.10
13565 calculator
13567 since 2.10
13568 computer
13570 since 2.10
13571 ac_home
13573 since 2.10
13574 ac_back
13576 since 2.10
13577 ac_forward
13579 since 2.10
13580 ac_refresh
13582 since 2.10
13583 ac_bookmarks
13585 since 2.10
13586 muhenkan
13588 since 2.12
13589 katakanahiragana
13591 since 2.12
13592 lang1 since 6.1
13594 lang2 since 6.1
13596 f13 since 8.0
13598 f14 since 8.0
13600 f15 since 8.0
13602 f16 since 8.0
13604 f17 since 8.0
13606 f18 since 8.0
13608 f19 since 8.0
13610 f20 since 8.0
13612 f21 since 8.0
13614 f22 since 8.0
13616 f23 since 8.0
13618 f24 since 8.0
13620 shift Not documented
13622 shift_r
13624 Not documented
13625 alt Not documented
13627 alt_r Not documented
13629 ctrl Not documented
13631 ctrl_r Not documented
13633 menu Not documented
13635 esc Not documented
13637 1 Not documented
13639 2 Not documented
13641 3 Not documented
13643 4 Not documented
13645 5 Not documented
13647 6 Not documented
13649 7 Not documented
13651 8 Not documented
13653 9 Not documented
13655 0 Not documented
13657 minus Not documented
13659 equal Not documented
13661 backspace
13663 Not documented
13664 tab Not documented
13666 q Not documented
13668 w Not documented
13670 e Not documented
13672 r Not documented
13674 t Not documented
13676 y Not documented
13678 u Not documented
13680 i Not documented
13682 o Not documented
13684 p Not documented
13686 bracket_left
13688 Not documented
13689 bracket_right
13691 Not documented
13692 ret Not documented
13694 a Not documented
13696 s Not documented
13698 d Not documented
13700 f Not documented
13702 g Not documented
13704 h Not documented
13706 j Not documented
13708 k Not documented
13710 l Not documented
13712 semicolon
13714 Not documented
13715 apostrophe
13717 Not documented
13718 grave_accent
13720 Not documented
13721 backslash
13723 Not documented
13724 z Not documented
13726 x Not documented
13728 c Not documented
13730 v Not documented
13732 b Not documented
13734 n Not documented
13736 m Not documented
13738 comma Not documented
13740 dot Not documented
13742 slash Not documented
13744 asterisk
13746 Not documented
13747 spc Not documented
13749 caps_lock
13751 Not documented
13752 f1 Not documented
13754 f2 Not documented
13756 f3 Not documented
13758 f4 Not documented
13760 f5 Not documented
13762 f6 Not documented
13764 f7 Not documented
13766 f8 Not documented
13768 f9 Not documented
13770 f10 Not documented
13772 num_lock
13774 Not documented
13775 scroll_lock
13777 Not documented
13778 kp_divide
13780 Not documented
13781 kp_multiply
13783 Not documented
13784 kp_subtract
13786 Not documented
13787 kp_add Not documented
13789 kp_enter
13791 Not documented
13792 kp_decimal
13794 Not documented
13795 sysrq Not documented
13797 kp_0 Not documented
13799 kp_1 Not documented
13801 kp_2 Not documented
13803 kp_3 Not documented
13805 kp_4 Not documented
13807 kp_5 Not documented
13809 kp_6 Not documented
13811 kp_7 Not documented
13813 kp_8 Not documented
13815 kp_9 Not documented
13817 less Not documented
13819 f11 Not documented
13821 f12 Not documented
13823 print Not documented
13825 home Not documented
13827 pgup Not documented
13829 pgdn Not documented
13831 end Not documented
13833 left Not documented
13835 up Not documented
13837 down Not documented
13839 right Not documented
13841 insert Not documented
13843 delete Not documented
13845 stop Not documented
13847 again Not documented
13849 props Not documented
13851 undo Not documented
13853 front Not documented
13855 copy Not documented
13857 open Not documented
13859 paste Not documented
13861 find Not documented
13863 cut Not documented
13865 lf Not documented
13867 help Not documented
13869 meta_l Not documented
13871 meta_r Not documented
13873 compose
13875 Not documented
13876 'sysrq' was mistakenly added to hack around the fact that the ps2
13877 driver was not generating correct scancodes sequences when 'alt+print'
13878 was pressed. This flaw is now fixed and the 'sysrq' key serves no fur‐
13879 ther purpose. Any further use of 'sysrq' will be transparently changed
13880 to 'print', so they are effectively synonyms.
13881 Since
13883 1.3
13884 KeyValueKind (Enum)
13886 Values
13887 number Not documented
13888 qcode Not documented
13890 Since
13892 1.3
13893 IntWrapper (Object)
13895 Members
13896 data: int
13897 Not documented
13898 Since
13900 1.3
13901 QKeyCodeWrapper (Object)
13903 Members
13904 data: QKeyCode
13905 Not documented
13906 Since
13908 1.3
13909 KeyValue (Object)
13911 Represents a keyboard key.
13912 Members
13914 type: KeyValueKind
13915 Not documented
13916 The members of IntWrapper when type is "number"
13918 The members of QKeyCodeWrapper when type is "qcode"
13920 Since
13922 1.3
13923 send-key (Command)
13925 Send keys to guest.
13926 Arguments
13928 keys: array of KeyValue
13929 An array of KeyValue elements. All KeyValues in this array are
13930 simultaneously sent to the guest. A KeyValue.number value is
13931 sent directly to the guest, while KeyValue.qcode must be a valid
13932 QKeyCode value
13933 hold-time: int (optional)
13935 time to delay key up events, milliseconds. Defaults to 100
13936 Returns
13938 • Nothing on success
13939 • If key is unknown or redundant, GenericError
13941 Since
13943 1.3
13944 Example
13946 -> { "execute": "send-key",
13947 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
13948 { "type": "qcode", "data": "alt" },
13949 { "type": "qcode", "data": "delete" } ] } }
13950 <- { "return": {} }
13951 InputButton (Enum)
13953 Button of a pointer input device (mouse, tablet).
13954 Values
13956 side front side button of a 5-button mouse (since 2.9)
13957 extra rear side button of a 5-button mouse (since 2.9)
13959 touch screen contact on a multi-touch device (since 8.1)
13961 left Not documented
13963 middle Not documented
13965 right Not documented
13967 wheel-up
13969 Not documented
13970 wheel-down
13972 Not documented
13973 wheel-left
13975 Not documented
13976 wheel-right
13978 Not documented
13979 Since
13981 2.0
13982 InputAxis (Enum)
13984 Position axis of a pointer input device (mouse, tablet).
13985 Values
13987 x Not documented
13988 y Not documented
13990 Since
13992 2.0
13993 InputMultiTouchType (Enum)
13995 Type of a multi-touch event.
13996 Values
13998 begin Not documented
13999 update Not documented
14001 end Not documented
14003 cancel Not documented
14005 data Not documented
14007 Since
14009 8.1
14010 InputKeyEvent (Object)
14012 Keyboard input event.
14013 Members
14015 key: KeyValue
14016 Which key this event is for.
14017 down: boolean
14019 True for key-down and false for key-up events.
14020 Since
14022 2.0
14023 InputBtnEvent (Object)
14025 Pointer button input event.
14026 Members
14028 button: InputButton
14029 Which button this event is for.
14030 down: boolean
14032 True for key-down and false for key-up events.
14033 Since
14035 2.0
14036 InputMoveEvent (Object)
14038 Pointer motion input event.
14039 Members
14041 axis: InputAxis
14042 Which axis is referenced by value.
14043 value: int
14045 Pointer position. For absolute coordinates the valid range is 0
14046 -> 0x7ffff
14047 Since
14049 2.0
14050 InputMultiTouchEvent (Object)
14052 MultiTouch input event.
14053 Members
14055 slot: int
14056 Which slot has generated the event.
14057 tracking-id: int
14059 ID to correlate this event with previously generated events.
14060 axis: InputAxis
14062 Which axis is referenced by value.
14063 value: int
14065 Contact position.
14066 type: InputMultiTouchType
14068 Not documented
14069 Since
14071 8.1
14072 InputEventKind (Enum)
14074 Values
14075 key a keyboard input event
14076 btn a pointer button input event
14078 rel a relative pointer motion input event
14080 abs an absolute pointer motion input event
14082 mtt a multi-touch input event
14084 Since
14086 2.0
14087 InputKeyEventWrapper (Object)
14089 Members
14090 data: InputKeyEvent
14091 Not documented
14092 Since
14094 2.0
14095 InputBtnEventWrapper (Object)
14097 Members
14098 data: InputBtnEvent
14099 Not documented
14100 Since
14102 2.0
14103 InputMoveEventWrapper (Object)
14105 Members
14106 data: InputMoveEvent
14107 Not documented
14108 Since
14110 2.0
14111 InputMultiTouchEventWrapper (Object)
14113 Members
14114 data: InputMultiTouchEvent
14115 Not documented
14116 Since
14118 8.1
14119 InputEvent (Object)
14121 Input event union.
14122 Members
14124 type: InputEventKind
14125 the type of input event
14126 The members of InputKeyEventWrapper when type is "key"
14128 The members of InputBtnEventWrapper when type is "btn"
14130 The members of InputMoveEventWrapper when type is "rel"
14132 The members of InputMoveEventWrapper when type is "abs"
14134 The members of InputMultiTouchEventWrapper when type is "mtt"
14136 Since
14138 2.0
14139 input-send-event (Command)
14141 Send input event(s) to guest.
14142 The device and head parameters can be used to send the input event to
14144 specific input devices in case (a) multiple input devices of the same
14145 kind are added to the virtual machine and (b) you have configured input
14146 routing (see docs/multiseat.txt) for those input devices. The parame‐
14147 ters work exactly like the device and head properties of input devices.
14148 If device is missing, only devices that have no input routing config
14149 are admissible. If device is specified, both input devices with and
14150 without input routing config are admissible, but devices with input
14151 routing config take precedence.
14152 Arguments
14154 device: string (optional)
14155 display device to send event(s) to.
14156 head: int (optional)
14158 head to send event(s) to, in case the display device supports
14159 multiple scanouts.
14160 events: array of InputEvent
14162 List of InputEvent union.
14163 Returns
14165 Nothing on success.
14166 Since
14168 2.6
14169 Note
14171 The consoles are visible in the qom tree, under /backend/console[$in‐
14172 dex]. They have a device link and head property, so it is possible to
14173 map which console belongs to which device and display.
14174 Examples
14176 1. Press left mouse button.
14177 -> { "execute": "input-send-event",
14179 "arguments": { "device": "video0",
14180 "events": [ { "type": "btn",
14181 "data" : { "down": true, "button": "left" } } ] } }
14182 <- { "return": {} }
14183 -> { "execute": "input-send-event",
14185 "arguments": { "device": "video0",
14186 "events": [ { "type": "btn",
14187 "data" : { "down": false, "button": "left" } } ] } }
14188 <- { "return": {} }
14189 2. Press ctrl-alt-del.
14191 -> { "execute": "input-send-event",
14193 "arguments": { "events": [
14194 { "type": "key", "data" : { "down": true,
14195 "key": {"type": "qcode", "data": "ctrl" } } },
14196 { "type": "key", "data" : { "down": true,
14197 "key": {"type": "qcode", "data": "alt" } } },
14198 { "type": "key", "data" : { "down": true,
14199 "key": {"type": "qcode", "data": "delete" } } } ] } }
14200 <- { "return": {} }
14201 3. Move mouse pointer to absolute coordinates (20000, 400).
14203 -> { "execute": "input-send-event" ,
14205 "arguments": { "events": [
14206 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
14207 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
14208 <- { "return": {} }
14209 DisplayGTK (Object)
14211 GTK display options.
14212 Members
14214 grab-on-hover: boolean (optional)
14215 Grab keyboard input on mouse hover.
14216 zoom-to-fit: boolean (optional)
14218 Zoom guest display to fit into the host window. When turned off
14219 the host window will be resized instead. In case the display
14220 device can notify the guest on window resizes (virtio-gpu) this
14221 will default to "on", assuming the guest will resize the display
14222 to match the window size then. Otherwise it defaults to "off".
14223 (Since 3.1)
14224 show-tabs: boolean (optional)
14226 Display the tab bar for switching between the various graphical
14227 interfaces (e.g. VGA and virtual console character devices) by
14228 default. (Since 7.1)
14229 show-menubar: boolean (optional)
14231 Display the main window menubar. Defaults to "on". (Since 8.0)
14232 Since
14234 2.12
14235 DisplayEGLHeadless (Object)
14237 EGL headless display options.
14238 Members
14240 rendernode: string (optional)
14241 Which DRM render node should be used. Default is the first
14242 available node on the host.
14243 Since
14245 3.1
14246 DisplayDBus (Object)
14248 DBus display options.
14249 Members
14251 addr: string (optional)
14252 The D-Bus bus address (default to the session bus).
14253 rendernode: string (optional)
14255 Which DRM render node should be used. Default is the first
14256 available node on the host.
14257 p2p: boolean (optional)
14259 Whether to use peer-to-peer connections (accepted through
14260 add_client).
14261 audiodev: string (optional)
14263 Use the specified DBus audiodev to export audio.
14264 Since
14266 7.0
14267 DisplayGLMode (Enum)
14269 Display OpenGL mode.
14270 Values
14272 off Disable OpenGL (default).
14273 on Use OpenGL, pick context type automatically. Would better be
14275 named 'auto' but is called 'on' for backward compatibility with
14276 bool type.
14277 core Use OpenGL with Core (desktop) Context.
14279 es Use OpenGL with ES (embedded systems) Context.
14281 Since
14283 3.0
14284 DisplayCurses (Object)
14286 Curses display options.
14287 Members
14289 charset: string (optional)
14290 Font charset used by guest (default: CP437).
14291 Since
14293 4.0
14294 DisplayCocoa (Object)
14296 Cocoa display options.
14297 Members
14299 left-command-key: boolean (optional)
14300 Enable/disable forwarding of left command key to guest. Allows
14301 command-tab window switching on the host without sending this
14302 key to the guest when "off". Defaults to "on"
14303 full-grab: boolean (optional)
14305 Capture all key presses, including system combos. This requires
14306 accessibility permissions, since it performs a global grab on
14307 key events. (default: off) See
14308 https://support.apple.com/en-in/guide/mac-help/mh32356/mac
14309 swap-opt-cmd: boolean (optional)
14311 Swap the Option and Command keys so that their key codes match
14312 their position on non-Mac keyboards and you can use Meta/Super
14313 and Alt where you expect them. (default: off)
14314 Since
14316 7.0
14317 HotKeyMod (Enum)
14319 Set of modifier keys that need to be held for shortcut key actions.
14320 Values
14322 lctrl-lalt
14323 Not documented
14324 lshift-lctrl-lalt
14326 Not documented
14327 rctrl Not documented
14329 Since
14331 7.1
14332 DisplaySDL (Object)
14334 SDL2 display options.
14335 Members
14337 grab-mod: HotKeyMod (optional)
14338 Modifier keys that should be pressed together with the "G" key
14339 to release the mouse grab.
14340 Since
14342 7.1
14343 DisplayType (Enum)
14345 Display (user interface) type.
14346 Values
14348 default
14349 The default user interface, selecting from the first available
14350 of gtk, sdl, cocoa, and vnc.
14351 none No user interface or video output display. The guest will still
14353 see an emulated graphics card, but its output will not be dis‐
14354 played to the QEMU user.
14355 gtk (If: CONFIG_GTK)
14357 The GTK user interface.
14358 sdl (If: CONFIG_SDL)
14360 The SDL user interface.
14361 egl-headless (If: CONFIG_OPENGL)
14363 No user interface, offload GL operations to a local DRI device.
14364 Graphical display need to be paired with VNC or Spice. (Since
14365 3.1)
14366 curses (If: CONFIG_CURSES)
14368 Display video output via curses. For graphics device models
14369 which support a text mode, QEMU can display this output using a
14370 curses/ncurses interface. Nothing is displayed when the graph‐
14371 ics device is in graphical mode or if the graphics device does
14372 not support a text mode. Generally only the VGA device models
14373 support text mode.
14374 cocoa (If: CONFIG_COCOA)
14376 The Cocoa user interface.
14377 spice-app (If: CONFIG_SPICE)
14379 Set up a Spice server and run the default associated application
14380 to connect to it. The server will redirect the serial console
14381 and QEMU monitors. (Since 4.0)
14382 dbus (If: CONFIG_DBUS_DISPLAY)
14384 Start a D-Bus service for the display. (Since 7.0)
14385 Since
14387 2.12
14388 DisplayOptions (Object)
14390 Display (user interface) options.
14391 Members
14393 type: DisplayType
14394 Which DisplayType qemu should use.
14395 full-screen: boolean (optional)
14397 Start user interface in fullscreen mode (default: off).
14398 window-close: boolean (optional)
14400 Allow to quit qemu with window close button (default: on).
14401 show-cursor: boolean (optional)
14403 Force showing the mouse cursor (default: off). (since: 5.0)
14404 gl: DisplayGLMode (optional)
14406 Enable OpenGL support (default: off).
14407 The members of DisplayGTK when type is "gtk" (If: CONFIG_GTK)
14409 The members of DisplayCocoa when type is "cocoa" (If: CONFIG_COCOA)
14411 The members of DisplayCurses when type is "curses" (If: CONFIG_CURSES)
14413 The members of DisplayEGLHeadless when type is "egl-headless" (If: CON‐
14415 FIG_OPENGL)
14416 The members of DisplayDBus when type is "dbus" (If: CONFIG_DBUS_DIS‐
14418 PLAY)
14419 The members of DisplaySDL when type is "sdl" (If: CONFIG_SDL)
14421 Since
14423 2.12
14424 query-display-options (Command)
14426 Returns information about display configuration
14427 Returns
14429 DisplayOptions
14430 Since
14432 3.1
14433 DisplayReloadType (Enum)
14435 Available DisplayReload types.
14436 Values
14438 vnc VNC display
14439 Since
14441 6.0
14442 DisplayReloadOptionsVNC (Object)
14444 Specify the VNC reload options.
14445 Members
14447 tls-certs: boolean (optional)
14448 reload tls certs or not.
14449 Since
14451 6.0
14452 DisplayReloadOptions (Object)
14454 Options of the display configuration reload.
14455 Members
14457 type: DisplayReloadType
14458 Specify the display type.
14459 The members of DisplayReloadOptionsVNC when type is "vnc"
14461 Since
14463 6.0
14464 display-reload (Command)
14466 Reload display configuration.
14467 Arguments
14469 The members of DisplayReloadOptions
14470 Returns
14472 Nothing on success.
14473 Since
14475 6.0
14476 Example
14478 -> { "execute": "display-reload",
14479 "arguments": { "type": "vnc", "tls-certs": true } }
14480 <- { "return": {} }
14481 DisplayUpdateType (Enum)
14483 Available DisplayUpdate types.
14484 Values
14486 vnc VNC display
14487 Since
14489 7.1
14490 DisplayUpdateOptionsVNC (Object)
14492 Specify the VNC reload options.
14493 Members
14495 addresses: array of SocketAddress (optional)
14496 If specified, change set of addresses to listen for connections.
14497 Addresses configured for websockets are not touched.
14498 Since
14500 7.1
14501 DisplayUpdateOptions (Object)
14503 Options of the display configuration reload.
14504 Members
14506 type: DisplayUpdateType
14507 Specify the display type.
14508 The members of DisplayUpdateOptionsVNC when type is "vnc"
14510 Since
14512 7.1
14513 display-update (Command)
14515 Update display configuration.
14516 Arguments
14518 The members of DisplayUpdateOptions
14519 Returns
14521 Nothing on success.
14522 Since
14524 7.1
14525 Example
14527 -> { "execute": "display-update",
14528 "arguments": { "type": "vnc", "addresses":
14529 [ { "type": "inet", "host": "0.0.0.0",
14530 "port": "5901" } ] } }
14531 <- { "return": {} }
14532 client_migrate_info (Command)
14534 Set migration information for remote display. This makes the server
14535 ask the client to automatically reconnect using the new parameters once
14536 migration finished successfully. Only implemented for SPICE.
14537 Arguments
14539 protocol: string
14540 must be "spice"
14541 hostname: string
14543 migration target hostname
14544 port: int (optional)
14546 spice tcp port for plaintext channels
14547 tls-port: int (optional)
14549 spice tcp port for tls-secured channels
14550 cert-subject: string (optional)
14552 server certificate subject
14553 Since
14555 0.14
14556 Example
14558 -> { "execute": "client_migrate_info",
14559 "arguments": { "protocol": "spice",
14560 "hostname": "virt42.lab.kraxel.org",
14561 "port": 1234 } }
14562 <- { "return": {} }
14563
14565 QAuthZListPolicy (Enum)
14566 The authorization policy result
14567 Values
14569 deny deny access
14570 allow allow access
14572 Since
14574 4.0
14575 QAuthZListFormat (Enum)
14577 The authorization policy match format
14578 Values
14580 exact an exact string match
14581 glob string with ? and * shell wildcard support
14583 Since
14585 4.0
14586 QAuthZListRule (Object)
14588 A single authorization rule.
14589 Members
14591 match: string
14592 a string or glob to match against a user identity
14593 policy: QAuthZListPolicy
14595 the result to return if match evaluates to true
14596 format: QAuthZListFormat (optional)
14598 the format of the match rule (default 'exact')
14599 Since
14601 4.0
14602 AuthZListProperties (Object)
14604 Properties for authz-list objects.
14605 Members
14607 policy: QAuthZListPolicy (optional)
14608 Default policy to apply when no rule matches (default: deny)
14609 rules: array of QAuthZListRule (optional)
14611 Authorization rules based on matching user
14612 Since
14614 4.0
14615 AuthZListFileProperties (Object)
14617 Properties for authz-listfile objects.
14618 Members
14620 filename: string
14621 File name to load the configuration from. The file must contain
14622 valid JSON for AuthZListProperties.
14623 refresh: boolean (optional)
14625 If true, inotify is used to monitor the file, automatically
14626 reloading changes. If an error occurs during reloading, all au‐
14627 thorizations will fail until the file is next successfully
14628 loaded. (default: true if the binary was built with CONFIG_INO‐
14629 TIFY1, false otherwise)
14630 Since
14632 4.0
14633 AuthZPAMProperties (Object)
14635 Properties for authz-pam objects.
14636 Members
14638 service: string
14639 PAM service name to use for authorization
14640 Since
14642 4.0
14643 AuthZSimpleProperties (Object)
14645 Properties for authz-simple objects.
14646 Members
14648 identity: string
14649 Identifies the allowed user. Its format depends on the network
14650 service that authorization object is associated with. For au‐
14651 thorizing based on TLS x509 certificates, the identity must be
14652 the x509 distinguished name.
14653 Since
14655 4.0
14656
14658 MigrationStats (Object)
14659 Detailed migration status.
14660 Members
14662 transferred: int
14663 amount of bytes already transferred to the target VM
14664 remaining: int
14666 amount of bytes remaining to be transferred to the target VM
14667 total: int
14669 total amount of bytes involved in the migration process
14670 duplicate: int
14672 number of duplicate (zero) pages (since 1.2)
14673 skipped: int
14675 number of skipped zero pages. Always zero, only provided for
14676 compatibility (since 1.5)
14677 normal: int
14679 number of normal pages (since 1.2)
14680 normal-bytes: int
14682 number of normal bytes sent (since 1.2)
14683 dirty-pages-rate: int
14685 number of pages dirtied by second by the guest (since 1.3)
14686 mbps: number
14688 throughput in megabits/sec. (since 1.6)
14689 dirty-sync-count: int
14691 number of times that dirty ram was synchronized (since 2.1)
14692 postcopy-requests: int
14694 The number of page requests received from the destination (since
14695 2.7)
14696 page-size: int
14698 The number of bytes per page for the various page-based statis‐
14699 tics (since 2.10)
14700 multifd-bytes: int
14702 The number of bytes sent through multifd (since 3.0)
14703 pages-per-second: int
14705 the number of memory pages transferred per second (Since 4.0)
14706 precopy-bytes: int
14708 The number of bytes sent in the pre-copy phase (since 7.0).
14709 downtime-bytes: int
14711 The number of bytes sent while the guest is paused (since 7.0).
14712 postcopy-bytes: int
14714 The number of bytes sent during the post-copy phase (since 7.0).
14715 dirty-sync-missed-zero-copy: int
14717 Number of times dirty RAM synchronization could not avoid copy‐
14718 ing dirty pages. This is between 0 and dirty-sync-count * mul‐
14719 tifd-channels. (since 7.1)
14720 Features
14722 deprecated
14723 Member skipped is always zero since 1.5.3
14724 Since
14726 0.14
14727 XBZRLECacheStats (Object)
14729 Detailed XBZRLE migration cache statistics
14730 Members
14732 cache-size: int
14733 XBZRLE cache size
14734 bytes: int
14736 amount of bytes already transferred to the target VM
14737 pages: int
14739 amount of pages transferred to the target VM
14740 cache-miss: int
14742 number of cache miss
14743 cache-miss-rate: number
14745 rate of cache miss (since 2.1)
14746 encoding-rate: number
14748 rate of encoded bytes (since 5.1)
14749 overflow: int
14751 number of overflows
14752 Since
14754 1.2
14755 CompressionStats (Object)
14757 Detailed migration compression statistics
14758 Members
14760 pages: int
14761 amount of pages compressed and transferred to the target VM
14762 busy: int
14764 count of times that no free thread was available to compress
14765 data
14766 busy-rate: number
14768 rate of thread busy
14769 compressed-size: int
14771 amount of bytes after compression
14772 compression-rate: number
14774 rate of compressed size
14775 Since
14777 3.1
14778 MigrationStatus (Enum)
14780 An enumeration of migration status.
14781 Values
14783 none no migration has ever happened.
14784 setup migration process has been initiated.
14786 cancelling
14788 in the process of cancelling migration.
14789 cancelled
14791 cancelling migration is finished.
14792 active in the process of doing migration.
14794 postcopy-active
14796 like active, but now in postcopy mode. (since 2.5)
14797 postcopy-paused
14799 during postcopy but paused. (since 3.0)
14800 postcopy-recover
14802 trying to recover from a paused postcopy. (since 3.0)
14803 completed
14805 migration is finished.
14806 failed some error occurred during migration process.
14808 colo VM is in the process of fault tolerance, VM can not get into
14810 this state unless colo capability is enabled for migration.
14811 (since 2.8)
14812 pre-switchover
14814 Paused before device serialisation. (since 2.11)
14815 device During device serialisation when pause-before-switchover is en‐
14817 abled (since 2.11)
14818 wait-unplug
14820 wait for device unplug request by guest OS to be completed.
14821 (since 4.2)
14822 Since
14824 2.3
14825 VfioStats (Object)
14827 Detailed VFIO devices migration statistics
14828 Members
14830 transferred: int
14831 amount of bytes transferred to the target VM by VFIO devices
14832 Since
14834 5.2
14835 MigrationInfo (Object)
14837 Information about current migration process.
14838 Members
14840 status: MigrationStatus (optional)
14841 MigrationStatus describing the current migration status. If
14842 this field is not returned, no migration process has been initi‐
14843 ated
14844 ram: MigrationStats (optional)
14846 MigrationStats containing detailed migration status, only re‐
14847 turned if status is 'active' or 'completed'(since 1.2)
14848 disk: MigrationStats (optional)
14850 MigrationStats containing detailed disk migration status, only
14851 returned if status is 'active' and it is a block migration
14852 xbzrle-cache: XBZRLECacheStats (optional)
14854 XBZRLECacheStats containing detailed XBZRLE migration statis‐
14855 tics, only returned if XBZRLE feature is on and status is 'ac‐
14856 tive' or 'completed' (since 1.2)
14857 total-time: int (optional)
14859 total amount of milliseconds since migration started. If migra‐
14860 tion has ended, it returns the total migration time. (since
14861 1.2)
14862 downtime: int (optional)
14864 only present when migration finishes correctly total downtime in
14865 milliseconds for the guest. (since 1.3)
14866 expected-downtime: int (optional)
14868 only present while migration is active expected downtime in mil‐
14869 liseconds for the guest in last walk of the dirty bitmap.
14870 (since 1.3)
14871 setup-time: int (optional)
14873 amount of setup time in milliseconds before the iterations begin
14874 but after the QMP command is issued. This is designed to pro‐
14875 vide an accounting of any activities (such as RDMA pinning)
14876 which may be expensive, but do not actually occur during the it‐
14877 erative migration rounds themselves. (since 1.6)
14878 cpu-throttle-percentage: int (optional)
14880 percentage of time guest cpus are being throttled during
14881 auto-converge. This is only present when auto-converge has
14882 started throttling guest cpus. (Since 2.7)
14883 error-desc: string (optional)
14885 the human readable error description string, when status is
14886 'failed'. Clients should not attempt to parse the error strings.
14887 (Since 2.7)
14888 postcopy-blocktime: int (optional)
14890 total time when all vCPU were blocked during postcopy live mi‐
14891 gration. This is only present when the postcopy-blocktime mi‐
14892 gration capability is enabled. (Since 3.0)
14893 postcopy-vcpu-blocktime: array of int (optional)
14895 list of the postcopy blocktime per vCPU. This is only present
14896 when the postcopy-blocktime migration capability is enabled.
14897 (Since 3.0)
14898 compression: CompressionStats (optional)
14900 migration compression statistics, only returned if compression
14901 feature is on and status is 'active' or 'completed' (Since 3.1)
14902 socket-address: array of SocketAddress (optional)
14904 Only used for tcp, to know what the real port is (Since 4.0)
14905 vfio: VfioStats (optional)
14907 VfioStats containing detailed VFIO devices migration statistics,
14908 only returned if VFIO device is present, migration is supported
14909 by all VFIO devices and status is 'active' or 'completed' (since
14910 5.2)
14911 blocked-reasons: array of string (optional)
14913 A list of reasons an outgoing migration is blocked. Present and
14914 non-empty when migration is blocked. (since 6.0)
14915 dirty-limit-throttle-time-per-round: int (optional)
14917 Maximum throttle time (in microseconds) of virtual CPUs each
14918 dirty ring full round, which shows how MigrationCapability
14919 dirty-limit affects the guest during live migration. (Since
14920 8.1)
14921 dirty-limit-ring-full-time: int (optional)
14923 Estimated average dirty ring full time (in microseconds) for
14924 each dirty ring full round. The value equals the dirty ring
14925 memory size divided by the average dirty page rate of the vir‐
14926 tual CPU, which can be used to observe the average memory load
14927 of the virtual CPU indirectly. Note that zero means guest
14928 doesn't dirty memory. (Since 8.1)
14929 Since
14931 0.14
14932 query-migrate (Command)
14934 Returns information about current migration process. If migration is
14935 active there will be another json-object with RAM migration status and
14936 if block migration is active another one with block migration status.
14937 Returns
14939 MigrationInfo
14940 Since
14942 0.14
14943 Examples
14945 1. Before the first migration
14946 -> { "execute": "query-migrate" }
14948 <- { "return": {} }
14949 2. Migration is done and has succeeded
14951 -> { "execute": "query-migrate" }
14953 <- { "return": {
14954 "status": "completed",
14955 "total-time":12345,
14956 "setup-time":12345,
14957 "downtime":12345,
14958 "ram":{
14959 "transferred":123,
14960 "remaining":123,
14961 "total":246,
14962 "duplicate":123,
14963 "normal":123,
14964 "normal-bytes":123456,
14965 "dirty-sync-count":15
14966 }
14967 }
14968 }
14969 3. Migration is done and has failed
14971 -> { "execute": "query-migrate" }
14973 <- { "return": { "status": "failed" } }
14974 4. Migration is being performed and is not a block migration:
14976 -> { "execute": "query-migrate" }
14978 <- {
14979 "return":{
14980 "status":"active",
14981 "total-time":12345,
14982 "setup-time":12345,
14983 "expected-downtime":12345,
14984 "ram":{
14985 "transferred":123,
14986 "remaining":123,
14987 "total":246,
14988 "duplicate":123,
14989 "normal":123,
14990 "normal-bytes":123456,
14991 "dirty-sync-count":15
14992 }
14993 }
14994 }
14995 5. Migration is being performed and is a block migration:
14997 -> { "execute": "query-migrate" }
14999 <- {
15000 "return":{
15001 "status":"active",
15002 "total-time":12345,
15003 "setup-time":12345,
15004 "expected-downtime":12345,
15005 "ram":{
15006 "total":1057024,
15007 "remaining":1053304,
15008 "transferred":3720,
15009 "duplicate":123,
15010 "normal":123,
15011 "normal-bytes":123456,
15012 "dirty-sync-count":15
15013 },
15014 "disk":{
15015 "total":20971520,
15016 "remaining":20880384,
15017 "transferred":91136
15018 }
15019 }
15020 }
15021 6. Migration is being performed and XBZRLE is active:
15023 -> { "execute": "query-migrate" }
15025 <- {
15026 "return":{
15027 "status":"active",
15028 "total-time":12345,
15029 "setup-time":12345,
15030 "expected-downtime":12345,
15031 "ram":{
15032 "total":1057024,
15033 "remaining":1053304,
15034 "transferred":3720,
15035 "duplicate":10,
15036 "normal":3333,
15037 "normal-bytes":3412992,
15038 "dirty-sync-count":15
15039 },
15040 "xbzrle-cache":{
15041 "cache-size":67108864,
15042 "bytes":20971520,
15043 "pages":2444343,
15044 "cache-miss":2244,
15045 "cache-miss-rate":0.123,
15046 "encoding-rate":80.1,
15047 "overflow":34434
15048 }
15049 }
15050 }
15051 MigrationCapability (Enum)
15053 Migration capabilities enumeration
15054 Values
15056 xbzrle Migration supports xbzrle (Xor Based Zero Run Length Encoding).
15057 This feature allows us to minimize migration traffic for certain
15058 work loads, by sending compressed difference of the pages
15059 rdma-pin-all
15061 Controls whether or not the entire VM memory footprint is
15062 mlock()'d on demand or all at once. Refer to docs/rdma.txt for
15063 usage. Disabled by default. (since 2.0)
15064 zero-blocks
15066 During storage migration encode blocks of zeroes efficiently.
15067 This essentially saves 1MB of zeroes per block on the wire. En‐
15068 abling requires source and target VM to support this feature.
15069 To enable it is sufficient to enable the capability on the
15070 source VM. The feature is disabled by default. (since 1.6)
15071 compress
15073 Use multiple compression threads to accelerate live migration.
15074 This feature can help to reduce the migration traffic, by send‐
15075 ing compressed pages. Please note that if compress and xbzrle
15076 are both on, compress only takes effect in the ram bulk stage,
15077 after that, it will be disabled and only xbzrle takes effect,
15078 this can help to minimize migration traffic. The feature is
15079 disabled by default. (since 2.4 )
15080 events generate events for each migration state change (since 2.4 )
15082 auto-converge
15084 If enabled, QEMU will automatically throttle down the guest to
15085 speed up convergence of RAM migration. (since 1.6)
15086 postcopy-ram
15088 Start executing on the migration target before all of RAM has
15089 been migrated, pulling the remaining pages along as needed. The
15090 capacity must have the same setting on both source and target or
15091 migration will not even start. NOTE: If the migration fails
15092 during postcopy the VM will fail. (since 2.6)
15093 x-colo If enabled, migration will never end, and the state of the VM on
15095 the primary side will be migrated continuously to the VM on sec‐
15096 ondary side, this process is called COarse-Grain LOck Stepping
15097 (COLO) for Non-stop Service. (since 2.8)
15098 release-ram
15100 if enabled, qemu will free the migrated ram pages on the source
15101 during postcopy-ram migration. (since 2.9)
15102 block If enabled, QEMU will also migrate the contents of all block de‐
15104 vices. Default is disabled. A possible alternative uses mirror
15105 jobs to a builtin NBD server on the destination, which offers
15106 more flexibility. (Since 2.10)
15107 return-path
15109 If enabled, migration will use the return path even for precopy.
15110 (since 2.10)
15111 pause-before-switchover
15113 Pause outgoing migration before serialising device state and be‐
15114 fore disabling block IO (since 2.11)
15115 multifd
15117 Use more than one fd for migration (since 4.0)
15118 dirty-bitmaps
15120 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
15121 postcopy-blocktime
15123 Calculate downtime for postcopy live migration (since 3.0)
15124 late-block-activate
15126 If enabled, the destination will not activate block devices (and
15127 thus take locks) immediately at the end of migration. (since
15128 3.0)
15129 x-ignore-shared
15131 If enabled, QEMU will not migrate shared memory that is accessi‐
15132 ble on the destination machine. (since 4.0)
15133 validate-uuid
15135 Send the UUID of the source to allow the destination to ensure
15136 it is the same. (since 4.2)
15137 background-snapshot
15139 If enabled, the migration stream will be a snapshot of the VM
15140 exactly at the point when the migration procedure starts. The
15141 VM RAM is saved with running VM. (since 6.0)
15142 zero-copy-send
15144 Controls behavior on sending memory pages on migration. When
15145 true, enables a zero-copy mechanism for sending memory pages, if
15146 host supports it. Requires that QEMU be permitted to use locked
15147 memory for guest RAM pages. (since 7.1)
15148 postcopy-preempt
15150 If enabled, the migration process will allow postcopy requests
15151 to preempt precopy stream, so postcopy requests will be handled
15152 faster. This is a performance feature and should not affect the
15153 correctness of postcopy migration. (since 7.1)
15154 switchover-ack
15156 If enabled, migration will not stop the source VM and complete
15157 the migration until an ACK is received from the destination that
15158 it's OK to do so. Exactly when this ACK is sent depends on the
15159 migrated devices that use this feature. For example, a device
15160 can use it to make sure some of its data is sent and loaded in
15161 the destination before doing switchover. This can reduce down‐
15162 time if devices that support this capability are present. 're‐
15163 turn-path' capability must be enabled to use it. (since 8.1)
15164 dirty-limit
15166 If enabled, migration will throttle vCPUs as needed to keep
15167 their dirty page rate within vcpu-dirty-limit. This can improve
15168 responsiveness of large guests during live migration, and can
15169 result in more stable read performance. Requires KVM with ac‐
15170 celerator property "dirty-ring-size" set. (Since 8.1)
15171 Features
15173 unstable
15174 Members x-colo and x-ignore-shared are experimental.
15175 Since
15177 1.2
15178 MigrationCapabilityStatus (Object)
15180 Migration capability information
15181 Members
15183 capability: MigrationCapability
15184 capability enum
15185 state: boolean
15187 capability state bool
15188 Since
15190 1.2
15191 migrate-set-capabilities (Command)
15193 Enable/Disable the following migration capabilities (like xbzrle)
15194 Arguments
15196 capabilities: array of MigrationCapabilityStatus
15197 json array of capability modifications to make
15198 Since
15200 1.2
15201 Example
15203 -> { "execute": "migrate-set-capabilities" , "arguments":
15204 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
15205 <- { "return": {} }
15206 query-migrate-capabilities (Command)
15208 Returns information about the current migration capabilities status
15209 Returns
15211 MigrationCapabilityStatus
15212 Since
15214 1.2
15215 Example
15217 -> { "execute": "query-migrate-capabilities" }
15218 <- { "return": [
15219 {"state": false, "capability": "xbzrle"},
15220 {"state": false, "capability": "rdma-pin-all"},
15221 {"state": false, "capability": "auto-converge"},
15222 {"state": false, "capability": "zero-blocks"},
15223 {"state": false, "capability": "compress"},
15224 {"state": true, "capability": "events"},
15225 {"state": false, "capability": "postcopy-ram"},
15226 {"state": false, "capability": "x-colo"}
15227 ]}
15228 MultiFDCompression (Enum)
15230 An enumeration of multifd compression methods.
15231 Values
15233 none no compression.
15234 zlib use zlib compression method.
15236 zstd (If: CONFIG_ZSTD)
15238 use zstd compression method.
15239 Since
15241 5.0
15242 BitmapMigrationBitmapAliasTransform (Object)
15244 Members
15245 persistent: boolean (optional)
15246 If present, the bitmap will be made persistent or transient de‐
15247 pending on this parameter.
15248 Since
15250 6.0
15251 BitmapMigrationBitmapAlias (Object)
15253 Members
15254 name: string
15255 The name of the bitmap.
15256 alias: string
15258 An alias name for migration (for example the bitmap name on the
15259 opposite site).
15260 transform: BitmapMigrationBitmapAliasTransform (optional)
15262 Allows the modification of the migrated bitmap. (since 6.0)
15263 Since
15265 5.2
15266 BitmapMigrationNodeAlias (Object)
15268 Maps a block node name and the bitmaps it has to aliases for dirty bit‐
15269 map migration.
15270 Members
15272 node-name: string
15273 A block node name.
15274 alias: string
15276 An alias block node name for migration (for example the node
15277 name on the opposite site).
15278 bitmaps: array of BitmapMigrationBitmapAlias
15280 Mappings for the bitmaps on this node.
15281 Since
15283 5.2
15284 MigrationParameter (Enum)
15286 Migration parameters enumeration
15287 Values
15289 announce-initial
15290 Initial delay (in milliseconds) before sending the first an‐
15291 nounce (Since 4.0)
15292 announce-max
15294 Maximum delay (in milliseconds) between packets in the announce‐
15295 ment (Since 4.0)
15296 announce-rounds
15298 Number of self-announce packets sent after migration (Since 4.0)
15299 announce-step
15301 Increase in delay (in milliseconds) between subsequent packets
15302 in the announcement (Since 4.0)
15303 compress-level
15305 Set the compression level to be used in live migration, the com‐
15306 pression level is an integer between 0 and 9, where 0 means no
15307 compression, 1 means the best compression speed, and 9 means
15308 best compression ratio which will consume more CPU.
15309 compress-threads
15311 Set compression thread count to be used in live migration, the
15312 compression thread count is an integer between 1 and 255.
15313 compress-wait-thread
15315 Controls behavior when all compression threads are currently
15316 busy. If true (default), wait for a free compression thread to
15317 become available; otherwise, send the page uncompressed. (Since
15318 3.1)
15319 decompress-threads
15321 Set decompression thread count to be used in live migration, the
15322 decompression thread count is an integer between 1 and 255. Usu‐
15323 ally, decompression is at least 4 times as fast as compression,
15324 so set the decompress-threads to the number about 1/4 of com‐
15325 press-threads is adequate.
15326 throttle-trigger-threshold
15328 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
15329 throttling. It is expressed as percentage. The default value
15330 is 50. (Since 5.0)
15331 cpu-throttle-initial
15333 Initial percentage of time guest cpus are throttled when migra‐
15334 tion auto-converge is activated. The default value is 20.
15335 (Since 2.7)
15336 cpu-throttle-increment
15338 throttle percentage increase each time auto-converge detects
15339 that migration is not making progress. The default value is 10.
15340 (Since 2.7)
15341 cpu-throttle-tailslow
15343 Make CPU throttling slower at tail stage At the tail stage of
15344 throttling, the Guest is very sensitive to CPU percentage while
15345 the cpu-throttle -increment is excessive usually at tail stage.
15346 If this parameter is true, we will compute the ideal CPU per‐
15347 centage used by the Guest, which may exactly make the dirty rate
15348 match the dirty rate threshold. Then we will choose a smaller
15349 throttle increment between the one specified by cpu-throttle-in‐
15350 crement and the one generated by ideal CPU percentage. There‐
15351 fore, it is compatible to traditional throttling, meanwhile the
15352 throttle increment won't be excessive at tail stage. The de‐
15353 fault value is false. (Since 5.1)
15354 tls-creds
15356 ID of the 'tls-creds' object that provides credentials for es‐
15357 tablishing a TLS connection over the migration data channel. On
15358 the outgoing side of the migration, the credentials must be for
15359 a 'client' endpoint, while for the incoming side the credentials
15360 must be for a 'server' endpoint. Setting this will enable TLS
15361 for all migrations. The default is unset, resulting in unse‐
15362 cured migration at the QEMU level. (Since 2.7)
15363 tls-hostname
15365 hostname of the target host for the migration. This is required
15366 when using x509 based TLS credentials and the migration URI does
15367 not already include a hostname. For example if using fd: or
15368 exec: based migration, the hostname must be provided so that the
15369 server's x509 certificate identity can be validated. (Since
15370 2.7)
15371 tls-authz
15373 ID of the 'authz' object subclass that provides access control
15374 checking of the TLS x509 certificate distinguished name. This
15375 object is only resolved at time of use, so can be deleted and
15376 recreated on the fly while the migration server is active. If
15377 missing, it will default to denying access (Since 4.0)
15378 max-bandwidth
15380 to set maximum speed for migration. maximum speed in bytes per
15381 second. (Since 2.8)
15382 downtime-limit
15384 set maximum tolerated downtime for migration. maximum downtime
15385 in milliseconds (Since 2.8)
15386 x-checkpoint-delay
15388 The delay time (in ms) between two COLO checkpoints in periodic
15389 mode. (Since 2.8)
15390 block-incremental
15392 Affects how much storage is migrated when the block migration
15393 capability is enabled. When false, the entire storage backing
15394 chain is migrated into a flattened image at the destination;
15395 when true, only the active qcow2 layer is migrated and the des‐
15396 tination must already have access to the same backing chain as
15397 was used on the source. (since 2.10)
15398 multifd-channels
15400 Number of channels used to migrate data in parallel. This is
15401 the same number that the number of sockets used for migration.
15402 The default value is 2 (since 4.0)
15403 xbzrle-cache-size
15405 cache size to be used by XBZRLE migration. It needs to be a
15406 multiple of the target page size and a power of 2 (Since 2.11)
15407 max-postcopy-bandwidth
15409 Background transfer bandwidth during postcopy. Defaults to 0
15410 (unlimited). In bytes per second. (Since 3.0)
15411 max-cpu-throttle
15413 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
15414 multifd-compression
15416 Which compression method to use. Defaults to none. (Since 5.0)
15417 multifd-zlib-level
15419 Set the compression level to be used in live migration, the com‐
15420 pression level is an integer between 0 and 9, where 0 means no
15421 compression, 1 means the best compression speed, and 9 means
15422 best compression ratio which will consume more CPU. Defaults to
15423 1. (Since 5.0)
15424 multifd-zstd-level
15426 Set the compression level to be used in live migration, the com‐
15427 pression level is an integer between 0 and 20, where 0 means no
15428 compression, 1 means the best compression speed, and 20 means
15429 best compression ratio which will consume more CPU. Defaults to
15430 1. (Since 5.0)
15431 block-bitmap-mapping
15433 Maps block nodes and bitmaps on them to aliases for the purpose
15434 of dirty bitmap migration. Such aliases may for example be the
15435 corresponding names on the opposite site. The mapping must be
15436 one-to-one, but not necessarily complete: On the source, un‐
15437 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
15438 nored. On the destination, encountering an unmapped alias in
15439 the incoming migration stream will result in a report, and all
15440 further bitmap migration data will then be discarded. Note that
15441 the destination does not know about bitmaps it does not receive,
15442 so there is no limitation or requirement regarding the number of
15443 bitmaps received, or how they are named, or on which nodes they
15444 are placed. By default (when this parameter has never been
15445 set), bitmap names are mapped to themselves. Nodes are mapped
15446 to their block device name if there is one, and to their node
15447 name otherwise. (Since 5.2)
15448 x-vcpu-dirty-limit-period
15450 Periodic time (in milliseconds) of dirty limit during live mi‐
15451 gration. Should be in the range 1 to 1000ms. Defaults to
15452 1000ms. (Since 8.1)
15453 vcpu-dirty-limit
15455 Dirtyrate limit (MB/s) during live migration. Defaults to 1.
15456 (Since 8.1)
15457 Features
15459 unstable
15460 Members x-checkpoint-delay and x-vcpu-dirty-limit-period are ex‐
15461 perimental.
15462 Since
15464 2.4
15465 MigrateSetParameters (Object)
15467 Members
15468 announce-initial: int (optional)
15469 Initial delay (in milliseconds) before sending the first an‐
15470 nounce (Since 4.0)
15471 announce-max: int (optional)
15473 Maximum delay (in milliseconds) between packets in the announce‐
15474 ment (Since 4.0)
15475 announce-rounds: int (optional)
15477 Number of self-announce packets sent after migration (Since 4.0)
15478 announce-step: int (optional)
15480 Increase in delay (in milliseconds) between subsequent packets
15481 in the announcement (Since 4.0)
15482 compress-level: int (optional)
15484 compression level
15485 compress-threads: int (optional)
15487 compression thread count
15488 compress-wait-thread: boolean (optional)
15490 Controls behavior when all compression threads are currently
15491 busy. If true (default), wait for a free compression thread to
15492 become available; otherwise, send the page uncompressed. (Since
15493 3.1)
15494 decompress-threads: int (optional)
15496 decompression thread count
15497 throttle-trigger-threshold: int (optional)
15499 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
15500 throttling. It is expressed as percentage. The default value
15501 is 50. (Since 5.0)
15502 cpu-throttle-initial: int (optional)
15504 Initial percentage of time guest cpus are throttled when migra‐
15505 tion auto-converge is activated. The default value is 20.
15506 (Since 2.7)
15507 cpu-throttle-increment: int (optional)
15509 throttle percentage increase each time auto-converge detects
15510 that migration is not making progress. The default value is 10.
15511 (Since 2.7)
15512 cpu-throttle-tailslow: boolean (optional)
15514 Make CPU throttling slower at tail stage At the tail stage of
15515 throttling, the Guest is very sensitive to CPU percentage while
15516 the cpu-throttle -increment is excessive usually at tail stage.
15517 If this parameter is true, we will compute the ideal CPU per‐
15518 centage used by the Guest, which may exactly make the dirty rate
15519 match the dirty rate threshold. Then we will choose a smaller
15520 throttle increment between the one specified by cpu-throttle-in‐
15521 crement and the one generated by ideal CPU percentage. There‐
15522 fore, it is compatible to traditional throttling, meanwhile the
15523 throttle increment won't be excessive at tail stage. The de‐
15524 fault value is false. (Since 5.1)
15525 tls-creds: StrOrNull (optional)
15527 ID of the 'tls-creds' object that provides credentials for es‐
15528 tablishing a TLS connection over the migration data channel. On
15529 the outgoing side of the migration, the credentials must be for
15530 a 'client' endpoint, while for the incoming side the credentials
15531 must be for a 'server' endpoint. Setting this to a non-empty
15532 string enables TLS for all migrations. An empty string means
15533 that QEMU will use plain text mode for migration, rather than
15534 TLS (Since 2.9) Previously (since 2.7), this was reported by
15535 omitting tls-creds instead.
15536 tls-hostname: StrOrNull (optional)
15538 hostname of the target host for the migration. This is required
15539 when using x509 based TLS credentials and the migration URI does
15540 not already include a hostname. For example if using fd: or
15541 exec: based migration, the hostname must be provided so that the
15542 server's x509 certificate identity can be validated. (Since
15543 2.7) An empty string means that QEMU will use the hostname asso‐
15544 ciated with the migration URI, if any. (Since 2.9) Previously
15545 (since 2.7), this was reported by omitting tls-hostname instead.
15546 max-bandwidth: int (optional)
15548 to set maximum speed for migration. maximum speed in bytes per
15549 second. (Since 2.8)
15550 downtime-limit: int (optional)
15552 set maximum tolerated downtime for migration. maximum downtime
15553 in milliseconds (Since 2.8)
15554 x-checkpoint-delay: int (optional)
15556 the delay time between two COLO checkpoints. (Since 2.8)
15557 block-incremental: boolean (optional)
15559 Affects how much storage is migrated when the block migration
15560 capability is enabled. When false, the entire storage backing
15561 chain is migrated into a flattened image at the destination;
15562 when true, only the active qcow2 layer is migrated and the des‐
15563 tination must already have access to the same backing chain as
15564 was used on the source. (since 2.10)
15565 multifd-channels: int (optional)
15567 Number of channels used to migrate data in parallel. This is
15568 the same number that the number of sockets used for migration.
15569 The default value is 2 (since 4.0)
15570 xbzrle-cache-size: int (optional)
15572 cache size to be used by XBZRLE migration. It needs to be a
15573 multiple of the target page size and a power of 2 (Since 2.11)
15574 max-postcopy-bandwidth: int (optional)
15576 Background transfer bandwidth during postcopy. Defaults to 0
15577 (unlimited). In bytes per second. (Since 3.0)
15578 max-cpu-throttle: int (optional)
15580 maximum cpu throttle percentage. The default value is 99.
15581 (Since 3.1)
15582 multifd-compression: MultiFDCompression (optional)
15584 Which compression method to use. Defaults to none. (Since 5.0)
15585 multifd-zlib-level: int (optional)
15587 Set the compression level to be used in live migration, the com‐
15588 pression level is an integer between 0 and 9, where 0 means no
15589 compression, 1 means the best compression speed, and 9 means
15590 best compression ratio which will consume more CPU. Defaults to
15591 1. (Since 5.0)
15592 multifd-zstd-level: int (optional)
15594 Set the compression level to be used in live migration, the com‐
15595 pression level is an integer between 0 and 20, where 0 means no
15596 compression, 1 means the best compression speed, and 20 means
15597 best compression ratio which will consume more CPU. Defaults to
15598 1. (Since 5.0)
15599 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
15601 Maps block nodes and bitmaps on them to aliases for the purpose
15602 of dirty bitmap migration. Such aliases may for example be the
15603 corresponding names on the opposite site. The mapping must be
15604 one-to-one, but not necessarily complete: On the source, un‐
15605 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
15606 nored. On the destination, encountering an unmapped alias in
15607 the incoming migration stream will result in a report, and all
15608 further bitmap migration data will then be discarded. Note that
15609 the destination does not know about bitmaps it does not receive,
15610 so there is no limitation or requirement regarding the number of
15611 bitmaps received, or how they are named, or on which nodes they
15612 are placed. By default (when this parameter has never been
15613 set), bitmap names are mapped to themselves. Nodes are mapped
15614 to their block device name if there is one, and to their node
15615 name otherwise. (Since 5.2)
15616 x-vcpu-dirty-limit-period: int (optional)
15618 Periodic time (in milliseconds) of dirty limit during live mi‐
15619 gration. Should be in the range 1 to 1000ms. Defaults to
15620 1000ms. (Since 8.1)
15621 vcpu-dirty-limit: int (optional)
15623 Dirtyrate limit (MB/s) during live migration. Defaults to 1.
15624 (Since 8.1)
15625 tls-authz: StrOrNull (optional)
15627 Not documented
15628 Features
15630 unstable
15631 Members x-checkpoint-delay and x-vcpu-dirty-limit-period are ex‐
15632 perimental.
15633 Since
15635 2.4
15636 migrate-set-parameters (Command)
15638 Set various migration parameters.
15639 Arguments
15641 The members of MigrateSetParameters
15642 Since
15644 2.4
15645 Example
15647 -> { "execute": "migrate-set-parameters" ,
15648 "arguments": { "compress-level": 1 } }
15649 <- { "return": {} }
15650 MigrationParameters (Object)
15652 The optional members aren't actually optional.
15653 Members
15655 announce-initial: int (optional)
15656 Initial delay (in milliseconds) before sending the first an‐
15657 nounce (Since 4.0)
15658 announce-max: int (optional)
15660 Maximum delay (in milliseconds) between packets in the announce‐
15661 ment (Since 4.0)
15662 announce-rounds: int (optional)
15664 Number of self-announce packets sent after migration (Since 4.0)
15665 announce-step: int (optional)
15667 Increase in delay (in milliseconds) between subsequent packets
15668 in the announcement (Since 4.0)
15669 compress-level: int (optional)
15671 compression level
15672 compress-threads: int (optional)
15674 compression thread count
15675 compress-wait-thread: boolean (optional)
15677 Controls behavior when all compression threads are currently
15678 busy. If true (default), wait for a free compression thread to
15679 become available; otherwise, send the page uncompressed. (Since
15680 3.1)
15681 decompress-threads: int (optional)
15683 decompression thread count
15684 throttle-trigger-threshold: int (optional)
15686 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
15687 throttling. It is expressed as percentage. The default value
15688 is 50. (Since 5.0)
15689 cpu-throttle-initial: int (optional)
15691 Initial percentage of time guest cpus are throttled when migra‐
15692 tion auto-converge is activated. (Since 2.7)
15693 cpu-throttle-increment: int (optional)
15695 throttle percentage increase each time auto-converge detects
15696 that migration is not making progress. (Since 2.7)
15697 cpu-throttle-tailslow: boolean (optional)
15699 Make CPU throttling slower at tail stage At the tail stage of
15700 throttling, the Guest is very sensitive to CPU percentage while
15701 the cpu-throttle -increment is excessive usually at tail stage.
15702 If this parameter is true, we will compute the ideal CPU per‐
15703 centage used by the Guest, which may exactly make the dirty rate
15704 match the dirty rate threshold. Then we will choose a smaller
15705 throttle increment between the one specified by cpu-throttle-in‐
15706 crement and the one generated by ideal CPU percentage. There‐
15707 fore, it is compatible to traditional throttling, meanwhile the
15708 throttle increment won't be excessive at tail stage. The de‐
15709 fault value is false. (Since 5.1)
15710 tls-creds: string (optional)
15712 ID of the 'tls-creds' object that provides credentials for es‐
15713 tablishing a TLS connection over the migration data channel. On
15714 the outgoing side of the migration, the credentials must be for
15715 a 'client' endpoint, while for the incoming side the credentials
15716 must be for a 'server' endpoint. An empty string means that
15717 QEMU will use plain text mode for migration, rather than TLS
15718 (Since 2.7) Note: 2.8 reports this by omitting tls-creds in‐
15719 stead.
15720 tls-hostname: string (optional)
15722 hostname of the target host for the migration. This is required
15723 when using x509 based TLS credentials and the migration URI does
15724 not already include a hostname. For example if using fd: or
15725 exec: based migration, the hostname must be provided so that the
15726 server's x509 certificate identity can be validated. (Since
15727 2.7) An empty string means that QEMU will use the hostname asso‐
15728 ciated with the migration URI, if any. (Since 2.9) Note: 2.8
15729 reports this by omitting tls-hostname instead.
15730 tls-authz: string (optional)
15732 ID of the 'authz' object subclass that provides access control
15733 checking of the TLS x509 certificate distinguished name. (Since
15734 4.0)
15735 max-bandwidth: int (optional)
15737 to set maximum speed for migration. maximum speed in bytes per
15738 second. (Since 2.8)
15739 downtime-limit: int (optional)
15741 set maximum tolerated downtime for migration. maximum downtime
15742 in milliseconds (Since 2.8)
15743 x-checkpoint-delay: int (optional)
15745 the delay time between two COLO checkpoints. (Since 2.8)
15746 block-incremental: boolean (optional)
15748 Affects how much storage is migrated when the block migration
15749 capability is enabled. When false, the entire storage backing
15750 chain is migrated into a flattened image at the destination;
15751 when true, only the active qcow2 layer is migrated and the des‐
15752 tination must already have access to the same backing chain as
15753 was used on the source. (since 2.10)
15754 multifd-channels: int (optional)
15756 Number of channels used to migrate data in parallel. This is
15757 the same number that the number of sockets used for migration.
15758 The default value is 2 (since 4.0)
15759 xbzrle-cache-size: int (optional)
15761 cache size to be used by XBZRLE migration. It needs to be a
15762 multiple of the target page size and a power of 2 (Since 2.11)
15763 max-postcopy-bandwidth: int (optional)
15765 Background transfer bandwidth during postcopy. Defaults to 0
15766 (unlimited). In bytes per second. (Since 3.0)
15767 max-cpu-throttle: int (optional)
15769 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
15770 multifd-compression: MultiFDCompression (optional)
15772 Which compression method to use. Defaults to none. (Since 5.0)
15773 multifd-zlib-level: int (optional)
15775 Set the compression level to be used in live migration, the com‐
15776 pression level is an integer between 0 and 9, where 0 means no
15777 compression, 1 means the best compression speed, and 9 means
15778 best compression ratio which will consume more CPU. Defaults to
15779 1. (Since 5.0)
15780 multifd-zstd-level: int (optional)
15782 Set the compression level to be used in live migration, the com‐
15783 pression level is an integer between 0 and 20, where 0 means no
15784 compression, 1 means the best compression speed, and 20 means
15785 best compression ratio which will consume more CPU. Defaults to
15786 1. (Since 5.0)
15787 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
15789 Maps block nodes and bitmaps on them to aliases for the purpose
15790 of dirty bitmap migration. Such aliases may for example be the
15791 corresponding names on the opposite site. The mapping must be
15792 one-to-one, but not necessarily complete: On the source, un‐
15793 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
15794 nored. On the destination, encountering an unmapped alias in
15795 the incoming migration stream will result in a report, and all
15796 further bitmap migration data will then be discarded. Note that
15797 the destination does not know about bitmaps it does not receive,
15798 so there is no limitation or requirement regarding the number of
15799 bitmaps received, or how they are named, or on which nodes they
15800 are placed. By default (when this parameter has never been
15801 set), bitmap names are mapped to themselves. Nodes are mapped
15802 to their block device name if there is one, and to their node
15803 name otherwise. (Since 5.2)
15804 x-vcpu-dirty-limit-period: int (optional)
15806 Periodic time (in milliseconds) of dirty limit during live mi‐
15807 gration. Should be in the range 1 to 1000ms. Defaults to
15808 1000ms. (Since 8.1)
15809 vcpu-dirty-limit: int (optional)
15811 Dirtyrate limit (MB/s) during live migration. Defaults to 1.
15812 (Since 8.1)
15813 Features
15815 unstable
15816 Members x-checkpoint-delay and x-vcpu-dirty-limit-period are ex‐
15817 perimental.
15818 Since
15820 2.4
15821 query-migrate-parameters (Command)
15823 Returns information about the current migration parameters
15824 Returns
15826 MigrationParameters
15827 Since
15829 2.4
15830 Example
15832 -> { "execute": "query-migrate-parameters" }
15833 <- { "return": {
15834 "decompress-threads": 2,
15835 "cpu-throttle-increment": 10,
15836 "compress-threads": 8,
15837 "compress-level": 1,
15838 "cpu-throttle-initial": 20,
15839 "max-bandwidth": 33554432,
15840 "downtime-limit": 300
15841 }
15842 }
15843 migrate-start-postcopy (Command)
15845 Followup to a migration command to switch the migration to postcopy
15846 mode. The postcopy-ram capability must be set on both source and des‐
15847 tination before the original migration command.
15848 Since
15850 2.5
15851 Example
15853 -> { "execute": "migrate-start-postcopy" }
15854 <- { "return": {} }
15855 MIGRATION (Event)
15857 Emitted when a migration event happens
15858 Arguments
15860 status: MigrationStatus
15861 MigrationStatus describing the current migration status.
15862 Since
15864 2.4
15865 Example
15867 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
15868 "event": "MIGRATION",
15869 "data": {"status": "completed"} }
15870 MIGRATION_PASS (Event)
15872 Emitted from the source side of a migration at the start of each pass
15873 (when it syncs the dirty bitmap)
15874 Arguments
15876 pass: int
15877 An incrementing count (starting at 1 on the first pass)
15878 Since
15880 2.6
15881 Example
15883 <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
15884 "event": "MIGRATION_PASS", "data": {"pass": 2} }
15885 COLOMessage (Enum)
15887 The message transmission between Primary side and Secondary side.
15888 Values
15890 checkpoint-ready
15891 Secondary VM (SVM) is ready for checkpointing
15892 checkpoint-request
15894 Primary VM (PVM) tells SVM to prepare for checkpointing
15895 checkpoint-reply
15897 SVM gets PVM's checkpoint request
15898 vmstate-send
15900 VM's state will be sent by PVM.
15901 vmstate-size
15903 The total size of VMstate.
15904 vmstate-received
15906 VM's state has been received by SVM.
15907 vmstate-loaded
15909 VM's state has been loaded by SVM.
15910 Since
15912 2.8
15913 COLOMode (Enum)
15915 The COLO current mode.
15916 Values
15918 none COLO is disabled.
15919 primary
15921 COLO node in primary side.
15922 secondary
15924 COLO node in slave side.
15925 Since
15927 2.8
15928 FailoverStatus (Enum)
15930 An enumeration of COLO failover status
15931 Values
15933 none no failover has ever happened
15934 require
15936 got failover requirement but not handled
15937 active in the process of doing failover
15939 completed
15941 finish the process of failover
15942 relaunch
15944 restart the failover process, from 'none' -> 'completed' (Since
15945 2.9)
15946 Since
15948 2.8
15949 COLO_EXIT (Event)
15951 Emitted when VM finishes COLO mode due to some errors happening or at
15952 the request of users.
15953 Arguments
15955 mode: COLOMode
15956 report COLO mode when COLO exited.
15957 reason: COLOExitReason
15959 describes the reason for the COLO exit.
15960 Since
15962 3.1
15963 Example
15965 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
15966 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
15967 COLOExitReason (Enum)
15969 The reason for a COLO exit.
15970 Values
15972 none failover has never happened. This state does not occur in the
15973 COLO_EXIT event, and is only visible in the result of
15974 query-colo-status.
15975 request
15977 COLO exit is due to an external request.
15978 error COLO exit is due to an internal error.
15980 processing
15982 COLO is currently handling a failover (since 4.0).
15983 Since
15985 3.1
15986 x-colo-lost-heartbeat (Command)
15988 Tell qemu that heartbeat is lost, request it to do takeover procedures.
15989 If this command is sent to the PVM, the Primary side will exit COLO
15990 mode. If sent to the Secondary, the Secondary side will run failover
15991 work, then takes over server operation to become the service VM.
15992 Features
15994 unstable
15995 This command is experimental.
15996 Since
15998 2.8
15999 Example
16001 -> { "execute": "x-colo-lost-heartbeat" }
16002 <- { "return": {} }
16003 If
16005 CONFIG_REPLICATION
16006 migrate_cancel (Command)
16008 Cancel the current executing migration process.
16009 Returns
16011 nothing on success
16012 Notes
16014 This command succeeds even if there is no migration process running.
16015 Since
16017 0.14
16018 Example
16020 -> { "execute": "migrate_cancel" }
16021 <- { "return": {} }
16022 migrate-continue (Command)
16024 Continue migration when it's in a paused state.
16025 Arguments
16027 state: MigrationStatus
16028 The state the migration is currently expected to be in
16029 Returns
16031 nothing on success
16032 Since
16034 2.11
16035 Example
16037 -> { "execute": "migrate-continue" , "arguments":
16038 { "state": "pre-switchover" } }
16039 <- { "return": {} }
16040 migrate (Command)
16042 Migrates the current running guest to another Virtual Machine.
16043 Arguments
16045 uri: string
16046 the Uniform Resource Identifier of the destination VM
16047 blk: boolean (optional)
16049 do block migration (full disk copy)
16050 inc: boolean (optional)
16052 incremental disk copy migration
16053 detach: boolean (optional)
16055 this argument exists only for compatibility reasons and is ig‐
16056 nored by QEMU
16057 resume: boolean (optional)
16059 resume one paused migration, default "off". (since 3.0)
16060 Returns
16062 nothing on success
16063 Since
16065 0.14
16066 Notes
16068 1. The 'query-migrate' command should be used to check migration's
16069 progress and final result (this information is provided by the 'sta‐
16070 tus' member)
16071 2. All boolean arguments default to false
16073 3. The user Monitor's "detach" argument is invalid in QMP and should
16075 not be used
16076 Example
16078 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
16079 <- { "return": {} }
16080 migrate-incoming (Command)
16082 Start an incoming migration, the qemu must have been started with -in‐
16083 coming defer
16084 Arguments
16086 uri: string
16087 The Uniform Resource Identifier identifying the source or ad‐
16088 dress to listen on
16089 Returns
16091 nothing on success
16092 Since
16094 2.3
16095 Notes
16097 1. It's a bad idea to use a string for the uri, but it needs to stay
16098 compatible with -incoming and the format of the uri is already ex‐
16099 posed above libvirt.
16100 2. QEMU must be started with -incoming defer to allow migrate-incoming
16102 to be used.
16103 3. The uri format is the same as for -incoming
16105 Example
16107 -> { "execute": "migrate-incoming",
16108 "arguments": { "uri": "tcp::4446" } }
16109 <- { "return": {} }
16110 xen-save-devices-state (Command)
16112 Save the state of all devices to file. The RAM and the block devices
16113 of the VM are not saved by this command.
16114 Arguments
16116 filename: string
16117 the file to save the state of the devices to as binary data.
16118 See xen-save-devices-state.txt for a description of the binary
16119 format.
16120 live: boolean (optional)
16122 Optional argument to ask QEMU to treat this command as part of a
16123 live migration. Default to true. (since 2.11)
16124 Returns
16126 Nothing on success
16127 Since
16129 1.1
16130 Example
16132 -> { "execute": "xen-save-devices-state",
16133 "arguments": { "filename": "/tmp/save" } }
16134 <- { "return": {} }
16135 xen-set-global-dirty-log (Command)
16137 Enable or disable the global dirty log mode.
16138 Arguments
16140 enable: boolean
16141 true to enable, false to disable.
16142 Returns
16144 nothing
16145 Since
16147 1.3
16148 Example
16150 -> { "execute": "xen-set-global-dirty-log",
16151 "arguments": { "enable": true } }
16152 <- { "return": {} }
16153 xen-load-devices-state (Command)
16155 Load the state of all devices from file. The RAM and the block devices
16156 of the VM are not loaded by this command.
16157 Arguments
16159 filename: string
16160 the file to load the state of the devices from as binary data.
16161 See xen-save-devices-state.txt for a description of the binary
16162 format.
16163 Since
16165 2.7
16166 Example
16168 -> { "execute": "xen-load-devices-state",
16169 "arguments": { "filename": "/tmp/resume" } }
16170 <- { "return": {} }
16171 xen-set-replication (Command)
16173 Enable or disable replication.
16174 Arguments
16176 enable: boolean
16177 true to enable, false to disable.
16178 primary: boolean
16180 true for primary or false for secondary.
16181 failover: boolean (optional)
16183 true to do failover, false to stop. but cannot be specified if
16184 'enable' is true. default value is false.
16185 Returns
16187 nothing.
16188 Example
16190 -> { "execute": "xen-set-replication",
16191 "arguments": {"enable": true, "primary": false} }
16192 <- { "return": {} }
16193 Since
16195 2.9
16196 If
16198 CONFIG_REPLICATION
16199 ReplicationStatus (Object)
16201 The result format for 'query-xen-replication-status'.
16202 Members
16204 error: boolean
16205 true if an error happened, false if replication is normal.
16206 desc: string (optional)
16208 the human readable error description string, when error is
16209 'true'.
16210 Since
16212 2.9
16213 If
16215 CONFIG_REPLICATION
16216 query-xen-replication-status (Command)
16218 Query replication status while the vm is running.
16219 Returns
16221 A ReplicationStatus object showing the status.
16222 Example
16224 -> { "execute": "query-xen-replication-status" }
16225 <- { "return": { "error": false } }
16226 Since
16228 2.9
16229 If
16231 CONFIG_REPLICATION
16232 xen-colo-do-checkpoint (Command)
16234 Xen uses this command to notify replication to trigger a checkpoint.
16235 Returns
16237 nothing.
16238 Example
16240 -> { "execute": "xen-colo-do-checkpoint" }
16241 <- { "return": {} }
16242 Since
16244 2.9
16245 If
16247 CONFIG_REPLICATION
16248 COLOStatus (Object)
16250 The result format for 'query-colo-status'.
16251 Members
16253 mode: COLOMode
16254 COLO running mode. If COLO is running, this field will return
16255 'primary' or 'secondary'.
16256 last-mode: COLOMode
16258 COLO last running mode. If COLO is running, this field will re‐
16259 turn same like mode field, after failover we can use this field
16260 to get last colo mode. (since 4.0)
16261 reason: COLOExitReason
16263 describes the reason for the COLO exit.
16264 Since
16266 3.1
16267 If
16269 CONFIG_REPLICATION
16270 query-colo-status (Command)
16272 Query COLO status while the vm is running.
16273 Returns
16275 A COLOStatus object showing the status.
16276 Example
16278 -> { "execute": "query-colo-status" }
16279 <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } }
16280 Since
16282 3.1
16283 If
16285 CONFIG_REPLICATION
16286 migrate-recover (Command)
16288 Provide a recovery migration stream URI.
16289 Arguments
16291 uri: string
16292 the URI to be used for the recovery of migration stream.
16293 Returns
16295 nothing.
16296 Example
16298 -> { "execute": "migrate-recover",
16299 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
16300 <- { "return": {} }
16301 Since
16303 3.0
16304 migrate-pause (Command)
16306 Pause a migration. Currently it only supports postcopy.
16307 Returns
16309 nothing.
16310 Example
16312 -> { "execute": "migrate-pause" }
16313 <- { "return": {} }
16314 Since
16316 3.0
16317 UNPLUG_PRIMARY (Event)
16319 Emitted from source side of a migration when migration state is
16320 WAIT_UNPLUG. Device was unplugged by guest operating system. Device
16321 resources in QEMU are kept on standby to be able to re-plug it in case
16322 of migration failure.
16323 Arguments
16325 device-id: string
16326 QEMU device id of the unplugged device
16327 Since
16329 4.2
16330 Example
16332 <- { "event": "UNPLUG_PRIMARY",
16333 "data": { "device-id": "hostdev0" },
16334 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
16335 DirtyRateVcpu (Object)
16337 Dirty rate of vcpu.
16338 Members
16340 id: int
16341 vcpu index.
16342 dirty-rate: int
16344 dirty rate.
16345 Since
16347 6.2
16348 DirtyRateStatus (Enum)
16350 Dirty page rate measurement status.
16351 Values
16353 unstarted
16354 measuring thread has not been started yet
16355 measuring
16357 measuring thread is running
16358 measured
16360 dirty page rate is measured and the results are available
16361 Since
16363 5.2
16364 DirtyRateMeasureMode (Enum)
16366 Method used to measure dirty page rate. Differences between available
16367 methods are explained in calc-dirty-rate.
16368 Values
16370 page-sampling
16371 use page sampling
16372 dirty-ring
16374 use dirty ring
16375 dirty-bitmap
16377 use dirty bitmap
16378 Since
16380 6.2
16381 DirtyRateInfo (Object)
16383 Information about measured dirty page rate.
16384 Members
16386 dirty-rate: int (optional)
16387 an estimate of the dirty page rate of the VM in units of MiB/s.
16388 Value is present only when status is 'measured'.
16389 status: DirtyRateStatus
16391 current status of dirty page rate measurements
16392 start-time: int
16394 start time in units of second for calculation
16395 calc-time: int
16397 time period for which dirty page rate was measured (in seconds)
16398 sample-pages: int
16400 number of sampled pages per GiB of guest memory. Valid only in
16401 page-sampling mode (Since 6.1)
16402 mode: DirtyRateMeasureMode
16404 mode that was used to measure dirty page rate (Since 6.2)
16405 vcpu-dirty-rate: array of DirtyRateVcpu (optional)
16407 dirty rate for each vCPU if dirty-ring mode was specified (Since
16408 6.2)
16409 Since
16411 5.2
16412 calc-dirty-rate (Command)
16414 Start measuring dirty page rate of the VM. Results can be retrieved
16415 with query-dirty-rate after measurements are completed.
16416 Dirty page rate is the number of pages changed in a given time period
16418 expressed in MiB/s. The following methods of calculation are avail‐
16419 able:
16420 1. In page sampling mode, a random subset of pages are selected and
16422 hashed twice: once at the beginning of measurement time period, and
16423 once again at the end. If two hashes for some page are different,
16424 the page is counted as changed. Since this method relies on sam‐
16425 pling and hashing, calculated dirty page rate is only an estimate of
16426 its true value. Increasing sample-pages improves estimation quality
16427 at the cost of higher computational overhead.
16428 2. Dirty bitmap mode captures writes to memory (for example by tempo‐
16430 rarily revoking write access to all pages) and counting page faults.
16431 Information about modified pages is collected into a bitmap, where
16432 each bit corresponds to one guest page. This mode requires that KVM
16433 accelerator property "dirty-ring-size" is not set.
16434 3. Dirty ring mode is similar to dirty bitmap mode, but the information
16436 about modified pages is collected into ring buffer. This mode
16437 tracks page modification per each vCPU separately. It requires that
16438 KVM accelerator property "dirty-ring-size" is set.
16439 Arguments
16441 calc-time: int
16442 time period in units of second for which dirty page rate is cal‐
16443 culated. Note that larger calc-time values will typically re‐
16444 sult in smaller dirty page rates because page dirtying is a
16445 one-time event. Once some page is counted as dirty during
16446 calc-time period, further writes to this page will not increase
16447 dirty page rate anymore.
16448 sample-pages: int (optional)
16450 number of sampled pages per each GiB of guest memory. Default
16451 value is 512. For 4KiB guest pages this corresponds to sampling
16452 ratio of 0.2%. This argument is used only in page sampling
16453 mode. (Since 6.1)
16454 mode: DirtyRateMeasureMode (optional)
16456 mechanism for tracking dirty pages. Default value is 'page-sam‐
16457 pling'. Others are 'dirty-bitmap' and 'dirty-ring'. (Since
16458 6.1)
16459 Since
16461 5.2
16462 Example
16464 -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
16465 'sample-pages': 512} }
16466 <- { "return": {} }
16467 query-dirty-rate (Command)
16469 Query results of the most recent invocation of calc-dirty-rate.
16470 Since
16472 5.2
16473 Examples
16475 1. Measurement is in progress:
16476 <- {"status": "measuring", "sample-pages": 512,
16478 "mode": "page-sampling", "start-time": 3665220, "calc-time": 10}
16479 2. Measurement has been completed:
16481 <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108,
16483 "mode": "page-sampling", "start-time": 3665220, "calc-time": 10}
16484 DirtyLimitInfo (Object)
16486 Dirty page rate limit information of a virtual CPU.
16487 Members
16489 cpu-index: int
16490 index of a virtual CPU.
16491 limit-rate: int
16493 upper limit of dirty page rate (MB/s) for a virtual CPU, 0 means
16494 unlimited.
16495 current-rate: int
16497 current dirty page rate (MB/s) for a virtual CPU.
16498 Since
16500 7.1
16501 set-vcpu-dirty-limit (Command)
16503 Set the upper limit of dirty page rate for virtual CPUs.
16504 Requires KVM with accelerator property "dirty-ring-size" set. A vir‐
16506 tual CPU's dirty page rate is a measure of its memory load. To observe
16507 dirty page rates, use calc-dirty-rate.
16508 Arguments
16510 cpu-index: int (optional)
16511 index of a virtual CPU, default is all.
16512 dirty-rate: int
16514 upper limit of dirty page rate (MB/s) for virtual CPUs.
16515 Since
16517 7.1
16518 Example
16520 -> {"execute": "set-vcpu-dirty-limit"}
16521 "arguments": { "dirty-rate": 200,
16522 "cpu-index": 1 } }
16523 <- { "return": {} }
16524 cancel-vcpu-dirty-limit (Command)
16526 Cancel the upper limit of dirty page rate for virtual CPUs.
16527 Cancel the dirty page limit for the vCPU which has been set with
16529 set-vcpu-dirty-limit command. Note that this command requires support
16530 from dirty ring, same as the "set-vcpu-dirty-limit".
16531 Arguments
16533 cpu-index: int (optional)
16534 index of a virtual CPU, default is all.
16535 Since
16537 7.1
16538 Example
16540 -> {"execute": "cancel-vcpu-dirty-limit"},
16541 "arguments": { "cpu-index": 1 } }
16542 <- { "return": {} }
16543 query-vcpu-dirty-limit (Command)
16545 Returns information about virtual CPU dirty page rate limits, if any.
16546 Since
16548 7.1
16549 Example
16551 -> {"execute": "query-vcpu-dirty-limit"}
16552 <- {"return": [
16553 { "limit-rate": 60, "current-rate": 3, "cpu-index": 0},
16554 { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]}
16555 MigrationThreadInfo (Object)
16557 Information about migrationthreads
16558 Members
16560 name: string
16561 the name of migration thread
16562 thread-id: int
16564 ID of the underlying host thread
16565 Since
16567 7.2
16568 query-migrationthreads (Command)
16570 Returns information of migration threads
16571 data: migration thread name
16573 Returns
16575 information about migration threads
16576 Since
16578 7.2
16579 snapshot-save (Command)
16581 Save a VM snapshot
16582 Arguments
16584 job-id: string
16585 identifier for the newly created job
16586 tag: string
16588 name of the snapshot to create
16589 vmstate: string
16591 block device node name to save vmstate to
16592 devices: array of string
16594 list of block device node names to save a snapshot to
16595 Applications should not assume that the snapshot save is complete when
16596 this command returns. The job commands / events must be used to deter‐
16597 mine completion and to fetch details of any errors that arise.
16598 Note that execution of the guest CPUs may be stopped during the time it
16600 takes to save the snapshot. A future version of QEMU may ensure CPUs
16601 are executing continuously.
16602 It is strongly recommended that devices contain all writable block de‐
16604 vice nodes if a consistent snapshot is required.
16605 If tag already exists, an error will be reported
16607 Returns
16609 nothing
16610 Example
16612 -> { "execute": "snapshot-save",
16613 "arguments": {
16614 "job-id": "snapsave0",
16615 "tag": "my-snap",
16616 "vmstate": "disk0",
16617 "devices": ["disk0", "disk1"]
16618 }
16619 }
16620 <- { "return": { } }
16621 <- {"event": "JOB_STATUS_CHANGE",
16622 "timestamp": {"seconds": 1432121972, "microseconds": 744001},
16623 "data": {"status": "created", "id": "snapsave0"}}
16624 <- {"event": "JOB_STATUS_CHANGE",
16625 "timestamp": {"seconds": 1432122172, "microseconds": 744001},
16626 "data": {"status": "running", "id": "snapsave0"}}
16627 <- {"event": "STOP",
16628 "timestamp": {"seconds": 1432122372, "microseconds": 744001} }
16629 <- {"event": "RESUME",
16630 "timestamp": {"seconds": 1432122572, "microseconds": 744001} }
16631 <- {"event": "JOB_STATUS_CHANGE",
16632 "timestamp": {"seconds": 1432122772, "microseconds": 744001},
16633 "data": {"status": "waiting", "id": "snapsave0"}}
16634 <- {"event": "JOB_STATUS_CHANGE",
16635 "timestamp": {"seconds": 1432122972, "microseconds": 744001},
16636 "data": {"status": "pending", "id": "snapsave0"}}
16637 <- {"event": "JOB_STATUS_CHANGE",
16638 "timestamp": {"seconds": 1432123172, "microseconds": 744001},
16639 "data": {"status": "concluded", "id": "snapsave0"}}
16640 -> {"execute": "query-jobs"}
16641 <- {"return": [{"current-progress": 1,
16642 "status": "concluded",
16643 "total-progress": 1,
16644 "type": "snapshot-save",
16645 "id": "snapsave0"}]}
16646 Since
16648 6.0
16649 snapshot-load (Command)
16651 Load a VM snapshot
16652 Arguments
16654 job-id: string
16655 identifier for the newly created job
16656 tag: string
16658 name of the snapshot to load.
16659 vmstate: string
16661 block device node name to load vmstate from
16662 devices: array of string
16664 list of block device node names to load a snapshot from
16665 Applications should not assume that the snapshot load is complete when
16666 this command returns. The job commands / events must be used to deter‐
16667 mine completion and to fetch details of any errors that arise.
16668 Note that execution of the guest CPUs will be stopped during the time
16670 it takes to load the snapshot.
16671 It is strongly recommended that devices contain all writable block de‐
16673 vice nodes that can have changed since the original snapshot-save com‐
16674 mand execution.
16675 Returns
16677 nothing
16678 Example
16680 -> { "execute": "snapshot-load",
16681 "arguments": {
16682 "job-id": "snapload0",
16683 "tag": "my-snap",
16684 "vmstate": "disk0",
16685 "devices": ["disk0", "disk1"]
16686 }
16687 }
16688 <- { "return": { } }
16689 <- {"event": "JOB_STATUS_CHANGE",
16690 "timestamp": {"seconds": 1472124172, "microseconds": 744001},
16691 "data": {"status": "created", "id": "snapload0"}}
16692 <- {"event": "JOB_STATUS_CHANGE",
16693 "timestamp": {"seconds": 1472125172, "microseconds": 744001},
16694 "data": {"status": "running", "id": "snapload0"}}
16695 <- {"event": "STOP",
16696 "timestamp": {"seconds": 1472125472, "microseconds": 744001} }
16697 <- {"event": "RESUME",
16698 "timestamp": {"seconds": 1472125872, "microseconds": 744001} }
16699 <- {"event": "JOB_STATUS_CHANGE",
16700 "timestamp": {"seconds": 1472126172, "microseconds": 744001},
16701 "data": {"status": "waiting", "id": "snapload0"}}
16702 <- {"event": "JOB_STATUS_CHANGE",
16703 "timestamp": {"seconds": 1472127172, "microseconds": 744001},
16704 "data": {"status": "pending", "id": "snapload0"}}
16705 <- {"event": "JOB_STATUS_CHANGE",
16706 "timestamp": {"seconds": 1472128172, "microseconds": 744001},
16707 "data": {"status": "concluded", "id": "snapload0"}}
16708 -> {"execute": "query-jobs"}
16709 <- {"return": [{"current-progress": 1,
16710 "status": "concluded",
16711 "total-progress": 1,
16712 "type": "snapshot-load",
16713 "id": "snapload0"}]}
16714 Since
16716 6.0
16717 snapshot-delete (Command)
16719 Delete a VM snapshot
16720 Arguments
16722 job-id: string
16723 identifier for the newly created job
16724 tag: string
16726 name of the snapshot to delete.
16727 devices: array of string
16729 list of block device node names to delete a snapshot from
16730 Applications should not assume that the snapshot delete is complete
16731 when this command returns. The job commands / events must be used to
16732 determine completion and to fetch details of any errors that arise.
16733 Returns
16735 nothing
16736 Example
16738 -> { "execute": "snapshot-delete",
16739 "arguments": {
16740 "job-id": "snapdelete0",
16741 "tag": "my-snap",
16742 "devices": ["disk0", "disk1"]
16743 }
16744 }
16745 <- { "return": { } }
16746 <- {"event": "JOB_STATUS_CHANGE",
16747 "timestamp": {"seconds": 1442124172, "microseconds": 744001},
16748 "data": {"status": "created", "id": "snapdelete0"}}
16749 <- {"event": "JOB_STATUS_CHANGE",
16750 "timestamp": {"seconds": 1442125172, "microseconds": 744001},
16751 "data": {"status": "running", "id": "snapdelete0"}}
16752 <- {"event": "JOB_STATUS_CHANGE",
16753 "timestamp": {"seconds": 1442126172, "microseconds": 744001},
16754 "data": {"status": "waiting", "id": "snapdelete0"}}
16755 <- {"event": "JOB_STATUS_CHANGE",
16756 "timestamp": {"seconds": 1442127172, "microseconds": 744001},
16757 "data": {"status": "pending", "id": "snapdelete0"}}
16758 <- {"event": "JOB_STATUS_CHANGE",
16759 "timestamp": {"seconds": 1442128172, "microseconds": 744001},
16760 "data": {"status": "concluded", "id": "snapdelete0"}}
16761 -> {"execute": "query-jobs"}
16762 <- {"return": [{"current-progress": 1,
16763 "status": "concluded",
16764 "total-progress": 1,
16765 "type": "snapshot-delete",
16766 "id": "snapdelete0"}]}
16767 Since
16769 6.0
16770
16772 Abort (Object)
16773 This action can be used to test transaction failure.
16774 Since
16776 1.6
16777 ActionCompletionMode (Enum)
16779 An enumeration of Transactional completion modes.
16780 Values
16782 individual
16783 Do not attempt to cancel any other Actions if any Actions fail
16784 after the Transaction request succeeds. All Actions that can
16785 complete successfully will do so without waiting on others.
16786 This is the default.
16787 grouped
16789 If any Action fails after the Transaction succeeds, cancel all
16790 Actions. Actions do not complete until all Actions are ready to
16791 complete. May be rejected by Actions that do not support this
16792 completion mode.
16793 Since
16795 2.5
16796 TransactionActionKind (Enum)
16798 Values
16799 abort Since 1.6
16800 block-dirty-bitmap-add
16802 Since 2.5
16803 block-dirty-bitmap-remove
16805 Since 4.2
16806 block-dirty-bitmap-clear
16808 Since 2.5
16809 block-dirty-bitmap-enable
16811 Since 4.0
16812 block-dirty-bitmap-disable
16814 Since 4.0
16815 block-dirty-bitmap-merge
16817 Since 4.0
16818 blockdev-backup
16820 Since 2.3
16821 blockdev-snapshot
16823 Since 2.5
16824 blockdev-snapshot-internal-sync
16826 Since 1.7
16827 blockdev-snapshot-sync
16829 since 1.1
16830 drive-backup
16832 Since 1.6
16833 Features
16835 deprecated
16836 Member drive-backup is deprecated. Use member blockdev-backup
16837 instead.
16838 Since
16840 1.1
16841 AbortWrapper (Object)
16843 Members
16844 data: Abort
16845 Not documented
16846 Since
16848 1.6
16849 BlockDirtyBitmapAddWrapper (Object)
16851 Members
16852 data: BlockDirtyBitmapAdd
16853 Not documented
16854 Since
16856 2.5
16857 BlockDirtyBitmapWrapper (Object)
16859 Members
16860 data: BlockDirtyBitmap
16861 Not documented
16862 Since
16864 2.5
16865 BlockDirtyBitmapMergeWrapper (Object)
16867 Members
16868 data: BlockDirtyBitmapMerge
16869 Not documented
16870 Since
16872 4.0
16873 BlockdevBackupWrapper (Object)
16875 Members
16876 data: BlockdevBackup
16877 Not documented
16878 Since
16880 2.3
16881 BlockdevSnapshotWrapper (Object)
16883 Members
16884 data: BlockdevSnapshot
16885 Not documented
16886 Since
16888 2.5
16889 BlockdevSnapshotInternalWrapper (Object)
16891 Members
16892 data: BlockdevSnapshotInternal
16893 Not documented
16894 Since
16896 1.7
16897 BlockdevSnapshotSyncWrapper (Object)
16899 Members
16900 data: BlockdevSnapshotSync
16901 Not documented
16902 Since
16904 1.1
16905 DriveBackupWrapper (Object)
16907 Members
16908 data: DriveBackup
16909 Not documented
16910 Since
16912 1.6
16913 TransactionAction (Object)
16915 A discriminated record of operations that can be performed with trans‐
16916 action.
16917 Members
16919 type: TransactionActionKind
16920 Not documented
16921 The members of AbortWrapper when type is "abort"
16923 The members of BlockDirtyBitmapAddWrapper when type is
16925 "block-dirty-bitmap-add"
16926 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
16928 map-remove"
16929 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
16931 map-clear"
16932 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
16934 map-enable"
16935 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
16937 map-disable"
16938 The members of BlockDirtyBitmapMergeWrapper when type is
16940 "block-dirty-bitmap-merge"
16941 The members of BlockdevBackupWrapper when type is "blockdev-backup"
16943 The members of BlockdevSnapshotWrapper when type is "blockdev-snapshot"
16945 The members of BlockdevSnapshotInternalWrapper when type is "block‐
16947 dev-snapshot-internal-sync"
16948 The members of BlockdevSnapshotSyncWrapper when type is "blockdev-snap‐
16950 shot-sync"
16951 The members of DriveBackupWrapper when type is "drive-backup"
16953 Since
16955 1.1
16956 TransactionProperties (Object)
16958 Optional arguments to modify the behavior of a Transaction.
16959 Members
16961 completion-mode: ActionCompletionMode (optional)
16962 Controls how jobs launched asynchronously by Actions will com‐
16963 plete or fail as a group. See ActionCompletionMode for details.
16964 Since
16966 2.5
16967 transaction (Command)
16969 Executes a number of transactionable QMP commands atomically. If any
16970 operation fails, then the entire set of actions will be abandoned and
16971 the appropriate error returned.
16972 For external snapshots, the dictionary contains the device, the file to
16974 use for the new snapshot, and the format. The default format, if not
16975 specified, is qcow2.
16976 Each new snapshot defaults to being created by QEMU (wiping any con‐
16978 tents if the file already exists), but it is also possible to reuse an
16979 externally-created file. In the latter case, you should ensure that
16980 the new image file has the same contents as the current one; QEMU can‐
16981 not perform any meaningful check. Typically this is achieved by using
16982 the current image file as the backing file for the new image.
16983 On failure, the original disks pre-snapshot attempt will be used.
16985 For internal snapshots, the dictionary contains the device and the
16987 snapshot's name. If an internal snapshot matching name already exists,
16988 the request will be rejected. Only some image formats support it, for
16989 example, qcow2, and rbd,
16990 On failure, qemu will try delete the newly created internal snapshot in
16992 the transaction. When an I/O error occurs during deletion, the user
16993 needs to fix it later with qemu-img or other command.
16994 Arguments
16996 actions: array of TransactionAction
16997 List of TransactionAction; information needed for the respective
16998 operations.
16999 properties: TransactionProperties (optional)
17001 structure of additional options to control the execution of the
17002 transaction. See TransactionProperties for additional detail.
17003 Returns
17005 nothing on success
17006 Errors depend on the operations of the transaction
17008 Note
17010 The transaction aborts on the first failure. Therefore, there will be
17011 information on only one failed operation returned in an error condi‐
17012 tion, and subsequent actions will not have been attempted.
17013 Since
17015 1.1
17016 Example
17018 -> { "execute": "transaction",
17019 "arguments": { "actions": [
17020 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
17021 "snapshot-file": "/some/place/my-image",
17022 "format": "qcow2" } },
17023 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
17024 "snapshot-file": "/some/place/my-image2",
17025 "snapshot-node-name": "node3432",
17026 "mode": "existing",
17027 "format": "qcow2" } },
17028 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
17029 "snapshot-file": "/some/place/my-image2",
17030 "mode": "existing",
17031 "format": "qcow2" } },
17032 { "type": "blockdev-snapshot-internal-sync", "data" : {
17033 "device": "ide-hd2",
17034 "name": "snapshot0" } } ] } }
17035 <- { "return": {} }
17036
17038 TraceEventState (Enum)
17039 State of a tracing event.
17040 Values
17042 unavailable
17043 The event is statically disabled.
17044 disabled
17046 The event is dynamically disabled.
17047 enabled
17049 The event is dynamically enabled.
17050 Since
17052 2.2
17053 TraceEventInfo (Object)
17055 Information of a tracing event.
17056 Members
17058 name: string
17059 Event name.
17060 state: TraceEventState
17062 Tracing state.
17063 vcpu: boolean
17065 Whether this is a per-vCPU event (since 2.7).
17066 Features
17068 deprecated
17069 Member vcpu is deprecated, and always ignored.
17070 Since
17072 2.2
17073 trace-event-get-state (Command)
17075 Query the state of events.
17076 Arguments
17078 name: string
17079 Event name pattern (case-sensitive glob).
17080 vcpu: int (optional)
17082 The vCPU to query (since 2.7).
17083 Features
17085 deprecated
17086 Member vcpu is deprecated, and always ignored.
17087 Returns
17089 a list of TraceEventInfo for the matching events
17090 Since
17092 2.2
17093 Example
17095 -> { "execute": "trace-event-get-state",
17096 "arguments": { "name": "qemu_memalign" } }
17097 <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }
17098 trace-event-set-state (Command)
17100 Set the dynamic tracing state of events.
17101 Arguments
17103 name: string
17104 Event name pattern (case-sensitive glob).
17105 enable: boolean
17107 Whether to enable tracing.
17108 ignore-unavailable: boolean (optional)
17110 Do not match unavailable events with name.
17111 vcpu: int (optional)
17113 The vCPU to act upon (all by default; since 2.7).
17114 Features
17116 deprecated
17117 Member vcpu is deprecated, and always ignored.
17118 Since
17120 2.2
17121 Example
17123 -> { "execute": "trace-event-set-state",
17124 "arguments": { "name": "qemu_memalign", "enable": true } }
17125 <- { "return": {} }
17126
17128 CompatPolicyInput (Enum)
17129 Policy for handling "funny" input.
17130 Values
17132 accept Accept silently
17133 reject Reject with an error
17135 crash abort() the process
17137 Since
17139 6.0
17140 CompatPolicyOutput (Enum)
17142 Policy for handling "funny" output.
17143 Values
17145 accept Pass on unchanged
17146 hide Filter out
17148 Since
17150 6.0
17151 CompatPolicy (Object)
17153 Policy for handling deprecated management interfaces.
17154 This is intended for testing users of the management interfaces.
17156 Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
17158 with feature 'deprecated'. We may want to extend it to cover semantic
17159 aspects and CLI.
17160 Limitation: deprecated-output policy hide is not implemented for enu‐
17162 meration values. They behave the same as with policy accept.
17163 Members
17165 deprecated-input: CompatPolicyInput (optional)
17166 how to handle deprecated input (default 'accept')
17167 deprecated-output: CompatPolicyOutput (optional)
17169 how to handle deprecated output (default 'accept')
17170 unstable-input: CompatPolicyInput (optional)
17172 how to handle unstable input (default 'accept') (since 6.2)
17173 unstable-output: CompatPolicyOutput (optional)
17175 how to handle unstable output (default 'accept') (since 6.2)
17176 Since
17178 6.0
17179
17181 qmp_capabilities (Command)
17182 Enable QMP capabilities.
17183 Arguments:
17185 Arguments
17187 enable: array of QMPCapability (optional)
17188 An optional list of QMPCapability values to enable. The client
17189 must not enable any capability that is not mentioned in the QMP
17190 greeting message. If the field is not provided, it means no QMP
17191 capabilities will be enabled. (since 2.12)
17192 Example
17194 -> { "execute": "qmp_capabilities",
17195 "arguments": { "enable": [ "oob" ] } }
17196 <- { "return": {} }
17197 Notes
17199 This command is valid exactly when first connecting: it must be issued
17200 before any other command will be accepted, and will fail once the moni‐
17201 tor is accepting other commands. (see qemu docs/interop/qmp-spec.rst)
17202 The QMP client needs to explicitly enable QMP capabilities, otherwise
17204 all the QMP capabilities will be turned off by default.
17205 Since
17207 0.13
17208 QMPCapability (Enum)
17210 Enumeration of capabilities to be advertised during initial client con‐
17211 nection, used for agreeing on particular QMP extension behaviors.
17212 Values
17214 oob QMP ability to support out-of-band requests. (Please refer to
17215 qmp-spec.rst for more information on OOB)
17216 Since
17218 2.12
17219 VersionTriple (Object)
17221 A three-part version number.
17222 Members
17224 major: int
17225 The major version number.
17226 minor: int
17228 The minor version number.
17229 micro: int
17231 The micro version number.
17232 Since
17234 2.4
17235 VersionInfo (Object)
17237 A description of QEMU's version.
17238 Members
17240 qemu: VersionTriple
17241 The version of QEMU. By current convention, a micro version of
17242 50 signifies a development branch. A micro version greater than
17243 or equal to 90 signifies a release candidate for the next minor
17244 version. A micro version of less than 50 signifies a stable re‐
17245 lease.
17246 package: string
17248 QEMU will always set this field to an empty string. Downstream
17249 versions of QEMU should set this to a non-empty string. The ex‐
17250 act format depends on the downstream however it highly recom‐
17251 mended that a unique name is used.
17252 Since
17254 0.14
17255 query-version (Command)
17257 Returns the current version of QEMU.
17258 Returns
17260 A VersionInfo object describing the current version of QEMU.
17261 Since
17263 0.14
17264 Example
17266 -> { "execute": "query-version" }
17267 <- {
17268 "return":{
17269 "qemu":{
17270 "major":0,
17271 "minor":11,
17272 "micro":5
17273 },
17274 "package":""
17275 }
17276 }
17277 CommandInfo (Object)
17279 Information about a QMP command
17280 Members
17282 name: string
17283 The command name
17284 Since
17286 0.14
17287 query-commands (Command)
17289 Return a list of supported QMP commands by this server
17290 Returns
17292 A list of CommandInfo for all supported commands
17293 Since
17295 0.14
17296 Example
17298 -> { "execute": "query-commands" }
17299 <- {
17300 "return":[
17301 {
17302 "name":"query-balloon"
17303 },
17304 {
17305 "name":"system_powerdown"
17306 }
17307 ]
17308 }
17309 Note
17311 This example has been shortened as the real response is too long.
17312 quit (Command)
17314 This command will cause the QEMU process to exit gracefully. While ev‐
17315 ery attempt is made to send the QMP response before terminating, this
17316 is not guaranteed. When using this interface, a premature EOF would
17317 not be unexpected.
17318 Since
17320 0.14
17321 Example
17323 -> { "execute": "quit" }
17324 <- { "return": {} }
17325 MonitorMode (Enum)
17327 An enumeration of monitor modes.
17328 Values
17330 readline
17331 HMP monitor (human-oriented command line interface)
17332 control
17334 QMP monitor (JSON-based machine interface)
17335 Since
17337 5.0
17338 MonitorOptions (Object)
17340 Options to be used for adding a new monitor.
17341 Members
17343 id: string (optional)
17344 Name of the monitor
17345 mode: MonitorMode (optional)
17347 Selects the monitor mode (default: readline in the system emula‐
17348 tor, control in qemu-storage-daemon)
17349 pretty: boolean (optional)
17351 Enables pretty printing (QMP only)
17352 chardev: string
17354 Name of a character device to expose the monitor on
17355 Since
17357 5.0
17358
17360 query-qmp-schema (Command)
17361 Command query-qmp-schema exposes the QMP wire ABI as an array of
17362 SchemaInfo. This lets QMP clients figure out what commands and events
17363 are available in this QEMU, and their parameters and results.
17364 However, the SchemaInfo can't reflect all the rules and restrictions
17366 that apply to QMP. It's interface introspection (figuring out what's
17367 there), not interface specification. The specification is in the QAPI
17368 schema.
17369 Furthermore, while we strive to keep the QMP wire format backwards-com‐
17371 patible across qemu versions, the introspection output is not guaran‐
17372 teed to have the same stability. For example, one version of qemu may
17373 list an object member as an optional non-variant, while another lists
17374 the same member only through the object's variants; or the type of a
17375 member may change from a generic string into a specific enum or from
17376 one specific type into an alternate that includes the original type
17377 alongside something else.
17378 Returns
17380 array of SchemaInfo, where each element describes an entity in the ABI:
17381 command, event, type, ...
17382 The order of the various SchemaInfo is unspecified; however, all names
17384 are guaranteed to be unique (no name will be duplicated with different
17385 meta-types).
17386 Note
17388 the QAPI schema is also used to help define internal interfaces, by
17389 defining QAPI types. These are not part of the QMP wire ABI, and
17390 therefore not returned by this command.
17391 Since
17393 2.5
17394 SchemaMetaType (Enum)
17396 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
17397 Values
17399 builtin
17400 a predefined type such as 'int' or 'bool'.
17401 enum an enumeration type
17403 array an array type
17405 object an object type (struct or union)
17407 alternate
17409 an alternate type
17410 command
17412 a QMP command
17413 event a QMP event
17415 Since
17417 2.5
17418 SchemaInfo (Object)
17420 Members
17421 name: string
17422 the entity's name, inherited from base. The SchemaInfo is al‐
17423 ways referenced by this name. Commands and events have the name
17424 defined in the QAPI schema. Unlike command and event names,
17425 type names are not part of the wire ABI. Consequently, type
17426 names are meaningless strings here, although they are still
17427 guaranteed unique regardless of meta-type.
17428 meta-type: SchemaMetaType
17430 the entity's meta type, inherited from base.
17431 features: array of string (optional)
17433 names of features associated with the entity, in no particular
17434 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
17435 the rest)
17436 The members of SchemaInfoBuiltin when meta-type is "builtin"
17438 The members of SchemaInfoEnum when meta-type is "enum"
17440 The members of SchemaInfoArray when meta-type is "array"
17442 The members of SchemaInfoObject when meta-type is "object"
17444 The members of SchemaInfoAlternate when meta-type is "alternate"
17446 The members of SchemaInfoCommand when meta-type is "command"
17448 The members of SchemaInfoEvent when meta-type is "event"
17450 Additional members depend on the value of meta-type.
17451 Since
17453 2.5
17454 SchemaInfoBuiltin (Object)
17456 Additional SchemaInfo members for meta-type 'builtin'.
17457 Members
17459 json-type: JSONType
17460 the JSON type used for this type on the wire.
17461 Since
17463 2.5
17464 JSONType (Enum)
17466 The four primitive and two structured types according to RFC 8259 sec‐
17467 tion 1, plus 'int' (split off 'number'), plus the obvious top type
17468 'value'.
17469 Values
17471 string Not documented
17472 number Not documented
17474 int Not documented
17476 boolean
17478 Not documented
17479 null Not documented
17481 object Not documented
17483 array Not documented
17485 value Not documented
17487 Since
17489 2.5
17490 SchemaInfoEnum (Object)
17492 Additional SchemaInfo members for meta-type 'enum'.
17493 Members
17495 members: array of SchemaInfoEnumMember
17496 the enum type's members, in no particular order (since 6.2).
17497 values: array of string
17499 the enumeration type's member names, in no particular order.
17500 Redundant with members. Just for backward compatibility.
17501 Features
17503 deprecated
17504 Member values is deprecated. Use members instead.
17505 Values of this type are JSON string on the wire.
17506 Since
17508 2.5
17509 SchemaInfoEnumMember (Object)
17511 An object member.
17512 Members
17514 name: string
17515 the member's name, as defined in the QAPI schema.
17516 features: array of string (optional)
17518 names of features associated with the member, in no particular
17519 order.
17520 Since
17522 6.2
17523 SchemaInfoArray (Object)
17525 Additional SchemaInfo members for meta-type 'array'.
17526 Members
17528 element-type: string
17529 the array type's element type.
17530 Values of this type are JSON array on the wire.
17531 Since
17533 2.5
17534 SchemaInfoObject (Object)
17536 Additional SchemaInfo members for meta-type 'object'.
17537 Members
17539 members: array of SchemaInfoObjectMember
17540 the object type's (non-variant) members, in no particular order.
17541 tag: string (optional)
17543 the name of the member serving as type tag. An element of mem‐
17544 bers with this name must exist.
17545 variants: array of SchemaInfoObjectVariant (optional)
17547 variant members, i.e. additional members that depend on the type
17548 tag's value. Present exactly when tag is present. The variants
17549 are in no particular order, and may even differ from the order
17550 of the values of the enum type of the tag.
17551 Values of this type are JSON object on the wire.
17552 Since
17554 2.5
17555 SchemaInfoObjectMember (Object)
17557 An object member.
17558 Members
17560 name: string
17561 the member's name, as defined in the QAPI schema.
17562 type: string
17564 the name of the member's type.
17565 default: value (optional)
17567 default when used as command parameter. If absent, the parame‐
17568 ter is mandatory. If present, the value must be null. The pa‐
17569 rameter is optional, and behavior when it's missing is not spec‐
17570 ified here. Future extension: if present and non-null, the pa‐
17571 rameter is optional, and defaults to this value.
17572 features: array of string (optional)
17574 names of features associated with the member, in no particular
17575 order. (since 5.0)
17576 Since
17578 2.5
17579 SchemaInfoObjectVariant (Object)
17581 The variant members for a value of the type tag.
17582 Members
17584 case: string
17585 a value of the type tag.
17586 type: string
17588 the name of the object type that provides the variant members
17589 when the type tag has value case.
17590 Since
17592 2.5
17593 SchemaInfoAlternate (Object)
17595 Additional SchemaInfo members for meta-type 'alternate'.
17596 Members
17598 members: array of SchemaInfoAlternateMember
17599 the alternate type's members, in no particular order. The mem‐
17600 bers' wire encoding is distinct, see docs/de‐
17601 vel/qapi-code-gen.txt section Alternate types.
17602 On the wire, this can be any of the members.
17603 Since
17605 2.5
17606 SchemaInfoAlternateMember (Object)
17608 An alternate member.
17609 Members
17611 type: string
17612 the name of the member's type.
17613 Since
17615 2.5
17616 SchemaInfoCommand (Object)
17618 Additional SchemaInfo members for meta-type 'command'.
17619 Members
17621 arg-type: string
17622 the name of the object type that provides the command's parame‐
17623 ters.
17624 ret-type: string
17626 the name of the command's result type.
17627 allow-oob: boolean (optional)
17629 whether the command allows out-of-band execution, defaults to
17630 false (Since: 2.12)
17631 Since
17633 2.5
17634 SchemaInfoEvent (Object)
17636 Additional SchemaInfo members for meta-type 'event'.
17637 Members
17639 arg-type: string
17640 the name of the object type that provides the event's parame‐
17641 ters.
17642 Since
17644 2.5
17645
17647 ObjectPropertyInfo (Object)
17648 Members
17649 name: string
17650 the name of the property
17651 type: string
17653 the type of the property. This will typically come in one of
17654 four forms:
17655 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
17657 ble'. These types are mapped to the appropriate JSON type.
17658 2. A child type in the form 'child<subtype>' where subtype is a
17660 qdev device type name. Child properties create the composi‐
17661 tion tree.
17662 3. A link type in the form 'link<subtype>' where subtype is a
17664 qdev device type name. Link properties form the device model
17665 graph.
17666 description: string (optional)
17668 if specified, the description of the property.
17669 default-value: value (optional)
17671 the default value, if any (since 5.0)
17672 Since
17674 1.2
17675 qom-list (Command)
17677 This command will list any properties of a object given a path in the
17678 object model.
17679 Arguments
17681 path: string
17682 the path within the object model. See qom-get for a description
17683 of this parameter.
17684 Returns
17686 a list of ObjectPropertyInfo that describe the properties of the ob‐
17687 ject.
17688 Since
17690 1.2
17691 Example
17693 -> { "execute": "qom-list",
17694 "arguments": { "path": "/chardevs" } }
17695 <- { "return": [ { "name": "type", "type": "string" },
17696 { "name": "parallel0", "type": "child<chardev-vc>" },
17697 { "name": "serial0", "type": "child<chardev-vc>" },
17698 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
17699 qom-get (Command)
17701 This command will get a property from a object model path and return
17702 the value.
17703 Arguments
17705 path: string
17706 The path within the object model. There are two forms of sup‐
17707 ported paths--absolute and partial paths.
17708 Absolute paths are derived from the root object and can follow
17710 child<> or link<> properties. Since they can follow link<>
17711 properties, they can be arbitrarily long. Absolute paths look
17712 like absolute filenames and are prefixed with a leading slash.
17713 Partial paths look like relative filenames. They do not begin
17715 with a prefix. The matching rules for partial paths are subtle
17716 but designed to make specifying objects easy. At each level of
17717 the composition tree, the partial path is matched as an absolute
17718 path. The first match is not returned. At least two matches
17719 are searched for. A successful result is only returned if only
17720 one match is found. If more than one match is found, a flag is
17721 return to indicate that the match was ambiguous.
17722 property: string
17724 The property name to read
17725 Returns
17727 The property value. The type depends on the property type. child<>
17728 and link<> properties are returned as #str pathnames. All integer
17729 property types (u8, u16, etc) are returned as #int.
17730 Since
17732 1.2
17733 Examples
17735 1. Use absolute path
17736 -> { "execute": "qom-get",
17738 "arguments": { "path": "/machine/unattached/device[0]",
17739 "property": "hotplugged" } }
17740 <- { "return": false }
17741 2. Use partial path
17743 -> { "execute": "qom-get",
17745 "arguments": { "path": "unattached/sysbus",
17746 "property": "type" } }
17747 <- { "return": "System" }
17748 qom-set (Command)
17750 This command will set a property from a object model path.
17751 Arguments
17753 path: string
17754 see qom-get for a description of this parameter
17755 property: string
17757 the property name to set
17758 value: value
17760 a value who's type is appropriate for the property type. See
17761 qom-get for a description of type mapping.
17762 Since
17764 1.2
17765 Example
17767 -> { "execute": "qom-set",
17768 "arguments": { "path": "/machine",
17769 "property": "graphics",
17770 "value": false } }
17771 <- { "return": {} }
17772 ObjectTypeInfo (Object)
17774 This structure describes a search result from qom-list-types
17775 Members
17777 name: string
17778 the type name found in the search
17779 abstract: boolean (optional)
17781 the type is abstract and can't be directly instantiated. Omit‐
17782 ted if false. (since 2.10)
17783 parent: string (optional)
17785 Name of parent type, if any (since 2.10)
17786 Since
17788 1.1
17789 qom-list-types (Command)
17791 This command will return a list of types given search parameters
17792 Arguments
17794 implements: string (optional)
17795 if specified, only return types that implement this type name
17796 abstract: boolean (optional)
17798 if true, include abstract types in the results
17799 Returns
17801 a list of ObjectTypeInfo or an empty list if no results are found
17802 Since
17804 1.1
17805 qom-list-properties (Command)
17807 List properties associated with a QOM object.
17808 Arguments
17810 typename: string
17811 the type name of an object
17812 Note
17814 objects can create properties at runtime, for example to describe links
17815 between different devices and/or objects. These properties are not in‐
17816 cluded in the output of this command.
17817 Returns
17819 a list of ObjectPropertyInfo describing object properties
17820 Since
17822 2.12
17823 CanHostSocketcanProperties (Object)
17825 Properties for can-host-socketcan objects.
17826 Members
17828 if: string
17829 interface name of the host system CAN bus to connect to
17830 canbus: string
17832 object ID of the can-bus object to connect to the host interface
17833 Since
17835 2.12
17836 ColoCompareProperties (Object)
17838 Properties for colo-compare objects.
17839 Members
17841 primary_in: string
17842 name of the character device backend to use for the primary in‐
17843 put (incoming packets are redirected to outdev)
17844 secondary_in: string
17846 name of the character device backend to use for secondary input
17847 (incoming packets are only compared to the input on primary_in
17848 and then dropped)
17849 outdev: string
17851 name of the character device backend to use for output
17852 iothread: string
17854 name of the iothread to run in
17855 notify_dev: string (optional)
17857 name of the character device backend to be used to communicate
17858 with the remote colo-frame (only for Xen COLO)
17859 compare_timeout: int (optional)
17861 the maximum time to hold a packet from primary_in for comparison
17862 with an incoming packet on secondary_in in milliseconds (de‐
17863 fault: 3000)
17864 expired_scan_cycle: int (optional)
17866 the interval at which colo-compare checks whether packets from
17867 primary have timed out, in milliseconds (default: 3000)
17868 max_queue_size: int (optional)
17870 the maximum number of packets to keep in the queue for comparing
17871 with incoming packets from secondary_in. If the queue is full
17872 and additional packets are received, the additional packets are
17873 dropped. (default: 1024)
17874 vnet_hdr_support: boolean (optional)
17876 if true, vnet header support is enabled (default: false)
17877 Since
17879 2.8
17880 CryptodevBackendProperties (Object)
17882 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
17883 Members
17885 queues: int (optional)
17886 the number of queues for the cryptodev backend. Ignored for
17887 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
17888 (default: 1)
17889 throttle-bps: int (optional)
17891 limit total bytes per second (Since 8.0)
17892 throttle-ops: int (optional)
17894 limit total operations per second (Since 8.0)
17895 Since
17897 2.8
17898 CryptodevVhostUserProperties (Object)
17900 Properties for cryptodev-vhost-user objects.
17901 Members
17903 chardev: string
17904 the name of a Unix domain socket character device that connects
17905 to the vhost-user server
17906 The members of CryptodevBackendProperties
17908 Since
17910 2.12
17911 DBusVMStateProperties (Object)
17913 Properties for dbus-vmstate objects.
17914 Members
17916 addr: string
17917 the name of the DBus bus to connect to
17918 id-list: string (optional)
17920 a comma separated list of DBus IDs of helpers whose data should
17921 be included in the VM state on migration
17922 Since
17924 5.0
17925 NetfilterInsert (Enum)
17927 Indicates where to insert a netfilter relative to a given other filter.
17928 Values
17930 before insert before the specified filter
17931 behind insert behind the specified filter
17933 Since
17935 5.0
17936 NetfilterProperties (Object)
17938 Properties for objects of classes derived from netfilter.
17939 Members
17941 netdev: string
17942 id of the network device backend to filter
17943 queue: NetFilterDirection (optional)
17945 indicates which queue(s) to filter (default: all)
17946 status: string (optional)
17948 indicates whether the filter is enabled ("on") or disabled
17949 ("off") (default: "on")
17950 position: string (optional)
17952 specifies where the filter should be inserted in the filter
17953 list. "head" means the filter is inserted at the head of the
17954 filter list, before any existing filters. "tail" means the fil‐
17955 ter is inserted at the tail of the filter list, behind any ex‐
17956 isting filters (default). "id=<id>" means the filter is inserted
17957 before or behind the filter specified by <id>, depending on the
17958 insert property. (default: "tail")
17959 insert: NetfilterInsert (optional)
17961 where to insert the filter relative to the filter given in posi‐
17962 tion. Ignored if position is "head" or "tail". (default: be‐
17963 hind)
17964 Since
17966 2.5
17967 FilterBufferProperties (Object)
17969 Properties for filter-buffer objects.
17970 Members
17972 interval: int
17973 a non-zero interval in microseconds. All packets arriving in
17974 the given interval are delayed until the end of the interval.
17975 The members of NetfilterProperties
17977 Since
17979 2.5
17980 FilterDumpProperties (Object)
17982 Properties for filter-dump objects.
17983 Members
17985 file: string
17986 the filename where the dumped packets should be stored
17987 maxlen: int (optional)
17989 maximum number of bytes in a packet that are stored (default:
17990 65536)
17991 The members of NetfilterProperties
17993 Since
17995 2.5
17996 FilterMirrorProperties (Object)
17998 Properties for filter-mirror objects.
17999 Members
18001 outdev: string
18002 the name of a character device backend to which all incoming
18003 packets are mirrored
18004 vnet_hdr_support: boolean (optional)
18006 if true, vnet header support is enabled (default: false)
18007 The members of NetfilterProperties
18009 Since
18011 2.6
18012 FilterRedirectorProperties (Object)
18014 Properties for filter-redirector objects.
18015 At least one of indev or outdev must be present. If both are present,
18017 they must not refer to the same character device backend.
18018 Members
18020 indev: string (optional)
18021 the name of a character device backend from which packets are
18022 received and redirected to the filtered network device
18023 outdev: string (optional)
18025 the name of a character device backend to which all incoming
18026 packets are redirected
18027 vnet_hdr_support: boolean (optional)
18029 if true, vnet header support is enabled (default: false)
18030 The members of NetfilterProperties
18032 Since
18034 2.6
18035 FilterRewriterProperties (Object)
18037 Properties for filter-rewriter objects.
18038 Members
18040 vnet_hdr_support: boolean (optional)
18041 if true, vnet header support is enabled (default: false)
18042 The members of NetfilterProperties
18044 Since
18046 2.8
18047 InputBarrierProperties (Object)
18049 Properties for input-barrier objects.
18050 Members
18052 name: string
18053 the screen name as declared in the screens section of bar‐
18054 rier.conf
18055 server: string (optional)
18057 hostname of the Barrier server (default: "localhost")
18058 port: string (optional)
18060 TCP port of the Barrier server (default: "24800")
18061 x-origin: string (optional)
18063 x coordinate of the leftmost pixel on the guest screen (default:
18064 "0")
18065 y-origin: string (optional)
18067 y coordinate of the topmost pixel on the guest screen (default:
18068 "0")
18069 width: string (optional)
18071 the width of secondary screen in pixels (default: "1920")
18072 height: string (optional)
18074 the height of secondary screen in pixels (default: "1080")
18075 Since
18077 4.2
18078 InputLinuxProperties (Object)
18080 Properties for input-linux objects.
18081 Members
18083 evdev: string
18084 the path of the host evdev device to use
18085 grab_all: boolean (optional)
18087 if true, grab is toggled for all devices (e.g. both keyboard and
18088 mouse) instead of just one device (default: false)
18089 repeat: boolean (optional)
18091 enables auto-repeat events (default: false)
18092 grab-toggle: GrabToggleKeys (optional)
18094 the key or key combination that toggles device grab (default:
18095 ctrl-ctrl)
18096 Since
18098 2.6
18099 EventLoopBaseProperties (Object)
18101 Common properties for event loops
18102 Members
18104 aio-max-batch: int (optional)
18105 maximum number of requests in a batch for the AIO engine, 0
18106 means that the engine will use its default. (default: 0)
18107 thread-pool-min: int (optional)
18109 minimum number of threads reserved in the thread pool (de‐
18110 fault:0)
18111 thread-pool-max: int (optional)
18113 maximum number of threads the thread pool can contain (de‐
18114 fault:64)
18115 Since
18117 7.1
18118 IothreadProperties (Object)
18120 Properties for iothread objects.
18121 Members
18123 poll-max-ns: int (optional)
18124 the maximum number of nanoseconds to busy wait for events. 0
18125 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
18126 erwise)
18127 poll-grow: int (optional)
18129 the multiplier used to increase the polling time when the algo‐
18130 rithm detects it is missing events due to not polling long
18131 enough. 0 selects a default behaviour (default: 0)
18132 poll-shrink: int (optional)
18134 the divisor used to decrease the polling time when the algorithm
18135 detects it is spending too long polling without encountering
18136 events. 0 selects a default behaviour (default: 0)
18137 The members of EventLoopBaseProperties
18139 The aio-max-batch option is available since 6.1.
18140 Since
18142 2.0
18143 MainLoopProperties (Object)
18145 Properties for the main-loop object.
18146 Members
18148 The members of EventLoopBaseProperties
18149 Since
18151 7.1
18152 MemoryBackendProperties (Object)
18154 Properties for objects of classes derived from memory-backend.
18155 Members
18157 merge: boolean (optional)
18158 if true, mark the memory as mergeable (default depends on the
18159 machine type)
18160 dump: boolean (optional)
18162 if true, include the memory in core dumps (default depends on
18163 the machine type)
18164 host-nodes: array of int (optional)
18166 the list of NUMA host nodes to bind the memory to
18167 policy: HostMemPolicy (optional)
18169 the NUMA policy (default: 'default')
18170 prealloc: boolean (optional)
18172 if true, preallocate memory (default: false)
18173 prealloc-threads: int (optional)
18175 number of CPU threads to use for prealloc (default: 1)
18176 prealloc-context: string (optional)
18178 thread context to use for creation of preallocation threads (de‐
18179 fault: none) (since 7.2)
18180 share: boolean (optional)
18182 if false, the memory is private to QEMU; if true, it is shared
18183 (default: false)
18184 reserve: boolean (optional)
18186 if true, reserve swap space (or huge pages) if applicable (de‐
18187 fault: true) (since 6.1)
18188 size: int
18190 size of the memory region in bytes
18191 x-use-canonical-path-for-ramblock-id: boolean (optional)
18193 if true, the canonical path is used for ramblock-id. Disable
18194 this for 4.0 machine types or older to allow migration with
18195 newer QEMU versions. (default: false generally, but true for
18196 machine types <= 4.0)
18197 Note
18199 prealloc=true and reserve=false cannot be set at the same time. With
18200 reserve=true, the behavior depends on the operating system: for exam‐
18201 ple, Linux will not reserve swap space for shared file mappings -- "not
18202 applicable". In contrast, reserve=false will bail out if it cannot be
18203 configured accordingly.
18204 Since
18206 2.1
18207 MemoryBackendFileProperties (Object)
18209 Properties for memory-backend-file objects.
18210 Members
18212 align: int (optional)
18213 the base address alignment when QEMU mmap(2)s mem-path. Some
18214 backend stores specified by mem-path require an alignment dif‐
18215 ferent than the default one used by QEMU, e.g. the device DAX
18216 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
18217 users can specify the required alignment via this option. 0 se‐
18218 lects a default alignment (currently the page size). (default:
18219 0)
18220 offset: int (optional)
18222 the offset into the target file that the region starts at. You
18223 can use this option to back multiple regions with a single file.
18224 Must be a multiple of the page size. (default: 0) (since 8.1)
18225 discard-data: boolean (optional)
18227 if true, the file contents can be destroyed when QEMU exits, to
18228 avoid unnecessarily flushing data to the backing file. Note
18229 that discard-data is only an optimization, and QEMU might not
18230 discard file contents if it aborts unexpectedly or is terminated
18231 using SIGKILL. (default: false)
18232 mem-path: string
18234 the path to either a shared memory or huge page filesystem mount
18235 pmem: boolean (optional) (If: CONFIG_LIBPMEM)
18237 specifies whether the backing file specified by mem-path is in
18238 host persistent memory that can be accessed using the SNIA NVM
18239 programming model (e.g. Intel NVDIMM).
18240 readonly: boolean (optional)
18242 if true, the backing file is opened read-only; if false, it is
18243 opened read-write. (default: false)
18244 The members of MemoryBackendProperties
18246 Since
18248 2.1
18249 MemoryBackendMemfdProperties (Object)
18251 Properties for memory-backend-memfd objects.
18252 The share boolean option is true by default with memfd.
18254 Members
18256 hugetlb: boolean (optional)
18257 if true, the file to be created resides in the hugetlbfs
18258 filesystem (default: false)
18259 hugetlbsize: int (optional)
18261 the hugetlb page size on systems that support multiple hugetlb
18262 page sizes (it must be a power of 2 value supported by the sys‐
18263 tem). 0 selects a default page size. This option is ignored if
18264 hugetlb is false. (default: 0)
18265 seal: boolean (optional)
18267 if true, create a sealed-file, which will block further resizing
18268 of the memory (default: true)
18269 The members of MemoryBackendProperties
18271 Since
18273 2.12
18274 MemoryBackendEpcProperties (Object)
18276 Properties for memory-backend-epc objects.
18277 The share boolean option is true by default with epc
18279 The merge boolean option is false by default with epc
18281 The dump boolean option is false by default with epc
18283 Members
18285 The members of MemoryBackendProperties
18286 Since
18288 6.2
18289 PrManagerHelperProperties (Object)
18291 Properties for pr-manager-helper objects.
18292 Members
18294 path: string
18295 the path to a Unix domain socket for connecting to the external
18296 helper
18297 Since
18299 2.11
18300 QtestProperties (Object)
18302 Properties for qtest objects.
18303 Members
18305 chardev: string
18306 the chardev to be used to receive qtest commands on.
18307 log: string (optional)
18309 the path to a log file
18310 Since
18312 6.0
18313 RemoteObjectProperties (Object)
18315 Properties for x-remote-object objects.
18316 Members
18318 fd: string
18319 file descriptor name previously passed via 'getfd' command
18320 devid: string
18322 the id of the device to be associated with the file descriptor
18323 Since
18325 6.0
18326 VfioUserServerProperties (Object)
18328 Properties for x-vfio-user-server objects.
18329 Members
18331 socket: SocketAddress
18332 socket to be used by the libvfio-user library
18333 device: string
18335 the ID of the device to be emulated at the server
18336 Since
18338 7.1
18339 RngProperties (Object)
18341 Properties for objects of classes derived from rng.
18342 Members
18344 opened: boolean (optional)
18345 if true, the device is opened immediately when applying this op‐
18346 tion and will probably fail when processing the next option.
18347 Don't use; only provided for compatibility. (default: false)
18348 Features
18350 deprecated
18351 Member opened is deprecated. Setting true doesn't make sense,
18352 and false is already the default.
18353 Since
18355 1.3
18356 RngEgdProperties (Object)
18358 Properties for rng-egd objects.
18359 Members
18361 chardev: string
18362 the name of a character device backend that provides the connec‐
18363 tion to the RNG daemon
18364 The members of RngProperties
18366 Since
18368 1.3
18369 RngRandomProperties (Object)
18371 Properties for rng-random objects.
18372 Members
18374 filename: string (optional)
18375 the filename of the device on the host to obtain entropy from
18376 (default: "/dev/urandom")
18377 The members of RngProperties
18379 Since
18381 1.3
18382 SevGuestProperties (Object)
18384 Properties for sev-guest objects.
18385 Members
18387 sev-device: string (optional)
18388 SEV device to use (default: "/dev/sev")
18389 dh-cert-file: string (optional)
18391 guest owners DH certificate (encoded with base64)
18392 session-file: string (optional)
18394 guest owners session parameters (encoded with base64)
18395 policy: int (optional)
18397 SEV policy value (default: 0x1)
18398 handle: int (optional)
18400 SEV firmware handle (default: 0)
18401 cbitpos: int (optional)
18403 C-bit location in page table entry (default: 0)
18404 reduced-phys-bits: int
18406 number of bits in physical addresses that become unavailable
18407 when SEV is enabled
18408 kernel-hashes: boolean (optional)
18410 if true, add hashes of kernel/initrd/cmdline to a designated
18411 guest firmware page for measured boot with -kernel (default:
18412 false) (since 6.2)
18413 Since
18415 2.12
18416 ThreadContextProperties (Object)
18418 Properties for thread context objects.
18419 Members
18421 cpu-affinity: array of int (optional)
18422 the list of host CPU numbers used as CPU affinity for all
18423 threads created in the thread context (default: QEMU main thread
18424 CPU affinity)
18425 node-affinity: array of int (optional)
18427 the list of host node numbers that will be resolved to a list of
18428 host CPU numbers used as CPU affinity. This is a shortcut for
18429 specifying the list of host CPU numbers belonging to the host
18430 nodes manually by setting cpu-affinity. (default: QEMU main
18431 thread affinity)
18432 Since
18434 7.2
18435 ObjectType (Enum)
18437 Values
18438 authz-list
18439 Not documented
18440 authz-listfile
18442 Not documented
18443 authz-pam
18445 Not documented
18446 authz-simple
18448 Not documented
18449 can-bus
18451 Not documented
18452 can-host-socketcan (If: CONFIG_LINUX)
18454 Not documented
18455 colo-compare
18457 Not documented
18458 cryptodev-backend
18460 Not documented
18461 cryptodev-backend-builtin
18463 Not documented
18464 cryptodev-backend-lkcf
18466 Not documented
18467 cryptodev-vhost-user (If: CONFIG_VHOST_CRYPTO)
18469 Not documented
18470 dbus-vmstate
18472 Not documented
18473 filter-buffer
18475 Not documented
18476 filter-dump
18478 Not documented
18479 filter-mirror
18481 Not documented
18482 filter-redirector
18484 Not documented
18485 filter-replay
18487 Not documented
18488 filter-rewriter
18490 Not documented
18491 input-barrier
18493 Not documented
18494 input-linux (If: CONFIG_LINUX)
18496 Not documented
18497 iothread
18499 Not documented
18500 main-loop
18502 Not documented
18503 memory-backend-epc (If: CONFIG_LINUX)
18505 Not documented
18506 memory-backend-file
18508 Not documented
18509 memory-backend-memfd (If: CONFIG_LINUX)
18511 Not documented
18512 memory-backend-ram
18514 Not documented
18515 pef-guest
18517 Not documented
18518 pr-manager-helper (If: CONFIG_LINUX)
18520 Not documented
18521 qtest Not documented
18523 rng-builtin
18525 Not documented
18526 rng-egd
18528 Not documented
18529 rng-random (If: CONFIG_POSIX)
18531 Not documented
18532 secret Not documented
18534 secret_keyring (If: CONFIG_SECRET_KEYRING)
18536 Not documented
18537 sev-guest
18539 Not documented
18540 thread-context
18542 Not documented
18543 s390-pv-guest
18545 Not documented
18546 throttle-group
18548 Not documented
18549 tls-creds-anon
18551 Not documented
18552 tls-creds-psk
18554 Not documented
18555 tls-creds-x509
18557 Not documented
18558 tls-cipher-suites
18560 Not documented
18561 x-remote-object
18563 Not documented
18564 x-vfio-user-server
18566 Not documented
18567 Features
18569 unstable
18570 Member x-remote-object is experimental.
18571 Since
18573 6.0
18574 ObjectOptions (Object)
18576 Describes the options of a user creatable QOM object.
18577 Members
18579 qom-type: ObjectType
18580 the class name for the object to be created
18581 id: string
18583 the name of the new object
18584 The members of AuthZListProperties when qom-type is "authz-list"
18586 The members of AuthZListFileProperties when qom-type is "authz-list‐
18588 file"
18589 The members of AuthZPAMProperties when qom-type is "authz-pam"
18591 The members of AuthZSimpleProperties when qom-type is "authz-simple"
18593 The members of CanHostSocketcanProperties when qom-type is
18595 "can-host-socketcan" (If: CONFIG_LINUX)
18596 The members of ColoCompareProperties when qom-type is "colo-compare"
18598 The members of CryptodevBackendProperties when qom-type is "cryp‐
18600 todev-backend"
18601 The members of CryptodevBackendProperties when qom-type is "cryp‐
18603 todev-backend-builtin"
18604 The members of CryptodevBackendProperties when qom-type is "cryp‐
18606 todev-backend-lkcf"
18607 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
18609 todev-vhost-user" (If: CONFIG_VHOST_CRYPTO)
18610 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
18612 The members of FilterBufferProperties when qom-type is "filter-buffer"
18614 The members of FilterDumpProperties when qom-type is "filter-dump"
18616 The members of FilterMirrorProperties when qom-type is "filter-mirror"
18618 The members of FilterRedirectorProperties when qom-type is "fil‐
18620 ter-redirector"
18621 The members of NetfilterProperties when qom-type is "filter-replay"
18623 The members of FilterRewriterProperties when qom-type is "fil‐
18625 ter-rewriter"
18626 The members of InputBarrierProperties when qom-type is "input-barrier"
18628 The members of InputLinuxProperties when qom-type is "input-linux" (If:
18630 CONFIG_LINUX)
18631 The members of IothreadProperties when qom-type is "iothread"
18633 The members of MainLoopProperties when qom-type is "main-loop"
18635 The members of MemoryBackendEpcProperties when qom-type is "mem‐
18637 ory-backend-epc" (If: CONFIG_LINUX)
18638 The members of MemoryBackendFileProperties when qom-type is "mem‐
18640 ory-backend-file"
18641 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
18643 ory-backend-memfd" (If: CONFIG_LINUX)
18644 The members of MemoryBackendProperties when qom-type is "memory-back‐
18646 end-ram"
18647 The members of PrManagerHelperProperties when qom-type is "pr-man‐
18649 ager-helper" (If: CONFIG_LINUX)
18650 The members of QtestProperties when qom-type is "qtest"
18652 The members of RngProperties when qom-type is "rng-builtin"
18654 The members of RngEgdProperties when qom-type is "rng-egd"
18656 The members of RngRandomProperties when qom-type is "rng-random" (If:
18658 CONFIG_POSIX)
18659 The members of SecretProperties when qom-type is "secret"
18661 The members of SecretKeyringProperties when qom-type is "se‐
18663 cret_keyring" (If: CONFIG_SECRET_KEYRING)
18664 The members of SevGuestProperties when qom-type is "sev-guest"
18666 The members of ThreadContextProperties when qom-type is "thread-con‐
18668 text"
18669 The members of ThrottleGroupProperties when qom-type is "throt‐
18671 tle-group"
18672 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
18674 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
18676 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
18678 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
18680 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
18682 ject"
18683 The members of VfioUserServerProperties when qom-type is
18685 "x-vfio-user-server"
18686 Since
18688 6.0
18689 object-add (Command)
18691 Create a QOM object.
18692 Arguments
18694 The members of ObjectOptions
18695 Returns
18697 Nothing on success Error if qom-type is not a valid class name
18698 Since
18700 2.0
18701 Example
18703 -> { "execute": "object-add",
18704 "arguments": { "qom-type": "rng-random", "id": "rng1",
18705 "filename": "/dev/hwrng" } }
18706 <- { "return": {} }
18707 object-del (Command)
18709 Remove a QOM object.
18710 Arguments
18712 id: string
18713 the name of the QOM object to remove
18714 Returns
18716 Nothing on success Error if id is not a valid id for a QOM object
18717 Since
18719 2.0
18720 Example
18722 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
18723 <- { "return": {} }
18724
18726 device-list-properties (Command)
18727 List properties associated with a device.
18728 Arguments
18730 typename: string
18731 the type name of a device
18732 Returns
18734 a list of ObjectPropertyInfo describing a devices properties
18735 Note
18737 objects can create properties at runtime, for example to describe links
18738 between different devices and/or objects. These properties are not in‐
18739 cluded in the output of this command.
18740 Since
18742 1.2
18743 device_add (Command)
18745 Add a device.
18746 Arguments
18748 driver: string
18749 the name of the new device's driver
18750 bus: string (optional)
18752 the device's parent bus (device tree path)
18753 id: string (optional)
18755 the device's ID, must be unique
18756 Features
18758 json-cli
18759 If present, the "-device" command line option supports JSON syn‐
18760 tax with a structure identical to the arguments of this command.
18761 json-cli-hotplug
18763 If present, the "-device" command line option supports JSON syn‐
18764 tax without the reference counting leak that broke hot-unplug
18765 Notes
18767 1. Additional arguments depend on the type.
18768 2. For detailed information about this command, please refer to the
18770 'docs/qdev-device-use.txt' file.
18771 3. It's possible to list device properties by running QEMU with the
18773 "-device DEVICE,help" command-line argument, where DEVICE is the de‐
18774 vice's name
18775 Example
18777 -> { "execute": "device_add",
18778 "arguments": { "driver": "e1000", "id": "net1",
18779 "bus": "pci.0",
18780 "mac": "52:54:00:12:34:56" } }
18781 <- { "return": {} }
18782 Since
18784 0.13
18785 device_del (Command)
18787 Remove a device from a guest
18788 Arguments
18790 id: string
18791 the device's ID or QOM path
18792 Returns
18794 Nothing on success If id is not a valid device, DeviceNotFound
18795 Notes
18797 When this command completes, the device may not be removed from the
18798 guest. Hot removal is an operation that requires guest cooperation.
18799 This command merely requests that the guest begin the hot removal
18800 process. Completion of the device removal process is signaled with a
18801 DEVICE_DELETED event. Guest reset will automatically complete removal
18802 for all devices. If a guest-side error in the hot removal process is
18803 detected, the device will not be removed and a DEVICE_UNPLUG_GUEST_ER‐
18804 ROR event is sent. Some errors cannot be detected.
18805 Since
18807 0.14
18808 Examples
18810 -> { "execute": "device_del",
18811 "arguments": { "id": "net1" } }
18812 <- { "return": {} }
18813 -> { "execute": "device_del",
18815 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
18816 <- { "return": {} }
18817 DEVICE_DELETED (Event)
18819 Emitted whenever the device removal completion is acknowledged by the
18820 guest. At this point, it's safe to reuse the specified device ID. De‐
18821 vice removal can be initiated by the guest or by HMP/QMP commands.
18822 Arguments
18824 device: string (optional)
18825 the device's ID if it has one
18826 path: string
18828 the device's QOM path
18829 Since
18831 1.5
18832 Example
18834 <- { "event": "DEVICE_DELETED",
18835 "data": { "device": "virtio-net-pci-0",
18836 "path": "/machine/peripheral/virtio-net-pci-0" },
18837 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
18838 DEVICE_UNPLUG_GUEST_ERROR (Event)
18840 Emitted when a device hot unplug fails due to a guest reported error.
18841 Arguments
18843 device: string (optional)
18844 the device's ID if it has one
18845 path: string
18847 the device's QOM path
18848 Since
18850 6.2
18851 Example
18853 <- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
18854 "data": { "device": "core1",
18855 "path": "/machine/peripheral/core1" },
18856 "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
18857
18859 SysEmuTarget (Enum)
18860 The comprehensive enumeration of QEMU system emulation ("softmmu") tar‐
18861 gets. Run "./configure --help" in the project root directory, and look
18862 for the *-softmmu targets near the "--target-list" option. The indi‐
18863 vidual target constants are not documented here, for the time being.
18864 Values
18866 rx since 5.0
18867 avr since 5.1
18869 aarch64
18871 Not documented
18872 alpha Not documented
18874 arm Not documented
18876 cris Not documented
18878 hppa Not documented
18880 i386 Not documented
18882 loongarch64
18884 Not documented
18885 m68k Not documented
18887 microblaze
18889 Not documented
18890 microblazeel
18892 Not documented
18893 mips Not documented
18895 mips64 Not documented
18897 mips64el
18899 Not documented
18900 mipsel Not documented
18902 nios2 Not documented
18904 or1k Not documented
18906 ppc Not documented
18908 ppc64 Not documented
18910 riscv32
18912 Not documented
18913 riscv64
18915 Not documented
18916 s390x Not documented
18918 sh4 Not documented
18920 sh4eb Not documented
18922 sparc Not documented
18924 sparc64
18926 Not documented
18927 tricore
18929 Not documented
18930 x86_64 Not documented
18932 xtensa Not documented
18934 xtensaeb
18936 Not documented
18937 Notes
18939 The resulting QMP strings can be appended to the "qemu-system-" prefix
18940 to produce the corresponding QEMU executable name. This is true even
18941 for "qemu-system-x86_64".
18942 Since
18944 3.0
18945 CpuS390State (Enum)
18947 An enumeration of cpu states that can be assumed by a virtual S390 CPU
18948 Values
18950 uninitialized
18951 Not documented
18952 stopped
18954 Not documented
18955 check-stop
18957 Not documented
18958 operating
18960 Not documented
18961 load Not documented
18963 Since
18965 2.12
18966 CpuInfoS390 (Object)
18968 Additional information about a virtual S390 CPU
18969 Members
18971 cpu-state: CpuS390State
18972 the virtual CPU's state
18973 Since
18975 2.12
18976 CpuInfoFast (Object)
18978 Information about a virtual CPU
18979 Members
18981 cpu-index: int
18982 index of the virtual CPU
18983 qom-path: string
18985 path to the CPU object in the QOM tree
18986 thread-id: int
18988 ID of the underlying host thread
18989 props: CpuInstanceProperties (optional)
18991 properties describing to which node/socket/core/thread virtual
18992 CPU belongs to, provided if supported by board
18993 target: SysEmuTarget
18995 the QEMU system emulation target, which determines which addi‐
18996 tional fields will be listed (since 3.0)
18997 The members of CpuInfoS390 when target is "s390x"
18999 Since
19001 2.12
19002 query-cpus-fast (Command)
19004 Returns information about all virtual CPUs.
19005 Returns
19007 list of CpuInfoFast
19008 Since
19010 2.12
19011 Example
19013 -> { "execute": "query-cpus-fast" }
19014 <- { "return": [
19015 {
19016 "thread-id": 25627,
19017 "props": {
19018 "core-id": 0,
19019 "thread-id": 0,
19020 "socket-id": 0
19021 },
19022 "qom-path": "/machine/unattached/device[0]",
19023 "target":"x86_64",
19024 "cpu-index": 0
19025 },
19026 {
19027 "thread-id": 25628,
19028 "props": {
19029 "core-id": 0,
19030 "thread-id": 0,
19031 "socket-id": 1
19032 },
19033 "qom-path": "/machine/unattached/device[2]",
19034 "target":"x86_64",
19035 "cpu-index": 1
19036 }
19037 ]
19038 }
19039 MachineInfo (Object)
19041 Information describing a machine.
19042 Members
19044 name: string
19045 the name of the machine
19046 alias: string (optional)
19048 an alias for the machine name
19049 is-default: boolean (optional)
19051 whether the machine is default
19052 cpu-max: int
19054 maximum number of CPUs supported by the machine type (since 1.5)
19055 hotpluggable-cpus: boolean
19057 cpu hotplug via -device is supported (since 2.7)
19058 numa-mem-supported: boolean
19060 true if '-numa node,mem' option is supported by the machine type
19061 and false otherwise (since 4.1)
19062 deprecated: boolean
19064 if true, the machine type is deprecated and may be removed in
19065 future versions of QEMU according to the QEMU deprecation policy
19066 (since 4.1)
19067 default-cpu-type: string (optional)
19069 default CPU model typename if none is requested via the -cpu ar‐
19070 gument. (since 4.2)
19071 default-ram-id: string (optional)
19073 the default ID of initial RAM memory backend (since 5.2)
19074 acpi: boolean
19076 machine type supports ACPI (since 8.0)
19077 Since
19079 1.2
19080 query-machines (Command)
19082 Return a list of supported machines
19083 Returns
19085 a list of MachineInfo
19086 Since
19088 1.2
19089 CurrentMachineParams (Object)
19091 Information describing the running machine parameters.
19092 Members
19094 wakeup-suspend-support: boolean
19095 true if the machine supports wake up from suspend
19096 Since
19098 4.0
19099 query-current-machine (Command)
19101 Return information on the current virtual machine.
19102 Returns
19104 CurrentMachineParams
19105 Since
19107 4.0
19108 TargetInfo (Object)
19110 Information describing the QEMU target.
19111 Members
19113 arch: SysEmuTarget
19114 the target architecture
19115 Since
19117 1.2
19118 query-target (Command)
19120 Return information about the target for this QEMU
19121 Returns
19123 TargetInfo
19124 Since
19126 1.2
19127 UuidInfo (Object)
19129 Guest UUID information (Universally Unique Identifier).
19130 Members
19132 UUID: string
19133 the UUID of the guest
19134 Since
19136 0.14
19137 Notes
19139 If no UUID was specified for the guest, a null UUID is returned.
19140 query-uuid (Command)
19142 Query the guest UUID information.
19143 Returns
19145 The UuidInfo for the guest
19146 Since
19148 0.14
19149 Example
19151 -> { "execute": "query-uuid" }
19152 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
19153 GuidInfo (Object)
19155 GUID information.
19156 Members
19158 guid: string
19159 the globally unique identifier
19160 Since
19162 2.9
19163 query-vm-generation-id (Command)
19165 Show Virtual Machine Generation ID
19166 Since
19168 2.9
19169 system_reset (Command)
19171 Performs a hard reset of a guest.
19172 Since
19174 0.14
19175 Example
19177 -> { "execute": "system_reset" }
19178 <- { "return": {} }
19179 system_powerdown (Command)
19181 Requests that a guest perform a powerdown operation.
19182 Since
19184 0.14
19185 Notes
19187 A guest may or may not respond to this command. This command returning
19188 does not indicate that a guest has accepted the request or that it has
19189 shut down. Many guests will respond to this command by prompting the
19190 user in some way.
19191 Example
19193 -> { "execute": "system_powerdown" }
19194 <- { "return": {} }
19195 system_wakeup (Command)
19197 Wake up guest from suspend. If the guest has wake-up from suspend sup‐
19198 port enabled (wakeup-suspend-support flag from query-current-machine),
19199 wake-up guest from suspend if the guest is in SUSPENDED state. Return
19200 an error otherwise.
19201 Since
19203 1.1
19204 Returns
19206 nothing.
19207 Note
19209 prior to 4.0, this command does nothing in case the guest isn't sus‐
19210 pended.
19211 Example
19213 -> { "execute": "system_wakeup" }
19214 <- { "return": {} }
19215 LostTickPolicy (Enum)
19217 Policy for handling lost ticks in timer devices. Ticks end up getting
19218 lost when, for example, the guest is paused.
19219 Values
19221 discard
19222 throw away the missed ticks and continue with future injection
19223 normally. The guest OS will see the timer jump ahead by a po‐
19224 tentially quite significant amount all at once, as if the inter‐
19225 vening chunk of time had simply not existed; needless to say,
19226 such a sudden jump can easily confuse a guest OS which is not
19227 specifically prepared to deal with it. Assuming the guest OS
19228 can deal correctly with the time jump, the time in the guest and
19229 in the host should now match.
19230 delay continue to deliver ticks at the normal rate. The guest OS will
19232 not notice anything is amiss, as from its point of view time
19233 will have continued to flow normally. The time in the guest
19234 should now be behind the time in the host by exactly the amount
19235 of time during which ticks have been missed.
19236 slew deliver ticks at a higher rate to catch up with the missed
19238 ticks. The guest OS will not notice anything is amiss, as from
19239 its point of view time will have continued to flow normally.
19240 Once the timer has managed to catch up with all the missing
19241 ticks, the time in the guest and in the host should match.
19242 Since
19244 2.0
19245 inject-nmi (Command)
19247 Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all
19248 CPUs (ppc64). The command fails when the guest doesn't support inject‐
19249 ing.
19250 Returns
19252 If successful, nothing
19253 Since
19255 0.14
19256 Note
19258 prior to 2.1, this command was only supported for x86 and s390 VMs
19259 Example
19261 -> { "execute": "inject-nmi" }
19262 <- { "return": {} }
19263 KvmInfo (Object)
19265 Information about support for KVM acceleration
19266 Members
19268 enabled: boolean
19269 true if KVM acceleration is active
19270 present: boolean
19272 true if KVM acceleration is built into this executable
19273 Since
19275 0.14
19276 query-kvm (Command)
19278 Returns information about KVM acceleration
19279 Returns
19281 KvmInfo
19282 Since
19284 0.14
19285 Example
19287 -> { "execute": "query-kvm" }
19288 <- { "return": { "enabled": true, "present": true } }
19289 NumaOptionsType (Enum)
19291 Values
19292 node NUMA nodes configuration
19293 dist NUMA distance configuration (since 2.10)
19295 cpu property based CPU(s) to node mapping (Since: 2.10)
19297 hmat-lb
19299 memory latency and bandwidth information (Since: 5.0)
19300 hmat-cache
19302 memory side cache information (Since: 5.0)
19303 Since
19305 2.1
19306 NumaOptions (Object)
19308 A discriminated record of NUMA options. (for OptsVisitor)
19309 Members
19311 type: NumaOptionsType
19312 Not documented
19313 The members of NumaNodeOptions when type is "node"
19315 The members of NumaDistOptions when type is "dist"
19317 The members of NumaCpuOptions when type is "cpu"
19319 The members of NumaHmatLBOptions when type is "hmat-lb"
19321 The members of NumaHmatCacheOptions when type is "hmat-cache"
19323 Since
19325 2.1
19326 NumaNodeOptions (Object)
19328 Create a guest NUMA node. (for OptsVisitor)
19329 Members
19331 nodeid: int (optional)
19332 NUMA node ID (increase by 1 from 0 if omitted)
19333 cpus: array of int (optional)
19335 VCPUs belonging to this node (assign VCPUS round-robin if omit‐
19336 ted)
19337 mem: int (optional)
19339 memory size of this node; mutually exclusive with memdev.
19340 Equally divide total memory among nodes if both mem and memdev
19341 are omitted.
19342 memdev: string (optional)
19344 memory backend object. If specified for one node, it must be
19345 specified for all nodes.
19346 initiator: int (optional)
19348 defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the
19349 nodeid which has the memory controller responsible for this NUMA
19350 node. This field provides additional information as to the ini‐
19351 tiator node that is closest (as in directly attached) to this
19352 node, and therefore has the best performance (since 5.0)
19353 Since
19355 2.1
19356 NumaDistOptions (Object)
19358 Set the distance between 2 NUMA nodes.
19359 Members
19361 src: int
19362 source NUMA node.
19363 dst: int
19365 destination NUMA node.
19366 val: int
19368 NUMA distance from source node to destination node. When a node
19369 is unreachable from another node, set the distance between them
19370 to 255.
19371 Since
19373 2.10
19374 CXLFixedMemoryWindowOptions (Object)
19376 Create a CXL Fixed Memory Window
19377 Members
19379 size: int
19380 Size of the Fixed Memory Window in bytes. Must be a multiple of
19381 256MiB.
19382 interleave-granularity: int (optional)
19384 Number of contiguous bytes for which accesses will go to a given
19385 interleave target. Accepted values [256, 512, 1k, 2k, 4k, 8k,
19386 16k]
19387 targets: array of string
19389 Target root bridge IDs from -device ...,id=<ID> for each root
19390 bridge.
19391 Since
19393 7.1
19394 CXLFMWProperties (Object)
19396 List of CXL Fixed Memory Windows.
19397 Members
19399 cxl-fmw: array of CXLFixedMemoryWindowOptions
19400 List of CXLFixedMemoryWindowOptions
19401 Since
19403 7.1
19404 X86CPURegister32 (Enum)
19406 A X86 32-bit register
19407 Values
19409 EAX Not documented
19410 EBX Not documented
19412 ECX Not documented
19414 EDX Not documented
19416 ESP Not documented
19418 EBP Not documented
19420 ESI Not documented
19422 EDI Not documented
19424 Since
19426 1.5
19427 X86CPUFeatureWordInfo (Object)
19429 Information about a X86 CPU feature word
19430 Members
19432 cpuid-input-eax: int
19433 Input EAX value for CPUID instruction for that feature word
19434 cpuid-input-ecx: int (optional)
19436 Input ECX value for CPUID instruction for that feature word
19437 cpuid-register: X86CPURegister32
19439 Output register containing the feature bits
19440 features: int
19442 value of output register, containing the feature bits
19443 Since
19445 1.5
19446 DummyForceArrays (Object)
19448 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList inter‐
19449 nally
19450 Members
19452 unused: array of X86CPUFeatureWordInfo
19453 Not documented
19454 Since
19456 2.5
19457 NumaCpuOptions (Object)
19459 Option "-numa cpu" overrides default cpu to node mapping. It accepts
19460 the same set of cpu properties as returned by query-hotplug‐
19461 gable-cpus[].props, where node-id could be used to override default
19462 node mapping.
19463 Members
19465 The members of CpuInstanceProperties
19466 Since
19468 2.10
19469 HmatLBMemoryHierarchy (Enum)
19471 The memory hierarchy in the System Locality Latency and Bandwidth In‐
19472 formation Structure of HMAT (Heterogeneous Memory Attribute Table)
19473 For more information about HmatLBMemoryHierarchy, see chapter 5.2.27.4:
19475 Table 5-146: Field "Flags" of ACPI 6.3 spec.
19476 Values
19478 memory the structure represents the memory performance
19479 first-level
19481 first level of memory side cache
19482 second-level
19484 second level of memory side cache
19485 third-level
19487 third level of memory side cache
19488 Since
19490 5.0
19491 HmatLBDataType (Enum)
19493 Data type in the System Locality Latency and Bandwidth Information
19494 Structure of HMAT (Heterogeneous Memory Attribute Table)
19495 For more information about HmatLBDataType, see chapter 5.2.27.4: Table
19497 5-146: Field "Data Type" of ACPI 6.3 spec.
19498 Values
19500 access-latency
19501 access latency (nanoseconds)
19502 read-latency
19504 read latency (nanoseconds)
19505 write-latency
19507 write latency (nanoseconds)
19508 access-bandwidth
19510 access bandwidth (Bytes per second)
19511 read-bandwidth
19513 read bandwidth (Bytes per second)
19514 write-bandwidth
19516 write bandwidth (Bytes per second)
19517 Since
19519 5.0
19520 NumaHmatLBOptions (Object)
19522 Set the system locality latency and bandwidth information between Ini‐
19523 tiator and Target proximity Domains.
19524 For more information about NumaHmatLBOptions, see chapter 5.2.27.4: Ta‐
19526 ble 5-146 of ACPI 6.3 spec.
19527 Members
19529 initiator: int
19530 the Initiator Proximity Domain.
19531 target: int
19533 the Target Proximity Domain.
19534 hierarchy: HmatLBMemoryHierarchy
19536 the Memory Hierarchy. Indicates the performance of memory or
19537 side cache.
19538 data-type: HmatLBDataType
19540 presents the type of data, access/read/write latency or hit la‐
19541 tency.
19542 latency: int (optional)
19544 the value of latency from initiator to target proximity domain,
19545 the latency unit is "ns(nanosecond)".
19546 bandwidth: int (optional)
19548 the value of bandwidth between initiator and target proximity
19549 domain, the bandwidth unit is "Bytes per second".
19550 Since
19552 5.0
19553 HmatCacheAssociativity (Enum)
19555 Cache associativity in the Memory Side Cache Information Structure of
19556 HMAT
19557 For more information of HmatCacheAssociativity, see chapter 5.2.27.5:
19559 Table 5-147 of ACPI 6.3 spec.
19560 Values
19562 none None (no memory side cache in this proximity domain, or cache
19563 associativity unknown)
19564 direct Direct Mapped
19566 complex
19568 Complex Cache Indexing (implementation specific)
19569 Since
19571 5.0
19572 HmatCacheWritePolicy (Enum)
19574 Cache write policy in the Memory Side Cache Information Structure of
19575 HMAT
19576 For more information of HmatCacheWritePolicy, see chapter 5.2.27.5: Ta‐
19578 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
19579 Values
19581 none None (no memory side cache in this proximity domain, or cache
19582 write policy unknown)
19583 write-back
19585 Write Back (WB)
19586 write-through
19588 Write Through (WT)
19589 Since
19591 5.0
19592 NumaHmatCacheOptions (Object)
19594 Set the memory side cache information for a given memory domain.
19595 For more information of NumaHmatCacheOptions, see chapter 5.2.27.5: Ta‐
19597 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
19598 Members
19600 node-id: int
19601 the memory proximity domain to which the memory belongs.
19602 size: int
19604 the size of memory side cache in bytes.
19605 level: int
19607 the cache level described in this structure.
19608 associativity: HmatCacheAssociativity
19610 the cache associativity, none/direct-mapped/complex(complex
19611 cache indexing).
19612 policy: HmatCacheWritePolicy
19614 the write policy, none/write-back/write-through.
19615 line: int
19617 the cache Line size in bytes.
19618 Since
19620 5.0
19621 memsave (Command)
19623 Save a portion of guest memory to a file.
19624 Arguments
19626 val: int
19627 the virtual address of the guest to start from
19628 size: int
19630 the size of memory region to save
19631 filename: string
19633 the file to save the memory to as binary data
19634 cpu-index: int (optional)
19636 the index of the virtual CPU to use for translating the virtual
19637 address (defaults to CPU 0)
19638 Returns
19640 Nothing on success
19641 Since
19643 0.14
19644 Notes
19646 Errors were not reliably returned until 1.1
19647 Example
19649 -> { "execute": "memsave",
19650 "arguments": { "val": 10,
19651 "size": 100,
19652 "filename": "/tmp/virtual-mem-dump" } }
19653 <- { "return": {} }
19654 pmemsave (Command)
19656 Save a portion of guest physical memory to a file.
19657 Arguments
19659 val: int
19660 the physical address of the guest to start from
19661 size: int
19663 the size of memory region to save
19664 filename: string
19666 the file to save the memory to as binary data
19667 Returns
19669 Nothing on success
19670 Since
19672 0.14
19673 Notes
19675 Errors were not reliably returned until 1.1
19676 Example
19678 -> { "execute": "pmemsave",
19679 "arguments": { "val": 10,
19680 "size": 100,
19681 "filename": "/tmp/physical-mem-dump" } }
19682 <- { "return": {} }
19683 Memdev (Object)
19685 Information about memory backend
19686 Members
19688 id: string (optional)
19689 backend's ID if backend has 'id' property (since 2.9)
19690 size: int
19692 memory backend size
19693 merge: boolean
19695 whether memory merge support is enabled
19696 dump: boolean
19698 whether memory backend's memory is included in a core dump
19699 prealloc: boolean
19701 whether memory was preallocated
19702 share: boolean
19704 whether memory is private to QEMU or shared (since 6.1)
19705 reserve: boolean (optional)
19707 whether swap space (or huge pages) was reserved if applicable.
19708 This corresponds to the user configuration and not the actual
19709 behavior implemented in the OS to perform the reservation. For
19710 example, Linux will never reserve swap space for shared file
19711 mappings. (since 6.1)
19712 host-nodes: array of int
19714 host nodes for its memory policy
19715 policy: HostMemPolicy
19717 memory policy of memory backend
19718 Since
19720 2.1
19721 query-memdev (Command)
19723 Returns information for all memory backends.
19724 Returns
19726 a list of Memdev.
19727 Since
19729 2.1
19730 Example
19732 -> { "execute": "query-memdev" }
19733 <- { "return": [
19734 {
19735 "id": "mem1",
19736 "size": 536870912,
19737 "merge": false,
19738 "dump": true,
19739 "prealloc": false,
19740 "share": false,
19741 "host-nodes": [0, 1],
19742 "policy": "bind"
19743 },
19744 {
19745 "size": 536870912,
19746 "merge": false,
19747 "dump": true,
19748 "prealloc": true,
19749 "share": false,
19750 "host-nodes": [2, 3],
19751 "policy": "preferred"
19752 }
19753 ]
19754 }
19755 CpuInstanceProperties (Object)
19757 List of properties to be used for hotplugging a CPU instance, it should
19758 be passed by management with device_add command when a CPU is being
19759 hotplugged.
19760 Members
19762 node-id: int (optional)
19763 NUMA node ID the CPU belongs to
19764 socket-id: int (optional)
19766 socket number within node/board the CPU belongs to
19767 die-id: int (optional)
19769 die number within socket the CPU belongs to (since 4.1)
19770 cluster-id: int (optional)
19772 cluster number within die the CPU belongs to (since 7.1)
19773 core-id: int (optional)
19775 core number within cluster the CPU belongs to
19776 thread-id: int (optional)
19778 thread number within core the CPU belongs to
19779 Note
19781 currently there are 6 properties that could be present but management
19782 should be prepared to pass through other properties with device_add
19783 command to allow for future interface extension. This also requires
19784 the filed names to be kept in sync with the properties passed to -de‐
19785 vice/device_add.
19786 Since
19788 2.7
19789 HotpluggableCPU (Object)
19791 Members
19792 type: string
19793 CPU object type for usage with device_add command
19794 props: CpuInstanceProperties
19796 list of properties to be used for hotplugging CPU
19797 vcpus-count: int
19799 number of logical VCPU threads HotpluggableCPU provides
19800 qom-path: string (optional)
19802 link to existing CPU object if CPU is present or omitted if CPU
19803 is not present.
19804 Since
19806 2.7
19807 query-hotpluggable-cpus (Command)
19809 Returns
19810 a list of HotpluggableCPU objects.
19811 Since
19813 2.7
19814 Examples
19816 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu
19817 POWER8:
19818 -> { "execute": "query-hotpluggable-cpus" }
19820 <- {"return": [
19821 { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
19822 "vcpus-count": 1 },
19823 { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
19824 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
19825 ]}'
19826 For pc machine type started with -smp 1,maxcpus=2:
19828 -> { "execute": "query-hotpluggable-cpus" }
19830 <- {"return": [
19831 {
19832 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
19833 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
19834 },
19835 {
19836 "qom-path": "/machine/unattached/device[0]",
19837 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
19838 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
19839 }
19840 ]}
19841 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu
19843 qemu (Since: 2.11):
19844 -> { "execute": "query-hotpluggable-cpus" }
19846 <- {"return": [
19847 {
19848 "type": "qemu-s390x-cpu", "vcpus-count": 1,
19849 "props": { "core-id": 1 }
19850 },
19851 {
19852 "qom-path": "/machine/unattached/device[0]",
19853 "type": "qemu-s390x-cpu", "vcpus-count": 1,
19854 "props": { "core-id": 0 }
19855 }
19856 ]}
19857 set-numa-node (Command)
19859 Runtime equivalent of '-numa' CLI option, available at preconfigure
19860 stage to configure numa mapping before initializing machine.
19861 Arguments
19863 The members of NumaOptions
19864 Since
19866 3.0
19867 balloon (Command)
19869 Request the balloon driver to change its balloon size.
19870 Arguments
19872 value: int
19873 the target logical size of the VM in bytes. We can deduce the
19874 size of the balloon using this formula:
19875 logical_vm_size = vm_ram_size - balloon_size
19876 From it we have: balloon_size = vm_ram_size - value
19878 Returns
19880 • Nothing on success
19881 • If the balloon driver is enabled but not functional because the KVM
19883 kernel module cannot support it, KVMMissingCap
19884 • If no balloon device is present, DeviceNotActive
19886 Notes
19888 This command just issues a request to the guest. When it returns, the
19889 balloon size may not have changed. A guest can change the balloon size
19890 independent of this command.
19891 Since
19893 0.14
19894 Example
19896 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
19897 <- { "return": {} }
19898 With a 2.5GiB guest this command inflated the ballon to 3GiB.
19900 BalloonInfo (Object)
19902 Information about the guest balloon device.
19903 Members
19905 actual: int
19906 the logical size of the VM in bytes Formula used: logi‐
19907 cal_vm_size = vm_ram_size - balloon_size
19908 Since
19910 0.14
19911 query-balloon (Command)
19913 Return information about the balloon device.
19914 Returns
19916 • BalloonInfo on success
19917 • If the balloon driver is enabled but not functional because the KVM
19919 kernel module cannot support it, KVMMissingCap
19920 • If no balloon device is present, DeviceNotActive
19922 Since
19924 0.14
19925 Example
19927 -> { "execute": "query-balloon" }
19928 <- { "return": {
19929 "actual": 1073741824
19930 }
19931 }
19932 BALLOON_CHANGE (Event)
19934 Emitted when the guest changes the actual BALLOON level. This value is
19935 equivalent to the actual field return by the 'query-balloon' command
19936 Arguments
19938 actual: int
19939 the logical size of the VM in bytes Formula used: logi‐
19940 cal_vm_size = vm_ram_size - balloon_size
19941 Note
19943 this event is rate-limited.
19944 Since
19946 1.2
19947 Example
19949 <- { "event": "BALLOON_CHANGE",
19950 "data": { "actual": 944766976 },
19951 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
19952 MemoryInfo (Object)
19954 Actual memory information in bytes.
19955 Members
19957 base-memory: int
19958 size of "base" memory specified with command line option -m.
19959 plugged-memory: int (optional)
19961 size of memory that can be hot-unplugged. This field is omitted
19962 if target doesn't support memory hotplug (i.e. CONFIG_MEM_DE‐
19963 VICE not defined at build time).
19964 Since
19966 2.11
19967 query-memory-size-summary (Command)
19969 Return the amount of initially allocated and present hotpluggable (if
19970 enabled) memory in bytes.
19971 Example
19973 -> { "execute": "query-memory-size-summary" }
19974 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
19975 Since
19977 2.11
19978 PCDIMMDeviceInfo (Object)
19980 PCDIMMDevice state information
19981 Members
19983 id: string (optional)
19984 device's ID
19985 addr: int
19987 physical address, where device is mapped
19988 size: int
19990 size of memory that the device provides
19991 slot: int
19993 slot number at which device is plugged in
19994 node: int
19996 NUMA node number where device is plugged in
19997 memdev: string
19999 memory backend linked with device
20000 hotplugged: boolean
20002 true if device was hotplugged
20003 hotpluggable: boolean
20005 true if device if could be added/removed while machine is run‐
20006 ning
20007 Since
20009 2.1
20010 VirtioPMEMDeviceInfo (Object)
20012 VirtioPMEM state information
20013 Members
20015 id: string (optional)
20016 device's ID
20017 memaddr: int
20019 physical address in memory, where device is mapped
20020 size: int
20022 size of memory that the device provides
20023 memdev: string
20025 memory backend linked with device
20026 Since
20028 4.1
20029 VirtioMEMDeviceInfo (Object)
20031 VirtioMEMDevice state information
20032 Members
20034 id: string (optional)
20035 device's ID
20036 memaddr: int
20038 physical address in memory, where device is mapped
20039 requested-size: int
20041 the user requested size of the device
20042 size: int
20044 the (current) size of memory that the device provides
20045 max-size: int
20047 the maximum size of memory that the device can provide
20048 block-size: int
20050 the block size of memory that the device provides
20051 node: int
20053 NUMA node number where device is assigned to
20054 memdev: string
20056 memory backend linked with the region
20057 Since
20059 5.1
20060 SgxEPCDeviceInfo (Object)
20062 Sgx EPC state information
20063 Members
20065 id: string (optional)
20066 device's ID
20067 memaddr: int
20069 physical address in memory, where device is mapped
20070 size: int
20072 size of memory that the device provides
20073 memdev: string
20075 memory backend linked with device
20076 node: int
20078 the numa node (Since: 7.0)
20079 Since
20081 6.2
20082 MemoryDeviceInfoKind (Enum)
20084 Values
20085 nvdimm since 2.12
20086 virtio-pmem
20088 since 4.1
20089 virtio-mem
20091 since 5.1
20092 sgx-epc
20094 since 6.2.
20095 dimm Not documented
20097 Since
20099 2.1
20100 PCDIMMDeviceInfoWrapper (Object)
20102 Members
20103 data: PCDIMMDeviceInfo
20104 Not documented
20105 Since
20107 2.1
20108 VirtioPMEMDeviceInfoWrapper (Object)
20110 Members
20111 data: VirtioPMEMDeviceInfo
20112 Not documented
20113 Since
20115 2.1
20116 VirtioMEMDeviceInfoWrapper (Object)
20118 Members
20119 data: VirtioMEMDeviceInfo
20120 Not documented
20121 Since
20123 2.1
20124 SgxEPCDeviceInfoWrapper (Object)
20126 Members
20127 data: SgxEPCDeviceInfo
20128 Not documented
20129 Since
20131 6.2
20132 MemoryDeviceInfo (Object)
20134 Union containing information about a memory device
20135 Members
20137 type: MemoryDeviceInfoKind
20138 Not documented
20139 The members of PCDIMMDeviceInfoWrapper when type is "dimm"
20141 The members of PCDIMMDeviceInfoWrapper when type is "nvdimm"
20143 The members of VirtioPMEMDeviceInfoWrapper when type is "virtio-pmem"
20145 The members of VirtioMEMDeviceInfoWrapper when type is "virtio-mem"
20147 The members of SgxEPCDeviceInfoWrapper when type is "sgx-epc"
20149 Since
20151 2.1
20152 SgxEPC (Object)
20154 Sgx EPC cmdline information
20155 Members
20157 memdev: string
20158 memory backend linked with device
20159 node: int
20161 the numa node (Since: 7.0)
20162 Since
20164 6.2
20165 SgxEPCProperties (Object)
20167 SGX properties of machine types.
20168 Members
20170 sgx-epc: array of SgxEPC
20171 list of ids of memory-backend-epc objects.
20172 Since
20174 6.2
20175 query-memory-devices (Command)
20177 Lists available memory devices and their state
20178 Since
20180 2.1
20181 Example
20183 -> { "execute": "query-memory-devices" }
20184 <- { "return": [ { "data":
20185 { "addr": 5368709120,
20186 "hotpluggable": true,
20187 "hotplugged": true,
20188 "id": "d1",
20189 "memdev": "/objects/memX",
20190 "node": 0,
20191 "size": 1073741824,
20192 "slot": 0},
20193 "type": "dimm"
20194 } ] }
20195 MEMORY_DEVICE_SIZE_CHANGE (Event)
20197 Emitted when the size of a memory device changes. Only emitted for
20198 memory devices that can actually change the size (e.g., virtio-mem due
20199 to guest action).
20200 Arguments
20202 id: string (optional)
20203 device's ID
20204 size: int
20206 the new size of memory that the device provides
20207 qom-path: string
20209 path to the device object in the QOM tree (since 6.2)
20210 Note
20212 this event is rate-limited.
20213 Since
20215 5.1
20216 Example
20218 <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
20219 "data": { "id": "vm0", "size": 1073741824,
20220 "qom-path": "/machine/unattached/device[2]" },
20221 "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
20222 MEM_UNPLUG_ERROR (Event)
20224 Emitted when memory hot unplug error occurs.
20225 Arguments
20227 device: string
20228 device name
20229 msg: string
20231 Informative message
20232 Features
20234 deprecated
20235 This event is deprecated. Use DEVICE_UNPLUG_GUEST_ERROR in‐
20236 stead.
20237 Since
20239 2.4
20240 Example
20242 <- { "event": "MEM_UNPLUG_ERROR",
20243 "data": { "device": "dimm1",
20244 "msg": "acpi: device unplug for unsupported device"
20245 },
20246 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
20247 BootConfiguration (Object)
20249 Schema for virtual machine boot configuration.
20250 Members
20252 order: string (optional)
20253 Boot order (a=floppy, c=hard disk, d=CD-ROM, n=network)
20254 once: string (optional)
20256 Boot order to apply on first boot
20257 menu: boolean (optional)
20259 Whether to show a boot menu
20260 splash: string (optional)
20262 The name of the file to be passed to the firmware as logo pic‐
20263 ture, if menu is true.
20264 splash-time: int (optional)
20266 How long to show the logo picture, in milliseconds
20267 reboot-timeout: int (optional)
20269 Timeout before guest reboots after boot fails
20270 strict: boolean (optional)
20272 Whether to attempt booting from devices not included in the boot
20273 order
20274 Since
20276 7.1
20277 SMPConfiguration (Object)
20279 Schema for CPU topology configuration. A missing value lets QEMU fig‐
20280 ure out a suitable value based on the ones that are provided.
20281 Members
20283 cpus: int (optional)
20284 number of virtual CPUs in the virtual machine
20285 sockets: int (optional)
20287 number of sockets in the CPU topology
20288 dies: int (optional)
20290 number of dies per socket in the CPU topology
20291 clusters: int (optional)
20293 number of clusters per die in the CPU topology (since 7.0)
20294 cores: int (optional)
20296 number of cores per cluster in the CPU topology
20297 threads: int (optional)
20299 number of threads per core in the CPU topology
20300 maxcpus: int (optional)
20302 maximum number of hotpluggable virtual CPUs in the virtual ma‐
20303 chine
20304 Since
20306 6.1
20307 x-query-irq (Command)
20309 Query interrupt statistics
20310 Features
20312 unstable
20313 This command is meant for debugging.
20314 Returns
20316 interrupt statistics
20317 Since
20319 6.2
20320 x-query-jit (Command)
20322 Query TCG compiler statistics
20323 Features
20325 unstable
20326 This command is meant for debugging.
20327 Returns
20329 TCG compiler statistics
20330 Since
20332 6.2
20333 If
20335 CONFIG_TCG
20336 x-query-numa (Command)
20338 Query NUMA topology information
20339 Features
20341 unstable
20342 This command is meant for debugging.
20343 Returns
20345 topology information
20346 Since
20348 6.2
20349 x-query-opcount (Command)
20351 Query TCG opcode counters
20352 Features
20354 unstable
20355 This command is meant for debugging.
20356 Returns
20358 TCG opcode counters
20359 Since
20361 6.2
20362 If
20364 CONFIG_TCG
20365 x-query-ramblock (Command)
20367 Query system ramblock information
20368 Features
20370 unstable
20371 This command is meant for debugging.
20372 Returns
20374 system ramblock information
20375 Since
20377 6.2
20378 x-query-rdma (Command)
20380 Query RDMA state
20381 Features
20383 unstable
20384 This command is meant for debugging.
20385 Returns
20387 RDMA state
20388 Since
20390 6.2
20391 x-query-roms (Command)
20393 Query information on the registered ROMS
20394 Features
20396 unstable
20397 This command is meant for debugging.
20398 Returns
20400 registered ROMs
20401 Since
20403 6.2
20404 x-query-usb (Command)
20406 Query information on the USB devices
20407 Features
20409 unstable
20410 This command is meant for debugging.
20411 Returns
20413 USB device information
20414 Since
20416 6.2
20417 SmbiosEntryPointType (Enum)
20419 Values
20420 32 SMBIOS version 2.1 (32-bit) Entry Point
20421 64 SMBIOS version 3.0 (64-bit) Entry Point
20423 Since
20425 7.0
20426 MemorySizeConfiguration (Object)
20428 Schema for memory size configuration.
20429 Members
20431 size: int (optional)
20432 memory size in bytes
20433 max-size: int (optional)
20435 maximum hotpluggable memory size in bytes
20436 slots: int (optional)
20438 number of available memory slots for hotplug
20439 Since
20441 7.1
20442 dumpdtb (Command)
20444 Save the FDT in dtb format.
20445 Arguments
20447 filename: string
20448 name of the dtb file to be created
20449 Since
20451 7.2
20452 Example
20454 -> { "execute": "dumpdtb" }
20455 "arguments": { "filename": "fdt.dtb" } }
20456 <- { "return": {} }
20457 If
20459 CONFIG_FDT
20460 CpuModelInfo (Object)
20462 Virtual CPU model.
20463 A CPU model consists of the name of a CPU definition, to which delta
20465 changes are applied (e.g. features added/removed). Most magic values
20466 that an architecture might require should be hidden behind the name.
20467 However, if required, architectures can expose relevant properties.
20468 Members
20470 name: string
20471 the name of the CPU definition the model is based on
20472 props: value (optional)
20474 a dictionary of QOM properties to be applied
20475 Since
20477 2.8
20478 CpuModelExpansionType (Enum)
20480 An enumeration of CPU model expansion types.
20481 Values
20483 static Expand to a static CPU model, a combination of a static base
20484 model name and property delta changes. As the static base model
20485 will never change, the expanded CPU model will be the same, in‐
20486 dependent of QEMU version, machine type, machine options, and
20487 accelerator options. Therefore, the resulting model can be used
20488 by tooling without having to specify a compatibility machine -
20489 e.g. when displaying the "host" model. The static CPU models
20490 are migration-safe.
20491 full Expand all properties. The produced model is not guaranteed to
20493 be migration-safe, but allows tooling to get an insight and work
20494 with model details.
20495 Note
20497 When a non-migration-safe CPU model is expanded in static mode, some
20498 features enabled by the CPU model may be omitted, because they can't be
20499 implemented by a static CPU model definition (e.g. cache info
20500 passthrough and PMU passthrough in x86). If you need an accurate repre‐
20501 sentation of the features enabled by a non-migration-safe CPU model,
20502 use full. If you need a static representation that will keep ABI com‐
20503 patibility even when changing QEMU version or machine-type, use static
20504 (but keep in mind that some features may be omitted).
20505 Since
20507 2.8
20508 CpuModelCompareResult (Enum)
20510 An enumeration of CPU model comparison results. The result is usually
20511 calculated using e.g. CPU features or CPU generations.
20512 Values
20514 incompatible
20515 If model A is incompatible to model B, model A is not guaranteed
20516 to run where model B runs and the other way around.
20517 identical
20519 If model A is identical to model B, model A is guaranteed to run
20520 where model B runs and the other way around.
20521 superset
20523 If model A is a superset of model B, model B is guaranteed to
20524 run where model A runs. There are no guarantees about the other
20525 way.
20526 subset If model A is a subset of model B, model A is guaranteed to run
20528 where model B runs. There are no guarantees about the other
20529 way.
20530 Since
20532 2.8
20533 CpuModelBaselineInfo (Object)
20535 The result of a CPU model baseline.
20536 Members
20538 model: CpuModelInfo
20539 the baselined CpuModelInfo.
20540 Since
20542 2.8
20543 If
20545 TARGET_S390X
20546 CpuModelCompareInfo (Object)
20548 The result of a CPU model comparison.
20549 Members
20551 result: CpuModelCompareResult
20552 The result of the compare operation.
20553 responsible-properties: array of string
20555 List of properties that led to the comparison result not being
20556 identical.
20557 responsible-properties is a list of QOM property names that led to both
20558 CPUs not being detected as identical. For identical models, this list
20559 is empty. If a QOM property is read-only, that means there's no known
20560 way to make the CPU models identical. If the special property name
20561 "type" is included, the models are by definition not identical and can‐
20562 not be made identical.
20563 Since
20565 2.8
20566 If
20568 TARGET_S390X
20569 query-cpu-model-comparison (Command)
20571 Compares two CPU models, returning how they compare in a specific con‐
20572 figuration. The results indicates how both models compare regarding
20573 runnability. This result can be used by tooling to make decisions if a
20574 certain CPU model will run in a certain configuration or if a compati‐
20575 ble CPU model has to be created by baselining.
20576 Usually, a CPU model is compared against the maximum possible CPU model
20578 of a certain configuration (e.g. the "host" model for KVM). If that
20579 CPU model is identical or a subset, it will run in that configuration.
20580 The result returned by this command may be affected by:
20582 • QEMU version: CPU models may look different depending on the QEMU
20584 version. (Except for CPU models reported as "static" in
20585 query-cpu-definitions.)
20586 • machine-type: CPU model may look different depending on the ma‐
20588 chine-type. (Except for CPU models reported as "static" in
20589 query-cpu-definitions.)
20590 • machine options (including accelerator): in some architectures, CPU
20592 models may look different depending on machine and accelerator op‐
20593 tions. (Except for CPU models reported as "static" in query-cpu-def‐
20594 initions.)
20595 • "-cpu" arguments and global properties: arguments to the -cpu option
20597 and global properties may affect expansion of CPU models. Using
20598 query-cpu-model-expansion while using these is not advised.
20599 Some architectures may not support comparing CPU models. s390x sup‐
20601 ports comparing CPU models.
20602 Arguments
20604 modela: CpuModelInfo
20605 Not documented
20606 modelb: CpuModelInfo
20608 Not documented
20609 Returns
20611 a CpuModelBaselineInfo. Returns an error if comparing CPU models is
20612 not supported, if a model cannot be used, if a model contains an un‐
20613 known cpu definition name, unknown properties or properties with wrong
20614 types.
20615 Note
20617 this command isn't specific to s390x, but is only implemented on this
20618 architecture currently.
20619 Since
20621 2.8
20622 If
20624 TARGET_S390X
20625 query-cpu-model-baseline (Command)
20627 Baseline two CPU models, creating a compatible third model. The cre‐
20628 ated model will always be a static, migration-safe CPU model (see
20629 "static" CPU model expansion for details).
20630 This interface can be used by tooling to create a compatible CPU model
20632 out two CPU models. The created CPU model will be identical to or a
20633 subset of both CPU models when comparing them. Therefore, the created
20634 CPU model is guaranteed to run where the given CPU models run.
20635 The result returned by this command may be affected by:
20637 • QEMU version: CPU models may look different depending on the QEMU
20639 version. (Except for CPU models reported as "static" in
20640 query-cpu-definitions.)
20641 • machine-type: CPU model may look different depending on the ma‐
20643 chine-type. (Except for CPU models reported as "static" in
20644 query-cpu-definitions.)
20645 • machine options (including accelerator): in some architectures, CPU
20647 models may look different depending on machine and accelerator op‐
20648 tions. (Except for CPU models reported as "static" in query-cpu-def‐
20649 initions.)
20650 • "-cpu" arguments and global properties: arguments to the -cpu option
20652 and global properties may affect expansion of CPU models. Using
20653 query-cpu-model-expansion while using these is not advised.
20654 Some architectures may not support baselining CPU models. s390x sup‐
20656 ports baselining CPU models.
20657 Arguments
20659 modela: CpuModelInfo
20660 Not documented
20661 modelb: CpuModelInfo
20663 Not documented
20664 Returns
20666 a CpuModelBaselineInfo. Returns an error if baselining CPU models is
20667 not supported, if a model cannot be used, if a model contains an un‐
20668 known cpu definition name, unknown properties or properties with wrong
20669 types.
20670 Note
20672 this command isn't specific to s390x, but is only implemented on this
20673 architecture currently.
20674 Since
20676 2.8
20677 If
20679 TARGET_S390X
20680 CpuModelExpansionInfo (Object)
20682 The result of a cpu model expansion.
20683 Members
20685 model: CpuModelInfo
20686 the expanded CpuModelInfo.
20687 Since
20689 2.8
20690 If
20692 TARGET_S390X or TARGET_I386 or TARGET_ARM
20693 query-cpu-model-expansion (Command)
20695 Expands a given CPU model (or a combination of CPU model + additional
20696 options) to different granularities, allowing tooling to get an under‐
20697 standing what a specific CPU model looks like in QEMU under a certain
20698 configuration.
20699 This interface can be used to query the "host" CPU model.
20701 The data returned by this command may be affected by:
20703 • QEMU version: CPU models may look different depending on the QEMU
20705 version. (Except for CPU models reported as "static" in
20706 query-cpu-definitions.)
20707 • machine-type: CPU model may look different depending on the ma‐
20709 chine-type. (Except for CPU models reported as "static" in
20710 query-cpu-definitions.)
20711 • machine options (including accelerator): in some architectures, CPU
20713 models may look different depending on machine and accelerator op‐
20714 tions. (Except for CPU models reported as "static" in query-cpu-def‐
20715 initions.)
20716 • "-cpu" arguments and global properties: arguments to the -cpu option
20718 and global properties may affect expansion of CPU models. Using
20719 query-cpu-model-expansion while using these is not advised.
20720 Some architectures may not support all expansion types. s390x supports
20722 "full" and "static". Arm only supports "full".
20723 Arguments
20725 type: CpuModelExpansionType
20726 Not documented
20727 model: CpuModelInfo
20729 Not documented
20730 Returns
20732 a CpuModelExpansionInfo. Returns an error if expanding CPU models is
20733 not supported, if the model cannot be expanded, if the model contains
20734 an unknown CPU definition name, unknown properties or properties with a
20735 wrong type. Also returns an error if an expansion type is not sup‐
20736 ported.
20737 Since
20739 2.8
20740 If
20742 TARGET_S390X or TARGET_I386 or TARGET_ARM
20743 CpuDefinitionInfo (Object)
20745 Virtual CPU definition.
20746 Members
20748 name: string
20749 the name of the CPU definition
20750 migration-safe: boolean (optional)
20752 whether a CPU definition can be safely used for migration in
20753 combination with a QEMU compatibility machine when migrating be‐
20754 tween different QEMU versions and between hosts with different
20755 sets of (hardware or software) capabilities. If not provided,
20756 information is not available and callers should not assume the
20757 CPU definition to be migration-safe. (since 2.8)
20758 static: boolean
20760 whether a CPU definition is static and will not change depending
20761 on QEMU version, machine type, machine options and accelerator
20762 options. A static model is always migration-safe. (since 2.8)
20763 unavailable-features: array of string (optional)
20765 List of properties that prevent the CPU model from running in
20766 the current host. (since 2.8)
20767 typename: string
20769 Type name that can be used as argument to device-list-proper‐
20770 ties, to introspect properties configurable using -cpu or
20771 -global. (since 2.9)
20772 alias-of: string (optional)
20774 Name of CPU model this model is an alias for. The target of the
20775 CPU model alias may change depending on the machine type. Man‐
20776 agement software is supposed to translate CPU model aliases in
20777 the VM configuration, because aliases may stop being migra‐
20778 tion-safe in the future (since 4.1)
20779 deprecated: boolean
20781 If true, this CPU model is deprecated and may be removed in in
20782 some future version of QEMU according to the QEMU deprecation
20783 policy. (since 5.2)
20784 unavailable-features is a list of QOM property names that represent CPU
20785 model attributes that prevent the CPU from running. If the QOM prop‐
20786 erty is read-only, that means there's no known way to make the CPU
20787 model run in the current host. Implementations that choose not to pro‐
20788 vide specific information return the property name "type". If the prop‐
20789 erty is read-write, it means that it MAY be possible to run the CPU
20790 model in the current host if that property is changed. Management
20791 software can use it as hints to suggest or choose an alternative for
20792 the user, or just to generate meaningful error messages explaining why
20793 the CPU model can't be used. If unavailable-features is an empty list,
20794 the CPU model is runnable using the current host and machine-type. If
20795 unavailable-features is not present, runnability information for the
20796 CPU is not available.
20797 Since
20799 1.2
20800 If
20802 TARGET_PPC or TARGET_ARM or TARGET_I386 or TARGET_S390X or TARGET_MIPS
20803 or TARGET_LOONGARCH64 or TARGET_RISCV
20804 query-cpu-definitions (Command)
20806 Return a list of supported virtual CPU definitions
20807 Returns
20809 a list of CpuDefinitionInfo
20810 Since
20812 1.2
20813 If
20815 TARGET_PPC or TARGET_ARM or TARGET_I386 or TARGET_S390X or TARGET_MIPS
20816 or TARGET_LOONGARCH64 or TARGET_RISCV
20817
20819 ReplayMode (Enum)
20820 Mode of the replay subsystem.
20821 Values
20823 none normal execution mode. Replay or record are not enabled.
20824 record record mode. All non-deterministic data is written into the re‐
20826 play log.
20827 play replay mode. Non-deterministic data required for system execu‐
20829 tion is read from the log.
20830 Since
20832 2.5
20833 ReplayInfo (Object)
20835 Record/replay information.
20836 Members
20838 mode: ReplayMode
20839 current mode.
20840 filename: string (optional)
20842 name of the record/replay log file. It is present only in
20843 record or replay modes, when the log is recorded or replayed.
20844 icount: int
20846 current number of executed instructions.
20847 Since
20849 5.2
20850 query-replay (Command)
20852 Retrieve the record/replay information. It includes current instruc‐
20853 tion count which may be used for replay-break and replay-seek commands.
20854 Returns
20856 record/replay information.
20857 Since
20859 5.2
20860 Example
20862 -> { "execute": "query-replay" }
20863 <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
20864 replay-break (Command)
20866 Set replay breakpoint at instruction count icount. Execution stops
20867 when the specified instruction is reached. There can be at most one
20868 breakpoint. When breakpoint is set, any prior one is removed. The
20869 breakpoint may be set only in replay mode and only "in the future",
20870 i.e. at instruction counts greater than the current one. The current
20871 instruction count can be observed with query-replay.
20872 Arguments
20874 icount: int
20875 instruction count to stop at
20876 Since
20878 5.2
20879 Example
20881 -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
20882 <- { "return": {} }
20883 replay-delete-break (Command)
20885 Remove replay breakpoint which was set with replay-break. The command
20886 is ignored when there are no replay breakpoints.
20887 Since
20889 5.2
20890 Example
20892 -> { "execute": "replay-delete-break" }
20893 <- { "return": {} }
20894 replay-seek (Command)
20896 Automatically proceed to the instruction count icount, when replaying
20897 the execution. The command automatically loads nearest snapshot and
20898 replays the execution to find the desired instruction. When there is
20899 no preceding snapshot or the execution is not replayed, then the com‐
20900 mand fails. icount for the reference may be obtained with query-replay
20901 command.
20902 Arguments
20904 icount: int
20905 target instruction count
20906 Since
20908 5.2
20909 Example
20911 -> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
20912 <- { "return": {} }
20913
20915 YankInstanceType (Enum)
20916 An enumeration of yank instance types. See YankInstance for more in‐
20917 formation.
20918 Values
20920 block-node
20921 Not documented
20922 chardev
20924 Not documented
20925 migration
20927 Not documented
20928 Since
20930 6.0
20931 YankInstanceBlockNode (Object)
20933 Specifies which block graph node to yank. See YankInstance for more
20934 information.
20935 Members
20937 node-name: string
20938 the name of the block graph node
20939 Since
20941 6.0
20942 YankInstanceChardev (Object)
20944 Specifies which character device to yank. See YankInstance for more
20945 information.
20946 Members
20948 id: string
20949 the chardev's ID
20950 Since
20952 6.0
20953 YankInstance (Object)
20955 A yank instance can be yanked with the yank qmp command to recover from
20956 a hanging QEMU.
20957 Currently implemented yank instances:
20959 • nbd block device: Yanking it will shut down the connection to the nbd
20961 server without attempting to reconnect.
20962 • socket chardev: Yanking it will shut down the connected socket.
20964 • migration: Yanking it will shut down all migration connections. Un‐
20966 like migrate_cancel, it will not notify the migration process, so mi‐
20967 gration will go into failed state, instead of cancelled state. yank
20968 should be used to recover from hangs.
20969 Members
20971 type: YankInstanceType
20972 Not documented
20973 The members of YankInstanceBlockNode when type is "block-node"
20975 The members of YankInstanceChardev when type is "chardev"
20977 Since
20979 6.0
20980 yank (Command)
20982 Try to recover from hanging QEMU by yanking the specified instances.
20983 See YankInstance for more information.
20984 Takes a list of YankInstance as argument.
20986 Arguments
20988 instances: array of YankInstance
20989 Not documented
20990 Returns
20992 • Nothing on success
20993 • DeviceNotFound error, if any of the YankInstances doesn't exist
20995 Example
20997 -> { "execute": "yank",
20998 "arguments": {
20999 "instances": [
21000 { "type": "block-node",
21001 "node-name": "nbd0" }
21002 ] } }
21003 <- { "return": {} }
21004 Since
21006 6.0
21007 query-yank (Command)
21009 Query yank instances. See YankInstance for more information.
21010 Returns
21012 list of YankInstance
21013 Example
21015 -> { "execute": "query-yank" }
21016 <- { "return": [
21017 { "type": "block-node",
21018 "node-name": "nbd0" }
21019 ] }
21020 Since
21022 6.0
21023
21025 add_client (Command)
21026 Allow client connections for VNC, Spice and socket based character de‐
21027 vices to be passed in to QEMU via SCM_RIGHTS.
21028 If the FD associated with fdname is not a socket, the command will fail
21030 and the FD will be closed.
21031 Arguments
21033 protocol: string
21034 protocol name. Valid names are "vnc", "spice", "dbus-display"
21035 or the name of a character device (e.g. from -chardev id=XXXX)
21036 fdname: string
21038 file descriptor name previously passed via 'getfd' command
21039 skipauth: boolean (optional)
21041 whether to skip authentication. Only applies to "vnc" and
21042 "spice" protocols
21043 tls: boolean (optional)
21045 whether to perform TLS. Only applies to the "spice" protocol
21046 Returns
21048 nothing on success.
21049 Since
21051 0.14
21052 Example
21054 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
21055 "fdname": "myclient" } }
21056 <- { "return": {} }
21057 NameInfo (Object)
21059 Guest name information.
21060 Members
21062 name: string (optional)
21063 The name of the guest
21064 Since
21066 0.14
21067 query-name (Command)
21069 Return the name information of a guest.
21070 Returns
21072 NameInfo of the guest
21073 Since
21075 0.14
21076 Example
21078 -> { "execute": "query-name" }
21079 <- { "return": { "name": "qemu-name" } }
21080 IOThreadInfo (Object)
21082 Information about an iothread
21083 Members
21085 id: string
21086 the identifier of the iothread
21087 thread-id: int
21089 ID of the underlying host thread
21090 poll-max-ns: int
21092 maximum polling time in ns, 0 means polling is disabled (since
21093 2.9)
21094 poll-grow: int
21096 how many ns will be added to polling time, 0 means that it's not
21097 configured (since 2.9)
21098 poll-shrink: int
21100 how many ns will be removed from polling time, 0 means that it's
21101 not configured (since 2.9)
21102 aio-max-batch: int
21104 maximum number of requests in a batch for the AIO engine, 0
21105 means that the engine will use its default (since 6.1)
21106 Since
21108 2.0
21109 query-iothreads (Command)
21111 Returns a list of information about each iothread.
21112 Note
21114 this list excludes the QEMU main loop thread, which is not declared us‐
21115 ing the -object iothread command-line option. It is always the main
21116 thread of the process.
21117 Returns
21119 a list of IOThreadInfo for each iothread
21120 Since
21122 2.0
21123 Example
21125 -> { "execute": "query-iothreads" }
21126 <- { "return": [
21127 {
21128 "id":"iothread0",
21129 "thread-id":3134
21130 },
21131 {
21132 "id":"iothread1",
21133 "thread-id":3135
21134 }
21135 ]
21136 }
21137 stop (Command)
21139 Stop all guest VCPU execution.
21140 Since
21142 0.14
21143 Notes
21145 This function will succeed even if the guest is already in the stopped
21146 state. In "inmigrate" state, it will ensure that the guest remains
21147 paused once migration finishes, as if the -S option was passed on the
21148 command line.
21149 Example
21151 -> { "execute": "stop" }
21152 <- { "return": {} }
21153 cont (Command)
21155 Resume guest VCPU execution.
21156 Since
21158 0.14
21159 Returns
21161 If successful, nothing
21162 Notes
21164 This command will succeed if the guest is currently running. It will
21165 also succeed if the guest is in the "inmigrate" state; in this case,
21166 the effect of the command is to make sure the guest starts once migra‐
21167 tion finishes, removing the effect of the -S command line option if it
21168 was passed.
21169 Example
21171 -> { "execute": "cont" }
21172 <- { "return": {} }
21173 x-exit-preconfig (Command)
21175 Exit from "preconfig" state
21176 This command makes QEMU exit the preconfig state and proceed with VM
21178 initialization using configuration data provided on the command line
21179 and via the QMP monitor during the preconfig state. The command is
21180 only available during the preconfig state (i.e. when the --preconfig
21181 command line option was in use).
21182 Features
21184 unstable
21185 This command is experimental.
21186 Since
21188 3.0
21189 Returns
21191 nothing
21192 Example
21194 -> { "execute": "x-exit-preconfig" }
21195 <- { "return": {} }
21196 human-monitor-command (Command)
21198 Execute a command on the human monitor and return the output.
21199 Arguments
21201 command-line: string
21202 the command to execute in the human monitor
21203 cpu-index: int (optional)
21205 The CPU to use for commands that require an implicit CPU
21206 Features
21208 savevm-monitor-nodes
21209 If present, HMP command savevm only snapshots monitor-owned
21210 nodes if they have no parents. This allows the use of 'savevm'
21211 with -blockdev. (since 4.2)
21212 Returns
21214 the output of the command as a string
21215 Since
21217 0.14
21218 Notes
21220 This command only exists as a stop-gap. Its use is highly discouraged.
21221 The semantics of this command are not guaranteed: this means that com‐
21222 mand names, arguments and responses can change or be removed at ANY
21223 time. Applications that rely on long term stability guarantees should
21224 NOT use this command.
21225 Known limitations:
21227 • This command is stateless, this means that commands that depend on
21229 state information (such as getfd) might not work
21230 • Commands that prompt the user for data don't currently work
21232 Example
21234 -> { "execute": "human-monitor-command",
21235 "arguments": { "command-line": "info kvm" } }
21236 <- { "return": "kvm support: enabled\r\n" }
21237 getfd (Command)
21239 Receive a file descriptor via SCM rights and assign it a name
21240 Arguments
21242 fdname: string
21243 file descriptor name
21244 Returns
21246 Nothing on success
21247 Since
21249 0.14
21250 Notes
21252 If fdname already exists, the file descriptor assigned to it will be
21253 closed and replaced by the received file descriptor.
21254 The 'closefd' command can be used to explicitly close the file descrip‐
21256 tor when it is no longer needed.
21257 Example
21259 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
21260 <- { "return": {} }
21261 If
21263 CONFIG_POSIX
21264 get-win32-socket (Command)
21266 Add a socket that was duplicated to QEMU process with WSADuplicateSock‐
21267 etW() via WSASocket() & WSAPROTOCOL_INFOW structure and assign it a
21268 name (the SOCKET is associated with a CRT file descriptor)
21269 Arguments
21271 info: string
21272 the WSAPROTOCOL_INFOW structure (encoded in base64)
21273 fdname: string
21275 file descriptor name
21276 Returns
21278 Nothing on success
21279 Since
21281 8.0
21282 Notes
21284 If fdname already exists, the file descriptor assigned to it will be
21285 closed and replaced by the received file descriptor.
21286 The 'closefd' command can be used to explicitly close the file descrip‐
21288 tor when it is no longer needed.
21289 Example
21291 -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } }
21292 <- { "return": {} }
21293 If
21295 CONFIG_WIN32
21296 closefd (Command)
21298 Close a file descriptor previously passed via SCM rights
21299 Arguments
21301 fdname: string
21302 file descriptor name
21303 Returns
21305 Nothing on success
21306 Since
21308 0.14
21309 Example
21311 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
21312 <- { "return": {} }
21313 AddfdInfo (Object)
21315 Information about a file descriptor that was added to an fd set.
21316 Members
21318 fdset-id: int
21319 The ID of the fd set that fd was added to.
21320 fd: int
21322 The file descriptor that was received via SCM rights and added
21323 to the fd set.
21324 Since
21326 1.2
21327 add-fd (Command)
21329 Add a file descriptor, that was passed via SCM rights, to an fd set.
21330 Arguments
21332 fdset-id: int (optional)
21333 The ID of the fd set to add the file descriptor to.
21334 opaque: string (optional)
21336 A free-form string that can be used to describe the fd.
21337 Returns
21339 • AddfdInfo on success
21340 • If file descriptor was not received, GenericError
21342 • If fdset-id is a negative value, GenericError
21344 Notes
21346 The list of fd sets is shared by all monitor connections.
21347 If fdset-id is not specified, a new fd set will be created.
21349 Since
21351 1.2
21352 Example
21354 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
21355 <- { "return": { "fdset-id": 1, "fd": 3 } }
21356 remove-fd (Command)
21358 Remove a file descriptor from an fd set.
21359 Arguments
21361 fdset-id: int
21362 The ID of the fd set that the file descriptor belongs to.
21363 fd: int (optional)
21365 The file descriptor that is to be removed.
21366 Returns
21368 • Nothing on success
21369 • If fdset-id or fd is not found, GenericError
21371 Since
21373 1.2
21374 Notes
21376 The list of fd sets is shared by all monitor connections.
21377 If fd is not specified, all file descriptors in fdset-id will be re‐
21379 moved.
21380 Example
21382 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
21383 <- { "return": {} }
21384 FdsetFdInfo (Object)
21386 Information about a file descriptor that belongs to an fd set.
21387 Members
21389 fd: int
21390 The file descriptor value.
21391 opaque: string (optional)
21393 A free-form string that can be used to describe the fd.
21394 Since
21396 1.2
21397 FdsetInfo (Object)
21399 Information about an fd set.
21400 Members
21402 fdset-id: int
21403 The ID of the fd set.
21404 fds: array of FdsetFdInfo
21406 A list of file descriptors that belong to this fd set.
21407 Since
21409 1.2
21410 query-fdsets (Command)
21412 Return information describing all fd sets.
21413 Returns
21415 A list of FdsetInfo
21416 Since
21418 1.2
21419 Note
21421 The list of fd sets is shared by all monitor connections.
21422 Example
21424 -> { "execute": "query-fdsets" }
21425 <- { "return": [
21426 {
21427 "fds": [
21428 {
21429 "fd": 30,
21430 "opaque": "rdonly:/path/to/file"
21431 },
21432 {
21433 "fd": 24,
21434 "opaque": "rdwr:/path/to/file"
21435 }
21436 ],
21437 "fdset-id": 1
21438 },
21439 {
21440 "fds": [
21441 {
21442 "fd": 28
21443 },
21444 {
21445 "fd": 29
21446 }
21447 ],
21448 "fdset-id": 0
21449 }
21450 ]
21451 }
21452 CommandLineParameterType (Enum)
21454 Possible types for an option parameter.
21455 Values
21457 string accepts a character string
21458 boolean
21460 accepts "on" or "off"
21461 number accepts a number
21463 size accepts a number followed by an optional suffix (K)ilo, (M)ega,
21465 (G)iga, (T)era
21466 Since
21468 1.5
21469 CommandLineParameterInfo (Object)
21471 Details about a single parameter of a command line option.
21472 Members
21474 name: string
21475 parameter name
21476 type: CommandLineParameterType
21478 parameter CommandLineParameterType
21479 help: string (optional)
21481 human readable text string, not suitable for parsing.
21482 default: string (optional)
21484 default value string (since 2.1)
21485 Since
21487 1.5
21488 CommandLineOptionInfo (Object)
21490 Details about a command line option, including its list of parameter
21491 details
21492 Members
21494 option: string
21495 option name
21496 parameters: array of CommandLineParameterInfo
21498 an array of CommandLineParameterInfo
21499 Since
21501 1.5
21502 query-command-line-options (Command)
21504 Query command line option schema.
21505 Arguments
21507 option: string (optional)
21508 option name
21509 Returns
21511 list of CommandLineOptionInfo for all options (or for the given op‐
21512 tion). Returns an error if the given option doesn't exist.
21513 Since
21515 1.5
21516 Example
21518 -> { "execute": "query-command-line-options",
21519 "arguments": { "option": "option-rom" } }
21520 <- { "return": [
21521 {
21522 "parameters": [
21523 {
21524 "name": "romfile",
21525 "type": "string"
21526 },
21527 {
21528 "name": "bootindex",
21529 "type": "number"
21530 }
21531 ],
21532 "option": "option-rom"
21533 }
21534 ]
21535 }
21536 RTC_CHANGE (Event)
21538 Emitted when the guest changes the RTC time.
21539 Arguments
21541 offset: int
21542 offset in seconds between base RTC clock (as specified by -rtc
21543 base), and new RTC clock value
21544 qom-path: string
21546 path to the RTC object in the QOM tree
21547 Note
21549 This event is rate-limited. It is not guaranteed that the RTC in the
21550 system implements this event, or even that the system has an RTC at
21551 all.
21552 Since
21554 0.13
21555 Example
21557 <- { "event": "RTC_CHANGE",
21558 "data": { "offset": 78 },
21559 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
21560 VFU_CLIENT_HANGUP (Event)
21562 Emitted when the client of a TYPE_VFIO_USER_SERVER closes the communi‐
21563 cation channel
21564 Arguments
21566 vfu-id: string
21567 ID of the TYPE_VFIO_USER_SERVER object. It is the last compo‐
21568 nent of vfu-qom-path referenced below
21569 vfu-qom-path: string
21571 path to the TYPE_VFIO_USER_SERVER object in the QOM tree
21572 dev-id: string
21574 ID of attached PCI device
21575 dev-qom-path: string
21577 path to attached PCI device in the QOM tree
21578 Since
21580 7.1
21581 Example
21583 <- { "event": "VFU_CLIENT_HANGUP",
21584 "data": { "vfu-id": "vfu1",
21585 "vfu-qom-path": "/objects/vfu1",
21586 "dev-id": "sas1",
21587 "dev-qom-path": "/machine/peripheral/sas1" },
21588 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
21589 rtc-reset-reinjection (Command)
21591 This command will reset the RTC interrupt reinjection backlog. Can be
21592 used if another mechanism to synchronize guest time is in effect, for
21593 example QEMU guest agent's guest-set-time command.
21594 Since
21596 2.1
21597 Example
21599 -> { "execute": "rtc-reset-reinjection" }
21600 <- { "return": {} }
21601 If
21603 TARGET_I386
21604 SevState (Enum)
21606 An enumeration of SEV state information used during query-sev.
21607 Values
21609 uninit The guest is uninitialized.
21610 launch-update
21612 The guest is currently being launched; plaintext data and regis‐
21613 ter state is being imported.
21614 launch-secret
21616 The guest is currently being launched; ciphertext data is being
21617 imported.
21618 running
21620 The guest is fully launched or migrated in.
21621 send-update
21623 The guest is currently being migrated out to another machine.
21624 receive-update
21626 The guest is currently being migrated from another machine.
21627 Since
21629 2.12
21630 If
21632 TARGET_I386
21633 SevInfo (Object)
21635 Information about Secure Encrypted Virtualization (SEV) support
21636 Members
21638 enabled: boolean
21639 true if SEV is active
21640 api-major: int
21642 SEV API major version
21643 api-minor: int
21645 SEV API minor version
21646 build-id: int
21648 SEV FW build id
21649 policy: int
21651 SEV policy value
21652 state: SevState
21654 SEV guest state
21655 handle: int
21657 SEV firmware handle
21658 Since
21660 2.12
21661 If
21663 TARGET_I386
21664 query-sev (Command)
21666 Returns information about SEV
21667 Returns
21669 SevInfo
21670 Since
21672 2.12
21673 Example
21675 -> { "execute": "query-sev" }
21676 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
21677 "build-id" : 0, "policy" : 0, "state" : "running",
21678 "handle" : 1 } }
21679 If
21681 TARGET_I386
21682 SevLaunchMeasureInfo (Object)
21684 SEV Guest Launch measurement information
21685 Members
21687 data: string
21688 the measurement value encoded in base64
21689 Since
21691 2.12
21692 If
21694 TARGET_I386
21695 query-sev-launch-measure (Command)
21697 Query the SEV guest launch information.
21698 Returns
21700 The SevLaunchMeasureInfo for the guest
21701 Since
21703 2.12
21704 Example
21706 -> { "execute": "query-sev-launch-measure" }
21707 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
21708 If
21710 TARGET_I386
21711 SevCapability (Object)
21713 The struct describes capability for a Secure Encrypted Virtualization
21714 feature.
21715 Members
21717 pdh: string
21718 Platform Diffie-Hellman key (base64 encoded)
21719 cert-chain: string
21721 PDH certificate chain (base64 encoded)
21722 cpu0-id: string
21724 Unique ID of CPU0 (base64 encoded) (since 7.1)
21725 cbitpos: int
21727 C-bit location in page table entry
21728 reduced-phys-bits: int
21730 Number of physical Address bit reduction when SEV is enabled
21731 Since
21733 2.12
21734 If
21736 TARGET_I386
21737 query-sev-capabilities (Command)
21739 This command is used to get the SEV capabilities, and is supported on
21740 AMD X86 platforms only.
21741 Returns
21743 SevCapability objects.
21744 Since
21746 2.12
21747 Example
21749 -> { "execute": "query-sev-capabilities" }
21750 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
21751 "cpu0-id": "2lvmGwo+...61iEinw==",
21752 "cbitpos": 47, "reduced-phys-bits": 1}}
21753 If
21755 TARGET_I386
21756 sev-inject-launch-secret (Command)
21758 This command injects a secret blob into memory of SEV guest.
21759 Arguments
21761 packet-header: string
21762 the launch secret packet header encoded in base64
21763 secret: string
21765 the launch secret data to be injected encoded in base64
21766 gpa: int (optional)
21768 the guest physical address where secret will be injected.
21769 Since
21771 6.0
21772 If
21774 TARGET_I386
21775 SevAttestationReport (Object)
21777 The struct describes attestation report for a Secure Encrypted Virtual‐
21778 ization feature.
21779 Members
21781 data: string
21782 guest attestation report (base64 encoded)
21783 Since
21785 6.1
21786 If
21788 TARGET_I386
21789 query-sev-attestation-report (Command)
21791 This command is used to get the SEV attestation report, and is sup‐
21792 ported on AMD X86 platforms only.
21793 Arguments
21795 mnonce: string
21796 a random 16 bytes value encoded in base64 (it will be included
21797 in report)
21798 Returns
21800 SevAttestationReport objects.
21801 Since
21803 6.1
21804 Example
21806 -> { "execute" : "query-sev-attestation-report",
21807 "arguments": { "mnonce": "aaaaaaa" } }
21808 <- { "return" : { "data": "aaaaaaaabbbddddd"} }
21809 If
21811 TARGET_I386
21812 dump-skeys (Command)
21814 Dump guest's storage keys
21815 Arguments
21817 filename: string
21818 the path to the file to dump to
21819 This command is only supported on s390 architecture.
21820 Since
21822 2.5
21823 Example
21825 -> { "execute": "dump-skeys",
21826 "arguments": { "filename": "/tmp/skeys" } }
21827 <- { "return": {} }
21828 If
21830 TARGET_S390X
21831 GICCapability (Object)
21833 The struct describes capability for a specific GIC (Generic Interrupt
21834 Controller) version. These bits are not only decided by QEMU/KVM soft‐
21835 ware version, but also decided by the hardware that the program is run‐
21836 ning upon.
21837 Members
21839 version: int
21840 version of GIC to be described. Currently, only 2 and 3 are
21841 supported.
21842 emulated: boolean
21844 whether current QEMU/hardware supports emulated GIC device in
21845 user space.
21846 kernel: boolean
21848 whether current QEMU/hardware supports hardware accelerated GIC
21849 device in kernel.
21850 Since
21852 2.6
21853 If
21855 TARGET_ARM
21856 query-gic-capabilities (Command)
21858 This command is ARM-only. It will return a list of GICCapability ob‐
21859 jects that describe its capability bits.
21860 Returns
21862 a list of GICCapability objects.
21863 Since
21865 2.6
21866 Example
21868 -> { "execute": "query-gic-capabilities" }
21869 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
21870 { "version": 3, "emulated": false, "kernel": true } ] }
21871 If
21873 TARGET_ARM
21874 SGXEPCSection (Object)
21876 Information about intel SGX EPC section info
21877 Members
21879 node: int
21880 the numa node
21881 size: int
21883 the size of EPC section
21884 Since
21886 7.0
21887 SGXInfo (Object)
21889 Information about intel Safe Guard eXtension (SGX) support
21890 Members
21892 sgx: boolean
21893 true if SGX is supported
21894 sgx1: boolean
21896 true if SGX1 is supported
21897 sgx2: boolean
21899 true if SGX2 is supported
21900 flc: boolean
21902 true if FLC is supported
21903 sections: array of SGXEPCSection
21905 The EPC sections info for guest (Since: 7.0)
21906 Since
21908 6.2
21909 If
21911 TARGET_I386
21912 query-sgx (Command)
21914 Returns information about SGX
21915 Returns
21917 SGXInfo
21918 Since
21920 6.2
21921 Example
21923 -> { "execute": "query-sgx" }
21924 <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
21925 "flc": true,
21926 "sections": [{"node": 0, "size": 67108864},
21927 {"node": 1, "size": 29360128}]} }
21928 If
21930 TARGET_I386
21931 query-sgx-capabilities (Command)
21933 Returns information from host SGX capabilities
21934 Returns
21936 SGXInfo
21937 Since
21939 6.2
21940 Example
21942 -> { "execute": "query-sgx-capabilities" }
21943 <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
21944 "flc": true,
21945 "section" : [{"node": 0, "size": 67108864},
21946 {"node": 1, "size": 29360128}]} }
21947 If
21949 TARGET_I386
21950 EvtchnPortType (Enum)
21952 An enumeration of Xen event channel port types.
21953 Values
21955 closed The port is unused.
21956 unbound
21958 The port is allocated and ready to be bound.
21959 interdomain
21961 The port is connected as an interdomain interrupt.
21962 pirq The port is bound to a physical IRQ (PIRQ).
21964 virq The port is bound to a virtual IRQ (VIRQ).
21966 ipi The post is an inter-processor interrupt (IPI).
21968 Since
21970 8.0
21971 If
21973 TARGET_I386
21974 EvtchnInfo (Object)
21976 Information about a Xen event channel port
21977 Members
21979 port: int
21980 the port number
21981 vcpu: int
21983 target vCPU for this port
21984 type: EvtchnPortType
21986 the port type
21987 remote-domain: string
21989 remote domain for interdomain ports
21990 target: int
21992 remote port ID, or virq/pirq number
21993 pending: boolean
21995 port is currently active pending delivery
21996 masked: boolean
21998 port is masked
21999 Since
22001 8.0
22002 If
22004 TARGET_I386
22005 xen-event-list (Command)
22007 Query the Xen event channels opened by the guest.
22008 Returns
22010 list of open event channel ports.
22011 Since
22013 8.0
22014 Example
22016 -> { "execute": "xen-event-list" }
22017 <- { "return": [
22018 {
22019 "pending": false,
22020 "port": 1,
22021 "vcpu": 1,
22022 "remote-domain": "qemu",
22023 "masked": false,
22024 "type": "interdomain",
22025 "target": 1
22026 },
22027 {
22028 "pending": false,
22029 "port": 2,
22030 "vcpu": 0,
22031 "remote-domain": "",
22032 "masked": false,
22033 "type": "virq",
22034 "target": 0
22035 }
22036 ]
22037 }
22038 If
22040 TARGET_I386
22041 xen-event-inject (Command)
22043 Inject a Xen event channel port (interrupt) to the guest.
22044 Arguments
22046 port: int
22047 The port number
22048 Returns
22050 • Nothing on success.
22051 Since
22053 8.0
22054 Example
22056 -> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
22057 <- { "return": { } }
22058 If
22060 TARGET_I386
22061
22063 AudiodevPerDirectionOptions (Object)
22064 General audio backend options that are used for both playback and
22065 recording.
22066 Members
22068 mixing-engine: boolean (optional)
22069 use QEMU's mixing engine to mix all streams inside QEMU and con‐
22070 vert audio formats when not supported by the backend. When set
22071 to off, fixed-settings must be also off (default on, since 4.2)
22072 fixed-settings: boolean (optional)
22074 use fixed settings for host input/output. When off, frequency,
22075 channels and format must not be specified (default true)
22076 frequency: int (optional)
22078 frequency to use when using fixed settings (default 44100)
22079 channels: int (optional)
22081 number of channels when using fixed settings (default 2)
22082 voices: int (optional)
22084 number of voices to use (default 1)
22085 format: AudioFormat (optional)
22087 sample format to use when using fixed settings (default s16)
22088 buffer-length: int (optional)
22090 the buffer length in microseconds
22091 Since
22093 4.0
22094 AudiodevGenericOptions (Object)
22096 Generic driver-specific options.
22097 Members
22099 in: AudiodevPerDirectionOptions (optional)
22100 options of the capture stream
22101 out: AudiodevPerDirectionOptions (optional)
22103 options of the playback stream
22104 Since
22106 4.0
22107 AudiodevAlsaPerDirectionOptions (Object)
22109 Options of the ALSA backend that are used for both playback and record‐
22110 ing.
22111 Members
22113 dev: string (optional)
22114 the name of the ALSA device to use (default 'default')
22115 period-length: int (optional)
22117 the period length in microseconds
22118 try-poll: boolean (optional)
22120 attempt to use poll mode, falling back to non-polling access on
22121 failure (default true)
22122 The members of AudiodevPerDirectionOptions
22124 Since
22126 4.0
22127 AudiodevAlsaOptions (Object)
22129 Options of the ALSA audio backend.
22130 Members
22132 in: AudiodevAlsaPerDirectionOptions (optional)
22133 options of the capture stream
22134 out: AudiodevAlsaPerDirectionOptions (optional)
22136 options of the playback stream
22137 threshold: int (optional)
22139 set the threshold (in microseconds) when playback starts
22140 Since
22142 4.0
22143 AudiodevSndioOptions (Object)
22145 Options of the sndio audio backend.
22146 Members
22148 in: AudiodevPerDirectionOptions (optional)
22149 options of the capture stream
22150 out: AudiodevPerDirectionOptions (optional)
22152 options of the playback stream
22153 dev: string (optional)
22155 the name of the sndio device to use (default 'default')
22156 latency: int (optional)
22158 play buffer size (in microseconds)
22159 Since
22161 7.2
22162 AudiodevCoreaudioPerDirectionOptions (Object)
22164 Options of the Core Audio backend that are used for both playback and
22165 recording.
22166 Members
22168 buffer-count: int (optional)
22169 number of buffers
22170 The members of AudiodevPerDirectionOptions
22172 Since
22174 4.0
22175 AudiodevCoreaudioOptions (Object)
22177 Options of the coreaudio audio backend.
22178 Members
22180 in: AudiodevCoreaudioPerDirectionOptions (optional)
22181 options of the capture stream
22182 out: AudiodevCoreaudioPerDirectionOptions (optional)
22184 options of the playback stream
22185 Since
22187 4.0
22188 AudiodevDsoundOptions (Object)
22190 Options of the DirectSound audio backend.
22191 Members
22193 in: AudiodevPerDirectionOptions (optional)
22194 options of the capture stream
22195 out: AudiodevPerDirectionOptions (optional)
22197 options of the playback stream
22198 latency: int (optional)
22200 add extra latency to playback in microseconds (default 10000)
22201 Since
22203 4.0
22204 AudiodevJackPerDirectionOptions (Object)
22206 Options of the JACK backend that are used for both playback and record‐
22207 ing.
22208 Members
22210 server-name: string (optional)
22211 select from among several possible concurrent server instances
22212 (default: environment variable $JACK_DEFAULT_SERVER if set, else
22213 "default")
22214 client-name: string (optional)
22216 the client name to use. The server will modify this name to
22217 create a unique variant, if needed unless exact-name is true
22218 (default: the guest's name)
22219 connect-ports: string (optional)
22221 if set, a regular expression of JACK client port name(s) to mon‐
22222 itor for and automatically connect to
22223 start-server: boolean (optional)
22225 start a jack server process if one is not already present (de‐
22226 fault: false)
22227 exact-name: boolean (optional)
22229 use the exact name requested otherwise JACK automatically gener‐
22230 ates a unique one, if needed (default: false)
22231 The members of AudiodevPerDirectionOptions
22233 Since
22235 5.1
22236 AudiodevJackOptions (Object)
22238 Options of the JACK audio backend.
22239 Members
22241 in: AudiodevJackPerDirectionOptions (optional)
22242 options of the capture stream
22243 out: AudiodevJackPerDirectionOptions (optional)
22245 options of the playback stream
22246 Since
22248 5.1
22249 AudiodevOssPerDirectionOptions (Object)
22251 Options of the OSS backend that are used for both playback and record‐
22252 ing.
22253 Members
22255 dev: string (optional)
22256 file name of the OSS device (default '/dev/dsp')
22257 buffer-count: int (optional)
22259 number of buffers
22260 try-poll: boolean (optional)
22262 attempt to use poll mode, falling back to non-polling access on
22263 failure (default true)
22264 The members of AudiodevPerDirectionOptions
22266 Since
22268 4.0
22269 AudiodevOssOptions (Object)
22271 Options of the OSS audio backend.
22272 Members
22274 in: AudiodevOssPerDirectionOptions (optional)
22275 options of the capture stream
22276 out: AudiodevOssPerDirectionOptions (optional)
22278 options of the playback stream
22279 try-mmap: boolean (optional)
22281 try using memory-mapped access, falling back to non-mem‐
22282 ory-mapped access on failure (default true)
22283 exclusive: boolean (optional)
22285 open device in exclusive mode (vmix won't work) (default false)
22286 dsp-policy: int (optional)
22288 set the timing policy of the device (between 0 and 10, where
22289 smaller number means smaller latency but higher CPU usage) or -1
22290 to use fragment mode (option ignored on some platforms) (default
22291 5)
22292 Since
22294 4.0
22295 AudiodevPaPerDirectionOptions (Object)
22297 Options of the Pulseaudio backend that are used for both playback and
22298 recording.
22299 Members
22301 name: string (optional)
22302 name of the sink/source to use
22303 stream-name: string (optional)
22305 name of the PulseAudio stream created by qemu. Can be used to
22306 identify the stream in PulseAudio when you create multiple
22307 PulseAudio devices or run multiple qemu instances (default: au‐
22308 diodev's id, since 4.2)
22309 latency: int (optional)
22311 latency you want PulseAudio to achieve in microseconds (default
22312 15000)
22313 The members of AudiodevPerDirectionOptions
22315 Since
22317 4.0
22318 AudiodevPaOptions (Object)
22320 Options of the PulseAudio audio backend.
22321 Members
22323 in: AudiodevPaPerDirectionOptions (optional)
22324 options of the capture stream
22325 out: AudiodevPaPerDirectionOptions (optional)
22327 options of the playback stream
22328 server: string (optional)
22330 PulseAudio server address (default: let PulseAudio choose)
22331 Since
22333 4.0
22334 AudiodevPipewirePerDirectionOptions (Object)
22336 Options of the PipeWire backend that are used for both playback and
22337 recording.
22338 Members
22340 name: string (optional)
22341 name of the sink/source to use
22342 stream-name: string (optional)
22344 name of the PipeWire stream created by qemu. Can be used to
22345 identify the stream in PipeWire when you create multiple
22346 PipeWire devices or run multiple qemu instances (default: au‐
22347 diodev's id)
22348 latency: int (optional)
22350 latency you want PipeWire to achieve in microseconds (default
22351 46000)
22352 The members of AudiodevPerDirectionOptions
22354 Since
22356 8.1
22357 AudiodevPipewireOptions (Object)
22359 Options of the PipeWire audio backend.
22360 Members
22362 in: AudiodevPipewirePerDirectionOptions (optional)
22363 options of the capture stream
22364 out: AudiodevPipewirePerDirectionOptions (optional)
22366 options of the playback stream
22367 Since
22369 8.1
22370 AudiodevSdlPerDirectionOptions (Object)
22372 Options of the SDL audio backend that are used for both playback and
22373 recording.
22374 Members
22376 buffer-count: int (optional)
22377 number of buffers (default 4)
22378 The members of AudiodevPerDirectionOptions
22380 Since
22382 6.0
22383 AudiodevSdlOptions (Object)
22385 Options of the SDL audio backend.
22386 Members
22388 in: AudiodevSdlPerDirectionOptions (optional)
22389 options of the recording stream
22390 out: AudiodevSdlPerDirectionOptions (optional)
22392 options of the playback stream
22393 Since
22395 6.0
22396 AudiodevWavOptions (Object)
22398 Options of the wav audio backend.
22399 Members
22401 in: AudiodevPerDirectionOptions (optional)
22402 options of the capture stream
22403 out: AudiodevPerDirectionOptions (optional)
22405 options of the playback stream
22406 path: string (optional)
22408 name of the wav file to record (default 'qemu.wav')
22409 Since
22411 4.0
22412 AudioFormat (Enum)
22414 An enumeration of possible audio formats.
22415 Values
22417 u8 unsigned 8 bit integer
22418 s8 signed 8 bit integer
22420 u16 unsigned 16 bit integer
22422 s16 signed 16 bit integer
22424 u32 unsigned 32 bit integer
22426 s32 signed 32 bit integer
22428 f32 single precision floating-point (since 5.0)
22430 Since
22432 4.0
22433 AudiodevDriver (Enum)
22435 An enumeration of possible audio backend drivers.
22436 Values
22438 jack (If: CONFIG_AUDIO_JACK)
22439 JACK audio backend (since 5.1)
22440 none Not documented
22442 alsa (If: CONFIG_AUDIO_ALSA)
22444 Not documented
22445 coreaudio (If: CONFIG_AUDIO_COREAUDIO)
22447 Not documented
22448 dbus (If: CONFIG_DBUS_DISPLAY)
22450 Not documented
22451 dsound (If: CONFIG_AUDIO_DSOUND)
22453 Not documented
22454 oss (If: CONFIG_AUDIO_OSS)
22456 Not documented
22457 pa (If: CONFIG_AUDIO_PA)
22459 Not documented
22460 pipewire (If: CONFIG_AUDIO_PIPEWIRE)
22462 Not documented
22463 sdl (If: CONFIG_AUDIO_SDL)
22465 Not documented
22466 sndio (If: CONFIG_AUDIO_SNDIO)
22468 Not documented
22469 spice (If: CONFIG_SPICE)
22471 Not documented
22472 wav Not documented
22474 Since
22476 4.0
22477 Audiodev (Object)
22479 Options of an audio backend.
22480 Members
22482 id: string
22483 identifier of the backend
22484 driver: AudiodevDriver
22486 the backend driver to use
22487 timer-period: int (optional)
22489 timer period (in microseconds, 0: use lowest possible)
22490 The members of AudiodevGenericOptions when driver is "none"
22492 The members of AudiodevAlsaOptions when driver is "alsa" (If: CON‐
22494 FIG_AUDIO_ALSA)
22495 The members of AudiodevCoreaudioOptions when driver is "coreaudio" (If:
22497 CONFIG_AUDIO_COREAUDIO)
22498 The members of AudiodevGenericOptions when driver is "dbus" (If: CON‐
22500 FIG_DBUS_DISPLAY)
22501 The members of AudiodevDsoundOptions when driver is "dsound" (If: CON‐
22503 FIG_AUDIO_DSOUND)
22504 The members of AudiodevJackOptions when driver is "jack" (If: CON‐
22506 FIG_AUDIO_JACK)
22507 The members of AudiodevOssOptions when driver is "oss" (If: CONFIG_AU‐
22509 DIO_OSS)
22510 The members of AudiodevPaOptions when driver is "pa" (If: CONFIG_AU‐
22512 DIO_PA)
22513 The members of AudiodevPipewireOptions when driver is "pipewire" (If:
22515 CONFIG_AUDIO_PIPEWIRE)
22516 The members of AudiodevSdlOptions when driver is "sdl" (If: CONFIG_AU‐
22518 DIO_SDL)
22519 The members of AudiodevSndioOptions when driver is "sndio" (If: CON‐
22521 FIG_AUDIO_SNDIO)
22522 The members of AudiodevGenericOptions when driver is "spice" (If: CON‐
22524 FIG_SPICE)
22525 The members of AudiodevWavOptions when driver is "wav"
22527 Since
22529 4.0
22530 query-audiodevs (Command)
22532 Returns information about audiodev configuration
22533 Returns
22535 array of Audiodev
22536 Since
22538 8.0
22539
22541 AcpiTableOptions (Object)
22542 Specify an ACPI table on the command line to load.
22543 At most one of file and data can be specified. The list of files spec‐
22545 ified by any one of them is loaded and concatenated in order. If both
22546 are omitted, data is implied.
22547 Other fields / optargs can be used to override fields of the generic
22549 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
22550 System Description Table Header. If a header field is not overridden,
22551 then the corresponding value from the concatenated blob is used (in
22552 case of file), or it is filled in with a hard-coded value (in case of
22553 data).
22554 String fields are copied into the matching ACPI member from lowest ad‐
22556 dress upwards, and silently truncated / NUL-padded to length.
22557 Members
22559 sig: string (optional)
22560 table signature / identifier (4 bytes)
22561 rev: int (optional)
22563 table revision number (dependent on signature, 1 byte)
22564 oem_id: string (optional)
22566 OEM identifier (6 bytes)
22567 oem_table_id: string (optional)
22569 OEM table identifier (8 bytes)
22570 oem_rev: int (optional)
22572 OEM-supplied revision number (4 bytes)
22573 asl_compiler_id: string (optional)
22575 identifier of the utility that created the table (4 bytes)
22576 asl_compiler_rev: int (optional)
22578 revision number of the utility that created the table (4 bytes)
22579 file: string (optional)
22581 colon (:) separated list of pathnames to load and concatenate as
22582 table data. The resultant binary blob is expected to have an
22583 ACPI table header. At least one file is required. This field
22584 excludes data.
22585 data: string (optional)
22587 colon (:) separated list of pathnames to load and concatenate as
22588 table data. The resultant binary blob must not have an ACPI ta‐
22589 ble header. At least one file is required. This field excludes
22590 file.
22591 Since
22593 1.5
22594 ACPISlotType (Enum)
22596 Values
22597 DIMM memory slot
22598 CPU logical CPU slot (since 2.7)
22600 ACPIOSTInfo (Object)
22602 OSPM Status Indication for a device For description of possible values
22603 of source and status fields see "_OST (OSPM Status Indication)" chapter
22604 of ACPI5.0 spec.
22605 Members
22607 device: string (optional)
22608 device ID associated with slot
22609 slot: string
22611 slot ID, unique per slot of a given slot-type
22612 slot-type: ACPISlotType
22614 type of the slot
22615 source: int
22617 an integer containing the source event
22618 status: int
22620 an integer containing the status code
22621 Since
22623 2.1
22624 query-acpi-ospm-status (Command)
22626 Return a list of ACPIOSTInfo for devices that support status reporting
22627 via ACPI _OST method.
22628 Since
22630 2.1
22631 Example
22633 -> { "execute": "query-acpi-ospm-status" }
22634 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
22635 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
22636 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
22637 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
22638 ]}
22639 ACPI_DEVICE_OST (Event)
22641 Emitted when guest executes ACPI _OST method.
22642 Arguments
22644 info: ACPIOSTInfo
22645 OSPM Status Indication
22646 Since
22648 2.1
22649 Example
22651 <- { "event": "ACPI_DEVICE_OST",
22652 "data": { "info": { "device": "d1", "slot": "0",
22653 "slot-type": "DIMM", "source": 1, "status": 0 } },
22654 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
22655
22657 PciMemoryRange (Object)
22658 A PCI device memory region
22659 Members
22661 base: int
22662 the starting address (guest physical)
22663 limit: int
22665 the ending address (guest physical)
22666 Since
22668 0.14
22669 PciMemoryRegion (Object)
22671 Information about a PCI device I/O region.
22672 Members
22674 bar: int
22675 the index of the Base Address Register for this region
22676 type: string
22678 • 'io' if the region is a PIO region
22680 • 'memory' if the region is a MMIO region
22682 size: int
22684 memory size
22685 prefetch: boolean (optional)
22687 if type is 'memory', true if the memory is prefetchable
22688 mem_type_64: boolean (optional)
22690 if type is 'memory', true if the BAR is 64-bit
22691 address: int
22693 Not documented
22694 Since
22696 0.14
22697 PciBusInfo (Object)
22699 Information about a bus of a PCI Bridge device
22700 Members
22702 number: int
22703 primary bus interface number. This should be the number of the
22704 bus the device resides on.
22705 secondary: int
22707 secondary bus interface number. This is the number of the main
22708 bus for the bridge
22709 subordinate: int
22711 This is the highest number bus that resides below the bridge.
22712 io_range: PciMemoryRange
22714 The PIO range for all devices on this bridge
22715 memory_range: PciMemoryRange
22717 The MMIO range for all devices on this bridge
22718 prefetchable_range: PciMemoryRange
22720 The range of prefetchable MMIO for all devices on this bridge
22721 Since
22723 2.4
22724 PciBridgeInfo (Object)
22726 Information about a PCI Bridge device
22727 Members
22729 bus: PciBusInfo
22730 information about the bus the device resides on
22731 devices: array of PciDeviceInfo (optional)
22733 a list of PciDeviceInfo for each device on this bridge
22734 Since
22736 0.14
22737 PciDeviceClass (Object)
22739 Information about the Class of a PCI device
22740 Members
22742 desc: string (optional)
22743 a string description of the device's class
22744 class: int
22746 the class code of the device
22747 Since
22749 2.4
22750 PciDeviceId (Object)
22752 Information about the Id of a PCI device
22753 Members
22755 device: int
22756 the PCI device id
22757 vendor: int
22759 the PCI vendor id
22760 subsystem: int (optional)
22762 the PCI subsystem id (since 3.1)
22763 subsystem-vendor: int (optional)
22765 the PCI subsystem vendor id (since 3.1)
22766 Since
22768 2.4
22769 PciDeviceInfo (Object)
22771 Information about a PCI device
22772 Members
22774 bus: int
22775 the bus number of the device
22776 slot: int
22778 the slot the device is located in
22779 function: int
22781 the function of the slot used by the device
22782 class_info: PciDeviceClass
22784 the class of the device
22785 id: PciDeviceId
22787 the PCI device id
22788 irq: int (optional)
22790 if an IRQ is assigned to the device, the IRQ number
22791 irq_pin: int
22793 the IRQ pin, zero means no IRQ (since 5.1)
22794 qdev_id: string
22796 the device name of the PCI device
22797 pci_bridge: PciBridgeInfo (optional)
22799 if the device is a PCI bridge, the bridge information
22800 regions: array of PciMemoryRegion
22802 a list of the PCI I/O regions associated with the device
22803 Notes
22805 the contents of class_info.desc are not stable and should only be
22806 treated as informational.
22807 Since
22809 0.14
22810 PciInfo (Object)
22812 Information about a PCI bus
22813 Members
22815 bus: int
22816 the bus index
22817 devices: array of PciDeviceInfo
22819 a list of devices on this bus
22820 Since
22822 0.14
22823 query-pci (Command)
22825 Return information about the PCI bus topology of the guest.
22826 Returns
22828 a list of PciInfo for each PCI bus. Each bus is represented by a
22829 json-object, which has a key with a json-array of all PCI devices at‐
22830 tached to it. Each device is represented by a json-object.
22831 Since
22833 0.14
22834 Example
22836 -> { "execute": "query-pci" }
22837 <- { "return": [
22838 {
22839 "bus": 0,
22840 "devices": [
22841 {
22842 "bus": 0,
22843 "qdev_id": "",
22844 "slot": 0,
22845 "class_info": {
22846 "class": 1536,
22847 "desc": "Host bridge"
22848 },
22849 "id": {
22850 "device": 32902,
22851 "vendor": 4663
22852 },
22853 "function": 0,
22854 "regions": [
22855 ]
22856 },
22857 {
22858 "bus": 0,
22859 "qdev_id": "",
22860 "slot": 1,
22861 "class_info": {
22862 "class": 1537,
22863 "desc": "ISA bridge"
22864 },
22865 "id": {
22866 "device": 32902,
22867 "vendor": 28672
22868 },
22869 "function": 0,
22870 "regions": [
22871 ]
22872 },
22873 {
22874 "bus": 0,
22875 "qdev_id": "",
22876 "slot": 1,
22877 "class_info": {
22878 "class": 257,
22879 "desc": "IDE controller"
22880 },
22881 "id": {
22882 "device": 32902,
22883 "vendor": 28688
22884 },
22885 "function": 1,
22886 "regions": [
22887 {
22888 "bar": 4,
22889 "size": 16,
22890 "address": 49152,
22891 "type": "io"
22892 }
22893 ]
22894 },
22895 {
22896 "bus": 0,
22897 "qdev_id": "",
22898 "slot": 2,
22899 "class_info": {
22900 "class": 768,
22901 "desc": "VGA controller"
22902 },
22903 "id": {
22904 "device": 4115,
22905 "vendor": 184
22906 },
22907 "function": 0,
22908 "regions": [
22909 {
22910 "prefetch": true,
22911 "mem_type_64": false,
22912 "bar": 0,
22913 "size": 33554432,
22914 "address": 4026531840,
22915 "type": "memory"
22916 },
22917 {
22918 "prefetch": false,
22919 "mem_type_64": false,
22920 "bar": 1,
22921 "size": 4096,
22922 "address": 4060086272,
22923 "type": "memory"
22924 },
22925 {
22926 "prefetch": false,
22927 "mem_type_64": false,
22928 "bar": 6,
22929 "size": 65536,
22930 "address": -1,
22931 "type": "memory"
22932 }
22933 ]
22934 },
22935 {
22936 "bus": 0,
22937 "qdev_id": "",
22938 "irq": 11,
22939 "slot": 4,
22940 "class_info": {
22941 "class": 1280,
22942 "desc": "RAM controller"
22943 },
22944 "id": {
22945 "device": 6900,
22946 "vendor": 4098
22947 },
22948 "function": 0,
22949 "regions": [
22950 {
22951 "bar": 0,
22952 "size": 32,
22953 "address": 49280,
22954 "type": "io"
22955 }
22956 ]
22957 }
22958 ]
22959 }
22960 ]
22961 }
22962 Note
22964 This example has been shortened as the real response is too long.
22965
22967 StatsType (Enum)
22968 Enumeration of statistics types
22969 Values
22971 cumulative
22972 stat is cumulative; value can only increase.
22973 instant
22975 stat is instantaneous; value can increase or decrease.
22976 peak stat is the peak value; value can only increase.
22978 linear-histogram
22980 stat is a linear histogram.
22981 log2-histogram
22983 stat is a logarithmic histogram, with one bucket for each power
22984 of two.
22985 Since
22987 7.1
22988 StatsUnit (Enum)
22990 Enumeration of unit of measurement for statistics
22991 Values
22993 bytes stat reported in bytes.
22994 seconds
22996 stat reported in seconds.
22997 cycles stat reported in clock cycles.
22999 boolean
23001 stat is a boolean value.
23002 Since
23004 7.1
23005 StatsProvider (Enum)
23007 Enumeration of statistics providers.
23008 Values
23010 kvm since 7.1
23011 cryptodev
23013 since 8.0
23014 Since
23016 7.1
23017 StatsTarget (Enum)
23019 The kinds of objects on which one can request statistics.
23020 Values
23022 vm statistics that apply to the entire virtual machine or the en‐
23023 tire QEMU process.
23024 vcpu statistics that apply to a single virtual CPU.
23026 cryptodev
23028 statistics that apply to a crypto device (since 8.0)
23029 Since
23031 7.1
23032 StatsRequest (Object)
23034 Indicates a set of statistics that should be returned by query-stats.
23035 Members
23037 provider: StatsProvider
23038 provider for which to return statistics.
23039 names: array of string (optional)
23041 statistics to be returned (all if omitted).
23042 Since
23044 7.1
23045 StatsVCPUFilter (Object)
23047 Members
23048 vcpus: array of string (optional)
23049 list of QOM paths for the desired vCPU objects.
23050 Since
23052 7.1
23053 StatsFilter (Object)
23055 The arguments to the query-stats command; specifies a target for which
23056 to request statistics and optionally the required subset of information
23057 for that target:
23058 • which vCPUs to request statistics for
23060 • which providers to request statistics from
23062 • which named values to return within each provider
23064 Members
23066 target: StatsTarget
23067 Not documented
23068 providers: array of StatsRequest (optional)
23070 Not documented
23071 The members of StatsVCPUFilter when target is "vcpu"
23073 Since
23075 7.1
23076 StatsValue (Alternate)
23078 Members
23079 scalar: int
23080 single unsigned 64-bit integers.
23081 list: array of int
23083 list of unsigned 64-bit integers (used for histograms).
23084 boolean: boolean
23086 Not documented
23087 Since
23089 7.1
23090 Stats (Object)
23092 Members
23093 name: string
23094 name of stat.
23095 value: StatsValue
23097 stat value.
23098 Since
23100 7.1
23101 StatsResult (Object)
23103 Members
23104 provider: StatsProvider
23105 provider for this set of statistics.
23106 qom-path: string (optional)
23108 Path to the object for which the statistics are returned, if the
23109 object is exposed in the QOM tree
23110 stats: array of Stats
23112 list of statistics.
23113 Since
23115 7.1
23116 query-stats (Command)
23118 Return runtime-collected statistics for objects such as the VM or its
23119 vCPUs.
23120 The arguments are a StatsFilter and specify the provider and objects to
23122 return statistics about.
23123 Arguments
23125 The members of StatsFilter
23126 Returns
23128 a list of StatsResult, one for each provider and object (e.g., for each
23129 vCPU).
23130 Since
23132 7.1
23133 StatsSchemaValue (Object)
23135 Schema for a single statistic.
23136 Members
23138 name: string
23139 name of the statistic; each element of the schema is uniquely
23140 identified by a target, a provider (both available in StatsS‐
23141 chema) and the name.
23142 type: StatsType
23144 kind of statistic.
23145 unit: StatsUnit (optional)
23147 basic unit of measure for the statistic; if missing, the statis‐
23148 tic is a simple number or counter.
23149 base: int (optional)
23151 base for the multiple of unit in which the statistic is mea‐
23152 sured. Only present if exponent is non-zero; base and exponent
23153 together form a SI prefix (e.g., _nano-_ for base=10 and expo‐
23154 nent=-9) or IEC binary prefix (e.g. _kibi-_ for base=2 and ex‐
23155 ponent=10)
23156 exponent: int
23158 exponent for the multiple of unit in which the statistic is ex‐
23159 pressed, or 0 for the basic unit
23160 bucket-size: int (optional)
23162 Present when type is "linear-histogram", contains the width of
23163 each bucket of the histogram.
23164 Since
23166 7.1
23167 StatsSchema (Object)
23169 Schema for all available statistics for a provider and target.
23170 Members
23172 provider: StatsProvider
23173 provider for this set of statistics.
23174 target: StatsTarget
23176 the kind of object that can be queried through the provider.
23177 stats: array of StatsSchemaValue
23179 list of statistics.
23180 Since
23182 7.1
23183 query-stats-schemas (Command)
23185 Return the schema for all available runtime-collected statistics.
23186 Arguments
23188 provider: StatsProvider (optional)
23189 Not documented
23190 Note
23192 runtime-collected statistics and their names fall outside QEMU's usual
23193 deprecation policies. QEMU will try to keep the set of available data
23194 stable, together with their names, but will not guarantee stability at
23195 all costs; the same is true of providers that source statistics exter‐
23196 nally, e.g. from Linux. For example, if the same value is being
23197 tracked with different names on different architectures or by different
23198 providers, one of them might be renamed. A statistic might go away if
23199 an algorithm is changed or some code is removed; changing a default
23200 might cause previously useful statistics to always report 0. Such
23201 changes, however, are expected to be rare.
23202 Since
23204 7.1
23205
23207 VirtioInfo (Object)
23208 Basic information about a given VirtIODevice
23209 Members
23211 path: string
23212 The VirtIODevice's canonical QOM path
23213 name: string
23215 Name of the VirtIODevice
23216 Since
23218 7.2
23219 x-query-virtio (Command)
23221 Returns a list of all realized VirtIODevices
23222 Features
23224 unstable
23225 This command is meant for debugging.
23226 Returns
23228 List of gathered VirtIODevices
23229 Since
23231 7.2
23232 Example
23234 -> { "execute": "x-query-virtio" }
23235 <- { "return": [
23236 {
23237 "name": "virtio-input",
23238 "path": "/machine/peripheral-anon/device[4]/virtio-backend"
23239 },
23240 {
23241 "name": "virtio-crypto",
23242 "path": "/machine/peripheral/crypto0/virtio-backend"
23243 },
23244 {
23245 "name": "virtio-scsi",
23246 "path": "/machine/peripheral-anon/device[2]/virtio-backend"
23247 },
23248 {
23249 "name": "virtio-net",
23250 "path": "/machine/peripheral-anon/device[1]/virtio-backend"
23251 },
23252 {
23253 "name": "virtio-serial",
23254 "path": "/machine/peripheral-anon/device[0]/virtio-backend"
23255 }
23256 ]
23257 }
23258 VhostStatus (Object)
23260 Information about a vhost device. This information will only be dis‐
23261 played if the vhost device is active.
23262 Members
23264 n-mem-sections: int
23265 vhost_dev n_mem_sections
23266 n-tmp-sections: int
23268 vhost_dev n_tmp_sections
23269 nvqs: int
23271 vhost_dev nvqs (number of virtqueues being used)
23272 vq-index: int
23274 vhost_dev vq_index
23275 features: VirtioDeviceFeatures
23277 vhost_dev features
23278 acked-features: VirtioDeviceFeatures
23280 vhost_dev acked_features
23281 backend-features: VirtioDeviceFeatures
23283 vhost_dev backend_features
23284 protocol-features: VhostDeviceProtocols
23286 vhost_dev protocol_features
23287 max-queues: int
23289 vhost_dev max_queues
23290 backend-cap: int
23292 vhost_dev backend_cap
23293 log-enabled: boolean
23295 vhost_dev log_enabled flag
23296 log-size: int
23298 vhost_dev log_size
23299 Since
23301 7.2
23302 VirtioStatus (Object)
23304 Full status of the virtio device with most VirtIODevice members. Also
23305 includes the full status of the corresponding vhost device if the vhost
23306 device is active.
23307 Members
23309 name: string
23310 VirtIODevice name
23311 device-id: int
23313 VirtIODevice ID
23314 vhost-started: boolean
23316 VirtIODevice vhost_started flag
23317 guest-features: VirtioDeviceFeatures
23319 VirtIODevice guest_features
23320 host-features: VirtioDeviceFeatures
23322 VirtIODevice host_features
23323 backend-features: VirtioDeviceFeatures
23325 VirtIODevice backend_features
23326 device-endian: string
23328 VirtIODevice device_endian
23329 num-vqs: int
23331 VirtIODevice virtqueue count. This is the number of active
23332 virtqueues being used by the VirtIODevice.
23333 status: VirtioDeviceStatus
23335 VirtIODevice configuration status (VirtioDeviceStatus)
23336 isr: int
23338 VirtIODevice ISR
23339 queue-sel: int
23341 VirtIODevice queue_sel
23342 vm-running: boolean
23344 VirtIODevice vm_running flag
23345 broken: boolean
23347 VirtIODevice broken flag
23348 disabled: boolean
23350 VirtIODevice disabled flag
23351 use-started: boolean
23353 VirtIODevice use_started flag
23354 started: boolean
23356 VirtIODevice started flag
23357 start-on-kick: boolean
23359 VirtIODevice start_on_kick flag
23360 disable-legacy-check: boolean
23362 VirtIODevice disabled_legacy_check flag
23363 bus-name: string
23365 VirtIODevice bus_name
23366 use-guest-notifier-mask: boolean
23368 VirtIODevice use_guest_notifier_mask flag
23369 vhost-dev: VhostStatus (optional)
23371 Corresponding vhost device info for a given VirtIODevice.
23372 Present if the given VirtIODevice has an active vhost device.
23373 Since
23375 7.2
23376 x-query-virtio-status (Command)
23378 Poll for a comprehensive status of a given virtio device
23379 Arguments
23381 path: string
23382 Canonical QOM path of the VirtIODevice
23383 Features
23385 unstable
23386 This command is meant for debugging.
23387 Returns
23389 VirtioStatus of the virtio device
23390 Since
23392 7.2
23393 Examples
23395 1. Poll for the status of virtio-crypto (no vhost-crypto active)
23396 -> { "execute": "x-query-virtio-status",
23398 "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
23399 }
23400 <- { "return": {
23401 "device-endian": "little",
23402 "bus-name": "",
23403 "disable-legacy-check": false,
23404 "name": "virtio-crypto",
23405 "started": true,
23406 "device-id": 20,
23407 "backend-features": {
23408 "transports": [],
23409 "dev-features": []
23410 },
23411 "start-on-kick": false,
23412 "isr": 1,
23413 "broken": false,
23414 "status": {
23415 "statuses": [
23416 "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
23417 "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
23418 "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
23419 "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
23420 ]
23421 },
23422 "num-vqs": 2,
23423 "guest-features": {
23424 "dev-features": [],
23425 "transports": [
23426 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
23427 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
23428 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
23429 ]
23430 },
23431 "host-features": {
23432 "unknown-dev-features": 1073741824,
23433 "dev-features": [],
23434 "transports": [
23435 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
23436 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
23437 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
23438 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
23439 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
23440 ]
23441 },
23442 "use-guest-notifier-mask": true,
23443 "vm-running": true,
23444 "queue-sel": 1,
23445 "disabled": false,
23446 "vhost-started": false,
23447 "use-started": true
23448 }
23449 }
23450 2. Poll for the status of virtio-net (vhost-net is active)
23452 -> { "execute": "x-query-virtio-status",
23454 "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
23455 }
23456 <- { "return": {
23457 "device-endian": "little",
23458 "bus-name": "",
23459 "disabled-legacy-check": false,
23460 "name": "virtio-net",
23461 "started": true,
23462 "device-id": 1,
23463 "vhost-dev": {
23464 "n-tmp-sections": 4,
23465 "n-mem-sections": 4,
23466 "max-queues": 1,
23467 "backend-cap": 2,
23468 "log-size": 0,
23469 "backend-features": {
23470 "dev-features": [],
23471 "transports": []
23472 },
23473 "nvqs": 2,
23474 "protocol-features": {
23475 "protocols": []
23476 },
23477 "vq-index": 0,
23478 "log-enabled": false,
23479 "acked-features": {
23480 "dev-features": [
23481 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
23482 ],
23483 "transports": [
23484 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
23485 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
23486 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
23487 ]
23488 },
23489 "features": {
23490 "dev-features": [
23491 "VHOST_F_LOG_ALL: Logging write descriptors supported",
23492 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
23493 ],
23494 "transports": [
23495 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
23496 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
23497 "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform",
23498 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
23499 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
23500 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
23501 ]
23502 }
23503 },
23504 "backend-features": {
23505 "dev-features": [
23506 "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
23507 "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
23508 "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
23509 "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
23510 "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
23511 "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
23512 "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
23513 "VIRTIO_NET_F_CTRL_VQ: Control channel available",
23514 "VIRTIO_NET_F_STATUS: Configuration status field available",
23515 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
23516 "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
23517 "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
23518 "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
23519 "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
23520 "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
23521 "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
23522 "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
23523 "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
23524 "VIRTIO_NET_F_MAC: Device has given MAC address",
23525 "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
23526 "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
23527 "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
23528 ],
23529 "transports": [
23530 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
23531 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
23532 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
23533 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
23534 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
23535 ]
23536 },
23537 "start-on-kick": false,
23538 "isr": 1,
23539 "broken": false,
23540 "status": {
23541 "statuses": [
23542 "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
23543 "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
23544 "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
23545 "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
23546 ]
23547 },
23548 "num-vqs": 3,
23549 "guest-features": {
23550 "dev-features": [
23551 "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
23552 "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
23553 "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
23554 "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
23555 "VIRTIO_NET_F_CTRL_VQ: Control channel available",
23556 "VIRTIO_NET_F_STATUS: Configuration status field available",
23557 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
23558 "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
23559 "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
23560 "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
23561 "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
23562 "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
23563 "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
23564 "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
23565 "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
23566 "VIRTIO_NET_F_MAC: Device has given MAC address",
23567 "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
23568 "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
23569 "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
23570 ],
23571 "transports": [
23572 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
23573 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
23574 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
23575 ]
23576 },
23577 "host-features": {
23578 "dev-features": [
23579 "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
23580 "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
23581 "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
23582 "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
23583 "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
23584 "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
23585 "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
23586 "VIRTIO_NET_F_CTRL_VQ: Control channel available",
23587 "VIRTIO_NET_F_STATUS: Configuration status field available",
23588 "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
23589 "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
23590 "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
23591 "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
23592 "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
23593 "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
23594 "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
23595 "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
23596 "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
23597 "VIRTIO_NET_F_MAC: Device has given MAC address",
23598 "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
23599 "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
23600 "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
23601 ],
23602 "transports": [
23603 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
23604 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
23605 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
23606 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
23607 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
23608 ]
23609 },
23610 "use-guest-notifier-mask": true,
23611 "vm-running": true,
23612 "queue-sel": 2,
23613 "disabled": false,
23614 "vhost-started": true,
23615 "use-started": true
23616 }
23617 }
23618 VirtioDeviceStatus (Object)
23620 A structure defined to list the configuration statuses of a virtio de‐
23621 vice
23622 Members
23624 statuses: array of string
23625 List of decoded configuration statuses of the virtio device
23626 unknown-statuses: int (optional)
23628 Virtio device statuses bitmap that have not been decoded
23629 Since
23631 7.2
23632 VhostDeviceProtocols (Object)
23634 A structure defined to list the vhost user protocol features of a Vhost
23635 User device
23636 Members
23638 protocols: array of string
23639 List of decoded vhost user protocol features of a vhost user de‐
23640 vice
23641 unknown-protocols: int (optional)
23643 Vhost user device protocol features bitmap that have not been
23644 decoded
23645 Since
23647 7.2
23648 VirtioDeviceFeatures (Object)
23650 The common fields that apply to most Virtio devices. Some devices may
23651 not have their own device-specific features (e.g. virtio-rng).
23652 Members
23654 transports: array of string
23655 List of transport features of the virtio device
23656 dev-features: array of string (optional)
23658 List of device-specific features (if the device has unique fea‐
23659 tures)
23660 unknown-dev-features: int (optional)
23662 Virtio device features bitmap that have not been decoded
23663 Since
23665 7.2
23666 VirtQueueStatus (Object)
23668 Information of a VirtIODevice VirtQueue, including most members of the
23669 VirtQueue data structure.
23670 Members
23672 name: string
23673 Name of the VirtIODevice that uses this VirtQueue
23674 queue-index: int
23676 VirtQueue queue_index
23677 inuse: int
23679 VirtQueue inuse
23680 vring-num: int
23682 VirtQueue vring.num
23683 vring-num-default: int
23685 VirtQueue vring.num_default
23686 vring-align: int
23688 VirtQueue vring.align
23689 vring-desc: int
23691 VirtQueue vring.desc (descriptor area)
23692 vring-avail: int
23694 VirtQueue vring.avail (driver area)
23695 vring-used: int
23697 VirtQueue vring.used (device area)
23698 last-avail-idx: int (optional)
23700 VirtQueue last_avail_idx or return of vhost_dev
23701 vhost_get_vring_base (if vhost active)
23702 shadow-avail-idx: int (optional)
23704 VirtQueue shadow_avail_idx
23705 used-idx: int
23707 VirtQueue used_idx
23708 signalled-used: int
23710 VirtQueue signalled_used
23711 signalled-used-valid: boolean
23713 VirtQueue signalled_used_valid flag
23714 Since
23716 7.2
23717 x-query-virtio-queue-status (Command)
23719 Return the status of a given VirtIODevice's VirtQueue
23720 Arguments
23722 path: string
23723 VirtIODevice canonical QOM path
23724 queue: int
23726 VirtQueue index to examine
23727 Features
23729 unstable
23730 This command is meant for debugging.
23731 Returns
23733 VirtQueueStatus of the VirtQueue
23734 Notes
23736 last_avail_idx will not be displayed in the case where the selected
23737 VirtIODevice has a running vhost device and the VirtIODevice VirtQueue
23738 index (queue) does not exist for the corresponding vhost device
23739 vhost_virtqueue. Also, shadow_avail_idx will not be displayed in the
23740 case where the selected VirtIODevice has a running vhost device.
23741 Since
23743 7.2
23744 Examples
23746 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
23747 -> { "execute": "x-query-virtio-queue-status",
23749 "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
23750 "queue": 1 }
23751 }
23752 <- { "return": {
23753 "signalled-used": 0,
23754 "inuse": 0,
23755 "name": "vhost-vsock",
23756 "vring-align": 4096,
23757 "vring-desc": 5217370112,
23758 "signalled-used-valid": false,
23759 "vring-num-default": 128,
23760 "vring-avail": 5217372160,
23761 "queue-index": 1,
23762 "last-avail-idx": 0,
23763 "vring-used": 5217372480,
23764 "used-idx": 0,
23765 "vring-num": 128
23766 }
23767 }
23768 2. Get VirtQueueStatus for virtio-serial (no vhost)
23770 -> { "execute": "x-query-virtio-queue-status",
23772 "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
23773 "queue": 20 }
23774 }
23775 <- { "return": {
23776 "signalled-used": 0,
23777 "inuse": 0,
23778 "name": "virtio-serial",
23779 "vring-align": 4096,
23780 "vring-desc": 5182074880,
23781 "signalled-used-valid": false,
23782 "vring-num-default": 128,
23783 "vring-avail": 5182076928,
23784 "queue-index": 20,
23785 "last-avail-idx": 0,
23786 "vring-used": 5182077248,
23787 "used-idx": 0,
23788 "shadow-avail-idx": 0,
23789 "vring-num": 128
23790 }
23791 }
23792 VirtVhostQueueStatus (Object)
23794 Information of a vhost device's vhost_virtqueue, including most members
23795 of the vhost_dev vhost_virtqueue data structure.
23796 Members
23798 name: string
23799 Name of the VirtIODevice that uses this vhost_virtqueue
23800 kick: int
23802 vhost_virtqueue kick
23803 call: int
23805 vhost_virtqueue call
23806 desc: int
23808 vhost_virtqueue desc
23809 avail: int
23811 vhost_virtqueue avail
23812 used: int
23814 vhost_virtqueue used
23815 num: int
23817 vhost_virtqueue num
23818 desc-phys: int
23820 vhost_virtqueue desc_phys (descriptor area phys. addr.)
23821 desc-size: int
23823 vhost_virtqueue desc_size
23824 avail-phys: int
23826 vhost_virtqueue avail_phys (driver area phys. addr.)
23827 avail-size: int
23829 vhost_virtqueue avail_size
23830 used-phys: int
23832 vhost_virtqueue used_phys (device area phys. addr.)
23833 used-size: int
23835 vhost_virtqueue used_size
23836 Since
23838 7.2
23839 x-query-virtio-vhost-queue-status (Command)
23841 Return information of a given vhost device's vhost_virtqueue
23842 Arguments
23844 path: string
23845 VirtIODevice canonical QOM path
23846 queue: int
23848 vhost_virtqueue index to examine
23849 Features
23851 unstable
23852 This command is meant for debugging.
23853 Returns
23855 VirtVhostQueueStatus of the vhost_virtqueue
23856 Since
23858 7.2
23859 Examples
23861 1. Get vhost_virtqueue status for vhost-crypto
23862 -> { "execute": "x-query-virtio-vhost-queue-status",
23864 "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
23865 "queue": 0 }
23866 }
23867 <- { "return": {
23868 "avail-phys": 5216124928,
23869 "name": "virtio-crypto",
23870 "used-phys": 5216127040,
23871 "avail-size": 2054,
23872 "desc-size": 16384,
23873 "used-size": 8198,
23874 "desc": 140141447430144,
23875 "num": 1024,
23876 "call": 0,
23877 "avail": 140141447446528,
23878 "desc-phys": 5216108544,
23879 "used": 140141447448640,
23880 "kick": 0
23881 }
23882 }
23883 2. Get vhost_virtqueue status for vhost-vsock
23885 -> { "execute": "x-query-virtio-vhost-queue-status",
23887 "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
23888 "queue": 0 }
23889 }
23890 <- { "return": {
23891 "avail-phys": 5182261248,
23892 "name": "vhost-vsock",
23893 "used-phys": 5182261568,
23894 "avail-size": 262,
23895 "desc-size": 2048,
23896 "used-size": 1030,
23897 "desc": 140141413580800,
23898 "num": 128,
23899 "call": 0,
23900 "avail": 140141413582848,
23901 "desc-phys": 5182259200,
23902 "used": 140141413583168,
23903 "kick": 0
23904 }
23905 }
23906 VirtioRingDesc (Object)
23908 Information regarding the vring descriptor area
23909 Members
23911 addr: int
23912 Guest physical address of the descriptor area
23913 len: int
23915 Length of the descriptor area
23916 flags: array of string
23918 List of descriptor flags
23919 Since
23921 7.2
23922 VirtioRingAvail (Object)
23924 Information regarding the avail vring (a.k.a. driver area)
23925 Members
23927 flags: int
23928 VRingAvail flags
23929 idx: int
23931 VRingAvail index
23932 ring: int
23934 VRingAvail ring[] entry at provided index
23935 Since
23937 7.2
23938 VirtioRingUsed (Object)
23940 Information regarding the used vring (a.k.a. device area)
23941 Members
23943 flags: int
23944 VRingUsed flags
23945 idx: int
23947 VRingUsed index
23948 Since
23950 7.2
23951 VirtioQueueElement (Object)
23953 Information regarding a VirtQueue's VirtQueueElement including descrip‐
23954 tor, driver, and device areas
23955 Members
23957 name: string
23958 Name of the VirtIODevice that uses this VirtQueue
23959 index: int
23961 Index of the element in the queue
23962 descs: array of VirtioRingDesc
23964 List of descriptors (VirtioRingDesc)
23965 avail: VirtioRingAvail
23967 VRingAvail info
23968 used: VirtioRingUsed
23970 VRingUsed info
23971 Since
23973 7.2
23974 x-query-virtio-queue-element (Command)
23976 Return the information about a VirtQueue's VirtQueueElement
23977 Arguments
23979 path: string
23980 VirtIODevice canonical QOM path
23981 queue: int
23983 VirtQueue index to examine
23984 index: int (optional)
23986 Index of the element in the queue (default: head of the queue)
23987 Features
23989 unstable
23990 This command is meant for debugging.
23991 Returns
23993 VirtioQueueElement information
23994 Since
23996 7.2
23997 Examples
23999 1. Introspect on virtio-net's VirtQueue 0 at index 5
24000 -> { "execute": "x-query-virtio-queue-element",
24002 "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
24003 "queue": 0,
24004 "index": 5 }
24005 }
24006 <- { "return": {
24007 "index": 5,
24008 "name": "virtio-net",
24009 "descs": [
24010 {
24011 "flags": ["write"],
24012 "len": 1536,
24013 "addr": 5257305600
24014 }
24015 ],
24016 "avail": {
24017 "idx": 256,
24018 "flags": 0,
24019 "ring": 5
24020 },
24021 "used": {
24022 "idx": 13,
24023 "flags": 0
24024 }
24025 }
24026 }
24027 2. Introspect on virtio-crypto's VirtQueue 1 at head
24029 -> { "execute": "x-query-virtio-queue-element",
24031 "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
24032 "queue": 1 }
24033 }
24034 <- { "return": {
24035 "index": 0,
24036 "name": "virtio-crypto",
24037 "descs": [
24038 {
24039 "flags": [],
24040 "len": 0,
24041 "addr": 8080268923184214134
24042 }
24043 ],
24044 "avail": {
24045 "idx": 280,
24046 "flags": 0,
24047 "ring": 0
24048 },
24049 "used": {
24050 "idx": 280,
24051 "flags": 0
24052 }
24053 }
24054 }
24055 3. Introspect on virtio-scsi's VirtQueue 2 at head
24057 -> { "execute": "x-query-virtio-queue-element",
24059 "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
24060 "queue": 2 }
24061 }
24062 <- { "return": {
24063 "index": 19,
24064 "name": "virtio-scsi",
24065 "descs": [
24066 {
24067 "flags": ["used", "indirect", "write"],
24068 "len": 4099327944,
24069 "addr": 12055409292258155293
24070 }
24071 ],
24072 "avail": {
24073 "idx": 1147,
24074 "flags": 0,
24075 "ring": 19
24076 },
24077 "used": {
24078 "idx": 280,
24079 "flags": 0
24080 }
24081 }
24082 }
24083
24085 QCryptodevBackendAlgType (Enum)
24086 The supported algorithm types of a crypto device.
24087 Values
24089 sym symmetric encryption
24090 asym asymmetric Encryption
24092 Since
24094 8.0
24095 QCryptodevBackendServiceType (Enum)
24097 The supported service types of a crypto device.
24098 Values
24100 cipher Not documented
24101 hash Not documented
24103 mac Not documented
24105 aead Not documented
24107 akcipher
24109 Not documented
24110 Since
24112 8.0
24113 QCryptodevBackendType (Enum)
24115 The crypto device backend type
24116 Values
24118 builtin
24119 the QEMU builtin support
24120 vhost-user
24122 vhost-user
24123 lkcf Linux kernel cryptographic framework
24125 Since
24127 8.0
24128 QCryptodevBackendClient (Object)
24130 Information about a queue of crypto device.
24131 Members
24133 queue: int
24134 the queue index of the crypto device
24135 type: QCryptodevBackendType
24137 the type of the crypto device
24138 Since
24140 8.0
24141 QCryptodevInfo (Object)
24143 Information about a crypto device.
24144 Members
24146 id: string
24147 the id of the crypto device
24148 service: array of QCryptodevBackendServiceType
24150 supported service types of a crypto device
24151 client: array of QCryptodevBackendClient
24153 the additional information of the crypto device
24154 Since
24156 8.0
24157 query-cryptodev (Command)
24159 Returns information about current crypto devices.
24160 Returns
24162 a list of QCryptodevInfo
24163 Since
24165 8.0
24166
24168 CxlEventLog (Enum)
24169 CXL has a number of separate event logs for different types of events.
24170 Each such event log is handled and signaled independently.
24171 Values
24173 informational
24174 Information Event Log
24175 warning
24177 Warning Event Log
24178 failure
24180 Failure Event Log
24181 fatal Fatal Event Log
24183 Since
24185 8.1
24186 cxl-inject-general-media-event (Command)
24188 Inject an event record for a General Media Event (CXL r3.0
24189 8.2.9.2.1.1). This event type is reported via one of the event logs
24190 specified via the log parameter.
24191 Arguments
24193 path: string
24194 CXL type 3 device canonical QOM path
24195 log: CxlEventLog
24197 event log to add the event to
24198 flags: int
24200 Event Record Flags. See CXL r3.0 Table 8-42 Common Event Record
24201 Format, Event Record Flags for subfield definitions.
24202 dpa: int
24204 Device Physical Address (relative to path device). Note lower
24205 bits include some flags. See CXL r3.0 Table 8-43 General Media
24206 Event Record, Physical Address.
24207 descriptor: int
24209 Memory Event Descriptor with additional memory event informa‐
24210 tion. See CXL r3.0 Table 8-43 General Media Event Record, Mem‐
24211 ory Event Descriptor for bit definitions.
24212 type: int
24214 Type of memory event that occurred. See CXL r3.0 Table 8-43
24215 General Media Event Record, Memory Event Type for possible val‐
24216 ues.
24217 transaction-type: int
24219 Type of first transaction that caused the event to occur. See
24220 CXL r3.0 Table 8-43 General Media Event Record, Transaction Type
24221 for possible values.
24222 channel: int (optional)
24224 The channel of the memory event location. A channel is an in‐
24225 terface that can be independently accessed for a transaction.
24226 rank: int (optional)
24228 The rank of the memory event location. A rank is a set of mem‐
24229 ory devices on a channel that together execute a transaction.
24230 device: int (optional)
24232 Bitmask that represents all devices in the rank associated with
24233 the memory event location.
24234 component-id: string (optional)
24236 Device specific component identifier for the event. May de‐
24237 scribe a field replaceable sub-component of the device.
24238 Since
24240 8.1
24241 cxl-inject-dram-event (Command)
24243 Inject an event record for a DRAM Event (CXL r3.0 8.2.9.2.1.2). This
24244 event type is reported via one of the event logs specified via the log
24245 parameter.
24246 Arguments
24248 path: string
24249 CXL type 3 device canonical QOM path
24250 log: CxlEventLog
24252 Event log to add the event to
24253 flags: int
24255 Event Record Flags. See CXL r3.0 Table 8-42 Common Event Record
24256 Format, Event Record Flags for subfield definitions.
24257 dpa: int
24259 Device Physical Address (relative to path device). Note lower
24260 bits include some flags. See CXL r3.0 Table 8-44 DRAM Event
24261 Record, Physical Address.
24262 descriptor: int
24264 Memory Event Descriptor with additional memory event informa‐
24265 tion. See CXL r3.0 Table 8-44 DRAM Event Record, Memory Event
24266 Descriptor for bit definitions.
24267 type: int
24269 Type of memory event that occurred. See CXL r3.0 Table 8-44
24270 DRAM Event Record, Memory Event Type for possible values.
24271 transaction-type: int
24273 Type of first transaction that caused the event to occur. See
24274 CXL r3.0 Table 8-44 DRAM Event Record, Transaction Type for pos‐
24275 sible values.
24276 channel: int (optional)
24278 The channel of the memory event location. A channel is an in‐
24279 terface that can be independently accessed for a transaction.
24280 rank: int (optional)
24282 The rank of the memory event location. A rank is a set of mem‐
24283 ory devices on a channel that together execute a transaction.
24284 nibble-mask: int (optional)
24286 Identifies one or more nibbles that the error affects
24287 bank-group: int (optional)
24289 Bank group of the memory event location, incorporating a number
24290 of Banks.
24291 bank: int (optional)
24293 Bank of the memory event location. A single bank is accessed
24294 per read or write of the memory.
24295 row: int (optional)
24297 Row address within the DRAM.
24298 column: int (optional)
24300 Column address within the DRAM.
24301 correction-mask: array of int (optional)
24303 Bits within each nibble. Used in order of bits set in the nib‐
24304 ble-mask. Up to 4 nibbles may be covered.
24305 Since
24307 8.1
24308 cxl-inject-memory-module-event (Command)
24310 Inject an event record for a Memory Module Event (CXL r3.0
24311 8.2.9.2.1.3). This event includes a copy of the Device Health info at
24312 the time of the event.
24313 Arguments
24315 path: string
24316 CXL type 3 device canonical QOM path
24317 log: CxlEventLog
24319 Event Log to add the event to
24320 flags: int
24322 Event Record Flags. See CXL r3.0 Table 8-42 Common Event Record
24323 Format, Event Record Flags for subfield definitions.
24324 type: int
24326 Device Event Type. See CXL r3.0 Table 8-45 Memory Module Event
24327 Record for bit definitions for bit definiions.
24328 health-status: int
24330 Overall health summary bitmap. See CXL r3.0 Table 8-100 Get
24331 Health Info Output Payload, Health Status for bit definitions.
24332 media-status: int
24334 Overall media health summary. See CXL r3.0 Table 8-100 Get
24335 Health Info Output Payload, Media Status for bit definitions.
24336 additional-status: int
24338 See CXL r3.0 Table 8-100 Get Health Info Output Payload, Addi‐
24339 tional Status for subfield definitions.
24340 life-used: int
24342 Percentage (0-100) of factory expected life span.
24343 temperature: int
24345 Device temperature in degrees Celsius.
24346 dirty-shutdown-count: int
24348 Number of times the device has been unable to determine whether
24349 data loss may have occurred.
24350 corrected-volatile-error-count: int
24352 Total number of correctable errors in volatile memory.
24353 corrected-persistent-error-count: int
24355 Total number of correctable errors in persistent memory
24356 Since
24358 8.1
24359 cxl-inject-poison (Command)
24361 Poison records indicate that a CXL memory device knows that a particu‐
24362 lar memory region may be corrupted. This may be because of locally de‐
24363 tected errors (e.g. ECC failure) or poisoned writes received from other
24364 components in the system. This injection mechanism enables testing of
24365 the OS handling of poison records which may be queried via the CXL
24366 mailbox.
24367 Arguments
24369 path: string
24370 CXL type 3 device canonical QOM path
24371 start: int
24373 Start address; must be 64 byte aligned.
24374 length: int
24376 Length of poison to inject; must be a multiple of 64 bytes.
24377 Since
24379 8.1
24380 CxlUncorErrorType (Enum)
24382 Type of uncorrectable CXL error to inject. These errors are reported
24383 via an AER uncorrectable internal error with additional information
24384 logged at the CXL device.
24385 Values
24387 cache-data-parity
24388 Data error such as data parity or data ECC error CXL.cache
24389 cache-address-parity
24391 Address parity or other errors associated with the address field
24392 on CXL.cache
24393 cache-be-parity
24395 Byte enable parity or other byte enable errors on CXL.cache
24396 cache-data-ecc
24398 ECC error on CXL.cache
24399 mem-data-parity
24401 Data error such as data parity or data ECC error on CXL.mem
24402 mem-address-parity
24404 Address parity or other errors associated with the address field
24405 on CXL.mem
24406 mem-be-parity
24408 Byte enable parity or other byte enable errors on CXL.mem.
24409 mem-data-ecc
24411 Data ECC error on CXL.mem.
24412 reinit-threshold
24414 REINIT threshold hit.
24415 rsvd-encoding
24417 Received unrecognized encoding.
24418 poison-received
24420 Received poison from the peer.
24421 receiver-overflow
24423 Buffer overflows (first 3 bits of header log indicate which)
24424 internal
24426 Component specific error
24427 cxl-ide-tx
24429 Integrity and data encryption tx error.
24430 cxl-ide-rx
24432 Integrity and data encryption rx error.
24433 Since
24435 8.0
24436 CXLUncorErrorRecord (Object)
24438 Record of a single error including header log.
24439 Members
24441 type: CxlUncorErrorType
24442 Type of error
24443 header: array of int
24445 16 DWORD of header.
24446 Since
24448 8.0
24449 cxl-inject-uncorrectable-errors (Command)
24451 Command to allow injection of multiple errors in one go. This allows
24452 testing of multiple header log handling in the OS.
24453 Arguments
24455 path: string
24456 CXL Type 3 device canonical QOM path
24457 errors: array of CXLUncorErrorRecord
24459 Errors to inject
24460 Since
24462 8.0
24463 CxlCorErrorType (Enum)
24465 Type of CXL correctable error to inject
24466 Values
24468 cache-data-ecc
24469 Data ECC error on CXL.cache
24470 mem-data-ecc
24472 Data ECC error on CXL.mem
24473 crc-threshold
24475 Component specific and applicable to 68 byte Flit mode only.
24476 cache-poison-received
24478 Received poison from a peer on CXL.cache.
24479 mem-poison-received
24481 Received poison from a peer on CXL.mem
24482 physical
24484 Received error indication from the physical layer.
24485 retry-threshold
24487 Not documented
24488 Since
24490 8.0
24491 cxl-inject-correctable-error (Command)
24493 Command to inject a single correctable error. Multiple error injection
24494 of this error type is not interesting as there is no associated header
24495 log. These errors are reported via AER as a correctable internal er‐
24496 ror, with additional detail available from the CXL device.
24497 Arguments
24499 path: string
24500 CXL Type 3 device canonical QOM path
24501 type: CxlCorErrorType
24503 Type of error.
24504 Since
24506 8.0
24507
24509 2023, The QEMU Project Developers
245108.1.3 Nov 28, 2023 QEMU-QMP-REF(7)