1QEMU-QMP-REF(7) QEMU QEMU-QMP-REF(7)
2
6 qemu-qmp-ref - QEMU QMP Reference Manual
7 Contents
9 • QEMU QMP Reference Manual
10 • Introduction
12 • This document describes all commands currently supported by QMP.
14 • Stability Considerations
16 • The current QMP command set (described in this file) may be use‐
18 ful for a number of use cases, however it's limited and several
19 commands have bad defined semantics, specially with regard to
20 command completion.
21 • QMP errors
23 • QapiErrorClass (Enum)
25 • Common data types
27 • IoOperationType (Enum)
29 • OnOffAuto (Enum)
31 • OnOffSplit (Enum)
33 • String (Object)
35 • StrOrNull (Alternate)
37 • OffAutoPCIBAR (Enum)
39 • PCIELinkSpeed (Enum)
41 • PCIELinkWidth (Enum)
43 • HostMemPolicy (Enum)
45 • NetFilterDirection (Enum)
47 • GrabToggleKeys (Enum)
49 • HumanReadableText (Object)
51 • Socket data types
53 • NetworkAddressFamily (Enum)
55 • InetSocketAddressBase (Object)
57 • InetSocketAddress (Object)
59 • UnixSocketAddress (Object)
61 • VsockSocketAddress (Object)
63 • InetSocketAddressWrapper (Object)
65 • UnixSocketAddressWrapper (Object)
67 • VsockSocketAddressWrapper (Object)
69 • StringWrapper (Object)
71 • SocketAddressLegacy (Object)
73 • SocketAddressType (Enum)
75 • SocketAddress (Object)
77 • VM run state
79 • RunState (Enum)
81 • ShutdownCause (Enum)
83 • StatusInfo (Object)
85 • query-status (Command)
87 • SHUTDOWN (Event)
89 • POWERDOWN (Event)
91 • RESET (Event)
93 • STOP (Event)
95 • RESUME (Event)
97 • SUSPEND (Event)
99 • SUSPEND_DISK (Event)
101 • WAKEUP (Event)
103 • WATCHDOG (Event)
105 • WatchdogAction (Enum)
107 • RebootAction (Enum)
109 • ShutdownAction (Enum)
111 • PanicAction (Enum)
113 • watchdog-set-action (Command)
115 • set-action (Command)
117 • GUEST_PANICKED (Event)
119 • GUEST_CRASHLOADED (Event)
121 • GuestPanicAction (Enum)
123 • GuestPanicInformationType (Enum)
125 • GuestPanicInformation (Object)
127 • GuestPanicInformationHyperV (Object)
129 • S390CrashReason (Enum)
131 • GuestPanicInformationS390 (Object)
133 • MEMORY_FAILURE (Event)
135 • MemoryFailureRecipient (Enum)
137 • MemoryFailureAction (Enum)
139 • MemoryFailureFlags (Object)
141 • Cryptography
143 • QCryptoTLSCredsEndpoint (Enum)
145 • QCryptoSecretFormat (Enum)
147 • QCryptoHashAlgorithm (Enum)
149 • QCryptoCipherAlgorithm (Enum)
151 • QCryptoCipherMode (Enum)
153 • QCryptoIVGenAlgorithm (Enum)
155 • QCryptoBlockFormat (Enum)
157 • QCryptoBlockOptionsBase (Object)
159 • QCryptoBlockOptionsQCow (Object)
161 • QCryptoBlockOptionsLUKS (Object)
163 • QCryptoBlockCreateOptionsLUKS (Object)
165 • QCryptoBlockOpenOptions (Object)
167 • QCryptoBlockCreateOptions (Object)
169 • QCryptoBlockInfoBase (Object)
171 • QCryptoBlockInfoLUKSSlot (Object)
173 • QCryptoBlockInfoLUKS (Object)
175 • QCryptoBlockInfo (Object)
177 • QCryptoBlockLUKSKeyslotState (Enum)
179 • QCryptoBlockAmendOptionsLUKS (Object)
181 • QCryptoBlockAmendOptions (Object)
183 • SecretCommonProperties (Object)
185 • SecretProperties (Object)
187 • SecretKeyringProperties (Object)
189 • TlsCredsProperties (Object)
191 • TlsCredsAnonProperties (Object)
193 • TlsCredsPskProperties (Object)
195 • TlsCredsX509Properties (Object)
197 • Block devices
199 • Block core (VM unrelated)
201 • Background jobs
203 • Additional block stuff (VM related)
205 • Block device exports
207 • Character devices
209 • ChardevInfo (Object)
211 • query-chardev (Command)
213 • ChardevBackendInfo (Object)
215 • query-chardev-backends (Command)
217 • DataFormat (Enum)
219 • ringbuf-write (Command)
221 • ringbuf-read (Command)
223 • ChardevCommon (Object)
225 • ChardevFile (Object)
227 • ChardevHostdev (Object)
229 • ChardevSocket (Object)
231 • ChardevUdp (Object)
233 • ChardevMux (Object)
235 • ChardevStdio (Object)
237 • ChardevSpiceChannel (Object)
239 • ChardevSpicePort (Object)
241 • ChardevDBus (Object)
243 • ChardevVC (Object)
245 • ChardevRingbuf (Object)
247 • ChardevQemuVDAgent (Object)
249 • ChardevBackendKind (Enum)
251 • ChardevFileWrapper (Object)
253 • ChardevHostdevWrapper (Object)
255 • ChardevSocketWrapper (Object)
257 • ChardevUdpWrapper (Object)
259 • ChardevCommonWrapper (Object)
261 • ChardevMuxWrapper (Object)
263 • ChardevStdioWrapper (Object)
265 • ChardevSpiceChannelWrapper (Object)
267 • ChardevSpicePortWrapper (Object)
269 • ChardevQemuVDAgentWrapper (Object)
271 • ChardevDBusWrapper (Object)
273 • ChardevVCWrapper (Object)
275 • ChardevRingbufWrapper (Object)
277 • ChardevBackend (Object)
279 • ChardevReturn (Object)
281 • chardev-add (Command)
283 • chardev-change (Command)
285 • chardev-remove (Command)
287 • chardev-send-break (Command)
289 • VSERPORT_CHANGE (Event)
291 • Dump guest memory
293 • DumpGuestMemoryFormat (Enum)
295 • dump-guest-memory (Command)
297 • DumpStatus (Enum)
299 • DumpQueryResult (Object)
301 • query-dump (Command)
303 • DUMP_COMPLETED (Event)
305 • DumpGuestMemoryCapability (Object)
307 • query-dump-guest-memory-capability (Command)
309 • Net devices
311 • set_link (Command)
313 • netdev_add (Command)
315 • netdev_del (Command)
317 • NetLegacyNicOptions (Object)
319 • NetdevUserOptions (Object)
321 • NetdevTapOptions (Object)
323 • NetdevSocketOptions (Object)
325 • NetdevL2TPv3Options (Object)
327 • NetdevVdeOptions (Object)
329 • NetdevBridgeOptions (Object)
331 • NetdevHubPortOptions (Object)
333 • NetdevNetmapOptions (Object)
335 • NetdevVhostUserOptions (Object)
337 • NetdevVhostVDPAOptions (Object)
339 • NetClientDriver (Enum)
341 • Netdev (Object)
343 • RxState (Enum)
345 • RxFilterInfo (Object)
347 • query-rx-filter (Command)
349 • NIC_RX_FILTER_CHANGED (Event)
351 • AnnounceParameters (Object)
353 • announce-self (Command)
355 • FAILOVER_NEGOTIATED (Event)
357 • RDMA device
359 • RDMA_GID_STATUS_CHANGED (Event)
361 • Rocker switch device
363 • RockerSwitch (Object)
365 • query-rocker (Command)
367 • RockerPortDuplex (Enum)
369 • RockerPortAutoneg (Enum)
371 • RockerPort (Object)
373 • query-rocker-ports (Command)
375 • RockerOfDpaFlowKey (Object)
377 • RockerOfDpaFlowMask (Object)
379 • RockerOfDpaFlowAction (Object)
381 • RockerOfDpaFlow (Object)
383 • query-rocker-of-dpa-flows (Command)
385 • RockerOfDpaGroup (Object)
387 • query-rocker-of-dpa-groups (Command)
389 • TPM (trusted platform module) devices
391 • TpmModel (Enum)
393 • query-tpm-models (Command)
395 • TpmType (Enum)
397 • query-tpm-types (Command)
399 • TPMPassthroughOptions (Object)
401 • TPMEmulatorOptions (Object)
403 • TPMPassthroughOptionsWrapper (Object)
405 • TPMEmulatorOptionsWrapper (Object)
407 • TpmTypeOptions (Object)
409 • TPMInfo (Object)
411 • query-tpm (Command)
413 • Remote desktop
415 • DisplayProtocol (Enum)
417 • SetPasswordAction (Enum)
419 • SetPasswordOptions (Object)
421 • SetPasswordOptionsVnc (Object)
423 • set_password (Command)
425 • ExpirePasswordOptions (Object)
427 • ExpirePasswordOptionsVnc (Object)
429 • expire_password (Command)
431 • screendump (Command)
433 • Spice
435 • VNC
437 • Input
439 • MouseInfo (Object)
441 • query-mice (Command)
443 • QKeyCode (Enum)
445 • KeyValueKind (Enum)
447 • IntWrapper (Object)
449 • QKeyCodeWrapper (Object)
451 • KeyValue (Object)
453 • send-key (Command)
455 • InputButton (Enum)
457 • InputAxis (Enum)
459 • InputKeyEvent (Object)
461 • InputBtnEvent (Object)
463 • InputMoveEvent (Object)
465 • InputEventKind (Enum)
467 • InputKeyEventWrapper (Object)
469 • InputBtnEventWrapper (Object)
471 • InputMoveEventWrapper (Object)
473 • InputEvent (Object)
475 • input-send-event (Command)
477 • DisplayGTK (Object)
479 • DisplayEGLHeadless (Object)
481 • DisplayDBus (Object)
483 • DisplayGLMode (Enum)
485 • DisplayCurses (Object)
487 • DisplayCocoa (Object)
489 • DisplayType (Enum)
491 • DisplayOptions (Object)
493 • query-display-options (Command)
495 • DisplayReloadType (Enum)
497 • DisplayReloadOptionsVNC (Object)
499 • DisplayReloadOptions (Object)
501 • display-reload (Command)
503 • User authorization
505 • QAuthZListPolicy (Enum)
507 • QAuthZListFormat (Enum)
509 • QAuthZListRule (Object)
511 • AuthZListProperties (Object)
513 • AuthZListFileProperties (Object)
515 • AuthZPAMProperties (Object)
517 • AuthZSimpleProperties (Object)
519 • Migration
521 • MigrationStats (Object)
523 • XBZRLECacheStats (Object)
525 • CompressionStats (Object)
527 • MigrationStatus (Enum)
529 • VfioStats (Object)
531 • MigrationInfo (Object)
533 • query-migrate (Command)
535 • MigrationCapability (Enum)
537 • MigrationCapabilityStatus (Object)
539 • migrate-set-capabilities (Command)
541 • query-migrate-capabilities (Command)
543 • MultiFDCompression (Enum)
545 • BitmapMigrationBitmapAliasTransform (Object)
547 • BitmapMigrationBitmapAlias (Object)
549 • BitmapMigrationNodeAlias (Object)
551 • MigrationParameter (Enum)
553 • MigrateSetParameters (Object)
555 • migrate-set-parameters (Command)
557 • MigrationParameters (Object)
559 • query-migrate-parameters (Command)
561 • client_migrate_info (Command)
563 • migrate-start-postcopy (Command)
565 • MIGRATION (Event)
567 • MIGRATION_PASS (Event)
569 • COLOMessage (Enum)
571 • COLOMode (Enum)
573 • FailoverStatus (Enum)
575 • COLO_EXIT (Event)
577 • COLOExitReason (Enum)
579 • x-colo-lost-heartbeat (Command)
581 • migrate_cancel (Command)
583 • migrate-continue (Command)
585 • migrate (Command)
587 • migrate-incoming (Command)
589 • xen-save-devices-state (Command)
591 • xen-set-global-dirty-log (Command)
593 • xen-load-devices-state (Command)
595 • xen-set-replication (Command)
597 • ReplicationStatus (Object)
599 • query-xen-replication-status (Command)
601 • xen-colo-do-checkpoint (Command)
603 • COLOStatus (Object)
605 • query-colo-status (Command)
607 • migrate-recover (Command)
609 • migrate-pause (Command)
611 • UNPLUG_PRIMARY (Event)
613 • DirtyRateVcpu (Object)
615 • DirtyRateStatus (Enum)
617 • DirtyRateMeasureMode (Enum)
619 • DirtyRateInfo (Object)
621 • calc-dirty-rate (Command)
623 • query-dirty-rate (Command)
625 • snapshot-save (Command)
627 • snapshot-load (Command)
629 • snapshot-delete (Command)
631 • Transactions
633 • Abort (Object)
635 • ActionCompletionMode (Enum)
637 • TransactionActionKind (Enum)
639 • AbortWrapper (Object)
641 • BlockDirtyBitmapAddWrapper (Object)
643 • BlockDirtyBitmapWrapper (Object)
645 • BlockDirtyBitmapMergeWrapper (Object)
647 • BlockdevBackupWrapper (Object)
649 • BlockdevSnapshotWrapper (Object)
651 • BlockdevSnapshotInternalWrapper (Object)
653 • BlockdevSnapshotSyncWrapper (Object)
655 • DriveBackupWrapper (Object)
657 • TransactionAction (Object)
659 • TransactionProperties (Object)
661 • transaction (Command)
663 • Tracing
665 • TraceEventState (Enum)
667 • TraceEventInfo (Object)
669 • trace-event-get-state (Command)
671 • trace-event-set-state (Command)
673 • Compatibility policy
675 • CompatPolicyInput (Enum)
677 • CompatPolicyOutput (Enum)
679 • CompatPolicy (Object)
681 • QMP monitor control
683 • qmp_capabilities (Command)
685 • QMPCapability (Enum)
687 • VersionTriple (Object)
689 • VersionInfo (Object)
691 • query-version (Command)
693 • CommandInfo (Object)
695 • query-commands (Command)
697 • quit (Command)
699 • MonitorMode (Enum)
701 • MonitorOptions (Object)
703 • QMP introspection
705 • query-qmp-schema (Command)
707 • SchemaMetaType (Enum)
709 • SchemaInfo (Object)
711 • SchemaInfoBuiltin (Object)
713 • JSONType (Enum)
715 • SchemaInfoEnum (Object)
717 • SchemaInfoEnumMember (Object)
719 • SchemaInfoArray (Object)
721 • SchemaInfoObject (Object)
723 • SchemaInfoObjectMember (Object)
725 • SchemaInfoObjectVariant (Object)
727 • SchemaInfoAlternate (Object)
729 • SchemaInfoAlternateMember (Object)
731 • SchemaInfoCommand (Object)
733 • SchemaInfoEvent (Object)
735 • QEMU Object Model (QOM)
737 • ObjectPropertyInfo (Object)
739 • qom-list (Command)
741 • qom-get (Command)
743 • qom-set (Command)
745 • ObjectTypeInfo (Object)
747 • qom-list-types (Command)
749 • qom-list-properties (Command)
751 • CanHostSocketcanProperties (Object)
753 • ColoCompareProperties (Object)
755 • CryptodevBackendProperties (Object)
757 • CryptodevVhostUserProperties (Object)
759 • DBusVMStateProperties (Object)
761 • NetfilterInsert (Enum)
763 • NetfilterProperties (Object)
765 • FilterBufferProperties (Object)
767 • FilterDumpProperties (Object)
769 • FilterMirrorProperties (Object)
771 • FilterRedirectorProperties (Object)
773 • FilterRewriterProperties (Object)
775 • InputBarrierProperties (Object)
777 • InputLinuxProperties (Object)
779 • IothreadProperties (Object)
781 • MemoryBackendProperties (Object)
783 • MemoryBackendFileProperties (Object)
785 • MemoryBackendMemfdProperties (Object)
787 • MemoryBackendEpcProperties (Object)
789 • PrManagerHelperProperties (Object)
791 • QtestProperties (Object)
793 • RemoteObjectProperties (Object)
795 • RngProperties (Object)
797 • RngEgdProperties (Object)
799 • RngRandomProperties (Object)
801 • SevGuestProperties (Object)
803 • ObjectType (Enum)
805 • ObjectOptions (Object)
807 • object-add (Command)
809 • object-del (Command)
811 • Device infrastructure (qdev)
813 • device-list-properties (Command)
815 • device_add (Command)
817 • device_del (Command)
819 • DEVICE_DELETED (Event)
821 • DEVICE_UNPLUG_GUEST_ERROR (Event)
823 • Machines
825 • SysEmuTarget (Enum)
827 • CpuS390State (Enum)
829 • CpuInfoS390 (Object)
831 • CpuInfoFast (Object)
833 • query-cpus-fast (Command)
835 • MachineInfo (Object)
837 • query-machines (Command)
839 • CurrentMachineParams (Object)
841 • query-current-machine (Command)
843 • TargetInfo (Object)
845 • query-target (Command)
847 • UuidInfo (Object)
849 • query-uuid (Command)
851 • GuidInfo (Object)
853 • query-vm-generation-id (Command)
855 • system_reset (Command)
857 • system_powerdown (Command)
859 • system_wakeup (Command)
861 • LostTickPolicy (Enum)
863 • inject-nmi (Command)
865 • KvmInfo (Object)
867 • query-kvm (Command)
869 • NumaOptionsType (Enum)
871 • NumaOptions (Object)
873 • NumaNodeOptions (Object)
875 • NumaDistOptions (Object)
877 • X86CPURegister32 (Enum)
879 • X86CPUFeatureWordInfo (Object)
881 • DummyForceArrays (Object)
883 • NumaCpuOptions (Object)
885 • HmatLBMemoryHierarchy (Enum)
887 • HmatLBDataType (Enum)
889 • NumaHmatLBOptions (Object)
891 • HmatCacheAssociativity (Enum)
893 • HmatCacheWritePolicy (Enum)
895 • NumaHmatCacheOptions (Object)
897 • memsave (Command)
899 • pmemsave (Command)
901 • Memdev (Object)
903 • query-memdev (Command)
905 • CpuInstanceProperties (Object)
907 • HotpluggableCPU (Object)
909 • query-hotpluggable-cpus (Command)
911 • set-numa-node (Command)
913 • balloon (Command)
915 • BalloonInfo (Object)
917 • query-balloon (Command)
919 • BALLOON_CHANGE (Event)
921 • MemoryInfo (Object)
923 • query-memory-size-summary (Command)
925 • PCDIMMDeviceInfo (Object)
927 • VirtioPMEMDeviceInfo (Object)
929 • VirtioMEMDeviceInfo (Object)
931 • SgxEPCDeviceInfo (Object)
933 • MemoryDeviceInfoKind (Enum)
935 • PCDIMMDeviceInfoWrapper (Object)
937 • VirtioPMEMDeviceInfoWrapper (Object)
939 • VirtioMEMDeviceInfoWrapper (Object)
941 • SgxEPCDeviceInfoWrapper (Object)
943 • MemoryDeviceInfo (Object)
945 • SgxEPC (Object)
947 • SgxEPCProperties (Object)
949 • query-memory-devices (Command)
951 • MEMORY_DEVICE_SIZE_CHANGE (Event)
953 • MEM_UNPLUG_ERROR (Event)
955 • SMPConfiguration (Object)
957 • x-query-irq (Command)
959 • x-query-jit (Command)
961 • x-query-numa (Command)
963 • x-query-opcount (Command)
965 • x-query-profile (Command)
967 • x-query-ramblock (Command)
969 • x-query-rdma (Command)
971 • x-query-roms (Command)
973 • x-query-usb (Command)
975 • SmbiosEntryPointType (Enum)
977 • CpuModelInfo (Object)
979 • CpuModelExpansionType (Enum)
981 • CpuModelCompareResult (Enum)
983 • CpuModelBaselineInfo (Object)
985 • CpuModelCompareInfo (Object)
987 • query-cpu-model-comparison (Command)
989 • query-cpu-model-baseline (Command)
991 • CpuModelExpansionInfo (Object)
993 • query-cpu-model-expansion (Command)
995 • CpuDefinitionInfo (Object)
997 • query-cpu-definitions (Command)
999 • Record/replay
1001 • ReplayMode (Enum)
1003 • ReplayInfo (Object)
1005 • query-replay (Command)
1007 • replay-break (Command)
1009 • replay-delete-break (Command)
1011 • replay-seek (Command)
1013 • Yank feature
1015 • YankInstanceType (Enum)
1017 • YankInstanceBlockNode (Object)
1019 • YankInstanceChardev (Object)
1021 • YankInstance (Object)
1023 • yank (Command)
1025 • query-yank (Command)
1027 • Miscellanea
1029 • add_client (Command)
1031 • NameInfo (Object)
1033 • query-name (Command)
1035 • IOThreadInfo (Object)
1037 • query-iothreads (Command)
1039 • stop (Command)
1041 • cont (Command)
1043 • x-exit-preconfig (Command)
1045 • human-monitor-command (Command)
1047 • getfd (Command)
1049 • closefd (Command)
1051 • AddfdInfo (Object)
1053 • add-fd (Command)
1055 • remove-fd (Command)
1057 • FdsetFdInfo (Object)
1059 • FdsetInfo (Object)
1061 • query-fdsets (Command)
1063 • CommandLineParameterType (Enum)
1065 • CommandLineParameterInfo (Object)
1067 • CommandLineOptionInfo (Object)
1069 • query-command-line-options (Command)
1071 • RTC_CHANGE (Event)
1073 • rtc-reset-reinjection (Command)
1075 • SevState (Enum)
1077 • SevInfo (Object)
1079 • query-sev (Command)
1081 • SevLaunchMeasureInfo (Object)
1083 • query-sev-launch-measure (Command)
1085 • SevCapability (Object)
1087 • query-sev-capabilities (Command)
1089 • sev-inject-launch-secret (Command)
1091 • SevAttestationReport (Object)
1093 • query-sev-attestation-report (Command)
1095 • dump-skeys (Command)
1097 • GICCapability (Object)
1099 • query-gic-capabilities (Command)
1101 • SGXEPCSection (Object)
1103 • SGXInfo (Object)
1105 • query-sgx (Command)
1107 • query-sgx-capabilities (Command)
1109 • Audio
1111 • AudiodevPerDirectionOptions (Object)
1113 • AudiodevGenericOptions (Object)
1115 • AudiodevAlsaPerDirectionOptions (Object)
1117 • AudiodevAlsaOptions (Object)
1119 • AudiodevCoreaudioPerDirectionOptions (Object)
1121 • AudiodevCoreaudioOptions (Object)
1123 • AudiodevDsoundOptions (Object)
1125 • AudiodevJackPerDirectionOptions (Object)
1127 • AudiodevJackOptions (Object)
1129 • AudiodevOssPerDirectionOptions (Object)
1131 • AudiodevOssOptions (Object)
1133 • AudiodevPaPerDirectionOptions (Object)
1135 • AudiodevPaOptions (Object)
1137 • AudiodevSdlPerDirectionOptions (Object)
1139 • AudiodevSdlOptions (Object)
1141 • AudiodevWavOptions (Object)
1143 • AudioFormat (Enum)
1145 • AudiodevDriver (Enum)
1147 • Audiodev (Object)
1149 • ACPI
1151 • AcpiTableOptions (Object)
1153 • ACPISlotType (Enum)
1155 • ACPIOSTInfo (Object)
1157 • query-acpi-ospm-status (Command)
1159 • ACPI_DEVICE_OST (Event)
1161 • PCI
1163 • PciMemoryRange (Object)
1165 • PciMemoryRegion (Object)
1167 • PciBusInfo (Object)
1169 • PciBridgeInfo (Object)
1171 • PciDeviceClass (Object)
1173 • PciDeviceId (Object)
1175 • PciDeviceInfo (Object)
1177 • PciInfo (Object)
1179 • query-pci (Command)
1181
1183 This document describes all commands currently supported by QMP.
1184 Most of the time their usage is exactly the same as in the user Moni‐
1186 tor, this means that any other document which also describe commands
1187 (the manpage, QEMU's manual, etc) can and should be consulted.
1188 QMP has two types of commands: regular and query commands. Regular com‐
1190 mands usually change the Virtual Machine's state someway, while query
1191 commands just return information. The sections below are divided ac‐
1192 cordingly.
1193 It's important to observe that all communication examples are formatted
1195 in a reader-friendly way, so that they're easier to understand. How‐
1196 ever, in real protocol usage, they're emitted as a single line.
1197 Also, the following notation is used to denote data flow:
1199 Example:
1201 -> data issued by the Client
1203 <- Server data response
1204 Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
1206 detailed information on the Server command and response formats.
1207
1209 The current QMP command set (described in this file) may be useful for
1210 a number of use cases, however it's limited and several commands have
1211 bad defined semantics, specially with regard to command completion.
1212 These problems are going to be solved incrementally in the next QEMU
1214 releases and we're going to establish a deprecation policy for badly
1215 defined commands.
1216 If you're planning to adopt QMP, please observe the following:
1218 1. The deprecation policy will take effect and be documented soon,
1220 please check the documentation of each used command as soon as a
1221 new release of QEMU is available
1222 2. DO NOT rely on anything which is not explicit documented
1224 3. Errors, in special, are not documented. Applications should NOT
1226 check for specific errors classes or data (it's strongly recom‐
1227 mended to only check for the "error" key)
1228
1230 QapiErrorClass (Enum)
1231 QEMU error classes
1232 Values
1234 GenericError
1235 this is used for errors that don't require a specific error
1236 class. This should be the default case for most errors
1237 CommandNotFound
1239 the requested command has not been found
1240 DeviceNotActive
1242 a device has failed to be become active
1243 DeviceNotFound
1245 the requested device has not been found
1246 KVMMissingCap
1248 the requested operation can't be fulfilled because a required
1249 KVM capability is missing
1250 Since
1252 1.2
1253
1255 IoOperationType (Enum)
1256 An enumeration of the I/O operation types
1257 Values
1259 read read operation
1260 write write operation
1262 Since
1264 2.1
1265 OnOffAuto (Enum)
1267 An enumeration of three options: on, off, and auto
1268 Values
1270 auto QEMU selects the value between on and off
1271 on Enabled
1273 off Disabled
1275 Since
1277 2.2
1278 OnOffSplit (Enum)
1280 An enumeration of three values: on, off, and split
1281 Values
1283 on Enabled
1284 off Disabled
1286 split Mixed
1288 Since
1290 2.6
1291 String (Object)
1293 A fat type wrapping 'str', to be embedded in lists.
1294 Members
1296 str: string
1297 Not documented
1298 Since
1300 1.2
1301 StrOrNull (Alternate)
1303 This is a string value or the explicit lack of a string (null pointer
1304 in C). Intended for cases when 'optional absent' already has a differ‐
1305 ent meaning.
1306 Members
1308 s: string
1309 the string value
1310 n: null
1312 no string value
1313 Since
1315 2.10
1316 OffAutoPCIBAR (Enum)
1318 An enumeration of options for specifying a PCI BAR
1319 Values
1321 off The specified feature is disabled
1322 auto The PCI BAR for the feature is automatically selected
1324 bar0 PCI BAR0 is used for the feature
1326 bar1 PCI BAR1 is used for the feature
1328 bar2 PCI BAR2 is used for the feature
1330 bar3 PCI BAR3 is used for the feature
1332 bar4 PCI BAR4 is used for the feature
1334 bar5 PCI BAR5 is used for the feature
1336 Since
1338 2.12
1339 PCIELinkSpeed (Enum)
1341 An enumeration of PCIe link speeds in units of GT/s
1342 Values
1344 2_5 2.5GT/s
1345 5 5.0GT/s
1347 8 8.0GT/s
1349 16 16.0GT/s
1351 Since
1353 4.0
1354 PCIELinkWidth (Enum)
1356 An enumeration of PCIe link width
1357 Values
1359 1 x1
1360 2 x2
1362 4 x4
1364 8 x8
1366 12 x12
1368 16 x16
1370 32 x32
1372 Since
1374 4.0
1375 HostMemPolicy (Enum)
1377 Host memory policy types
1378 Values
1380 default
1381 restore default policy, remove any nondefault policy
1382 preferred
1384 set the preferred host nodes for allocation
1385 bind a strict policy that restricts memory allocation to the host
1387 nodes specified
1388 interleave
1390 memory allocations are interleaved across the set of host nodes
1391 specified
1392 Since
1394 2.1
1395 NetFilterDirection (Enum)
1397 Indicates whether a netfilter is attached to a netdev's transmit queue
1398 or receive queue or both.
1399 Values
1401 all the filter is attached both to the receive and the transmit
1402 queue of the netdev (default).
1403 rx the filter is attached to the receive queue of the netdev, where
1405 it will receive packets sent to the netdev.
1406 tx the filter is attached to the transmit queue of the netdev,
1408 where it will receive packets sent by the netdev.
1409 Since
1411 2.5
1412 GrabToggleKeys (Enum)
1414 Keys to toggle input-linux between host and guest.
1415 Values
1417 ctrl-ctrl
1418 Not documented
1419 alt-alt
1421 Not documented
1422 shift-shift
1424 Not documented
1425 meta-meta
1427 Not documented
1428 scrolllock
1430 Not documented
1431 ctrl-scrolllock
1433 Not documented
1434 Since
1436 4.0
1437 HumanReadableText (Object)
1439 Members
1440 human-readable-text: string
1441 Formatted output intended for humans.
1442 Since
1444 6.2
1445
1447 NetworkAddressFamily (Enum)
1448 The network address family
1449 Values
1451 ipv4 IPV4 family
1452 ipv6 IPV6 family
1454 unix unix socket
1456 vsock vsock family (since 2.8)
1458 unknown
1460 otherwise
1461 Since
1463 2.1
1464 InetSocketAddressBase (Object)
1466 Members
1467 host: string
1468 host part of the address
1469 port: string
1471 port part of the address
1472 InetSocketAddress (Object)
1474 Captures a socket address or address range in the Internet namespace.
1475 Members
1477 numeric: boolean (optional)
1478 true if the host/port are guaranteed to be numeric, false if
1479 name resolution should be attempted. Defaults to false. (Since
1480 2.9)
1481 to: int (optional)
1483 If present, this is range of possible addresses, with port be‐
1484 tween port and to.
1485 ipv4: boolean (optional)
1487 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1488 ipv6: boolean (optional)
1490 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1491 keep-alive: boolean (optional)
1493 enable keep-alive when connecting to this socket. Not supported
1494 for passive sockets. (Since 4.2)
1495 mptcp: boolean (optional) (If: HAVE_IPPROTO_MPTCP)
1497 enable multi-path TCP. (Since 6.1)
1498 The members of InetSocketAddressBase
1500 Since
1502 1.3
1503 UnixSocketAddress (Object)
1505 Captures a socket address in the local ("Unix socket") namespace.
1506 Members
1508 path: string
1509 filesystem path to use
1510 abstract: boolean (optional) (If: CONFIG_LINUX)
1512 if true, this is a Linux abstract socket address. path will be
1513 prefixed by a null byte, and optionally padded with null bytes.
1514 Defaults to false. (Since 5.1)
1515 tight: boolean (optional) (If: CONFIG_LINUX)
1517 if false, pad an abstract socket address with enough null bytes
1518 to make it fill struct sockaddr_un member sun_path. Defaults to
1519 true. (Since 5.1)
1520 Since
1522 1.3
1523 VsockSocketAddress (Object)
1525 Captures a socket address in the vsock namespace.
1526 Members
1528 cid: string
1529 unique host identifier
1530 port: string
1532 port
1533 Note
1535 string types are used to allow for possible future hostname or service
1536 resolution support.
1537 Since
1539 2.8
1540 InetSocketAddressWrapper (Object)
1542 Members
1543 data: InetSocketAddress
1544 Not documented
1545 Since
1547 1.3
1548 UnixSocketAddressWrapper (Object)
1550 Members
1551 data: UnixSocketAddress
1552 Not documented
1553 Since
1555 1.3
1556 VsockSocketAddressWrapper (Object)
1558 Members
1559 data: VsockSocketAddress
1560 Not documented
1561 Since
1563 2.8
1564 StringWrapper (Object)
1566 Members
1567 data: String
1568 Not documented
1569 Since
1571 1.3
1572 SocketAddressLegacy (Object)
1574 Captures the address of a socket, which could also be a named file de‐
1575 scriptor
1576 Members
1578 type: SocketAddressType
1579 Not documented
1580 The members of InetSocketAddressWrapper when type is "inet"
1582 The members of UnixSocketAddressWrapper when type is "unix"
1584 The members of VsockSocketAddressWrapper when type is "vsock"
1586 The members of StringWrapper when type is "fd"
1588 Note
1590 This type is deprecated in favor of SocketAddress. The difference be‐
1591 tween SocketAddressLegacy and SocketAddress is that the latter is has
1592 fewer {} on the wire.
1593 Since
1595 1.3
1596 SocketAddressType (Enum)
1598 Available SocketAddress types
1599 Values
1601 inet Internet address
1602 unix Unix domain socket
1604 vsock VMCI address
1606 fd decimal is for file descriptor number, otherwise a file descrip‐
1608 tor name. Named file descriptors are permitted in monitor com‐
1609 mands, in combination with the 'getfd' command. Decimal file de‐
1610 scriptors are permitted at startup or other contexts where no
1611 monitor context is active.
1612 Since
1614 2.9
1615 SocketAddress (Object)
1617 Captures the address of a socket, which could also be a named file de‐
1618 scriptor
1619 Members
1621 type: SocketAddressType
1622 Transport type
1623 The members of InetSocketAddress when type is "inet"
1625 The members of UnixSocketAddress when type is "unix"
1627 The members of VsockSocketAddress when type is "vsock"
1629 The members of String when type is "fd"
1631 Since
1633 2.9
1634
1636 RunState (Enum)
1637 An enumeration of VM run states.
1638 Values
1640 debug QEMU is running on a debugger
1641 finish-migrate
1643 guest is paused to finish the migration process
1644 inmigrate
1646 guest is paused waiting for an incoming migration. Note that
1647 this state does not tell whether the machine will start at the
1648 end of the migration. This depends on the command-line -S op‐
1649 tion and any invocation of 'stop' or 'cont' that has happened
1650 since QEMU was started.
1651 internal-error
1653 An internal error that prevents further guest execution has oc‐
1654 curred
1655 io-error
1657 the last IOP has failed and the device is configured to pause on
1658 I/O errors
1659 paused guest has been paused via the 'stop' command
1661 postmigrate
1663 guest is paused following a successful 'migrate'
1664 prelaunch
1666 QEMU was started with -S and guest has not started
1667 restore-vm
1669 guest is paused to restore VM state
1670 running
1672 guest is actively running
1673 save-vm
1675 guest is paused to save the VM state
1676 shutdown
1678 guest is shut down (and -no-shutdown is in use)
1679 suspended
1681 guest is suspended (ACPI S3)
1682 watchdog
1684 the watchdog action is configured to pause and has been trig‐
1685 gered
1686 guest-panicked
1688 guest has been panicked as a result of guest OS panic
1689 colo guest is paused to save/restore VM state under colo checkpoint,
1691 VM can not get into this state unless colo capability is enabled
1692 for migration. (since 2.8)
1693 ShutdownCause (Enum)
1695 An enumeration of reasons for a Shutdown.
1696 Values
1698 none No shutdown request pending
1699 host-error
1701 An error prevents further use of guest
1702 host-qmp-quit
1704 Reaction to the QMP command 'quit'
1705 host-qmp-system-reset
1707 Reaction to the QMP command 'system_reset'
1708 host-signal
1710 Reaction to a signal, such as SIGINT
1711 host-ui
1713 Reaction to a UI event, like window close
1714 guest-shutdown
1716 Guest shutdown/suspend request, via ACPI or other hardware-spe‐
1717 cific means
1718 guest-reset
1720 Guest reset request, and command line turns that into a shutdown
1721 guest-panic
1723 Guest panicked, and command line turns that into a shutdown
1724 subsystem-reset
1726 Partial guest reset that does not trigger QMP events and ignores
1727 --no-reboot. This is useful for sanitizing hypercalls on s390
1728 that are used during kexec/kdump/boot
1729 StatusInfo (Object)
1731 Information about VCPU run state
1732 Members
1734 running: boolean
1735 true if all VCPUs are runnable, false if not runnable
1736 singlestep: boolean
1738 true if VCPUs are in single-step mode
1739 status: RunState
1741 the virtual machine RunState
1742 Since
1744 0.14
1745 Notes
1747 singlestep is enabled through the GDB stub
1748 query-status (Command)
1750 Query the run status of all VCPUs
1751 Returns
1753 StatusInfo reflecting all VCPUs
1754 Since
1756 0.14
1757 Example
1759 -> { "execute": "query-status" }
1760 <- { "return": { "running": true,
1761 "singlestep": false,
1762 "status": "running" } }
1763 SHUTDOWN (Event)
1765 Emitted when the virtual machine has shut down, indicating that qemu is
1766 about to exit.
1767 Arguments
1769 guest: boolean
1770 If true, the shutdown was triggered by a guest request (such as
1771 a guest-initiated ACPI shutdown request or other hardware-spe‐
1772 cific action) rather than a host request (such as sending qemu a
1773 SIGINT). (since 2.10)
1774 reason: ShutdownCause
1776 The ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
1777 Note
1779 If the command-line option "-no-shutdown" has been specified, qemu will
1780 not exit, and a STOP event will eventually follow the SHUTDOWN event
1781 Since
1783 0.12
1784 Example
1786 <- { "event": "SHUTDOWN",
1787 "data": { "guest": true, "reason": "guest-shutdown" },
1788 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1789 POWERDOWN (Event)
1791 Emitted when the virtual machine is powered down through the power con‐
1792 trol system, such as via ACPI.
1793 Since
1795 0.12
1796 Example
1798 <- { "event": "POWERDOWN",
1799 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
1800 RESET (Event)
1802 Emitted when the virtual machine is reset
1803 Arguments
1805 guest: boolean
1806 If true, the reset was triggered by a guest request (such as a
1807 guest-initiated ACPI reboot request or other hardware-specific
1808 action) rather than a host request (such as the QMP command sys‐
1809 tem_reset). (since 2.10)
1810 reason: ShutdownCause
1812 The ShutdownCause of the RESET. (since 4.0)
1813 Since
1815 0.12
1816 Example
1818 <- { "event": "RESET",
1819 "data": { "guest": false, "reason": "guest-reset" },
1820 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
1821 STOP (Event)
1823 Emitted when the virtual machine is stopped
1824 Since
1826 0.12
1827 Example
1829 <- { "event": "STOP",
1830 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
1831 RESUME (Event)
1833 Emitted when the virtual machine resumes execution
1834 Since
1836 0.12
1837 Example
1839 <- { "event": "RESUME",
1840 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
1841 SUSPEND (Event)
1843 Emitted when guest enters a hardware suspension state, for example, S3
1844 state, which is sometimes called standby state
1845 Since
1847 1.1
1848 Example
1850 <- { "event": "SUSPEND",
1851 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
1852 SUSPEND_DISK (Event)
1854 Emitted when guest enters a hardware suspension state with data saved
1855 on disk, for example, S4 state, which is sometimes called hibernate
1856 state
1857 Note
1859 QEMU shuts down (similar to event SHUTDOWN) when entering this state
1860 Since
1862 1.2
1863 Example
1865 <- { "event": "SUSPEND_DISK",
1866 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
1867 WAKEUP (Event)
1869 Emitted when the guest has woken up from suspend state and is running
1870 Since
1872 1.1
1873 Example
1875 <- { "event": "WAKEUP",
1876 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
1877 WATCHDOG (Event)
1879 Emitted when the watchdog device's timer is expired
1880 Arguments
1882 action: WatchdogAction
1883 action that has been taken
1884 Note
1886 If action is "reset", "shutdown", or "pause" the WATCHDOG event is fol‐
1887 lowed respectively by the RESET, SHUTDOWN, or STOP events
1888 Note
1890 This event is rate-limited.
1891 Since
1893 0.13
1894 Example
1896 <- { "event": "WATCHDOG",
1897 "data": { "action": "reset" },
1898 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
1899 WatchdogAction (Enum)
1901 An enumeration of the actions taken when the watchdog device's timer is
1902 expired
1903 Values
1905 reset system resets
1906 shutdown
1908 system shutdown, note that it is similar to powerdown, which
1909 tries to set to system status and notify guest
1910 poweroff
1912 system poweroff, the emulator program exits
1913 pause system pauses, similar to stop
1915 debug system enters debug state
1917 none nothing is done
1919 inject-nmi
1921 a non-maskable interrupt is injected into the first VCPU (all
1922 VCPUS on x86) (since 2.4)
1923 Since
1925 2.1
1926 RebootAction (Enum)
1928 Possible QEMU actions upon guest reboot
1929 Values
1931 reset Reset the VM
1932 shutdown
1934 Shutdown the VM and exit, according to the shutdown action
1935 Since
1937 6.0
1938 ShutdownAction (Enum)
1940 Possible QEMU actions upon guest shutdown
1941 Values
1943 poweroff
1944 Shutdown the VM and exit
1945 pause pause the VM#
1947 Since
1949 6.0
1950 PanicAction (Enum)
1952 Values
1953 none Continue VM execution
1954 pause Pause the VM
1956 shutdown
1958 Shutdown the VM and exit, according to the shutdown action
1959 Since
1961 6.0
1962 watchdog-set-action (Command)
1964 Set watchdog action
1965 Arguments
1967 action: WatchdogAction
1968 Not documented
1969 Since
1971 2.11
1972 set-action (Command)
1974 Set the actions that will be taken by the emulator in response to guest
1975 events.
1976 Arguments
1978 reboot: RebootAction (optional)
1979 RebootAction action taken on guest reboot.
1980 shutdown: ShutdownAction (optional)
1982 ShutdownAction action taken on guest shutdown.
1983 panic: PanicAction (optional)
1985 PanicAction action taken on guest panic.
1986 watchdog: WatchdogAction (optional)
1988 WatchdogAction action taken when watchdog timer expires .
1989 Returns
1991 Nothing on success.
1992 Since
1994 6.0
1995 Example
1997 -> { "execute": "set-action",
1998 "arguments": { "reboot": "shutdown",
1999 "shutdown" : "pause",
2000 "panic": "pause",
2001 "watchdog": "inject-nmi" } }
2002 <- { "return": {} }
2003 GUEST_PANICKED (Event)
2005 Emitted when guest OS panic is detected
2006 Arguments
2008 action: GuestPanicAction
2009 action that has been taken, currently always "pause"
2010 info: GuestPanicInformation (optional)
2012 information about a panic (since 2.9)
2013 Since
2015 1.5
2016 Example
2018 <- { "event": "GUEST_PANICKED",
2019 "data": { "action": "pause" },
2020 "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
2021 GUEST_CRASHLOADED (Event)
2023 Emitted when guest OS crash loaded is detected
2024 Arguments
2026 action: GuestPanicAction
2027 action that has been taken, currently always "run"
2028 info: GuestPanicInformation (optional)
2030 information about a panic
2031 Since
2033 5.0
2034 Example
2036 <- { "event": "GUEST_CRASHLOADED",
2037 "data": { "action": "run" },
2038 "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
2039 GuestPanicAction (Enum)
2041 An enumeration of the actions taken when guest OS panic is detected
2042 Values
2044 pause system pauses
2045 poweroff
2047 Not documented
2048 run Not documented
2050 Since
2052 2.1 (poweroff since 2.8, run since 5.0)
2053 GuestPanicInformationType (Enum)
2055 An enumeration of the guest panic information types
2056 Values
2058 hyper-v
2059 hyper-v guest panic information type
2060 s390 s390 guest panic information type (Since: 2.12)
2062 Since
2064 2.9
2065 GuestPanicInformation (Object)
2067 Information about a guest panic
2068 Members
2070 type: GuestPanicInformationType
2071 Crash type that defines the hypervisor specific information
2072 The members of GuestPanicInformationHyperV when type is "hyper-v"
2074 The members of GuestPanicInformationS390 when type is "s390"
2076 Since
2078 2.9
2079 GuestPanicInformationHyperV (Object)
2081 Hyper-V specific guest panic information (HV crash MSRs)
2082 Members
2084 arg1: int
2085 Not documented
2086 arg2: int
2088 Not documented
2089 arg3: int
2091 Not documented
2092 arg4: int
2094 Not documented
2095 arg5: int
2097 Not documented
2098 Since
2100 2.9
2101 S390CrashReason (Enum)
2103 Reason why the CPU is in a crashed state.
2104 Values
2106 unknown
2107 no crash reason was set
2108 disabled-wait
2110 the CPU has entered a disabled wait state
2111 extint-loop
2113 clock comparator or cpu timer interrupt with new PSW enabled for
2114 external interrupts
2115 pgmint-loop
2117 program interrupt with BAD new PSW
2118 opint-loop
2120 operation exception interrupt with invalid code at the program
2121 interrupt new PSW
2122 Since
2124 2.12
2125 GuestPanicInformationS390 (Object)
2127 S390 specific guest panic information (PSW)
2128 Members
2130 core: int
2131 core id of the CPU that crashed
2132 psw-mask: int
2134 control fields of guest PSW
2135 psw-addr: int
2137 guest instruction address
2138 reason: S390CrashReason
2140 guest crash reason
2141 Since
2143 2.12
2144 MEMORY_FAILURE (Event)
2146 Emitted when a memory failure occurs on host side.
2147 Arguments
2149 recipient: MemoryFailureRecipient
2150 recipient is defined as MemoryFailureRecipient.
2151 action: MemoryFailureAction
2153 action that has been taken. action is defined as MemoryFailure‐
2154 Action.
2155 flags: MemoryFailureFlags
2157 flags for MemoryFailureAction. action is defined as MemoryFail‐
2158 ureFlags.
2159 Since
2161 5.2
2162 Example
2164 <- { "event": "MEMORY_FAILURE",
2165 "data": { "recipient": "hypervisor",
2166 "action": "fatal",
2167 "flags": { "action-required": false,
2168 "recursive": false } },
2169 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
2170 MemoryFailureRecipient (Enum)
2172 Hardware memory failure occurs, handled by recipient.
2173 Values
2175 hypervisor
2176 memory failure at QEMU process address space. (none guest mem‐
2177 ory, but used by QEMU itself).
2178 guest memory failure at guest memory,
2180 Since
2182 5.2
2183 MemoryFailureAction (Enum)
2185 Actions taken by QEMU in response to a hardware memory failure.
2186 Values
2188 ignore the memory failure could be ignored. This will only be the case
2189 for action-optional failures.
2190 inject memory failure occurred in guest memory, the guest enabled MCE
2192 handling mechanism, and QEMU could inject the MCE into the guest
2193 successfully.
2194 fatal the failure is unrecoverable. This occurs for action-required
2196 failures if the recipient is the hypervisor; QEMU will exit.
2197 reset the failure is unrecoverable but confined to the guest. This
2199 occurs if the recipient is a guest guest which is not ready to
2200 handle memory failures.
2201 Since
2203 5.2
2204 MemoryFailureFlags (Object)
2206 Additional information on memory failures.
2207 Members
2209 action-required: boolean
2210 whether a memory failure event is action-required or action-op‐
2211 tional (e.g. a failure during memory scrub).
2212 recursive: boolean
2214 whether the failure occurred while the previous failure was
2215 still in progress.
2216 Since
2218 5.2
2219
2221 QCryptoTLSCredsEndpoint (Enum)
2222 The type of network endpoint that will be using the credentials. Most
2223 types of credential require different setup / structures depending on
2224 whether they will be used in a server versus a client.
2225 Values
2227 client the network endpoint is acting as the client
2228 server the network endpoint is acting as the server
2230 Since
2232 2.5
2233 QCryptoSecretFormat (Enum)
2235 The data format that the secret is provided in
2236 Values
2238 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
2239 be used
2240 base64 arbitrary base64 encoded binary data
2242 Since
2244 2.6
2245 QCryptoHashAlgorithm (Enum)
2247 The supported algorithms for computing content digests
2248 Values
2250 md5 MD5. Should not be used in any new code, legacy compat only
2251 sha1 SHA-1. Should not be used in any new code, legacy compat only
2253 sha224 SHA-224. (since 2.7)
2255 sha256 SHA-256. Current recommended strong hash.
2257 sha384 SHA-384. (since 2.7)
2259 sha512 SHA-512. (since 2.7)
2261 ripemd160
2263 RIPEMD-160. (since 2.7)
2264 Since
2266 2.6
2267 QCryptoCipherAlgorithm (Enum)
2269 The supported algorithms for content encryption ciphers
2270 Values
2272 aes-128
2273 AES with 128 bit / 16 byte keys
2274 aes-192
2276 AES with 192 bit / 24 byte keys
2277 aes-256
2279 AES with 256 bit / 32 byte keys
2280 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
2282 6.1)
2283 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
2285 cast5-128
2287 Cast5 with 128 bit / 16 byte keys
2288 serpent-128
2290 Serpent with 128 bit / 16 byte keys
2291 serpent-192
2293 Serpent with 192 bit / 24 byte keys
2294 serpent-256
2296 Serpent with 256 bit / 32 byte keys
2297 twofish-128
2299 Twofish with 128 bit / 16 byte keys
2300 twofish-192
2302 Twofish with 192 bit / 24 byte keys
2303 twofish-256
2305 Twofish with 256 bit / 32 byte keys
2306 Since
2308 2.6
2309 QCryptoCipherMode (Enum)
2311 The supported modes for content encryption ciphers
2312 Values
2314 ecb Electronic Code Book
2315 cbc Cipher Block Chaining
2317 xts XEX with tweaked code book and ciphertext stealing
2319 ctr Counter (Since 2.8)
2321 Since
2323 2.6
2324 QCryptoIVGenAlgorithm (Enum)
2326 The supported algorithms for generating initialization vectors for full
2327 disk encryption. The 'plain' generator should not be used for disks
2328 with sector numbers larger than 2^32, except where compatibility with
2329 pre-existing Linux dm-crypt volumes is required.
2330 Values
2332 plain 64-bit sector number truncated to 32-bits
2333 plain64
2335 64-bit sector number
2336 essiv 64-bit sector number encrypted with a hash of the encryption key
2338 Since
2340 2.6
2341 QCryptoBlockFormat (Enum)
2343 The supported full disk encryption formats
2344 Values
2346 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
2347 data from old images.
2348 luks LUKS encryption format. Recommended for new images
2350 Since
2352 2.6
2353 QCryptoBlockOptionsBase (Object)
2355 The common options that apply to all full disk encryption formats
2356 Members
2358 format: QCryptoBlockFormat
2359 the encryption format
2360 Since
2362 2.6
2363 QCryptoBlockOptionsQCow (Object)
2365 The options that apply to QCow/QCow2 AES-CBC encryption format
2366 Members
2368 key-secret: string (optional)
2369 the ID of a QCryptoSecret object providing the decryption key.
2370 Mandatory except when probing image for metadata only.
2371 Since
2373 2.6
2374 QCryptoBlockOptionsLUKS (Object)
2376 The options that apply to LUKS encryption format
2377 Members
2379 key-secret: string (optional)
2380 the ID of a QCryptoSecret object providing the decryption key.
2381 Mandatory except when probing image for metadata only.
2382 Since
2384 2.6
2385 QCryptoBlockCreateOptionsLUKS (Object)
2387 The options that apply to LUKS encryption format initialization
2388 Members
2390 cipher-alg: QCryptoCipherAlgorithm (optional)
2391 the cipher algorithm for data encryption Currently defaults to
2392 'aes-256'.
2393 cipher-mode: QCryptoCipherMode (optional)
2395 the cipher mode for data encryption Currently defaults to 'xts'
2396 ivgen-alg: QCryptoIVGenAlgorithm (optional)
2398 the initialization vector generator Currently defaults to
2399 'plain64'
2400 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2402 the initialization vector generator hash Currently defaults to
2403 'sha256'
2404 hash-alg: QCryptoHashAlgorithm (optional)
2406 the master key hash algorithm Currently defaults to 'sha256'
2407 iter-time: int (optional)
2409 number of milliseconds to spend in PBKDF passphrase processing.
2410 Currently defaults to 2000. (since 2.8)
2411 The members of QCryptoBlockOptionsLUKS
2413 Since
2415 2.6
2416 QCryptoBlockOpenOptions (Object)
2418 The options that are available for all encryption formats when opening
2419 an existing volume
2420 Members
2422 The members of QCryptoBlockOptionsBase
2423 The members of QCryptoBlockOptionsQCow when format is "qcow"
2425 The members of QCryptoBlockOptionsLUKS when format is "luks"
2427 Since
2429 2.6
2430 QCryptoBlockCreateOptions (Object)
2432 The options that are available for all encryption formats when initial‐
2433 izing a new volume
2434 Members
2436 The members of QCryptoBlockOptionsBase
2437 The members of QCryptoBlockOptionsQCow when format is "qcow"
2439 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
2441 Since
2443 2.6
2444 QCryptoBlockInfoBase (Object)
2446 The common information that applies to all full disk encryption formats
2447 Members
2449 format: QCryptoBlockFormat
2450 the encryption format
2451 Since
2453 2.7
2454 QCryptoBlockInfoLUKSSlot (Object)
2456 Information about the LUKS block encryption key slot options
2457 Members
2459 active: boolean
2460 whether the key slot is currently in use
2461 key-offset: int
2463 offset to the key material in bytes
2464 iters: int (optional)
2466 number of PBKDF2 iterations for key material
2467 stripes: int (optional)
2469 number of stripes for splitting key material
2470 Since
2472 2.7
2473 QCryptoBlockInfoLUKS (Object)
2475 Information about the LUKS block encryption options
2476 Members
2478 cipher-alg: QCryptoCipherAlgorithm
2479 the cipher algorithm for data encryption
2480 cipher-mode: QCryptoCipherMode
2482 the cipher mode for data encryption
2483 ivgen-alg: QCryptoIVGenAlgorithm
2485 the initialization vector generator
2486 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
2488 the initialization vector generator hash
2489 hash-alg: QCryptoHashAlgorithm
2491 the master key hash algorithm
2492 payload-offset: int
2494 offset to the payload data in bytes
2495 master-key-iters: int
2497 number of PBKDF2 iterations for key material
2498 uuid: string
2500 unique identifier for the volume
2501 slots: array of QCryptoBlockInfoLUKSSlot
2503 information about each key slot
2504 Since
2506 2.7
2507 QCryptoBlockInfo (Object)
2509 Information about the block encryption options
2510 Members
2512 The members of QCryptoBlockInfoBase
2513 The members of QCryptoBlockInfoLUKS when format is "luks"
2515 Since
2517 2.7
2518 QCryptoBlockLUKSKeyslotState (Enum)
2520 Defines state of keyslots that are affected by the update
2521 Values
2523 active The slots contain the given password and marked as active
2524 inactive
2526 The slots are erased (contain garbage) and marked as inactive
2527 Since
2529 5.1
2530 QCryptoBlockAmendOptionsLUKS (Object)
2532 This struct defines the update parameters that activate/de-activate set
2533 of keyslots
2534 Members
2536 state: QCryptoBlockLUKSKeyslotState
2537 the desired state of the keyslots
2538 new-secret: string (optional)
2540 The ID of a QCryptoSecret object providing the password to be
2541 written into added active keyslots
2542 old-secret: string (optional)
2544 Optional (for deactivation only) If given will deactivate all
2545 keyslots that match password located in QCryptoSecret with this
2546 ID
2547 iter-time: int (optional)
2549 Optional (for activation only) Number of milliseconds to spend
2550 in PBKDF passphrase processing for the newly activated keyslot.
2551 Currently defaults to 2000.
2552 keyslot: int (optional)
2554 Optional. ID of the keyslot to activate/deactivate. For keyslot
2555 activation, keyslot should not be active already (this is unsafe
2556 to update an active keyslot), but possible if 'force' parameter
2557 is given. If keyslot is not given, first free keyslot will be
2558 written.
2559 For keyslot deactivation, this parameter specifies the exact
2561 keyslot to deactivate
2562 secret: string (optional)
2564 Optional. The ID of a QCryptoSecret object providing the pass‐
2565 word to use to retrieve current master key. Defaults to the
2566 same secret that was used to open the image
2567 Since 5.1
2568 QCryptoBlockAmendOptions (Object)
2570 The options that are available for all encryption formats when amending
2571 encryption settings
2572 Members
2574 The members of QCryptoBlockOptionsBase
2575 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
2577 Since
2579 5.1
2580 SecretCommonProperties (Object)
2582 Properties for objects of classes derived from secret-common.
2583 Members
2585 loaded: boolean (optional)
2586 if true, the secret is loaded immediately when applying this op‐
2587 tion and will probably fail when processing the next option.
2588 Don't use; only provided for compatibility. (default: false)
2589 format: QCryptoSecretFormat (optional)
2591 the data format that the secret is provided in (default: raw)
2592 keyid: string (optional)
2594 the name of another secret that should be used to decrypt the
2595 provided data. If not present, the data is assumed to be unen‐
2596 crypted.
2597 iv: string (optional)
2599 the random initialization vector used for encryption of this
2600 particular secret. Should be a base64 encrypted string of the
2601 16-byte IV. Mandatory if keyid is given. Ignored if keyid is ab‐
2602 sent.
2603 Features
2605 deprecated
2606 Member loaded is deprecated. Setting true doesn't make sense,
2607 and false is already the default.
2608 Since
2610 2.6
2611 SecretProperties (Object)
2613 Properties for secret objects.
2614 Either data or file must be provided, but not both.
2616 Members
2618 data: string (optional)
2619 the associated with the secret from
2620 file: string (optional)
2622 the filename to load the data associated with the secret from
2623 The members of SecretCommonProperties
2625 Since
2627 2.6
2628 SecretKeyringProperties (Object)
2630 Properties for secret_keyring objects.
2631 Members
2633 serial: int
2634 serial number that identifies a key to get from the kernel
2635 The members of SecretCommonProperties
2637 Since
2639 5.1
2640 TlsCredsProperties (Object)
2642 Properties for objects of classes derived from tls-creds.
2643 Members
2645 verify-peer: boolean (optional)
2646 if true the peer credentials will be verified once the handshake
2647 is completed. This is a no-op for anonymous credentials. (de‐
2648 fault: true)
2649 dir: string (optional)
2651 the path of the directory that contains the credential files
2652 endpoint: QCryptoTLSCredsEndpoint (optional)
2654 whether the QEMU network backend that uses the credentials will
2655 be acting as a client or as a server (default: client)
2656 priority: string (optional)
2658 a gnutls priority string as described at
2659 https://gnutls.org/manual/html_node/Priority-Strings.html
2660 Since
2662 2.5
2663 TlsCredsAnonProperties (Object)
2665 Properties for tls-creds-anon objects.
2666 Members
2668 loaded: boolean (optional)
2669 if true, the credentials are loaded immediately when applying
2670 this option and will ignore options that are processed later.
2671 Don't use; only provided for compatibility. (default: false)
2672 The members of TlsCredsProperties
2674 Features
2676 deprecated
2677 Member loaded is deprecated. Setting true doesn't make sense,
2678 and false is already the default.
2679 Since
2681 2.5
2682 TlsCredsPskProperties (Object)
2684 Properties for tls-creds-psk objects.
2685 Members
2687 loaded: boolean (optional)
2688 if true, the credentials are loaded immediately when applying
2689 this option and will ignore options that are processed later.
2690 Don't use; only provided for compatibility. (default: false)
2691 username: string (optional)
2693 the username which will be sent to the server. For clients
2694 only. If absent, "qemu" is sent and the property will read back
2695 as an empty string.
2696 The members of TlsCredsProperties
2698 Features
2700 deprecated
2701 Member loaded is deprecated. Setting true doesn't make sense,
2702 and false is already the default.
2703 Since
2705 3.0
2706 TlsCredsX509Properties (Object)
2708 Properties for tls-creds-x509 objects.
2709 Members
2711 loaded: boolean (optional)
2712 if true, the credentials are loaded immediately when applying
2713 this option and will ignore options that are processed later.
2714 Don't use; only provided for compatibility. (default: false)
2715 sanity-check: boolean (optional)
2717 if true, perform some sanity checks before using the credentials
2718 (default: true)
2719 passwordid: string (optional)
2721 For the server-key.pem and client-key.pem files which contain
2722 sensitive private keys, it is possible to use an encrypted ver‐
2723 sion by providing the passwordid parameter. This provides the
2724 ID of a previously created secret object containing the password
2725 for decryption.
2726 The members of TlsCredsProperties
2728 Features
2730 deprecated
2731 Member loaded is deprecated. Setting true doesn't make sense,
2732 and false is already the default.
2733 Since
2735 2.5
2736
2738 Block core (VM unrelated)
2739 Background jobs
2740 JobType (Enum)
2741 Type of a background job.
2742 Values
2744 commit block commit job type, see "block-commit"
2745 stream block stream job type, see "block-stream"
2747 mirror drive mirror job type, see "drive-mirror"
2749 backup drive backup job type, see "drive-backup"
2751 create image creation job type, see "blockdev-create" (since 3.0)
2753 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
2755 snapshot-load
2757 snapshot load job type, see "snapshot-load" (since 6.0)
2758 snapshot-save
2760 snapshot save job type, see "snapshot-save" (since 6.0)
2761 snapshot-delete
2763 snapshot delete job type, see "snapshot-delete" (since 6.0)
2764 Since
2766 1.7
2767 JobStatus (Enum)
2769 Indicates the present state of a given job in its lifetime.
2770 Values
2772 undefined
2773 Erroneous, default state. Should not ever be visible.
2774 created
2776 The job has been created, but not yet started.
2777 running
2779 The job is currently running.
2780 paused The job is running, but paused. The pause may be requested by
2782 either the QMP user or by internal processes.
2783 ready The job is running, but is ready for the user to signal comple‐
2785 tion. This is used for long-running jobs like mirror that are
2786 designed to run indefinitely.
2787 standby
2789 The job is ready, but paused. This is nearly identical to
2790 paused. The job may return to ready or otherwise be canceled.
2791 waiting
2793 The job is waiting for other jobs in the transaction to converge
2794 to the waiting state. This status will likely not be visible for
2795 the last job in a transaction.
2796 pending
2798 The job has finished its work, but has finalization steps that
2799 it needs to make prior to completing. These changes will require
2800 manual intervention via job-finalize if auto-finalize was set to
2801 false. These pending changes may still fail.
2802 aborting
2804 The job is in the process of being aborted, and will finish with
2805 an error. The job will afterwards report that it is concluded.
2806 This status may not be visible to the management process.
2807 concluded
2809 The job has finished all work. If auto-dismiss was set to false,
2810 the job will remain in the query list until it is dismissed via
2811 job-dismiss.
2812 null The job is in the process of being dismantled. This state should
2814 not ever be visible externally.
2815 Since
2817 2.12
2818 JobVerb (Enum)
2820 Represents command verbs that can be applied to a job.
2821 Values
2823 cancel see job-cancel
2824 pause see job-pause
2826 resume see job-resume
2828 set-speed
2830 see block-job-set-speed
2831 complete
2833 see job-complete
2834 dismiss
2836 see job-dismiss
2837 finalize
2839 see job-finalize
2840 Since
2842 2.12
2843 JOB_STATUS_CHANGE (Event)
2845 Emitted when a job transitions to a different status.
2846 Arguments
2848 id: string
2849 The job identifier
2850 status: JobStatus
2852 The new job status
2853 Since
2855 3.0
2856 job-pause (Command)
2858 Pause an active job.
2859 This command returns immediately after marking the active job for paus‐
2861 ing. Pausing an already paused job is an error.
2862 The job will pause as soon as possible, which means transitioning into
2864 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
2865 The corresponding JOB_STATUS_CHANGE event will be emitted.
2866 Cancelling a paused job automatically resumes it.
2868 Arguments
2870 id: string
2871 The job identifier.
2872 Since
2874 3.0
2875 job-resume (Command)
2877 Resume a paused job.
2878 This command returns immediately after resuming a paused job. Resuming
2880 an already running job is an error.
2881 id : The job identifier.
2883 Arguments
2885 id: string
2886 Not documented
2887 Since
2889 3.0
2890 job-cancel (Command)
2892 Instruct an active background job to cancel at the next opportunity.
2893 This command returns immediately after marking the active job for can‐
2894 cellation.
2895 The job will cancel as soon as possible and then emit a JOB_STA‐
2897 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
2898 is possible that a job successfully completes (e.g. because it was al‐
2899 most done and there was no opportunity to cancel earlier than complet‐
2900 ing the job) and transitions to PENDING instead.
2901 Arguments
2903 id: string
2904 The job identifier.
2905 Since
2907 3.0
2908 job-complete (Command)
2910 Manually trigger completion of an active job in the READY state.
2911 Arguments
2913 id: string
2914 The job identifier.
2915 Since
2917 3.0
2918 job-dismiss (Command)
2920 Deletes a job that is in the CONCLUDED state. This command only needs
2921 to be run explicitly for jobs that don't have automatic dismiss en‐
2922 abled.
2923 This command will refuse to operate on any job that has not yet reached
2925 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
2926 JOB_READY event, job-cancel or job-complete will still need to be used
2927 as appropriate.
2928 Arguments
2930 id: string
2931 The job identifier.
2932 Since
2934 3.0
2935 job-finalize (Command)
2937 Instructs all jobs in a transaction (or a single job if it is not part
2938 of any transaction) to finalize any graph changes and do any necessary
2939 cleanup. This command requires that all involved jobs are in the PEND‐
2940 ING state.
2941 For jobs in a transaction, instructing one job to finalize will force
2943 ALL jobs in the transaction to finalize, so it is only necessary to in‐
2944 struct a single member job to finalize.
2945 Arguments
2947 id: string
2948 The identifier of any job in the transaction, or of a job that
2949 is not part of any transaction.
2950 Since
2952 3.0
2953 JobInfo (Object)
2955 Information about a job.
2956 Members
2958 id: string
2959 The job identifier
2960 type: JobType
2962 The kind of job that is being performed
2963 status: JobStatus
2965 Current job state/status
2966 current-progress: int
2968 Progress made until now. The unit is arbitrary and the value can
2969 only meaningfully be used for the ratio of current-progress to
2970 total-progress. The value is monotonically increasing.
2971 total-progress: int
2973 Estimated current-progress value at the completion of the job.
2974 This value can arbitrarily change while the job is running, in
2975 both directions.
2976 error: string (optional)
2978 If this field is present, the job failed; if it is still missing
2979 in the CONCLUDED state, this indicates successful completion.
2980 The value is a human-readable error message to describe the rea‐
2982 son for the job failure. It should not be parsed by applica‐
2983 tions.
2984 Since
2986 3.0
2987 query-jobs (Command)
2989 Return information about jobs.
2990 Returns
2992 a list with a JobInfo for each active job
2993 Since
2995 3.0
2996 SnapshotInfo (Object)
2998 Members
2999 id: string
3000 unique snapshot id
3001 name: string
3003 user chosen name
3004 vm-state-size: int
3006 size of the VM state
3007 date-sec: int
3009 UTC date of the snapshot in seconds
3010 date-nsec: int
3012 fractional part in nano seconds to be used with date-sec
3013 vm-clock-sec: int
3015 VM clock relative to boot in seconds
3016 vm-clock-nsec: int
3018 fractional part in nano seconds to be used with vm-clock-sec
3019 icount: int (optional)
3021 Current instruction count. Appears when execution record/replay
3022 is enabled. Used for "time-traveling" to match the moment in the
3023 recorded execution with the snapshots. This counter may be ob‐
3024 tained through query-replay command (since 5.2)
3025 Since
3027 1.3
3028 ImageInfoSpecificQCow2EncryptionBase (Object)
3030 Members
3031 format: BlockdevQcow2EncryptionFormat
3032 The encryption format
3033 Since
3035 2.10
3036 ImageInfoSpecificQCow2Encryption (Object)
3038 Members
3039 The members of ImageInfoSpecificQCow2EncryptionBase
3040 The members of QCryptoBlockInfoLUKS when format is "luks"
3042 Since
3044 2.10
3045 ImageInfoSpecificQCow2 (Object)
3047 Members
3048 compat: string
3049 compatibility level
3050 data-file: string (optional)
3052 the filename of the external data file that is stored in the im‐
3053 age and used as a default for opening the image (since: 4.0)
3054 data-file-raw: boolean (optional)
3056 True if the external data file must stay valid as a standalone
3057 (read-only) raw image without looking at qcow2 metadata (since:
3058 4.0)
3059 extended-l2: boolean (optional)
3061 true if the image has extended L2 entries; only valid for compat
3062 >= 1.1 (since 5.2)
3063 lazy-refcounts: boolean (optional)
3065 on or off; only valid for compat >= 1.1
3066 corrupt: boolean (optional)
3068 true if the image has been marked corrupt; only valid for compat
3069 >= 1.1 (since 2.2)
3070 refcount-bits: int
3072 width of a refcount entry in bits (since 2.3)
3073 encrypt: ImageInfoSpecificQCow2Encryption (optional)
3075 details about encryption parameters; only set if image is en‐
3076 crypted (since 2.10)
3077 bitmaps: array of Qcow2BitmapInfo (optional)
3079 A list of qcow2 bitmap details (since 4.0)
3080 compression-type: Qcow2CompressionType
3082 the image cluster compression method (since 5.1)
3083 Since
3085 1.7
3086 ImageInfoSpecificVmdk (Object)
3088 Members
3089 create-type: string
3090 The create type of VMDK image
3091 cid: int
3093 Content id of image
3094 parent-cid: int
3096 Parent VMDK image's cid
3097 extents: array of ImageInfo
3099 List of extent files
3100 Since
3102 1.7
3103 ImageInfoSpecificRbd (Object)
3105 Members
3106 encryption-format: RbdImageEncryptionFormat (optional)
3107 Image encryption format
3108 Since
3110 6.1
3111 ImageInfoSpecificKind (Enum)
3113 Values
3114 luks Since 2.7
3115 rbd Since 6.1
3117 qcow2 Not documented
3119 vmdk Not documented
3121 Since
3123 1.7
3124 ImageInfoSpecificQCow2Wrapper (Object)
3126 Members
3127 data: ImageInfoSpecificQCow2
3128 Not documented
3129 Since
3131 1.7
3132 ImageInfoSpecificVmdkWrapper (Object)
3134 Members
3135 data: ImageInfoSpecificVmdk
3136 Not documented
3137 Since
3139 6.1
3140 ImageInfoSpecificLUKSWrapper (Object)
3142 Members
3143 data: QCryptoBlockInfoLUKS
3144 Not documented
3145 Since
3147 2.7
3148 ImageInfoSpecificRbdWrapper (Object)
3150 Members
3151 data: ImageInfoSpecificRbd
3152 Not documented
3153 Since
3155 6.1
3156 ImageInfoSpecific (Object)
3158 A discriminated record of image format specific information structures.
3159 Members
3161 type: ImageInfoSpecificKind
3162 Not documented
3163 The members of ImageInfoSpecificQCow2Wrapper when type is "qcow2"
3165 The members of ImageInfoSpecificVmdkWrapper when type is "vmdk"
3167 The members of ImageInfoSpecificLUKSWrapper when type is "luks"
3169 The members of ImageInfoSpecificRbdWrapper when type is "rbd"
3171 Since
3173 1.7
3174 ImageInfo (Object)
3176 Information about a QEMU image file
3177 Members
3179 filename: string
3180 name of the image file
3181 format: string
3183 format of the image file
3184 virtual-size: int
3186 maximum capacity in bytes of the image
3187 actual-size: int (optional)
3189 actual size on disk in bytes of the image
3190 dirty-flag: boolean (optional)
3192 true if image is not cleanly closed
3193 cluster-size: int (optional)
3195 size of a cluster in bytes
3196 encrypted: boolean (optional)
3198 true if the image is encrypted
3199 compressed: boolean (optional)
3201 true if the image is compressed (Since 1.7)
3202 backing-filename: string (optional)
3204 name of the backing file
3205 full-backing-filename: string (optional)
3207 full path of the backing file
3208 backing-filename-format: string (optional)
3210 the format of the backing file
3211 snapshots: array of SnapshotInfo (optional)
3213 list of VM snapshots
3214 backing-image: ImageInfo (optional)
3216 info of the backing image (since 1.6)
3217 format-specific: ImageInfoSpecific (optional)
3219 structure supplying additional format-specific information
3220 (since 1.7)
3221 Since
3223 1.3
3224 ImageCheck (Object)
3226 Information about a QEMU image file check
3227 Members
3229 filename: string
3230 name of the image file checked
3231 format: string
3233 format of the image file checked
3234 check-errors: int
3236 number of unexpected errors occurred during check
3237 image-end-offset: int (optional)
3239 offset (in bytes) where the image ends, this field is present if
3240 the driver for the image format supports it
3241 corruptions: int (optional)
3243 number of corruptions found during the check if any
3244 leaks: int (optional)
3246 number of leaks found during the check if any
3247 corruptions-fixed: int (optional)
3249 number of corruptions fixed during the check if any
3250 leaks-fixed: int (optional)
3252 number of leaks fixed during the check if any
3253 total-clusters: int (optional)
3255 total number of clusters, this field is present if the driver
3256 for the image format supports it
3257 allocated-clusters: int (optional)
3259 total number of allocated clusters, this field is present if the
3260 driver for the image format supports it
3261 fragmented-clusters: int (optional)
3263 total number of fragmented clusters, this field is present if
3264 the driver for the image format supports it
3265 compressed-clusters: int (optional)
3267 total number of compressed clusters, this field is present if
3268 the driver for the image format supports it
3269 Since
3271 1.4
3272 MapEntry (Object)
3274 Mapping information from a virtual block range to a host file range
3275 Members
3277 start: int
3278 virtual (guest) offset of the first byte described by this entry
3279 length: int
3281 the number of bytes of the mapped virtual range
3282 data: boolean
3284 reading the image will actually read data from a file (in par‐
3285 ticular, if offset is present this means that the sectors are
3286 not simply preallocated, but contain actual data in raw format)
3287 zero: boolean
3289 whether the virtual blocks read as zeroes
3290 depth: int
3292 number of layers (0 = top image, 1 = top image's backing file,
3293 ..., n - 1 = bottom image (where n is the number of images in
3294 the chain)) before reaching one for which the range is allocated
3295 present: boolean
3297 true if this layer provides the data, false if adding a backing
3298 layer could impact this region (since 6.1)
3299 offset: int (optional)
3301 if present, the image file stores the data for this range in raw
3302 format at the given (host) offset
3303 filename: string (optional)
3305 filename that is referred to by offset
3306 Since
3308 2.6
3309 BlockdevCacheInfo (Object)
3311 Cache mode information for a block device
3312 Members
3314 writeback: boolean
3315 true if writeback mode is enabled
3316 direct: boolean
3318 true if the host page cache is bypassed (O_DIRECT)
3319 no-flush: boolean
3321 true if flush requests are ignored for the device
3322 Since
3324 2.3
3325 BlockDeviceInfo (Object)
3327 Information about the backing device for a block device.
3328 Members
3330 file: string
3331 the filename of the backing device
3332 node-name: string (optional)
3334 the name of the block driver node (Since 2.0)
3335 ro: boolean
3337 true if the backing device was open read-only
3338 drv: string
3340 the name of the block format used to open the backing device. As
3341 of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
3342 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
3343 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2',
3344 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added,
3345 'cow' dropped 2.3: 'host_floppy' deprecated 2.5: 'host_floppy'
3346 dropped 2.6: 'luks' added 2.8: 'replication' added, 'tftp'
3347 dropped 2.9: 'archipelago' dropped
3348 backing_file: string (optional)
3350 the name of the backing file (for copy-on-write)
3351 backing_file_depth: int
3353 number of files in the backing file chain (since: 1.2)
3354 encrypted: boolean
3356 true if the backing device is encrypted
3357 detect_zeroes: BlockdevDetectZeroesOptions
3359 detect and optimize zero writes (Since 2.1)
3360 bps: int
3362 total throughput limit in bytes per second is specified
3363 bps_rd: int
3365 read throughput limit in bytes per second is specified
3366 bps_wr: int
3368 write throughput limit in bytes per second is specified
3369 iops: int
3371 total I/O operations per second is specified
3372 iops_rd: int
3374 read I/O operations per second is specified
3375 iops_wr: int
3377 write I/O operations per second is specified
3378 image: ImageInfo
3380 the info of image used (since: 1.6)
3381 bps_max: int (optional)
3383 total throughput limit during bursts,
3385 in bytes (Since 1.7)
3386 bps_rd_max: int (optional)
3388 read throughput limit during bursts,
3390 in bytes (Since 1.7)
3391 bps_wr_max: int (optional)
3393 write throughput limit during bursts,
3395 in bytes (Since 1.7)
3396 iops_max: int (optional)
3398 total I/O operations per second during bursts,
3400 in bytes (Since 1.7)
3401 iops_rd_max: int (optional)
3403 read I/O operations per second during bursts,
3405 in bytes (Since 1.7)
3406 iops_wr_max: int (optional)
3408 write I/O operations per second during bursts,
3410 in bytes (Since 1.7)
3411 bps_max_length: int (optional)
3413 maximum length of the bps_max burst
3415 period, in seconds. (Since 2.6)
3416 bps_rd_max_length: int (optional)
3418 maximum length of the bps_rd_max
3420 burst period, in seconds. (Since 2.6)
3421 bps_wr_max_length: int (optional)
3423 maximum length of the bps_wr_max
3425 burst period, in seconds. (Since 2.6)
3426 iops_max_length: int (optional)
3428 maximum length of the iops burst
3430 period, in seconds. (Since 2.6)
3431 iops_rd_max_length: int (optional)
3433 maximum length of the iops_rd_max
3435 burst period, in seconds. (Since 2.6)
3436 iops_wr_max_length: int (optional)
3438 maximum length of the iops_wr_max
3440 burst period, in seconds. (Since 2.6)
3441 iops_size: int (optional)
3443 an I/O size in bytes (Since 1.7)
3444 group: string (optional)
3446 throttle group name (Since 2.4)
3447 cache: BlockdevCacheInfo
3449 the cache mode used for the block device (since: 2.3)
3450 write_threshold: int
3452 configured write threshold for the device. 0 if disabled.
3453 (Since 2.3)
3454 dirty-bitmaps: array of BlockDirtyInfo (optional)
3456 dirty bitmaps information (only present if node has one or more
3457 dirty bitmaps) (Since 4.2)
3458 Since
3460 0.14
3461 BlockDeviceIoStatus (Enum)
3463 An enumeration of block device I/O status.
3464 Values
3466 ok The last I/O operation has succeeded
3467 failed The last I/O operation has failed
3469 nospace
3471 The last I/O operation has failed due to a no-space condition
3472 Since
3474 1.0
3475 BlockDirtyInfo (Object)
3477 Block dirty bitmap information.
3478 Members
3480 name: string (optional)
3481 the name of the dirty bitmap (Since 2.4)
3482 count: int
3484 number of dirty bytes according to the dirty bitmap
3485 granularity: int
3487 granularity of the dirty bitmap in bytes (since 1.4)
3488 recording: boolean
3490 true if the bitmap is recording new writes from the guest. Re‐
3491 places active and disabled statuses. (since 4.0)
3492 busy: boolean
3494 true if the bitmap is in-use by some operation (NBD or jobs) and
3495 cannot be modified via QMP or used by another operation. Re‐
3496 places locked and frozen statuses. (since 4.0)
3497 persistent: boolean
3499 true if the bitmap was stored on disk, is scheduled to be stored
3500 on disk, or both. (since 4.0)
3501 inconsistent: boolean (optional)
3503 true if this is a persistent bitmap that was improperly stored.
3504 Implies persistent to be true; recording and busy to be false.
3505 This bitmap cannot be used. To remove it, use block-dirty-bit‐
3506 map-remove. (Since 4.0)
3507 Since
3509 1.3
3510 Qcow2BitmapInfoFlags (Enum)
3512 An enumeration of flags that a bitmap can report to the user.
3513 Values
3515 in-use This flag is set by any process actively modifying the qcow2
3516 file, and cleared when the updated bitmap is flushed to the
3517 qcow2 image. The presence of this flag in an offline image
3518 means that the bitmap was not saved correctly after its last us‐
3519 age, and may contain inconsistent data.
3520 auto The bitmap must reflect all changes of the virtual disk by any
3522 application that would write to this qcow2 file.
3523 Since
3525 4.0
3526 Qcow2BitmapInfo (Object)
3528 Qcow2 bitmap information.
3529 Members
3531 name: string
3532 the name of the bitmap
3533 granularity: int
3535 granularity of the bitmap in bytes
3536 flags: array of Qcow2BitmapInfoFlags
3538 flags of the bitmap
3539 Since
3541 4.0
3542 BlockLatencyHistogramInfo (Object)
3544 Block latency histogram.
3545 Members
3547 boundaries: array of int
3548 list of interval boundary values in nanoseconds, all greater
3549 than zero and in ascending order. For example, the list [10,
3550 50, 100] produces the following histogram intervals: [0, 10),
3551 [10, 50), [50, 100), [100, +inf).
3552 bins: array of int
3554 list of io request counts corresponding to histogram intervals.
3555 len(bins) = len(boundaries) + 1 For the example above, bins may
3556 be something like [3, 1, 5, 2], and corresponding histogram
3557 looks like:
3558 5| *
3560 4| *
3561 3| * *
3562 2| * * *
3563 1| * * * *
3564 +------------------
3565 10 50 100
3566 Since
3568 4.0
3569 BlockInfo (Object)
3571 Block device information. This structure describes a virtual device
3572 and the backing device associated with it.
3573 Members
3575 device: string
3576 The device name associated with the virtual device.
3577 qdev: string (optional)
3579 The qdev ID, or if no ID is assigned, the QOM path of the block
3580 device. (since 2.10)
3581 type: string
3583 This field is returned only for compatibility reasons, it should
3584 not be used (always returns 'unknown')
3585 removable: boolean
3587 True if the device supports removable media.
3588 locked: boolean
3590 True if the guest has locked this device from having its media
3591 removed
3592 tray_open: boolean (optional)
3594 True if the device's tray is open (only present if it has a
3595 tray)
3596 io-status: BlockDeviceIoStatus (optional)
3598 BlockDeviceIoStatus. Only present if the device supports it and
3599 the VM is configured to stop on errors (supported device models:
3600 virtio-blk, IDE, SCSI except scsi-generic)
3601 inserted: BlockDeviceInfo (optional)
3603 BlockDeviceInfo describing the device if media is present
3604 Since
3606 0.14
3607 BlockMeasureInfo (Object)
3609 Image file size calculation information. This structure describes the
3610 size requirements for creating a new image file.
3611 The size requirements depend on the new image file format. File size
3613 always equals virtual disk size for the 'raw' format, even for sparse
3614 POSIX files. Compact formats such as 'qcow2' represent unallocated and
3615 zero regions efficiently so file size may be smaller than virtual disk
3616 size.
3617 The values are upper bounds that are guaranteed to fit the new image
3619 file. Subsequent modification, such as internal snapshot or further
3620 bitmap creation, may require additional space and is not covered here.
3621 Members
3623 required: int
3624 Size required for a new image file, in bytes, when copying just
3625 allocated guest-visible contents.
3626 fully-allocated: int
3628 Image file size, in bytes, once data has been written to all
3629 sectors, when copying just guest-visible contents.
3630 bitmaps: int (optional)
3632 Additional size required if all the top-level bitmap metadata in
3633 the source image were to be copied to the destination, present
3634 only when source and destination both support persistent bit‐
3635 maps. (since 5.1)
3636 Since
3638 2.10
3639 query-block (Command)
3641 Get a list of BlockInfo for all virtual block devices.
3642 Returns
3644 a list of BlockInfo describing each virtual block device. Filter nodes
3645 that were created implicitly are skipped over.
3646 Since
3648 0.14
3649 Example
3651 -> { "execute": "query-block" }
3652 <- {
3653 "return":[
3654 {
3655 "io-status": "ok",
3656 "device":"ide0-hd0",
3657 "locked":false,
3658 "removable":false,
3659 "inserted":{
3660 "ro":false,
3661 "drv":"qcow2",
3662 "encrypted":false,
3663 "file":"disks/test.qcow2",
3664 "backing_file_depth":1,
3665 "bps":1000000,
3666 "bps_rd":0,
3667 "bps_wr":0,
3668 "iops":1000000,
3669 "iops_rd":0,
3670 "iops_wr":0,
3671 "bps_max": 8000000,
3672 "bps_rd_max": 0,
3673 "bps_wr_max": 0,
3674 "iops_max": 0,
3675 "iops_rd_max": 0,
3676 "iops_wr_max": 0,
3677 "iops_size": 0,
3678 "detect_zeroes": "on",
3679 "write_threshold": 0,
3680 "image":{
3681 "filename":"disks/test.qcow2",
3682 "format":"qcow2",
3683 "virtual-size":2048000,
3684 "backing_file":"base.qcow2",
3685 "full-backing-filename":"disks/base.qcow2",
3686 "backing-filename-format":"qcow2",
3687 "snapshots":[
3688 {
3689 "id": "1",
3690 "name": "snapshot1",
3691 "vm-state-size": 0,
3692 "date-sec": 10000200,
3693 "date-nsec": 12,
3694 "vm-clock-sec": 206,
3695 "vm-clock-nsec": 30
3696 }
3697 ],
3698 "backing-image":{
3699 "filename":"disks/base.qcow2",
3700 "format":"qcow2",
3701 "virtual-size":2048000
3702 }
3703 }
3704 },
3705 "qdev": "ide_disk",
3706 "type":"unknown"
3707 },
3708 {
3709 "io-status": "ok",
3710 "device":"ide1-cd0",
3711 "locked":false,
3712 "removable":true,
3713 "qdev": "/machine/unattached/device[23]",
3714 "tray_open": false,
3715 "type":"unknown"
3716 },
3717 {
3718 "device":"floppy0",
3719 "locked":false,
3720 "removable":true,
3721 "qdev": "/machine/unattached/device[20]",
3722 "type":"unknown"
3723 },
3724 {
3725 "device":"sd0",
3726 "locked":false,
3727 "removable":true,
3728 "type":"unknown"
3729 }
3730 ]
3731 }
3732 BlockDeviceTimedStats (Object)
3734 Statistics of a block device during a given interval of time.
3735 Members
3737 interval_length: int
3738 Interval used for calculating the statistics, in seconds.
3739 min_rd_latency_ns: int
3741 Minimum latency of read operations in the defined interval, in
3742 nanoseconds.
3743 min_wr_latency_ns: int
3745 Minimum latency of write operations in the defined interval, in
3746 nanoseconds.
3747 min_flush_latency_ns: int
3749 Minimum latency of flush operations in the defined interval, in
3750 nanoseconds.
3751 max_rd_latency_ns: int
3753 Maximum latency of read operations in the defined interval, in
3754 nanoseconds.
3755 max_wr_latency_ns: int
3757 Maximum latency of write operations in the defined interval, in
3758 nanoseconds.
3759 max_flush_latency_ns: int
3761 Maximum latency of flush operations in the defined interval, in
3762 nanoseconds.
3763 avg_rd_latency_ns: int
3765 Average latency of read operations in the defined interval, in
3766 nanoseconds.
3767 avg_wr_latency_ns: int
3769 Average latency of write operations in the defined interval, in
3770 nanoseconds.
3771 avg_flush_latency_ns: int
3773 Average latency of flush operations in the defined interval, in
3774 nanoseconds.
3775 avg_rd_queue_depth: number
3777 Average number of pending read operations in the defined inter‐
3778 val.
3779 avg_wr_queue_depth: number
3781 Average number of pending write operations in the defined inter‐
3782 val.
3783 Since
3785 2.5
3786 BlockDeviceStats (Object)
3788 Statistics of a virtual block device or a block backing device.
3789 Members
3791 rd_bytes: int
3792 The number of bytes read by the device.
3793 wr_bytes: int
3795 The number of bytes written by the device.
3796 unmap_bytes: int
3798 The number of bytes unmapped by the device (Since 4.2)
3799 rd_operations: int
3801 The number of read operations performed by the device.
3802 wr_operations: int
3804 The number of write operations performed by the device.
3805 flush_operations: int
3807 The number of cache flush operations performed by the device
3808 (since 0.15)
3809 unmap_operations: int
3811 The number of unmap operations performed by the device (Since
3812 4.2)
3813 rd_total_time_ns: int
3815 Total time spent on reads in nanoseconds (since 0.15).
3816 wr_total_time_ns: int
3818 Total time spent on writes in nanoseconds (since 0.15).
3819 flush_total_time_ns: int
3821 Total time spent on cache flushes in nanoseconds (since 0.15).
3822 unmap_total_time_ns: int
3824 Total time spent on unmap operations in nanoseconds (Since 4.2)
3825 wr_highest_offset: int
3827 The offset after the greatest byte written to the device. The
3828 intended use of this information is for growable sparse files
3829 (like qcow2) that are used on top of a physical device.
3830 rd_merged: int
3832 Number of read requests that have been merged into another re‐
3833 quest (Since 2.3).
3834 wr_merged: int
3836 Number of write requests that have been merged into another re‐
3837 quest (Since 2.3).
3838 unmap_merged: int
3840 Number of unmap requests that have been merged into another re‐
3841 quest (Since 4.2)
3842 idle_time_ns: int (optional)
3844 Time since the last I/O operation, in nanoseconds. If the field
3845 is absent it means that there haven't been any operations yet
3846 (Since 2.5).
3847 failed_rd_operations: int
3849 The number of failed read operations performed by the device
3850 (Since 2.5)
3851 failed_wr_operations: int
3853 The number of failed write operations performed by the device
3854 (Since 2.5)
3855 failed_flush_operations: int
3857 The number of failed flush operations performed by the device
3858 (Since 2.5)
3859 failed_unmap_operations: int
3861 The number of failed unmap operations performed by the device
3862 (Since 4.2)
3863 invalid_rd_operations: int
3865 The number of invalid read operations
3867 performed by the device (Since 2.5)
3868 invalid_wr_operations: int
3870 The number of invalid write operations performed by the device
3871 (Since 2.5)
3872 invalid_flush_operations: int
3874 The number of invalid flush operations performed by the device
3875 (Since 2.5)
3876 invalid_unmap_operations: int
3878 The number of invalid unmap operations performed by the device
3879 (Since 4.2)
3880 account_invalid: boolean
3882 Whether invalid operations are included in the last access sta‐
3883 tistics (Since 2.5)
3884 account_failed: boolean
3886 Whether failed operations are included in the latency and last
3887 access statistics (Since 2.5)
3888 timed_stats: array of BlockDeviceTimedStats
3890 Statistics specific to the set of previously defined intervals
3891 of time (Since 2.5)
3892 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
3894 BlockLatencyHistogramInfo. (Since 4.0)
3895 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
3897 BlockLatencyHistogramInfo. (Since 4.0)
3898 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
3900 BlockLatencyHistogramInfo. (Since 4.0)
3901 Since
3903 0.14
3904 BlockStatsSpecificFile (Object)
3906 File driver statistics
3907 Members
3909 discard-nb-ok: int
3910 The number of successful discard operations performed by the
3911 driver.
3912 discard-nb-failed: int
3914 The number of failed discard operations performed by the driver.
3915 discard-bytes-ok: int
3917 The number of bytes discarded by the driver.
3918 Since
3920 4.2
3921 BlockStatsSpecificNvme (Object)
3923 NVMe driver statistics
3924 Members
3926 completion-errors: int
3927 The number of completion errors.
3928 aligned-accesses: int
3930 The number of aligned accesses performed by the driver.
3931 unaligned-accesses: int
3933 The number of unaligned accesses performed by the driver.
3934 Since
3936 5.2
3937 BlockStatsSpecific (Object)
3939 Block driver specific statistics
3940 Members
3942 driver: BlockdevDriver
3943 Not documented
3944 The members of BlockStatsSpecificFile when driver is "file"
3946 The members of BlockStatsSpecificFile when driver is "host_device" (If:
3948 HAVE_HOST_BLOCK_DEVICE)
3949 The members of BlockStatsSpecificNvme when driver is "nvme"
3951 Since
3953 4.2
3954 BlockStats (Object)
3956 Statistics of a virtual block device or a block backing device.
3957 Members
3959 device: string (optional)
3960 If the stats are for a virtual block device, the name corre‐
3961 sponding to the virtual block device.
3962 node-name: string (optional)
3964 The node name of the device. (Since 2.3)
3965 qdev: string (optional)
3967 The qdev ID, or if no ID is assigned, the QOM path of the block
3968 device. (since 3.0)
3969 stats: BlockDeviceStats
3971 A BlockDeviceStats for the device.
3972 driver-specific: BlockStatsSpecific (optional)
3974 Optional driver-specific stats. (Since 4.2)
3975 parent: BlockStats (optional)
3977 This describes the file block device if it has one. Contains
3978 recursively the statistics of the underlying protocol (e.g. the
3979 host file for a qcow2 image). If there is no underlying proto‐
3980 col, this field is omitted
3981 backing: BlockStats (optional)
3983 This describes the backing block device if it has one. (Since
3984 2.0)
3985 Since
3987 0.14
3988 query-blockstats (Command)
3990 Query the BlockStats for all virtual block devices.
3991 Arguments
3993 query-nodes: boolean (optional)
3994 If true, the command will query all the block nodes that have a
3995 node name, in a list which will include "parent" information,
3996 but not "backing". If false or omitted, the behavior is as be‐
3997 fore - query all the device backends, recursively including
3998 their "parent" and "backing". Filter nodes that were created im‐
3999 plicitly are skipped over in this mode. (Since 2.3)
4000 Returns
4002 A list of BlockStats for each virtual block devices.
4003 Since
4005 0.14
4006 Example
4008 -> { "execute": "query-blockstats" }
4009 <- {
4010 "return":[
4011 {
4012 "device":"ide0-hd0",
4013 "parent":{
4014 "stats":{
4015 "wr_highest_offset":3686448128,
4016 "wr_bytes":9786368,
4017 "wr_operations":751,
4018 "rd_bytes":122567168,
4019 "rd_operations":36772
4020 "wr_total_times_ns":313253456
4021 "rd_total_times_ns":3465673657
4022 "flush_total_times_ns":49653
4023 "flush_operations":61,
4024 "rd_merged":0,
4025 "wr_merged":0,
4026 "idle_time_ns":2953431879,
4027 "account_invalid":true,
4028 "account_failed":false
4029 }
4030 },
4031 "stats":{
4032 "wr_highest_offset":2821110784,
4033 "wr_bytes":9786368,
4034 "wr_operations":692,
4035 "rd_bytes":122739200,
4036 "rd_operations":36604
4037 "flush_operations":51,
4038 "wr_total_times_ns":313253456
4039 "rd_total_times_ns":3465673657
4040 "flush_total_times_ns":49653,
4041 "rd_merged":0,
4042 "wr_merged":0,
4043 "idle_time_ns":2953431879,
4044 "account_invalid":true,
4045 "account_failed":false
4046 },
4047 "qdev": "/machine/unattached/device[23]"
4048 },
4049 {
4050 "device":"ide1-cd0",
4051 "stats":{
4052 "wr_highest_offset":0,
4053 "wr_bytes":0,
4054 "wr_operations":0,
4055 "rd_bytes":0,
4056 "rd_operations":0
4057 "flush_operations":0,
4058 "wr_total_times_ns":0
4059 "rd_total_times_ns":0
4060 "flush_total_times_ns":0,
4061 "rd_merged":0,
4062 "wr_merged":0,
4063 "account_invalid":false,
4064 "account_failed":false
4065 },
4066 "qdev": "/machine/unattached/device[24]"
4067 },
4068 {
4069 "device":"floppy0",
4070 "stats":{
4071 "wr_highest_offset":0,
4072 "wr_bytes":0,
4073 "wr_operations":0,
4074 "rd_bytes":0,
4075 "rd_operations":0
4076 "flush_operations":0,
4077 "wr_total_times_ns":0
4078 "rd_total_times_ns":0
4079 "flush_total_times_ns":0,
4080 "rd_merged":0,
4081 "wr_merged":0,
4082 "account_invalid":false,
4083 "account_failed":false
4084 },
4085 "qdev": "/machine/unattached/device[16]"
4086 },
4087 {
4088 "device":"sd0",
4089 "stats":{
4090 "wr_highest_offset":0,
4091 "wr_bytes":0,
4092 "wr_operations":0,
4093 "rd_bytes":0,
4094 "rd_operations":0
4095 "flush_operations":0,
4096 "wr_total_times_ns":0
4097 "rd_total_times_ns":0
4098 "flush_total_times_ns":0,
4099 "rd_merged":0,
4100 "wr_merged":0,
4101 "account_invalid":false,
4102 "account_failed":false
4103 }
4104 }
4105 ]
4106 }
4107 BlockdevOnError (Enum)
4109 An enumeration of possible behaviors for errors on I/O operations. The
4110 exact meaning depends on whether the I/O was initiated by a guest or by
4111 a block job
4112 Values
4114 report for guest operations, report the error to the guest; for jobs,
4115 cancel the job
4116 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
4118 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
4119 the failing request later and may still complete successfully.
4120 The stream block job continues to stream and will complete with
4121 an error.
4122 enospc same as stop on ENOSPC, same as report otherwise.
4124 stop for guest operations, stop the virtual machine; for jobs, pause
4126 the job
4127 auto inherit the error handling policy of the backend (since: 2.7)
4129 Since
4131 1.3
4132 MirrorSyncMode (Enum)
4134 An enumeration of possible behaviors for the initial synchronization
4135 phase of storage mirroring.
4136 Values
4138 top copies data in the topmost image to the destination
4139 full copies data from all images to the destination
4141 none only copy data written from now on
4143 incremental
4145 only copy data described by the dirty bitmap. (since: 2.4)
4146 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
4148 havior on completion is determined by the BitmapSyncMode.
4149 Since
4151 1.3
4152 BitmapSyncMode (Enum)
4154 An enumeration of possible behaviors for the synchronization of a bit‐
4155 map when used for data copy operations.
4156 Values
4158 on-success
4159 The bitmap is only synced when the operation is successful.
4160 This is the behavior always used for 'INCREMENTAL' backups.
4161 never The bitmap is never synchronized with the operation, and is
4163 treated solely as a read-only manifest of blocks to copy.
4164 always The bitmap is always synchronized with the operation, regardless
4166 of whether or not the operation was successful.
4167 Since
4169 4.2
4170 MirrorCopyMode (Enum)
4172 An enumeration whose values tell the mirror block job when to trigger
4173 writes to the target.
4174 Values
4176 background
4177 copy data in background only.
4178 write-blocking
4180 when data is written to the source, write it (synchronously) to
4181 the target as well. In addition, data is copied in background
4182 just like in background mode.
4183 Since
4185 3.0
4186 BlockJobInfo (Object)
4188 Information about a long-running block device operation.
4189 Members
4191 type: string
4192 the job type ('stream' for image streaming)
4193 device: string
4195 The job identifier. Originally the device name but other values
4196 are allowed since QEMU 2.7
4197 len: int
4199 Estimated offset value at the completion of the job. This value
4200 can arbitrarily change while the job is running, in both direc‐
4201 tions.
4202 offset: int
4204 Progress made until now. The unit is arbitrary and the value can
4205 only meaningfully be used for the ratio of offset to len. The
4206 value is monotonically increasing.
4207 busy: boolean
4209 false if the job is known to be in a quiescent state, with no
4210 pending I/O. Since 1.3.
4211 paused: boolean
4213 whether the job is paused or, if busy is true, will pause itself
4214 as soon as possible. Since 1.3.
4215 speed: int
4217 the rate limit, bytes per second
4218 io-status: BlockDeviceIoStatus
4220 the status of the job (since 1.3)
4221 ready: boolean
4223 true if the job may be completed (since 2.2)
4224 status: JobStatus
4226 Current job state/status (since 2.12)
4227 auto-finalize: boolean
4229 Job will finalize itself when PENDING, moving to the CONCLUDED
4230 state. (since 2.12)
4231 auto-dismiss: boolean
4233 Job will dismiss itself when CONCLUDED, moving to the NULL state
4234 and disappearing from the query list. (since 2.12)
4235 error: string (optional)
4237 Error information if the job did not complete successfully. Not
4238 set if the job completed successfully. (since 2.12.1)
4239 Since
4241 1.1
4242 query-block-jobs (Command)
4244 Return information about long-running block device operations.
4245 Returns
4247 a list of BlockJobInfo for each active block job
4248 Since
4250 1.1
4251 block_resize (Command)
4253 Resize a block image while a guest is running.
4254 Either device or node-name must be set but not both.
4256 Arguments
4258 device: string (optional)
4259 the name of the device to get the image resized
4260 node-name: string (optional)
4262 graph node name to get the image resized (Since 2.0)
4263 size: int
4265 new image size in bytes
4266 Returns
4268 • nothing on success
4269 • If device is not a valid block device, DeviceNotFound
4271 Since
4273 0.14
4274 Example
4276 -> { "execute": "block_resize",
4277 "arguments": { "device": "scratch", "size": 1073741824 } }
4278 <- { "return": {} }
4279 NewImageMode (Enum)
4281 An enumeration that tells QEMU how to set the backing file path in a
4282 new image file.
4283 Values
4285 existing
4286 QEMU should look for an existing image file.
4287 absolute-paths
4289 QEMU should create a new image with absolute paths for the back‐
4290 ing file. If there is no backing file available, the new image
4291 will not be backed either.
4292 Since
4294 1.1
4295 BlockdevSnapshotSync (Object)
4297 Either device or node-name must be set but not both.
4298 Members
4300 device: string (optional)
4301 the name of the device to take a snapshot of.
4302 node-name: string (optional)
4304 graph node name to generate the snapshot from (Since 2.0)
4305 snapshot-file: string
4307 the target of the new overlay image. If the file exists, or if
4308 it is a device, the overlay will be created in the existing
4309 file/device. Otherwise, a new file will be created.
4310 snapshot-node-name: string (optional)
4312 the graph node name of the new image (Since 2.0)
4313 format: string (optional)
4315 the format of the overlay image, default is 'qcow2'.
4316 mode: NewImageMode (optional)
4318 whether and how QEMU should create a new image, default is 'ab‐
4319 solute-paths'.
4320 BlockdevSnapshot (Object)
4322 Members
4323 node: string
4324 device or node name that will have a snapshot taken.
4325 overlay: string
4327 reference to the existing block device that will become the
4328 overlay of node, as part of taking the snapshot. It must not
4329 have a current backing file (this can be achieved by passing
4330 "backing": null to blockdev-add).
4331 Since
4333 2.5
4334 BackupPerf (Object)
4336 Optional parameters for backup. These parameters don't affect function‐
4337 ality, but may significantly affect performance.
4338 Members
4340 use-copy-range: boolean (optional)
4341 Use copy offloading. Default false.
4342 max-workers: int (optional)
4344 Maximum number of parallel requests for the sustained background
4345 copying process. Doesn't influence copy-before-write operations.
4346 Default 64.
4347 max-chunk: int (optional)
4349 Maximum request length for the sustained background copying
4350 process. Doesn't influence copy-before-write operations. 0
4351 means unlimited. If max-chunk is non-zero then it should not be
4352 less than job cluster size which is calculated as maximum of
4353 target image cluster size and 64k. Default 0.
4354 Since
4356 6.0
4357 BackupCommon (Object)
4359 Members
4360 job-id: string (optional)
4361 identifier for the newly-created block job. If omitted, the de‐
4362 vice name will be used. (Since 2.7)
4363 device: string
4365 the device name or node-name of a root node which should be
4366 copied.
4367 sync: MirrorSyncMode
4369 what parts of the disk image should be copied to the destination
4370 (all the disk, only the sectors allocated in the topmost image,
4371 from a dirty bitmap, or only new I/O).
4372 speed: int (optional)
4374 the maximum speed, in bytes per second. The default is 0, for
4375 unlimited.
4376 bitmap: string (optional)
4378 The name of a dirty bitmap to use. Must be present if sync is
4379 "bitmap" or "incremental". Can be present if sync is "full" or
4380 "top". Must not be present otherwise. (Since 2.4
4381 (drive-backup), 3.1 (blockdev-backup))
4382 bitmap-mode: BitmapSyncMode (optional)
4384 Specifies the type of data the bitmap should contain after the
4385 operation concludes. Must be present if a bitmap was provided,
4386 Must NOT be present otherwise. (Since 4.2)
4387 compress: boolean (optional)
4389 true to compress data, if the target format supports it. (de‐
4390 fault: false) (since 2.8)
4391 on-source-error: BlockdevOnError (optional)
4393 the action to take on an error on the source, default 'report'.
4394 'stop' and 'enospc' can only be used if the block device sup‐
4395 ports io-status (see BlockInfo).
4396 on-target-error: BlockdevOnError (optional)
4398 the action to take on an error on the target, default 'report'
4399 (no limitations, since this applies to a different block device
4400 than device).
4401 auto-finalize: boolean (optional)
4403 When false, this job will wait in a PENDING state after it has
4404 finished its work, waiting for block-job-finalize before making
4405 any block graph changes. When true, this job will automatically
4406 perform its abort or commit actions. Defaults to true. (Since
4407 2.12)
4408 auto-dismiss: boolean (optional)
4410 When false, this job will wait in a CONCLUDED state after it has
4411 completely ceased all work, and awaits block-job-dismiss. When
4412 true, this job will automatically disappear from the query list
4413 without user intervention. Defaults to true. (Since 2.12)
4414 filter-node-name: string (optional)
4416 the node name that should be assigned to the filter driver that
4417 the backup job inserts into the graph above node specified by
4418 drive. If this option is not given, a node name is autogener‐
4419 ated. (Since: 4.2)
4420 x-perf: BackupPerf (optional)
4422 Performance options. (Since 6.0)
4423 Features
4425 unstable
4426 Member x-perf is experimental.
4427 Note
4429 on-source-error and on-target-error only affect background I/O. If an
4430 error occurs during a guest write request, the device's rerror/werror
4431 actions will be used.
4432 Since
4434 4.2
4435 DriveBackup (Object)
4437 Members
4438 target: string
4439 the target of the new image. If the file exists, or if it is a
4440 device, the existing file/device will be used as the new desti‐
4441 nation. If it does not exist, a new file will be created.
4442 format: string (optional)
4444 the format of the new destination, default is to probe if mode
4445 is 'existing', else the format of the source
4446 mode: NewImageMode (optional)
4448 whether and how QEMU should create a new image, default is 'ab‐
4449 solute-paths'.
4450 The members of BackupCommon
4452 Since
4454 1.6
4455 BlockdevBackup (Object)
4457 Members
4458 target: string
4459 the device name or node-name of the backup target node.
4460 The members of BackupCommon
4462 Since
4464 2.3
4465 blockdev-snapshot-sync (Command)
4467 Takes a synchronous snapshot of a block device.
4468 For the arguments, see the documentation of BlockdevSnapshotSync.
4470 Returns
4472 • nothing on success
4473 • If device is not a valid block device, DeviceNotFound
4475 Since
4477 0.14
4478 Example
4480 -> { "execute": "blockdev-snapshot-sync",
4481 "arguments": { "device": "ide-hd0",
4482 "snapshot-file":
4483 "/some/place/my-image",
4484 "format": "qcow2" } }
4485 <- { "return": {} }
4486 blockdev-snapshot (Command)
4488 Takes a snapshot of a block device.
4489 Take a snapshot, by installing 'node' as the backing image of 'over‐
4491 lay'. Additionally, if 'node' is associated with a block device, the
4492 block device changes to using 'overlay' as its new active image.
4493 For the arguments, see the documentation of BlockdevSnapshot.
4495 Features
4497 allow-write-only-overlay
4498 If present, the check whether this operation is safe was relaxed
4499 so that it can be used to change backing file of a destination
4500 of a blockdev-mirror. (since 5.0)
4501 Since
4503 2.5
4504 Example
4506 -> { "execute": "blockdev-add",
4507 "arguments": { "driver": "qcow2",
4508 "node-name": "node1534",
4509 "file": { "driver": "file",
4510 "filename": "hd1.qcow2" },
4511 "backing": null } }
4512 <- { "return": {} }
4514 -> { "execute": "blockdev-snapshot",
4516 "arguments": { "node": "ide-hd0",
4517 "overlay": "node1534" } }
4518 <- { "return": {} }
4519 change-backing-file (Command)
4521 Change the backing file in the image file metadata. This does not
4522 cause QEMU to reopen the image file to reparse the backing filename (it
4523 may, however, perform a reopen to change permissions from r/o -> r/w ->
4524 r/o, if needed). The new backing file string is written into the image
4525 file metadata, and the QEMU internal strings are updated.
4526 Arguments
4528 image-node-name: string
4529 The name of the block driver state node of the image to modify.
4530 The "device" argument is used to verify "image-node-name" is in
4531 the chain described by "device".
4532 device: string
4534 The device name or node-name of the root node that owns im‐
4535 age-node-name.
4536 backing-file: string
4538 The string to write as the backing file. This string is not
4539 validated, so care should be taken when specifying the string or
4540 the image chain may not be able to be reopened again.
4541 Returns
4543 • Nothing on success
4544 • If "device" does not exist or cannot be determined, DeviceNotFound
4546 Since
4548 2.1
4549 block-commit (Command)
4551 Live commit of data from overlay image nodes into backing nodes - i.e.,
4552 writes data between 'top' and 'base' into 'base'.
4553 If top == base, that is an error. If top has no overlays on top of it,
4555 or if it is in use by a writer, the job will not be completed by it‐
4556 self. The user needs to complete the job with the block-job-complete
4557 command after getting the ready event. (Since 2.0)
4558 If the base image is smaller than top, then the base image will be re‐
4560 sized to be the same size as top. If top is smaller than the base im‐
4561 age, the base will not be truncated. If you want the base image size
4562 to match the size of the smaller top, you can safely truncate it your‐
4563 self once the commit operation successfully completes.
4564 Arguments
4566 job-id: string (optional)
4567 identifier for the newly-created block job. If omitted, the de‐
4568 vice name will be used. (Since 2.7)
4569 device: string
4571 the device name or node-name of a root node
4572 base-node: string (optional)
4574 The node name of the backing image to write data into. If not
4575 specified, this is the deepest backing image. (since: 3.1)
4576 base: string (optional)
4578 Same as base-node, except that it is a file name rather than a
4579 node name. This must be the exact filename string that was used
4580 to open the node; other strings, even if addressing the same
4581 file, are not accepted
4582 top-node: string (optional)
4584 The node name of the backing image within the image chain which
4585 contains the topmost data to be committed down. If not speci‐
4586 fied, this is the active layer. (since: 3.1)
4587 top: string (optional)
4589 Same as top-node, except that it is a file name rather than a
4590 node name. This must be the exact filename string that was used
4591 to open the node; other strings, even if addressing the same
4592 file, are not accepted
4593 backing-file: string (optional)
4595 The backing file string to write into the overlay image of
4596 'top'. If 'top' does not have an overlay image, or if 'top' is
4597 in use by a writer, specifying a backing file string is an er‐
4598 ror.
4599 This filename is not validated. If a pathname string is such
4601 that it cannot be resolved by QEMU, that means that subsequent
4602 QMP or HMP commands must use node-names for the image in ques‐
4603 tion, as filename lookup methods will fail.
4604 If not specified, QEMU will automatically determine the backing
4606 file string to use, or error out if there is no obvious choice.
4607 Care should be taken when specifying the string, to specify a
4608 valid filename or protocol. (Since 2.1)
4609 speed: int (optional)
4611 the maximum speed, in bytes per second
4612 on-error: BlockdevOnError (optional)
4614 the action to take on an error. 'ignore' means that the request
4615 should be retried. (default: report; Since: 5.0)
4616 filter-node-name: string (optional)
4618 the node name that should be assigned to the filter driver that
4619 the commit job inserts into the graph above top. If this option
4620 is not given, a node name is autogenerated. (Since: 2.9)
4621 auto-finalize: boolean (optional)
4623 When false, this job will wait in a PENDING state after it has
4624 finished its work, waiting for block-job-finalize before making
4625 any block graph changes. When true, this job will automatically
4626 perform its abort or commit actions. Defaults to true. (Since
4627 3.1)
4628 auto-dismiss: boolean (optional)
4630 When false, this job will wait in a CONCLUDED state after it has
4631 completely ceased all work, and awaits block-job-dismiss. When
4632 true, this job will automatically disappear from the query list
4633 without user intervention. Defaults to true. (Since 3.1)
4634 Features
4636 deprecated
4637 Members base and top are deprecated. Use base-node and top-node
4638 instead.
4639 Returns
4641 • Nothing on success
4642 • If device does not exist, DeviceNotFound
4644 • Any other error returns a GenericError.
4646 Since
4648 1.3
4649 Example
4651 -> { "execute": "block-commit",
4652 "arguments": { "device": "virtio0",
4653 "top": "/tmp/snap1.qcow2" } }
4654 <- { "return": {} }
4655 drive-backup (Command)
4657 Start a point-in-time copy of a block device to a new destination. The
4658 status of ongoing drive-backup operations can be checked with
4659 query-block-jobs where the BlockJobInfo.type field has the value
4660 'backup'. The operation can be stopped before it has completed using
4661 the block-job-cancel command.
4662 Arguments
4664 The members of DriveBackup
4665 Features
4667 deprecated
4668 This command is deprecated. Use blockdev-backup instead.
4669 Returns
4671 • nothing on success
4672 • If device is not a valid block device, GenericError
4674 Since
4676 1.6
4677 Example
4679 -> { "execute": "drive-backup",
4680 "arguments": { "device": "drive0",
4681 "sync": "full",
4682 "target": "backup.img" } }
4683 <- { "return": {} }
4684 blockdev-backup (Command)
4686 Start a point-in-time copy of a block device to a new destination. The
4687 status of ongoing blockdev-backup operations can be checked with
4688 query-block-jobs where the BlockJobInfo.type field has the value
4689 'backup'. The operation can be stopped before it has completed using
4690 the block-job-cancel command.
4691 Arguments
4693 The members of BlockdevBackup
4694 Returns
4696 • nothing on success
4697 • If device is not a valid block device, DeviceNotFound
4699 Since
4701 2.3
4702 Example
4704 -> { "execute": "blockdev-backup",
4705 "arguments": { "device": "src-id",
4706 "sync": "full",
4707 "target": "tgt-id" } }
4708 <- { "return": {} }
4709 query-named-block-nodes (Command)
4711 Get the named block driver list
4712 Arguments
4714 flat: boolean (optional)
4715 Omit the nested data about backing image ("backing-image" key)
4716 if true. Default is false (Since 5.0)
4717 Returns
4719 the list of BlockDeviceInfo
4720 Since
4722 2.0
4723 Example
4725 -> { "execute": "query-named-block-nodes" }
4726 <- { "return": [ { "ro":false,
4727 "drv":"qcow2",
4728 "encrypted":false,
4729 "file":"disks/test.qcow2",
4730 "node-name": "my-node",
4731 "backing_file_depth":1,
4732 "detect_zeroes":"off",
4733 "bps":1000000,
4734 "bps_rd":0,
4735 "bps_wr":0,
4736 "iops":1000000,
4737 "iops_rd":0,
4738 "iops_wr":0,
4739 "bps_max": 8000000,
4740 "bps_rd_max": 0,
4741 "bps_wr_max": 0,
4742 "iops_max": 0,
4743 "iops_rd_max": 0,
4744 "iops_wr_max": 0,
4745 "iops_size": 0,
4746 "write_threshold": 0,
4747 "image":{
4748 "filename":"disks/test.qcow2",
4749 "format":"qcow2",
4750 "virtual-size":2048000,
4751 "backing_file":"base.qcow2",
4752 "full-backing-filename":"disks/base.qcow2",
4753 "backing-filename-format":"qcow2",
4754 "snapshots":[
4755 {
4756 "id": "1",
4757 "name": "snapshot1",
4758 "vm-state-size": 0,
4759 "date-sec": 10000200,
4760 "date-nsec": 12,
4761 "vm-clock-sec": 206,
4762 "vm-clock-nsec": 30
4763 }
4764 ],
4765 "backing-image":{
4766 "filename":"disks/base.qcow2",
4767 "format":"qcow2",
4768 "virtual-size":2048000
4769 }
4770 } } ] }
4771 XDbgBlockGraphNodeType (Enum)
4773 Values
4774 block-backend
4775 corresponds to BlockBackend
4776 block-job
4778 corresponds to BlockJob
4779 block-driver
4781 corresponds to BlockDriverState
4782 Since
4784 4.0
4785 XDbgBlockGraphNode (Object)
4787 Members
4788 id: int
4789 Block graph node identifier. This id is generated only for x-de‐
4790 bug-query-block-graph and does not relate to any other identi‐
4791 fiers in Qemu.
4792 type: XDbgBlockGraphNodeType
4794 Type of graph node. Can be one of block-backend, block-job or
4795 block-driver-state.
4796 name: string
4798 Human readable name of the node. Corresponds to node-name for
4799 block-driver-state nodes; is not guaranteed to be unique in the
4800 whole graph (with block-jobs and block-backends).
4801 Since
4803 4.0
4804 BlockPermission (Enum)
4806 Enum of base block permissions.
4807 Values
4809 consistent-read
4810 A user that has the "permission" of consistent reads is guaran‐
4811 teed that their view of the contents of the block device is com‐
4812 plete and self-consistent, representing the contents of a disk
4813 at a specific point. For most block devices (including their
4814 backing files) this is true, but the property cannot be main‐
4815 tained in a few situations like for intermediate nodes of a com‐
4816 mit block job.
4817 write This permission is required to change the visible disk contents.
4819 write-unchanged
4821 This permission (which is weaker than BLK_PERM_WRITE) is both
4822 enough and required for writes to the block node when the caller
4823 promises that the visible disk content doesn't change. As the
4824 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
4825 cient to perform an unchanging write.
4826 resize This permission is required to change the size of a block node.
4828 Since
4830 4.0
4831 XDbgBlockGraphEdge (Object)
4833 Block Graph edge description for x-debug-query-block-graph.
4834 Members
4836 parent: int
4837 parent id
4838 child: int
4840 child id
4841 name: string
4843 name of the relation (examples are 'file' and 'backing')
4844 perm: array of BlockPermission
4846 granted permissions for the parent operating on the child
4847 shared-perm: array of BlockPermission
4849 permissions that can still be granted to other users of the
4850 child while it is still attached to this parent
4851 Since
4853 4.0
4854 XDbgBlockGraph (Object)
4856 Block Graph - list of nodes and list of edges.
4857 Members
4859 nodes: array of XDbgBlockGraphNode
4860 Not documented
4861 edges: array of XDbgBlockGraphEdge
4863 Not documented
4864 Since
4866 4.0
4867 x-debug-query-block-graph (Command)
4869 Get the block graph.
4870 Features
4872 unstable
4873 This command is meant for debugging.
4874 Since
4876 4.0
4877 drive-mirror (Command)
4879 Start mirroring a block device's writes to a new destination. target
4880 specifies the target of the new image. If the file exists, or if it is
4881 a device, it will be used as the new destination for writes. If it does
4882 not exist, a new file will be created. format specifies the format of
4883 the mirror image, default is to probe if mode='existing', else the for‐
4884 mat of the source.
4885 Arguments
4887 The members of DriveMirror
4888 Returns
4890 • nothing on success
4891 • If device is not a valid block device, GenericError
4893 Since
4895 1.3
4896 Example
4898 -> { "execute": "drive-mirror",
4899 "arguments": { "device": "ide-hd0",
4900 "target": "/some/place/my-image",
4901 "sync": "full",
4902 "format": "qcow2" } }
4903 <- { "return": {} }
4904 DriveMirror (Object)
4906 A set of parameters describing drive mirror setup.
4907 Members
4909 job-id: string (optional)
4910 identifier for the newly-created block job. If omitted, the de‐
4911 vice name will be used. (Since 2.7)
4912 device: string
4914 the device name or node-name of a root node whose writes should
4915 be mirrored.
4916 target: string
4918 the target of the new image. If the file exists, or if it is a
4919 device, the existing file/device will be used as the new desti‐
4920 nation. If it does not exist, a new file will be created.
4921 format: string (optional)
4923 the format of the new destination, default is to probe if mode
4924 is 'existing', else the format of the source
4925 node-name: string (optional)
4927 the new block driver state node name in the graph (Since 2.1)
4928 replaces: string (optional)
4930 with sync=full graph node name to be replaced by the new image
4931 when a whole image copy is done. This can be used to repair bro‐
4932 ken Quorum files. By default, device is replaced, although im‐
4933 plicitly created filters on it are kept. (Since 2.1)
4934 mode: NewImageMode (optional)
4936 whether and how QEMU should create a new image, default is 'ab‐
4937 solute-paths'.
4938 speed: int (optional)
4940 the maximum speed, in bytes per second
4941 sync: MirrorSyncMode
4943 what parts of the disk image should be copied to the destination
4944 (all the disk, only the sectors allocated in the topmost image,
4945 or only new I/O).
4946 granularity: int (optional)
4948 granularity of the dirty bitmap, default is 64K if the image
4949 format doesn't have clusters, 4K if the clusters are smaller
4950 than that, else the cluster size. Must be a power of 2 between
4951 512 and 64M (since 1.4).
4952 buf-size: int (optional)
4954 maximum amount of data in flight from source to target (since
4955 1.4).
4956 on-source-error: BlockdevOnError (optional)
4958 the action to take on an error on the source, default 'report'.
4959 'stop' and 'enospc' can only be used if the block device sup‐
4960 ports io-status (see BlockInfo).
4961 on-target-error: BlockdevOnError (optional)
4963 the action to take on an error on the target, default 'report'
4964 (no limitations, since this applies to a different block device
4965 than device).
4966 unmap: boolean (optional)
4968 Whether to try to unmap target sectors where source has only
4969 zero. If true, and target unallocated sectors will read as zero,
4970 target image sectors will be unmapped; otherwise, zeroes will be
4971 written. Both will result in identical contents. Default is
4972 true. (Since 2.4)
4973 copy-mode: MirrorCopyMode (optional)
4975 when to copy data to the destination; defaults to 'background'
4976 (Since: 3.0)
4977 auto-finalize: boolean (optional)
4979 When false, this job will wait in a PENDING state after it has
4980 finished its work, waiting for block-job-finalize before making
4981 any block graph changes. When true, this job will automatically
4982 perform its abort or commit actions. Defaults to true. (Since
4983 3.1)
4984 auto-dismiss: boolean (optional)
4986 When false, this job will wait in a CONCLUDED state after it has
4987 completely ceased all work, and awaits block-job-dismiss. When
4988 true, this job will automatically disappear from the query list
4989 without user intervention. Defaults to true. (Since 3.1)
4990 Since
4992 1.3
4993 BlockDirtyBitmap (Object)
4995 Members
4996 node: string
4997 name of device/node which the bitmap is tracking
4998 name: string
5000 name of the dirty bitmap
5001 Since
5003 2.4
5004 BlockDirtyBitmapAdd (Object)
5006 Members
5007 node: string
5008 name of device/node which the bitmap is tracking
5009 name: string
5011 name of the dirty bitmap (must be less than 1024 bytes)
5012 granularity: int (optional)
5014 the bitmap granularity, default is 64k for block-dirty-bit‐
5015 map-add
5016 persistent: boolean (optional)
5018 the bitmap is persistent, i.e. it will be saved to the corre‐
5019 sponding block device image file on its close. For now only
5020 Qcow2 disks support persistent bitmaps. Default is false for
5021 block-dirty-bitmap-add. (Since: 2.10)
5022 disabled: boolean (optional)
5024 the bitmap is created in the disabled state, which means that it
5025 will not track drive changes. The bitmap may be enabled with
5026 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
5027 Since
5029 2.4
5030 BlockDirtyBitmapMergeSource (Alternate)
5032 Members
5033 local: string
5034 name of the bitmap, attached to the same node as target bitmap.
5035 external: BlockDirtyBitmap
5037 bitmap with specified node
5038 Since
5040 4.1
5041 BlockDirtyBitmapMerge (Object)
5043 Members
5044 node: string
5045 name of device/node which the target bitmap is tracking
5046 target: string
5048 name of the destination dirty bitmap
5049 bitmaps: array of BlockDirtyBitmapMergeSource
5051 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
5052 ified BlockDirtyBitmap elements. The latter are supported since
5053 4.1.
5054 Since
5056 4.0
5057 block-dirty-bitmap-add (Command)
5059 Create a dirty bitmap with a name on the node, and start tracking the
5060 writes.
5061 Returns
5063 • nothing on success
5064 • If node is not a valid block device or node, DeviceNotFound
5066 • If name is already taken, GenericError with an explanation
5068 Since
5070 2.4
5071 Example
5073 -> { "execute": "block-dirty-bitmap-add",
5074 "arguments": { "node": "drive0", "name": "bitmap0" } }
5075 <- { "return": {} }
5076 block-dirty-bitmap-remove (Command)
5078 Stop write tracking and remove the dirty bitmap that was created with
5079 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
5080 storage too.
5081 Returns
5083 • nothing on success
5084 • If node is not a valid block device or node, DeviceNotFound
5086 • If name is not found, GenericError with an explanation
5088 • if name is frozen by an operation, GenericError
5090 Since
5092 2.4
5093 Example
5095 -> { "execute": "block-dirty-bitmap-remove",
5096 "arguments": { "node": "drive0", "name": "bitmap0" } }
5097 <- { "return": {} }
5098 block-dirty-bitmap-clear (Command)
5100 Clear (reset) a dirty bitmap on the device, so that an incremental
5101 backup from this point in time forward will only backup clusters modi‐
5102 fied after this clear operation.
5103 Returns
5105 • nothing on success
5106 • If node is not a valid block device, DeviceNotFound
5108 • If name is not found, GenericError with an explanation
5110 Since
5112 2.4
5113 Example
5115 -> { "execute": "block-dirty-bitmap-clear",
5116 "arguments": { "node": "drive0", "name": "bitmap0" } }
5117 <- { "return": {} }
5118 block-dirty-bitmap-enable (Command)
5120 Enables a dirty bitmap so that it will begin tracking disk changes.
5121 Returns
5123 • nothing on success
5124 • If node is not a valid block device, DeviceNotFound
5126 • If name is not found, GenericError with an explanation
5128 Since
5130 4.0
5131 Example
5133 -> { "execute": "block-dirty-bitmap-enable",
5134 "arguments": { "node": "drive0", "name": "bitmap0" } }
5135 <- { "return": {} }
5136 block-dirty-bitmap-disable (Command)
5138 Disables a dirty bitmap so that it will stop tracking disk changes.
5139 Returns
5141 • nothing on success
5142 • If node is not a valid block device, DeviceNotFound
5144 • If name is not found, GenericError with an explanation
5146 Since
5148 4.0
5149 Example
5151 -> { "execute": "block-dirty-bitmap-disable",
5152 "arguments": { "node": "drive0", "name": "bitmap0" } }
5153 <- { "return": {} }
5154 block-dirty-bitmap-merge (Command)
5156 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
5157 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
5158 as the target bitmap. Any bits already set in target will still be set
5159 after the merge, i.e., this operation does not clear the target. On
5160 error, target is unchanged.
5161 The resulting bitmap will count as dirty any clusters that were dirty
5163 in any of the source bitmaps. This can be used to achieve backup check‐
5164 points, or in simpler usages, to copy bitmaps.
5165 Returns
5167 • nothing on success
5168 • If node is not a valid block device, DeviceNotFound
5170 • If any bitmap in bitmaps or target is not found, GenericError
5172 • If any of the bitmaps have different sizes or granularities, Gener‐
5174 icError
5175 Since
5177 4.0
5178 Example
5180 -> { "execute": "block-dirty-bitmap-merge",
5181 "arguments": { "node": "drive0", "target": "bitmap0",
5182 "bitmaps": ["bitmap1"] } }
5183 <- { "return": {} }
5184 BlockDirtyBitmapSha256 (Object)
5186 SHA256 hash of dirty bitmap data
5187 Members
5189 sha256: string
5190 ASCII representation of SHA256 bitmap hash
5191 Since
5193 2.10
5194 x-debug-block-dirty-bitmap-sha256 (Command)
5196 Get bitmap SHA256.
5197 Features
5199 unstable
5200 This command is meant for debugging.
5201 Returns
5203 • BlockDirtyBitmapSha256 on success
5204 • If node is not a valid block device, DeviceNotFound
5206 • If name is not found or if hashing has failed, GenericError with an
5208 explanation
5209 Since
5211 2.10
5212 blockdev-mirror (Command)
5214 Start mirroring a block device's writes to a new destination.
5215 Arguments
5217 job-id: string (optional)
5218 identifier for the newly-created block job. If omitted, the de‐
5219 vice name will be used. (Since 2.7)
5220 device: string
5222 The device name or node-name of a root node whose writes should
5223 be mirrored.
5224 target: string
5226 the id or node-name of the block device to mirror to. This
5227 mustn't be attached to guest.
5228 replaces: string (optional)
5230 with sync=full graph node name to be replaced by the new image
5231 when a whole image copy is done. This can be used to repair bro‐
5232 ken Quorum files. By default, device is replaced, although im‐
5233 plicitly created filters on it are kept.
5234 speed: int (optional)
5236 the maximum speed, in bytes per second
5237 sync: MirrorSyncMode
5239 what parts of the disk image should be copied to the destination
5240 (all the disk, only the sectors allocated in the topmost image,
5241 or only new I/O).
5242 granularity: int (optional)
5244 granularity of the dirty bitmap, default is 64K if the image
5245 format doesn't have clusters, 4K if the clusters are smaller
5246 than that, else the cluster size. Must be a power of 2 between
5247 512 and 64M
5248 buf-size: int (optional)
5250 maximum amount of data in flight from source to target
5251 on-source-error: BlockdevOnError (optional)
5253 the action to take on an error on the source, default 'report'.
5254 'stop' and 'enospc' can only be used if the block device sup‐
5255 ports io-status (see BlockInfo).
5256 on-target-error: BlockdevOnError (optional)
5258 the action to take on an error on the target, default 'report'
5259 (no limitations, since this applies to a different block device
5260 than device).
5261 filter-node-name: string (optional)
5263 the node name that should be assigned to the filter driver that
5264 the mirror job inserts into the graph above device. If this op‐
5265 tion is not given, a node name is autogenerated. (Since: 2.9)
5266 copy-mode: MirrorCopyMode (optional)
5268 when to copy data to the destination; defaults to 'background'
5269 (Since: 3.0)
5270 auto-finalize: boolean (optional)
5272 When false, this job will wait in a PENDING state after it has
5273 finished its work, waiting for block-job-finalize before making
5274 any block graph changes. When true, this job will automatically
5275 perform its abort or commit actions. Defaults to true. (Since
5276 3.1)
5277 auto-dismiss: boolean (optional)
5279 When false, this job will wait in a CONCLUDED state after it has
5280 completely ceased all work, and awaits block-job-dismiss. When
5281 true, this job will automatically disappear from the query list
5282 without user intervention. Defaults to true. (Since 3.1)
5283 Returns
5285 nothing on success.
5286 Since
5288 2.6
5289 Example
5291 -> { "execute": "blockdev-mirror",
5292 "arguments": { "device": "ide-hd0",
5293 "target": "target0",
5294 "sync": "full" } }
5295 <- { "return": {} }
5296 BlockIOThrottle (Object)
5298 A set of parameters describing block throttling.
5299 Members
5301 device: string (optional)
5302 Block device name
5303 id: string (optional)
5305 The name or QOM path of the guest device (since: 2.8)
5306 bps: int
5308 total throughput limit in bytes per second
5309 bps_rd: int
5311 read throughput limit in bytes per second
5312 bps_wr: int
5314 write throughput limit in bytes per second
5315 iops: int
5317 total I/O operations per second
5318 iops_rd: int
5320 read I/O operations per second
5321 iops_wr: int
5323 write I/O operations per second
5324 bps_max: int (optional)
5326 total throughput limit during bursts, in bytes (Since 1.7)
5327 bps_rd_max: int (optional)
5329 read throughput limit during bursts, in bytes (Since 1.7)
5330 bps_wr_max: int (optional)
5332 write throughput limit during bursts, in bytes (Since 1.7)
5333 iops_max: int (optional)
5335 total I/O operations per second during bursts, in bytes (Since
5336 1.7)
5337 iops_rd_max: int (optional)
5339 read I/O operations per second during bursts, in bytes (Since
5340 1.7)
5341 iops_wr_max: int (optional)
5343 write I/O operations per second during bursts, in bytes (Since
5344 1.7)
5345 bps_max_length: int (optional)
5347 maximum length of the bps_max burst period, in seconds. It must
5348 only be set if bps_max is set as well. Defaults to 1. (Since
5349 2.6)
5350 bps_rd_max_length: int (optional)
5352 maximum length of the bps_rd_max burst period, in seconds. It
5353 must only be set if bps_rd_max is set as well. Defaults to 1.
5354 (Since 2.6)
5355 bps_wr_max_length: int (optional)
5357 maximum length of the bps_wr_max burst period, in seconds. It
5358 must only be set if bps_wr_max is set as well. Defaults to 1.
5359 (Since 2.6)
5360 iops_max_length: int (optional)
5362 maximum length of the iops burst period, in seconds. It must
5363 only be set if iops_max is set as well. Defaults to 1. (Since
5364 2.6)
5365 iops_rd_max_length: int (optional)
5367 maximum length of the iops_rd_max burst period, in seconds. It
5368 must only be set if iops_rd_max is set as well. Defaults to 1.
5369 (Since 2.6)
5370 iops_wr_max_length: int (optional)
5372 maximum length of the iops_wr_max burst period, in seconds. It
5373 must only be set if iops_wr_max is set as well. Defaults to 1.
5374 (Since 2.6)
5375 iops_size: int (optional)
5377 an I/O size in bytes (Since 1.7)
5378 group: string (optional)
5380 throttle group name (Since 2.4)
5381 Features
5383 deprecated
5384 Member device is deprecated. Use id instead.
5385 Since
5387 1.1
5388 ThrottleLimits (Object)
5390 Limit parameters for throttling. Since some limit combinations are il‐
5391 legal, limits should always be set in one transaction. All fields are
5392 optional. When setting limits, if a field is missing the current value
5393 is not changed.
5394 Members
5396 iops-total: int (optional)
5397 limit total I/O operations per second
5398 iops-total-max: int (optional)
5400 I/O operations burst
5401 iops-total-max-length: int (optional)
5403 length of the iops-total-max burst period, in seconds It must
5404 only be set if iops-total-max is set as well.
5405 iops-read: int (optional)
5407 limit read operations per second
5408 iops-read-max: int (optional)
5410 I/O operations read burst
5411 iops-read-max-length: int (optional)
5413 length of the iops-read-max burst period, in seconds It must
5414 only be set if iops-read-max is set as well.
5415 iops-write: int (optional)
5417 limit write operations per second
5418 iops-write-max: int (optional)
5420 I/O operations write burst
5421 iops-write-max-length: int (optional)
5423 length of the iops-write-max burst period, in seconds It must
5424 only be set if iops-write-max is set as well.
5425 bps-total: int (optional)
5427 limit total bytes per second
5428 bps-total-max: int (optional)
5430 total bytes burst
5431 bps-total-max-length: int (optional)
5433 length of the bps-total-max burst period, in seconds. It must
5434 only be set if bps-total-max is set as well.
5435 bps-read: int (optional)
5437 limit read bytes per second
5438 bps-read-max: int (optional)
5440 total bytes read burst
5441 bps-read-max-length: int (optional)
5443 length of the bps-read-max burst period, in seconds It must only
5444 be set if bps-read-max is set as well.
5445 bps-write: int (optional)
5447 limit write bytes per second
5448 bps-write-max: int (optional)
5450 total bytes write burst
5451 bps-write-max-length: int (optional)
5453 length of the bps-write-max burst period, in seconds It must
5454 only be set if bps-write-max is set as well.
5455 iops-size: int (optional)
5457 when limiting by iops max size of an I/O in bytes
5458 Since
5460 2.11
5461 ThrottleGroupProperties (Object)
5463 Properties for throttle-group objects.
5464 Members
5466 limits: ThrottleLimits (optional)
5467 limits to apply for this throttle group
5468 x-iops-total: int (optional)
5470 Not documented
5471 x-iops-total-max: int (optional)
5473 Not documented
5474 x-iops-total-max-length: int (optional)
5476 Not documented
5477 x-iops-read: int (optional)
5479 Not documented
5480 x-iops-read-max: int (optional)
5482 Not documented
5483 x-iops-read-max-length: int (optional)
5485 Not documented
5486 x-iops-write: int (optional)
5488 Not documented
5489 x-iops-write-max: int (optional)
5491 Not documented
5492 x-iops-write-max-length: int (optional)
5494 Not documented
5495 x-bps-total: int (optional)
5497 Not documented
5498 x-bps-total-max: int (optional)
5500 Not documented
5501 x-bps-total-max-length: int (optional)
5503 Not documented
5504 x-bps-read: int (optional)
5506 Not documented
5507 x-bps-read-max: int (optional)
5509 Not documented
5510 x-bps-read-max-length: int (optional)
5512 Not documented
5513 x-bps-write: int (optional)
5515 Not documented
5516 x-bps-write-max: int (optional)
5518 Not documented
5519 x-bps-write-max-length: int (optional)
5521 Not documented
5522 x-iops-size: int (optional)
5524 Not documented
5525 Features
5527 unstable
5528 All members starting with x- are aliases for the same key with‐
5529 out x- in the limits object. This is not a stable interface and
5530 may be removed or changed incompatibly in the future. Use lim‐
5531 its for a supported stable interface.
5532 Since
5534 2.11
5535 block-stream (Command)
5537 Copy data from a backing file into a block device.
5538 The block streaming operation is performed in the background until the
5540 entire backing file has been copied. This command returns immediately
5541 once streaming has started. The status of ongoing block streaming op‐
5542 erations can be checked with query-block-jobs. The operation can be
5543 stopped before it has completed using the block-job-cancel command.
5544 The node that receives the data is called the top image, can be located
5546 in any part of the chain (but always above the base image; see below)
5547 and can be specified using its device or node name. Earlier qemu ver‐
5548 sions only allowed 'device' to name the top level node; presence of the
5549 'base-node' parameter during introspection can be used as a witness of
5550 the enhanced semantics of 'device'.
5551 If a base file is specified then sectors are not copied from that base
5553 file and its backing chain. This can be used to stream a subset of the
5554 backing file chain instead of flattening the entire image. When
5555 streaming completes the image file will have the base file as its back‐
5556 ing file, unless that node was changed while the job was running. In
5557 that case, base's parent's backing (or filtered, whichever exists)
5558 child (i.e., base at the beginning of the job) will be the new backing
5559 file.
5560 On successful completion the image file is updated to drop the backing
5562 file and the BLOCK_JOB_COMPLETED event is emitted.
5563 In case device is a filter node, block-stream modifies the first
5565 non-filter overlay node below it to point to the new backing node in‐
5566 stead of modifying device itself.
5567 Arguments
5569 job-id: string (optional)
5570 identifier for the newly-created block job. If omitted, the de‐
5571 vice name will be used. (Since 2.7)
5572 device: string
5574 the device or node name of the top image
5575 base: string (optional)
5577 the common backing file name. It cannot be set if base-node or
5578 bottom is also set.
5579 base-node: string (optional)
5581 the node name of the backing file. It cannot be set if base or
5582 bottom is also set. (Since 2.8)
5583 bottom: string (optional)
5585 the last node in the chain that should be streamed into top. It
5586 cannot be set if base or base-node is also set. It cannot be
5587 filter node. (Since 6.0)
5588 backing-file: string (optional)
5590 The backing file string to write into the top image. This file‐
5591 name is not validated.
5592 If a pathname string is such that it cannot be resolved by QEMU,
5594 that means that subsequent QMP or HMP commands must use
5595 node-names for the image in question, as filename lookup methods
5596 will fail.
5597 If not specified, QEMU will automatically determine the backing
5599 file string to use, or error out if there is no obvious choice.
5600 Care should be taken when specifying the string, to specify a
5601 valid filename or protocol. (Since 2.1)
5602 speed: int (optional)
5604 the maximum speed, in bytes per second
5605 on-error: BlockdevOnError (optional)
5607 the action to take on an error (default report). 'stop' and
5608 'enospc' can only be used if the block device supports io-status
5609 (see BlockInfo). Since 1.3.
5610 filter-node-name: string (optional)
5612 the node name that should be assigned to the filter driver that
5613 the stream job inserts into the graph above device. If this op‐
5614 tion is not given, a node name is autogenerated. (Since: 6.0)
5615 auto-finalize: boolean (optional)
5617 When false, this job will wait in a PENDING state after it has
5618 finished its work, waiting for block-job-finalize before making
5619 any block graph changes. When true, this job will automatically
5620 perform its abort or commit actions. Defaults to true. (Since
5621 3.1)
5622 auto-dismiss: boolean (optional)
5624 When false, this job will wait in a CONCLUDED state after it has
5625 completely ceased all work, and awaits block-job-dismiss. When
5626 true, this job will automatically disappear from the query list
5627 without user intervention. Defaults to true. (Since 3.1)
5628 Returns
5630 • Nothing on success.
5631 • If device does not exist, DeviceNotFound.
5633 Since
5635 1.1
5636 Example
5638 -> { "execute": "block-stream",
5639 "arguments": { "device": "virtio0",
5640 "base": "/tmp/master.qcow2" } }
5641 <- { "return": {} }
5642 block-job-set-speed (Command)
5644 Set maximum speed for a background block operation.
5645 This command can only be issued when there is an active block job.
5647 Throttling can be disabled by setting the speed to 0.
5649 Arguments
5651 device: string
5652 The job identifier. This used to be a device name (hence the
5653 name of the parameter), but since QEMU 2.7 it can have other
5654 values.
5655 speed: int
5657 the maximum speed, in bytes per second, or 0 for unlimited. De‐
5658 faults to 0.
5659 Returns
5661 • Nothing on success
5662 • If no background operation is active on this device, DeviceNotActive
5664 Since
5666 1.1
5667 block-job-cancel (Command)
5669 Stop an active background block operation.
5670 This command returns immediately after marking the active background
5672 block operation for cancellation. It is an error to call this command
5673 if no operation is in progress.
5674 The operation will cancel as soon as possible and then emit the
5676 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
5677 ble when enumerated using query-block-jobs.
5678 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
5680 dicated (via the event BLOCK_JOB_READY) that the source and destination
5681 are synchronized, then the event triggered by this command changes to
5682 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
5683 destination now has a point-in-time copy tied to the time of the can‐
5684 cellation.
5685 For streaming, the image file retains its backing file unless the
5687 streaming operation happens to complete just as it is being cancelled.
5688 A new streaming operation can be started at a later time to finish
5689 copying all data from the backing file.
5690 Arguments
5692 device: string
5693 The job identifier. This used to be a device name (hence the
5694 name of the parameter), but since QEMU 2.7 it can have other
5695 values.
5696 force: boolean (optional)
5698 If true, and the job has already emitted the event
5699 BLOCK_JOB_READY, abandon the job immediately (even if it is
5700 paused) instead of waiting for the destination to complete its
5701 final synchronization (since 1.3)
5702 Returns
5704 • Nothing on success
5705 • If no background operation is active on this device, DeviceNotActive
5707 Since
5709 1.1
5710 block-job-pause (Command)
5712 Pause an active background block operation.
5713 This command returns immediately after marking the active background
5715 block operation for pausing. It is an error to call this command if no
5716 operation is in progress or if the job is already paused.
5717 The operation will pause as soon as possible. No event is emitted when
5719 the operation is actually paused. Cancelling a paused job automati‐
5720 cally resumes it.
5721 Arguments
5723 device: string
5724 The job identifier. This used to be a device name (hence the
5725 name of the parameter), but since QEMU 2.7 it can have other
5726 values.
5727 Returns
5729 • Nothing on success
5730 • If no background operation is active on this device, DeviceNotActive
5732 Since
5734 1.3
5735 block-job-resume (Command)
5737 Resume an active background block operation.
5738 This command returns immediately after resuming a paused background
5740 block operation. It is an error to call this command if no operation
5741 is in progress or if the job is not paused.
5742 This command also clears the error status of the job.
5744 Arguments
5746 device: string
5747 The job identifier. This used to be a device name (hence the
5748 name of the parameter), but since QEMU 2.7 it can have other
5749 values.
5750 Returns
5752 • Nothing on success
5753 • If no background operation is active on this device, DeviceNotActive
5755 Since
5757 1.3
5758 block-job-complete (Command)
5760 Manually trigger completion of an active background block operation.
5761 This is supported for drive mirroring, where it also switches the de‐
5762 vice to write to the target path only. The ability to complete is sig‐
5763 naled with a BLOCK_JOB_READY event.
5764 This command completes an active background block operation syn‐
5766 chronously. The ordering of this command's return with the
5767 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
5768 occurs during the processing of this command: 1) the command itself
5769 will fail; 2) the error will be processed according to the rerror/wer‐
5770 ror arguments that were specified when starting the operation.
5771 A cancelled or paused job cannot be completed.
5773 Arguments
5775 device: string
5776 The job identifier. This used to be a device name (hence the
5777 name of the parameter), but since QEMU 2.7 it can have other
5778 values.
5779 Returns
5781 • Nothing on success
5782 • If no background operation is active on this device, DeviceNotActive
5784 Since
5786 1.3
5787 block-job-dismiss (Command)
5789 For jobs that have already concluded, remove them from the
5790 block-job-query list. This command only needs to be run for jobs which
5791 were started with QEMU 2.12+ job lifetime management semantics.
5792 This command will refuse to operate on any job that has not yet reached
5794 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
5795 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
5796 still need to be used as appropriate.
5797 Arguments
5799 id: string
5800 The job identifier.
5801 Returns
5803 Nothing on success
5804 Since
5806 2.12
5807 block-job-finalize (Command)
5809 Once a job that has manual=true reaches the pending state, it can be
5810 instructed to finalize any graph changes and do any necessary cleanup
5811 via this command. For jobs in a transaction, instructing one job to
5812 finalize will force ALL jobs in the transaction to finalize, so it is
5813 only necessary to instruct a single member job to finalize.
5814 Arguments
5816 id: string
5817 The job identifier.
5818 Returns
5820 Nothing on success
5821 Since
5823 2.12
5824 BlockdevDiscardOptions (Enum)
5826 Determines how to handle discard requests.
5827 Values
5829 ignore Ignore the request
5830 unmap Forward as an unmap request
5832 Since
5834 2.9
5835 BlockdevDetectZeroesOptions (Enum)
5837 Describes the operation mode for the automatic conversion of plain zero
5838 writes by the OS to driver specific optimized zero write commands.
5839 Values
5841 off Disabled (default)
5842 on Enabled
5844 unmap Enabled and even try to unmap blocks if possible. This requires
5846 also that BlockdevDiscardOptions is set to unmap for this de‐
5847 vice.
5848 Since
5850 2.1
5851 BlockdevAioOptions (Enum)
5853 Selects the AIO backend to handle I/O requests
5854 Values
5856 threads
5857 Use qemu's thread pool
5858 native Use native AIO backend (only Linux and Windows)
5860 io_uring (If: CONFIG_LINUX_IO_URING)
5862 Use linux io_uring (since 5.0)
5863 Since
5865 2.9
5866 BlockdevCacheOptions (Object)
5868 Includes cache-related options for block devices
5869 Members
5871 direct: boolean (optional)
5872 enables use of O_DIRECT (bypass the host page cache; default:
5873 false)
5874 no-flush: boolean (optional)
5876 ignore any flush requests for the device (default: false)
5877 Since
5879 2.9
5880 BlockdevDriver (Enum)
5882 Drivers that are supported in block device operations.
5883 Values
5885 throttle
5886 Since 2.11
5887 nvme Since 2.12
5889 copy-on-read
5891 Since 3.0
5892 blklogwrites
5894 Since 3.0
5895 blkreplay
5897 Since 4.2
5898 compress
5900 Since 5.0
5901 copy-before-write
5903 Since 6.2
5904 snapshot-access
5906 Since 7.0
5907 blkdebug
5909 Not documented
5910 blkverify
5912 Not documented
5913 bochs Not documented
5915 cloop Not documented
5917 dmg Not documented
5919 file Not documented
5921 ftp Not documented
5923 ftps Not documented
5925 gluster
5927 Not documented
5928 host_cdrom (If: HAVE_HOST_BLOCK_DEVICE)
5930 Not documented
5931 host_device (If: HAVE_HOST_BLOCK_DEVICE)
5933 Not documented
5934 http Not documented
5936 https Not documented
5938 iscsi Not documented
5940 luks Not documented
5942 nbd Not documented
5944 nfs Not documented
5946 null-aio
5948 Not documented
5949 null-co
5951 Not documented
5952 parallels
5954 Not documented
5955 preallocate
5957 Not documented
5958 qcow Not documented
5960 qcow2 Not documented
5962 qed Not documented
5964 quorum Not documented
5966 raw Not documented
5968 rbd Not documented
5970 replication (If: CONFIG_REPLICATION)
5972 Not documented
5973 ssh Not documented
5975 vdi Not documented
5977 vhdx Not documented
5979 vmdk Not documented
5981 vpc Not documented
5983 vvfat Not documented
5985 Since
5987 2.9
5988 BlockdevOptionsFile (Object)
5990 Driver specific block device options for the file backend.
5991 Members
5993 filename: string
5994 path to the image file
5995 pr-manager: string (optional)
5997 the id for the object that will handle persistent reservations
5998 for this device (default: none, forward the commands via SG_IO;
5999 since 2.11)
6000 aio: BlockdevAioOptions (optional)
6002 AIO backend (default: threads) (since: 2.8)
6003 aio-max-batch: int (optional)
6005 maximum number of requests to batch together into a single sub‐
6006 mission in the AIO backend. The smallest value between this and
6007 the aio-max-batch value of the IOThread object is chosen. 0
6008 means that the AIO backend will handle it automatically. (de‐
6009 fault: 0, since 6.2)
6010 locking: OnOffAuto (optional)
6012 whether to enable file locking. If set to 'auto', only enable
6013 when Open File Descriptor (OFD) locking API is available (de‐
6014 fault: auto, since 2.10)
6015 drop-cache: boolean (optional) (If: CONFIG_LINUX)
6017 invalidate page cache during live migration. This prevents
6018 stale data on the migration destination with cache.direct=off.
6019 Currently only supported on Linux hosts. (default: on, since:
6020 4.0)
6021 x-check-cache-dropped: boolean (optional)
6023 whether to check that page cache was dropped on live migration.
6024 May cause noticeable delays if the image file is large, do not
6025 use in production. (default: off) (since: 3.0)
6026 Features
6028 dynamic-auto-read-only
6029 If present, enabled auto-read-only means that the driver will
6030 open the image read-only at first, dynamically reopen the image
6031 file read-write when the first writer is attached to the node
6032 and reopen read-only when the last writer is detached. This al‐
6033 lows giving QEMU write permissions only on demand when an opera‐
6034 tion actually needs write access.
6035 unstable
6037 Member x-check-cache-dropped is meant for debugging.
6038 Since
6040 2.9
6041 BlockdevOptionsNull (Object)
6043 Driver specific block device options for the null backend.
6044 Members
6046 size: int (optional)
6047 size of the device in bytes.
6048 latency-ns: int (optional)
6050 emulated latency (in nanoseconds) in processing requests. De‐
6051 fault to zero which completes requests immediately. (Since 2.4)
6052 read-zeroes: boolean (optional)
6054 if true, reads from the device produce zeroes; if false, the
6055 buffer is left unchanged. (default: false; since: 4.1)
6056 Since
6058 2.9
6059 BlockdevOptionsNVMe (Object)
6061 Driver specific block device options for the NVMe backend.
6062 Members
6064 device: string
6065 PCI controller address of the NVMe device in format hhhh:bb:ss.f
6066 (host:bus:slot.function)
6067 namespace: int
6069 namespace number of the device, starting from 1.
6070 Note that the PCI device must have been unbound from any host kernel
6071 driver before instructing QEMU to add the blockdev.
6072 Since
6074 2.12
6075 BlockdevOptionsVVFAT (Object)
6077 Driver specific block device options for the vvfat protocol.
6078 Members
6080 dir: string
6081 directory to be exported as FAT image
6082 fat-type: int (optional)
6084 FAT type: 12, 16 or 32
6085 floppy: boolean (optional)
6087 whether to export a floppy image (true) or partitioned hard disk
6088 (false; default)
6089 label: string (optional)
6091 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
6092 ditionally have some restrictions on labels, which are ignored
6093 by most operating systems. Defaults to "QEMU VVFAT". (since
6094 2.4)
6095 rw: boolean (optional)
6097 whether to allow write operations (default: false)
6098 Since
6100 2.9
6101 BlockdevOptionsGenericFormat (Object)
6103 Driver specific block device options for image format that have no op‐
6104 tion besides their data source.
6105 Members
6107 file: BlockdevRef
6108 reference to or definition of the data source block device
6109 Since
6111 2.9
6112 BlockdevOptionsLUKS (Object)
6114 Driver specific block device options for LUKS.
6115 Members
6117 key-secret: string (optional)
6118 the ID of a QCryptoSecret object providing the decryption key
6119 (since 2.6). Mandatory except when doing a metadata-only probe
6120 of the image.
6121 The members of BlockdevOptionsGenericFormat
6123 Since
6125 2.9
6126 BlockdevOptionsGenericCOWFormat (Object)
6128 Driver specific block device options for image format that have no op‐
6129 tion besides their data source and an optional backing file.
6130 Members
6132 backing: BlockdevRefOrNull (optional)
6133 reference to or definition of the backing file block device,
6134 null disables the backing file entirely. Defaults to the back‐
6135 ing file stored the image file.
6136 The members of BlockdevOptionsGenericFormat
6138 Since
6140 2.9
6141 Qcow2OverlapCheckMode (Enum)
6143 General overlap check modes.
6144 Values
6146 none Do not perform any checks
6147 constant
6149 Perform only checks which can be done in constant time and with‐
6150 out reading anything from disk
6151 cached Perform only checks which can be done without reading anything
6153 from disk
6154 all Perform all available overlap checks
6156 Since
6158 2.9
6159 Qcow2OverlapCheckFlags (Object)
6161 Structure of flags for each metadata structure. Setting a field to
6162 'true' makes qemu guard that structure against unintended overwriting.
6163 The default value is chosen according to the template given.
6164 Members
6166 template: Qcow2OverlapCheckMode (optional)
6167 Specifies a template mode which can be adjusted using the other
6168 flags, defaults to 'cached'
6169 bitmap-directory: boolean (optional)
6171 since 3.0
6172 main-header: boolean (optional)
6174 Not documented
6175 active-l1: boolean (optional)
6177 Not documented
6178 active-l2: boolean (optional)
6180 Not documented
6181 refcount-table: boolean (optional)
6183 Not documented
6184 refcount-block: boolean (optional)
6186 Not documented
6187 snapshot-table: boolean (optional)
6189 Not documented
6190 inactive-l1: boolean (optional)
6192 Not documented
6193 inactive-l2: boolean (optional)
6195 Not documented
6196 Since
6198 2.9
6199 Qcow2OverlapChecks (Alternate)
6201 Specifies which metadata structures should be guarded against unin‐
6202 tended overwriting.
6203 Members
6205 flags: Qcow2OverlapCheckFlags
6206 set of flags for separate specification of each metadata struc‐
6207 ture type
6208 mode: Qcow2OverlapCheckMode
6210 named mode which chooses a specific set of flags
6211 Since
6213 2.9
6214 BlockdevQcowEncryptionFormat (Enum)
6216 Values
6217 aes AES-CBC with plain64 initialization vectors
6218 Since
6220 2.10
6221 BlockdevQcowEncryption (Object)
6223 Members
6224 format: BlockdevQcowEncryptionFormat
6225 Not documented
6226 The members of QCryptoBlockOptionsQCow when format is "aes"
6228 Since
6230 2.10
6231 BlockdevOptionsQcow (Object)
6233 Driver specific block device options for qcow.
6234 Members
6236 encrypt: BlockdevQcowEncryption (optional)
6237 Image decryption options. Mandatory for encrypted images, except
6238 when doing a metadata-only probe of the image.
6239 The members of BlockdevOptionsGenericCOWFormat
6241 Since
6243 2.10
6244 BlockdevQcow2EncryptionFormat (Enum)
6246 Values
6247 aes AES-CBC with plain64 initialization vectors
6248 luks Not documented
6250 Since
6252 2.10
6253 BlockdevQcow2Encryption (Object)
6255 Members
6256 format: BlockdevQcow2EncryptionFormat
6257 Not documented
6258 The members of QCryptoBlockOptionsQCow when format is "aes"
6260 The members of QCryptoBlockOptionsLUKS when format is "luks"
6262 Since
6264 2.10
6265 BlockdevOptionsPreallocate (Object)
6267 Filter driver intended to be inserted between format and protocol node
6268 and do preallocation in protocol node on write.
6269 Members
6271 prealloc-align: int (optional)
6272 on preallocation, align file length to this number, default
6273 1048576 (1M)
6274 prealloc-size: int (optional)
6276 how much to preallocate, default 134217728 (128M)
6277 The members of BlockdevOptionsGenericFormat
6279 Since
6281 6.0
6282 BlockdevOptionsQcow2 (Object)
6284 Driver specific block device options for qcow2.
6285 Members
6287 lazy-refcounts: boolean (optional)
6288 whether to enable the lazy refcounts feature (default is taken
6289 from the image file)
6290 pass-discard-request: boolean (optional)
6292 whether discard requests to the qcow2 device should be forwarded
6293 to the data source
6294 pass-discard-snapshot: boolean (optional)
6296 whether discard requests for the data source should be issued
6297 when a snapshot operation (e.g. deleting a snapshot) frees
6298 clusters in the qcow2 file
6299 pass-discard-other: boolean (optional)
6301 whether discard requests for the data source should be issued on
6302 other occasions where a cluster gets freed
6303 overlap-check: Qcow2OverlapChecks (optional)
6305 which overlap checks to perform for writes to the image, de‐
6306 faults to 'cached' (since 2.2)
6307 cache-size: int (optional)
6309 the maximum total size of the L2 table and refcount block caches
6310 in bytes (since 2.2)
6311 l2-cache-size: int (optional)
6313 the maximum size of the L2 table cache in bytes (since 2.2)
6314 l2-cache-entry-size: int (optional)
6316 the size of each entry in the L2 cache in bytes. It must be a
6317 power of two between 512 and the cluster size. The default value
6318 is the cluster size (since 2.12)
6319 refcount-cache-size: int (optional)
6321 the maximum size of the refcount block cache in bytes (since
6322 2.2)
6323 cache-clean-interval: int (optional)
6325 clean unused entries in the L2 and refcount caches. The interval
6326 is in seconds. The default value is 600 on supporting platforms,
6327 and 0 on other platforms. 0 disables this feature. (since 2.5)
6328 encrypt: BlockdevQcow2Encryption (optional)
6330 Image decryption options. Mandatory for encrypted images, except
6331 when doing a metadata-only probe of the image. (since 2.10)
6332 data-file: BlockdevRef (optional)
6334 reference to or definition of the external data file. This may
6335 only be specified for images that require an external data file.
6336 If it is not specified for such an image, the data file name is
6337 loaded from the image file. (since 4.0)
6338 The members of BlockdevOptionsGenericCOWFormat
6340 Since
6342 2.9
6343 SshHostKeyCheckMode (Enum)
6345 Values
6346 none Don't check the host key at all
6347 hash Compare the host key with a given hash
6349 known_hosts
6351 Check the host key against the known_hosts file
6352 Since
6354 2.12
6355 SshHostKeyCheckHashType (Enum)
6357 Values
6358 md5 The given hash is an md5 hash
6359 sha1 The given hash is an sha1 hash
6361 sha256 The given hash is an sha256 hash
6363 Since
6365 2.12
6366 SshHostKeyHash (Object)
6368 Members
6369 type: SshHostKeyCheckHashType
6370 The hash algorithm used for the hash
6371 hash: string
6373 The expected hash value
6374 Since
6376 2.12
6377 SshHostKeyCheck (Object)
6379 Members
6380 mode: SshHostKeyCheckMode
6381 Not documented
6382 The members of SshHostKeyHash when mode is "hash"
6384 Since
6386 2.12
6387 BlockdevOptionsSsh (Object)
6389 Members
6390 server: InetSocketAddress
6391 host address
6392 path: string
6394 path to the image on the host
6395 user: string (optional)
6397 user as which to connect, defaults to current local user name
6398 host-key-check: SshHostKeyCheck (optional)
6400 Defines how and what to check the host key against (default:
6401 known_hosts)
6402 Since
6404 2.9
6405 BlkdebugEvent (Enum)
6407 Trigger events supported by blkdebug.
6408 Values
6410 l1_shrink_write_table
6411 write zeros to the l1 table to shrink image. (since 2.11)
6412 l1_shrink_free_l2_clusters
6414 discard the l2 tables. (since 2.11)
6415 cor_write
6417 a write due to copy-on-read (since 2.11)
6418 cluster_alloc_space
6420 an allocation of file space for a cluster (since 4.1)
6421 none triggers once at creation of the blkdebug node (since 4.1)
6423 l1_update
6425 Not documented
6426 l1_grow_alloc_table
6428 Not documented
6429 l1_grow_write_table
6431 Not documented
6432 l1_grow_activate_table
6434 Not documented
6435 l2_load
6437 Not documented
6438 l2_update
6440 Not documented
6441 l2_update_compressed
6443 Not documented
6444 l2_alloc_cow_read
6446 Not documented
6447 l2_alloc_write
6449 Not documented
6450 read_aio
6452 Not documented
6453 read_backing_aio
6455 Not documented
6456 read_compressed
6458 Not documented
6459 write_aio
6461 Not documented
6462 write_compressed
6464 Not documented
6465 vmstate_load
6467 Not documented
6468 vmstate_save
6470 Not documented
6471 cow_read
6473 Not documented
6474 cow_write
6476 Not documented
6477 reftable_load
6479 Not documented
6480 reftable_grow
6482 Not documented
6483 reftable_update
6485 Not documented
6486 refblock_load
6488 Not documented
6489 refblock_update
6491 Not documented
6492 refblock_update_part
6494 Not documented
6495 refblock_alloc
6497 Not documented
6498 refblock_alloc_hookup
6500 Not documented
6501 refblock_alloc_write
6503 Not documented
6504 refblock_alloc_write_blocks
6506 Not documented
6507 refblock_alloc_write_table
6509 Not documented
6510 refblock_alloc_switch_table
6512 Not documented
6513 cluster_alloc
6515 Not documented
6516 cluster_alloc_bytes
6518 Not documented
6519 cluster_free
6521 Not documented
6522 flush_to_os
6524 Not documented
6525 flush_to_disk
6527 Not documented
6528 pwritev_rmw_head
6530 Not documented
6531 pwritev_rmw_after_head
6533 Not documented
6534 pwritev_rmw_tail
6536 Not documented
6537 pwritev_rmw_after_tail
6539 Not documented
6540 pwritev
6542 Not documented
6543 pwritev_zero
6545 Not documented
6546 pwritev_done
6548 Not documented
6549 empty_image_prepare
6551 Not documented
6552 Since
6554 2.9
6555 BlkdebugIOType (Enum)
6557 Kinds of I/O that blkdebug can inject errors in.
6558 Values
6560 read .bdrv_co_preadv()
6561 write .bdrv_co_pwritev()
6563 write-zeroes
6565 .bdrv_co_pwrite_zeroes()
6566 discard
6568 .bdrv_co_pdiscard()
6569 flush .bdrv_co_flush_to_disk()
6571 block-status
6573 .bdrv_co_block_status()
6574 Since
6576 4.1
6577 BlkdebugInjectErrorOptions (Object)
6579 Describes a single error injection for blkdebug.
6580 Members
6582 event: BlkdebugEvent
6583 trigger event
6584 state: int (optional)
6586 the state identifier blkdebug needs to be in to actually trigger
6587 the event; defaults to "any"
6588 iotype: BlkdebugIOType (optional)
6590 the type of I/O operations on which this error should be in‐
6591 jected; defaults to "all read, write, write-zeroes, discard, and
6592 flush operations" (since: 4.1)
6593 errno: int (optional)
6595 error identifier (errno) to be returned; defaults to EIO
6596 sector: int (optional)
6598 specifies the sector index which has to be affected in order to
6599 actually trigger the event; defaults to "any sector"
6600 once: boolean (optional)
6602 disables further events after this one has been triggered; de‐
6603 faults to false
6604 immediately: boolean (optional)
6606 fail immediately; defaults to false
6607 Since
6609 2.9
6610 BlkdebugSetStateOptions (Object)
6612 Describes a single state-change event for blkdebug.
6613 Members
6615 event: BlkdebugEvent
6616 trigger event
6617 state: int (optional)
6619 the current state identifier blkdebug needs to be in; defaults
6620 to "any"
6621 new_state: int
6623 the state identifier blkdebug is supposed to assume if this
6624 event is triggered
6625 Since
6627 2.9
6628 BlockdevOptionsBlkdebug (Object)
6630 Driver specific block device options for blkdebug.
6631 Members
6633 image: BlockdevRef
6634 underlying raw block device (or image file)
6635 config: string (optional)
6637 filename of the configuration file
6638 align: int (optional)
6640 required alignment for requests in bytes, must be positive power
6641 of 2, or 0 for default
6642 max-transfer: int (optional)
6644 maximum size for I/O transfers in bytes, must be positive multi‐
6645 ple of align and of the underlying file's request alignment (but
6646 need not be a power of 2), or 0 for default (since 2.10)
6647 opt-write-zero: int (optional)
6649 preferred alignment for write zero requests in bytes, must be
6650 positive multiple of align and of the underlying file's request
6651 alignment (but need not be a power of 2), or 0 for default
6652 (since 2.10)
6653 max-write-zero: int (optional)
6655 maximum size for write zero requests in bytes, must be positive
6656 multiple of align, of opt-write-zero, and of the underlying
6657 file's request alignment (but need not be a power of 2), or 0
6658 for default (since 2.10)
6659 opt-discard: int (optional)
6661 preferred alignment for discard requests in bytes, must be posi‐
6662 tive multiple of align and of the underlying file's request
6663 alignment (but need not be a power of 2), or 0 for default
6664 (since 2.10)
6665 max-discard: int (optional)
6667 maximum size for discard requests in bytes, must be positive
6668 multiple of align, of opt-discard, and of the underlying file's
6669 request alignment (but need not be a power of 2), or 0 for de‐
6670 fault (since 2.10)
6671 inject-error: array of BlkdebugInjectErrorOptions (optional)
6673 array of error injection descriptions
6674 set-state: array of BlkdebugSetStateOptions (optional)
6676 array of state-change descriptions
6677 take-child-perms: array of BlockPermission (optional)
6679 Permissions to take on image in addition to what is necessary
6680 anyway (which depends on how the blkdebug node is used). De‐
6681 faults to none. (since 5.0)
6682 unshare-child-perms: array of BlockPermission (optional)
6684 Permissions not to share on image in addition to what cannot be
6685 shared anyway (which depends on how the blkdebug node is used).
6686 Defaults to none. (since 5.0)
6687 Since
6689 2.9
6690 BlockdevOptionsBlklogwrites (Object)
6692 Driver specific block device options for blklogwrites.
6693 Members
6695 file: BlockdevRef
6696 block device
6697 log: BlockdevRef
6699 block device used to log writes to file
6700 log-sector-size: int (optional)
6702 sector size used in logging writes to file, determines granular‐
6703 ity of offsets and sizes of writes (default: 512)
6704 log-append: boolean (optional)
6706 append to an existing log (default: false)
6707 log-super-update-interval: int (optional)
6709 interval of write requests after which the log super block is
6710 updated to disk (default: 4096)
6711 Since
6713 3.0
6714 BlockdevOptionsBlkverify (Object)
6716 Driver specific block device options for blkverify.
6717 Members
6719 test: BlockdevRef
6720 block device to be tested
6721 raw: BlockdevRef
6723 raw image used for verification
6724 Since
6726 2.9
6727 BlockdevOptionsBlkreplay (Object)
6729 Driver specific block device options for blkreplay.
6730 Members
6732 image: BlockdevRef
6733 disk image which should be controlled with blkreplay
6734 Since
6736 4.2
6737 QuorumReadPattern (Enum)
6739 An enumeration of quorum read patterns.
6740 Values
6742 quorum read all the children and do a quorum vote on reads
6743 fifo read only from the first child that has not failed
6745 Since
6747 2.9
6748 BlockdevOptionsQuorum (Object)
6750 Driver specific block device options for Quorum
6751 Members
6753 blkverify: boolean (optional)
6754 true if the driver must print content mismatch
6756 set to false by default
6757 children: array of BlockdevRef
6759 the children block devices to use
6760 vote-threshold: int
6762 the vote limit under which a read will fail
6763 rewrite-corrupted: boolean (optional)
6765 rewrite corrupted data when quorum is reached (Since 2.1)
6766 read-pattern: QuorumReadPattern (optional)
6768 choose read pattern and set to quorum by default (Since 2.2)
6769 Since
6771 2.9
6772 BlockdevOptionsGluster (Object)
6774 Driver specific block device options for Gluster
6775 Members
6777 volume: string
6778 name of gluster volume where VM image resides
6779 path: string
6781 absolute path to image file in gluster volume
6782 server: array of SocketAddress
6784 gluster servers description
6785 debug: int (optional)
6787 libgfapi log level (default '4' which is Error) (Since 2.8)
6788 logfile: string (optional)
6790 libgfapi log file (default /dev/stderr) (Since 2.8)
6791 Since
6793 2.9
6794 IscsiTransport (Enum)
6796 An enumeration of libiscsi transport types
6797 Values
6799 tcp Not documented
6800 iser Not documented
6802 Since
6804 2.9
6805 IscsiHeaderDigest (Enum)
6807 An enumeration of header digests supported by libiscsi
6808 Values
6810 crc32c Not documented
6811 none Not documented
6813 crc32c-none
6815 Not documented
6816 none-crc32c
6818 Not documented
6819 Since
6821 2.9
6822 BlockdevOptionsIscsi (Object)
6824 Members
6825 transport: IscsiTransport
6826 The iscsi transport type
6827 portal: string
6829 The address of the iscsi portal
6830 target: string
6832 The target iqn name
6833 lun: int (optional)
6835 LUN to connect to. Defaults to 0.
6836 user: string (optional)
6838 User name to log in with. If omitted, no CHAP authentication is
6839 performed.
6840 password-secret: string (optional)
6842 The ID of a QCryptoSecret object providing the password for the
6843 login. This option is required if user is specified.
6844 initiator-name: string (optional)
6846 The iqn name we want to identify to the target as. If this op‐
6847 tion is not specified, an initiator name is generated automati‐
6848 cally.
6849 header-digest: IscsiHeaderDigest (optional)
6851 The desired header digest. Defaults to none-crc32c.
6852 timeout: int (optional)
6854 Timeout in seconds after which a request will timeout. 0 means
6855 no timeout and is the default.
6856 Driver specific block device options for iscsi
6857 Since
6859 2.9
6860 RbdAuthMode (Enum)
6862 Values
6863 cephx Not documented
6864 none Not documented
6866 Since
6868 3.0
6869 RbdImageEncryptionFormat (Enum)
6871 Values
6872 luks Not documented
6873 luks2 Not documented
6875 Since
6877 6.1
6878 RbdEncryptionOptionsLUKSBase (Object)
6880 Members
6881 key-secret: string
6882 ID of a QCryptoSecret object providing a passphrase for unlock‐
6883 ing the encryption
6884 Since
6886 6.1
6887 RbdEncryptionCreateOptionsLUKSBase (Object)
6889 Members
6890 cipher-alg: QCryptoCipherAlgorithm (optional)
6891 The encryption algorithm
6892 The members of RbdEncryptionOptionsLUKSBase
6894 Since
6896 6.1
6897 RbdEncryptionOptionsLUKS (Object)
6899 Members
6900 The members of RbdEncryptionOptionsLUKSBase
6901 Since
6903 6.1
6904 RbdEncryptionOptionsLUKS2 (Object)
6906 Members
6907 The members of RbdEncryptionOptionsLUKSBase
6908 Since
6910 6.1
6911 RbdEncryptionCreateOptionsLUKS (Object)
6913 Members
6914 The members of RbdEncryptionCreateOptionsLUKSBase
6915 Since
6917 6.1
6918 RbdEncryptionCreateOptionsLUKS2 (Object)
6920 Members
6921 The members of RbdEncryptionCreateOptionsLUKSBase
6922 Since
6924 6.1
6925 RbdEncryptionOptions (Object)
6927 Members
6928 format: RbdImageEncryptionFormat
6929 Not documented
6930 The members of RbdEncryptionOptionsLUKS when format is "luks"
6932 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
6934 Since
6936 6.1
6937 RbdEncryptionCreateOptions (Object)
6939 Members
6940 format: RbdImageEncryptionFormat
6941 Not documented
6942 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
6944 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
6946 Since
6948 6.1
6949 BlockdevOptionsRbd (Object)
6951 Members
6952 pool: string
6953 Ceph pool name.
6954 namespace: string (optional)
6956 Rados namespace name in the Ceph pool. (Since 5.0)
6957 image: string
6959 Image name in the Ceph pool.
6960 conf: string (optional)
6962 path to Ceph configuration file. Values in the configuration
6963 file will be overridden by options specified via QAPI.
6964 snapshot: string (optional)
6966 Ceph snapshot name.
6967 encrypt: RbdEncryptionOptions (optional)
6969 Image encryption options. (Since 6.1)
6970 user: string (optional)
6972 Ceph id name.
6973 auth-client-required: array of RbdAuthMode (optional)
6975 Acceptable authentication modes. This maps to Ceph configura‐
6976 tion option "auth_client_required". (Since 3.0)
6977 key-secret: string (optional)
6979 ID of a QCryptoSecret object providing a key for cephx authenti‐
6980 cation. This maps to Ceph configuration option "key". (Since
6981 3.0)
6982 server: array of InetSocketAddressBase (optional)
6984 Monitor host address and port. This maps to the "mon_host" Ceph
6985 option.
6986 Since
6988 2.9
6989 ReplicationMode (Enum)
6991 An enumeration of replication modes.
6992 Values
6994 primary
6995 Primary mode, the vm's state will be sent to secondary QEMU.
6996 secondary
6998 Secondary mode, receive the vm's state from primary QEMU.
6999 Since
7001 2.9
7002 If
7004 CONFIG_REPLICATION
7005 BlockdevOptionsReplication (Object)
7007 Driver specific block device options for replication
7008 Members
7010 mode: ReplicationMode
7011 the replication mode
7012 top-id: string (optional)
7014 In secondary mode, node name or device ID of the root node who
7015 owns the replication node chain. Must not be given in primary
7016 mode.
7017 The members of BlockdevOptionsGenericFormat
7019 Since
7021 2.9
7022 If
7024 CONFIG_REPLICATION
7025 NFSTransport (Enum)
7027 An enumeration of NFS transport types
7028 Values
7030 inet TCP transport
7031 Since
7033 2.9
7034 NFSServer (Object)
7036 Captures the address of the socket
7037 Members
7039 type: NFSTransport
7040 transport type used for NFS (only TCP supported)
7041 host: string
7043 host address for NFS server
7044 Since
7046 2.9
7047 BlockdevOptionsNfs (Object)
7049 Driver specific block device option for NFS
7050 Members
7052 server: NFSServer
7053 host address
7054 path: string
7056 path of the image on the host
7057 user: int (optional)
7059 UID value to use when talking to the server (defaults to 65534
7060 on Windows and getuid() on unix)
7061 group: int (optional)
7063 GID value to use when talking to the server (defaults to 65534
7064 on Windows and getgid() in unix)
7065 tcp-syn-count: int (optional)
7067 number of SYNs during the session establishment (defaults to
7068 libnfs default)
7069 readahead-size: int (optional)
7071 set the readahead size in bytes (defaults to libnfs default)
7072 page-cache-size: int (optional)
7074 set the pagecache size in bytes (defaults to libnfs default)
7075 debug: int (optional)
7077 set the NFS debug level (max 2) (defaults to libnfs default)
7078 Since
7080 2.9
7081 BlockdevOptionsCurlBase (Object)
7083 Driver specific block device options shared by all protocols supported
7084 by the curl backend.
7085 Members
7087 url: string
7088 URL of the image file
7089 readahead: int (optional)
7091 Size of the read-ahead cache; must be a multiple of 512 (de‐
7092 faults to 256 kB)
7093 timeout: int (optional)
7095 Timeout for connections, in seconds (defaults to 5)
7096 username: string (optional)
7098 Username for authentication (defaults to none)
7099 password-secret: string (optional)
7101 ID of a QCryptoSecret object providing a password for authenti‐
7102 cation (defaults to no password)
7103 proxy-username: string (optional)
7105 Username for proxy authentication (defaults to none)
7106 proxy-password-secret: string (optional)
7108 ID of a QCryptoSecret object providing a password for proxy au‐
7109 thentication (defaults to no password)
7110 Since
7112 2.9
7113 BlockdevOptionsCurlHttp (Object)
7115 Driver specific block device options for HTTP connections over the curl
7116 backend. URLs must start with "http://".
7117 Members
7119 cookie: string (optional)
7120 List of cookies to set; format is "name1=content1; name2=con‐
7121 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
7122 ies.
7123 cookie-secret: string (optional)
7125 ID of a QCryptoSecret object providing the cookie data in a se‐
7126 cure way. See cookie for the format. (since 2.10)
7127 The members of BlockdevOptionsCurlBase
7129 Since
7131 2.9
7132 BlockdevOptionsCurlHttps (Object)
7134 Driver specific block device options for HTTPS connections over the
7135 curl backend. URLs must start with "https://".
7136 Members
7138 cookie: string (optional)
7139 List of cookies to set; format is "name1=content1; name2=con‐
7140 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
7141 ies.
7142 sslverify: boolean (optional)
7144 Whether to verify the SSL certificate's validity (defaults to
7145 true)
7146 cookie-secret: string (optional)
7148 ID of a QCryptoSecret object providing the cookie data in a se‐
7149 cure way. See cookie for the format. (since 2.10)
7150 The members of BlockdevOptionsCurlBase
7152 Since
7154 2.9
7155 BlockdevOptionsCurlFtp (Object)
7157 Driver specific block device options for FTP connections over the curl
7158 backend. URLs must start with "ftp://".
7159 Members
7161 The members of BlockdevOptionsCurlBase
7162 Since
7164 2.9
7165 BlockdevOptionsCurlFtps (Object)
7167 Driver specific block device options for FTPS connections over the curl
7168 backend. URLs must start with "ftps://".
7169 Members
7171 sslverify: boolean (optional)
7172 Whether to verify the SSL certificate's validity (defaults to
7173 true)
7174 The members of BlockdevOptionsCurlBase
7176 Since
7178 2.9
7179 BlockdevOptionsNbd (Object)
7181 Driver specific block device options for NBD.
7182 Members
7184 server: SocketAddress
7185 NBD server address
7186 export: string (optional)
7188 export name
7189 tls-creds: string (optional)
7191 TLS credentials ID
7192 tls-hostname: string (optional)
7194 TLS hostname override for certificate validation (Since 7.0)
7195 x-dirty-bitmap: string (optional)
7197 A metadata context name such as "qemu:dirty-bitmap:NAME" or
7198 "qemu:allocation-depth" to query in place of the traditional
7199 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
7200 the NBD protocol; and yes, naming this option x-context would
7201 have made more sense) (since 3.0)
7202 reconnect-delay: int (optional)
7204 On an unexpected disconnect, the nbd client tries to connect
7205 again until succeeding or encountering a serious error. During
7206 the first reconnect-delay seconds, all requests are paused and
7207 will be rerun on a successful reconnect. After that time, any
7208 delayed requests and all future requests before a successful re‐
7209 connect will immediately fail. Default 0 (Since 4.2)
7210 open-timeout: int (optional)
7212 In seconds. If zero, the nbd driver tries the connection only
7213 once, and fails to open if the connection fails. If non-zero,
7214 the nbd driver will repeat connection attempts until successful
7215 or until open-timeout seconds have elapsed. Default 0 (Since
7216 7.0)
7217 Features
7219 unstable
7220 Member x-dirty-bitmap is experimental.
7221 Since
7223 2.9
7224 BlockdevOptionsRaw (Object)
7226 Driver specific block device options for the raw driver.
7227 Members
7229 offset: int (optional)
7230 position where the block device starts
7231 size: int (optional)
7233 the assumed size of the device
7234 The members of BlockdevOptionsGenericFormat
7236 Since
7238 2.9
7239 BlockdevOptionsThrottle (Object)
7241 Driver specific block device options for the throttle driver
7242 Members
7244 throttle-group: string
7245 the name of the throttle-group object to use. It must already
7246 exist.
7247 file: BlockdevRef
7249 reference to or definition of the data source block device
7250 Since
7252 2.11
7253 BlockdevOptionsCor (Object)
7255 Driver specific block device options for the copy-on-read driver.
7256 Members
7258 bottom: string (optional)
7259 The name of a non-filter node (allocation-bearing layer) that
7260 limits the COR operations in the backing chain (inclusive), so
7261 that no data below this node will be copied by this filter. If
7262 option is absent, the limit is not applied, so that data from
7263 all backing layers may be copied.
7264 The members of BlockdevOptionsGenericFormat
7266 Since
7268 6.0
7269 BlockdevOptionsCbw (Object)
7271 Driver specific block device options for the copy-before-write driver,
7272 which does so called copy-before-write operations: when data is written
7273 to the filter, the filter first reads corresponding blocks from its
7274 file child and copies them to target child. After successfully copying,
7275 the write request is propagated to file child. If copying fails, the
7276 original write request is failed too and no data is written to file
7277 child.
7278 Members
7280 target: BlockdevRef
7281 The target for copy-before-write operations.
7282 bitmap: BlockDirtyBitmap (optional)
7284 If specified, copy-before-write filter will do copy-before-write
7285 operations only for dirty regions of the bitmap. Bitmap size
7286 must be equal to length of file and target child of the filter.
7287 Note also, that bitmap is used only to initialize internal bit‐
7288 map of the process, so further modifications (or removing) of
7289 specified bitmap doesn't influence the filter. (Since 7.0)
7290 The members of BlockdevOptionsGenericFormat
7292 Since
7294 6.2
7295 BlockdevOptions (Object)
7297 Options for creating a block device. Many options are available for
7298 all block devices, independent of the block driver:
7299 Members
7301 driver: BlockdevDriver
7302 block driver name
7303 node-name: string (optional)
7305 the node name of the new node (Since 2.0). This option is re‐
7306 quired on the top level of blockdev-add. Valid node names start
7307 with an alphabetic character and may contain only alphanumeric
7308 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
7309 ters.
7310 discard: BlockdevDiscardOptions (optional)
7312 discard-related options (default: ignore)
7313 cache: BlockdevCacheOptions (optional)
7315 cache-related options
7316 read-only: boolean (optional)
7318 whether the block device should be read-only (default: false).
7319 Note that some block drivers support only read-only access, ei‐
7320 ther generally or in certain configurations. In this case, the
7321 default value does not work and the option must be specified ex‐
7322 plicitly.
7323 auto-read-only: boolean (optional)
7325 if true and read-only is false, QEMU may automatically decide
7326 not to open the image read-write as requested, but fall back to
7327 read-only instead (and switch between the modes later), e.g. de‐
7328 pending on whether the image file is writable or whether a writ‐
7329 ing user is attached to the node (default: false, since 3.1)
7330 detect-zeroes: BlockdevDetectZeroesOptions (optional)
7332 detect and optimize zero writes (Since 2.1) (default: off)
7333 force-share: boolean (optional)
7335 force share all permission on added nodes. Requires
7336 read-only=true. (Since 2.10)
7337 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
7339 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
7341 writes"
7342 The members of BlockdevOptionsBlkverify when driver is "blkverify"
7344 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
7346 The members of BlockdevOptionsGenericFormat when driver is "bochs"
7348 The members of BlockdevOptionsGenericFormat when driver is "cloop"
7350 The members of BlockdevOptionsGenericFormat when driver is "compress"
7352 The members of BlockdevOptionsCbw when driver is "copy-before-write"
7354 The members of BlockdevOptionsCor when driver is "copy-on-read"
7356 The members of BlockdevOptionsGenericFormat when driver is "dmg"
7358 The members of BlockdevOptionsFile when driver is "file"
7360 The members of BlockdevOptionsCurlFtp when driver is "ftp"
7362 The members of BlockdevOptionsCurlFtps when driver is "ftps"
7364 The members of BlockdevOptionsGluster when driver is "gluster"
7366 The members of BlockdevOptionsFile when driver is "host_cdrom" (If:
7368 HAVE_HOST_BLOCK_DEVICE)
7369 The members of BlockdevOptionsFile when driver is "host_device" (If:
7371 HAVE_HOST_BLOCK_DEVICE)
7372 The members of BlockdevOptionsCurlHttp when driver is "http"
7374 The members of BlockdevOptionsCurlHttps when driver is "https"
7376 The members of BlockdevOptionsIscsi when driver is "iscsi"
7378 The members of BlockdevOptionsLUKS when driver is "luks"
7380 The members of BlockdevOptionsNbd when driver is "nbd"
7382 The members of BlockdevOptionsNfs when driver is "nfs"
7384 The members of BlockdevOptionsNull when driver is "null-aio"
7386 The members of BlockdevOptionsNull when driver is "null-co"
7388 The members of BlockdevOptionsNVMe when driver is "nvme"
7390 The members of BlockdevOptionsGenericFormat when driver is "parallels"
7392 The members of BlockdevOptionsPreallocate when driver is "preallocate"
7394 The members of BlockdevOptionsQcow2 when driver is "qcow2"
7396 The members of BlockdevOptionsQcow when driver is "qcow"
7398 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
7400 The members of BlockdevOptionsQuorum when driver is "quorum"
7402 The members of BlockdevOptionsRaw when driver is "raw"
7404 The members of BlockdevOptionsRbd when driver is "rbd"
7406 The members of BlockdevOptionsReplication when driver is "replication"
7408 (If: CONFIG_REPLICATION)
7409 The members of BlockdevOptionsGenericFormat when driver is "snap‐
7411 shot-access"
7412 The members of BlockdevOptionsSsh when driver is "ssh"
7414 The members of BlockdevOptionsThrottle when driver is "throttle"
7416 The members of BlockdevOptionsGenericFormat when driver is "vdi"
7418 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
7420 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
7422 The members of BlockdevOptionsGenericFormat when driver is "vpc"
7424 The members of BlockdevOptionsVVFAT when driver is "vvfat"
7426 Remaining options are determined by the block driver.
7427 Since
7429 2.9
7430 BlockdevRef (Alternate)
7432 Reference to a block device.
7433 Members
7435 definition: BlockdevOptions
7436 defines a new block device inline
7437 reference: string
7439 references the ID of an existing block device
7440 Since
7442 2.9
7443 BlockdevRefOrNull (Alternate)
7445 Reference to a block device.
7446 Members
7448 definition: BlockdevOptions
7449 defines a new block device inline
7450 reference: string
7452 references the ID of an existing block device. An empty string
7453 means that no block device should be referenced. Deprecated;
7454 use null instead.
7455 null: null
7457 No block device should be referenced (since 2.10)
7458 Since
7460 2.9
7461 blockdev-add (Command)
7463 Creates a new block device.
7464 Arguments
7466 The members of BlockdevOptions
7467 Since
7469 2.9
7470 Example
7472 1.
7473 -> { "execute": "blockdev-add",
7474 "arguments": {
7475 "driver": "qcow2",
7476 "node-name": "test1",
7477 "file": {
7478 "driver": "file",
7479 "filename": "test.qcow2"
7480 }
7481 }
7482 }
7483 <- { "return": {} }
7484 2.
7486 -> { "execute": "blockdev-add",
7487 "arguments": {
7488 "driver": "qcow2",
7489 "node-name": "node0",
7490 "discard": "unmap",
7491 "cache": {
7492 "direct": true
7493 },
7494 "file": {
7495 "driver": "file",
7496 "filename": "/tmp/test.qcow2"
7497 },
7498 "backing": {
7499 "driver": "raw",
7500 "file": {
7501 "driver": "file",
7502 "filename": "/dev/fdset/4"
7503 }
7504 }
7505 }
7506 }
7507 <- { "return": {} }
7509 blockdev-reopen (Command)
7511 Reopens one or more block devices using the given set of options. Any
7512 option not specified will be reset to its default value regardless of
7513 its previous status. If an option cannot be changed or a particular
7514 driver does not support reopening then the command will return an er‐
7515 ror. All devices in the list are reopened in one transaction, so if one
7516 of them fails then the whole transaction is cancelled.
7517 The command receives a list of block devices to reopen. For each one of
7519 them, the top-level node-name option (from BlockdevOptions) must be
7520 specified and is used to select the block device to be reopened. Other
7521 node-name options must be either omitted or set to the current name of
7522 the appropriate node. This command won't change any node name and any
7523 attempt to do it will result in an error.
7524 In the case of options that refer to child nodes, the behavior of this
7526 command depends on the value:
7527 1. A set of options (BlockdevOptions): the child is reopened with
7529 the specified set of options.
7530 2. A reference to the current child: the child is reopened using its
7532 existing set of options.
7533 3. A reference to a different node: the current child is replaced
7535 with the specified one.
7536 4. NULL: the current child (if any) is detached.
7538 Options (1) and (2) are supported in all cases. Option (3) is supported
7540 for file and backing, and option (4) for backing only.
7541 Unlike with blockdev-add, the backing option must always be present un‐
7543 less the node being reopened does not have a backing file and its image
7544 does not have a default backing file name as part of its metadata.
7545 Arguments
7547 options: array of BlockdevOptions
7548 Not documented
7549 Since
7551 6.1
7552 blockdev-del (Command)
7554 Deletes a block device that has been added using blockdev-add. The
7555 command will fail if the node is attached to a device or is otherwise
7556 being used.
7557 Arguments
7559 node-name: string
7560 Name of the graph node to delete.
7561 Since
7563 2.9
7564 Example
7566 -> { "execute": "blockdev-add",
7567 "arguments": {
7568 "driver": "qcow2",
7569 "node-name": "node0",
7570 "file": {
7571 "driver": "file",
7572 "filename": "test.qcow2"
7573 }
7574 }
7575 }
7576 <- { "return": {} }
7577 -> { "execute": "blockdev-del",
7579 "arguments": { "node-name": "node0" }
7580 }
7581 <- { "return": {} }
7582 BlockdevCreateOptionsFile (Object)
7584 Driver specific image creation options for file.
7585 Members
7587 filename: string
7588 Filename for the new image file
7589 size: int
7591 Size of the virtual disk in bytes
7592 preallocation: PreallocMode (optional)
7594 Preallocation mode for the new image (default: off; allowed val‐
7595 ues: off, falloc (if CONFIG_POSIX_FALLOCATE), full (if CON‐
7596 FIG_POSIX))
7597 nocow: boolean (optional)
7599 Turn off copy-on-write (valid only on btrfs; default: off)
7600 extent-size-hint: int (optional)
7602 Extent size hint to add to the image file; 0 for not adding an
7603 extent size hint (default: 1 MB, since 5.1)
7604 Since
7606 2.12
7607 BlockdevCreateOptionsGluster (Object)
7609 Driver specific image creation options for gluster.
7610 Members
7612 location: BlockdevOptionsGluster
7613 Where to store the new image file
7614 size: int
7616 Size of the virtual disk in bytes
7617 preallocation: PreallocMode (optional)
7619 Preallocation mode for the new image (default: off; allowed val‐
7620 ues: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), full (if CON‐
7621 FIG_GLUSTERFS_ZEROFILL))
7622 Since
7624 2.12
7625 BlockdevCreateOptionsLUKS (Object)
7627 Driver specific image creation options for LUKS.
7628 Members
7630 file: BlockdevRef
7631 Node to create the image format on
7632 size: int
7634 Size of the virtual disk in bytes
7635 preallocation: PreallocMode (optional)
7637 Preallocation mode for the new image (since: 4.2) (default: off;
7638 allowed values: off, metadata, falloc, full)
7639 The members of QCryptoBlockCreateOptionsLUKS
7641 Since
7643 2.12
7644 BlockdevCreateOptionsNfs (Object)
7646 Driver specific image creation options for NFS.
7647 Members
7649 location: BlockdevOptionsNfs
7650 Where to store the new image file
7651 size: int
7653 Size of the virtual disk in bytes
7654 Since
7656 2.12
7657 BlockdevCreateOptionsParallels (Object)
7659 Driver specific image creation options for parallels.
7660 Members
7662 file: BlockdevRef
7663 Node to create the image format on
7664 size: int
7666 Size of the virtual disk in bytes
7667 cluster-size: int (optional)
7669 Cluster size in bytes (default: 1 MB)
7670 Since
7672 2.12
7673 BlockdevCreateOptionsQcow (Object)
7675 Driver specific image creation options for qcow.
7676 Members
7678 file: BlockdevRef
7679 Node to create the image format on
7680 size: int
7682 Size of the virtual disk in bytes
7683 backing-file: string (optional)
7685 File name of the backing file if a backing file should be used
7686 encrypt: QCryptoBlockCreateOptions (optional)
7688 Encryption options if the image should be encrypted
7689 Since
7691 2.12
7692 BlockdevQcow2Version (Enum)
7694 Values
7695 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
7696 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
7698 Since
7700 2.12
7701 Qcow2CompressionType (Enum)
7703 Compression type used in qcow2 image file
7704 Values
7706 zlib zlib compression, see <http://zlib.net/>
7707 zstd (If: CONFIG_ZSTD)
7709 zstd compression, see <http://github.com/facebook/zstd>
7710 Since
7712 5.1
7713 BlockdevCreateOptionsQcow2 (Object)
7715 Driver specific image creation options for qcow2.
7716 Members
7718 file: BlockdevRef
7719 Node to create the image format on
7720 data-file: BlockdevRef (optional)
7722 Node to use as an external data file in which all guest data is
7723 stored so that only metadata remains in the qcow2 file (since:
7724 4.0)
7725 data-file-raw: boolean (optional)
7727 True if the external data file must stay valid as a standalone
7728 (read-only) raw image without looking at qcow2 metadata (de‐
7729 fault: false; since: 4.0)
7730 extended-l2: boolean (optional)
7732 True to make the image have extended L2 entries (default: false;
7733 since 5.2)
7734 size: int
7736 Size of the virtual disk in bytes
7737 version: BlockdevQcow2Version (optional)
7739 Compatibility level (default: v3)
7740 backing-file: string (optional)
7742 File name of the backing file if a backing file should be used
7743 backing-fmt: BlockdevDriver (optional)
7745 Name of the block driver to use for the backing file
7746 encrypt: QCryptoBlockCreateOptions (optional)
7748 Encryption options if the image should be encrypted
7749 cluster-size: int (optional)
7751 qcow2 cluster size in bytes (default: 65536)
7752 preallocation: PreallocMode (optional)
7754 Preallocation mode for the new image (default: off; allowed val‐
7755 ues: off, falloc, full, metadata)
7756 lazy-refcounts: boolean (optional)
7758 True if refcounts may be updated lazily (default: off)
7759 refcount-bits: int (optional)
7761 Width of reference counts in bits (default: 16)
7762 compression-type: Qcow2CompressionType (optional)
7764 The image cluster compression method (default: zlib, since 5.1)
7765 Since
7767 2.12
7768 BlockdevCreateOptionsQed (Object)
7770 Driver specific image creation options for qed.
7771 Members
7773 file: BlockdevRef
7774 Node to create the image format on
7775 size: int
7777 Size of the virtual disk in bytes
7778 backing-file: string (optional)
7780 File name of the backing file if a backing file should be used
7781 backing-fmt: BlockdevDriver (optional)
7783 Name of the block driver to use for the backing file
7784 cluster-size: int (optional)
7786 Cluster size in bytes (default: 65536)
7787 table-size: int (optional)
7789 L1/L2 table size (in clusters)
7790 Since
7792 2.12
7793 BlockdevCreateOptionsRbd (Object)
7795 Driver specific image creation options for rbd/Ceph.
7796 Members
7798 location: BlockdevOptionsRbd
7799 Where to store the new image file. This location cannot point to
7800 a snapshot.
7801 size: int
7803 Size of the virtual disk in bytes
7804 cluster-size: int (optional)
7806 RBD object size
7807 encrypt: RbdEncryptionCreateOptions (optional)
7809 Image encryption options. (Since 6.1)
7810 Since
7812 2.12
7813 BlockdevVmdkSubformat (Enum)
7815 Subformat options for VMDK images
7816 Values
7818 monolithicSparse
7819 Single file image with sparse cluster allocation
7820 monolithicFlat
7822 Single flat data image and a descriptor file
7823 twoGbMaxExtentSparse
7825 Data is split into 2GB (per virtual LBA) sparse extent files, in
7826 addition to a descriptor file
7827 twoGbMaxExtentFlat
7829 Data is split into 2GB (per virtual LBA) flat extent files, in
7830 addition to a descriptor file
7831 streamOptimized
7833 Single file image sparse cluster allocation, optimized for
7834 streaming over network.
7835 Since
7837 4.0
7838 BlockdevVmdkAdapterType (Enum)
7840 Adapter type info for VMDK images
7841 Values
7843 ide Not documented
7844 buslogic
7846 Not documented
7847 lsilogic
7849 Not documented
7850 legacyESX
7852 Not documented
7853 Since
7855 4.0
7856 BlockdevCreateOptionsVmdk (Object)
7858 Driver specific image creation options for VMDK.
7859 Members
7861 file: BlockdevRef
7862 Where to store the new image file. This refers to the image file
7863 for monolithcSparse and streamOptimized format, or the descrip‐
7864 tor file for other formats.
7865 size: int
7867 Size of the virtual disk in bytes
7868 extents: array of BlockdevRef (optional)
7870 Where to store the data extents. Required for monolithcFlat,
7871 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
7872 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
7873 mats, the number of entries required is calculated as ex‐
7874 tent_number = virtual_size / 2GB. Providing more extents than
7875 will be used is an error.
7876 subformat: BlockdevVmdkSubformat (optional)
7878 The subformat of the VMDK image. Default: "monolithicSparse".
7879 backing-file: string (optional)
7881 The path of backing file. Default: no backing file is used.
7882 adapter-type: BlockdevVmdkAdapterType (optional)
7884 The adapter type used to fill in the descriptor. Default: ide.
7885 hwversion: string (optional)
7887 Hardware version. The meaningful options are "4" or "6". De‐
7888 fault: "4".
7889 toolsversion: string (optional)
7891 VMware guest tools version. Default: "2147483647" (Since 6.2)
7892 zeroed-grain: boolean (optional)
7894 Whether to enable zeroed-grain feature for sparse subformats.
7895 Default: false.
7896 Since
7898 4.0
7899 BlockdevCreateOptionsSsh (Object)
7901 Driver specific image creation options for SSH.
7902 Members
7904 location: BlockdevOptionsSsh
7905 Where to store the new image file
7906 size: int
7908 Size of the virtual disk in bytes
7909 Since
7911 2.12
7912 BlockdevCreateOptionsVdi (Object)
7914 Driver specific image creation options for VDI.
7915 Members
7917 file: BlockdevRef
7918 Node to create the image format on
7919 size: int
7921 Size of the virtual disk in bytes
7922 preallocation: PreallocMode (optional)
7924 Preallocation mode for the new image (default: off; allowed val‐
7925 ues: off, metadata)
7926 Since
7928 2.12
7929 BlockdevVhdxSubformat (Enum)
7931 Values
7932 dynamic
7933 Growing image file
7934 fixed Preallocated fixed-size image file
7936 Since
7938 2.12
7939 BlockdevCreateOptionsVhdx (Object)
7941 Driver specific image creation options for vhdx.
7942 Members
7944 file: BlockdevRef
7945 Node to create the image format on
7946 size: int
7948 Size of the virtual disk in bytes
7949 log-size: int (optional)
7951 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
7952 block-size: int (optional)
7954 Block size in bytes, must be a multiple of 1 MB and not larger
7955 than 256 MB (default: automatically choose a block size depend‐
7956 ing on the image size)
7957 subformat: BlockdevVhdxSubformat (optional)
7959 vhdx subformat (default: dynamic)
7960 block-state-zero: boolean (optional)
7962 Force use of payload blocks of type 'ZERO'. Non-standard, but
7963 default. Do not set to 'off' when using 'qemu-img convert' with
7964 subformat=dynamic.
7965 Since
7967 2.12
7968 BlockdevVpcSubformat (Enum)
7970 Values
7971 dynamic
7972 Growing image file
7973 fixed Preallocated fixed-size image file
7975 Since
7977 2.12
7978 BlockdevCreateOptionsVpc (Object)
7980 Driver specific image creation options for vpc (VHD).
7981 Members
7983 file: BlockdevRef
7984 Node to create the image format on
7985 size: int
7987 Size of the virtual disk in bytes
7988 subformat: BlockdevVpcSubformat (optional)
7990 vhdx subformat (default: dynamic)
7991 force-size: boolean (optional)
7993 Force use of the exact byte size instead of rounding to the next
7994 size that can be represented in CHS geometry (default: false)
7995 Since
7997 2.12
7998 BlockdevCreateOptions (Object)
8000 Options for creating an image format on a given node.
8001 Members
8003 driver: BlockdevDriver
8004 block driver to create the image format
8005 The members of BlockdevCreateOptionsFile when driver is "file"
8007 The members of BlockdevCreateOptionsGluster when driver is "gluster"
8009 The members of BlockdevCreateOptionsLUKS when driver is "luks"
8011 The members of BlockdevCreateOptionsNfs when driver is "nfs"
8013 The members of BlockdevCreateOptionsParallels when driver is "paral‐
8015 lels"
8016 The members of BlockdevCreateOptionsQcow when driver is "qcow"
8018 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
8020 The members of BlockdevCreateOptionsQed when driver is "qed"
8022 The members of BlockdevCreateOptionsRbd when driver is "rbd"
8024 The members of BlockdevCreateOptionsSsh when driver is "ssh"
8026 The members of BlockdevCreateOptionsVdi when driver is "vdi"
8028 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
8030 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
8032 The members of BlockdevCreateOptionsVpc when driver is "vpc"
8034 Since
8036 2.12
8037 blockdev-create (Command)
8039 Starts a job to create an image format on a given node. The job is au‐
8040 tomatically finalized, but a manual job-dismiss is required.
8041 Arguments
8043 job-id: string
8044 Identifier for the newly created job.
8045 options: BlockdevCreateOptions
8047 Options for the image creation.
8048 Since
8050 3.0
8051 BlockdevAmendOptionsLUKS (Object)
8053 Driver specific image amend options for LUKS.
8054 Members
8056 The members of QCryptoBlockAmendOptionsLUKS
8057 Since
8059 5.1
8060 BlockdevAmendOptionsQcow2 (Object)
8062 Driver specific image amend options for qcow2. For now, only encryp‐
8063 tion options can be amended
8064 encrypt Encryption options to be amended
8066 Members
8068 encrypt: QCryptoBlockAmendOptions (optional)
8069 Not documented
8070 Since
8072 5.1
8073 BlockdevAmendOptions (Object)
8075 Options for amending an image format
8076 Members
8078 driver: BlockdevDriver
8079 Block driver of the node to amend.
8080 The members of BlockdevAmendOptionsLUKS when driver is "luks"
8082 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
8084 Since
8086 5.1
8087 x-blockdev-amend (Command)
8089 Starts a job to amend format specific options of an existing open block
8090 device The job is automatically finalized, but a manual job-dismiss is
8091 required.
8092 Arguments
8094 job-id: string
8095 Identifier for the newly created job.
8096 node-name: string
8098 Name of the block node to work on
8099 options: BlockdevAmendOptions
8101 Options (driver specific)
8102 force: boolean (optional)
8104 Allow unsafe operations, format specific For luks that allows
8105 erase of the last active keyslot (permanent loss of data), and
8106 replacement of an active keyslot (possible loss of data if IO
8107 error happens)
8108 Features
8110 unstable
8111 This command is experimental.
8112 Since
8114 5.1
8115 BlockErrorAction (Enum)
8117 An enumeration of action that has been taken when a DISK I/O occurs
8118 Values
8120 ignore error has been ignored
8121 report error has been reported to the device
8123 stop error caused VM to be stopped
8125 Since
8127 2.1
8128 BLOCK_IMAGE_CORRUPTED (Event)
8130 Emitted when a disk image is being marked corrupt. The image can be
8131 identified by its device or node name. The 'device' field is always
8132 present for compatibility reasons, but it can be empty ("") if the im‐
8133 age does not have a device name associated.
8134 Arguments
8136 device: string
8137 device name. This is always present for compatibility reasons,
8138 but it can be empty ("") if the image does not have a device
8139 name associated.
8140 node-name: string (optional)
8142 node name (Since: 2.4)
8143 msg: string
8145 informative message for human consumption, such as the kind of
8146 corruption being detected. It should not be parsed by machine as
8147 it is not guaranteed to be stable
8148 offset: int (optional)
8150 if the corruption resulted from an image access, this is the
8151 host's access offset into the image
8152 size: int (optional)
8154 if the corruption resulted from an image access, this is the ac‐
8155 cess size
8156 fatal: boolean
8158 if set, the image is marked corrupt and therefore unusable after
8159 this event and must be repaired (Since 2.2; before, every
8160 BLOCK_IMAGE_CORRUPTED event was fatal)
8161 Note
8163 If action is "stop", a STOP event will eventually follow the
8164 BLOCK_IO_ERROR event.
8165 Example
8167 <- { "event": "BLOCK_IMAGE_CORRUPTED",
8168 "data": { "device": "", "node-name": "drive", "fatal": false,
8169 "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
8170 "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }
8171 Since
8173 1.7
8174 BLOCK_IO_ERROR (Event)
8176 Emitted when a disk I/O error occurs
8177 Arguments
8179 device: string
8180 device name. This is always present for compatibility reasons,
8181 but it can be empty ("") if the image does not have a device
8182 name associated.
8183 node-name: string (optional)
8185 node name. Note that errors may be reported for the root node
8186 that is directly attached to a guest device rather than for the
8187 node where the error occurred. The node name is not present if
8188 the drive is empty. (Since: 2.8)
8189 operation: IoOperationType
8191 I/O operation
8192 action: BlockErrorAction
8194 action that has been taken
8195 nospace: boolean (optional)
8197 true if I/O error was caused due to a no-space condition. This
8198 key is only present if query-block's io-status is present,
8199 please see query-block documentation for more information
8200 (since: 2.2)
8201 reason: string
8203 human readable string describing the error cause. (This field
8204 is a debugging aid for humans, it should not be parsed by appli‐
8205 cations) (since: 2.2)
8206 Note
8208 If action is "stop", a STOP event will eventually follow the
8209 BLOCK_IO_ERROR event
8210 Since
8212 0.13
8213 Example
8215 <- { "event": "BLOCK_IO_ERROR",
8216 "data": { "device": "ide0-hd1",
8217 "node-name": "#block212",
8218 "operation": "write",
8219 "action": "stop",
8220 "reason": "No space left on device" },
8221 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8222 BLOCK_JOB_COMPLETED (Event)
8224 Emitted when a block job has completed
8225 Arguments
8227 type: JobType
8228 job type
8229 device: string
8231 The job identifier. Originally the device name but other values
8232 are allowed since QEMU 2.7
8233 len: int
8235 maximum progress value
8236 offset: int
8238 current progress value. On success this is equal to len. On
8239 failure this is less than len
8240 speed: int
8242 rate limit, bytes per second
8243 error: string (optional)
8245 error message. Only present on failure. This field contains a
8246 human-readable error message. There are no semantics other than
8247 that streaming has failed and clients should not try to inter‐
8248 pret the error string
8249 Since
8251 1.1
8252 Example
8254 <- { "event": "BLOCK_JOB_COMPLETED",
8255 "data": { "type": "stream", "device": "virtio-disk0",
8256 "len": 10737418240, "offset": 10737418240,
8257 "speed": 0 },
8258 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
8259 BLOCK_JOB_CANCELLED (Event)
8261 Emitted when a block job has been cancelled
8262 Arguments
8264 type: JobType
8265 job type
8266 device: string
8268 The job identifier. Originally the device name but other values
8269 are allowed since QEMU 2.7
8270 len: int
8272 maximum progress value
8273 offset: int
8275 current progress value. On success this is equal to len. On
8276 failure this is less than len
8277 speed: int
8279 rate limit, bytes per second
8280 Since
8282 1.1
8283 Example
8285 <- { "event": "BLOCK_JOB_CANCELLED",
8286 "data": { "type": "stream", "device": "virtio-disk0",
8287 "len": 10737418240, "offset": 134217728,
8288 "speed": 0 },
8289 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
8290 BLOCK_JOB_ERROR (Event)
8292 Emitted when a block job encounters an error
8293 Arguments
8295 device: string
8296 The job identifier. Originally the device name but other values
8297 are allowed since QEMU 2.7
8298 operation: IoOperationType
8300 I/O operation
8301 action: BlockErrorAction
8303 action that has been taken
8304 Since
8306 1.3
8307 Example
8309 <- { "event": "BLOCK_JOB_ERROR",
8310 "data": { "device": "ide0-hd1",
8311 "operation": "write",
8312 "action": "stop" },
8313 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8314 BLOCK_JOB_READY (Event)
8316 Emitted when a block job is ready to complete
8317 Arguments
8319 type: JobType
8320 job type
8321 device: string
8323 The job identifier. Originally the device name but other values
8324 are allowed since QEMU 2.7
8325 len: int
8327 maximum progress value
8328 offset: int
8330 current progress value. On success this is equal to len. On
8331 failure this is less than len
8332 speed: int
8334 rate limit, bytes per second
8335 Note
8337 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
8338 event
8339 Since
8341 1.3
8342 Example
8344 <- { "event": "BLOCK_JOB_READY",
8345 "data": { "device": "drive0", "type": "mirror", "speed": 0,
8346 "len": 2097152, "offset": 2097152 }
8347 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8348 BLOCK_JOB_PENDING (Event)
8350 Emitted when a block job is awaiting explicit authorization to finalize
8351 graph changes via block-job-finalize. If this job is part of a transac‐
8352 tion, it will not emit this event until the transaction has converged
8353 first.
8354 Arguments
8356 type: JobType
8357 job type
8358 id: string
8360 The job identifier.
8361 Since
8363 2.12
8364 Example
8366 <- { "event": "BLOCK_JOB_PENDING",
8367 "data": { "type": "mirror", "id": "backup_1" },
8368 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
8369 PreallocMode (Enum)
8371 Preallocation mode of QEMU image file
8372 Values
8374 off no preallocation
8375 metadata
8377 preallocate only for metadata
8378 falloc like full preallocation but allocate disk space by posix_fallo‐
8380 cate() rather than writing data.
8381 full preallocate all data by writing it to the device to ensure disk
8383 space is really available. This data may or may not be zero, de‐
8384 pending on the image format and storage. full preallocation
8385 also sets up metadata correctly.
8386 Since
8388 2.2
8389 BLOCK_WRITE_THRESHOLD (Event)
8391 Emitted when writes on block device reaches or exceeds the configured
8392 write threshold. For thin-provisioned devices, this means the device
8393 should be extended to avoid pausing for disk exhaustion. The event is
8394 one shot. Once triggered, it needs to be re-registered with another
8395 block-set-write-threshold command.
8396 Arguments
8398 node-name: string
8399 graph node name on which the threshold was exceeded.
8400 amount-exceeded: int
8402 amount of data which exceeded the threshold, in bytes.
8403 write-threshold: int
8405 last configured threshold, in bytes.
8406 Since
8408 2.3
8409 block-set-write-threshold (Command)
8411 Change the write threshold for a block drive. An event will be deliv‐
8412 ered if a write to this block drive crosses the configured threshold.
8413 The threshold is an offset, thus must be non-negative. Default is no
8414 write threshold. Setting the threshold to zero disables it.
8415 This is useful to transparently resize thin-provisioned drives without
8417 the guest OS noticing.
8418 Arguments
8420 node-name: string
8421 graph node name on which the threshold must be set.
8422 write-threshold: int
8424 configured threshold for the block device, bytes. Use 0 to dis‐
8425 able the threshold.
8426 Since
8428 2.3
8429 Example
8431 -> { "execute": "block-set-write-threshold",
8432 "arguments": { "node-name": "mydev",
8433 "write-threshold": 17179869184 } }
8434 <- { "return": {} }
8435 x-blockdev-change (Command)
8437 Dynamically reconfigure the block driver state graph. It can be used to
8438 add, remove, insert or replace a graph node. Currently only the Quorum
8439 driver implements this feature to add or remove its child. This is use‐
8440 ful to fix a broken quorum child.
8441 If node is specified, it will be inserted under parent. child may not
8443 be specified in this case. If both parent and child are specified but
8444 node is not, child will be detached from parent.
8445 Arguments
8447 parent: string
8448 the id or name of the parent node.
8449 child: string (optional)
8451 the name of a child under the given parent node.
8452 node: string (optional)
8454 the name of the node that will be added.
8455 Features
8457 unstable
8458 This command is experimental, and its API is not stable. It
8459 does not support all kinds of operations, all kinds of children,
8460 nor all block drivers.
8461 FIXME Removing children from a quorum node means introducing
8463 gaps in the child indices. This cannot be represented in the
8464 'children' list of BlockdevOptionsQuorum, as returned by
8465 .bdrv_refresh_filename().
8466 Warning: The data in a new quorum child MUST be consistent with
8468 that of the rest of the array.
8469 Since
8471 2.7
8472 Example
8474 1. Add a new node to a quorum
8475 -> { "execute": "blockdev-add",
8476 "arguments": {
8477 "driver": "raw",
8478 "node-name": "new_node",
8479 "file": { "driver": "file",
8480 "filename": "test.raw" } } }
8481 <- { "return": {} }
8482 -> { "execute": "x-blockdev-change",
8483 "arguments": { "parent": "disk1",
8484 "node": "new_node" } }
8485 <- { "return": {} }
8486 2. Delete a quorum's node
8488 -> { "execute": "x-blockdev-change",
8489 "arguments": { "parent": "disk1",
8490 "child": "children.1" } }
8491 <- { "return": {} }
8492 x-blockdev-set-iothread (Command)
8494 Move node and its children into the iothread. If iothread is null then
8495 move node and its children into the main loop.
8496 The node must not be attached to a BlockBackend.
8498 Arguments
8500 node-name: string
8501 the name of the block driver node
8502 iothread: StrOrNull
8504 the name of the IOThread object or null for the main loop
8505 force: boolean (optional)
8507 true if the node and its children should be moved when a Block‐
8508 Backend is already attached
8509 Features
8511 unstable
8512 This command is experimental and intended for test cases that
8513 need control over IOThreads only.
8514 Since
8516 2.12
8517 Example
8519 1. Move a node into an IOThread
8520 -> { "execute": "x-blockdev-set-iothread",
8521 "arguments": { "node-name": "disk1",
8522 "iothread": "iothread0" } }
8523 <- { "return": {} }
8524 2. Move a node into the main loop
8526 -> { "execute": "x-blockdev-set-iothread",
8527 "arguments": { "node-name": "disk1",
8528 "iothread": null } }
8529 <- { "return": {} }
8530 QuorumOpType (Enum)
8532 An enumeration of the quorum operation types
8533 Values
8535 read read operation
8536 write write operation
8538 flush flush operation
8540 Since
8542 2.6
8543 QUORUM_FAILURE (Event)
8545 Emitted by the Quorum block driver if it fails to establish a quorum
8546 Arguments
8548 reference: string
8549 device name if defined else node name
8550 sector-num: int
8552 number of the first sector of the failed read operation
8553 sectors-count: int
8555 failed read operation sector count
8556 Note
8558 This event is rate-limited.
8559 Since
8561 2.0
8562 Example
8564 <- { "event": "QUORUM_FAILURE",
8565 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
8566 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
8567 QUORUM_REPORT_BAD (Event)
8569 Emitted to report a corruption of a Quorum file
8570 Arguments
8572 type: QuorumOpType
8573 quorum operation type (Since 2.6)
8574 error: string (optional)
8576 error message. Only present on failure. This field contains a
8577 human-readable error message. There are no semantics other than
8578 that the block layer reported an error and clients should not
8579 try to interpret the error string.
8580 node-name: string
8582 the graph node name of the block driver state
8583 sector-num: int
8585 number of the first sector of the failed read operation
8586 sectors-count: int
8588 failed read operation sector count
8589 Note
8591 This event is rate-limited.
8592 Since
8594 2.0
8595 Example
8597 1. Read operation
8598 { "event": "QUORUM_REPORT_BAD",
8600 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
8601 "type": "read" },
8602 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
8603 2. Flush operation
8605 { "event": "QUORUM_REPORT_BAD",
8607 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
8608 "type": "flush", "error": "Broken pipe" },
8609 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
8610 BlockdevSnapshotInternal (Object)
8612 Members
8613 device: string
8614 the device name or node-name of a root node to generate the
8615 snapshot from
8616 name: string
8618 the name of the internal snapshot to be created
8619 Notes
8621 In transaction, if name is empty, or any snapshot matching name exists,
8622 the operation will fail. Only some image formats support it, for exam‐
8623 ple, qcow2, and rbd.
8624 Since
8626 1.7
8627 blockdev-snapshot-internal-sync (Command)
8629 Synchronously take an internal snapshot of a block device, when the
8630 format of the image used supports it. If the name is an empty string,
8631 or a snapshot with name already exists, the operation will fail.
8632 For the arguments, see the documentation of BlockdevSnapshotInternal.
8634 Returns
8636 • nothing on success
8637 • If device is not a valid block device, GenericError
8639 • If any snapshot matching name exists, or name is empty, GenericError
8641 • If the format of the image used does not support it, BlockFormatFea‐
8643 tureNotSupported
8644 Since
8646 1.7
8647 Example
8649 -> { "execute": "blockdev-snapshot-internal-sync",
8650 "arguments": { "device": "ide-hd0",
8651 "name": "snapshot0" }
8652 }
8653 <- { "return": {} }
8654 blockdev-snapshot-delete-internal-sync (Command)
8656 Synchronously delete an internal snapshot of a block device, when the
8657 format of the image used support it. The snapshot is identified by name
8658 or id or both. One of the name or id is required. Return SnapshotInfo
8659 for the successfully deleted snapshot.
8660 Arguments
8662 device: string
8663 the device name or node-name of a root node to delete the snap‐
8664 shot from
8665 id: string (optional)
8667 optional the snapshot's ID to be deleted
8668 name: string (optional)
8670 optional the snapshot's name to be deleted
8671 Returns
8673 • SnapshotInfo on success
8674 • If device is not a valid block device, GenericError
8676 • If snapshot not found, GenericError
8678 • If the format of the image used does not support it, BlockFormatFea‐
8680 tureNotSupported
8681 • If id and name are both not specified, GenericError
8683 Since
8685 1.7
8686 Example
8688 -> { "execute": "blockdev-snapshot-delete-internal-sync",
8689 "arguments": { "device": "ide-hd0",
8690 "name": "snapshot0" }
8691 }
8692 <- { "return": {
8693 "id": "1",
8694 "name": "snapshot0",
8695 "vm-state-size": 0,
8696 "date-sec": 1000012,
8697 "date-nsec": 10,
8698 "vm-clock-sec": 100,
8699 "vm-clock-nsec": 20,
8700 "icount": 220414
8701 }
8702 }
8703 Additional block stuff (VM related)
8705 BiosAtaTranslation (Enum)
8706 Policy that BIOS should use to interpret cylinder/head/sector ad‐
8707 dresses. Note that Bochs BIOS and SeaBIOS will not actually translate
8708 logical CHS to physical; instead, they will use logical block address‐
8709 ing.
8710 Values
8712 auto If cylinder/heads/sizes are passed, choose between none and LBA
8713 depending on the size of the disk. If they are not passed,
8714 choose none if QEMU can guess that the disk had 16 or fewer
8715 heads, large if QEMU can guess that the disk had 131072 or fewer
8716 tracks across all heads (i.e. cylinders*heads<131072), otherwise
8717 LBA.
8718 none The physical disk geometry is equal to the logical geometry.
8720 lba Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
8722 heads (if fewer than 255 are enough to cover the whole disk with
8723 1024 cylinders/head). The number of cylinders/head is then com‐
8724 puted based on the number of sectors and heads.
8725 large The number of cylinders per head is scaled down to 1024 by cor‐
8727 respondingly scaling up the number of heads.
8728 rechs Same as large, but first convert a 16-head geometry to 15-head,
8730 by proportionally scaling up the number of cylinders/head.
8731 Since
8733 2.0
8734 FloppyDriveType (Enum)
8736 Type of Floppy drive to be emulated by the Floppy Disk Controller.
8737 Values
8739 144 1.44MB 3.5" drive
8740 288 2.88MB 3.5" drive
8742 120 1.2MB 5.25" drive
8744 none No drive connected
8746 auto Automatically determined by inserted media at boot
8748 Since
8750 2.6
8751 PRManagerInfo (Object)
8753 Information about a persistent reservation manager
8754 Members
8756 id: string
8757 the identifier of the persistent reservation manager
8758 connected: boolean
8760 true if the persistent reservation manager is connected to the
8761 underlying storage or helper
8762 Since
8764 3.0
8765 query-pr-managers (Command)
8767 Returns a list of information about each persistent reservation man‐
8768 ager.
8769 Returns
8771 a list of PRManagerInfo for each persistent reservation manager
8772 Since
8774 3.0
8775 eject (Command)
8777 Ejects the medium from a removable drive.
8778 Arguments
8780 device: string (optional)
8781 Block device name
8782 id: string (optional)
8784 The name or QOM path of the guest device (since: 2.8)
8785 force: boolean (optional)
8787 If true, eject regardless of whether the drive is locked. If
8788 not specified, the default value is false.
8789 Features
8791 deprecated
8792 Member device is deprecated. Use id instead.
8793 Returns
8795 • Nothing on success
8796 • If device is not a valid block device, DeviceNotFound
8798 Notes
8800 Ejecting a device with no media results in success
8801 Since
8803 0.14
8804 Example
8806 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
8807 <- { "return": {} }
8808 blockdev-open-tray (Command)
8810 Opens a block device's tray. If there is a block driver state tree in‐
8811 serted as a medium, it will become inaccessible to the guest (but it
8812 will remain associated to the block device, so closing the tray will
8813 make it accessible again).
8814 If the tray was already open before, this will be a no-op.
8816 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
8818 cases in which no such event will be generated, these include:
8819 • if the guest has locked the tray, force is false and the guest does
8821 not respond to the eject request
8822 • if the BlockBackend denoted by device does not have a guest device
8824 attached to it
8825 • if the guest device does not have an actual tray
8827 Arguments
8829 device: string (optional)
8830 Block device name
8831 id: string (optional)
8833 The name or QOM path of the guest device (since: 2.8)
8834 force: boolean (optional)
8836 if false (the default), an eject request will be sent to the
8837 guest if it has locked the tray (and the tray will not be opened
8838 immediately); if true, the tray will be opened regardless of
8839 whether it is locked
8840 Features
8842 deprecated
8843 Member device is deprecated. Use id instead.
8844 Since
8846 2.5
8847 Example
8849 -> { "execute": "blockdev-open-tray",
8850 "arguments": { "id": "ide0-1-0" } }
8851 <- { "timestamp": { "seconds": 1418751016,
8853 "microseconds": 716996 },
8854 "event": "DEVICE_TRAY_MOVED",
8855 "data": { "device": "ide1-cd0",
8856 "id": "ide0-1-0",
8857 "tray-open": true } }
8858 <- { "return": {} }
8860 blockdev-close-tray (Command)
8862 Closes a block device's tray. If there is a block driver state tree as‐
8863 sociated with the block device (which is currently ejected), that tree
8864 will be loaded as the medium.
8865 If the tray was already closed before, this will be a no-op.
8867 Arguments
8869 device: string (optional)
8870 Block device name
8871 id: string (optional)
8873 The name or QOM path of the guest device (since: 2.8)
8874 Features
8876 deprecated
8877 Member device is deprecated. Use id instead.
8878 Since
8880 2.5
8881 Example
8883 -> { "execute": "blockdev-close-tray",
8884 "arguments": { "id": "ide0-1-0" } }
8885 <- { "timestamp": { "seconds": 1418751345,
8887 "microseconds": 272147 },
8888 "event": "DEVICE_TRAY_MOVED",
8889 "data": { "device": "ide1-cd0",
8890 "id": "ide0-1-0",
8891 "tray-open": false } }
8892 <- { "return": {} }
8894 blockdev-remove-medium (Command)
8896 Removes a medium (a block driver state tree) from a block device. That
8897 block device's tray must currently be open (unless there is no attached
8898 guest device).
8899 If the tray is open and there is no medium inserted, this will be a
8901 no-op.
8902 Arguments
8904 id: string
8905 The name or QOM path of the guest device
8906 Since
8908 2.12
8909 Example
8911 -> { "execute": "blockdev-remove-medium",
8912 "arguments": { "id": "ide0-1-0" } }
8913 <- { "error": { "class": "GenericError",
8915 "desc": "Tray of device 'ide0-1-0' is not open" } }
8916 -> { "execute": "blockdev-open-tray",
8918 "arguments": { "id": "ide0-1-0" } }
8919 <- { "timestamp": { "seconds": 1418751627,
8921 "microseconds": 549958 },
8922 "event": "DEVICE_TRAY_MOVED",
8923 "data": { "device": "ide1-cd0",
8924 "id": "ide0-1-0",
8925 "tray-open": true } }
8926 <- { "return": {} }
8928 -> { "execute": "blockdev-remove-medium",
8930 "arguments": { "id": "ide0-1-0" } }
8931 <- { "return": {} }
8933 blockdev-insert-medium (Command)
8935 Inserts a medium (a block driver state tree) into a block device. That
8936 block device's tray must currently be open (unless there is no attached
8937 guest device) and there must be no medium inserted already.
8938 Arguments
8940 id: string
8941 The name or QOM path of the guest device
8942 node-name: string
8944 name of a node in the block driver state graph
8945 Since
8947 2.12
8948 Example
8950 -> { "execute": "blockdev-add",
8951 "arguments": {
8952 "node-name": "node0",
8953 "driver": "raw",
8954 "file": { "driver": "file",
8955 "filename": "fedora.iso" } } }
8956 <- { "return": {} }
8957 -> { "execute": "blockdev-insert-medium",
8959 "arguments": { "id": "ide0-1-0",
8960 "node-name": "node0" } }
8961 <- { "return": {} }
8963 BlockdevChangeReadOnlyMode (Enum)
8965 Specifies the new read-only mode of a block device subject to the
8966 blockdev-change-medium command.
8967 Values
8969 retain Retains the current read-only mode
8970 read-only
8972 Makes the device read-only
8973 read-write
8975 Makes the device writable
8976 Since
8978 2.3
8979 blockdev-change-medium (Command)
8981 Changes the medium inserted into a block device by ejecting the current
8982 medium and loading a new image file which is inserted as the new medium
8983 (this command combines blockdev-open-tray, blockdev-remove-medium,
8984 blockdev-insert-medium and blockdev-close-tray).
8985 Arguments
8987 device: string (optional)
8988 Block device name
8989 id: string (optional)
8991 The name or QOM path of the guest device (since: 2.8)
8992 filename: string
8994 filename of the new image to be loaded
8995 format: string (optional)
8997 format to open the new image with (defaults to the probed for‐
8998 mat)
8999 read-only-mode: BlockdevChangeReadOnlyMode (optional)
9001 change the read-only mode of the device; defaults to 'retain'
9002 Features
9004 deprecated
9005 Member device is deprecated. Use id instead.
9006 Since
9008 2.5
9009 Examples
9011 1. Change a removable medium
9012 -> { "execute": "blockdev-change-medium",
9014 "arguments": { "id": "ide0-1-0",
9015 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
9016 "format": "raw" } }
9017 <- { "return": {} }
9018 2. Load a read-only medium into a writable drive
9020 -> { "execute": "blockdev-change-medium",
9022 "arguments": { "id": "floppyA",
9023 "filename": "/srv/images/ro.img",
9024 "format": "raw",
9025 "read-only-mode": "retain" } }
9026 <- { "error":
9028 { "class": "GenericError",
9029 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
9030 -> { "execute": "blockdev-change-medium",
9032 "arguments": { "id": "floppyA",
9033 "filename": "/srv/images/ro.img",
9034 "format": "raw",
9035 "read-only-mode": "read-only" } }
9036 <- { "return": {} }
9038 DEVICE_TRAY_MOVED (Event)
9040 Emitted whenever the tray of a removable device is moved by the guest
9041 or by HMP/QMP commands
9042 Arguments
9044 device: string
9045 Block device name. This is always present for compatibility rea‐
9046 sons, but it can be empty ("") if the image does not have a de‐
9047 vice name associated.
9048 id: string
9050 The name or QOM path of the guest device (since 2.8)
9051 tray-open: boolean
9053 true if the tray has been opened or false if it has been closed
9054 Since
9056 1.1
9057 Example
9059 <- { "event": "DEVICE_TRAY_MOVED",
9060 "data": { "device": "ide1-cd0",
9061 "id": "/machine/unattached/device[22]",
9062 "tray-open": true
9063 },
9064 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
9065 PR_MANAGER_STATUS_CHANGED (Event)
9067 Emitted whenever the connected status of a persistent reservation man‐
9068 ager changes.
9069 Arguments
9071 id: string
9072 The id of the PR manager object
9073 connected: boolean
9075 true if the PR manager is connected to a backend
9076 Since
9078 3.0
9079 Example
9081 <- { "event": "PR_MANAGER_STATUS_CHANGED",
9082 "data": { "id": "pr-helper0",
9083 "connected": true
9084 },
9085 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
9086 block_set_io_throttle (Command)
9088 Change I/O throttle limits for a block drive.
9089 Since QEMU 2.4, each device with I/O limits is member of a throttle
9091 group.
9092 If two or more devices are members of the same group, the limits will
9094 apply to the combined I/O of the whole group in a round-robin fashion.
9095 Therefore, setting new I/O limits to a device will affect the whole
9096 group.
9097 The name of the group can be specified using the 'group' parameter. If
9099 the parameter is unset, it is assumed to be the current group of that
9100 device. If it's not in any group yet, the name of the device will be
9101 used as the name for its group.
9102 The 'group' parameter can also be used to move a device to a different
9104 group. In this case the limits specified in the parameters will be ap‐
9105 plied to the new group only.
9106 I/O limits can be disabled by setting all of them to 0. In this case
9108 the device will be removed from its group and the rest of its members
9109 will not be affected. The 'group' parameter is ignored.
9110 Arguments
9112 The members of BlockIOThrottle
9113 Returns
9115 • Nothing on success
9116 • If device is not a valid block device, DeviceNotFound
9118 Since
9120 1.1
9121 Example
9123 -> { "execute": "block_set_io_throttle",
9124 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
9125 "bps": 0,
9126 "bps_rd": 0,
9127 "bps_wr": 0,
9128 "iops": 512,
9129 "iops_rd": 0,
9130 "iops_wr": 0,
9131 "bps_max": 0,
9132 "bps_rd_max": 0,
9133 "bps_wr_max": 0,
9134 "iops_max": 0,
9135 "iops_rd_max": 0,
9136 "iops_wr_max": 0,
9137 "bps_max_length": 0,
9138 "iops_size": 0 } }
9139 <- { "return": {} }
9140 -> { "execute": "block_set_io_throttle",
9142 "arguments": { "id": "ide0-1-0",
9143 "bps": 1000000,
9144 "bps_rd": 0,
9145 "bps_wr": 0,
9146 "iops": 0,
9147 "iops_rd": 0,
9148 "iops_wr": 0,
9149 "bps_max": 8000000,
9150 "bps_rd_max": 0,
9151 "bps_wr_max": 0,
9152 "iops_max": 0,
9153 "iops_rd_max": 0,
9154 "iops_wr_max": 0,
9155 "bps_max_length": 60,
9156 "iops_size": 0 } }
9157 <- { "return": {} }
9158 block-latency-histogram-set (Command)
9160 Manage read, write and flush latency histograms for the device.
9161 If only id parameter is specified, remove all present latency his‐
9163 tograms for the device. Otherwise, add/reset some of (or all) latency
9164 histograms.
9165 Arguments
9167 id: string
9168 The name or QOM path of the guest device.
9169 boundaries: array of int (optional)
9171 list of interval boundary values (see description in BlockLaten‐
9172 cyHistogramInfo definition). If specified, all latency his‐
9173 tograms are removed, and empty ones created for all io types
9174 with intervals corresponding to boundaries (except for io types,
9175 for which specific boundaries are set through the following pa‐
9176 rameters).
9177 boundaries-read: array of int (optional)
9179 list of interval boundary values for read latency histogram. If
9180 specified, old read latency histogram is removed, and empty one
9181 created with intervals corresponding to boundaries-read. The pa‐
9182 rameter has higher priority then boundaries.
9183 boundaries-write: array of int (optional)
9185 list of interval boundary values for write latency histogram.
9186 boundaries-flush: array of int (optional)
9188 list of interval boundary values for flush latency histogram.
9189 Returns
9191 error if device is not found or any boundary arrays are invalid.
9192 Since
9194 4.0
9195 Example
9197 set new histograms for all io types with intervals
9198 [0, 10), [10, 50), [50, 100), [100, +inf):
9199 -> { "execute": "block-latency-histogram-set",
9201 "arguments": { "id": "drive0",
9202 "boundaries": [10, 50, 100] } }
9203 <- { "return": {} }
9204 Example
9206 set new histogram only for write, other histograms will remain
9207 not changed (or not created):
9208 -> { "execute": "block-latency-histogram-set",
9210 "arguments": { "id": "drive0",
9211 "boundaries-write": [10, 50, 100] } }
9212 <- { "return": {} }
9213 Example
9215 set new histograms with the following intervals:
9216 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
9217 write: [0, 1000), [1000, 5000), [5000, +inf)
9218 -> { "execute": "block-latency-histogram-set",
9220 "arguments": { "id": "drive0",
9221 "boundaries": [10, 50, 100],
9222 "boundaries-write": [1000, 5000] } }
9223 <- { "return": {} }
9224 Example
9226 remove all latency histograms:
9227 -> { "execute": "block-latency-histogram-set",
9229 "arguments": { "id": "drive0" } }
9230 <- { "return": {} }
9231 Block device exports
9233 NbdServerOptions (Object)
9234 Keep this type consistent with the nbd-server-start arguments. The only
9235 intended difference is using SocketAddress instead of SocketAddressLe‐
9236 gacy.
9237 Members
9239 addr: SocketAddress
9240 Address on which to listen.
9241 tls-creds: string (optional)
9243 ID of the TLS credentials object (since 2.6).
9244 tls-authz: string (optional)
9246 ID of the QAuthZ authorization object used to validate the
9247 client's x509 distinguished name. This object is is only re‐
9248 solved at time of use, so can be deleted and recreated on the
9249 fly while the NBD server is active. If missing, it will default
9250 to denying access (since 4.0).
9251 max-connections: int (optional)
9253 The maximum number of connections to allow at the same time, 0
9254 for unlimited. (since 5.2; default: 0)
9255 Since
9257 4.2
9258 nbd-server-start (Command)
9260 Start an NBD server listening on the given host and port. Block de‐
9261 vices can then be exported using nbd-server-add. The NBD server will
9262 present them as named exports; for example, another QEMU instance could
9263 refer to them as "nbd:HOST:PORT:exportname=NAME".
9264 Keep this type consistent with the NbdServerOptions type. The only in‐
9266 tended difference is using SocketAddressLegacy instead of SocketAd‐
9267 dress.
9268 Arguments
9270 addr: SocketAddressLegacy
9271 Address on which to listen.
9272 tls-creds: string (optional)
9274 ID of the TLS credentials object (since 2.6).
9275 tls-authz: string (optional)
9277 ID of the QAuthZ authorization object used to validate the
9278 client's x509 distinguished name. This object is is only re‐
9279 solved at time of use, so can be deleted and recreated on the
9280 fly while the NBD server is active. If missing, it will default
9281 to denying access (since 4.0).
9282 max-connections: int (optional)
9284 The maximum number of connections to allow at the same time, 0
9285 for unlimited. (since 5.2; default: 0)
9286 Returns
9288 error if the server is already running.
9289 Since
9291 1.3
9292 BlockExportOptionsNbdBase (Object)
9294 An NBD block export (common options shared between nbd-server-add and
9295 the NBD branch of block-export-add).
9296 Members
9298 name: string (optional)
9299 Export name. If unspecified, the device parameter is used as the
9300 export name. (Since 2.12)
9301 description: string (optional)
9303 Free-form description of the export, up to 4096 bytes. (Since
9304 5.0)
9305 Since
9307 5.0
9308 BlockExportOptionsNbd (Object)
9310 An NBD block export (distinct options used in the NBD branch of
9311 block-export-add).
9312 Members
9314 bitmaps: array of string (optional)
9315 Also export each of the named dirty bitmaps reachable from de‐
9316 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
9317 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
9318 each bitmap.
9319 allocation-depth: boolean (optional)
9321 Also export the allocation depth map for device, so the NBD
9322 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
9323 text name "qemu:allocation-depth" to inspect allocation details.
9324 (since 5.2)
9325 The members of BlockExportOptionsNbdBase
9327 Since
9329 5.2
9330 BlockExportOptionsVhostUserBlk (Object)
9332 A vhost-user-blk block export.
9333 Members
9335 addr: SocketAddress
9336 The vhost-user socket on which to listen. Both 'unix' and 'fd'
9337 SocketAddress types are supported. Passed fds must be UNIX do‐
9338 main sockets.
9339 logical-block-size: int (optional)
9341 Logical block size in bytes. Defaults to 512 bytes.
9342 num-queues: int (optional)
9344 Number of request virtqueues. Must be greater than 0. Defaults
9345 to 1.
9346 Since
9348 5.2
9349 FuseExportAllowOther (Enum)
9351 Possible allow_other modes for FUSE exports.
9352 Values
9354 off Do not pass allow_other as a mount option.
9355 on Pass allow_other as a mount option.
9357 auto Try mounting with allow_other first, and if that fails, retry
9359 without allow_other.
9360 Since
9362 6.1
9363 BlockExportOptionsFuse (Object)
9365 Options for exporting a block graph node on some (file) mountpoint as a
9366 raw image.
9367 Members
9369 mountpoint: string
9370 Path on which to export the block device via FUSE. This must
9371 point to an existing regular file.
9372 growable: boolean (optional)
9374 Whether writes beyond the EOF should grow the block node accord‐
9375 ingly. (default: false)
9376 allow-other: FuseExportAllowOther (optional)
9378 If this is off, only qemu's user is allowed access to this ex‐
9379 port. That cannot be changed even with chmod or chown. En‐
9380 abling this option will allow other users access to the export
9381 with the FUSE mount option "allow_other". Note that using al‐
9382 low_other as a non-root user requires user_allow_other to be en‐
9383 abled in the global fuse.conf configuration file. In auto mode
9384 (the default), the FUSE export driver will first attempt to
9385 mount the export with allow_other, and if that fails, try again
9386 without. (since 6.1; default: auto)
9387 Since
9389 6.0
9390 If
9392 CONFIG_FUSE
9393 NbdServerAddOptions (Object)
9395 An NBD block export, per legacy nbd-server-add command.
9396 Members
9398 device: string
9399 The device name or node name of the node to be exported
9400 writable: boolean (optional)
9402 Whether clients should be able to write to the device via the
9403 NBD connection (default false).
9404 bitmap: string (optional)
9406 Also export a single dirty bitmap reachable from device, so the
9407 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
9408 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
9409 (since 4.0).
9410 The members of BlockExportOptionsNbdBase
9412 Since
9414 5.0
9415 nbd-server-add (Command)
9417 Export a block node to QEMU's embedded NBD server.
9418 The export name will be used as the id for the resulting block export.
9420 Arguments
9422 The members of NbdServerAddOptions
9423 Features
9425 deprecated
9426 This command is deprecated. Use block-export-add instead.
9427 Returns
9429 error if the server is not running, or export with the same name al‐
9430 ready exists.
9431 Since
9433 1.3
9434 BlockExportRemoveMode (Enum)
9436 Mode for removing a block export.
9437 Values
9439 safe Remove export if there are no existing connections, fail other‐
9440 wise.
9441 hard Drop all connections immediately and remove export.
9443 TODO
9445 Potential additional modes to be added in the future:
9446 hide: Just hide export from new clients, leave existing connections as
9448 is. Remove export after all clients are disconnected.
9449 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
9451 ther requests from existing clients.
9452 Since
9454 2.12
9455 nbd-server-remove (Command)
9457 Remove NBD export by name.
9458 Arguments
9460 name: string
9461 Block export id.
9462 mode: BlockExportRemoveMode (optional)
9464 Mode of command operation. See BlockExportRemoveMode descrip‐
9465 tion. Default is 'safe'.
9466 Features
9468 deprecated
9469 This command is deprecated. Use block-export-del instead.
9470 Returns
9472 error if
9473 • the server is not running
9475 • export is not found
9477 • mode is 'safe' and there are existing connections
9479 Since
9481 2.12
9482 nbd-server-stop (Command)
9484 Stop QEMU's embedded NBD server, and unregister all devices previously
9485 added via nbd-server-add.
9486 Since
9488 1.3
9489 BlockExportType (Enum)
9491 An enumeration of block export types
9492 Values
9494 nbd NBD export
9495 vhost-user-blk (If: CONFIG_VHOST_USER_BLK_SERVER)
9497 vhost-user-blk export (since 5.2)
9498 fuse (If: CONFIG_FUSE)
9500 FUSE export (since: 6.0)
9501 Since
9503 4.2
9504 BlockExportOptions (Object)
9506 Describes a block export, i.e. how single node should be exported on an
9507 external interface.
9508 Members
9510 id: string
9511 A unique identifier for the block export (across all export
9512 types)
9513 node-name: string
9515 The node name of the block node to be exported (since: 5.2)
9516 writable: boolean (optional)
9518 True if clients should be able to write to the export (default
9519 false)
9520 writethrough: boolean (optional)
9522 If true, caches are flushed after every write request to the ex‐
9523 port before completion is signalled. (since: 5.2; default:
9524 false)
9525 iothread: string (optional)
9527 The name of the iothread object where the export will run. The
9528 default is to use the thread currently associated with the block
9529 node. (since: 5.2)
9530 fixed-iothread: boolean (optional)
9532 True prevents the block node from being moved to another thread
9533 while the export is active. If true and iothread is given, ex‐
9534 port creation fails if the block node cannot be moved to the io‐
9535 thread. The default is false. (since: 5.2)
9536 type: BlockExportType
9538 Not documented
9539 The members of BlockExportOptionsNbd when type is "nbd"
9541 The members of BlockExportOptionsVhostUserBlk when type is
9543 "vhost-user-blk" (If: CONFIG_VHOST_USER_BLK_SERVER)
9544 The members of BlockExportOptionsFuse when type is "fuse" (If: CON‐
9546 FIG_FUSE)
9547 Since
9549 4.2
9550 block-export-add (Command)
9552 Creates a new block export.
9553 Arguments
9555 The members of BlockExportOptions
9556 Since
9558 5.2
9559 block-export-del (Command)
9561 Request to remove a block export. This drops the user's reference to
9562 the export, but the export may still stay around after this command re‐
9563 turns until the shutdown of the export has completed.
9564 Arguments
9566 id: string
9567 Block export id.
9568 mode: BlockExportRemoveMode (optional)
9570 Mode of command operation. See BlockExportRemoveMode descrip‐
9571 tion. Default is 'safe'.
9572 Returns
9574 Error if the export is not found or mode is 'safe' and the export is
9575 still in use (e.g. by existing client connections)
9576 Since
9578 5.2
9579 BLOCK_EXPORT_DELETED (Event)
9581 Emitted when a block export is removed and its id can be reused.
9582 Arguments
9584 id: string
9585 Block export id.
9586 Since
9588 5.2
9589 BlockExportInfo (Object)
9591 Information about a single block export.
9592 Members
9594 id: string
9595 The unique identifier for the block export
9596 type: BlockExportType
9598 The block export type
9599 node-name: string
9601 The node name of the block node that is exported
9602 shutting-down: boolean
9604 True if the export is shutting down (e.g. after a block-ex‐
9605 port-del command, but before the shutdown has completed)
9606 Since
9608 5.2
9609 query-block-exports (Command)
9611 Returns
9612 A list of BlockExportInfo describing all block exports
9613 Since
9615 5.2
9616
9618 ChardevInfo (Object)
9619 Information about a character device.
9620 Members
9622 label: string
9623 the label of the character device
9624 filename: string
9626 the filename of the character device
9627 frontend-open: boolean
9629 shows whether the frontend device attached to this backend (eg.
9630 with the chardev=... option) is in open or closed state (since
9631 2.1)
9632 Notes
9634 filename is encoded using the QEMU command line character device encod‐
9635 ing. See the QEMU man page for details.
9636 Since
9638 0.14
9639 query-chardev (Command)
9641 Returns information about current character devices.
9642 Returns
9644 a list of ChardevInfo
9645 Since
9647 0.14
9648 Example
9650 -> { "execute": "query-chardev" }
9651 <- {
9652 "return": [
9653 {
9654 "label": "charchannel0",
9655 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
9656 "frontend-open": false
9657 },
9658 {
9659 "label": "charmonitor",
9660 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
9661 "frontend-open": true
9662 },
9663 {
9664 "label": "charserial0",
9665 "filename": "pty:/dev/pts/2",
9666 "frontend-open": true
9667 }
9668 ]
9669 }
9670 ChardevBackendInfo (Object)
9672 Information about a character device backend
9673 Members
9675 name: string
9676 The backend name
9677 Since
9679 2.0
9680 query-chardev-backends (Command)
9682 Returns information about character device backends.
9683 Returns
9685 a list of ChardevBackendInfo
9686 Since
9688 2.0
9689 Example
9691 -> { "execute": "query-chardev-backends" }
9692 <- {
9693 "return":[
9694 {
9695 "name":"udp"
9696 },
9697 {
9698 "name":"tcp"
9699 },
9700 {
9701 "name":"unix"
9702 },
9703 {
9704 "name":"spiceport"
9705 }
9706 ]
9707 }
9708 DataFormat (Enum)
9710 An enumeration of data format.
9711 Values
9713 utf8 Data is a UTF-8 string (RFC 3629)
9714 base64 Data is Base64 encoded binary (RFC 3548)
9716 Since
9718 1.4
9719 ringbuf-write (Command)
9721 Write to a ring buffer character device.
9722 Arguments
9724 device: string
9725 the ring buffer character device name
9726 data: string
9728 data to write
9729 format: DataFormat (optional)
9731 data encoding (default 'utf8').
9732 • base64: data must be base64 encoded text. Its binary decoding
9734 gets written.
9735 • utf8: data's UTF-8 encoding is written
9737 • data itself is always Unicode regardless of format, like any
9739 other string.
9740 Returns
9742 Nothing on success
9743 Since
9745 1.4
9746 Example
9748 -> { "execute": "ringbuf-write",
9749 "arguments": { "device": "foo",
9750 "data": "abcdefgh",
9751 "format": "utf8" } }
9752 <- { "return": {} }
9753 ringbuf-read (Command)
9755 Read from a ring buffer character device.
9756 Arguments
9758 device: string
9759 the ring buffer character device name
9760 size: int
9762 how many bytes to read at most
9763 format: DataFormat (optional)
9765 data encoding (default 'utf8').
9766 • base64: the data read is returned in base64 encoding.
9768 • utf8: the data read is interpreted as UTF-8. Bug: can screw
9770 up when the buffer contains invalid UTF-8 sequences, NUL char‐
9771 acters, after the ring buffer lost data, and when reading
9772 stops because the size limit is reached.
9773 • The return value is always Unicode regardless of format, like
9775 any other string.
9776 Returns
9778 data read from the device
9779 Since
9781 1.4
9782 Example
9784 -> { "execute": "ringbuf-read",
9785 "arguments": { "device": "foo",
9786 "size": 1000,
9787 "format": "utf8" } }
9788 <- { "return": "abcdefgh" }
9789 ChardevCommon (Object)
9791 Configuration shared across all chardev backends
9792 Members
9794 logfile: string (optional)
9795 The name of a logfile to save output
9796 logappend: boolean (optional)
9798 true to append instead of truncate (default to false to trun‐
9799 cate)
9800 Since
9802 2.6
9803 ChardevFile (Object)
9805 Configuration info for file chardevs.
9806 Members
9808 in: string (optional)
9809 The name of the input file
9810 out: string
9812 The name of the output file
9813 append: boolean (optional)
9815 Open the file in append mode (default false to truncate) (Since
9816 2.6)
9817 The members of ChardevCommon
9819 Since
9821 1.4
9822 ChardevHostdev (Object)
9824 Configuration info for device and pipe chardevs.
9825 Members
9827 device: string
9828 The name of the special file for the device, i.e. /dev/ttyS0 on
9829 Unix or COM1: on Windows
9830 The members of ChardevCommon
9832 Since
9834 1.4
9835 ChardevSocket (Object)
9837 Configuration info for (stream) socket chardevs.
9838 Members
9840 addr: SocketAddressLegacy
9841 socket address to listen on (server=true) or connect to
9842 (server=false)
9843 tls-creds: string (optional)
9845 the ID of the TLS credentials object (since 2.6)
9846 tls-authz: string (optional)
9848 the ID of the QAuthZ authorization object against which the
9849 client's x509 distinguished name will be validated. This object
9850 is only resolved at time of use, so can be deleted and recreated
9851 on the fly while the chardev server is active. If missing, it
9852 will default to denying access (since 4.0)
9853 server: boolean (optional)
9855 create server socket (default: true)
9856 wait: boolean (optional)
9858 wait for incoming connection on server sockets (default: false).
9859 Silently ignored with server: false. This use is deprecated.
9860 nodelay: boolean (optional)
9862 set TCP_NODELAY socket option (default: false)
9863 telnet: boolean (optional)
9865 enable telnet protocol on server sockets (default: false)
9866 tn3270: boolean (optional)
9868 enable tn3270 protocol on server sockets (default: false)
9869 (Since: 2.10)
9870 websocket: boolean (optional)
9872 enable websocket protocol on server sockets (default: false)
9873 (Since: 3.1)
9874 reconnect: int (optional)
9876 For a client socket, if a socket is disconnected, then attempt a
9877 reconnect after the given number of seconds. Setting this to
9878 zero disables this function. (default: 0) (Since: 2.2)
9879 The members of ChardevCommon
9881 Since
9883 1.4
9884 ChardevUdp (Object)
9886 Configuration info for datagram socket chardevs.
9887 Members
9889 remote: SocketAddressLegacy
9890 remote address
9891 local: SocketAddressLegacy (optional)
9893 local address
9894 The members of ChardevCommon
9896 Since
9898 1.5
9899 ChardevMux (Object)
9901 Configuration info for mux chardevs.
9902 Members
9904 chardev: string
9905 name of the base chardev.
9906 The members of ChardevCommon
9908 Since
9910 1.5
9911 ChardevStdio (Object)
9913 Configuration info for stdio chardevs.
9914 Members
9916 signal: boolean (optional)
9917 Allow signals (such as SIGINT triggered by ^C) be delivered to
9918 qemu. Default: true.
9919 The members of ChardevCommon
9921 Since
9923 1.5
9924 ChardevSpiceChannel (Object)
9926 Configuration info for spice vm channel chardevs.
9927 Members
9929 type: string
9930 kind of channel (for example vdagent).
9931 The members of ChardevCommon
9933 Since
9935 1.5
9936 If
9938 CONFIG_SPICE
9939 ChardevSpicePort (Object)
9941 Configuration info for spice port chardevs.
9942 Members
9944 fqdn: string
9945 name of the channel (see docs/spice-port-fqdn.txt)
9946 The members of ChardevCommon
9948 Since
9950 1.5
9951 If
9953 CONFIG_SPICE
9954 ChardevDBus (Object)
9956 Configuration info for DBus chardevs.
9957 Members
9959 name: string
9960 name of the channel (following docs/spice-port-fqdn.txt)
9961 The members of ChardevCommon
9963 Since
9965 7.0
9966 If
9968 CONFIG_DBUS_DISPLAY
9969 ChardevVC (Object)
9971 Configuration info for virtual console chardevs.
9972 Members
9974 width: int (optional)
9975 console width, in pixels
9976 height: int (optional)
9978 console height, in pixels
9979 cols: int (optional)
9981 console width, in chars
9982 rows: int (optional)
9984 console height, in chars
9985 The members of ChardevCommon
9987 Since
9989 1.5
9990 ChardevRingbuf (Object)
9992 Configuration info for ring buffer chardevs.
9993 Members
9995 size: int (optional)
9996 ring buffer size, must be power of two, default is 65536
9997 The members of ChardevCommon
9999 Since
10001 1.5
10002 ChardevQemuVDAgent (Object)
10004 Configuration info for qemu vdagent implementation.
10005 Members
10007 mouse: boolean (optional)
10008 enable/disable mouse, default is enabled.
10009 clipboard: boolean (optional)
10011 enable/disable clipboard, default is disabled.
10012 The members of ChardevCommon
10014 Since
10016 6.1
10017 If
10019 CONFIG_SPICE_PROTOCOL
10020 ChardevBackendKind (Enum)
10022 Values
10023 pipe Since 1.5
10024 udp Since 1.5
10026 mux Since 1.5
10028 msmouse
10030 Since 1.5
10031 wctablet
10033 Since 2.9
10034 braille
10036 Since 1.5
10037 testdev
10039 Since 2.2
10040 stdio Since 1.5
10042 console
10044 Since 1.5
10045 spicevmc (If: CONFIG_SPICE)
10047 Since 1.5
10048 spiceport (If: CONFIG_SPICE)
10050 Since 1.5
10051 qemu-vdagent (If: CONFIG_SPICE_PROTOCOL)
10053 Since 6.1
10054 dbus (If: CONFIG_DBUS_DISPLAY)
10056 Since 7.0
10057 vc v1.5
10059 ringbuf
10061 Since 1.6
10062 memory Since 1.5
10064 file Not documented
10066 serial Not documented
10068 parallel
10070 Not documented
10071 socket Not documented
10073 pty Not documented
10075 null Not documented
10077 Since
10079 1.4
10080 ChardevFileWrapper (Object)
10082 Members
10083 data: ChardevFile
10084 Not documented
10085 Since
10087 1.4
10088 ChardevHostdevWrapper (Object)
10090 Members
10091 data: ChardevHostdev
10092 Not documented
10093 Since
10095 1.4
10096 ChardevSocketWrapper (Object)
10098 Members
10099 data: ChardevSocket
10100 Not documented
10101 Since
10103 1.4
10104 ChardevUdpWrapper (Object)
10106 Members
10107 data: ChardevUdp
10108 Not documented
10109 Since
10111 1.5
10112 ChardevCommonWrapper (Object)
10114 Members
10115 data: ChardevCommon
10116 Not documented
10117 Since
10119 2.6
10120 ChardevMuxWrapper (Object)
10122 Members
10123 data: ChardevMux
10124 Not documented
10125 Since
10127 1.5
10128 ChardevStdioWrapper (Object)
10130 Members
10131 data: ChardevStdio
10132 Not documented
10133 Since
10135 1.5
10136 ChardevSpiceChannelWrapper (Object)
10138 Members
10139 data: ChardevSpiceChannel
10140 Not documented
10141 Since
10143 1.5
10144 If
10146 CONFIG_SPICE
10147 ChardevSpicePortWrapper (Object)
10149 Members
10150 data: ChardevSpicePort
10151 Not documented
10152 Since
10154 1.5
10155 If
10157 CONFIG_SPICE
10158 ChardevQemuVDAgentWrapper (Object)
10160 Members
10161 data: ChardevQemuVDAgent
10162 Not documented
10163 Since
10165 6.1
10166 If
10168 CONFIG_SPICE_PROTOCOL
10169 ChardevDBusWrapper (Object)
10171 Members
10172 data: ChardevDBus
10173 Not documented
10174 Since
10176 7.0
10177 If
10179 CONFIG_DBUS_DISPLAY
10180 ChardevVCWrapper (Object)
10182 Members
10183 data: ChardevVC
10184 Not documented
10185 Since
10187 1.5
10188 ChardevRingbufWrapper (Object)
10190 Members
10191 data: ChardevRingbuf
10192 Not documented
10193 Since
10195 1.5
10196 ChardevBackend (Object)
10198 Configuration info for the new chardev backend.
10199 Members
10201 type: ChardevBackendKind
10202 Not documented
10203 The members of ChardevFileWrapper when type is "file"
10205 The members of ChardevHostdevWrapper when type is "serial"
10207 The members of ChardevHostdevWrapper when type is "parallel"
10209 The members of ChardevHostdevWrapper when type is "pipe"
10211 The members of ChardevSocketWrapper when type is "socket"
10213 The members of ChardevUdpWrapper when type is "udp"
10215 The members of ChardevCommonWrapper when type is "pty"
10217 The members of ChardevCommonWrapper when type is "null"
10219 The members of ChardevMuxWrapper when type is "mux"
10221 The members of ChardevCommonWrapper when type is "msmouse"
10223 The members of ChardevCommonWrapper when type is "wctablet"
10225 The members of ChardevCommonWrapper when type is "braille"
10227 The members of ChardevCommonWrapper when type is "testdev"
10229 The members of ChardevStdioWrapper when type is "stdio"
10231 The members of ChardevCommonWrapper when type is "console"
10233 The members of ChardevSpiceChannelWrapper when type is "spicevmc" (If:
10235 CONFIG_SPICE)
10236 The members of ChardevSpicePortWrapper when type is "spiceport" (If:
10238 CONFIG_SPICE)
10239 The members of ChardevQemuVDAgentWrapper when type is "qemu-vdagent"
10241 (If: CONFIG_SPICE_PROTOCOL)
10242 The members of ChardevDBusWrapper when type is "dbus" (If: CON‐
10244 FIG_DBUS_DISPLAY)
10245 The members of ChardevVCWrapper when type is "vc"
10247 The members of ChardevRingbufWrapper when type is "ringbuf"
10249 The members of ChardevRingbufWrapper when type is "memory"
10251 Since
10253 1.4
10254 ChardevReturn (Object)
10256 Return info about the chardev backend just created.
10257 Members
10259 pty: string (optional)
10260 name of the slave pseudoterminal device, present if and only if
10261 a chardev of type 'pty' was created
10262 Since
10264 1.4
10265 chardev-add (Command)
10267 Add a character device backend
10268 Arguments
10270 id: string
10271 the chardev's ID, must be unique
10272 backend: ChardevBackend
10274 backend type and parameters
10275 Returns
10277 ChardevReturn.
10278 Since
10280 1.4
10281 Example
10283 -> { "execute" : "chardev-add",
10284 "arguments" : { "id" : "foo",
10285 "backend" : { "type" : "null", "data" : {} } } }
10286 <- { "return": {} }
10287 -> { "execute" : "chardev-add",
10289 "arguments" : { "id" : "bar",
10290 "backend" : { "type" : "file",
10291 "data" : { "out" : "/tmp/bar.log" } } } }
10292 <- { "return": {} }
10293 -> { "execute" : "chardev-add",
10295 "arguments" : { "id" : "baz",
10296 "backend" : { "type" : "pty", "data" : {} } } }
10297 <- { "return": { "pty" : "/dev/pty/42" } }
10298 chardev-change (Command)
10300 Change a character device backend
10301 Arguments
10303 id: string
10304 the chardev's ID, must exist
10305 backend: ChardevBackend
10307 new backend type and parameters
10308 Returns
10310 ChardevReturn.
10311 Since
10313 2.10
10314 Example
10316 -> { "execute" : "chardev-change",
10317 "arguments" : { "id" : "baz",
10318 "backend" : { "type" : "pty", "data" : {} } } }
10319 <- { "return": { "pty" : "/dev/pty/42" } }
10320 -> {"execute" : "chardev-change",
10322 "arguments" : {
10323 "id" : "charchannel2",
10324 "backend" : {
10325 "type" : "socket",
10326 "data" : {
10327 "addr" : {
10328 "type" : "unix" ,
10329 "data" : {
10330 "path" : "/tmp/charchannel2.socket"
10331 }
10332 },
10333 "server" : true,
10334 "wait" : false }}}}
10335 <- {"return": {}}
10336 chardev-remove (Command)
10338 Remove a character device backend
10339 Arguments
10341 id: string
10342 the chardev's ID, must exist and not be in use
10343 Returns
10345 Nothing on success
10346 Since
10348 1.4
10349 Example
10351 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
10352 <- { "return": {} }
10353 chardev-send-break (Command)
10355 Send a break to a character device
10356 Arguments
10358 id: string
10359 the chardev's ID, must exist
10360 Returns
10362 Nothing on success
10363 Since
10365 2.10
10366 Example
10368 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
10369 <- { "return": {} }
10370 VSERPORT_CHANGE (Event)
10372 Emitted when the guest opens or closes a virtio-serial port.
10373 Arguments
10375 id: string
10376 device identifier of the virtio-serial port
10377 open: boolean
10379 true if the guest has opened the virtio-serial port
10380 Note
10382 This event is rate-limited.
10383 Since
10385 2.1
10386 Example
10388 <- { "event": "VSERPORT_CHANGE",
10389 "data": { "id": "channel0", "open": true },
10390 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
10391
10393 DumpGuestMemoryFormat (Enum)
10394 An enumeration of guest-memory-dump's format.
10395 Values
10397 elf elf format
10398 kdump-zlib
10400 kdump-compressed format with zlib-compressed
10401 kdump-lzo
10403 kdump-compressed format with lzo-compressed
10404 kdump-snappy
10406 kdump-compressed format with snappy-compressed
10407 win-dmp
10409 Windows full crashdump format, can be used instead of ELF con‐
10410 verting (since 2.13)
10411 Since
10413 2.0
10414 dump-guest-memory (Command)
10416 Dump guest's memory to vmcore. It is a synchronous operation that can
10417 take very long depending on the amount of guest memory.
10418 Arguments
10420 paging: boolean
10421 if true, do paging to get guest's memory mapping. This allows
10422 using gdb to process the core file.
10423 IMPORTANT: this option can make QEMU allocate several gigabytes
10425 of RAM. This can happen for a large guest, or a malicious guest
10426 pretending to be large.
10427 Also, paging=true has the following limitations:
10429 1. The guest may be in a catastrophic state or can have cor‐
10431 rupted memory, which cannot be trusted
10432 2. The guest can be in real-mode even if paging is enabled.
10434 For example, the guest uses ACPI to sleep, and ACPI sleep
10435 state goes in real-mode
10436 3. Currently only supported on i386 and x86_64.
10438 protocol: string
10440 the filename or file descriptor of the vmcore. The supported
10441 protocols are:
10442 1. file: the protocol starts with "file:", and the following
10444 string is the file's path.
10445 2. fd: the protocol starts with "fd:", and the following string
10447 is the fd's name.
10448 detach: boolean (optional)
10450 if true, QMP will return immediately rather than waiting for the
10451 dump to finish. The user can track progress using "query-dump".
10452 (since 2.6).
10453 begin: int (optional)
10455 if specified, the starting physical address.
10456 length: int (optional)
10458 if specified, the memory size, in bytes. If you don't want to
10459 dump all guest's memory, please specify the start begin and
10460 length
10461 format: DumpGuestMemoryFormat (optional)
10463 if specified, the format of guest memory dump. But non-elf for‐
10464 mat is conflict with paging and filter, ie. paging, begin and
10465 length is not allowed to be specified with non-elf format at the
10466 same time (since 2.0)
10467 Note
10469 All boolean arguments default to false
10470 Returns
10472 nothing on success
10473 Since
10475 1.2
10476 Example
10478 -> { "execute": "dump-guest-memory",
10479 "arguments": { "paging": false, "protocol": "fd:dump" } }
10480 <- { "return": {} }
10481 DumpStatus (Enum)
10483 Describe the status of a long-running background guest memory dump.
10484 Values
10486 none no dump-guest-memory has started yet.
10487 active there is one dump running in background.
10489 completed
10491 the last dump has finished successfully.
10492 failed the last dump has failed.
10494 Since
10496 2.6
10497 DumpQueryResult (Object)
10499 The result format for 'query-dump'.
10500 Members
10502 status: DumpStatus
10503 enum of DumpStatus, which shows current dump status
10504 completed: int
10506 bytes written in latest dump (uncompressed)
10507 total: int
10509 total bytes to be written in latest dump (uncompressed)
10510 Since
10512 2.6
10513 query-dump (Command)
10515 Query latest dump status.
10516 Returns
10518 A DumpStatus object showing the dump status.
10519 Since
10521 2.6
10522 Example
10524 -> { "execute": "query-dump" }
10525 <- { "return": { "status": "active", "completed": 1024000,
10526 "total": 2048000 } }
10527 DUMP_COMPLETED (Event)
10529 Emitted when background dump has completed
10530 Arguments
10532 result: DumpQueryResult
10533 final dump status
10534 error: string (optional)
10536 human-readable error string that provides hint on why dump
10537 failed. Only presents on failure. The user should not try to in‐
10538 terpret the error string.
10539 Since
10541 2.6
10542 Example
10544 <- { "event": "DUMP_COMPLETED",
10545 "data": { "result": { "total": 1090650112, "status": "completed",
10546 "completed": 1090650112 } },
10547 "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }
10548 DumpGuestMemoryCapability (Object)
10550 A list of the available formats for dump-guest-memory
10551 Members
10553 formats: array of DumpGuestMemoryFormat
10554 Not documented
10555 Since
10557 2.0
10558 query-dump-guest-memory-capability (Command)
10560 Returns the available formats for dump-guest-memory
10561 Returns
10563 A DumpGuestMemoryCapability object listing available formats for
10564 dump-guest-memory
10565 Since
10567 2.0
10568 Example
10570 -> { "execute": "query-dump-guest-memory-capability" }
10571 <- { "return": { "formats":
10572 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
10573
10575 set_link (Command)
10576 Sets the link status of a virtual network adapter.
10577 Arguments
10579 name: string
10580 the device name of the virtual network adapter
10581 up: boolean
10583 true to set the link status to be up
10584 Returns
10586 Nothing on success If name is not a valid network device, DeviceNot‐
10587 Found
10588 Since
10590 0.14
10591 Notes
10593 Not all network adapters support setting link status. This command
10594 will succeed even if the network adapter does not support link status
10595 notification.
10596 Example
10598 -> { "execute": "set_link",
10599 "arguments": { "name": "e1000.0", "up": false } }
10600 <- { "return": {} }
10601 netdev_add (Command)
10603 Add a network backend.
10604 Additional arguments depend on the type.
10606 Arguments
10608 The members of Netdev
10609 Since
10611 0.14
10612 Returns
10614 Nothing on success If type is not a valid network backend, DeviceNot‐
10615 Found
10616 Example
10618 -> { "execute": "netdev_add",
10619 "arguments": { "type": "user", "id": "netdev1",
10620 "dnssearch": [ { "str": "example.org" } ] } }
10621 <- { "return": {} }
10622 netdev_del (Command)
10624 Remove a network backend.
10625 Arguments
10627 id: string
10628 the name of the network backend to remove
10629 Returns
10631 Nothing on success If id is not a valid network backend, DeviceNotFound
10632 Since
10634 0.14
10635 Example
10637 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
10638 <- { "return": {} }
10639 NetLegacyNicOptions (Object)
10641 Create a new Network Interface Card.
10642 Members
10644 netdev: string (optional)
10645 id of -netdev to connect to
10646 macaddr: string (optional)
10648 MAC address
10649 model: string (optional)
10651 device model (e1000, rtl8139, virtio etc.)
10652 addr: string (optional)
10654 PCI device address
10655 vectors: int (optional)
10657 number of MSI-x vectors, 0 to disable MSI-X
10658 Since
10660 1.2
10661 NetdevUserOptions (Object)
10663 Use the user mode network stack which requires no administrator privi‐
10664 lege to run.
10665 Members
10667 hostname: string (optional)
10668 client hostname reported by the builtin DHCP server
10669 restrict: boolean (optional)
10671 isolate the guest from the host
10672 ipv4: boolean (optional)
10674 whether to support IPv4, default true for enabled (since 2.6)
10675 ipv6: boolean (optional)
10677 whether to support IPv6, default true for enabled (since 2.6)
10678 ip: string (optional)
10680 legacy parameter, use net= instead
10681 net: string (optional)
10683 IP network address that the guest will see, in the form
10684 addr[/netmask] The netmask is optional, and can be either in the
10685 form a.b.c.d or as a number of valid top-most bits. Default is
10686 10.0.2.0/24.
10687 host: string (optional)
10689 guest-visible address of the host
10690 tftp: string (optional)
10692 root directory of the built-in TFTP server
10693 bootfile: string (optional)
10695 BOOTP filename, for use with tftp=
10696 dhcpstart: string (optional)
10698 the first of the 16 IPs the built-in DHCP server can assign
10699 dns: string (optional)
10701 guest-visible address of the virtual nameserver
10702 dnssearch: array of String (optional)
10704 list of DNS suffixes to search, passed as DHCP option to the
10705 guest
10706 domainname: string (optional)
10708 guest-visible domain name of the virtual nameserver (since 3.0)
10709 ipv6-prefix: string (optional)
10711 IPv6 network prefix (default is fec0::) (since 2.6). The network
10712 prefix is given in the usual hexadecimal IPv6 address notation.
10713 ipv6-prefixlen: int (optional)
10715 IPv6 network prefix length (default is 64) (since 2.6)
10716 ipv6-host: string (optional)
10718 guest-visible IPv6 address of the host (since 2.6)
10719 ipv6-dns: string (optional)
10721 guest-visible IPv6 address of the virtual nameserver (since 2.6)
10722 smb: string (optional)
10724 root directory of the built-in SMB server
10725 smbserver: string (optional)
10727 IP address of the built-in SMB server
10728 hostfwd: array of String (optional)
10730 redirect incoming TCP or UDP host connections to guest endpoints
10731 guestfwd: array of String (optional)
10733 forward guest TCP connections
10734 tftp-server-name: string (optional)
10736 RFC2132 "TFTP server name" string (Since 3.1)
10737 Since
10739 1.2
10740 NetdevTapOptions (Object)
10742 Used to configure a host TAP network interface backend.
10743 Members
10745 ifname: string (optional)
10746 interface name
10747 fd: string (optional)
10749 file descriptor of an already opened tap
10750 fds: string (optional)
10752 multiple file descriptors of already opened multiqueue capable
10753 tap
10754 script: string (optional)
10756 script to initialize the interface
10757 downscript: string (optional)
10759 script to shut down the interface
10760 br: string (optional)
10762 bridge name (since 2.8)
10763 helper: string (optional)
10765 command to execute to configure bridge
10766 sndbuf: int (optional)
10768 send buffer limit. Understands [TGMKkb] suffixes.
10769 vnet_hdr: boolean (optional)
10771 enable the IFF_VNET_HDR flag on the tap interface
10772 vhost: boolean (optional)
10774 enable vhost-net network accelerator
10775 vhostfd: string (optional)
10777 file descriptor of an already opened vhost net device
10778 vhostfds: string (optional)
10780 file descriptors of multiple already opened vhost net devices
10781 vhostforce: boolean (optional)
10783 vhost on for non-MSIX virtio guests
10784 queues: int (optional)
10786 number of queues to be created for multiqueue capable tap
10787 poll-us: int (optional)
10789 maximum number of microseconds that could be spent on busy
10790 polling for tap (since 2.7)
10791 Since
10793 1.2
10794 NetdevSocketOptions (Object)
10796 Socket netdevs are used to establish a network connection to another
10797 QEMU virtual machine via a TCP socket.
10798 Members
10800 fd: string (optional)
10801 file descriptor of an already opened socket
10802 listen: string (optional)
10804 port number, and optional hostname, to listen on
10805 connect: string (optional)
10807 port number, and optional hostname, to connect to
10808 mcast: string (optional)
10810 UDP multicast address and port number
10811 localaddr: string (optional)
10813 source address and port for multicast and udp packets
10814 udp: string (optional)
10816 UDP unicast address and port number
10817 Since
10819 1.2
10820 NetdevL2TPv3Options (Object)
10822 Configure an Ethernet over L2TPv3 tunnel.
10823 Members
10825 src: string
10826 source address
10827 dst: string
10829 destination address
10830 srcport: string (optional)
10832 source port - mandatory for udp, optional for ip
10833 dstport: string (optional)
10835 destination port - mandatory for udp, optional for ip
10836 ipv6: boolean (optional)
10838 force the use of ipv6
10839 udp: boolean (optional)
10841 use the udp version of l2tpv3 encapsulation
10842 cookie64: boolean (optional)
10844 use 64 bit coookies
10845 counter: boolean (optional)
10847 have sequence counter
10848 pincounter: boolean (optional)
10850 pin sequence counter to zero - workaround for buggy implementa‐
10851 tions or networks with packet reorder
10852 txcookie: int (optional)
10854 32 or 64 bit transmit cookie
10855 rxcookie: int (optional)
10857 32 or 64 bit receive cookie
10858 txsession: int
10860 32 bit transmit session
10861 rxsession: int (optional)
10863 32 bit receive session - if not specified set to the same value
10864 as transmit
10865 offset: int (optional)
10867 additional offset - allows the insertion of additional applica‐
10868 tion-specific data before the packet payload
10869 Since
10871 2.1
10872 NetdevVdeOptions (Object)
10874 Connect to a vde switch running on the host.
10875 Members
10877 sock: string (optional)
10878 socket path
10879 port: int (optional)
10881 port number
10882 group: string (optional)
10884 group owner of socket
10885 mode: int (optional)
10887 permissions for socket
10888 Since
10890 1.2
10891 NetdevBridgeOptions (Object)
10893 Connect a host TAP network interface to a host bridge device.
10894 Members
10896 br: string (optional)
10897 bridge name
10898 helper: string (optional)
10900 command to execute to configure bridge
10901 Since
10903 1.2
10904 NetdevHubPortOptions (Object)
10906 Connect two or more net clients through a software hub.
10907 Members
10909 hubid: int
10910 hub identifier number
10911 netdev: string (optional)
10913 used to connect hub to a netdev instead of a device (since 2.12)
10914 Since
10916 1.2
10917 NetdevNetmapOptions (Object)
10919 Connect a client to a netmap-enabled NIC or to a VALE switch port
10920 Members
10922 ifname: string
10923 Either the name of an existing network interface supported by
10924 netmap, or the name of a VALE port (created on the fly). A VALE
10925 port name is in the form 'valeXXX:YYY', where XXX and YYY are
10926 non-negative integers. XXX identifies a switch and YYY identi‐
10927 fies a port of the switch. VALE ports having the same XXX are
10928 therefore connected to the same switch.
10929 devname: string (optional)
10931 path of the netmap device (default: '/dev/netmap').
10932 Since
10934 2.0
10935 NetdevVhostUserOptions (Object)
10937 Vhost-user network backend
10938 Members
10940 chardev: string
10941 name of a unix socket chardev
10942 vhostforce: boolean (optional)
10944 vhost on for non-MSIX virtio guests (default: false).
10945 queues: int (optional)
10947 number of queues to be created for multiqueue vhost-user (de‐
10948 fault: 1) (Since 2.5)
10949 Since
10951 2.1
10952 NetdevVhostVDPAOptions (Object)
10954 Vhost-vdpa network backend
10955 vDPA device is a device that uses a datapath which complies with the
10957 virtio specifications with a vendor specific control path.
10958 Members
10960 vhostdev: string (optional)
10961 path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
10962 queues: int (optional)
10964 number of queues to be created for multiqueue vhost-vdpa (de‐
10965 fault: 1)
10966 Since
10968 5.1
10969 NetClientDriver (Enum)
10971 Available netdev drivers.
10972 Values
10974 none Not documented
10975 nic Not documented
10977 user Not documented
10979 tap Not documented
10981 l2tpv3 Not documented
10983 socket Not documented
10985 vde Not documented
10987 bridge Not documented
10989 hubport
10991 Not documented
10992 netmap Not documented
10994 vhost-user
10996 Not documented
10997 vhost-vdpa
10999 Not documented
11000 Since
11002 2.7
11003 vhost-vdpa since 5.1
11005 Netdev (Object)
11007 Captures the configuration of a network device.
11008 Members
11010 id: string
11011 identifier for monitor commands.
11012 type: NetClientDriver
11014 Specify the driver used for interpreting remaining arguments.
11015 The members of NetLegacyNicOptions when type is "nic"
11017 The members of NetdevUserOptions when type is "user"
11019 The members of NetdevTapOptions when type is "tap"
11021 The members of NetdevL2TPv3Options when type is "l2tpv3"
11023 The members of NetdevSocketOptions when type is "socket"
11025 The members of NetdevVdeOptions when type is "vde"
11027 The members of NetdevBridgeOptions when type is "bridge"
11029 The members of NetdevHubPortOptions when type is "hubport"
11031 The members of NetdevNetmapOptions when type is "netmap"
11033 The members of NetdevVhostUserOptions when type is "vhost-user"
11035 The members of NetdevVhostVDPAOptions when type is "vhost-vdpa"
11037 Since
11039 1.2
11040 'l2tpv3' - since 2.1
11042 RxState (Enum)
11044 Packets receiving state
11045 Values
11047 normal filter assigned packets according to the mac-table
11048 none don't receive any assigned packet
11050 all receive all assigned packets
11052 Since
11054 1.6
11055 RxFilterInfo (Object)
11057 Rx-filter information for a NIC.
11058 Members
11060 name: string
11061 net client name
11062 promiscuous: boolean
11064 whether promiscuous mode is enabled
11065 multicast: RxState
11067 multicast receive state
11068 unicast: RxState
11070 unicast receive state
11071 vlan: RxState
11073 vlan receive state (Since 2.0)
11074 broadcast-allowed: boolean
11076 whether to receive broadcast
11077 multicast-overflow: boolean
11079 multicast table is overflowed or not
11080 unicast-overflow: boolean
11082 unicast table is overflowed or not
11083 main-mac: string
11085 the main macaddr string
11086 vlan-table: array of int
11088 a list of active vlan id
11089 unicast-table: array of string
11091 a list of unicast macaddr string
11092 multicast-table: array of string
11094 a list of multicast macaddr string
11095 Since
11097 1.6
11098 query-rx-filter (Command)
11100 Return rx-filter information for all NICs (or for the given NIC).
11101 Arguments
11103 name: string (optional)
11104 net client name
11105 Returns
11107 list of RxFilterInfo for all NICs (or for the given NIC). Returns an
11108 error if the given name doesn't exist, or given NIC doesn't support
11109 rx-filter querying, or given net client isn't a NIC.
11110 Since
11112 1.6
11113 Example
11115 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
11116 <- { "return": [
11117 {
11118 "promiscuous": true,
11119 "name": "vnet0",
11120 "main-mac": "52:54:00:12:34:56",
11121 "unicast": "normal",
11122 "vlan": "normal",
11123 "vlan-table": [
11124 4,
11125 0
11126 ],
11127 "unicast-table": [
11128 ],
11129 "multicast": "normal",
11130 "multicast-overflow": false,
11131 "unicast-overflow": false,
11132 "multicast-table": [
11133 "01:00:5e:00:00:01",
11134 "33:33:00:00:00:01",
11135 "33:33:ff:12:34:56"
11136 ],
11137 "broadcast-allowed": false
11138 }
11139 ]
11140 }
11141 NIC_RX_FILTER_CHANGED (Event)
11143 Emitted once until the 'query-rx-filter' command is executed, the first
11144 event will always be emitted
11145 Arguments
11147 name: string (optional)
11148 net client name
11149 path: string
11151 device path
11152 Since
11154 1.6
11155 Example
11157 <- { "event": "NIC_RX_FILTER_CHANGED",
11158 "data": { "name": "vnet0",
11159 "path": "/machine/peripheral/vnet0/virtio-backend" },
11160 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
11161 }
11162 AnnounceParameters (Object)
11164 Parameters for self-announce timers
11165 Members
11167 initial: int
11168 Initial delay (in ms) before sending the first GARP/RARP an‐
11169 nouncement
11170 max: int
11172 Maximum delay (in ms) between GARP/RARP announcement packets
11173 rounds: int
11175 Number of self-announcement attempts
11176 step: int
11178 Delay increase (in ms) after each self-announcement attempt
11179 interfaces: array of string (optional)
11181 An optional list of interface names, which restricts the an‐
11182 nouncement to the listed interfaces. (Since 4.1)
11183 id: string (optional)
11185 A name to be used to identify an instance of announce-timers and
11186 to allow it to modified later. Not for use as part of the mi‐
11187 gration parameters. (Since 4.1)
11188 Since
11190 4.0
11191 announce-self (Command)
11193 Trigger generation of broadcast RARP frames to update network switches.
11194 This can be useful when network bonds fail-over the active slave.
11195 Arguments
11197 The members of AnnounceParameters
11198 Example
11200 -> { "execute": "announce-self",
11201 "arguments": {
11202 "initial": 50, "max": 550, "rounds": 10, "step": 50,
11203 "interfaces": ["vn2", "vn3"], "id": "bob" } }
11204 <- { "return": {} }
11205 Since
11207 4.0
11208 FAILOVER_NEGOTIATED (Event)
11210 Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotia‐
11211 tion. Failover primary devices which were hidden (not hotplugged when
11212 requested) before will now be hotplugged by the virtio-net standby de‐
11213 vice.
11214 Arguments
11216 device-id: string
11217 QEMU device id of the unplugged device
11218 Since
11220 4.2
11221 Example
11223 <- { "event": "FAILOVER_NEGOTIATED",
11224 "data": { "device-id": "net1" },
11225 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
11226
11228 RDMA_GID_STATUS_CHANGED (Event)
11229 Emitted when guest driver adds/deletes GID to/from device
11230 Arguments
11232 netdev: string
11233 RoCE Network Device name
11234 gid-status: boolean
11236 Add or delete indication
11237 subnet-prefix: int
11239 Subnet Prefix
11240 interface-id: int
11242 Not documented
11243 interface-id : Interface ID
11244 Since
11246 4.0
11247 Example
11249 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
11250 "event": "RDMA_GID_STATUS_CHANGED",
11251 "data":
11252 {"netdev": "bridge0",
11253 "interface-id": 15880512517475447892,
11254 "gid-status": true,
11255 "subnet-prefix": 33022}}
11256
11258 RockerSwitch (Object)
11259 Rocker switch information.
11260 Members
11262 name: string
11263 switch name
11264 id: int
11266 switch ID
11267 ports: int
11269 number of front-panel ports
11270 Since
11272 2.4
11273 query-rocker (Command)
11275 Return rocker switch information.
11276 Arguments
11278 name: string
11279 Not documented
11280 Returns
11282 Rocker information
11283 Since
11285 2.4
11286 Example
11288 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
11289 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
11290 RockerPortDuplex (Enum)
11292 An eumeration of port duplex states.
11293 Values
11295 half half duplex
11296 full full duplex
11298 Since
11300 2.4
11301 RockerPortAutoneg (Enum)
11303 An eumeration of port autoneg states.
11304 Values
11306 off autoneg is off
11307 on autoneg is on
11309 Since
11311 2.4
11312 RockerPort (Object)
11314 Rocker switch port information.
11315 Members
11317 name: string
11318 port name
11319 enabled: boolean
11321 port is enabled for I/O
11322 link-up: boolean
11324 physical link is UP on port
11325 speed: int
11327 port link speed in Mbps
11328 duplex: RockerPortDuplex
11330 port link duplex
11331 autoneg: RockerPortAutoneg
11333 port link autoneg
11334 Since
11336 2.4
11337 query-rocker-ports (Command)
11339 Return rocker switch port information.
11340 Arguments
11342 name: string
11343 Not documented
11344 Returns
11346 a list of RockerPort information
11347 Since
11349 2.4
11350 Example
11352 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
11353 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
11354 "autoneg": "off", "link-up": true, "speed": 10000},
11355 {"duplex": "full", "enabled": true, "name": "sw1.2",
11356 "autoneg": "off", "link-up": true, "speed": 10000}
11357 ]}
11358 RockerOfDpaFlowKey (Object)
11360 Rocker switch OF-DPA flow key
11361 Members
11363 priority: int
11364 key priority, 0 being lowest priority
11365 tbl-id: int
11367 flow table ID
11368 in-pport: int (optional)
11370 physical input port
11371 tunnel-id: int (optional)
11373 tunnel ID
11374 vlan-id: int (optional)
11376 VLAN ID
11377 eth-type: int (optional)
11379 Ethernet header type
11380 eth-src: string (optional)
11382 Ethernet header source MAC address
11383 eth-dst: string (optional)
11385 Ethernet header destination MAC address
11386 ip-proto: int (optional)
11388 IP Header protocol field
11389 ip-tos: int (optional)
11391 IP header TOS field
11392 ip-dst: string (optional)
11394 IP header destination address
11395 Note
11397 optional members may or may not appear in the flow key depending if
11398 they're relevant to the flow key.
11399 Since
11401 2.4
11402 RockerOfDpaFlowMask (Object)
11404 Rocker switch OF-DPA flow mask
11405 Members
11407 in-pport: int (optional)
11408 physical input port
11409 tunnel-id: int (optional)
11411 tunnel ID
11412 vlan-id: int (optional)
11414 VLAN ID
11415 eth-src: string (optional)
11417 Ethernet header source MAC address
11418 eth-dst: string (optional)
11420 Ethernet header destination MAC address
11421 ip-proto: int (optional)
11423 IP Header protocol field
11424 ip-tos: int (optional)
11426 IP header TOS field
11427 Note
11429 optional members may or may not appear in the flow mask depending if
11430 they're relevant to the flow mask.
11431 Since
11433 2.4
11434 RockerOfDpaFlowAction (Object)
11436 Rocker switch OF-DPA flow action
11437 Members
11439 goto-tbl: int (optional)
11440 next table ID
11441 group-id: int (optional)
11443 group ID
11444 tunnel-lport: int (optional)
11446 tunnel logical port ID
11447 vlan-id: int (optional)
11449 VLAN ID
11450 new-vlan-id: int (optional)
11452 new VLAN ID
11453 out-pport: int (optional)
11455 physical output port
11456 Note
11458 optional members may or may not appear in the flow action depending if
11459 they're relevant to the flow action.
11460 Since
11462 2.4
11463 RockerOfDpaFlow (Object)
11465 Rocker switch OF-DPA flow
11466 Members
11468 cookie: int
11469 flow unique cookie ID
11470 hits: int
11472 count of matches (hits) on flow
11473 key: RockerOfDpaFlowKey
11475 flow key
11476 mask: RockerOfDpaFlowMask
11478 flow mask
11479 action: RockerOfDpaFlowAction
11481 flow action
11482 Since
11484 2.4
11485 query-rocker-of-dpa-flows (Command)
11487 Return rocker OF-DPA flow information.
11488 Arguments
11490 name: string
11491 switch name
11492 tbl-id: int (optional)
11494 flow table ID. If tbl-id is not specified, returns flow infor‐
11495 mation for all tables.
11496 Returns
11498 rocker OF-DPA flow information
11499 Since
11501 2.4
11502 Example
11504 -> { "execute": "query-rocker-of-dpa-flows",
11505 "arguments": { "name": "sw1" } }
11506 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
11507 "hits": 138,
11508 "cookie": 0,
11509 "action": {"goto-tbl": 10},
11510 "mask": {"in-pport": 4294901760}
11511 },
11512 {...more...},
11513 ]}
11514 RockerOfDpaGroup (Object)
11516 Rocker switch OF-DPA group
11517 Members
11519 id: int
11520 group unique ID
11521 type: int
11523 group type
11524 vlan-id: int (optional)
11526 VLAN ID
11527 pport: int (optional)
11529 physical port number
11530 index: int (optional)
11532 group index, unique with group type
11533 out-pport: int (optional)
11535 output physical port number
11536 group-id: int (optional)
11538 next group ID
11539 set-vlan-id: int (optional)
11541 VLAN ID to set
11542 pop-vlan: int (optional)
11544 pop VLAN headr from packet
11545 group-ids: array of int (optional)
11547 list of next group IDs
11548 set-eth-src: string (optional)
11550 set source MAC address in Ethernet header
11551 set-eth-dst: string (optional)
11553 set destination MAC address in Ethernet header
11554 ttl-check: int (optional)
11556 perform TTL check
11557 Note
11559 optional members may or may not appear in the group depending if
11560 they're relevant to the group type.
11561 Since
11563 2.4
11564 query-rocker-of-dpa-groups (Command)
11566 Return rocker OF-DPA group information.
11567 Arguments
11569 name: string
11570 switch name
11571 type: int (optional)
11573 group type. If type is not specified, returns group information
11574 for all group types.
11575 Returns
11577 rocker OF-DPA group information
11578 Since
11580 2.4
11581 Example
11583 -> { "execute": "query-rocker-of-dpa-groups",
11584 "arguments": { "name": "sw1" } }
11585 <- { "return": [ {"type": 0, "out-pport": 2,
11586 "pport": 2, "vlan-id": 3841,
11587 "pop-vlan": 1, "id": 251723778},
11588 {"type": 0, "out-pport": 0,
11589 "pport": 0, "vlan-id": 3841,
11590 "pop-vlan": 1, "id": 251723776},
11591 {"type": 0, "out-pport": 1,
11592 "pport": 1, "vlan-id": 3840,
11593 "pop-vlan": 1, "id": 251658241},
11594 {"type": 0, "out-pport": 0,
11595 "pport": 0, "vlan-id": 3840,
11596 "pop-vlan": 1, "id": 251658240}
11597 ]}
11598
11600 TpmModel (Enum)
11601 An enumeration of TPM models
11602 Values
11604 tpm-tis
11605 TPM TIS model
11606 tpm-crb
11608 TPM CRB model (since 2.12)
11609 tpm-spapr
11611 TPM SPAPR model (since 5.0)
11612 Since
11614 1.5
11615 If
11617 CONFIG_TPM
11618 query-tpm-models (Command)
11620 Return a list of supported TPM models
11621 Returns
11623 a list of TpmModel
11624 Since
11626 1.5
11627 Example
11629 -> { "execute": "query-tpm-models" }
11630 <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
11631 If
11633 CONFIG_TPM
11634 TpmType (Enum)
11636 An enumeration of TPM types
11637 Values
11639 passthrough
11640 TPM passthrough type
11641 emulator
11643 Software Emulator TPM type Since: 2.11
11644 Since
11646 1.5
11647 If
11649 CONFIG_TPM
11650 query-tpm-types (Command)
11652 Return a list of supported TPM types
11653 Returns
11655 a list of TpmType
11656 Since
11658 1.5
11659 Example
11661 -> { "execute": "query-tpm-types" }
11662 <- { "return": [ "passthrough", "emulator" ] }
11663 If
11665 CONFIG_TPM
11666 TPMPassthroughOptions (Object)
11668 Information about the TPM passthrough type
11669 Members
11671 path: string (optional)
11672 string describing the path used for accessing the TPM device
11673 cancel-path: string (optional)
11675 string showing the TPM's sysfs cancel file for cancellation of
11676 TPM commands while they are executing
11677 Since
11679 1.5
11680 If
11682 CONFIG_TPM
11683 TPMEmulatorOptions (Object)
11685 Information about the TPM emulator type
11686 Members
11688 chardev: string
11689 Name of a unix socket chardev
11690 Since
11692 2.11
11693 If
11695 CONFIG_TPM
11696 TPMPassthroughOptionsWrapper (Object)
11698 Members
11699 data: TPMPassthroughOptions
11700 Not documented
11701 Since
11703 1.5
11704 If
11706 CONFIG_TPM
11707 TPMEmulatorOptionsWrapper (Object)
11709 Members
11710 data: TPMEmulatorOptions
11711 Not documented
11712 Since
11714 2.11
11715 If
11717 CONFIG_TPM
11718 TpmTypeOptions (Object)
11720 A union referencing different TPM backend types' configuration options
11721 Members
11723 type: TpmType
11724 • 'passthrough' The configuration options for the TPM
11726 passthrough type
11727 • 'emulator' The configuration options for TPM emulator backend
11729 type
11730 The members of TPMPassthroughOptionsWrapper when type is "passthrough"
11732 The members of TPMEmulatorOptionsWrapper when type is "emulator"
11734 Since
11736 1.5
11737 If
11739 CONFIG_TPM
11740 TPMInfo (Object)
11742 Information about the TPM
11743 Members
11745 id: string
11746 The Id of the TPM
11747 model: TpmModel
11749 The TPM frontend model
11750 options: TpmTypeOptions
11752 The TPM (backend) type configuration options
11753 Since
11755 1.5
11756 If
11758 CONFIG_TPM
11759 query-tpm (Command)
11761 Return information about the TPM device
11762 Returns
11764 TPMInfo on success
11765 Since
11767 1.5
11768 Example
11770 -> { "execute": "query-tpm" }
11771 <- { "return":
11772 [
11773 { "model": "tpm-tis",
11774 "options":
11775 { "type": "passthrough",
11776 "data":
11777 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
11778 "path": "/dev/tpm0"
11779 }
11780 },
11781 "id": "tpm0"
11782 }
11783 ]
11784 }
11785 If
11787 CONFIG_TPM
11788
11790 DisplayProtocol (Enum)
11791 Display protocols which support changing password options.
11792 Values
11794 vnc Not documented
11795 spice Not documented
11797 Since
11799 7.0
11800 SetPasswordAction (Enum)
11802 An action to take on changing a password on a connection with active
11803 clients.
11804 Values
11806 keep maintain existing clients
11807 fail fail the command if clients are connected
11809 disconnect
11811 disconnect existing clients
11812 Since
11814 7.0
11815 SetPasswordOptions (Object)
11817 Options for set_password.
11818 Members
11820 protocol: DisplayProtocol
11821 • 'vnc' to modify the VNC server password
11823 • 'spice' to modify the Spice server password
11825 password: string
11827 the new password
11828 connected: SetPasswordAction (optional)
11830 How to handle existing clients when changing the password. If
11831 nothing is specified, defaults to 'keep'. For VNC, only 'keep'
11832 is currently implemented.
11833 The members of SetPasswordOptionsVnc when protocol is "vnc"
11835 Since
11837 7.0
11838 SetPasswordOptionsVnc (Object)
11840 Options for set_password specific to the VNC procotol.
11841 Members
11843 display: string (optional)
11844 The id of the display where the password should be changed. De‐
11845 faults to the first.
11846 Since
11848 7.0
11849 set_password (Command)
11851 Set the password of a remote display server.
11852 Arguments
11854 The members of SetPasswordOptions
11855 Returns
11857 • Nothing on success
11858 • If Spice is not enabled, DeviceNotFound
11860 Since
11862 0.14
11863 Example
11865 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
11866 "password": "secret" } }
11867 <- { "return": {} }
11868 ExpirePasswordOptions (Object)
11870 General options for expire_password.
11871 Members
11873 protocol: DisplayProtocol
11874 • 'vnc' to modify the VNC server expiration
11876 • 'spice' to modify the Spice server expiration
11878 time: string
11880 when to expire the password.
11881 • 'now' to expire the password immediately
11883 • 'never' to cancel password expiration
11885 • '+INT' where INT is the number of seconds from now (integer)
11887 • 'INT' where INT is the absolute time in seconds
11889 The members of ExpirePasswordOptionsVnc when protocol is "vnc"
11891 Notes
11893 Time is relative to the server and currently there is no way to coordi‐
11894 nate server time with client time. It is not recommended to use the
11895 absolute time version of the time parameter unless you're sure you are
11896 on the same machine as the QEMU instance.
11897 Since
11899 7.0
11900 ExpirePasswordOptionsVnc (Object)
11902 Options for expire_password specific to the VNC procotol.
11903 Members
11905 display: string (optional)
11906 The id of the display where the expiration should be changed.
11907 Defaults to the first.
11908 Since
11910 7.0
11911 expire_password (Command)
11913 Expire the password of a remote display server.
11914 Arguments
11916 The members of ExpirePasswordOptions
11917 Returns
11919 • Nothing on success
11920 • If protocol is 'spice' and Spice is not active, DeviceNotFound
11922 Since
11924 0.14
11925 Example
11927 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
11928 "time": "+60" } }
11929 <- { "return": {} }
11930 screendump (Command)
11932 Write a PPM of the VGA screen to a file.
11933 Arguments
11935 filename: string
11936 the path of a new PPM file to store the image
11937 device: string (optional)
11939 ID of the display device that should be dumped. If this parame‐
11940 ter is missing, the primary display will be used. (Since 2.12)
11941 head: int (optional)
11943 head to use in case the device supports multiple heads. If this
11944 parameter is missing, head #0 will be used. Also note that the
11945 head can only be specified in conjunction with the device ID.
11946 (Since 2.12)
11947 Returns
11949 Nothing on success
11950 Since
11952 0.14
11953 Example
11955 -> { "execute": "screendump",
11956 "arguments": { "filename": "/tmp/image" } }
11957 <- { "return": {} }
11958 Spice
11960 SpiceBasicInfo (Object)
11961 The basic information for SPICE network connection
11962 Members
11964 host: string
11965 IP address
11966 port: string
11968 port number
11969 family: NetworkAddressFamily
11971 address family
11972 Since
11974 2.1
11975 If
11977 CONFIG_SPICE
11978 SpiceServerInfo (Object)
11980 Information about a SPICE server
11981 Members
11983 auth: string (optional)
11984 authentication method
11985 The members of SpiceBasicInfo
11987 Since
11989 2.1
11990 If
11992 CONFIG_SPICE
11993 SpiceChannel (Object)
11995 Information about a SPICE client channel.
11996 Members
11998 connection-id: int
11999 SPICE connection id number. All channels with the same id be‐
12000 long to the same SPICE session.
12001 channel-type: int
12003 SPICE channel type number. "1" is the main control channel,
12004 filter for this one if you want to track spice sessions only
12005 channel-id: int
12007 SPICE channel ID number. Usually "0", might be different when
12008 multiple channels of the same type exist, such as multiple dis‐
12009 play channels in a multihead setup
12010 tls: boolean
12012 true if the channel is encrypted, false otherwise.
12013 The members of SpiceBasicInfo
12015 Since
12017 0.14
12018 If
12020 CONFIG_SPICE
12021 SpiceQueryMouseMode (Enum)
12023 An enumeration of Spice mouse states.
12024 Values
12026 client Mouse cursor position is determined by the client.
12027 server Mouse cursor position is determined by the server.
12029 unknown
12031 No information is available about mouse mode used by the spice
12032 server.
12033 Note
12035 spice/enums.h has a SpiceMouseMode already, hence the name.
12036 Since
12038 1.1
12039 If
12041 CONFIG_SPICE
12042 SpiceInfo (Object)
12044 Information about the SPICE session.
12045 Members
12047 enabled: boolean
12048 true if the SPICE server is enabled, false otherwise
12049 migrated: boolean
12051 true if the last guest migration completed and spice migration
12052 had completed as well. false otherwise. (since 1.4)
12053 host: string (optional)
12055 The hostname the SPICE server is bound to. This depends on the
12056 name resolution on the host and may be an IP address.
12057 port: int (optional)
12059 The SPICE server's port number.
12060 compiled-version: string (optional)
12062 SPICE server version.
12063 tls-port: int (optional)
12065 The SPICE server's TLS port number.
12066 auth: string (optional)
12068 the current authentication type used by the server
12069 • 'none' if no authentication is being used
12071 • 'spice' uses SASL or direct TLS authentication, depending on
12073 command line options
12074 mouse-mode: SpiceQueryMouseMode
12076 The mode in which the mouse cursor is displayed currently. Can
12077 be determined by the client or the server, or unknown if spice
12078 server doesn't provide this information. (since: 1.1)
12079 channels: array of SpiceChannel (optional)
12081 a list of SpiceChannel for each active spice channel
12082 Since
12084 0.14
12085 If
12087 CONFIG_SPICE
12088 query-spice (Command)
12090 Returns information about the current SPICE server
12091 Returns
12093 SpiceInfo
12094 Since
12096 0.14
12097 Example
12099 -> { "execute": "query-spice" }
12100 <- { "return": {
12101 "enabled": true,
12102 "auth": "spice",
12103 "port": 5920,
12104 "migrated":false,
12105 "tls-port": 5921,
12106 "host": "0.0.0.0",
12107 "mouse-mode":"client",
12108 "channels": [
12109 {
12110 "port": "54924",
12111 "family": "ipv4",
12112 "channel-type": 1,
12113 "connection-id": 1804289383,
12114 "host": "127.0.0.1",
12115 "channel-id": 0,
12116 "tls": true
12117 },
12118 {
12119 "port": "36710",
12120 "family": "ipv4",
12121 "channel-type": 4,
12122 "connection-id": 1804289383,
12123 "host": "127.0.0.1",
12124 "channel-id": 0,
12125 "tls": false
12126 },
12127 [ ... more channels follow ... ]
12128 ]
12129 }
12130 }
12131 If
12133 CONFIG_SPICE
12134 SPICE_CONNECTED (Event)
12136 Emitted when a SPICE client establishes a connection
12137 Arguments
12139 server: SpiceBasicInfo
12140 server information
12141 client: SpiceBasicInfo
12143 client information
12144 Since
12146 0.14
12147 Example
12149 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
12150 "event": "SPICE_CONNECTED",
12151 "data": {
12152 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
12153 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
12154 }}
12155 If
12157 CONFIG_SPICE
12158 SPICE_INITIALIZED (Event)
12160 Emitted after initial handshake and authentication takes place (if any)
12161 and the SPICE channel is up and running
12162 Arguments
12164 server: SpiceServerInfo
12165 server information
12166 client: SpiceChannel
12168 client information
12169 Since
12171 0.14
12172 Example
12174 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
12175 "event": "SPICE_INITIALIZED",
12176 "data": {"server": {"auth": "spice", "port": "5921",
12177 "family": "ipv4", "host": "127.0.0.1"},
12178 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
12179 "connection-id": 1804289383, "host": "127.0.0.1",
12180 "channel-id": 0, "tls": true}
12181 }}
12182 If
12184 CONFIG_SPICE
12185 SPICE_DISCONNECTED (Event)
12187 Emitted when the SPICE connection is closed
12188 Arguments
12190 server: SpiceBasicInfo
12191 server information
12192 client: SpiceBasicInfo
12194 client information
12195 Since
12197 0.14
12198 Example
12200 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
12201 "event": "SPICE_DISCONNECTED",
12202 "data": {
12203 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
12204 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
12205 }}
12206 If
12208 CONFIG_SPICE
12209 SPICE_MIGRATE_COMPLETED (Event)
12211 Emitted when SPICE migration has completed
12212 Since
12214 1.3
12215 Example
12217 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
12218 "event": "SPICE_MIGRATE_COMPLETED" }
12219 If
12221 CONFIG_SPICE
12222 VNC
12224 VncBasicInfo (Object)
12225 The basic information for vnc network connection
12226 Members
12228 host: string
12229 IP address
12230 service: string
12232 The service name of the vnc port. This may depend on the host
12233 system's service database so symbolic names should not be relied
12234 on.
12235 family: NetworkAddressFamily
12237 address family
12238 websocket: boolean
12240 true in case the socket is a websocket (since 2.3).
12241 Since
12243 2.1
12244 If
12246 CONFIG_VNC
12247 VncServerInfo (Object)
12249 The network connection information for server
12250 Members
12252 auth: string (optional)
12253 authentication method used for the plain (non-websocket) VNC
12254 server
12255 The members of VncBasicInfo
12257 Since
12259 2.1
12260 If
12262 CONFIG_VNC
12263 VncClientInfo (Object)
12265 Information about a connected VNC client.
12266 Members
12268 x509_dname: string (optional)
12269 If x509 authentication is in use, the Distinguished Name of the
12270 client.
12271 sasl_username: string (optional)
12273 If SASL authentication is in use, the SASL username used for au‐
12274 thentication.
12275 The members of VncBasicInfo
12277 Since
12279 0.14
12280 If
12282 CONFIG_VNC
12283 VncInfo (Object)
12285 Information about the VNC session.
12286 Members
12288 enabled: boolean
12289 true if the VNC server is enabled, false otherwise
12290 host: string (optional)
12292 The hostname the VNC server is bound to. This depends on the
12293 name resolution on the host and may be an IP address.
12294 family: NetworkAddressFamily (optional)
12296 • 'ipv6' if the host is listening for IPv6 connections
12298 • 'ipv4' if the host is listening for IPv4 connections
12300 • 'unix' if the host is listening on a unix domain socket
12302 • 'unknown' otherwise
12304 service: string (optional)
12306 The service name of the server's port. This may depends on the
12307 host system's service database so symbolic names should not be
12308 relied on.
12309 auth: string (optional)
12311 the current authentication type used by the server
12312 • 'none' if no authentication is being used
12314 • 'vnc' if VNC authentication is being used
12316 • 'vencrypt+plain' if VEncrypt is used with plain text authenti‐
12318 cation
12319 • 'vencrypt+tls+none' if VEncrypt is used with TLS and no au‐
12321 thentication
12322 • 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC au‐
12324 thentication
12325 • 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain
12327 text auth
12328 • 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
12330 • 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
12332 • 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain
12334 text auth
12335 • 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
12337 • 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
12339 auth
12340 clients: array of VncClientInfo (optional)
12342 a list of VncClientInfo of all currently connected clients
12343 Since
12345 0.14
12346 If
12348 CONFIG_VNC
12349 VncPrimaryAuth (Enum)
12351 vnc primary authentication method.
12352 Values
12354 none Not documented
12355 vnc Not documented
12357 ra2 Not documented
12359 ra2ne Not documented
12361 tight Not documented
12363 ultra Not documented
12365 tls Not documented
12367 vencrypt
12369 Not documented
12370 sasl Not documented
12372 Since
12374 2.3
12375 If
12377 CONFIG_VNC
12378 VncVencryptSubAuth (Enum)
12380 vnc sub authentication method with vencrypt.
12381 Values
12383 plain Not documented
12384 tls-none
12386 Not documented
12387 x509-none
12389 Not documented
12390 tls-vnc
12392 Not documented
12393 x509-vnc
12395 Not documented
12396 tls-plain
12398 Not documented
12399 x509-plain
12401 Not documented
12402 tls-sasl
12404 Not documented
12405 x509-sasl
12407 Not documented
12408 Since
12410 2.3
12411 If
12413 CONFIG_VNC
12414 VncServerInfo2 (Object)
12416 The network connection information for server
12417 Members
12419 auth: VncPrimaryAuth
12420 The current authentication type used by the servers
12421 vencrypt: VncVencryptSubAuth (optional)
12423 The vencrypt sub authentication type used by the servers, only
12424 specified in case auth == vencrypt.
12425 The members of VncBasicInfo
12427 Since
12429 2.9
12430 If
12432 CONFIG_VNC
12433 VncInfo2 (Object)
12435 Information about a vnc server
12436 Members
12438 id: string
12439 vnc server name.
12440 server: array of VncServerInfo2
12442 A list of VncBasincInfo describing all listening sockets. The
12443 list can be empty (in case the vnc server is disabled). It also
12444 may have multiple entries: normal + websocket, possibly also
12445 ipv4 + ipv6 in the future.
12446 clients: array of VncClientInfo
12448 A list of VncClientInfo of all currently connected clients. The
12449 list can be empty, for obvious reasons.
12450 auth: VncPrimaryAuth
12452 The current authentication type used by the non-websockets
12453 servers
12454 vencrypt: VncVencryptSubAuth (optional)
12456 The vencrypt authentication type used by the servers, only spec‐
12457 ified in case auth == vencrypt.
12458 display: string (optional)
12460 The display device the vnc server is linked to.
12461 Since
12463 2.3
12464 If
12466 CONFIG_VNC
12467 query-vnc (Command)
12469 Returns information about the current VNC server
12470 Returns
12472 VncInfo
12473 Since
12475 0.14
12476 Example
12478 -> { "execute": "query-vnc" }
12479 <- { "return": {
12480 "enabled":true,
12481 "host":"0.0.0.0",
12482 "service":"50402",
12483 "auth":"vnc",
12484 "family":"ipv4",
12485 "clients":[
12486 {
12487 "host":"127.0.0.1",
12488 "service":"50401",
12489 "family":"ipv4"
12490 "websocket":false,
12491 }
12492 ]
12493 }
12494 }
12495 If
12497 CONFIG_VNC
12498 query-vnc-servers (Command)
12500 Returns a list of vnc servers. The list can be empty.
12501 Returns
12503 a list of VncInfo2
12504 Since
12506 2.3
12507 If
12509 CONFIG_VNC
12510 change-vnc-password (Command)
12512 Change the VNC server password.
12513 Arguments
12515 password: string
12516 the new password to use with VNC authentication
12517 Since
12519 1.1
12520 Notes
12522 An empty password in this command will set the password to the empty
12523 string. Existing clients are unaffected by executing this command.
12524 If
12526 CONFIG_VNC
12527 VNC_CONNECTED (Event)
12529 Emitted when a VNC client establishes a connection
12530 Arguments
12532 server: VncServerInfo
12533 server information
12534 client: VncBasicInfo
12536 client information
12537 Note
12539 This event is emitted before any authentication takes place, thus the
12540 authentication ID is not provided
12541 Since
12543 0.13
12544 Example
12546 <- { "event": "VNC_CONNECTED",
12547 "data": {
12548 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
12549 "service": "5901", "host": "0.0.0.0" },
12550 "client": { "family": "ipv4", "service": "58425",
12551 "host": "127.0.0.1", "websocket": false } },
12552 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
12553 If
12555 CONFIG_VNC
12556 VNC_INITIALIZED (Event)
12558 Emitted after authentication takes place (if any) and the VNC session
12559 is made active
12560 Arguments
12562 server: VncServerInfo
12563 server information
12564 client: VncClientInfo
12566 client information
12567 Since
12569 0.13
12570 Example
12572 <- { "event": "VNC_INITIALIZED",
12573 "data": {
12574 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
12575 "service": "5901", "host": "0.0.0.0"},
12576 "client": { "family": "ipv4", "service": "46089", "websocket": false,
12577 "host": "127.0.0.1", "sasl_username": "luiz" } },
12578 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
12579 If
12581 CONFIG_VNC
12582 VNC_DISCONNECTED (Event)
12584 Emitted when the connection is closed
12585 Arguments
12587 server: VncServerInfo
12588 server information
12589 client: VncClientInfo
12591 client information
12592 Since
12594 0.13
12595 Example
12597 <- { "event": "VNC_DISCONNECTED",
12598 "data": {
12599 "server": { "auth": "sasl", "family": "ipv4", "websocket": false,
12600 "service": "5901", "host": "0.0.0.0" },
12601 "client": { "family": "ipv4", "service": "58425", "websocket": false,
12602 "host": "127.0.0.1", "sasl_username": "luiz" } },
12603 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
12604 If
12606 CONFIG_VNC
12607
12609 MouseInfo (Object)
12610 Information about a mouse device.
12611 Members
12613 name: string
12614 the name of the mouse device
12615 index: int
12617 the index of the mouse device
12618 current: boolean
12620 true if this device is currently receiving mouse events
12621 absolute: boolean
12623 true if this device supports absolute coordinates as input
12624 Since
12626 0.14
12627 query-mice (Command)
12629 Returns information about each active mouse device
12630 Returns
12632 a list of MouseInfo for each device
12633 Since
12635 0.14
12636 Example
12638 -> { "execute": "query-mice" }
12639 <- { "return": [
12640 {
12641 "name":"QEMU Microsoft Mouse",
12642 "index":0,
12643 "current":false,
12644 "absolute":false
12645 },
12646 {
12647 "name":"QEMU PS/2 Mouse",
12648 "index":1,
12649 "current":true,
12650 "absolute":true
12651 }
12652 ]
12653 }
12654 QKeyCode (Enum)
12656 An enumeration of key name.
12657 This is used by the send-key command.
12659 Values
12661 unmapped
12662 since 2.0
12663 pause since 2.0
12665 ro since 2.4
12667 kp_comma
12669 since 2.4
12670 kp_equals
12672 since 2.6
12673 power since 2.6
12675 hiragana
12677 since 2.9
12678 henkan since 2.9
12680 yen since 2.9
12682 sleep since 2.10
12684 wake since 2.10
12686 audionext
12688 since 2.10
12689 audioprev
12691 since 2.10
12692 audiostop
12694 since 2.10
12695 audioplay
12697 since 2.10
12698 audiomute
12700 since 2.10
12701 volumeup
12703 since 2.10
12704 volumedown
12706 since 2.10
12707 mediaselect
12709 since 2.10
12710 mail since 2.10
12712 calculator
12714 since 2.10
12715 computer
12717 since 2.10
12718 ac_home
12720 since 2.10
12721 ac_back
12723 since 2.10
12724 ac_forward
12726 since 2.10
12727 ac_refresh
12729 since 2.10
12730 ac_bookmarks
12732 since 2.10
12733 muhenkan
12735 since 2.12
12736 katakanahiragana
12738 since 2.12
12739 lang1 since 6.1
12741 lang2 since 6.1
12743 shift Not documented
12745 shift_r
12747 Not documented
12748 alt Not documented
12750 alt_r Not documented
12752 ctrl Not documented
12754 ctrl_r Not documented
12756 menu Not documented
12758 esc Not documented
12760 1 Not documented
12762 2 Not documented
12764 3 Not documented
12766 4 Not documented
12768 5 Not documented
12770 6 Not documented
12772 7 Not documented
12774 8 Not documented
12776 9 Not documented
12778 0 Not documented
12780 minus Not documented
12782 equal Not documented
12784 backspace
12786 Not documented
12787 tab Not documented
12789 q Not documented
12791 w Not documented
12793 e Not documented
12795 r Not documented
12797 t Not documented
12799 y Not documented
12801 u Not documented
12803 i Not documented
12805 o Not documented
12807 p Not documented
12809 bracket_left
12811 Not documented
12812 bracket_right
12814 Not documented
12815 ret Not documented
12817 a Not documented
12819 s Not documented
12821 d Not documented
12823 f Not documented
12825 g Not documented
12827 h Not documented
12829 j Not documented
12831 k Not documented
12833 l Not documented
12835 semicolon
12837 Not documented
12838 apostrophe
12840 Not documented
12841 grave_accent
12843 Not documented
12844 backslash
12846 Not documented
12847 z Not documented
12849 x Not documented
12851 c Not documented
12853 v Not documented
12855 b Not documented
12857 n Not documented
12859 m Not documented
12861 comma Not documented
12863 dot Not documented
12865 slash Not documented
12867 asterisk
12869 Not documented
12870 spc Not documented
12872 caps_lock
12874 Not documented
12875 f1 Not documented
12877 f2 Not documented
12879 f3 Not documented
12881 f4 Not documented
12883 f5 Not documented
12885 f6 Not documented
12887 f7 Not documented
12889 f8 Not documented
12891 f9 Not documented
12893 f10 Not documented
12895 num_lock
12897 Not documented
12898 scroll_lock
12900 Not documented
12901 kp_divide
12903 Not documented
12904 kp_multiply
12906 Not documented
12907 kp_subtract
12909 Not documented
12910 kp_add Not documented
12912 kp_enter
12914 Not documented
12915 kp_decimal
12917 Not documented
12918 sysrq Not documented
12920 kp_0 Not documented
12922 kp_1 Not documented
12924 kp_2 Not documented
12926 kp_3 Not documented
12928 kp_4 Not documented
12930 kp_5 Not documented
12932 kp_6 Not documented
12934 kp_7 Not documented
12936 kp_8 Not documented
12938 kp_9 Not documented
12940 less Not documented
12942 f11 Not documented
12944 f12 Not documented
12946 print Not documented
12948 home Not documented
12950 pgup Not documented
12952 pgdn Not documented
12954 end Not documented
12956 left Not documented
12958 up Not documented
12960 down Not documented
12962 right Not documented
12964 insert Not documented
12966 delete Not documented
12968 stop Not documented
12970 again Not documented
12972 props Not documented
12974 undo Not documented
12976 front Not documented
12978 copy Not documented
12980 open Not documented
12982 paste Not documented
12984 find Not documented
12986 cut Not documented
12988 lf Not documented
12990 help Not documented
12992 meta_l Not documented
12994 meta_r Not documented
12996 compose
12998 Not documented
12999 'sysrq' was mistakenly added to hack around the fact that the ps2
13000 driver was not generating correct scancodes sequences when 'alt+print'
13001 was pressed. This flaw is now fixed and the 'sysrq' key serves no fur‐
13002 ther purpose. Any further use of 'sysrq' will be transparently changed
13003 to 'print', so they are effectively synonyms.
13004 Since
13006 1.3
13007 KeyValueKind (Enum)
13009 Values
13010 number Not documented
13011 qcode Not documented
13013 Since
13015 1.3
13016 IntWrapper (Object)
13018 Members
13019 data: int
13020 Not documented
13021 Since
13023 1.3
13024 QKeyCodeWrapper (Object)
13026 Members
13027 data: QKeyCode
13028 Not documented
13029 Since
13031 1.3
13032 KeyValue (Object)
13034 Represents a keyboard key.
13035 Members
13037 type: KeyValueKind
13038 Not documented
13039 The members of IntWrapper when type is "number"
13041 The members of QKeyCodeWrapper when type is "qcode"
13043 Since
13045 1.3
13046 send-key (Command)
13048 Send keys to guest.
13049 Arguments
13051 keys: array of KeyValue
13052 An array of KeyValue elements. All KeyValues in this array are
13053 simultaneously sent to the guest. A KeyValue.number value is
13054 sent directly to the guest, while KeyValue.qcode must be a valid
13055 QKeyCode value
13056 hold-time: int (optional)
13058 time to delay key up events, milliseconds. Defaults to 100
13059 Returns
13061 • Nothing on success
13062 • If key is unknown or redundant, InvalidParameter
13064 Since
13066 1.3
13067 Example
13069 -> { "execute": "send-key",
13070 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
13071 { "type": "qcode", "data": "alt" },
13072 { "type": "qcode", "data": "delete" } ] } }
13073 <- { "return": {} }
13074 InputButton (Enum)
13076 Button of a pointer input device (mouse, tablet).
13077 Values
13079 side front side button of a 5-button mouse (since 2.9)
13080 extra rear side button of a 5-button mouse (since 2.9)
13082 left Not documented
13084 middle Not documented
13086 right Not documented
13088 wheel-up
13090 Not documented
13091 wheel-down
13093 Not documented
13094 wheel-left
13096 Not documented
13097 wheel-right
13099 Not documented
13100 Since
13102 2.0
13103 InputAxis (Enum)
13105 Position axis of a pointer input device (mouse, tablet).
13106 Values
13108 x Not documented
13109 y Not documented
13111 Since
13113 2.0
13114 InputKeyEvent (Object)
13116 Keyboard input event.
13117 Members
13119 key: KeyValue
13120 Which key this event is for.
13121 down: boolean
13123 True for key-down and false for key-up events.
13124 Since
13126 2.0
13127 InputBtnEvent (Object)
13129 Pointer button input event.
13130 Members
13132 button: InputButton
13133 Which button this event is for.
13134 down: boolean
13136 True for key-down and false for key-up events.
13137 Since
13139 2.0
13140 InputMoveEvent (Object)
13142 Pointer motion input event.
13143 Members
13145 axis: InputAxis
13146 Which axis is referenced by value.
13147 value: int
13149 Pointer position. For absolute coordinates the valid range is 0
13150 -> 0x7ffff
13151 Since
13153 2.0
13154 InputEventKind (Enum)
13156 Values
13157 key Not documented
13158 btn Not documented
13160 rel Not documented
13162 abs Not documented
13164 Since
13166 2.0
13167 InputKeyEventWrapper (Object)
13169 Members
13170 data: InputKeyEvent
13171 Not documented
13172 Since
13174 2.0
13175 InputBtnEventWrapper (Object)
13177 Members
13178 data: InputBtnEvent
13179 Not documented
13180 Since
13182 2.0
13183 InputMoveEventWrapper (Object)
13185 Members
13186 data: InputMoveEvent
13187 Not documented
13188 Since
13190 2.0
13191 InputEvent (Object)
13193 Input event union.
13194 Members
13196 type: InputEventKind
13197 the input type, one of:
13198 • 'key': Input event of Keyboard
13200 • 'btn': Input event of pointer buttons
13202 • 'rel': Input event of relative pointer motion
13204 • 'abs': Input event of absolute pointer motion
13206 The members of InputKeyEventWrapper when type is "key"
13208 The members of InputBtnEventWrapper when type is "btn"
13210 The members of InputMoveEventWrapper when type is "rel"
13212 The members of InputMoveEventWrapper when type is "abs"
13214 Since
13216 2.0
13217 input-send-event (Command)
13219 Send input event(s) to guest.
13220 The device and head parameters can be used to send the input event to
13222 specific input devices in case (a) multiple input devices of the same
13223 kind are added to the virtual machine and (b) you have configured input
13224 routing (see docs/multiseat.txt) for those input devices. The parame‐
13225 ters work exactly like the device and head properties of input devices.
13226 If device is missing, only devices that have no input routing config
13227 are admissible. If device is specified, both input devices with and
13228 without input routing config are admissible, but devices with input
13229 routing config take precedence.
13230 Arguments
13232 device: string (optional)
13233 display device to send event(s) to.
13234 head: int (optional)
13236 head to send event(s) to, in case the display device supports
13237 multiple scanouts.
13238 events: array of InputEvent
13240 List of InputEvent union.
13241 Returns
13243 Nothing on success.
13244 Since
13246 2.6
13247 Note
13249 The consoles are visible in the qom tree, under /backend/console[$in‐
13250 dex]. They have a device link and head property, so it is possible to
13251 map which console belongs to which device and display.
13252 Example
13254 1. Press left mouse button.
13255 -> { "execute": "input-send-event",
13257 "arguments": { "device": "video0",
13258 "events": [ { "type": "btn",
13259 "data" : { "down": true, "button": "left" } } ] } }
13260 <- { "return": {} }
13261 -> { "execute": "input-send-event",
13263 "arguments": { "device": "video0",
13264 "events": [ { "type": "btn",
13265 "data" : { "down": false, "button": "left" } } ] } }
13266 <- { "return": {} }
13267 2. Press ctrl-alt-del.
13269 -> { "execute": "input-send-event",
13271 "arguments": { "events": [
13272 { "type": "key", "data" : { "down": true,
13273 "key": {"type": "qcode", "data": "ctrl" } } },
13274 { "type": "key", "data" : { "down": true,
13275 "key": {"type": "qcode", "data": "alt" } } },
13276 { "type": "key", "data" : { "down": true,
13277 "key": {"type": "qcode", "data": "delete" } } } ] } }
13278 <- { "return": {} }
13279 3. Move mouse pointer to absolute coordinates (20000, 400).
13281 -> { "execute": "input-send-event" ,
13283 "arguments": { "events": [
13284 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
13285 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
13286 <- { "return": {} }
13287 DisplayGTK (Object)
13289 GTK display options.
13290 Members
13292 grab-on-hover: boolean (optional)
13293 Grab keyboard input on mouse hover.
13294 zoom-to-fit: boolean (optional)
13296 Zoom guest display to fit into the host window. When turned off
13297 the host window will be resized instead. In case the display
13298 device can notify the guest on window resizes (virtio-gpu) this
13299 will default to "on", assuming the guest will resize the display
13300 to match the window size then. Otherwise it defaults to "off".
13301 Since 3.1
13302 Since
13304 2.12
13305 DisplayEGLHeadless (Object)
13307 EGL headless display options.
13308 Members
13310 rendernode: string (optional)
13311 Which DRM render node should be used. Default is the first
13312 available node on the host.
13313 Since
13315 3.1
13316 DisplayDBus (Object)
13318 DBus display options.
13319 Members
13321 addr: string (optional)
13322 The D-Bus bus address (default to the session bus).
13323 rendernode: string (optional)
13325 Which DRM render node should be used. Default is the first
13326 available node on the host.
13327 p2p: boolean (optional)
13329 Whether to use peer-to-peer connections (accepted through
13330 add_client).
13331 audiodev: string (optional)
13333 Use the specified DBus audiodev to export audio.
13334 Since
13336 7.0
13337 DisplayGLMode (Enum)
13339 Display OpenGL mode.
13340 Values
13342 off Disable OpenGL (default).
13343 on Use OpenGL, pick context type automatically. Would better be
13345 named 'auto' but is called 'on' for backward compatibility with
13346 bool type.
13347 core Use OpenGL with Core (desktop) Context.
13349 es Use OpenGL with ES (embedded systems) Context.
13351 Since
13353 3.0
13354 DisplayCurses (Object)
13356 Curses display options.
13357 Members
13359 charset: string (optional)
13360 Font charset used by guest (default: CP437).
13361 Since
13363 4.0
13364 DisplayCocoa (Object)
13366 Cocoa display options.
13367 Members
13369 left-command-key: boolean (optional)
13370 Enable/disable forwarding of left command key to guest. Allows
13371 command-tab window switching on the host without sending this
13372 key to the guest when "off". Defaults to "on"
13373 full-grab: boolean (optional)
13375 Capture all key presses, including system combos. This requires
13376 accessibility permissions, since it performs a global grab on
13377 key events. (default: off) See
13378 https://support.apple.com/en-in/guide/mac-help/mh32356/mac
13379 swap-opt-cmd: boolean (optional)
13381 Swap the Option and Command keys so that their key codes match
13382 their position on non-Mac keyboards and you can use Meta/Super
13383 and Alt where you expect them. (default: off)
13384 Since
13386 7.0
13387 DisplayType (Enum)
13389 Display (user interface) type.
13390 Values
13392 default
13393 The default user interface, selecting from the first available
13394 of gtk, sdl, cocoa, and vnc.
13395 none No user interface or video output display. The guest will still
13397 see an emulated graphics card, but its output will not be dis‐
13398 played to the QEMU user.
13399 gtk (If: CONFIG_GTK)
13401 The GTK user interface.
13402 sdl (If: CONFIG_SDL)
13404 The SDL user interface.
13405 egl-headless (If: CONFIG_OPENGL and CONFIG_GBM)
13407 No user interface, offload GL operations to a local DRI device.
13408 Graphical display need to be paired with VNC or Spice. (Since
13409 3.1)
13410 curses (If: CONFIG_CURSES)
13412 Display video output via curses. For graphics device models
13413 which support a text mode, QEMU can display this output using a
13414 curses/ncurses interface. Nothing is displayed when the graphics
13415 device is in graphical mode or if the graphics device does not
13416 support a text mode. Generally only the VGA device models sup‐
13417 port text mode.
13418 cocoa (If: CONFIG_COCOA)
13420 The Cocoa user interface.
13421 spice-app (If: CONFIG_SPICE)
13423 Set up a Spice server and run the default associated application
13424 to connect to it. The server will redirect the serial console
13425 and QEMU monitors. (Since 4.0)
13426 dbus (If: CONFIG_DBUS_DISPLAY)
13428 Start a D-Bus service for the display. (Since 7.0)
13429 Since
13431 2.12
13432 DisplayOptions (Object)
13434 Display (user interface) options.
13435 Members
13437 type: DisplayType
13438 Which DisplayType qemu should use.
13439 full-screen: boolean (optional)
13441 Start user interface in fullscreen mode (default: off).
13442 window-close: boolean (optional)
13444 Allow to quit qemu with window close button (default: on).
13445 show-cursor: boolean (optional)
13447 Force showing the mouse cursor (default: off). (since: 5.0)
13448 gl: DisplayGLMode (optional)
13450 Enable OpenGL support (default: off).
13451 The members of DisplayGTK when type is "gtk" (If: CONFIG_GTK)
13453 The members of DisplayCocoa when type is "cocoa" (If: CONFIG_COCOA)
13455 The members of DisplayCurses when type is "curses" (If: CONFIG_CURSES)
13457 The members of DisplayEGLHeadless when type is "egl-headless" (If: CON‐
13459 FIG_OPENGL and CONFIG_GBM)
13460 The members of DisplayDBus when type is "dbus" (If: CONFIG_DBUS_DIS‐
13462 PLAY)
13463 Since
13465 2.12
13466 query-display-options (Command)
13468 Returns information about display configuration
13469 Returns
13471 DisplayOptions
13472 Since
13474 3.1
13475 DisplayReloadType (Enum)
13477 Available DisplayReload types.
13478 Values
13480 vnc VNC display
13481 Since
13483 6.0
13484 DisplayReloadOptionsVNC (Object)
13486 Specify the VNC reload options.
13487 Members
13489 tls-certs: boolean (optional)
13490 reload tls certs or not.
13491 Since
13493 6.0
13494 DisplayReloadOptions (Object)
13496 Options of the display configuration reload.
13497 Members
13499 type: DisplayReloadType
13500 Specify the display type.
13501 The members of DisplayReloadOptionsVNC when type is "vnc"
13503 Since
13505 6.0
13506 display-reload (Command)
13508 Reload display configuration.
13509 Arguments
13511 The members of DisplayReloadOptions
13512 Returns
13514 Nothing on success.
13515 Since
13517 6.0
13518 Example
13520 -> { "execute": "display-reload",
13521 "arguments": { "type": "vnc", "tls-certs": true } }
13522 <- { "return": {} }
13523
13525 QAuthZListPolicy (Enum)
13526 The authorization policy result
13527 Values
13529 deny deny access
13530 allow allow access
13532 Since
13534 4.0
13535 QAuthZListFormat (Enum)
13537 The authorization policy match format
13538 Values
13540 exact an exact string match
13541 glob string with ? and * shell wildcard support
13543 Since
13545 4.0
13546 QAuthZListRule (Object)
13548 A single authorization rule.
13549 Members
13551 match: string
13552 a string or glob to match against a user identity
13553 policy: QAuthZListPolicy
13555 the result to return if match evaluates to true
13556 format: QAuthZListFormat (optional)
13558 the format of the match rule (default 'exact')
13559 Since
13561 4.0
13562 AuthZListProperties (Object)
13564 Properties for authz-list objects.
13565 Members
13567 policy: QAuthZListPolicy (optional)
13568 Default policy to apply when no rule matches (default: deny)
13569 rules: array of QAuthZListRule (optional)
13571 Authorization rules based on matching user
13572 Since
13574 4.0
13575 AuthZListFileProperties (Object)
13577 Properties for authz-listfile objects.
13578 Members
13580 filename: string
13581 File name to load the configuration from. The file must contain
13582 valid JSON for AuthZListProperties.
13583 refresh: boolean (optional)
13585 If true, inotify is used to monitor the file, automatically
13586 reloading changes. If an error occurs during reloading, all au‐
13587 thorizations will fail until the file is next successfully
13588 loaded. (default: true if the binary was built with CONFIG_INO‐
13589 TIFY1, false otherwise)
13590 Since
13592 4.0
13593 AuthZPAMProperties (Object)
13595 Properties for authz-pam objects.
13596 Members
13598 service: string
13599 PAM service name to use for authorization
13600 Since
13602 4.0
13603 AuthZSimpleProperties (Object)
13605 Properties for authz-simple objects.
13606 Members
13608 identity: string
13609 Identifies the allowed user. Its format depends on the network
13610 service that authorization object is associated with. For autho‐
13611 rizing based on TLS x509 certificates, the identity must be the
13612 x509 distinguished name.
13613 Since
13615 4.0
13616
13618 MigrationStats (Object)
13619 Detailed migration status.
13620 Members
13622 transferred: int
13623 amount of bytes already transferred to the target VM
13624 remaining: int
13626 amount of bytes remaining to be transferred to the target VM
13627 total: int
13629 total amount of bytes involved in the migration process
13630 duplicate: int
13632 number of duplicate (zero) pages (since 1.2)
13633 skipped: int
13635 number of skipped zero pages (since 1.5)
13636 normal: int
13638 number of normal pages (since 1.2)
13639 normal-bytes: int
13641 number of normal bytes sent (since 1.2)
13642 dirty-pages-rate: int
13644 number of pages dirtied by second by the guest (since 1.3)
13645 mbps: number
13647 throughput in megabits/sec. (since 1.6)
13648 dirty-sync-count: int
13650 number of times that dirty ram was synchronized (since 2.1)
13651 postcopy-requests: int
13653 The number of page requests received from the destination (since
13654 2.7)
13655 page-size: int
13657 The number of bytes per page for the various page-based statis‐
13658 tics (since 2.10)
13659 multifd-bytes: int
13661 The number of bytes sent through multifd (since 3.0)
13662 pages-per-second: int
13664 the number of memory pages transferred per second (Since 4.0)
13665 precopy-bytes: int
13667 The number of bytes sent in the pre-copy phase (since 7.0).
13668 downtime-bytes: int
13670 The number of bytes sent while the guest is paused (since 7.0).
13671 postcopy-bytes: int
13673 The number of bytes sent during the post-copy phase (since 7.0).
13674 Since
13676 0.14
13677 XBZRLECacheStats (Object)
13679 Detailed XBZRLE migration cache statistics
13680 Members
13682 cache-size: int
13683 XBZRLE cache size
13684 bytes: int
13686 amount of bytes already transferred to the target VM
13687 pages: int
13689 amount of pages transferred to the target VM
13690 cache-miss: int
13692 number of cache miss
13693 cache-miss-rate: number
13695 rate of cache miss (since 2.1)
13696 encoding-rate: number
13698 rate of encoded bytes (since 5.1)
13699 overflow: int
13701 number of overflows
13702 Since
13704 1.2
13705 CompressionStats (Object)
13707 Detailed migration compression statistics
13708 Members
13710 pages: int
13711 amount of pages compressed and transferred to the target VM
13712 busy: int
13714 count of times that no free thread was available to compress
13715 data
13716 busy-rate: number
13718 rate of thread busy
13719 compressed-size: int
13721 amount of bytes after compression
13722 compression-rate: number
13724 rate of compressed size
13725 Since
13727 3.1
13728 MigrationStatus (Enum)
13730 An enumeration of migration status.
13731 Values
13733 none no migration has ever happened.
13734 setup migration process has been initiated.
13736 cancelling
13738 in the process of cancelling migration.
13739 cancelled
13741 cancelling migration is finished.
13742 active in the process of doing migration.
13744 postcopy-active
13746 like active, but now in postcopy mode. (since 2.5)
13747 postcopy-paused
13749 during postcopy but paused. (since 3.0)
13750 postcopy-recover
13752 trying to recover from a paused postcopy. (since 3.0)
13753 completed
13755 migration is finished.
13756 failed some error occurred during migration process.
13758 colo VM is in the process of fault tolerance, VM can not get into
13760 this state unless colo capability is enabled for migration.
13761 (since 2.8)
13762 pre-switchover
13764 Paused before device serialisation. (since 2.11)
13765 device During device serialisation when pause-before-switchover is en‐
13767 abled (since 2.11)
13768 wait-unplug
13770 wait for device unplug request by guest OS to be completed.
13771 (since 4.2)
13772 Since
13774 2.3
13775 VfioStats (Object)
13777 Detailed VFIO devices migration statistics
13778 Members
13780 transferred: int
13781 amount of bytes transferred to the target VM by VFIO devices
13782 Since
13784 5.2
13785 MigrationInfo (Object)
13787 Information about current migration process.
13788 Members
13790 status: MigrationStatus (optional)
13791 MigrationStatus describing the current migration status. If
13792 this field is not returned, no migration process has been initi‐
13793 ated
13794 ram: MigrationStats (optional)
13796 MigrationStats containing detailed migration status, only re‐
13797 turned if status is 'active' or 'completed'(since 1.2)
13798 disk: MigrationStats (optional)
13800 MigrationStats containing detailed disk migration status, only
13801 returned if status is 'active' and it is a block migration
13802 xbzrle-cache: XBZRLECacheStats (optional)
13804 XBZRLECacheStats containing detailed XBZRLE migration statis‐
13805 tics, only returned if XBZRLE feature is on and status is 'ac‐
13806 tive' or 'completed' (since 1.2)
13807 total-time: int (optional)
13809 total amount of milliseconds since migration started. If migra‐
13810 tion has ended, it returns the total migration time. (since 1.2)
13811 downtime: int (optional)
13813 only present when migration finishes correctly total downtime in
13814 milliseconds for the guest. (since 1.3)
13815 expected-downtime: int (optional)
13817 only present while migration is active expected downtime in mil‐
13818 liseconds for the guest in last walk of the dirty bitmap. (since
13819 1.3)
13820 setup-time: int (optional)
13822 amount of setup time in milliseconds before the iterations begin
13823 but after the QMP command is issued. This is designed to provide
13824 an accounting of any activities (such as RDMA pinning) which may
13825 be expensive, but do not actually occur during the iterative mi‐
13826 gration rounds themselves. (since 1.6)
13827 cpu-throttle-percentage: int (optional)
13829 percentage of time guest cpus are being throttled during
13830 auto-converge. This is only present when auto-converge has
13831 started throttling guest cpus. (Since 2.7)
13832 error-desc: string (optional)
13834 the human readable error description string, when status is
13835 'failed'. Clients should not attempt to parse the error strings.
13836 (Since 2.7)
13837 postcopy-blocktime: int (optional)
13839 total time when all vCPU were blocked during postcopy live mi‐
13840 gration. This is only present when the postcopy-blocktime migra‐
13841 tion capability is enabled. (Since 3.0)
13842 postcopy-vcpu-blocktime: array of int (optional)
13844 list of the postcopy blocktime per vCPU. This is only present
13845 when the postcopy-blocktime migration capability is enabled.
13846 (Since 3.0)
13847 compression: CompressionStats (optional)
13849 migration compression statistics, only returned if compression
13850 feature is on and status is 'active' or 'completed' (Since 3.1)
13851 socket-address: array of SocketAddress (optional)
13853 Only used for tcp, to know what the real port is (Since 4.0)
13854 vfio: VfioStats (optional)
13856 VfioStats containing detailed VFIO devices migration statistics,
13857 only returned if VFIO device is present, migration is supported
13858 by all VFIO devices and status is 'active' or 'completed' (since
13859 5.2)
13860 blocked-reasons: array of string (optional)
13862 A list of reasons an outgoing migration is blocked. Present and
13863 non-empty when migration is blocked. (since 6.0)
13864 Since
13866 0.14
13867 query-migrate (Command)
13869 Returns information about current migration process. If migration is
13870 active there will be another json-object with RAM migration status and
13871 if block migration is active another one with block migration status.
13872 Returns
13874 MigrationInfo
13875 Since
13877 0.14
13878 Example
13880 1. Before the first migration
13881 -> { "execute": "query-migrate" }
13883 <- { "return": {} }
13884 2. Migration is done and has succeeded
13886 -> { "execute": "query-migrate" }
13888 <- { "return": {
13889 "status": "completed",
13890 "total-time":12345,
13891 "setup-time":12345,
13892 "downtime":12345,
13893 "ram":{
13894 "transferred":123,
13895 "remaining":123,
13896 "total":246,
13897 "duplicate":123,
13898 "normal":123,
13899 "normal-bytes":123456,
13900 "dirty-sync-count":15
13901 }
13902 }
13903 }
13904 3. Migration is done and has failed
13906 -> { "execute": "query-migrate" }
13908 <- { "return": { "status": "failed" } }
13909 4. Migration is being performed and is not a block migration:
13911 -> { "execute": "query-migrate" }
13913 <- {
13914 "return":{
13915 "status":"active",
13916 "total-time":12345,
13917 "setup-time":12345,
13918 "expected-downtime":12345,
13919 "ram":{
13920 "transferred":123,
13921 "remaining":123,
13922 "total":246,
13923 "duplicate":123,
13924 "normal":123,
13925 "normal-bytes":123456,
13926 "dirty-sync-count":15
13927 }
13928 }
13929 }
13930 5. Migration is being performed and is a block migration:
13932 -> { "execute": "query-migrate" }
13934 <- {
13935 "return":{
13936 "status":"active",
13937 "total-time":12345,
13938 "setup-time":12345,
13939 "expected-downtime":12345,
13940 "ram":{
13941 "total":1057024,
13942 "remaining":1053304,
13943 "transferred":3720,
13944 "duplicate":123,
13945 "normal":123,
13946 "normal-bytes":123456,
13947 "dirty-sync-count":15
13948 },
13949 "disk":{
13950 "total":20971520,
13951 "remaining":20880384,
13952 "transferred":91136
13953 }
13954 }
13955 }
13956 6. Migration is being performed and XBZRLE is active:
13958 -> { "execute": "query-migrate" }
13960 <- {
13961 "return":{
13962 "status":"active",
13963 "total-time":12345,
13964 "setup-time":12345,
13965 "expected-downtime":12345,
13966 "ram":{
13967 "total":1057024,
13968 "remaining":1053304,
13969 "transferred":3720,
13970 "duplicate":10,
13971 "normal":3333,
13972 "normal-bytes":3412992,
13973 "dirty-sync-count":15
13974 },
13975 "xbzrle-cache":{
13976 "cache-size":67108864,
13977 "bytes":20971520,
13978 "pages":2444343,
13979 "cache-miss":2244,
13980 "cache-miss-rate":0.123,
13981 "encoding-rate":80.1,
13982 "overflow":34434
13983 }
13984 }
13985 }
13986 MigrationCapability (Enum)
13988 Migration capabilities enumeration
13989 Values
13991 xbzrle Migration supports xbzrle (Xor Based Zero Run Length Encoding).
13992 This feature allows us to minimize migration traffic for certain
13993 work loads, by sending compressed difference of the pages
13994 rdma-pin-all
13996 Controls whether or not the entire VM memory footprint is
13997 mlock()'d on demand or all at once. Refer to docs/rdma.txt for
13998 usage. Disabled by default. (since 2.0)
13999 zero-blocks
14001 During storage migration encode blocks of zeroes efficiently.
14002 This essentially saves 1MB of zeroes per block on the wire. En‐
14003 abling requires source and target VM to support this feature. To
14004 enable it is sufficient to enable the capability on the source
14005 VM. The feature is disabled by default. (since 1.6)
14006 compress
14008 Use multiple compression threads to accelerate live migration.
14009 This feature can help to reduce the migration traffic, by send‐
14010 ing compressed pages. Please note that if compress and xbzrle
14011 are both on, compress only takes effect in the ram bulk stage,
14012 after that, it will be disabled and only xbzrle takes effect,
14013 this can help to minimize migration traffic. The feature is dis‐
14014 abled by default. (since 2.4 )
14015 events generate events for each migration state change (since 2.4 )
14017 auto-converge
14019 If enabled, QEMU will automatically throttle down the guest to
14020 speed up convergence of RAM migration. (since 1.6)
14021 postcopy-ram
14023 Start executing on the migration target before all of RAM has
14024 been migrated, pulling the remaining pages along as needed. The
14025 capacity must have the same setting on both source and target or
14026 migration will not even start. NOTE: If the migration fails dur‐
14027 ing postcopy the VM will fail. (since 2.6)
14028 x-colo If enabled, migration will never end, and the state of the VM on
14030 the primary side will be migrated continuously to the VM on sec‐
14031 ondary side, this process is called COarse-Grain LOck Stepping
14032 (COLO) for Non-stop Service. (since 2.8)
14033 release-ram
14035 if enabled, qemu will free the migrated ram pages on the source
14036 during postcopy-ram migration. (since 2.9)
14037 block If enabled, QEMU will also migrate the contents of all block de‐
14039 vices. Default is disabled. A possible alternative uses mirror
14040 jobs to a builtin NBD server on the destination, which offers
14041 more flexibility. (Since 2.10)
14042 return-path
14044 If enabled, migration will use the return path even for precopy.
14045 (since 2.10)
14046 pause-before-switchover
14048 Pause outgoing migration before serialising device state and be‐
14049 fore disabling block IO (since 2.11)
14050 multifd
14052 Use more than one fd for migration (since 4.0)
14053 dirty-bitmaps
14055 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
14056 postcopy-blocktime
14058 Calculate downtime for postcopy live migration (since 3.0)
14059 late-block-activate
14061 If enabled, the destination will not activate block devices (and
14062 thus take locks) immediately at the end of migration. (since
14063 3.0)
14064 x-ignore-shared
14066 If enabled, QEMU will not migrate shared memory (since 4.0)
14067 validate-uuid
14069 Send the UUID of the source to allow the destination to ensure
14070 it is the same. (since 4.2)
14071 background-snapshot
14073 If enabled, the migration stream will be a snapshot of the VM
14074 exactly at the point when the migration procedure starts. The VM
14075 RAM is saved with running VM. (since 6.0)
14076 Features
14078 unstable
14079 Members x-colo and x-ignore-shared are experimental.
14080 Since
14082 1.2
14083 MigrationCapabilityStatus (Object)
14085 Migration capability information
14086 Members
14088 capability: MigrationCapability
14089 capability enum
14090 state: boolean
14092 capability state bool
14093 Since
14095 1.2
14096 migrate-set-capabilities (Command)
14098 Enable/Disable the following migration capabilities (like xbzrle)
14099 Arguments
14101 capabilities: array of MigrationCapabilityStatus
14102 json array of capability modifications to make
14103 Since
14105 1.2
14106 Example
14108 -> { "execute": "migrate-set-capabilities" , "arguments":
14109 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
14110 query-migrate-capabilities (Command)
14112 Returns information about the current migration capabilities status
14113 Returns
14115 MigrationCapabilitiesStatus
14116 Since
14118 1.2
14119 Example
14121 -> { "execute": "query-migrate-capabilities" }
14122 <- { "return": [
14123 {"state": false, "capability": "xbzrle"},
14124 {"state": false, "capability": "rdma-pin-all"},
14125 {"state": false, "capability": "auto-converge"},
14126 {"state": false, "capability": "zero-blocks"},
14127 {"state": false, "capability": "compress"},
14128 {"state": true, "capability": "events"},
14129 {"state": false, "capability": "postcopy-ram"},
14130 {"state": false, "capability": "x-colo"}
14131 ]}
14132 MultiFDCompression (Enum)
14134 An enumeration of multifd compression methods.
14135 Values
14137 none no compression.
14138 zlib use zlib compression method.
14140 zstd (If: CONFIG_ZSTD)
14142 use zstd compression method.
14143 Since
14145 5.0
14146 BitmapMigrationBitmapAliasTransform (Object)
14148 Members
14149 persistent: boolean (optional)
14150 If present, the bitmap will be made persistent or transient de‐
14151 pending on this parameter.
14152 Since
14154 6.0
14155 BitmapMigrationBitmapAlias (Object)
14157 Members
14158 name: string
14159 The name of the bitmap.
14160 alias: string
14162 An alias name for migration (for example the bitmap name on the
14163 opposite site).
14164 transform: BitmapMigrationBitmapAliasTransform (optional)
14166 Allows the modification of the migrated bitmap. (since 6.0)
14167 Since
14169 5.2
14170 BitmapMigrationNodeAlias (Object)
14172 Maps a block node name and the bitmaps it has to aliases for dirty bit‐
14173 map migration.
14174 Members
14176 node-name: string
14177 A block node name.
14178 alias: string
14180 An alias block node name for migration (for example the node
14181 name on the opposite site).
14182 bitmaps: array of BitmapMigrationBitmapAlias
14184 Mappings for the bitmaps on this node.
14185 Since
14187 5.2
14188 MigrationParameter (Enum)
14190 Migration parameters enumeration
14191 Values
14193 announce-initial
14194 Initial delay (in milliseconds) before sending the first an‐
14195 nounce (Since 4.0)
14196 announce-max
14198 Maximum delay (in milliseconds) between packets in the announce‐
14199 ment (Since 4.0)
14200 announce-rounds
14202 Number of self-announce packets sent after migration (Since 4.0)
14203 announce-step
14205 Increase in delay (in milliseconds) between subsequent packets
14206 in the announcement (Since 4.0)
14207 compress-level
14209 Set the compression level to be used in live migration, the com‐
14210 pression level is an integer between 0 and 9, where 0 means no
14211 compression, 1 means the best compression speed, and 9 means
14212 best compression ratio which will consume more CPU.
14213 compress-threads
14215 Set compression thread count to be used in live migration, the
14216 compression thread count is an integer between 1 and 255.
14217 compress-wait-thread
14219 Controls behavior when all compression threads are currently
14220 busy. If true (default), wait for a free compression thread to
14221 become available; otherwise, send the page uncompressed. (Since
14222 3.1)
14223 decompress-threads
14225 Set decompression thread count to be used in live migration, the
14226 decompression thread count is an integer between 1 and 255. Usu‐
14227 ally, decompression is at least 4 times as fast as compression,
14228 so set the decompress-threads to the number about 1/4 of com‐
14229 press-threads is adequate.
14230 throttle-trigger-threshold
14232 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
14233 throttling. It is expressed as percentage. The default value is
14234 50. (Since 5.0)
14235 cpu-throttle-initial
14237 Initial percentage of time guest cpus are throttled when migra‐
14238 tion auto-converge is activated. The default value is 20. (Since
14239 2.7)
14240 cpu-throttle-increment
14242 throttle percentage increase each time auto-converge detects
14243 that migration is not making progress. The default value is 10.
14244 (Since 2.7)
14245 cpu-throttle-tailslow
14247 Make CPU throttling slower at tail stage At the tail stage of
14248 throttling, the Guest is very sensitive to CPU percentage while
14249 the cpu-throttle -increment is excessive usually at tail stage.
14250 If this parameter is true, we will compute the ideal CPU per‐
14251 centage used by the Guest, which may exactly make the dirty rate
14252 match the dirty rate threshold. Then we will choose a smaller
14253 throttle increment between the one specified by cpu-throttle-in‐
14254 crement and the one generated by ideal CPU percentage. There‐
14255 fore, it is compatible to traditional throttling, meanwhile the
14256 throttle increment won't be excessive at tail stage. The de‐
14257 fault value is false. (Since 5.1)
14258 tls-creds
14260 ID of the 'tls-creds' object that provides credentials for es‐
14261 tablishing a TLS connection over the migration data channel. On
14262 the outgoing side of the migration, the credentials must be for
14263 a 'client' endpoint, while for the incoming side the credentials
14264 must be for a 'server' endpoint. Setting this will enable TLS
14265 for all migrations. The default is unset, resulting in unsecured
14266 migration at the QEMU level. (Since 2.7)
14267 tls-hostname
14269 hostname of the target host for the migration. This is required
14270 when using x509 based TLS credentials and the migration URI does
14271 not already include a hostname. For example if using fd: or
14272 exec: based migration, the hostname must be provided so that the
14273 server's x509 certificate identity can be validated. (Since 2.7)
14274 tls-authz
14276 ID of the 'authz' object subclass that provides access control
14277 checking of the TLS x509 certificate distinguished name. This
14278 object is only resolved at time of use, so can be deleted and
14279 recreated on the fly while the migration server is active. If
14280 missing, it will default to denying access (Since 4.0)
14281 max-bandwidth
14283 to set maximum speed for migration. maximum speed in bytes per
14284 second. (Since 2.8)
14285 downtime-limit
14287 set maximum tolerated downtime for migration. maximum downtime
14288 in milliseconds (Since 2.8)
14289 x-checkpoint-delay
14291 The delay time (in ms) between two COLO checkpoints in periodic
14292 mode. (Since 2.8)
14293 block-incremental
14295 Affects how much storage is migrated when the block migration
14296 capability is enabled. When false, the entire storage backing
14297 chain is migrated into a flattened image at the destination;
14298 when true, only the active qcow2 layer is migrated and the des‐
14299 tination must already have access to the same backing chain as
14300 was used on the source. (since 2.10)
14301 multifd-channels
14303 Number of channels used to migrate data in parallel. This is the
14304 same number that the number of sockets used for migration. The
14305 default value is 2 (since 4.0)
14306 xbzrle-cache-size
14308 cache size to be used by XBZRLE migration. It needs to be a
14309 multiple of the target page size and a power of 2 (Since 2.11)
14310 max-postcopy-bandwidth
14312 Background transfer bandwidth during postcopy. Defaults to 0
14313 (unlimited). In bytes per second. (Since 3.0)
14314 max-cpu-throttle
14316 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
14317 multifd-compression
14319 Which compression method to use. Defaults to none. (Since 5.0)
14320 multifd-zlib-level
14322 Set the compression level to be used in live migration, the com‐
14323 pression level is an integer between 0 and 9, where 0 means no
14324 compression, 1 means the best compression speed, and 9 means
14325 best compression ratio which will consume more CPU. Defaults to
14326 1. (Since 5.0)
14327 multifd-zstd-level
14329 Set the compression level to be used in live migration, the com‐
14330 pression level is an integer between 0 and 20, where 0 means no
14331 compression, 1 means the best compression speed, and 20 means
14332 best compression ratio which will consume more CPU. Defaults to
14333 1. (Since 5.0)
14334 block-bitmap-mapping
14336 Maps block nodes and bitmaps on them to aliases for the purpose
14337 of dirty bitmap migration. Such aliases may for example be the
14338 corresponding names on the opposite site. The mapping must be
14339 one-to-one, but not necessarily complete: On the source, un‐
14340 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
14341 nored. On the destination, encountering an unmapped alias in
14342 the incoming migration stream will result in a report, and all
14343 further bitmap migration data will then be discarded. Note that
14344 the destination does not know about bitmaps it does not receive,
14345 so there is no limitation or requirement regarding the number of
14346 bitmaps received, or how they are named, or on which nodes they
14347 are placed. By default (when this parameter has never been
14348 set), bitmap names are mapped to themselves. Nodes are mapped
14349 to their block device name if there is one, and to their node
14350 name otherwise. (Since 5.2)
14351 Features
14353 unstable
14354 Member x-checkpoint-delay is experimental.
14355 Since
14357 2.4
14358 MigrateSetParameters (Object)
14360 Members
14361 announce-initial: int (optional)
14362 Initial delay (in milliseconds) before sending the first an‐
14363 nounce (Since 4.0)
14364 announce-max: int (optional)
14366 Maximum delay (in milliseconds) between packets in the announce‐
14367 ment (Since 4.0)
14368 announce-rounds: int (optional)
14370 Number of self-announce packets sent after migration (Since 4.0)
14371 announce-step: int (optional)
14373 Increase in delay (in milliseconds) between subsequent packets
14374 in the announcement (Since 4.0)
14375 compress-level: int (optional)
14377 compression level
14378 compress-threads: int (optional)
14380 compression thread count
14381 compress-wait-thread: boolean (optional)
14383 Controls behavior when all compression threads are currently
14384 busy. If true (default), wait for a free compression thread to
14385 become available; otherwise, send the page uncompressed. (Since
14386 3.1)
14387 decompress-threads: int (optional)
14389 decompression thread count
14390 throttle-trigger-threshold: int (optional)
14392 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
14393 throttling. It is expressed as percentage. The default value is
14394 50. (Since 5.0)
14395 cpu-throttle-initial: int (optional)
14397 Initial percentage of time guest cpus are throttled when migra‐
14398 tion auto-converge is activated. The default value is 20.
14399 (Since 2.7)
14400 cpu-throttle-increment: int (optional)
14402 throttle percentage increase each time auto-converge detects
14403 that migration is not making progress. The default value is 10.
14404 (Since 2.7)
14405 cpu-throttle-tailslow: boolean (optional)
14407 Make CPU throttling slower at tail stage At the tail stage of
14408 throttling, the Guest is very sensitive to CPU percentage while
14409 the cpu-throttle -increment is excessive usually at tail stage.
14410 If this parameter is true, we will compute the ideal CPU per‐
14411 centage used by the Guest, which may exactly make the dirty rate
14412 match the dirty rate threshold. Then we will choose a smaller
14413 throttle increment between the one specified by cpu-throttle-in‐
14414 crement and the one generated by ideal CPU percentage. There‐
14415 fore, it is compatible to traditional throttling, meanwhile the
14416 throttle increment won't be excessive at tail stage. The de‐
14417 fault value is false. (Since 5.1)
14418 tls-creds: StrOrNull (optional)
14420 ID of the 'tls-creds' object that provides credentials for es‐
14421 tablishing a TLS connection over the migration data channel. On
14422 the outgoing side of the migration, the credentials must be for
14423 a 'client' endpoint, while for the incoming side the credentials
14424 must be for a 'server' endpoint. Setting this to a non-empty
14425 string enables TLS for all migrations. An empty string means
14426 that QEMU will use plain text mode for migration, rather than
14427 TLS (Since 2.9) Previously (since 2.7), this was reported by
14428 omitting tls-creds instead.
14429 tls-hostname: StrOrNull (optional)
14431 hostname of the target host for the migration. This is required
14432 when using x509 based TLS credentials and the migration URI does
14433 not already include a hostname. For example if using fd: or
14434 exec: based migration, the hostname must be provided so that the
14435 server's x509 certificate identity can be validated. (Since 2.7)
14436 An empty string means that QEMU will use the hostname associated
14437 with the migration URI, if any. (Since 2.9) Previously (since
14438 2.7), this was reported by omitting tls-hostname instead.
14439 max-bandwidth: int (optional)
14441 to set maximum speed for migration. maximum speed in bytes per
14442 second. (Since 2.8)
14443 downtime-limit: int (optional)
14445 set maximum tolerated downtime for migration. maximum downtime
14446 in milliseconds (Since 2.8)
14447 x-checkpoint-delay: int (optional)
14449 the delay time between two COLO checkpoints. (Since 2.8)
14450 block-incremental: boolean (optional)
14452 Affects how much storage is migrated when the block migration
14453 capability is enabled. When false, the entire storage backing
14454 chain is migrated into a flattened image at the destination;
14455 when true, only the active qcow2 layer is migrated and the des‐
14456 tination must already have access to the same backing chain as
14457 was used on the source. (since 2.10)
14458 multifd-channels: int (optional)
14460 Number of channels used to migrate data in parallel. This is the
14461 same number that the number of sockets used for migration. The
14462 default value is 2 (since 4.0)
14463 xbzrle-cache-size: int (optional)
14465 cache size to be used by XBZRLE migration. It needs to be a
14466 multiple of the target page size and a power of 2 (Since 2.11)
14467 max-postcopy-bandwidth: int (optional)
14469 Background transfer bandwidth during postcopy. Defaults to 0
14470 (unlimited). In bytes per second. (Since 3.0)
14471 max-cpu-throttle: int (optional)
14473 maximum cpu throttle percentage. The default value is 99.
14474 (Since 3.1)
14475 multifd-compression: MultiFDCompression (optional)
14477 Which compression method to use. Defaults to none. (Since 5.0)
14478 multifd-zlib-level: int (optional)
14480 Set the compression level to be used in live migration, the com‐
14481 pression level is an integer between 0 and 9, where 0 means no
14482 compression, 1 means the best compression speed, and 9 means
14483 best compression ratio which will consume more CPU. Defaults to
14484 1. (Since 5.0)
14485 multifd-zstd-level: int (optional)
14487 Set the compression level to be used in live migration, the com‐
14488 pression level is an integer between 0 and 20, where 0 means no
14489 compression, 1 means the best compression speed, and 20 means
14490 best compression ratio which will consume more CPU. Defaults to
14491 1. (Since 5.0)
14492 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
14494 Maps block nodes and bitmaps on them to aliases for the purpose
14495 of dirty bitmap migration. Such aliases may for example be the
14496 corresponding names on the opposite site. The mapping must be
14497 one-to-one, but not necessarily complete: On the source, un‐
14498 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
14499 nored. On the destination, encountering an unmapped alias in
14500 the incoming migration stream will result in a report, and all
14501 further bitmap migration data will then be discarded. Note that
14502 the destination does not know about bitmaps it does not receive,
14503 so there is no limitation or requirement regarding the number of
14504 bitmaps received, or how they are named, or on which nodes they
14505 are placed. By default (when this parameter has never been
14506 set), bitmap names are mapped to themselves. Nodes are mapped
14507 to their block device name if there is one, and to their node
14508 name otherwise. (Since 5.2)
14509 tls-authz: StrOrNull (optional)
14511 Not documented
14512 Features
14514 unstable
14515 Member x-checkpoint-delay is experimental.
14516 Since
14518 2.4
14519 migrate-set-parameters (Command)
14521 Set various migration parameters.
14522 Arguments
14524 The members of MigrateSetParameters
14525 Since
14527 2.4
14528 Example
14530 -> { "execute": "migrate-set-parameters" ,
14531 "arguments": { "compress-level": 1 } }
14532 MigrationParameters (Object)
14534 The optional members aren't actually optional.
14535 Members
14537 announce-initial: int (optional)
14538 Initial delay (in milliseconds) before sending the first an‐
14539 nounce (Since 4.0)
14540 announce-max: int (optional)
14542 Maximum delay (in milliseconds) between packets in the announce‐
14543 ment (Since 4.0)
14544 announce-rounds: int (optional)
14546 Number of self-announce packets sent after migration (Since 4.0)
14547 announce-step: int (optional)
14549 Increase in delay (in milliseconds) between subsequent packets
14550 in the announcement (Since 4.0)
14551 compress-level: int (optional)
14553 compression level
14554 compress-threads: int (optional)
14556 compression thread count
14557 compress-wait-thread: boolean (optional)
14559 Controls behavior when all compression threads are currently
14560 busy. If true (default), wait for a free compression thread to
14561 become available; otherwise, send the page uncompressed. (Since
14562 3.1)
14563 decompress-threads: int (optional)
14565 decompression thread count
14566 throttle-trigger-threshold: int (optional)
14568 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
14569 throttling. It is expressed as percentage. The default value is
14570 50. (Since 5.0)
14571 cpu-throttle-initial: int (optional)
14573 Initial percentage of time guest cpus are throttled when migra‐
14574 tion auto-converge is activated. (Since 2.7)
14575 cpu-throttle-increment: int (optional)
14577 throttle percentage increase each time auto-converge detects
14578 that migration is not making progress. (Since 2.7)
14579 cpu-throttle-tailslow: boolean (optional)
14581 Make CPU throttling slower at tail stage At the tail stage of
14582 throttling, the Guest is very sensitive to CPU percentage while
14583 the cpu-throttle -increment is excessive usually at tail stage.
14584 If this parameter is true, we will compute the ideal CPU per‐
14585 centage used by the Guest, which may exactly make the dirty rate
14586 match the dirty rate threshold. Then we will choose a smaller
14587 throttle increment between the one specified by cpu-throttle-in‐
14588 crement and the one generated by ideal CPU percentage. There‐
14589 fore, it is compatible to traditional throttling, meanwhile the
14590 throttle increment won't be excessive at tail stage. The de‐
14591 fault value is false. (Since 5.1)
14592 tls-creds: string (optional)
14594 ID of the 'tls-creds' object that provides credentials for es‐
14595 tablishing a TLS connection over the migration data channel. On
14596 the outgoing side of the migration, the credentials must be for
14597 a 'client' endpoint, while for the incoming side the credentials
14598 must be for a 'server' endpoint. An empty string means that
14599 QEMU will use plain text mode for migration, rather than TLS
14600 (Since 2.7) Note: 2.8 reports this by omitting tls-creds in‐
14601 stead.
14602 tls-hostname: string (optional)
14604 hostname of the target host for the migration. This is required
14605 when using x509 based TLS credentials and the migration URI does
14606 not already include a hostname. For example if using fd: or
14607 exec: based migration, the hostname must be provided so that the
14608 server's x509 certificate identity can be validated. (Since 2.7)
14609 An empty string means that QEMU will use the hostname associated
14610 with the migration URI, if any. (Since 2.9) Note: 2.8 reports
14611 this by omitting tls-hostname instead.
14612 tls-authz: string (optional)
14614 ID of the 'authz' object subclass that provides access control
14615 checking of the TLS x509 certificate distinguished name. (Since
14616 4.0)
14617 max-bandwidth: int (optional)
14619 to set maximum speed for migration. maximum speed in bytes per
14620 second. (Since 2.8)
14621 downtime-limit: int (optional)
14623 set maximum tolerated downtime for migration. maximum downtime
14624 in milliseconds (Since 2.8)
14625 x-checkpoint-delay: int (optional)
14627 the delay time between two COLO checkpoints. (Since 2.8)
14628 block-incremental: boolean (optional)
14630 Affects how much storage is migrated when the block migration
14631 capability is enabled. When false, the entire storage backing
14632 chain is migrated into a flattened image at the destination;
14633 when true, only the active qcow2 layer is migrated and the des‐
14634 tination must already have access to the same backing chain as
14635 was used on the source. (since 2.10)
14636 multifd-channels: int (optional)
14638 Number of channels used to migrate data in parallel. This is the
14639 same number that the number of sockets used for migration. The
14640 default value is 2 (since 4.0)
14641 xbzrle-cache-size: int (optional)
14643 cache size to be used by XBZRLE migration. It needs to be a
14644 multiple of the target page size and a power of 2 (Since 2.11)
14645 max-postcopy-bandwidth: int (optional)
14647 Background transfer bandwidth during postcopy. Defaults to 0
14648 (unlimited). In bytes per second. (Since 3.0)
14649 max-cpu-throttle: int (optional)
14651 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
14652 multifd-compression: MultiFDCompression (optional)
14654 Which compression method to use. Defaults to none. (Since 5.0)
14655 multifd-zlib-level: int (optional)
14657 Set the compression level to be used in live migration, the com‐
14658 pression level is an integer between 0 and 9, where 0 means no
14659 compression, 1 means the best compression speed, and 9 means
14660 best compression ratio which will consume more CPU. Defaults to
14661 1. (Since 5.0)
14662 multifd-zstd-level: int (optional)
14664 Set the compression level to be used in live migration, the com‐
14665 pression level is an integer between 0 and 20, where 0 means no
14666 compression, 1 means the best compression speed, and 20 means
14667 best compression ratio which will consume more CPU. Defaults to
14668 1. (Since 5.0)
14669 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
14671 Maps block nodes and bitmaps on them to aliases for the purpose
14672 of dirty bitmap migration. Such aliases may for example be the
14673 corresponding names on the opposite site. The mapping must be
14674 one-to-one, but not necessarily complete: On the source, un‐
14675 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
14676 nored. On the destination, encountering an unmapped alias in
14677 the incoming migration stream will result in a report, and all
14678 further bitmap migration data will then be discarded. Note that
14679 the destination does not know about bitmaps it does not receive,
14680 so there is no limitation or requirement regarding the number of
14681 bitmaps received, or how they are named, or on which nodes they
14682 are placed. By default (when this parameter has never been
14683 set), bitmap names are mapped to themselves. Nodes are mapped
14684 to their block device name if there is one, and to their node
14685 name otherwise. (Since 5.2)
14686 Features
14688 unstable
14689 Member x-checkpoint-delay is experimental.
14690 Since
14692 2.4
14693 query-migrate-parameters (Command)
14695 Returns information about the current migration parameters
14696 Returns
14698 MigrationParameters
14699 Since
14701 2.4
14702 Example
14704 -> { "execute": "query-migrate-parameters" }
14705 <- { "return": {
14706 "decompress-threads": 2,
14707 "cpu-throttle-increment": 10,
14708 "compress-threads": 8,
14709 "compress-level": 1,
14710 "cpu-throttle-initial": 20,
14711 "max-bandwidth": 33554432,
14712 "downtime-limit": 300
14713 }
14714 }
14715 client_migrate_info (Command)
14717 Set migration information for remote display. This makes the server
14718 ask the client to automatically reconnect using the new parameters once
14719 migration finished successfully. Only implemented for SPICE.
14720 Arguments
14722 protocol: string
14723 must be "spice"
14724 hostname: string
14726 migration target hostname
14727 port: int (optional)
14729 spice tcp port for plaintext channels
14730 tls-port: int (optional)
14732 spice tcp port for tls-secured channels
14733 cert-subject: string (optional)
14735 server certificate subject
14736 Since
14738 0.14
14739 Example
14741 -> { "execute": "client_migrate_info",
14742 "arguments": { "protocol": "spice",
14743 "hostname": "virt42.lab.kraxel.org",
14744 "port": 1234 } }
14745 <- { "return": {} }
14746 migrate-start-postcopy (Command)
14748 Followup to a migration command to switch the migration to postcopy
14749 mode. The postcopy-ram capability must be set on both source and des‐
14750 tination before the original migration command.
14751 Since
14753 2.5
14754 Example
14756 -> { "execute": "migrate-start-postcopy" }
14757 <- { "return": {} }
14758 MIGRATION (Event)
14760 Emitted when a migration event happens
14761 Arguments
14763 status: MigrationStatus
14764 MigrationStatus describing the current migration status.
14765 Since
14767 2.4
14768 Example
14770 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
14771 "event": "MIGRATION",
14772 "data": {"status": "completed"} }
14773 MIGRATION_PASS (Event)
14775 Emitted from the source side of a migration at the start of each pass
14776 (when it syncs the dirty bitmap)
14777 Arguments
14779 pass: int
14780 An incrementing count (starting at 1 on the first pass)
14781 Since
14783 2.6
14784 Example
14786 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
14787 "event": "MIGRATION_PASS", "data": {"pass": 2} }
14788 COLOMessage (Enum)
14790 The message transmission between Primary side and Secondary side.
14791 Values
14793 checkpoint-ready
14794 Secondary VM (SVM) is ready for checkpointing
14795 checkpoint-request
14797 Primary VM (PVM) tells SVM to prepare for checkpointing
14798 checkpoint-reply
14800 SVM gets PVM's checkpoint request
14801 vmstate-send
14803 VM's state will be sent by PVM.
14804 vmstate-size
14806 The total size of VMstate.
14807 vmstate-received
14809 VM's state has been received by SVM.
14810 vmstate-loaded
14812 VM's state has been loaded by SVM.
14813 Since
14815 2.8
14816 COLOMode (Enum)
14818 The COLO current mode.
14819 Values
14821 none COLO is disabled.
14822 primary
14824 COLO node in primary side.
14825 secondary
14827 COLO node in slave side.
14828 Since
14830 2.8
14831 FailoverStatus (Enum)
14833 An enumeration of COLO failover status
14834 Values
14836 none no failover has ever happened
14837 require
14839 got failover requirement but not handled
14840 active in the process of doing failover
14842 completed
14844 finish the process of failover
14845 relaunch
14847 restart the failover process, from 'none' -> 'completed' (Since
14848 2.9)
14849 Since
14851 2.8
14852 COLO_EXIT (Event)
14854 Emitted when VM finishes COLO mode due to some errors happening or at
14855 the request of users.
14856 Arguments
14858 mode: COLOMode
14859 report COLO mode when COLO exited.
14860 reason: COLOExitReason
14862 describes the reason for the COLO exit.
14863 Since
14865 3.1
14866 Example
14868 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
14869 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
14870 COLOExitReason (Enum)
14872 The reason for a COLO exit.
14873 Values
14875 none failover has never happened. This state does not occur in the
14876 COLO_EXIT event, and is only visible in the result of
14877 query-colo-status.
14878 request
14880 COLO exit is due to an external request.
14881 error COLO exit is due to an internal error.
14883 processing
14885 COLO is currently handling a failover (since 4.0).
14886 Since
14888 3.1
14889 x-colo-lost-heartbeat (Command)
14891 Tell qemu that heartbeat is lost, request it to do takeover procedures.
14892 If this command is sent to the PVM, the Primary side will exit COLO
14893 mode. If sent to the Secondary, the Secondary side will run failover
14894 work, then takes over server operation to become the service VM.
14895 Features
14897 unstable
14898 This command is experimental.
14899 Since
14901 2.8
14902 Example
14904 -> { "execute": "x-colo-lost-heartbeat" }
14905 <- { "return": {} }
14906 migrate_cancel (Command)
14908 Cancel the current executing migration process.
14909 Returns
14911 nothing on success
14912 Notes
14914 This command succeeds even if there is no migration process running.
14915 Since
14917 0.14
14918 Example
14920 -> { "execute": "migrate_cancel" }
14921 <- { "return": {} }
14922 migrate-continue (Command)
14924 Continue migration when it's in a paused state.
14925 Arguments
14927 state: MigrationStatus
14928 The state the migration is currently expected to be in
14929 Returns
14931 nothing on success
14932 Since
14934 2.11
14935 Example
14937 -> { "execute": "migrate-continue" , "arguments":
14938 { "state": "pre-switchover" } }
14939 <- { "return": {} }
14940 migrate (Command)
14942 Migrates the current running guest to another Virtual Machine.
14943 Arguments
14945 uri: string
14946 the Uniform Resource Identifier of the destination VM
14947 blk: boolean (optional)
14949 do block migration (full disk copy)
14950 inc: boolean (optional)
14952 incremental disk copy migration
14953 detach: boolean (optional)
14955 this argument exists only for compatibility reasons and is ig‐
14956 nored by QEMU
14957 resume: boolean (optional)
14959 resume one paused migration, default "off". (since 3.0)
14960 Returns
14962 nothing on success
14963 Since
14965 0.14
14966 Notes
14968 1. The 'query-migrate' command should be used to check migration's
14969 progress and final result (this information is provided by the 'sta‐
14970 tus' member)
14971 2. All boolean arguments default to false
14973 3. The user Monitor's "detach" argument is invalid in QMP and should
14975 not be used
14976 Example
14978 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
14979 <- { "return": {} }
14980 migrate-incoming (Command)
14982 Start an incoming migration, the qemu must have been started with -in‐
14983 coming defer
14984 Arguments
14986 uri: string
14987 The Uniform Resource Identifier identifying the source or ad‐
14988 dress to listen on
14989 Returns
14991 nothing on success
14992 Since
14994 2.3
14995 Notes
14997 1. It's a bad idea to use a string for the uri, but it needs to stay
14998 compatible with -incoming and the format of the uri is already ex‐
14999 posed above libvirt.
15000 2. QEMU must be started with -incoming defer to allow migrate-incoming
15002 to be used.
15003 3. The uri format is the same as for -incoming
15005 Example
15007 -> { "execute": "migrate-incoming",
15008 "arguments": { "uri": "tcp::4446" } }
15009 <- { "return": {} }
15010 xen-save-devices-state (Command)
15012 Save the state of all devices to file. The RAM and the block devices of
15013 the VM are not saved by this command.
15014 Arguments
15016 filename: string
15017 the file to save the state of the devices to as binary data. See
15018 xen-save-devices-state.txt for a description of the binary for‐
15019 mat.
15020 live: boolean (optional)
15022 Optional argument to ask QEMU to treat this command as part of a
15023 live migration. Default to true. (since 2.11)
15024 Returns
15026 Nothing on success
15027 Since
15029 1.1
15030 Example
15032 -> { "execute": "xen-save-devices-state",
15033 "arguments": { "filename": "/tmp/save" } }
15034 <- { "return": {} }
15035 xen-set-global-dirty-log (Command)
15037 Enable or disable the global dirty log mode.
15038 Arguments
15040 enable: boolean
15041 true to enable, false to disable.
15042 Returns
15044 nothing
15045 Since
15047 1.3
15048 Example
15050 -> { "execute": "xen-set-global-dirty-log",
15051 "arguments": { "enable": true } }
15052 <- { "return": {} }
15053 xen-load-devices-state (Command)
15055 Load the state of all devices from file. The RAM and the block devices
15056 of the VM are not loaded by this command.
15057 Arguments
15059 filename: string
15060 the file to load the state of the devices from as binary data.
15061 See xen-save-devices-state.txt for a description of the binary
15062 format.
15063 Since
15065 2.7
15066 Example
15068 -> { "execute": "xen-load-devices-state",
15069 "arguments": { "filename": "/tmp/resume" } }
15070 <- { "return": {} }
15071 xen-set-replication (Command)
15073 Enable or disable replication.
15074 Arguments
15076 enable: boolean
15077 true to enable, false to disable.
15078 primary: boolean
15080 true for primary or false for secondary.
15081 failover: boolean (optional)
15083 true to do failover, false to stop. but cannot be specified if
15084 'enable' is true. default value is false.
15085 Returns
15087 nothing.
15088 Example
15090 -> { "execute": "xen-set-replication",
15091 "arguments": {"enable": true, "primary": false} }
15092 <- { "return": {} }
15093 Since
15095 2.9
15096 If
15098 CONFIG_REPLICATION
15099 ReplicationStatus (Object)
15101 The result format for 'query-xen-replication-status'.
15102 Members
15104 error: boolean
15105 true if an error happened, false if replication is normal.
15106 desc: string (optional)
15108 the human readable error description string, when error is
15109 'true'.
15110 Since
15112 2.9
15113 If
15115 CONFIG_REPLICATION
15116 query-xen-replication-status (Command)
15118 Query replication status while the vm is running.
15119 Returns
15121 A ReplicationResult object showing the status.
15122 Example
15124 -> { "execute": "query-xen-replication-status" }
15125 <- { "return": { "error": false } }
15126 Since
15128 2.9
15129 If
15131 CONFIG_REPLICATION
15132 xen-colo-do-checkpoint (Command)
15134 Xen uses this command to notify replication to trigger a checkpoint.
15135 Returns
15137 nothing.
15138 Example
15140 -> { "execute": "xen-colo-do-checkpoint" }
15141 <- { "return": {} }
15142 Since
15144 2.9
15145 If
15147 CONFIG_REPLICATION
15148 COLOStatus (Object)
15150 The result format for 'query-colo-status'.
15151 Members
15153 mode: COLOMode
15154 COLO running mode. If COLO is running, this field will return
15155 'primary' or 'secondary'.
15156 last-mode: COLOMode
15158 COLO last running mode. If COLO is running, this field will re‐
15159 turn same like mode field, after failover we can use this field
15160 to get last colo mode. (since 4.0)
15161 reason: COLOExitReason
15163 describes the reason for the COLO exit.
15164 Since
15166 3.1
15167 query-colo-status (Command)
15169 Query COLO status while the vm is running.
15170 Returns
15172 A COLOStatus object showing the status.
15173 Example
15175 -> { "execute": "query-colo-status" }
15176 <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } }
15177 Since
15179 3.1
15180 migrate-recover (Command)
15182 Provide a recovery migration stream URI.
15183 Arguments
15185 uri: string
15186 the URI to be used for the recovery of migration stream.
15187 Returns
15189 nothing.
15190 Example
15192 -> { "execute": "migrate-recover",
15193 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
15194 <- { "return": {} }
15195 Since
15197 3.0
15198 migrate-pause (Command)
15200 Pause a migration. Currently it only supports postcopy.
15201 Returns
15203 nothing.
15204 Example
15206 -> { "execute": "migrate-pause" }
15207 <- { "return": {} }
15208 Since
15210 3.0
15211 UNPLUG_PRIMARY (Event)
15213 Emitted from source side of a migration when migration state is
15214 WAIT_UNPLUG. Device was unplugged by guest operating system. Device
15215 resources in QEMU are kept on standby to be able to re-plug it in case
15216 of migration failure.
15217 Arguments
15219 device-id: string
15220 QEMU device id of the unplugged device
15221 Since
15223 4.2
15224 Example
15226 <- { "event": "UNPLUG_PRIMARY",
15227 "data": { "device-id": "hostdev0" },
15228 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
15229 DirtyRateVcpu (Object)
15231 Dirty rate of vcpu.
15232 Members
15234 id: int
15235 vcpu index.
15236 dirty-rate: int
15238 dirty rate.
15239 Since
15241 6.2
15242 DirtyRateStatus (Enum)
15244 An enumeration of dirtyrate status.
15245 Values
15247 unstarted
15248 the dirtyrate thread has not been started.
15249 measuring
15251 the dirtyrate thread is measuring.
15252 measured
15254 the dirtyrate thread has measured and results are available.
15255 Since
15257 5.2
15258 DirtyRateMeasureMode (Enum)
15260 An enumeration of mode of measuring dirtyrate.
15261 Values
15263 page-sampling
15264 calculate dirtyrate by sampling pages.
15265 dirty-ring
15267 calculate dirtyrate by dirty ring.
15268 dirty-bitmap
15270 calculate dirtyrate by dirty bitmap.
15271 Since
15273 6.2
15274 DirtyRateInfo (Object)
15276 Information about current dirty page rate of vm.
15277 Members
15279 dirty-rate: int (optional)
15280 an estimate of the dirty page rate of the VM in units of MB/s,
15281 present only when estimating the rate has completed.
15282 status: DirtyRateStatus
15284 status containing dirtyrate query status includes 'unstarted' or
15285 'measuring' or 'measured'
15286 start-time: int
15288 start time in units of second for calculation
15289 calc-time: int
15291 time in units of second for sample dirty pages
15292 sample-pages: int
15294 page count per GB for sample dirty pages the default value is
15295 512 (since 6.1)
15296 mode: DirtyRateMeasureMode
15298 mode containing method of calculate dirtyrate includes
15299 'page-sampling' and 'dirty-ring' (Since 6.2)
15300 vcpu-dirty-rate: array of DirtyRateVcpu (optional)
15302 dirtyrate for each vcpu if dirty-ring mode specified (Since 6.2)
15303 Since
15305 5.2
15306 calc-dirty-rate (Command)
15308 start calculating dirty page rate for vm
15309 Arguments
15311 calc-time: int
15312 time in units of second for sample dirty pages
15313 sample-pages: int (optional)
15315 page count per GB for sample dirty pages the default value is
15316 512 (since 6.1)
15317 mode: DirtyRateMeasureMode (optional)
15319 mechanism of calculating dirtyrate includes 'page-sampling' and
15320 'dirty-ring' (Since 6.1)
15321 Since
15323 5.2
15324 Example
15326 {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
15327 'sample-pages': 512} }
15328 query-dirty-rate (Command)
15330 query dirty page rate in units of MB/s for vm
15331 Since
15333 5.2
15334 snapshot-save (Command)
15336 Save a VM snapshot
15337 Arguments
15339 job-id: string
15340 identifier for the newly created job
15341 tag: string
15343 name of the snapshot to create
15344 vmstate: string
15346 block device node name to save vmstate to
15347 devices: array of string
15349 list of block device node names to save a snapshot to
15350 Applications should not assume that the snapshot save is complete when
15351 this command returns. The job commands / events must be used to deter‐
15352 mine completion and to fetch details of any errors that arise.
15353 Note that execution of the guest CPUs may be stopped during the time it
15355 takes to save the snapshot. A future version of QEMU may ensure CPUs
15356 are executing continuously.
15357 It is strongly recommended that devices contain all writable block de‐
15359 vice nodes if a consistent snapshot is required.
15360 If tag already exists, an error will be reported
15362 Returns
15364 nothing
15365 Example
15367 -> { "execute": "snapshot-save",
15368 "arguments": {
15369 "job-id": "snapsave0",
15370 "tag": "my-snap",
15371 "vmstate": "disk0",
15372 "devices": ["disk0", "disk1"]
15373 }
15374 }
15375 <- { "return": { } }
15376 <- {"event": "JOB_STATUS_CHANGE",
15377 "data": {"status": "created", "id": "snapsave0"}}
15378 <- {"event": "JOB_STATUS_CHANGE",
15379 "data": {"status": "running", "id": "snapsave0"}}
15380 <- {"event": "STOP"}
15381 <- {"event": "RESUME"}
15382 <- {"event": "JOB_STATUS_CHANGE",
15383 "data": {"status": "waiting", "id": "snapsave0"}}
15384 <- {"event": "JOB_STATUS_CHANGE",
15385 "data": {"status": "pending", "id": "snapsave0"}}
15386 <- {"event": "JOB_STATUS_CHANGE",
15387 "data": {"status": "concluded", "id": "snapsave0"}}
15388 -> {"execute": "query-jobs"}
15389 <- {"return": [{"current-progress": 1,
15390 "status": "concluded",
15391 "total-progress": 1,
15392 "type": "snapshot-save",
15393 "id": "snapsave0"}]}
15394 Since
15396 6.0
15397 snapshot-load (Command)
15399 Load a VM snapshot
15400 Arguments
15402 job-id: string
15403 identifier for the newly created job
15404 tag: string
15406 name of the snapshot to load.
15407 vmstate: string
15409 block device node name to load vmstate from
15410 devices: array of string
15412 list of block device node names to load a snapshot from
15413 Applications should not assume that the snapshot load is complete when
15414 this command returns. The job commands / events must be used to deter‐
15415 mine completion and to fetch details of any errors that arise.
15416 Note that execution of the guest CPUs will be stopped during the time
15418 it takes to load the snapshot.
15419 It is strongly recommended that devices contain all writable block de‐
15421 vice nodes that can have changed since the original snapshot-save com‐
15422 mand execution.
15423 Returns
15425 nothing
15426 Example
15428 -> { "execute": "snapshot-load",
15429 "arguments": {
15430 "job-id": "snapload0",
15431 "tag": "my-snap",
15432 "vmstate": "disk0",
15433 "devices": ["disk0", "disk1"]
15434 }
15435 }
15436 <- { "return": { } }
15437 <- {"event": "JOB_STATUS_CHANGE",
15438 "data": {"status": "created", "id": "snapload0"}}
15439 <- {"event": "JOB_STATUS_CHANGE",
15440 "data": {"status": "running", "id": "snapload0"}}
15441 <- {"event": "STOP"}
15442 <- {"event": "RESUME"}
15443 <- {"event": "JOB_STATUS_CHANGE",
15444 "data": {"status": "waiting", "id": "snapload0"}}
15445 <- {"event": "JOB_STATUS_CHANGE",
15446 "data": {"status": "pending", "id": "snapload0"}}
15447 <- {"event": "JOB_STATUS_CHANGE",
15448 "data": {"status": "concluded", "id": "snapload0"}}
15449 -> {"execute": "query-jobs"}
15450 <- {"return": [{"current-progress": 1,
15451 "status": "concluded",
15452 "total-progress": 1,
15453 "type": "snapshot-load",
15454 "id": "snapload0"}]}
15455 Since
15457 6.0
15458 snapshot-delete (Command)
15460 Delete a VM snapshot
15461 Arguments
15463 job-id: string
15464 identifier for the newly created job
15465 tag: string
15467 name of the snapshot to delete.
15468 devices: array of string
15470 list of block device node names to delete a snapshot from
15471 Applications should not assume that the snapshot delete is complete
15472 when this command returns. The job commands / events must be used to
15473 determine completion and to fetch details of any errors that arise.
15474 Returns
15476 nothing
15477 Example
15479 -> { "execute": "snapshot-delete",
15480 "arguments": {
15481 "job-id": "snapdelete0",
15482 "tag": "my-snap",
15483 "devices": ["disk0", "disk1"]
15484 }
15485 }
15486 <- { "return": { } }
15487 <- {"event": "JOB_STATUS_CHANGE",
15488 "data": {"status": "created", "id": "snapdelete0"}}
15489 <- {"event": "JOB_STATUS_CHANGE",
15490 "data": {"status": "running", "id": "snapdelete0"}}
15491 <- {"event": "JOB_STATUS_CHANGE",
15492 "data": {"status": "waiting", "id": "snapdelete0"}}
15493 <- {"event": "JOB_STATUS_CHANGE",
15494 "data": {"status": "pending", "id": "snapdelete0"}}
15495 <- {"event": "JOB_STATUS_CHANGE",
15496 "data": {"status": "concluded", "id": "snapdelete0"}}
15497 -> {"execute": "query-jobs"}
15498 <- {"return": [{"current-progress": 1,
15499 "status": "concluded",
15500 "total-progress": 1,
15501 "type": "snapshot-delete",
15502 "id": "snapdelete0"}]}
15503 Since
15505 6.0
15506
15508 Abort (Object)
15509 This action can be used to test transaction failure.
15510 Since
15512 1.6
15513 ActionCompletionMode (Enum)
15515 An enumeration of Transactional completion modes.
15516 Values
15518 individual
15519 Do not attempt to cancel any other Actions if any Actions fail
15520 after the Transaction request succeeds. All Actions that can
15521 complete successfully will do so without waiting on others.
15522 This is the default.
15523 grouped
15525 If any Action fails after the Transaction succeeds, cancel all
15526 Actions. Actions do not complete until all Actions are ready to
15527 complete. May be rejected by Actions that do not support this
15528 completion mode.
15529 Since
15531 2.5
15532 TransactionActionKind (Enum)
15534 Values
15535 abort Since 1.6
15536 block-dirty-bitmap-add
15538 Since 2.5
15539 block-dirty-bitmap-remove
15541 Since 4.2
15542 block-dirty-bitmap-clear
15544 Since 2.5
15545 block-dirty-bitmap-enable
15547 Since 4.0
15548 block-dirty-bitmap-disable
15550 Since 4.0
15551 block-dirty-bitmap-merge
15553 Since 4.0
15554 blockdev-backup
15556 Since 2.3
15557 blockdev-snapshot
15559 Since 2.5
15560 blockdev-snapshot-internal-sync
15562 Since 1.7
15563 blockdev-snapshot-sync
15565 since 1.1
15566 drive-backup
15568 Since 1.6
15569 Features
15571 deprecated
15572 Member drive-backup is deprecated. Use member blockdev-backup
15573 instead.
15574 Since
15576 1.1
15577 AbortWrapper (Object)
15579 Members
15580 data: Abort
15581 Not documented
15582 Since
15584 1.6
15585 BlockDirtyBitmapAddWrapper (Object)
15587 Members
15588 data: BlockDirtyBitmapAdd
15589 Not documented
15590 Since
15592 2.5
15593 BlockDirtyBitmapWrapper (Object)
15595 Members
15596 data: BlockDirtyBitmap
15597 Not documented
15598 Since
15600 2.5
15601 BlockDirtyBitmapMergeWrapper (Object)
15603 Members
15604 data: BlockDirtyBitmapMerge
15605 Not documented
15606 Since
15608 4.0
15609 BlockdevBackupWrapper (Object)
15611 Members
15612 data: BlockdevBackup
15613 Not documented
15614 Since
15616 2.3
15617 BlockdevSnapshotWrapper (Object)
15619 Members
15620 data: BlockdevSnapshot
15621 Not documented
15622 Since
15624 2.5
15625 BlockdevSnapshotInternalWrapper (Object)
15627 Members
15628 data: BlockdevSnapshotInternal
15629 Not documented
15630 Since
15632 1.7
15633 BlockdevSnapshotSyncWrapper (Object)
15635 Members
15636 data: BlockdevSnapshotSync
15637 Not documented
15638 Since
15640 1.1
15641 DriveBackupWrapper (Object)
15643 Members
15644 data: DriveBackup
15645 Not documented
15646 Since
15648 1.6
15649 TransactionAction (Object)
15651 A discriminated record of operations that can be performed with trans‐
15652 action.
15653 Members
15655 type: TransactionActionKind
15656 Not documented
15657 The members of AbortWrapper when type is "abort"
15659 The members of BlockDirtyBitmapAddWrapper when type is
15661 "block-dirty-bitmap-add"
15662 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
15664 map-remove"
15665 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
15667 map-clear"
15668 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
15670 map-enable"
15671 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
15673 map-disable"
15674 The members of BlockDirtyBitmapMergeWrapper when type is
15676 "block-dirty-bitmap-merge"
15677 The members of BlockdevBackupWrapper when type is "blockdev-backup"
15679 The members of BlockdevSnapshotWrapper when type is "blockdev-snapshot"
15681 The members of BlockdevSnapshotInternalWrapper when type is "block‐
15683 dev-snapshot-internal-sync"
15684 The members of BlockdevSnapshotSyncWrapper when type is "blockdev-snap‐
15686 shot-sync"
15687 The members of DriveBackupWrapper when type is "drive-backup"
15689 Since
15691 1.1
15692 TransactionProperties (Object)
15694 Optional arguments to modify the behavior of a Transaction.
15695 Members
15697 completion-mode: ActionCompletionMode (optional)
15698 Controls how jobs launched asynchronously by Actions will com‐
15699 plete or fail as a group. See ActionCompletionMode for details.
15700 Since
15702 2.5
15703 transaction (Command)
15705 Executes a number of transactionable QMP commands atomically. If any
15706 operation fails, then the entire set of actions will be abandoned and
15707 the appropriate error returned.
15708 For external snapshots, the dictionary contains the device, the file to
15710 use for the new snapshot, and the format. The default format, if not
15711 specified, is qcow2.
15712 Each new snapshot defaults to being created by QEMU (wiping any con‐
15714 tents if the file already exists), but it is also possible to reuse an
15715 externally-created file. In the latter case, you should ensure that
15716 the new image file has the same contents as the current one; QEMU can‐
15717 not perform any meaningful check. Typically this is achieved by using
15718 the current image file as the backing file for the new image.
15719 On failure, the original disks pre-snapshot attempt will be used.
15721 For internal snapshots, the dictionary contains the device and the
15723 snapshot's name. If an internal snapshot matching name already exists,
15724 the request will be rejected. Only some image formats support it, for
15725 example, qcow2, and rbd,
15726 On failure, qemu will try delete the newly created internal snapshot in
15728 the transaction. When an I/O error occurs during deletion, the user
15729 needs to fix it later with qemu-img or other command.
15730 Arguments
15732 actions: array of TransactionAction
15733 List of TransactionAction; information needed for the respective
15734 operations.
15735 properties: TransactionProperties (optional)
15737 structure of additional options to control the execution of the
15738 transaction. See TransactionProperties for additional detail.
15739 Returns
15741 nothing on success
15742 Errors depend on the operations of the transaction
15744 Note
15746 The transaction aborts on the first failure. Therefore, there will be
15747 information on only one failed operation returned in an error condi‐
15748 tion, and subsequent actions will not have been attempted.
15749 Since
15751 1.1
15752 Example
15754 -> { "execute": "transaction",
15755 "arguments": { "actions": [
15756 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
15757 "snapshot-file": "/some/place/my-image",
15758 "format": "qcow2" } },
15759 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
15760 "snapshot-file": "/some/place/my-image2",
15761 "snapshot-node-name": "node3432",
15762 "mode": "existing",
15763 "format": "qcow2" } },
15764 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
15765 "snapshot-file": "/some/place/my-image2",
15766 "mode": "existing",
15767 "format": "qcow2" } },
15768 { "type": "blockdev-snapshot-internal-sync", "data" : {
15769 "device": "ide-hd2",
15770 "name": "snapshot0" } } ] } }
15771 <- { "return": {} }
15772
15774 TraceEventState (Enum)
15775 State of a tracing event.
15776 Values
15778 unavailable
15779 The event is statically disabled.
15780 disabled
15782 The event is dynamically disabled.
15783 enabled
15785 The event is dynamically enabled.
15786 Since
15788 2.2
15789 TraceEventInfo (Object)
15791 Information of a tracing event.
15792 Members
15794 name: string
15795 Event name.
15796 state: TraceEventState
15798 Tracing state.
15799 vcpu: boolean
15801 Whether this is a per-vCPU event (since 2.7).
15802 An event is per-vCPU if it has the "vcpu" property in the
15803 "trace-events" files.
15804 Since
15806 2.2
15807 trace-event-get-state (Command)
15809 Query the state of events.
15810 Arguments
15812 name: string
15813 Event name pattern (case-sensitive glob).
15814 vcpu: int (optional)
15816 The vCPU to query (any by default; since 2.7).
15817 Returns
15819 a list of TraceEventInfo for the matching events
15820 An event is returned if:
15822 • its name matches the name pattern, and
15824 • if vcpu is given, the event has the "vcpu" property.
15826 Therefore, if vcpu is given, the operation will only match per-vCPU
15828 events, returning their state on the specified vCPU. Special case: if
15829 name is an exact match, vcpu is given and the event does not have the
15830 "vcpu" property, an error is returned.
15831 Since
15833 2.2
15834 Example
15836 -> { "execute": "trace-event-get-state",
15837 "arguments": { "name": "qemu_memalign" } }
15838 <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }
15839 trace-event-set-state (Command)
15841 Set the dynamic tracing state of events.
15842 Arguments
15844 name: string
15845 Event name pattern (case-sensitive glob).
15846 enable: boolean
15848 Whether to enable tracing.
15849 ignore-unavailable: boolean (optional)
15851 Do not match unavailable events with name.
15852 vcpu: int (optional)
15854 The vCPU to act upon (all by default; since 2.7).
15855 An event's state is modified if: - its name matches the name pattern,
15856 and - if vcpu is given, the event has the "vcpu" property.
15857 Therefore, if vcpu is given, the operation will only match per-vCPU
15859 events, setting their state on the specified vCPU. Special case: if
15860 name is an exact match, vcpu is given and the event does not have the
15861 "vcpu" property, an error is returned.
15862 Since
15864 2.2
15865 Example
15867 -> { "execute": "trace-event-set-state",
15868 "arguments": { "name": "qemu_memalign", "enable": true } }
15869 <- { "return": {} }
15870
15872 CompatPolicyInput (Enum)
15873 Policy for handling "funny" input.
15874 Values
15876 accept Accept silently
15877 reject Reject with an error
15879 crash abort() the process
15881 Since
15883 6.0
15884 CompatPolicyOutput (Enum)
15886 Policy for handling "funny" output.
15887 Values
15889 accept Pass on unchanged
15890 hide Filter out
15892 Since
15894 6.0
15895 CompatPolicy (Object)
15897 Policy for handling deprecated management interfaces.
15898 This is intended for testing users of the management interfaces.
15900 Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
15902 with feature 'deprecated'. We may want to extend it to cover semantic
15903 aspects and CLI.
15904 Limitation: deprecated-output policy hide is not implemented for enu‐
15906 meration values. They behave the same as with policy accept.
15907 Members
15909 deprecated-input: CompatPolicyInput (optional)
15910 how to handle deprecated input (default 'accept')
15911 deprecated-output: CompatPolicyOutput (optional)
15913 how to handle deprecated output (default 'accept')
15914 unstable-input: CompatPolicyInput (optional)
15916 how to handle unstable input (default 'accept') (since 6.2)
15917 unstable-output: CompatPolicyOutput (optional)
15919 how to handle unstable output (default 'accept') (since 6.2)
15920 Since
15922 6.0
15923
15925 qmp_capabilities (Command)
15926 Enable QMP capabilities.
15927 Arguments:
15929 Arguments
15931 enable: array of QMPCapability (optional)
15932 An optional list of QMPCapability values to enable. The client
15933 must not enable any capability that is not mentioned in the QMP
15934 greeting message. If the field is not provided, it means no QMP
15935 capabilities will be enabled. (since 2.12)
15936 Example
15938 -> { "execute": "qmp_capabilities",
15939 "arguments": { "enable": [ "oob" ] } }
15940 <- { "return": {} }
15941 Notes
15943 This command is valid exactly when first connecting: it must be issued
15944 before any other command will be accepted, and will fail once the moni‐
15945 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
15946 The QMP client needs to explicitly enable QMP capabilities, otherwise
15948 all the QMP capabilities will be turned off by default.
15949 Since
15951 0.13
15952 QMPCapability (Enum)
15954 Enumeration of capabilities to be advertised during initial client con‐
15955 nection, used for agreeing on particular QMP extension behaviors.
15956 Values
15958 oob QMP ability to support out-of-band requests. (Please refer to
15959 qmp-spec.txt for more information on OOB)
15960 Since
15962 2.12
15963 VersionTriple (Object)
15965 A three-part version number.
15966 Members
15968 major: int
15969 The major version number.
15970 minor: int
15972 The minor version number.
15973 micro: int
15975 The micro version number.
15976 Since
15978 2.4
15979 VersionInfo (Object)
15981 A description of QEMU's version.
15982 Members
15984 qemu: VersionTriple
15985 The version of QEMU. By current convention, a micro version of
15986 50 signifies a development branch. A micro version greater than
15987 or equal to 90 signifies a release candidate for the next minor
15988 version. A micro version of less than 50 signifies a stable re‐
15989 lease.
15990 package: string
15992 QEMU will always set this field to an empty string. Downstream
15993 versions of QEMU should set this to a non-empty string. The ex‐
15994 act format depends on the downstream however it highly recom‐
15995 mended that a unique name is used.
15996 Since
15998 0.14
15999 query-version (Command)
16001 Returns the current version of QEMU.
16002 Returns
16004 A VersionInfo object describing the current version of QEMU.
16005 Since
16007 0.14
16008 Example
16010 -> { "execute": "query-version" }
16011 <- {
16012 "return":{
16013 "qemu":{
16014 "major":0,
16015 "minor":11,
16016 "micro":5
16017 },
16018 "package":""
16019 }
16020 }
16021 CommandInfo (Object)
16023 Information about a QMP command
16024 Members
16026 name: string
16027 The command name
16028 Since
16030 0.14
16031 query-commands (Command)
16033 Return a list of supported QMP commands by this server
16034 Returns
16036 A list of CommandInfo for all supported commands
16037 Since
16039 0.14
16040 Example
16042 -> { "execute": "query-commands" }
16043 <- {
16044 "return":[
16045 {
16046 "name":"query-balloon"
16047 },
16048 {
16049 "name":"system_powerdown"
16050 }
16051 ]
16052 }
16053 Note
16055 This example has been shortened as the real response is too long.
16056 quit (Command)
16058 This command will cause the QEMU process to exit gracefully. While ev‐
16059 ery attempt is made to send the QMP response before terminating, this
16060 is not guaranteed. When using this interface, a premature EOF would
16061 not be unexpected.
16062 Since
16064 0.14
16065 Example
16067 -> { "execute": "quit" }
16068 <- { "return": {} }
16069 MonitorMode (Enum)
16071 An enumeration of monitor modes.
16072 Values
16074 readline
16075 HMP monitor (human-oriented command line interface)
16076 control
16078 QMP monitor (JSON-based machine interface)
16079 Since
16081 5.0
16082 MonitorOptions (Object)
16084 Options to be used for adding a new monitor.
16085 Members
16087 id: string (optional)
16088 Name of the monitor
16089 mode: MonitorMode (optional)
16091 Selects the monitor mode (default: readline in the system emula‐
16092 tor, control in qemu-storage-daemon)
16093 pretty: boolean (optional)
16095 Enables pretty printing (QMP only)
16096 chardev: string
16098 Name of a character device to expose the monitor on
16099 Since
16101 5.0
16102
16104 query-qmp-schema (Command)
16105 Command query-qmp-schema exposes the QMP wire ABI as an array of
16106 SchemaInfo. This lets QMP clients figure out what commands and events
16107 are available in this QEMU, and their parameters and results.
16108 However, the SchemaInfo can't reflect all the rules and restrictions
16110 that apply to QMP. It's interface introspection (figuring out what's
16111 there), not interface specification. The specification is in the QAPI
16112 schema.
16113 Furthermore, while we strive to keep the QMP wire format backwards-com‐
16115 patible across qemu versions, the introspection output is not guaran‐
16116 teed to have the same stability. For example, one version of qemu may
16117 list an object member as an optional non-variant, while another lists
16118 the same member only through the object's variants; or the type of a
16119 member may change from a generic string into a specific enum or from
16120 one specific type into an alternate that includes the original type
16121 alongside something else.
16122 Returns
16124 array of SchemaInfo, where each element describes an entity in the ABI:
16125 command, event, type, ...
16126 The order of the various SchemaInfo is unspecified; however, all names
16128 are guaranteed to be unique (no name will be duplicated with different
16129 meta-types).
16130 Note
16132 the QAPI schema is also used to help define internal interfaces, by
16133 defining QAPI types. These are not part of the QMP wire ABI, and
16134 therefore not returned by this command.
16135 Since
16137 2.5
16138 SchemaMetaType (Enum)
16140 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
16141 Values
16143 builtin
16144 a predefined type such as 'int' or 'bool'.
16145 enum an enumeration type
16147 array an array type
16149 object an object type (struct or union)
16151 alternate
16153 an alternate type
16154 command
16156 a QMP command
16157 event a QMP event
16159 Since
16161 2.5
16162 SchemaInfo (Object)
16164 Members
16165 name: string
16166 the entity's name, inherited from base. The SchemaInfo is al‐
16167 ways referenced by this name. Commands and events have the name
16168 defined in the QAPI schema. Unlike command and event names,
16169 type names are not part of the wire ABI. Consequently, type
16170 names are meaningless strings here, although they are still
16171 guaranteed unique regardless of meta-type.
16172 meta-type: SchemaMetaType
16174 the entity's meta type, inherited from base.
16175 features: array of string (optional)
16177 names of features associated with the entity, in no particular
16178 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
16179 the rest)
16180 The members of SchemaInfoBuiltin when meta-type is "builtin"
16182 The members of SchemaInfoEnum when meta-type is "enum"
16184 The members of SchemaInfoArray when meta-type is "array"
16186 The members of SchemaInfoObject when meta-type is "object"
16188 The members of SchemaInfoAlternate when meta-type is "alternate"
16190 The members of SchemaInfoCommand when meta-type is "command"
16192 The members of SchemaInfoEvent when meta-type is "event"
16194 Additional members depend on the value of meta-type.
16195 Since
16197 2.5
16198 SchemaInfoBuiltin (Object)
16200 Additional SchemaInfo members for meta-type 'builtin'.
16201 Members
16203 json-type: JSONType
16204 the JSON type used for this type on the wire.
16205 Since
16207 2.5
16208 JSONType (Enum)
16210 The four primitive and two structured types according to RFC 8259 sec‐
16211 tion 1, plus 'int' (split off 'number'), plus the obvious top type
16212 'value'.
16213 Values
16215 string Not documented
16216 number Not documented
16218 int Not documented
16220 boolean
16222 Not documented
16223 null Not documented
16225 object Not documented
16227 array Not documented
16229 value Not documented
16231 Since
16233 2.5
16234 SchemaInfoEnum (Object)
16236 Additional SchemaInfo members for meta-type 'enum'.
16237 Members
16239 members: array of SchemaInfoEnumMember
16240 the enum type's members, in no particular order (since 6.2).
16241 values: array of string
16243 the enumeration type's member names, in no particular order.
16244 Redundant with members. Just for backward compatibility.
16245 Features
16247 deprecated
16248 Member values is deprecated. Use members instead.
16249 Values of this type are JSON string on the wire.
16250 Since
16252 2.5
16253 SchemaInfoEnumMember (Object)
16255 An object member.
16256 Members
16258 name: string
16259 the member's name, as defined in the QAPI schema.
16260 features: array of string (optional)
16262 names of features associated with the member, in no particular
16263 order.
16264 Since
16266 6.2
16267 SchemaInfoArray (Object)
16269 Additional SchemaInfo members for meta-type 'array'.
16270 Members
16272 element-type: string
16273 the array type's element type.
16274 Values of this type are JSON array on the wire.
16275 Since
16277 2.5
16278 SchemaInfoObject (Object)
16280 Additional SchemaInfo members for meta-type 'object'.
16281 Members
16283 members: array of SchemaInfoObjectMember
16284 the object type's (non-variant) members, in no particular order.
16285 tag: string (optional)
16287 the name of the member serving as type tag. An element of mem‐
16288 bers with this name must exist.
16289 variants: array of SchemaInfoObjectVariant (optional)
16291 variant members, i.e. additional members that depend on the type
16292 tag's value. Present exactly when tag is present. The variants
16293 are in no particular order, and may even differ from the order
16294 of the values of the enum type of the tag.
16295 Values of this type are JSON object on the wire.
16296 Since
16298 2.5
16299 SchemaInfoObjectMember (Object)
16301 An object member.
16302 Members
16304 name: string
16305 the member's name, as defined in the QAPI schema.
16306 type: string
16308 the name of the member's type.
16309 default: value (optional)
16311 default when used as command parameter. If absent, the parame‐
16312 ter is mandatory. If present, the value must be null. The pa‐
16313 rameter is optional, and behavior when it's missing is not spec‐
16314 ified here. Future extension: if present and non-null, the pa‐
16315 rameter is optional, and defaults to this value.
16316 features: array of string (optional)
16318 names of features associated with the member, in no particular
16319 order. (since 5.0)
16320 Since
16322 2.5
16323 SchemaInfoObjectVariant (Object)
16325 The variant members for a value of the type tag.
16326 Members
16328 case: string
16329 a value of the type tag.
16330 type: string
16332 the name of the object type that provides the variant members
16333 when the type tag has value case.
16334 Since
16336 2.5
16337 SchemaInfoAlternate (Object)
16339 Additional SchemaInfo members for meta-type 'alternate'.
16340 Members
16342 members: array of SchemaInfoAlternateMember
16343 the alternate type's members, in no particular order. The mem‐
16344 bers' wire encoding is distinct, see docs/de‐
16345 vel/qapi-code-gen.txt section Alternate types.
16346 On the wire, this can be any of the members.
16347 Since
16349 2.5
16350 SchemaInfoAlternateMember (Object)
16352 An alternate member.
16353 Members
16355 type: string
16356 the name of the member's type.
16357 Since
16359 2.5
16360 SchemaInfoCommand (Object)
16362 Additional SchemaInfo members for meta-type 'command'.
16363 Members
16365 arg-type: string
16366 the name of the object type that provides the command's parame‐
16367 ters.
16368 ret-type: string
16370 the name of the command's result type.
16371 allow-oob: boolean (optional)
16373 whether the command allows out-of-band execution, defaults to
16374 false (Since: 2.12)
16375 TODO
16377 success-response (currently irrelevant, because it's QGA, not QMP)
16378 Since
16380 2.5
16381 SchemaInfoEvent (Object)
16383 Additional SchemaInfo members for meta-type 'event'.
16384 Members
16386 arg-type: string
16387 the name of the object type that provides the event's parame‐
16388 ters.
16389 Since
16391 2.5
16392
16394 ObjectPropertyInfo (Object)
16395 Members
16396 name: string
16397 the name of the property
16398 type: string
16400 the type of the property. This will typically come in one of
16401 four forms:
16402 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
16404 ble'. These types are mapped to the appropriate JSON type.
16405 2. A child type in the form 'child<subtype>' where subtype is a
16407 qdev device type name. Child properties create the composi‐
16408 tion tree.
16409 3. A link type in the form 'link<subtype>' where subtype is a
16411 qdev device type name. Link properties form the device model
16412 graph.
16413 description: string (optional)
16415 if specified, the description of the property.
16416 default-value: value (optional)
16418 the default value, if any (since 5.0)
16419 Since
16421 1.2
16422 qom-list (Command)
16424 This command will list any properties of a object given a path in the
16425 object model.
16426 Arguments
16428 path: string
16429 the path within the object model. See qom-get for a description
16430 of this parameter.
16431 Returns
16433 a list of ObjectPropertyInfo that describe the properties of the ob‐
16434 ject.
16435 Since
16437 1.2
16438 Example
16440 -> { "execute": "qom-list",
16441 "arguments": { "path": "/chardevs" } }
16442 <- { "return": [ { "name": "type", "type": "string" },
16443 { "name": "parallel0", "type": "child<chardev-vc>" },
16444 { "name": "serial0", "type": "child<chardev-vc>" },
16445 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
16446 qom-get (Command)
16448 This command will get a property from a object model path and return
16449 the value.
16450 Arguments
16452 path: string
16453 The path within the object model. There are two forms of sup‐
16454 ported paths--absolute and partial paths.
16455 Absolute paths are derived from the root object and can follow
16457 child<> or link<> properties. Since they can follow link<>
16458 properties, they can be arbitrarily long. Absolute paths look
16459 like absolute filenames and are prefixed with a leading slash.
16460 Partial paths look like relative filenames. They do not begin
16462 with a prefix. The matching rules for partial paths are subtle
16463 but designed to make specifying objects easy. At each level of
16464 the composition tree, the partial path is matched as an absolute
16465 path. The first match is not returned. At least two matches
16466 are searched for. A successful result is only returned if only
16467 one match is found. If more than one match is found, a flag is
16468 return to indicate that the match was ambiguous.
16469 property: string
16471 The property name to read
16472 Returns
16474 The property value. The type depends on the property type. child<> and
16475 link<> properties are returned as #str pathnames. All integer property
16476 types (u8, u16, etc) are returned as #int.
16477 Since
16479 1.2
16480 Example
16482 1. Use absolute path
16483 -> { "execute": "qom-get",
16485 "arguments": { "path": "/machine/unattached/device[0]",
16486 "property": "hotplugged" } }
16487 <- { "return": false }
16488 2. Use partial path
16490 -> { "execute": "qom-get",
16492 "arguments": { "path": "unattached/sysbus",
16493 "property": "type" } }
16494 <- { "return": "System" }
16495 qom-set (Command)
16497 This command will set a property from a object model path.
16498 Arguments
16500 path: string
16501 see qom-get for a description of this parameter
16502 property: string
16504 the property name to set
16505 value: value
16507 a value who's type is appropriate for the property type. See
16508 qom-get for a description of type mapping.
16509 Since
16511 1.2
16512 Example
16514 -> { "execute": "qom-set",
16515 "arguments": { "path": "/machine",
16516 "property": "graphics",
16517 "value": false } }
16518 <- { "return": {} }
16519 ObjectTypeInfo (Object)
16521 This structure describes a search result from qom-list-types
16522 Members
16524 name: string
16525 the type name found in the search
16526 abstract: boolean (optional)
16528 the type is abstract and can't be directly instantiated. Omit‐
16529 ted if false. (since 2.10)
16530 parent: string (optional)
16532 Name of parent type, if any (since 2.10)
16533 Since
16535 1.1
16536 qom-list-types (Command)
16538 This command will return a list of types given search parameters
16539 Arguments
16541 implements: string (optional)
16542 if specified, only return types that implement this type name
16543 abstract: boolean (optional)
16545 if true, include abstract types in the results
16546 Returns
16548 a list of ObjectTypeInfo or an empty list if no results are found
16549 Since
16551 1.1
16552 qom-list-properties (Command)
16554 List properties associated with a QOM object.
16555 Arguments
16557 typename: string
16558 the type name of an object
16559 Note
16561 objects can create properties at runtime, for example to describe links
16562 between different devices and/or objects. These properties are not in‐
16563 cluded in the output of this command.
16564 Returns
16566 a list of ObjectPropertyInfo describing object properties
16567 Since
16569 2.12
16570 CanHostSocketcanProperties (Object)
16572 Properties for can-host-socketcan objects.
16573 Members
16575 if: string
16576 interface name of the host system CAN bus to connect to
16577 canbus: string
16579 object ID of the can-bus object to connect to the host interface
16580 Since
16582 2.12
16583 ColoCompareProperties (Object)
16585 Properties for colo-compare objects.
16586 Members
16588 primary_in: string
16589 name of the character device backend to use for the primary in‐
16590 put (incoming packets are redirected to outdev)
16591 secondary_in: string
16593 name of the character device backend to use for secondary input
16594 (incoming packets are only compared to the input on primary_in
16595 and then dropped)
16596 outdev: string
16598 name of the character device backend to use for output
16599 iothread: string
16601 name of the iothread to run in
16602 notify_dev: string (optional)
16604 name of the character device backend to be used to communicate
16605 with the remote colo-frame (only for Xen COLO)
16606 compare_timeout: int (optional)
16608 the maximum time to hold a packet from primary_in for comparison
16609 with an incoming packet on secondary_in in milliseconds (de‐
16610 fault: 3000)
16611 expired_scan_cycle: int (optional)
16613 the interval at which colo-compare checks whether packets from
16614 primary have timed out, in milliseconds (default: 3000)
16615 max_queue_size: int (optional)
16617 the maximum number of packets to keep in the queue for comparing
16618 with incoming packets from secondary_in. If the queue is full
16619 and additional packets are received, the additional packets are
16620 dropped. (default: 1024)
16621 vnet_hdr_support: boolean (optional)
16623 if true, vnet header support is enabled (default: false)
16624 Since
16626 2.8
16627 CryptodevBackendProperties (Object)
16629 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
16630 Members
16632 queues: int (optional)
16633 the number of queues for the cryptodev backend. Ignored for
16634 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
16635 (default: 1)
16636 Since
16638 2.8
16639 CryptodevVhostUserProperties (Object)
16641 Properties for cryptodev-vhost-user objects.
16642 Members
16644 chardev: string
16645 the name of a Unix domain socket character device that connects
16646 to the vhost-user server
16647 The members of CryptodevBackendProperties
16649 Since
16651 2.12
16652 DBusVMStateProperties (Object)
16654 Properties for dbus-vmstate objects.
16655 Members
16657 addr: string
16658 the name of the DBus bus to connect to
16659 id-list: string (optional)
16661 a comma separated list of DBus IDs of helpers whose data should
16662 be included in the VM state on migration
16663 Since
16665 5.0
16666 NetfilterInsert (Enum)
16668 Indicates where to insert a netfilter relative to a given other filter.
16669 Values
16671 before insert before the specified filter
16672 behind insert behind the specified filter
16674 Since
16676 5.0
16677 NetfilterProperties (Object)
16679 Properties for objects of classes derived from netfilter.
16680 Members
16682 netdev: string
16683 id of the network device backend to filter
16684 queue: NetFilterDirection (optional)
16686 indicates which queue(s) to filter (default: all)
16687 status: string (optional)
16689 indicates whether the filter is enabled ("on") or disabled
16690 ("off") (default: "on")
16691 position: string (optional)
16693 specifies where the filter should be inserted in the filter
16694 list. "head" means the filter is inserted at the head of the
16695 filter list, before any existing filters. "tail" means the fil‐
16696 ter is inserted at the tail of the filter list, behind any ex‐
16697 isting filters (default). "id=<id>" means the filter is in‐
16698 serted before or behind the filter specified by <id>, depending
16699 on the insert property. (default: "tail")
16700 insert: NetfilterInsert (optional)
16702 where to insert the filter relative to the filter given in posi‐
16703 tion. Ignored if position is "head" or "tail". (default: be‐
16704 hind)
16705 Since
16707 2.5
16708 FilterBufferProperties (Object)
16710 Properties for filter-buffer objects.
16711 Members
16713 interval: int
16714 a non-zero interval in microseconds. All packets arriving in
16715 the given interval are delayed until the end of the interval.
16716 The members of NetfilterProperties
16718 Since
16720 2.5
16721 FilterDumpProperties (Object)
16723 Properties for filter-dump objects.
16724 Members
16726 file: string
16727 the filename where the dumped packets should be stored
16728 maxlen: int (optional)
16730 maximum number of bytes in a packet that are stored (default:
16731 65536)
16732 The members of NetfilterProperties
16734 Since
16736 2.5
16737 FilterMirrorProperties (Object)
16739 Properties for filter-mirror objects.
16740 Members
16742 outdev: string
16743 the name of a character device backend to which all incoming
16744 packets are mirrored
16745 vnet_hdr_support: boolean (optional)
16747 if true, vnet header support is enabled (default: false)
16748 The members of NetfilterProperties
16750 Since
16752 2.6
16753 FilterRedirectorProperties (Object)
16755 Properties for filter-redirector objects.
16756 At least one of indev or outdev must be present. If both are present,
16758 they must not refer to the same character device backend.
16759 Members
16761 indev: string (optional)
16762 the name of a character device backend from which packets are
16763 received and redirected to the filtered network device
16764 outdev: string (optional)
16766 the name of a character device backend to which all incoming
16767 packets are redirected
16768 vnet_hdr_support: boolean (optional)
16770 if true, vnet header support is enabled (default: false)
16771 The members of NetfilterProperties
16773 Since
16775 2.6
16776 FilterRewriterProperties (Object)
16778 Properties for filter-rewriter objects.
16779 Members
16781 vnet_hdr_support: boolean (optional)
16782 if true, vnet header support is enabled (default: false)
16783 The members of NetfilterProperties
16785 Since
16787 2.8
16788 InputBarrierProperties (Object)
16790 Properties for input-barrier objects.
16791 Members
16793 name: string
16794 the screen name as declared in the screens section of bar‐
16795 rier.conf
16796 server: string (optional)
16798 hostname of the Barrier server (default: "localhost")
16799 port: string (optional)
16801 TCP port of the Barrier server (default: "24800")
16802 x-origin: string (optional)
16804 x coordinate of the leftmost pixel on the guest screen (default:
16805 "0")
16806 y-origin: string (optional)
16808 y coordinate of the topmost pixel on the guest screen (default:
16809 "0")
16810 width: string (optional)
16812 the width of secondary screen in pixels (default: "1920")
16813 height: string (optional)
16815 the height of secondary screen in pixels (default: "1080")
16816 Since
16818 4.2
16819 InputLinuxProperties (Object)
16821 Properties for input-linux objects.
16822 Members
16824 evdev: string
16825 the path of the host evdev device to use
16826 grab_all: boolean (optional)
16828 if true, grab is toggled for all devices (e.g. both keyboard and
16829 mouse) instead of just one device (default: false)
16830 repeat: boolean (optional)
16832 enables auto-repeat events (default: false)
16833 grab-toggle: GrabToggleKeys (optional)
16835 the key or key combination that toggles device grab (default:
16836 ctrl-ctrl)
16837 Since
16839 2.6
16840 IothreadProperties (Object)
16842 Properties for iothread objects.
16843 Members
16845 poll-max-ns: int (optional)
16846 the maximum number of nanoseconds to busy wait for events. 0
16847 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
16848 erwise)
16849 poll-grow: int (optional)
16851 the multiplier used to increase the polling time when the algo‐
16852 rithm detects it is missing events due to not polling long
16853 enough. 0 selects a default behaviour (default: 0)
16854 poll-shrink: int (optional)
16856 the divisor used to decrease the polling time when the algorithm
16857 detects it is spending too long polling without encountering
16858 events. 0 selects a default behaviour (default: 0)
16859 aio-max-batch: int (optional)
16861 maximum number of requests in a batch for the AIO engine, 0
16862 means that the engine will use its default (default:0, since
16863 6.1)
16864 Since
16866 2.0
16867 MemoryBackendProperties (Object)
16869 Properties for objects of classes derived from memory-backend.
16870 Members
16872 merge: boolean (optional)
16873 if true, mark the memory as mergeable (default depends on the
16874 machine type)
16875 dump: boolean (optional)
16877 if true, include the memory in core dumps (default depends on
16878 the machine type)
16879 host-nodes: array of int (optional)
16881 the list of NUMA host nodes to bind the memory to
16882 policy: HostMemPolicy (optional)
16884 the NUMA policy (default: 'default')
16885 prealloc: boolean (optional)
16887 if true, preallocate memory (default: false)
16888 prealloc-threads: int (optional)
16890 number of CPU threads to use for prealloc (default: 1)
16891 share: boolean (optional)
16893 if false, the memory is private to QEMU; if true, it is shared
16894 (default: false)
16895 reserve: boolean (optional)
16897 if true, reserve swap space (or huge pages) if applicable (de‐
16898 fault: true) (since 6.1)
16899 size: int
16901 size of the memory region in bytes
16902 x-use-canonical-path-for-ramblock-id: boolean (optional)
16904 if true, the canoncial path is used for ramblock-id. Disable
16905 this for 4.0 machine types or older to allow migration with
16906 newer QEMU versions. (default: false generally, but true for
16907 machine types <= 4.0)
16908 Note
16910 prealloc=true and reserve=false cannot be set at the same time. With
16911 reserve=true, the behavior depends on the operating system: for exam‐
16912 ple, Linux will not reserve swap space for shared file mappings -- "not
16913 applicable". In contrast, reserve=false will bail out if it cannot be
16914 configured accordingly.
16915 Since
16917 2.1
16918 MemoryBackendFileProperties (Object)
16920 Properties for memory-backend-file objects.
16921 Members
16923 align: int (optional)
16924 the base address alignment when QEMU mmap(2)s mem-path. Some
16925 backend stores specified by mem-path require an alignment dif‐
16926 ferent than the default one used by QEMU, e.g. the device DAX
16927 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
16928 users can specify the required alignment via this option. 0 se‐
16929 lects a default alignment (currently the page size). (default:
16930 0)
16931 discard-data: boolean (optional)
16933 if true, the file contents can be destroyed when QEMU exits, to
16934 avoid unnecessarily flushing data to the backing file. Note that
16935 discard-data is only an optimization, and QEMU might not discard
16936 file contents if it aborts unexpectedly or is terminated using
16937 SIGKILL. (default: false)
16938 mem-path: string
16940 the path to either a shared memory or huge page filesystem mount
16941 pmem: boolean (optional) (If: CONFIG_LIBPMEM)
16943 specifies whether the backing file specified by mem-path is in
16944 host persistent memory that can be accessed using the SNIA NVM
16945 programming model (e.g. Intel NVDIMM).
16946 readonly: boolean (optional)
16948 if true, the backing file is opened read-only; if false, it is
16949 opened read-write. (default: false)
16950 The members of MemoryBackendProperties
16952 Since
16954 2.1
16955 MemoryBackendMemfdProperties (Object)
16957 Properties for memory-backend-memfd objects.
16958 The share boolean option is true by default with memfd.
16960 Members
16962 hugetlb: boolean (optional)
16963 if true, the file to be created resides in the hugetlbfs
16964 filesystem (default: false)
16965 hugetlbsize: int (optional)
16967 the hugetlb page size on systems that support multiple hugetlb
16968 page sizes (it must be a power of 2 value supported by the sys‐
16969 tem). 0 selects a default page size. This option is ignored if
16970 hugetlb is false. (default: 0)
16971 seal: boolean (optional)
16973 if true, create a sealed-file, which will block further resizing
16974 of the memory (default: true)
16975 The members of MemoryBackendProperties
16977 Since
16979 2.12
16980 MemoryBackendEpcProperties (Object)
16982 Properties for memory-backend-epc objects.
16983 The share boolean option is true by default with epc
16985 The merge boolean option is false by default with epc
16987 The dump boolean option is false by default with epc
16989 Members
16991 The members of MemoryBackendProperties
16992 Since
16994 6.2
16995 PrManagerHelperProperties (Object)
16997 Properties for pr-manager-helper objects.
16998 Members
17000 path: string
17001 the path to a Unix domain socket for connecting to the external
17002 helper
17003 Since
17005 2.11
17006 QtestProperties (Object)
17008 Properties for qtest objects.
17009 Members
17011 chardev: string
17012 the chardev to be used to receive qtest commands on.
17013 log: string (optional)
17015 the path to a log file
17016 Since
17018 6.0
17019 RemoteObjectProperties (Object)
17021 Properties for x-remote-object objects.
17022 Members
17024 fd: string
17025 file descriptor name previously passed via 'getfd' command
17026 devid: string
17028 the id of the device to be associated with the file descriptor
17029 Since
17031 6.0
17032 RngProperties (Object)
17034 Properties for objects of classes derived from rng.
17035 Members
17037 opened: boolean (optional)
17038 if true, the device is opened immediately when applying this op‐
17039 tion and will probably fail when processing the next option.
17040 Don't use; only provided for compatibility. (default: false)
17041 Features
17043 deprecated
17044 Member opened is deprecated. Setting true doesn't make sense,
17045 and false is already the default.
17046 Since
17048 1.3
17049 RngEgdProperties (Object)
17051 Properties for rng-egd objects.
17052 Members
17054 chardev: string
17055 the name of a character device backend that provides the connec‐
17056 tion to the RNG daemon
17057 The members of RngProperties
17059 Since
17061 1.3
17062 RngRandomProperties (Object)
17064 Properties for rng-random objects.
17065 Members
17067 filename: string (optional)
17068 the filename of the device on the host to obtain entropy from
17069 (default: "/dev/urandom")
17070 The members of RngProperties
17072 Since
17074 1.3
17075 SevGuestProperties (Object)
17077 Properties for sev-guest objects.
17078 Members
17080 sev-device: string (optional)
17081 SEV device to use (default: "/dev/sev")
17082 dh-cert-file: string (optional)
17084 guest owners DH certificate (encoded with base64)
17085 session-file: string (optional)
17087 guest owners session parameters (encoded with base64)
17088 policy: int (optional)
17090 SEV policy value (default: 0x1)
17091 handle: int (optional)
17093 SEV firmware handle (default: 0)
17094 cbitpos: int (optional)
17096 C-bit location in page table entry (default: 0)
17097 reduced-phys-bits: int
17099 number of bits in physical addresses that become unavailable
17100 when SEV is enabled
17101 kernel-hashes: boolean (optional)
17103 if true, add hashes of kernel/initrd/cmdline to a designated
17104 guest firmware page for measured boot with -kernel (default:
17105 false) (since 6.2)
17106 Since
17108 2.12
17109 ObjectType (Enum)
17111 Values
17112 authz-list
17113 Not documented
17114 authz-listfile
17116 Not documented
17117 authz-pam
17119 Not documented
17120 authz-simple
17122 Not documented
17123 can-bus
17125 Not documented
17126 can-host-socketcan (If: CONFIG_LINUX)
17128 Not documented
17129 colo-compare
17131 Not documented
17132 cryptodev-backend
17134 Not documented
17135 cryptodev-backend-builtin
17137 Not documented
17138 cryptodev-vhost-user (If: CONFIG_VHOST_CRYPTO)
17140 Not documented
17141 dbus-vmstate
17143 Not documented
17144 filter-buffer
17146 Not documented
17147 filter-dump
17149 Not documented
17150 filter-mirror
17152 Not documented
17153 filter-redirector
17155 Not documented
17156 filter-replay
17158 Not documented
17159 filter-rewriter
17161 Not documented
17162 input-barrier
17164 Not documented
17165 input-linux (If: CONFIG_LINUX)
17167 Not documented
17168 iothread
17170 Not documented
17171 memory-backend-epc (If: CONFIG_LINUX)
17173 Not documented
17174 memory-backend-file
17176 Not documented
17177 memory-backend-memfd (If: CONFIG_LINUX)
17179 Not documented
17180 memory-backend-ram
17182 Not documented
17183 pef-guest
17185 Not documented
17186 pr-manager-helper (If: CONFIG_LINUX)
17188 Not documented
17189 qtest Not documented
17191 rng-builtin
17193 Not documented
17194 rng-egd
17196 Not documented
17197 rng-random (If: CONFIG_POSIX)
17199 Not documented
17200 secret Not documented
17202 secret_keyring (If: CONFIG_SECRET_KEYRING)
17204 Not documented
17205 sev-guest
17207 Not documented
17208 s390-pv-guest
17210 Not documented
17211 throttle-group
17213 Not documented
17214 tls-creds-anon
17216 Not documented
17217 tls-creds-psk
17219 Not documented
17220 tls-creds-x509
17222 Not documented
17223 tls-cipher-suites
17225 Not documented
17226 x-remote-object
17228 Not documented
17229 Features
17231 unstable
17232 Member x-remote-object is experimental.
17233 Since
17235 6.0
17236 ObjectOptions (Object)
17238 Describes the options of a user creatable QOM object.
17239 Members
17241 qom-type: ObjectType
17242 the class name for the object to be created
17243 id: string
17245 the name of the new object
17246 The members of AuthZListProperties when qom-type is "authz-list"
17248 The members of AuthZListFileProperties when qom-type is "authz-list‐
17250 file"
17251 The members of AuthZPAMProperties when qom-type is "authz-pam"
17253 The members of AuthZSimpleProperties when qom-type is "authz-simple"
17255 The members of CanHostSocketcanProperties when qom-type is
17257 "can-host-socketcan" (If: CONFIG_LINUX)
17258 The members of ColoCompareProperties when qom-type is "colo-compare"
17260 The members of CryptodevBackendProperties when qom-type is "cryp‐
17262 todev-backend"
17263 The members of CryptodevBackendProperties when qom-type is "cryp‐
17265 todev-backend-builtin"
17266 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
17268 todev-vhost-user" (If: CONFIG_VHOST_CRYPTO)
17269 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
17271 The members of FilterBufferProperties when qom-type is "filter-buffer"
17273 The members of FilterDumpProperties when qom-type is "filter-dump"
17275 The members of FilterMirrorProperties when qom-type is "filter-mirror"
17277 The members of FilterRedirectorProperties when qom-type is "fil‐
17279 ter-redirector"
17280 The members of NetfilterProperties when qom-type is "filter-replay"
17282 The members of FilterRewriterProperties when qom-type is "fil‐
17284 ter-rewriter"
17285 The members of InputBarrierProperties when qom-type is "input-barrier"
17287 The members of InputLinuxProperties when qom-type is "input-linux" (If:
17289 CONFIG_LINUX)
17290 The members of IothreadProperties when qom-type is "iothread"
17292 The members of MemoryBackendEpcProperties when qom-type is "mem‐
17294 ory-backend-epc" (If: CONFIG_LINUX)
17295 The members of MemoryBackendFileProperties when qom-type is "mem‐
17297 ory-backend-file"
17298 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
17300 ory-backend-memfd" (If: CONFIG_LINUX)
17301 The members of MemoryBackendProperties when qom-type is "memory-back‐
17303 end-ram"
17304 The members of PrManagerHelperProperties when qom-type is "pr-man‐
17306 ager-helper" (If: CONFIG_LINUX)
17307 The members of QtestProperties when qom-type is "qtest"
17309 The members of RngProperties when qom-type is "rng-builtin"
17311 The members of RngEgdProperties when qom-type is "rng-egd"
17313 The members of RngRandomProperties when qom-type is "rng-random" (If:
17315 CONFIG_POSIX)
17316 The members of SecretProperties when qom-type is "secret"
17318 The members of SecretKeyringProperties when qom-type is "se‐
17320 cret_keyring" (If: CONFIG_SECRET_KEYRING)
17321 The members of SevGuestProperties when qom-type is "sev-guest"
17323 The members of ThrottleGroupProperties when qom-type is "throt‐
17325 tle-group"
17326 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
17328 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
17330 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
17332 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
17334 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
17336 ject"
17337 Since
17339 6.0
17340 object-add (Command)
17342 Create a QOM object.
17343 Arguments
17345 The members of ObjectOptions
17346 Returns
17348 Nothing on success Error if qom-type is not a valid class name
17349 Since
17351 2.0
17352 Example
17354 -> { "execute": "object-add",
17355 "arguments": { "qom-type": "rng-random", "id": "rng1",
17356 "filename": "/dev/hwrng" } }
17357 <- { "return": {} }
17358 object-del (Command)
17360 Remove a QOM object.
17361 Arguments
17363 id: string
17364 the name of the QOM object to remove
17365 Returns
17367 Nothing on success Error if id is not a valid id for a QOM object
17368 Since
17370 2.0
17371 Example
17373 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
17374 <- { "return": {} }
17375
17377 device-list-properties (Command)
17378 List properties associated with a device.
17379 Arguments
17381 typename: string
17382 the type name of a device
17383 Returns
17385 a list of ObjectPropertyInfo describing a devices properties
17386 Note
17388 objects can create properties at runtime, for example to describe links
17389 between different devices and/or objects. These properties are not in‐
17390 cluded in the output of this command.
17391 Since
17393 1.2
17394 device_add (Command)
17396 Add a device.
17397 Arguments
17399 driver: string
17400 the name of the new device's driver
17401 bus: string (optional)
17403 the device's parent bus (device tree path)
17404 id: string (optional)
17406 the device's ID, must be unique
17407 Features
17409 json-cli
17410 If present, the "-device" command line option supports JSON syn‐
17411 tax with a structure identical to the arguments of this command.
17412 json-cli-hotplug
17414 If present, the "-device" command line option supports JSON syn‐
17415 tax without the reference counting leak that broke hot-unplug
17416 Notes
17418 Additional arguments depend on the type.
17419 1. For detailed information about this command, please refer to the
17421 'docs/qdev-device-use.txt' file.
17422 2. It's possible to list device properties by running QEMU with the
17424 "-device DEVICE,help" command-line argument, where DEVICE is the de‐
17425 vice's name
17426 Example
17428 -> { "execute": "device_add",
17429 "arguments": { "driver": "e1000", "id": "net1",
17430 "bus": "pci.0",
17431 "mac": "52:54:00:12:34:56" } }
17432 <- { "return": {} }
17433 TODO
17435 This command effectively bypasses QAPI completely due to its "addi‐
17436 tional arguments" business. It shouldn't have been added to the schema
17437 in this form. It should be qapified properly, or replaced by a prop‐
17438 erly qapified command.
17439 Since
17441 0.13
17442 device_del (Command)
17444 Remove a device from a guest
17445 Arguments
17447 id: string
17448 the device's ID or QOM path
17449 Returns
17451 Nothing on success If id is not a valid device, DeviceNotFound
17452 Notes
17454 When this command completes, the device may not be removed from the
17455 guest. Hot removal is an operation that requires guest cooperation.
17456 This command merely requests that the guest begin the hot removal
17457 process. Completion of the device removal process is signaled with a
17458 DEVICE_DELETED event. Guest reset will automatically complete removal
17459 for all devices. If a guest-side error in the hot removal process is
17460 detected, the device will not be removed and a DEVICE_UNPLUG_GUEST_ER‐
17461 ROR event is sent. Some errors cannot be detected.
17462 Since
17464 0.14
17465 Example
17467 -> { "execute": "device_del",
17468 "arguments": { "id": "net1" } }
17469 <- { "return": {} }
17470 -> { "execute": "device_del",
17472 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
17473 <- { "return": {} }
17474 DEVICE_DELETED (Event)
17476 Emitted whenever the device removal completion is acknowledged by the
17477 guest. At this point, it's safe to reuse the specified device ID. De‐
17478 vice removal can be initiated by the guest or by HMP/QMP commands.
17479 Arguments
17481 device: string (optional)
17482 the device's ID if it has one
17483 path: string
17485 the device's QOM path
17486 Since
17488 1.5
17489 Example
17491 <- { "event": "DEVICE_DELETED",
17492 "data": { "device": "virtio-net-pci-0",
17493 "path": "/machine/peripheral/virtio-net-pci-0" },
17494 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
17495 DEVICE_UNPLUG_GUEST_ERROR (Event)
17497 Emitted when a device hot unplug fails due to a guest reported error.
17498 Arguments
17500 device: string (optional)
17501 the device's ID if it has one
17502 path: string
17504 the device's QOM path
17505 Since
17507 6.2
17508 Example
17510 <- { "event": "DEVICE_UNPLUG_GUEST_ERROR"
17511 "data": { "device": "core1",
17512 "path": "/machine/peripheral/core1" },
17513 },
17514 "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
17515
17517 SysEmuTarget (Enum)
17518 The comprehensive enumeration of QEMU system emulation ("softmmu") tar‐
17519 gets. Run "./configure --help" in the project root directory, and look
17520 for the *-softmmu targets near the "--target-list" option. The individ‐
17521 ual target constants are not documented here, for the time being.
17522 Values
17524 rx since 5.0
17525 avr since 5.1
17527 aarch64
17529 Not documented
17530 alpha Not documented
17532 arm Not documented
17534 cris Not documented
17536 hppa Not documented
17538 i386 Not documented
17540 m68k Not documented
17542 microblaze
17544 Not documented
17545 microblazeel
17547 Not documented
17548 mips Not documented
17550 mips64 Not documented
17552 mips64el
17554 Not documented
17555 mipsel Not documented
17557 nios2 Not documented
17559 or1k Not documented
17561 ppc Not documented
17563 ppc64 Not documented
17565 riscv32
17567 Not documented
17568 riscv64
17570 Not documented
17571 s390x Not documented
17573 sh4 Not documented
17575 sh4eb Not documented
17577 sparc Not documented
17579 sparc64
17581 Not documented
17582 tricore
17584 Not documented
17585 x86_64 Not documented
17587 xtensa Not documented
17589 xtensaeb
17591 Not documented
17592 Notes
17594 The resulting QMP strings can be appended to the "qemu-system-" prefix
17595 to produce the corresponding QEMU executable name. This is true even
17596 for "qemu-system-x86_64".
17597 Since
17599 3.0
17600 CpuS390State (Enum)
17602 An enumeration of cpu states that can be assumed by a virtual S390 CPU
17603 Values
17605 uninitialized
17606 Not documented
17607 stopped
17609 Not documented
17610 check-stop
17612 Not documented
17613 operating
17615 Not documented
17616 load Not documented
17618 Since
17620 2.12
17621 CpuInfoS390 (Object)
17623 Additional information about a virtual S390 CPU
17624 Members
17626 cpu-state: CpuS390State
17627 the virtual CPU's state
17628 Since
17630 2.12
17631 CpuInfoFast (Object)
17633 Information about a virtual CPU
17634 Members
17636 cpu-index: int
17637 index of the virtual CPU
17638 qom-path: string
17640 path to the CPU object in the QOM tree
17641 thread-id: int
17643 ID of the underlying host thread
17644 props: CpuInstanceProperties (optional)
17646 properties describing to which node/socket/core/thread virtual
17647 CPU belongs to, provided if supported by board
17648 target: SysEmuTarget
17650 the QEMU system emulation target, which determines which addi‐
17651 tional fields will be listed (since 3.0)
17652 The members of CpuInfoS390 when target is "s390x"
17654 Since
17656 2.12
17657 query-cpus-fast (Command)
17659 Returns information about all virtual CPUs.
17660 Returns
17662 list of CpuInfoFast
17663 Since
17665 2.12
17666 Example
17668 -> { "execute": "query-cpus-fast" }
17669 <- { "return": [
17670 {
17671 "thread-id": 25627,
17672 "props": {
17673 "core-id": 0,
17674 "thread-id": 0,
17675 "socket-id": 0
17676 },
17677 "qom-path": "/machine/unattached/device[0]",
17678 "target":"x86_64",
17679 "cpu-index": 0
17680 },
17681 {
17682 "thread-id": 25628,
17683 "props": {
17684 "core-id": 0,
17685 "thread-id": 0,
17686 "socket-id": 1
17687 },
17688 "qom-path": "/machine/unattached/device[2]",
17689 "target":"x86_64",
17690 "cpu-index": 1
17691 }
17692 ]
17693 }
17694 MachineInfo (Object)
17696 Information describing a machine.
17697 Members
17699 name: string
17700 the name of the machine
17701 alias: string (optional)
17703 an alias for the machine name
17704 is-default: boolean (optional)
17706 whether the machine is default
17707 cpu-max: int
17709 maximum number of CPUs supported by the machine type (since 1.5)
17710 hotpluggable-cpus: boolean
17712 cpu hotplug via -device is supported (since 2.7)
17713 numa-mem-supported: boolean
17715 true if '-numa node,mem' option is supported by the machine type
17716 and false otherwise (since 4.1)
17717 deprecated: boolean
17719 if true, the machine type is deprecated and may be removed in
17720 future versions of QEMU according to the QEMU deprecation policy
17721 (since 4.1)
17722 default-cpu-type: string (optional)
17724 default CPU model typename if none is requested via the -cpu ar‐
17725 gument. (since 4.2)
17726 default-ram-id: string (optional)
17728 the default ID of initial RAM memory backend (since 5.2)
17729 Since
17731 1.2
17732 query-machines (Command)
17734 Return a list of supported machines
17735 Returns
17737 a list of MachineInfo
17738 Since
17740 1.2
17741 CurrentMachineParams (Object)
17743 Information describing the running machine parameters.
17744 Members
17746 wakeup-suspend-support: boolean
17747 true if the machine supports wake up from suspend
17748 Since
17750 4.0
17751 query-current-machine (Command)
17753 Return information on the current virtual machine.
17754 Returns
17756 CurrentMachineParams
17757 Since
17759 4.0
17760 TargetInfo (Object)
17762 Information describing the QEMU target.
17763 Members
17765 arch: SysEmuTarget
17766 the target architecture
17767 Since
17769 1.2
17770 query-target (Command)
17772 Return information about the target for this QEMU
17773 Returns
17775 TargetInfo
17776 Since
17778 1.2
17779 UuidInfo (Object)
17781 Guest UUID information (Universally Unique Identifier).
17782 Members
17784 UUID: string
17785 the UUID of the guest
17786 Since
17788 0.14
17789 Notes
17791 If no UUID was specified for the guest, a null UUID is returned.
17792 query-uuid (Command)
17794 Query the guest UUID information.
17795 Returns
17797 The UuidInfo for the guest
17798 Since
17800 0.14
17801 Example
17803 -> { "execute": "query-uuid" }
17804 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
17805 GuidInfo (Object)
17807 GUID information.
17808 Members
17810 guid: string
17811 the globally unique identifier
17812 Since
17814 2.9
17815 query-vm-generation-id (Command)
17817 Show Virtual Machine Generation ID
17818 Since
17820 2.9
17821 system_reset (Command)
17823 Performs a hard reset of a guest.
17824 Since
17826 0.14
17827 Example
17829 -> { "execute": "system_reset" }
17830 <- { "return": {} }
17831 system_powerdown (Command)
17833 Requests that a guest perform a powerdown operation.
17834 Since
17836 0.14
17837 Notes
17839 A guest may or may not respond to this command. This command returning
17840 does not indicate that a guest has accepted the request or that it has
17841 shut down. Many guests will respond to this command by prompting the
17842 user in some way.
17843 Example
17845 -> { "execute": "system_powerdown" }
17846 <- { "return": {} }
17847 system_wakeup (Command)
17849 Wake up guest from suspend. If the guest has wake-up from suspend sup‐
17850 port enabled (wakeup-suspend-support flag from query-current-machine),
17851 wake-up guest from suspend if the guest is in SUSPENDED state. Return
17852 an error otherwise.
17853 Since
17855 1.1
17856 Returns
17858 nothing.
17859 Note
17861 prior to 4.0, this command does nothing in case the guest isn't sus‐
17862 pended.
17863 Example
17865 -> { "execute": "system_wakeup" }
17866 <- { "return": {} }
17867 LostTickPolicy (Enum)
17869 Policy for handling lost ticks in timer devices. Ticks end up getting
17870 lost when, for example, the guest is paused.
17871 Values
17873 discard
17874 throw away the missed ticks and continue with future injection
17875 normally. The guest OS will see the timer jump ahead by a po‐
17876 tentially quite significant amount all at once, as if the inter‐
17877 vening chunk of time had simply not existed; needless to say,
17878 such a sudden jump can easily confuse a guest OS which is not
17879 specifically prepared to deal with it. Assuming the guest OS
17880 can deal correctly with the time jump, the time in the guest and
17881 in the host should now match.
17882 delay continue to deliver ticks at the normal rate. The guest OS will
17884 not notice anything is amiss, as from its point of view time
17885 will have continued to flow normally. The time in the guest
17886 should now be behind the time in the host by exactly the amount
17887 of time during which ticks have been missed.
17888 slew deliver ticks at a higher rate to catch up with the missed
17890 ticks. The guest OS will not notice anything is amiss, as from
17891 its point of view time will have continued to flow normally.
17892 Once the timer has managed to catch up with all the missing
17893 ticks, the time in the guest and in the host should match.
17894 Since
17896 2.0
17897 inject-nmi (Command)
17899 Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all
17900 CPUs (ppc64). The command fails when the guest doesn't support inject‐
17901 ing.
17902 Returns
17904 If successful, nothing
17905 Since
17907 0.14
17908 Note
17910 prior to 2.1, this command was only supported for x86 and s390 VMs
17911 Example
17913 -> { "execute": "inject-nmi" }
17914 <- { "return": {} }
17915 KvmInfo (Object)
17917 Information about support for KVM acceleration
17918 Members
17920 enabled: boolean
17921 true if KVM acceleration is active
17922 present: boolean
17924 true if KVM acceleration is built into this executable
17925 Since
17927 0.14
17928 query-kvm (Command)
17930 Returns information about KVM acceleration
17931 Returns
17933 KvmInfo
17934 Since
17936 0.14
17937 Example
17939 -> { "execute": "query-kvm" }
17940 <- { "return": { "enabled": true, "present": true } }
17941 NumaOptionsType (Enum)
17943 Values
17944 node NUMA nodes configuration
17945 dist NUMA distance configuration (since 2.10)
17947 cpu property based CPU(s) to node mapping (Since: 2.10)
17949 hmat-lb
17951 memory latency and bandwidth information (Since: 5.0)
17952 hmat-cache
17954 memory side cache information (Since: 5.0)
17955 Since
17957 2.1
17958 NumaOptions (Object)
17960 A discriminated record of NUMA options. (for OptsVisitor)
17961 Members
17963 type: NumaOptionsType
17964 Not documented
17965 The members of NumaNodeOptions when type is "node"
17967 The members of NumaDistOptions when type is "dist"
17969 The members of NumaCpuOptions when type is "cpu"
17971 The members of NumaHmatLBOptions when type is "hmat-lb"
17973 The members of NumaHmatCacheOptions when type is "hmat-cache"
17975 Since
17977 2.1
17978 NumaNodeOptions (Object)
17980 Create a guest NUMA node. (for OptsVisitor)
17981 Members
17983 nodeid: int (optional)
17984 NUMA node ID (increase by 1 from 0 if omitted)
17985 cpus: array of int (optional)
17987 VCPUs belonging to this node (assign VCPUS round-robin
17989 if omitted)
17990 mem: int (optional)
17992 memory size of this node; mutually exclusive with memdev.
17993 Equally divide total memory among nodes if both mem and memdev
17994 are omitted.
17995 memdev: string (optional)
17997 memory backend object. If specified for one node, it must be
17998 specified for all nodes.
17999 initiator: int (optional)
18001 defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the
18002 nodeid which has the memory controller responsible for this NUMA
18003 node. This field provides additional information as to the ini‐
18004 tiator node that is closest (as in directly attached) to this
18005 node, and therefore has the best performance (since 5.0)
18006 Since
18008 2.1
18009 NumaDistOptions (Object)
18011 Set the distance between 2 NUMA nodes.
18012 Members
18014 src: int
18015 source NUMA node.
18016 dst: int
18018 destination NUMA node.
18019 val: int
18021 NUMA distance from source node to destination node. When a node
18022 is unreachable from another node, set the distance between them
18023 to 255.
18024 Since
18026 2.10
18027 X86CPURegister32 (Enum)
18029 A X86 32-bit register
18030 Values
18032 EAX Not documented
18033 EBX Not documented
18035 ECX Not documented
18037 EDX Not documented
18039 ESP Not documented
18041 EBP Not documented
18043 ESI Not documented
18045 EDI Not documented
18047 Since
18049 1.5
18050 X86CPUFeatureWordInfo (Object)
18052 Information about a X86 CPU feature word
18053 Members
18055 cpuid-input-eax: int
18056 Input EAX value for CPUID instruction for that feature word
18057 cpuid-input-ecx: int (optional)
18059 Input ECX value for CPUID instruction for that feature word
18060 cpuid-register: X86CPURegister32
18062 Output register containing the feature bits
18063 features: int
18065 value of output register, containing the feature bits
18066 Since
18068 1.5
18069 DummyForceArrays (Object)
18071 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList inter‐
18072 nally
18073 Members
18075 unused: array of X86CPUFeatureWordInfo
18076 Not documented
18077 Since
18079 2.5
18080 NumaCpuOptions (Object)
18082 Option "-numa cpu" overrides default cpu to node mapping. It accepts
18083 the same set of cpu properties as returned by query-hotplug‐
18084 gable-cpus[].props, where node-id could be used to override default
18085 node mapping.
18086 Members
18088 The members of CpuInstanceProperties
18089 Since
18091 2.10
18092 HmatLBMemoryHierarchy (Enum)
18094 The memory hierarchy in the System Locality Latency and Bandwidth In‐
18095 formation Structure of HMAT (Heterogeneous Memory Attribute Table)
18096 For more information about HmatLBMemoryHierarchy, see chapter 5.2.27.4:
18098 Table 5-146: Field "Flags" of ACPI 6.3 spec.
18099 Values
18101 memory the structure represents the memory performance
18102 first-level
18104 first level of memory side cache
18105 second-level
18107 second level of memory side cache
18108 third-level
18110 third level of memory side cache
18111 Since
18113 5.0
18114 HmatLBDataType (Enum)
18116 Data type in the System Locality Latency and Bandwidth Information
18117 Structure of HMAT (Heterogeneous Memory Attribute Table)
18118 For more information about HmatLBDataType, see chapter 5.2.27.4: Table
18120 5-146: Field "Data Type" of ACPI 6.3 spec.
18121 Values
18123 access-latency
18124 access latency (nanoseconds)
18125 read-latency
18127 read latency (nanoseconds)
18128 write-latency
18130 write latency (nanoseconds)
18131 access-bandwidth
18133 access bandwidth (Bytes per second)
18134 read-bandwidth
18136 read bandwidth (Bytes per second)
18137 write-bandwidth
18139 write bandwidth (Bytes per second)
18140 Since
18142 5.0
18143 NumaHmatLBOptions (Object)
18145 Set the system locality latency and bandwidth information between Ini‐
18146 tiator and Target proximity Domains.
18147 For more information about NumaHmatLBOptions, see chapter 5.2.27.4: Ta‐
18149 ble 5-146 of ACPI 6.3 spec.
18150 Members
18152 initiator: int
18153 the Initiator Proximity Domain.
18154 target: int
18156 the Target Proximity Domain.
18157 hierarchy: HmatLBMemoryHierarchy
18159 the Memory Hierarchy. Indicates the performance of memory or
18160 side cache.
18161 data-type: HmatLBDataType
18163 presents the type of data, access/read/write latency or hit la‐
18164 tency.
18165 latency: int (optional)
18167 the value of latency from initiator to target proximity domain,
18168 the latency unit is "ns(nanosecond)".
18169 bandwidth: int (optional)
18171 the value of bandwidth between initiator and target proximity
18172 domain, the bandwidth unit is "Bytes per second".
18173 Since
18175 5.0
18176 HmatCacheAssociativity (Enum)
18178 Cache associativity in the Memory Side Cache Information Structure of
18179 HMAT
18180 For more information of HmatCacheAssociativity, see chapter 5.2.27.5:
18182 Table 5-147 of ACPI 6.3 spec.
18183 Values
18185 none
18186 None (no memory side cache in this proximity domain,
18188 or cache associativity unknown)
18189 direct Direct Mapped
18191 complex
18193 Complex Cache Indexing (implementation specific)
18194 Since
18196 5.0
18197 HmatCacheWritePolicy (Enum)
18199 Cache write policy in the Memory Side Cache Information Structure of
18200 HMAT
18201 For more information of HmatCacheWritePolicy, see chapter 5.2.27.5: Ta‐
18203 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
18204 Values
18206 none None (no memory side cache in this proximity domain, or cache
18207 write policy unknown)
18208 write-back
18210 Write Back (WB)
18211 write-through
18213 Write Through (WT)
18214 Since
18216 5.0
18217 NumaHmatCacheOptions (Object)
18219 Set the memory side cache information for a given memory domain.
18220 For more information of NumaHmatCacheOptions, see chapter 5.2.27.5: Ta‐
18222 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
18223 Members
18225 node-id: int
18226 the memory proximity domain to which the memory belongs.
18227 size: int
18229 the size of memory side cache in bytes.
18230 level: int
18232 the cache level described in this structure.
18233 associativity: HmatCacheAssociativity
18235 the cache associativity, none/direct-mapped/complex(complex
18236 cache indexing).
18237 policy: HmatCacheWritePolicy
18239 the write policy, none/write-back/write-through.
18240 line: int
18242 the cache Line size in bytes.
18243 Since
18245 5.0
18246 memsave (Command)
18248 Save a portion of guest memory to a file.
18249 Arguments
18251 val: int
18252 the virtual address of the guest to start from
18253 size: int
18255 the size of memory region to save
18256 filename: string
18258 the file to save the memory to as binary data
18259 cpu-index: int (optional)
18261 the index of the virtual CPU to use for translating the virtual
18262 address (defaults to CPU 0)
18263 Returns
18265 Nothing on success
18266 Since
18268 0.14
18269 Notes
18271 Errors were not reliably returned until 1.1
18272 Example
18274 -> { "execute": "memsave",
18275 "arguments": { "val": 10,
18276 "size": 100,
18277 "filename": "/tmp/virtual-mem-dump" } }
18278 <- { "return": {} }
18279 pmemsave (Command)
18281 Save a portion of guest physical memory to a file.
18282 Arguments
18284 val: int
18285 the physical address of the guest to start from
18286 size: int
18288 the size of memory region to save
18289 filename: string
18291 the file to save the memory to as binary data
18292 Returns
18294 Nothing on success
18295 Since
18297 0.14
18298 Notes
18300 Errors were not reliably returned until 1.1
18301 Example
18303 -> { "execute": "pmemsave",
18304 "arguments": { "val": 10,
18305 "size": 100,
18306 "filename": "/tmp/physical-mem-dump" } }
18307 <- { "return": {} }
18308 Memdev (Object)
18310 Information about memory backend
18311 Members
18313 id: string (optional)
18314 backend's ID if backend has 'id' property (since 2.9)
18315 size: int
18317 memory backend size
18318 merge: boolean
18320 whether memory merge support is enabled
18321 dump: boolean
18323 whether memory backend's memory is included in a core dump
18324 prealloc: boolean
18326 whether memory was preallocated
18327 share: boolean
18329 whether memory is private to QEMU or shared (since 6.1)
18330 reserve: boolean (optional)
18332 whether swap space (or huge pages) was reserved if applicable.
18333 This corresponds to the user configuration and not the actual
18334 behavior implemented in the OS to perform the reservation. For
18335 example, Linux will never reserve swap space for shared file
18336 mappings. (since 6.1)
18337 host-nodes: array of int
18339 host nodes for its memory policy
18340 policy: HostMemPolicy
18342 memory policy of memory backend
18343 Since
18345 2.1
18346 query-memdev (Command)
18348 Returns information for all memory backends.
18349 Returns
18351 a list of Memdev.
18352 Since
18354 2.1
18355 Example
18357 -> { "execute": "query-memdev" }
18358 <- { "return": [
18359 {
18360 "id": "mem1",
18361 "size": 536870912,
18362 "merge": false,
18363 "dump": true,
18364 "prealloc": false,
18365 "share": false,
18366 "host-nodes": [0, 1],
18367 "policy": "bind"
18368 },
18369 {
18370 "size": 536870912,
18371 "merge": false,
18372 "dump": true,
18373 "prealloc": true,
18374 "share": false,
18375 "host-nodes": [2, 3],
18376 "policy": "preferred"
18377 }
18378 ]
18379 }
18380 CpuInstanceProperties (Object)
18382 List of properties to be used for hotplugging a CPU instance, it should
18383 be passed by management with device_add command when a CPU is being
18384 hotplugged.
18385 Members
18387 node-id: int (optional)
18388 NUMA node ID the CPU belongs to
18389 socket-id: int (optional)
18391 socket number within node/board the CPU belongs to
18392 die-id: int (optional)
18394 die number within socket the CPU belongs to (since 4.1)
18395 core-id: int (optional)
18397 core number within die the CPU belongs to
18398 thread-id: int (optional)
18400 thread number within core the CPU belongs to
18401 Note
18403 currently there are 5 properties that could be present but management
18404 should be prepared to pass through other properties with device_add
18405 command to allow for future interface extension. This also requires the
18406 filed names to be kept in sync with the properties passed to -de‐
18407 vice/device_add.
18408 Since
18410 2.7
18411 HotpluggableCPU (Object)
18413 Members
18414 type: string
18415 CPU object type for usage with device_add command
18416 props: CpuInstanceProperties
18418 list of properties to be used for hotplugging CPU
18419 vcpus-count: int
18421 number of logical VCPU threads HotpluggableCPU provides
18422 qom-path: string (optional)
18424 link to existing CPU object if CPU is present or omitted if CPU
18425 is not present.
18426 Since
18428 2.7
18429 query-hotpluggable-cpus (Command)
18431 TODO
18432 Better documentation; currently there is none.
18433 Returns
18435 a list of HotpluggableCPU objects.
18436 Since
18438 2.7
18439 Example
18441 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
18442 -> { "execute": "query-hotpluggable-cpus" }
18444 <- {"return": [
18445 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
18446 "vcpus-count": 1 },
18447 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
18448 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
18449 ]}'
18450 For pc machine type started with -smp 1,maxcpus=2:
18452 -> { "execute": "query-hotpluggable-cpus" }
18454 <- {"return": [
18455 {
18456 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
18457 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
18458 },
18459 {
18460 "qom-path": "/machine/unattached/device[0]",
18461 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
18462 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
18463 }
18464 ]}
18465 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
18467 (Since: 2.11):
18468 -> { "execute": "query-hotpluggable-cpus" }
18470 <- {"return": [
18471 {
18472 "type": "qemu-s390x-cpu", "vcpus-count": 1,
18473 "props": { "core-id": 1 }
18474 },
18475 {
18476 "qom-path": "/machine/unattached/device[0]",
18477 "type": "qemu-s390x-cpu", "vcpus-count": 1,
18478 "props": { "core-id": 0 }
18479 }
18480 ]}
18481 set-numa-node (Command)
18483 Runtime equivalent of '-numa' CLI option, available at preconfigure
18484 stage to configure numa mapping before initializing machine.
18485 Since 3.0
18487 Arguments
18489 The members of NumaOptions
18490 balloon (Command)
18492 Request the balloon driver to change its balloon size.
18493 Arguments
18495 value: int
18496 the target logical size of the VM in bytes. We can deduce the
18497 size of the balloon using this formula:
18498 logical_vm_size = vm_ram_size - balloon_size
18499 From it we have: balloon_size = vm_ram_size - value
18501 Returns
18503 • Nothing on success
18504 • If the balloon driver is enabled but not functional because the KVM
18506 kernel module cannot support it, KvmMissingCap
18507 • If no balloon device is present, DeviceNotActive
18509 Notes
18511 This command just issues a request to the guest. When it returns, the
18512 balloon size may not have changed. A guest can change the balloon size
18513 independent of this command.
18514 Since
18516 0.14
18517 Example
18519 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
18520 <- { "return": {} }
18521 With a 2.5GiB guest this command inflated the ballon to 3GiB.
18523 BalloonInfo (Object)
18525 Information about the guest balloon device.
18526 Members
18528 actual: int
18529 the logical size of the VM in bytes Formula used: logi‐
18530 cal_vm_size = vm_ram_size - balloon_size
18531 Since
18533 0.14
18534 query-balloon (Command)
18536 Return information about the balloon device.
18537 Returns
18539 • BalloonInfo on success
18540 • If the balloon driver is enabled but not functional because the KVM
18542 kernel module cannot support it, KvmMissingCap
18543 • If no balloon device is present, DeviceNotActive
18545 Since
18547 0.14
18548 Example
18550 -> { "execute": "query-balloon" }
18551 <- { "return": {
18552 "actual": 1073741824,
18553 }
18554 }
18555 BALLOON_CHANGE (Event)
18557 Emitted when the guest changes the actual BALLOON level. This value is
18558 equivalent to the actual field return by the 'query-balloon' command
18559 Arguments
18561 actual: int
18562 the logical size of the VM in bytes Formula used: logi‐
18563 cal_vm_size = vm_ram_size - balloon_size
18564 Note
18566 this event is rate-limited.
18567 Since
18569 1.2
18570 Example
18572 <- { "event": "BALLOON_CHANGE",
18573 "data": { "actual": 944766976 },
18574 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
18575 MemoryInfo (Object)
18577 Actual memory information in bytes.
18578 Members
18580 base-memory: int
18581 size of "base" memory specified with command line option -m.
18582 plugged-memory: int (optional)
18584 size of memory that can be hot-unplugged. This field is omitted
18585 if target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE
18586 not defined at build time).
18587 Since
18589 2.11
18590 query-memory-size-summary (Command)
18592 Return the amount of initially allocated and present hotpluggable (if
18593 enabled) memory in bytes.
18594 Example
18596 -> { "execute": "query-memory-size-summary" }
18597 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
18598 Since
18600 2.11
18601 PCDIMMDeviceInfo (Object)
18603 PCDIMMDevice state information
18604 Members
18606 id: string (optional)
18607 device's ID
18608 addr: int
18610 physical address, where device is mapped
18611 size: int
18613 size of memory that the device provides
18614 slot: int
18616 slot number at which device is plugged in
18617 node: int
18619 NUMA node number where device is plugged in
18620 memdev: string
18622 memory backend linked with device
18623 hotplugged: boolean
18625 true if device was hotplugged
18626 hotpluggable: boolean
18628 true if device if could be added/removed while machine is run‐
18629 ning
18630 Since
18632 2.1
18633 VirtioPMEMDeviceInfo (Object)
18635 VirtioPMEM state information
18636 Members
18638 id: string (optional)
18639 device's ID
18640 memaddr: int
18642 physical address in memory, where device is mapped
18643 size: int
18645 size of memory that the device provides
18646 memdev: string
18648 memory backend linked with device
18649 Since
18651 4.1
18652 VirtioMEMDeviceInfo (Object)
18654 VirtioMEMDevice state information
18655 Members
18657 id: string (optional)
18658 device's ID
18659 memaddr: int
18661 physical address in memory, where device is mapped
18662 requested-size: int
18664 the user requested size of the device
18665 size: int
18667 the (current) size of memory that the device provides
18668 max-size: int
18670 the maximum size of memory that the device can provide
18671 block-size: int
18673 the block size of memory that the device provides
18674 node: int
18676 NUMA node number where device is assigned to
18677 memdev: string
18679 memory backend linked with the region
18680 Since
18682 5.1
18683 SgxEPCDeviceInfo (Object)
18685 Sgx EPC state information
18686 Members
18688 id: string (optional)
18689 device's ID
18690 memaddr: int
18692 physical address in memory, where device is mapped
18693 size: int
18695 size of memory that the device provides
18696 memdev: string
18698 memory backend linked with device
18699 node: int
18701 the numa node (Since: 7.0)
18702 Since
18704 6.2
18705 MemoryDeviceInfoKind (Enum)
18707 Values
18708 dimm Not documented
18709 nvdimm Not documented
18711 virtio-pmem
18713 Not documented
18714 virtio-mem
18716 Not documented
18717 sgx-epc
18719 Not documented
18720 Since
18722 2.1
18723 PCDIMMDeviceInfoWrapper (Object)
18725 Members
18726 data: PCDIMMDeviceInfo
18727 Not documented
18728 Since
18730 2.1
18731 VirtioPMEMDeviceInfoWrapper (Object)
18733 Members
18734 data: VirtioPMEMDeviceInfo
18735 Not documented
18736 Since
18738 2.1
18739 VirtioMEMDeviceInfoWrapper (Object)
18741 Members
18742 data: VirtioMEMDeviceInfo
18743 Not documented
18744 Since
18746 2.1
18747 SgxEPCDeviceInfoWrapper (Object)
18749 Members
18750 data: SgxEPCDeviceInfo
18751 Not documented
18752 Since
18754 6.2
18755 MemoryDeviceInfo (Object)
18757 Union containing information about a memory device
18758 nvdimm is included since 2.12. virtio-pmem is included since 4.1. vir‐
18760 tio-mem is included since 5.1. sgx-epc is included since 6.2.
18761 Members
18763 type: MemoryDeviceInfoKind
18764 Not documented
18765 The members of PCDIMMDeviceInfoWrapper when type is "dimm"
18767 The members of PCDIMMDeviceInfoWrapper when type is "nvdimm"
18769 The members of VirtioPMEMDeviceInfoWrapper when type is "virtio-pmem"
18771 The members of VirtioMEMDeviceInfoWrapper when type is "virtio-mem"
18773 The members of SgxEPCDeviceInfoWrapper when type is "sgx-epc"
18775 Since
18777 2.1
18778 SgxEPC (Object)
18780 Sgx EPC cmdline information
18781 Members
18783 memdev: string
18784 memory backend linked with device
18785 node: int
18787 the numa node (Since: 7.0)
18788 Since
18790 6.2
18791 SgxEPCProperties (Object)
18793 SGX properties of machine types.
18794 Members
18796 sgx-epc: array of SgxEPC
18797 list of ids of memory-backend-epc objects.
18798 Since
18800 6.2
18801 query-memory-devices (Command)
18803 Lists available memory devices and their state
18804 Since
18806 2.1
18807 Example
18809 -> { "execute": "query-memory-devices" }
18810 <- { "return": [ { "data":
18811 { "addr": 5368709120,
18812 "hotpluggable": true,
18813 "hotplugged": true,
18814 "id": "d1",
18815 "memdev": "/objects/memX",
18816 "node": 0,
18817 "size": 1073741824,
18818 "slot": 0},
18819 "type": "dimm"
18820 } ] }
18821 MEMORY_DEVICE_SIZE_CHANGE (Event)
18823 Emitted when the size of a memory device changes. Only emitted for mem‐
18824 ory devices that can actually change the size (e.g., virtio-mem due to
18825 guest action).
18826 Arguments
18828 id: string (optional)
18829 device's ID
18830 size: int
18832 the new size of memory that the device provides
18833 qom-path: string
18835 path to the device object in the QOM tree (since 6.2)
18836 Note
18838 this event is rate-limited.
18839 Since
18841 5.1
18842 Example
18844 <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
18845 "data": { "id": "vm0", "size": 1073741824,
18846 "qom-path": "/machine/unattached/device[2]" },
18847 "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
18848 MEM_UNPLUG_ERROR (Event)
18850 Emitted when memory hot unplug error occurs.
18851 Arguments
18853 device: string
18854 device name
18855 msg: string
18857 Informative message
18858 Features
18860 deprecated
18861 This event is deprecated. Use DEVICE_UNPLUG_GUEST_ERROR instead.
18862 Since
18864 2.4
18865 Example
18867 <- { "event": "MEM_UNPLUG_ERROR"
18868 "data": { "device": "dimm1",
18869 "msg": "acpi: device unplug for unsupported device"
18870 },
18871 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
18872 SMPConfiguration (Object)
18874 Schema for CPU topology configuration. A missing value lets QEMU fig‐
18875 ure out a suitable value based on the ones that are provided.
18876 Members
18878 cpus: int (optional)
18879 number of virtual CPUs in the virtual machine
18880 sockets: int (optional)
18882 number of sockets in the CPU topology
18883 dies: int (optional)
18885 number of dies per socket in the CPU topology
18886 clusters: int (optional)
18888 number of clusters per die in the CPU topology (since 7.0)
18889 cores: int (optional)
18891 number of cores per cluster in the CPU topology
18892 threads: int (optional)
18894 number of threads per core in the CPU topology
18895 maxcpus: int (optional)
18897 maximum number of hotpluggable virtual CPUs in the virtual ma‐
18898 chine
18899 Since
18901 6.1
18902 x-query-irq (Command)
18904 Query interrupt statistics
18905 Features
18907 unstable
18908 This command is meant for debugging.
18909 Returns
18911 interrupt statistics
18912 Since
18914 6.2
18915 x-query-jit (Command)
18917 Query TCG compiler statistics
18918 Features
18920 unstable
18921 This command is meant for debugging.
18922 Returns
18924 TCG compiler statistics
18925 Since
18927 6.2
18928 If
18930 CONFIG_TCG
18931 x-query-numa (Command)
18933 Query NUMA topology information
18934 Features
18936 unstable
18937 This command is meant for debugging.
18938 Returns
18940 topology information
18941 Since
18943 6.2
18944 x-query-opcount (Command)
18946 Query TCG opcode counters
18947 Features
18949 unstable
18950 This command is meant for debugging.
18951 Returns
18953 TCG opcode counters
18954 Since
18956 6.2
18957 If
18959 CONFIG_TCG
18960 x-query-profile (Command)
18962 Query TCG profiling information
18963 Features
18965 unstable
18966 This command is meant for debugging.
18967 Returns
18969 profile information
18970 Since
18972 6.2
18973 If
18975 CONFIG_TCG
18976 x-query-ramblock (Command)
18978 Query system ramblock information
18979 Features
18981 unstable
18982 This command is meant for debugging.
18983 Returns
18985 system ramblock information
18986 Since
18988 6.2
18989 x-query-rdma (Command)
18991 Query RDMA state
18992 Features
18994 unstable
18995 This command is meant for debugging.
18996 Returns
18998 RDMA state
18999 Since
19001 6.2
19002 x-query-roms (Command)
19004 Query information on the registered ROMS
19005 Features
19007 unstable
19008 This command is meant for debugging.
19009 Returns
19011 registered ROMs
19012 Since
19014 6.2
19015 x-query-usb (Command)
19017 Query information on the USB devices
19018 Features
19020 unstable
19021 This command is meant for debugging.
19022 Returns
19024 USB device information
19025 Since
19027 6.2
19028 SmbiosEntryPointType (Enum)
19030 Values
19031 32 SMBIOS version 2.1 (32-bit) Entry Point
19032 64 SMBIOS version 3.0 (64-bit) Entry Point
19034 Since
19036 7.0
19037 CpuModelInfo (Object)
19039 Virtual CPU model.
19040 A CPU model consists of the name of a CPU definition, to which delta
19042 changes are applied (e.g. features added/removed). Most magic values
19043 that an architecture might require should be hidden behind the name.
19044 However, if required, architectures can expose relevant properties.
19045 Members
19047 name: string
19048 the name of the CPU definition the model is based on
19049 props: value (optional)
19051 a dictionary of QOM properties to be applied
19052 Since
19054 2.8
19055 CpuModelExpansionType (Enum)
19057 An enumeration of CPU model expansion types.
19058 Values
19060 static Expand to a static CPU model, a combination of a static base
19061 model name and property delta changes. As the static base model
19062 will never change, the expanded CPU model will be the same, in‐
19063 dependent of QEMU version, machine type, machine options, and
19064 accelerator options. Therefore, the resulting model can be used
19065 by tooling without having to specify a compatibility machine -
19066 e.g. when displaying the "host" model. The static CPU models are
19067 migration-safe.
19068 full Expand all properties. The produced model is not guaranteed to
19070 be migration-safe, but allows tooling to get an insight and work
19071 with model details.
19072 Note
19074 When a non-migration-safe CPU model is expanded in static mode, some
19075 features enabled by the CPU model may be omitted, because they can't be
19076 implemented by a static CPU model definition (e.g. cache info
19077 passthrough and PMU passthrough in x86). If you need an accurate repre‐
19078 sentation of the features enabled by a non-migration-safe CPU model,
19079 use full. If you need a static representation that will keep ABI com‐
19080 patibility even when changing QEMU version or machine-type, use static
19081 (but keep in mind that some features may be omitted).
19082 Since
19084 2.8
19085 CpuModelCompareResult (Enum)
19087 An enumeration of CPU model comparison results. The result is usually
19088 calculated using e.g. CPU features or CPU generations.
19089 Values
19091 incompatible
19092 If model A is incompatible to model B, model A is not guaranteed
19093 to run where model B runs and the other way around.
19094 identical
19096 If model A is identical to model B, model A is guaranteed to run
19097 where model B runs and the other way around.
19098 superset
19100 If model A is a superset of model B, model B is guaranteed to
19101 run where model A runs. There are no guarantees about the other
19102 way.
19103 subset If model A is a subset of model B, model A is guaranteed to run
19105 where model B runs. There are no guarantees about the other way.
19106 Since
19108 2.8
19109 CpuModelBaselineInfo (Object)
19111 The result of a CPU model baseline.
19112 Members
19114 model: CpuModelInfo
19115 the baselined CpuModelInfo.
19116 Since
19118 2.8
19119 If
19121 TARGET_S390X
19122 CpuModelCompareInfo (Object)
19124 The result of a CPU model comparison.
19125 Members
19127 result: CpuModelCompareResult
19128 The result of the compare operation.
19129 responsible-properties: array of string
19131 List of properties that led to the comparison result not being
19132 identical.
19133 responsible-properties is a list of QOM property names that led to both
19134 CPUs not being detected as identical. For identical models, this list
19135 is empty. If a QOM property is read-only, that means there's no known
19136 way to make the CPU models identical. If the special property name
19137 "type" is included, the models are by definition not identical and can‐
19138 not be made identical.
19139 Since
19141 2.8
19142 If
19144 TARGET_S390X
19145 query-cpu-model-comparison (Command)
19147 Compares two CPU models, returning how they compare in a specific con‐
19148 figuration. The results indicates how both models compare regarding
19149 runnability. This result can be used by tooling to make decisions if a
19150 certain CPU model will run in a certain configuration or if a compati‐
19151 ble CPU model has to be created by baselining.
19152 Usually, a CPU model is compared against the maximum possible CPU model
19154 of a certain configuration (e.g. the "host" model for KVM). If that CPU
19155 model is identical or a subset, it will run in that configuration.
19156 The result returned by this command may be affected by:
19158 • QEMU version: CPU models may look different depending on the QEMU
19160 version. (Except for CPU models reported as "static" in
19161 query-cpu-definitions.)
19162 • machine-type: CPU model may look different depending on the ma‐
19164 chine-type. (Except for CPU models reported as "static" in
19165 query-cpu-definitions.)
19166 • machine options (including accelerator): in some architectures, CPU
19168 models may look different depending on machine and accelerator op‐
19169 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
19170 nitions.)
19171 • "-cpu" arguments and global properties: arguments to the -cpu option
19173 and global properties may affect expansion of CPU models. Using
19174 query-cpu-model-expansion while using these is not advised.
19175 Some architectures may not support comparing CPU models. s390x supports
19177 comparing CPU models.
19178 Arguments
19180 modela: CpuModelInfo
19181 Not documented
19182 modelb: CpuModelInfo
19184 Not documented
19185 Returns
19187 a CpuModelBaselineInfo. Returns an error if comparing CPU models is not
19188 supported, if a model cannot be used, if a model contains an unknown
19189 cpu definition name, unknown properties or properties with wrong types.
19190 Note
19192 this command isn't specific to s390x, but is only implemented on this
19193 architecture currently.
19194 Since
19196 2.8
19197 If
19199 TARGET_S390X
19200 query-cpu-model-baseline (Command)
19202 Baseline two CPU models, creating a compatible third model. The created
19203 model will always be a static, migration-safe CPU model (see "static"
19204 CPU model expansion for details).
19205 This interface can be used by tooling to create a compatible CPU model
19207 out two CPU models. The created CPU model will be identical to or a
19208 subset of both CPU models when comparing them. Therefore, the created
19209 CPU model is guaranteed to run where the given CPU models run.
19210 The result returned by this command may be affected by:
19212 • QEMU version: CPU models may look different depending on the QEMU
19214 version. (Except for CPU models reported as "static" in
19215 query-cpu-definitions.)
19216 • machine-type: CPU model may look different depending on the ma‐
19218 chine-type. (Except for CPU models reported as "static" in
19219 query-cpu-definitions.)
19220 • machine options (including accelerator): in some architectures, CPU
19222 models may look different depending on machine and accelerator op‐
19223 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
19224 nitions.)
19225 • "-cpu" arguments and global properties: arguments to the -cpu option
19227 and global properties may affect expansion of CPU models. Using
19228 query-cpu-model-expansion while using these is not advised.
19229 Some architectures may not support baselining CPU models. s390x sup‐
19231 ports baselining CPU models.
19232 Arguments
19234 modela: CpuModelInfo
19235 Not documented
19236 modelb: CpuModelInfo
19238 Not documented
19239 Returns
19241 a CpuModelBaselineInfo. Returns an error if baselining CPU models is
19242 not supported, if a model cannot be used, if a model contains an un‐
19243 known cpu definition name, unknown properties or properties with wrong
19244 types.
19245 Note
19247 this command isn't specific to s390x, but is only implemented on this
19248 architecture currently.
19249 Since
19251 2.8
19252 If
19254 TARGET_S390X
19255 CpuModelExpansionInfo (Object)
19257 The result of a cpu model expansion.
19258 Members
19260 model: CpuModelInfo
19261 the expanded CpuModelInfo.
19262 Since
19264 2.8
19265 If
19267 TARGET_S390X or TARGET_I386 or TARGET_ARM
19268 query-cpu-model-expansion (Command)
19270 Expands a given CPU model (or a combination of CPU model + additional
19271 options) to different granularities, allowing tooling to get an under‐
19272 standing what a specific CPU model looks like in QEMU under a certain
19273 configuration.
19274 This interface can be used to query the "host" CPU model.
19276 The data returned by this command may be affected by:
19278 • QEMU version: CPU models may look different depending on the QEMU
19280 version. (Except for CPU models reported as "static" in
19281 query-cpu-definitions.)
19282 • machine-type: CPU model may look different depending on the ma‐
19284 chine-type. (Except for CPU models reported as "static" in
19285 query-cpu-definitions.)
19286 • machine options (including accelerator): in some architectures, CPU
19288 models may look different depending on machine and accelerator op‐
19289 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
19290 nitions.)
19291 • "-cpu" arguments and global properties: arguments to the -cpu option
19293 and global properties may affect expansion of CPU models. Using
19294 query-cpu-model-expansion while using these is not advised.
19295 Some architectures may not support all expansion types. s390x supports
19297 "full" and "static". Arm only supports "full".
19298 Arguments
19300 type: CpuModelExpansionType
19301 Not documented
19302 model: CpuModelInfo
19304 Not documented
19305 Returns
19307 a CpuModelExpansionInfo. Returns an error if expanding CPU models is
19308 not supported, if the model cannot be expanded, if the model contains
19309 an unknown CPU definition name, unknown properties or properties with a
19310 wrong type. Also returns an error if an expansion type is not sup‐
19311 ported.
19312 Since
19314 2.8
19315 If
19317 TARGET_S390X or TARGET_I386 or TARGET_ARM
19318 CpuDefinitionInfo (Object)
19320 Virtual CPU definition.
19321 Members
19323 name: string
19324 the name of the CPU definition
19325 migration-safe: boolean (optional)
19327 whether a CPU definition can be safely used for migration in
19328 combination with a QEMU compatibility machine when migrating be‐
19329 tween different QEMU versions and between hosts with different
19330 sets of (hardware or software) capabilities. If not provided,
19331 information is not available and callers should not assume the
19332 CPU definition to be migration-safe. (since 2.8)
19333 static: boolean
19335 whether a CPU definition is static and will not change depending
19336 on QEMU version, machine type, machine options and accelerator
19337 options. A static model is always migration-safe. (since 2.8)
19338 unavailable-features: array of string (optional)
19340 List of properties that prevent the CPU model from running in
19341 the current host. (since 2.8)
19342 typename: string
19344 Type name that can be used as argument to device-list-proper‐
19345 ties, to introspect properties configurable using -cpu or
19346 -global. (since 2.9)
19347 alias-of: string (optional)
19349 Name of CPU model this model is an alias for. The target of the
19350 CPU model alias may change depending on the machine type. Man‐
19351 agement software is supposed to translate CPU model aliases in
19352 the VM configuration, because aliases may stop being migra‐
19353 tion-safe in the future (since 4.1)
19354 deprecated: boolean
19356 If true, this CPU model is deprecated and may be removed in in
19357 some future version of QEMU according to the QEMU deprecation
19358 policy. (since 5.2)
19359 unavailable-features is a list of QOM property names that represent CPU
19360 model attributes that prevent the CPU from running. If the QOM prop‐
19361 erty is read-only, that means there's no known way to make the CPU
19362 model run in the current host. Implementations that choose not to pro‐
19363 vide specific information return the property name "type". If the
19364 property is read-write, it means that it MAY be possible to run the CPU
19365 model in the current host if that property is changed. Management soft‐
19366 ware can use it as hints to suggest or choose an alternative for the
19367 user, or just to generate meaningful error messages explaining why the
19368 CPU model can't be used. If unavailable-features is an empty list, the
19369 CPU model is runnable using the current host and machine-type. If un‐
19370 available-features is not present, runnability information for the CPU
19371 is not available.
19372 Since
19374 1.2
19375 If
19377 TARGET_PPC or TARGET_ARM or TARGET_I386 or TARGET_S390X or TARGET_MIPS
19378 query-cpu-definitions (Command)
19380 Return a list of supported virtual CPU definitions
19381 Returns
19383 a list of CpuDefInfo
19384 Since
19386 1.2
19387 If
19389 TARGET_PPC or TARGET_ARM or TARGET_I386 or TARGET_S390X or TARGET_MIPS
19390
19392 ReplayMode (Enum)
19393 Mode of the replay subsystem.
19394 Values
19396 none normal execution mode. Replay or record are not enabled.
19397 record record mode. All non-deterministic data is written into the re‐
19399 play log.
19400 play replay mode. Non-deterministic data required for system execu‐
19402 tion is read from the log.
19403 Since
19405 2.5
19406 ReplayInfo (Object)
19408 Record/replay information.
19409 Members
19411 mode: ReplayMode
19412 current mode.
19413 filename: string (optional)
19415 name of the record/replay log file. It is present only in
19416 record or replay modes, when the log is recorded or replayed.
19417 icount: int
19419 current number of executed instructions.
19420 Since
19422 5.2
19423 query-replay (Command)
19425 Retrieve the record/replay information. It includes current instruc‐
19426 tion count which may be used for replay-break and replay-seek commands.
19427 Returns
19429 record/replay information.
19430 Since
19432 5.2
19433 Example
19435 -> { "execute": "query-replay" }
19436 <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
19437 replay-break (Command)
19439 Set replay breakpoint at instruction count icount. Execution stops
19440 when the specified instruction is reached. There can be at most one
19441 breakpoint. When breakpoint is set, any prior one is removed. The
19442 breakpoint may be set only in replay mode and only "in the future",
19443 i.e. at instruction counts greater than the current one. The current
19444 instruction count can be observed with query-replay.
19445 Arguments
19447 icount: int
19448 instruction count to stop at
19449 Since
19451 5.2
19452 Example
19454 -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
19455 replay-delete-break (Command)
19457 Remove replay breakpoint which was set with replay-break. The command
19458 is ignored when there are no replay breakpoints.
19459 Since
19461 5.2
19462 Example
19464 -> { "execute": "replay-delete-break" }
19465 replay-seek (Command)
19467 Automatically proceed to the instruction count icount, when replaying
19468 the execution. The command automatically loads nearest snapshot and re‐
19469 plays the execution to find the desired instruction. When there is no
19470 preceding snapshot or the execution is not replayed, then the command
19471 fails. icount for the reference may be obtained with query-replay com‐
19472 mand.
19473 Arguments
19475 icount: int
19476 target instruction count
19477 Since
19479 5.2
19480 Example
19482 -> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
19483
19485 YankInstanceType (Enum)
19486 An enumeration of yank instance types. See YankInstance for more infor‐
19487 mation.
19488 Values
19490 block-node
19491 Not documented
19492 chardev
19494 Not documented
19495 migration
19497 Not documented
19498 Since
19500 6.0
19501 YankInstanceBlockNode (Object)
19503 Specifies which block graph node to yank. See YankInstance for more in‐
19504 formation.
19505 Members
19507 node-name: string
19508 the name of the block graph node
19509 Since
19511 6.0
19512 YankInstanceChardev (Object)
19514 Specifies which character device to yank. See YankInstance for more in‐
19515 formation.
19516 Members
19518 id: string
19519 the chardev's ID
19520 Since
19522 6.0
19523 YankInstance (Object)
19525 A yank instance can be yanked with the yank qmp command to recover from
19526 a hanging QEMU.
19527 Currently implemented yank instances:
19529 • nbd block device: Yanking it will shut down the connection to
19531 the nbd server without attempting to reconnect.
19532 • socket chardev: Yanking it will shut down the connected
19534 socket.
19535 • migration: Yanking it will shut down all migration connec‐
19537 tions. Unlike migrate_cancel, it will not notify the migration
19538 process, so migration will go into failed state, instead of
19539 cancelled state. yank should be used to recover from hangs.
19540 Members
19542 type: YankInstanceType
19543 Not documented
19544 The members of YankInstanceBlockNode when type is "block-node"
19546 The members of YankInstanceChardev when type is "chardev"
19548 Since
19550 6.0
19551 yank (Command)
19553 Try to recover from hanging QEMU by yanking the specified instances.
19554 See YankInstance for more information.
19555 Takes a list of YankInstance as argument.
19557 Arguments
19559 instances: array of YankInstance
19560 Not documented
19561 Returns
19563 • Nothing on success
19564 • DeviceNotFound error, if any of the YankInstances doesn't exist
19566 Example
19568 -> { "execute": "yank",
19569 "arguments": {
19570 "instances": [
19571 { "type": "block-node",
19572 "node-name": "nbd0" }
19573 ] } }
19574 <- { "return": {} }
19575 Since
19577 6.0
19578 query-yank (Command)
19580 Query yank instances. See YankInstance for more information.
19581 Returns
19583 list of YankInstance
19584 Example
19586 -> { "execute": "query-yank" }
19587 <- { "return": [
19588 { "type": "block-node",
19589 "node-name": "nbd0" }
19590 ] }
19591 Since
19593 6.0
19594
19596 add_client (Command)
19597 Allow client connections for VNC, Spice and socket based character de‐
19598 vices to be passed in to QEMU via SCM_RIGHTS.
19599 Arguments
19601 protocol: string
19602 protocol name. Valid names are "vnc", "spice", "dbus-display" or
19603 the name of a character device (eg. from -chardev id=XXXX)
19604 fdname: string
19606 file descriptor name previously passed via 'getfd' command
19607 skipauth: boolean (optional)
19609 whether to skip authentication. Only applies to "vnc" and
19610 "spice" protocols
19611 tls: boolean (optional)
19613 whether to perform TLS. Only applies to the "spice" protocol
19614 Returns
19616 nothing on success.
19617 Since
19619 0.14
19620 Example
19622 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
19623 "fdname": "myclient" } }
19624 <- { "return": {} }
19625 NameInfo (Object)
19627 Guest name information.
19628 Members
19630 name: string (optional)
19631 The name of the guest
19632 Since
19634 0.14
19635 query-name (Command)
19637 Return the name information of a guest.
19638 Returns
19640 NameInfo of the guest
19641 Since
19643 0.14
19644 Example
19646 -> { "execute": "query-name" }
19647 <- { "return": { "name": "qemu-name" } }
19648 IOThreadInfo (Object)
19650 Information about an iothread
19651 Members
19653 id: string
19654 the identifier of the iothread
19655 thread-id: int
19657 ID of the underlying host thread
19658 poll-max-ns: int
19660 maximum polling time in ns, 0 means polling is disabled (since
19661 2.9)
19662 poll-grow: int
19664 how many ns will be added to polling time, 0 means that it's not
19665 configured (since 2.9)
19666 poll-shrink: int
19668 how many ns will be removed from polling time, 0 means that it's
19669 not configured (since 2.9)
19670 aio-max-batch: int
19672 maximum number of requests in a batch for the AIO engine, 0
19673 means that the engine will use its default (since 6.1)
19674 Since
19676 2.0
19677 query-iothreads (Command)
19679 Returns a list of information about each iothread.
19680 Note
19682 this list excludes the QEMU main loop thread, which is not declared us‐
19683 ing the -object iothread command-line option. It is always the main
19684 thread of the process.
19685 Returns
19687 a list of IOThreadInfo for each iothread
19688 Since
19690 2.0
19691 Example
19693 -> { "execute": "query-iothreads" }
19694 <- { "return": [
19695 {
19696 "id":"iothread0",
19697 "thread-id":3134
19698 },
19699 {
19700 "id":"iothread1",
19701 "thread-id":3135
19702 }
19703 ]
19704 }
19705 stop (Command)
19707 Stop all guest VCPU execution.
19708 Since
19710 0.14
19711 Notes
19713 This function will succeed even if the guest is already in the stopped
19714 state. In "inmigrate" state, it will ensure that the guest remains
19715 paused once migration finishes, as if the -S option was passed on the
19716 command line.
19717 Example
19719 -> { "execute": "stop" }
19720 <- { "return": {} }
19721 cont (Command)
19723 Resume guest VCPU execution.
19724 Since
19726 0.14
19727 Returns
19729 If successful, nothing
19730 Notes
19732 This command will succeed if the guest is currently running. It will
19733 also succeed if the guest is in the "inmigrate" state; in this case,
19734 the effect of the command is to make sure the guest starts once migra‐
19735 tion finishes, removing the effect of the -S command line option if it
19736 was passed.
19737 Example
19739 -> { "execute": "cont" }
19740 <- { "return": {} }
19741 x-exit-preconfig (Command)
19743 Exit from "preconfig" state
19744 This command makes QEMU exit the preconfig state and proceed with VM
19746 initialization using configuration data provided on the command line
19747 and via the QMP monitor during the preconfig state. The command is only
19748 available during the preconfig state (i.e. when the --preconfig command
19749 line option was in use).
19750 Features
19752 unstable
19753 This command is experimental.
19754 Since 3.0
19755 Returns
19757 nothing
19758 Example
19760 -> { "execute": "x-exit-preconfig" }
19761 <- { "return": {} }
19762 human-monitor-command (Command)
19764 Execute a command on the human monitor and return the output.
19765 Arguments
19767 command-line: string
19768 the command to execute in the human monitor
19769 cpu-index: int (optional)
19771 The CPU to use for commands that require an implicit CPU
19772 Features
19774 savevm-monitor-nodes
19775 If present, HMP command savevm only snapshots monitor-owned
19776 nodes if they have no parents. This allows the use of 'savevm'
19777 with -blockdev. (since 4.2)
19778 Returns
19780 the output of the command as a string
19781 Since
19783 0.14
19784 Notes
19786 This command only exists as a stop-gap. Its use is highly discouraged.
19787 The semantics of this command are not guaranteed: this means that com‐
19788 mand names, arguments and responses can change or be removed at ANY
19789 time. Applications that rely on long term stability guarantees should
19790 NOT use this command.
19791 Known limitations:
19793 • This command is stateless, this means that commands that depend on
19795 state information (such as getfd) might not work
19796 • Commands that prompt the user for data don't currently work
19798 Example
19800 -> { "execute": "human-monitor-command",
19801 "arguments": { "command-line": "info kvm" } }
19802 <- { "return": "kvm support: enabled\r\n" }
19803 getfd (Command)
19805 Receive a file descriptor via SCM rights and assign it a name
19806 Arguments
19808 fdname: string
19809 file descriptor name
19810 Returns
19812 Nothing on success
19813 Since
19815 0.14
19816 Notes
19818 If fdname already exists, the file descriptor assigned to it will be
19819 closed and replaced by the received file descriptor.
19820 The 'closefd' command can be used to explicitly close the file descrip‐
19822 tor when it is no longer needed.
19823 Example
19825 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
19826 <- { "return": {} }
19827 closefd (Command)
19829 Close a file descriptor previously passed via SCM rights
19830 Arguments
19832 fdname: string
19833 file descriptor name
19834 Returns
19836 Nothing on success
19837 Since
19839 0.14
19840 Example
19842 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
19843 <- { "return": {} }
19844 AddfdInfo (Object)
19846 Information about a file descriptor that was added to an fd set.
19847 Members
19849 fdset-id: int
19850 The ID of the fd set that fd was added to.
19851 fd: int
19853 The file descriptor that was received via SCM rights and added
19854 to the fd set.
19855 Since
19857 1.2
19858 add-fd (Command)
19860 Add a file descriptor, that was passed via SCM rights, to an fd set.
19861 Arguments
19863 fdset-id: int (optional)
19864 The ID of the fd set to add the file descriptor to.
19865 opaque: string (optional)
19867 A free-form string that can be used to describe the fd.
19868 Returns
19870 • AddfdInfo on success
19871 • If file descriptor was not received, FdNotSupplied
19873 • If fdset-id is a negative value, InvalidParameterValue
19875 Notes
19877 The list of fd sets is shared by all monitor connections.
19878 If fdset-id is not specified, a new fd set will be created.
19880 Since
19882 1.2
19883 Example
19885 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
19886 <- { "return": { "fdset-id": 1, "fd": 3 } }
19887 remove-fd (Command)
19889 Remove a file descriptor from an fd set.
19890 Arguments
19892 fdset-id: int
19893 The ID of the fd set that the file descriptor belongs to.
19894 fd: int (optional)
19896 The file descriptor that is to be removed.
19897 Returns
19899 • Nothing on success
19900 • If fdset-id or fd is not found, FdNotFound
19902 Since
19904 1.2
19905 Notes
19907 The list of fd sets is shared by all monitor connections.
19908 If fd is not specified, all file descriptors in fdset-id will be re‐
19910 moved.
19911 Example
19913 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
19914 <- { "return": {} }
19915 FdsetFdInfo (Object)
19917 Information about a file descriptor that belongs to an fd set.
19918 Members
19920 fd: int
19921 The file descriptor value.
19922 opaque: string (optional)
19924 A free-form string that can be used to describe the fd.
19925 Since
19927 1.2
19928 FdsetInfo (Object)
19930 Information about an fd set.
19931 Members
19933 fdset-id: int
19934 The ID of the fd set.
19935 fds: array of FdsetFdInfo
19937 A list of file descriptors that belong to this fd set.
19938 Since
19940 1.2
19941 query-fdsets (Command)
19943 Return information describing all fd sets.
19944 Returns
19946 A list of FdsetInfo
19947 Since
19949 1.2
19950 Note
19952 The list of fd sets is shared by all monitor connections.
19953 Example
19955 -> { "execute": "query-fdsets" }
19956 <- { "return": [
19957 {
19958 "fds": [
19959 {
19960 "fd": 30,
19961 "opaque": "rdonly:/path/to/file"
19962 },
19963 {
19964 "fd": 24,
19965 "opaque": "rdwr:/path/to/file"
19966 }
19967 ],
19968 "fdset-id": 1
19969 },
19970 {
19971 "fds": [
19972 {
19973 "fd": 28
19974 },
19975 {
19976 "fd": 29
19977 }
19978 ],
19979 "fdset-id": 0
19980 }
19981 ]
19982 }
19983 CommandLineParameterType (Enum)
19985 Possible types for an option parameter.
19986 Values
19988 string accepts a character string
19989 boolean
19991 accepts "on" or "off"
19992 number accepts a number
19994 size accepts a number followed by an optional suffix (K)ilo, (M)ega,
19996 (G)iga, (T)era
19997 Since
19999 1.5
20000 CommandLineParameterInfo (Object)
20002 Details about a single parameter of a command line option.
20003 Members
20005 name: string
20006 parameter name
20007 type: CommandLineParameterType
20009 parameter CommandLineParameterType
20010 help: string (optional)
20012 human readable text string, not suitable for parsing.
20013 default: string (optional)
20015 default value string (since 2.1)
20016 Since
20018 1.5
20019 CommandLineOptionInfo (Object)
20021 Details about a command line option, including its list of parameter
20022 details
20023 Members
20025 option: string
20026 option name
20027 parameters: array of CommandLineParameterInfo
20029 an array of CommandLineParameterInfo
20030 Since
20032 1.5
20033 query-command-line-options (Command)
20035 Query command line option schema.
20036 Arguments
20038 option: string (optional)
20039 option name
20040 Returns
20042 list of CommandLineOptionInfo for all options (or for the given op‐
20043 tion). Returns an error if the given option doesn't exist.
20044 Since
20046 1.5
20047 Example
20049 -> { "execute": "query-command-line-options",
20050 "arguments": { "option": "option-rom" } }
20051 <- { "return": [
20052 {
20053 "parameters": [
20054 {
20055 "name": "romfile",
20056 "type": "string"
20057 },
20058 {
20059 "name": "bootindex",
20060 "type": "number"
20061 }
20062 ],
20063 "option": "option-rom"
20064 }
20065 ]
20066 }
20067 RTC_CHANGE (Event)
20069 Emitted when the guest changes the RTC time.
20070 Arguments
20072 offset: int
20073 offset in seconds between base RTC clock (as specified by -rtc
20074 base), and new RTC clock value
20075 qom-path: string
20077 path to the RTC object in the QOM tree
20078 Note
20080 This event is rate-limited. It is not guaranteed that the RTC in the
20081 system implements this event, or even that the system has an RTC at
20082 all.
20083 Since
20085 0.13
20086 Example
20088 <- { "event": "RTC_CHANGE",
20089 "data": { "offset": 78 },
20090 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
20091 rtc-reset-reinjection (Command)
20093 This command will reset the RTC interrupt reinjection backlog. Can be
20094 used if another mechanism to synchronize guest time is in effect, for
20095 example QEMU guest agent's guest-set-time command.
20096 Since
20098 2.1
20099 Example
20101 -> { "execute": "rtc-reset-reinjection" }
20102 <- { "return": {} }
20103 If
20105 TARGET_I386
20106 SevState (Enum)
20108 An enumeration of SEV state information used during query-sev.
20109 Values
20111 uninit The guest is uninitialized.
20112 launch-update
20114 The guest is currently being launched; plaintext data and regis‐
20115 ter state is being imported.
20116 launch-secret
20118 The guest is currently being launched; ciphertext data is being
20119 imported.
20120 running
20122 The guest is fully launched or migrated in.
20123 send-update
20125 The guest is currently being migrated out to another machine.
20126 receive-update
20128 The guest is currently being migrated from another machine.
20129 Since
20131 2.12
20132 If
20134 TARGET_I386
20135 SevInfo (Object)
20137 Information about Secure Encrypted Virtualization (SEV) support
20138 Members
20140 enabled: boolean
20141 true if SEV is active
20142 api-major: int
20144 SEV API major version
20145 api-minor: int
20147 SEV API minor version
20148 build-id: int
20150 SEV FW build id
20151 policy: int
20153 SEV policy value
20154 state: SevState
20156 SEV guest state
20157 handle: int
20159 SEV firmware handle
20160 Since
20162 2.12
20163 If
20165 TARGET_I386
20166 query-sev (Command)
20168 Returns information about SEV
20169 Returns
20171 SevInfo
20172 Since
20174 2.12
20175 Example
20177 -> { "execute": "query-sev" }
20178 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
20179 "build-id" : 0, "policy" : 0, "state" : "running",
20180 "handle" : 1 } }
20181 If
20183 TARGET_I386
20184 SevLaunchMeasureInfo (Object)
20186 SEV Guest Launch measurement information
20187 Members
20189 data: string
20190 the measurement value encoded in base64
20191 Since
20193 2.12
20194 If
20196 TARGET_I386
20197 query-sev-launch-measure (Command)
20199 Query the SEV guest launch information.
20200 Returns
20202 The SevLaunchMeasureInfo for the guest
20203 Since
20205 2.12
20206 Example
20208 -> { "execute": "query-sev-launch-measure" }
20209 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
20210 If
20212 TARGET_I386
20213 SevCapability (Object)
20215 The struct describes capability for a Secure Encrypted Virtualization
20216 feature.
20217 Members
20219 pdh: string
20220 Platform Diffie-Hellman key (base64 encoded)
20221 cert-chain: string
20223 PDH certificate chain (base64 encoded)
20224 cbitpos: int
20226 C-bit location in page table entry
20227 reduced-phys-bits: int
20229 Number of physical Address bit reduction when SEV is enabled
20230 Since
20232 2.12
20233 If
20235 TARGET_I386
20236 query-sev-capabilities (Command)
20238 This command is used to get the SEV capabilities, and is supported on
20239 AMD X86 platforms only.
20240 Returns
20242 SevCapability objects.
20243 Since
20245 2.12
20246 Example
20248 -> { "execute": "query-sev-capabilities" }
20249 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
20250 "cbitpos": 47, "reduced-phys-bits": 5}}
20251 If
20253 TARGET_I386
20254 sev-inject-launch-secret (Command)
20256 This command injects a secret blob into memory of SEV guest.
20257 Arguments
20259 packet-header: string
20260 the launch secret packet header encoded in base64
20261 secret: string
20263 the launch secret data to be injected encoded in base64
20264 gpa: int (optional)
20266 the guest physical address where secret will be injected.
20267 Since
20269 6.0
20270 If
20272 TARGET_I386
20273 SevAttestationReport (Object)
20275 The struct describes attestation report for a Secure Encrypted Virtual‐
20276 ization feature.
20277 Members
20279 data: string
20280 guest attestation report (base64 encoded)
20281 Since
20283 6.1
20284 If
20286 TARGET_I386
20287 query-sev-attestation-report (Command)
20289 This command is used to get the SEV attestation report, and is sup‐
20290 ported on AMD X86 platforms only.
20291 Arguments
20293 mnonce: string
20294 a random 16 bytes value encoded in base64 (it will be included
20295 in report)
20296 Returns
20298 SevAttestationReport objects.
20299 Since
20301 6.1
20302 Example
20304 -> { "execute" : "query-sev-attestation-report",
20305 "arguments": { "mnonce": "aaaaaaa" } }
20306 <- { "return" : { "data": "aaaaaaaabbbddddd"} }
20307 If
20309 TARGET_I386
20310 dump-skeys (Command)
20312 Dump guest's storage keys
20313 Arguments
20315 filename: string
20316 the path to the file to dump to
20317 This command is only supported on s390 architecture.
20318 Since
20320 2.5
20321 Example
20323 -> { "execute": "dump-skeys",
20324 "arguments": { "filename": "/tmp/skeys" } }
20325 <- { "return": {} }
20326 If
20328 TARGET_S390X
20329 GICCapability (Object)
20331 The struct describes capability for a specific GIC (Generic Interrupt
20332 Controller) version. These bits are not only decided by QEMU/KVM soft‐
20333 ware version, but also decided by the hardware that the program is run‐
20334 ning upon.
20335 Members
20337 version: int
20338 version of GIC to be described. Currently, only 2 and 3 are sup‐
20339 ported.
20340 emulated: boolean
20342 whether current QEMU/hardware supports emulated GIC device in
20343 user space.
20344 kernel: boolean
20346 whether current QEMU/hardware supports hardware accelerated GIC
20347 device in kernel.
20348 Since
20350 2.6
20351 If
20353 TARGET_ARM
20354 query-gic-capabilities (Command)
20356 This command is ARM-only. It will return a list of GICCapability ob‐
20357 jects that describe its capability bits.
20358 Returns
20360 a list of GICCapability objects.
20361 Since
20363 2.6
20364 Example
20366 -> { "execute": "query-gic-capabilities" }
20367 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
20368 { "version": 3, "emulated": false, "kernel": true } ] }
20369 If
20371 TARGET_ARM
20372 SGXEPCSection (Object)
20374 Information about intel SGX EPC section info
20375 Members
20377 node: int
20378 the numa node
20379 size: int
20381 the size of EPC section
20382 Since
20384 7.0
20385 SGXInfo (Object)
20387 Information about intel Safe Guard eXtension (SGX) support
20388 Members
20390 sgx: boolean
20391 true if SGX is supported
20392 sgx1: boolean
20394 true if SGX1 is supported
20395 sgx2: boolean
20397 true if SGX2 is supported
20398 flc: boolean
20400 true if FLC is supported
20401 section-size: int
20403 The EPC section size for guest Redundant with sections. Just
20404 for backward compatibility.
20405 sections: array of SGXEPCSection
20407 The EPC sections info for guest (Since: 7.0)
20408 Features
20410 deprecated
20411 Member section-size is deprecated. Use sections instead.
20412 Since
20414 6.2
20415 If
20417 TARGET_I386
20418 query-sgx (Command)
20420 Returns information about SGX
20421 Returns
20423 SGXInfo
20424 Since
20426 6.2
20427 Example
20429 -> { "execute": "query-sgx" }
20430 <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
20431 "flc": true, "section-size" : 96468992,
20432 "sections": [{"node": 0, "size": 67108864},
20433 {"node": 1, "size": 29360128}]} }
20434 If
20436 TARGET_I386
20437 query-sgx-capabilities (Command)
20439 Returns information from host SGX capabilities
20440 Returns
20442 SGXInfo
20443 Since
20445 6.2
20446 Example
20448 -> { "execute": "query-sgx-capabilities" }
20449 <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
20450 "flc": true, "section-size" : 96468992,
20451 "section" : [{"node": 0, "size": 67108864},
20452 {"node": 1, "size": 29360128}]} }
20453 If
20455 TARGET_I386
20456
20458 AudiodevPerDirectionOptions (Object)
20459 General audio backend options that are used for both playback and
20460 recording.
20461 Members
20463 mixing-engine: boolean (optional)
20464 use QEMU's mixing engine to mix all streams inside QEMU and con‐
20465 vert audio formats when not supported by the backend. When set
20466 to off, fixed-settings must be also off (default on, since 4.2)
20467 fixed-settings: boolean (optional)
20469 use fixed settings for host input/output. When off, frequency,
20470 channels and format must not be specified (default true)
20471 frequency: int (optional)
20473 frequency to use when using fixed settings (default 44100)
20474 channels: int (optional)
20476 number of channels when using fixed settings (default 2)
20477 voices: int (optional)
20479 number of voices to use (default 1)
20480 format: AudioFormat (optional)
20482 sample format to use when using fixed settings (default s16)
20483 buffer-length: int (optional)
20485 the buffer length in microseconds
20486 Since
20488 4.0
20489 AudiodevGenericOptions (Object)
20491 Generic driver-specific options.
20492 Members
20494 in: AudiodevPerDirectionOptions (optional)
20495 options of the capture stream
20496 out: AudiodevPerDirectionOptions (optional)
20498 options of the playback stream
20499 Since
20501 4.0
20502 AudiodevAlsaPerDirectionOptions (Object)
20504 Options of the ALSA backend that are used for both playback and record‐
20505 ing.
20506 Members
20508 dev: string (optional)
20509 the name of the ALSA device to use (default 'default')
20510 period-length: int (optional)
20512 the period length in microseconds
20513 try-poll: boolean (optional)
20515 attempt to use poll mode, falling back to non-polling access on
20516 failure (default true)
20517 The members of AudiodevPerDirectionOptions
20519 Since
20521 4.0
20522 AudiodevAlsaOptions (Object)
20524 Options of the ALSA audio backend.
20525 Members
20527 in: AudiodevAlsaPerDirectionOptions (optional)
20528 options of the capture stream
20529 out: AudiodevAlsaPerDirectionOptions (optional)
20531 options of the playback stream
20532 threshold: int (optional)
20534 set the threshold (in microseconds) when playback starts
20535 Since
20537 4.0
20538 AudiodevCoreaudioPerDirectionOptions (Object)
20540 Options of the Core Audio backend that are used for both playback and
20541 recording.
20542 Members
20544 buffer-count: int (optional)
20545 number of buffers
20546 The members of AudiodevPerDirectionOptions
20548 Since
20550 4.0
20551 AudiodevCoreaudioOptions (Object)
20553 Options of the coreaudio audio backend.
20554 Members
20556 in: AudiodevCoreaudioPerDirectionOptions (optional)
20557 options of the capture stream
20558 out: AudiodevCoreaudioPerDirectionOptions (optional)
20560 options of the playback stream
20561 Since
20563 4.0
20564 AudiodevDsoundOptions (Object)
20566 Options of the DirectSound audio backend.
20567 Members
20569 in: AudiodevPerDirectionOptions (optional)
20570 options of the capture stream
20571 out: AudiodevPerDirectionOptions (optional)
20573 options of the playback stream
20574 latency: int (optional)
20576 add extra latency to playback in microseconds (default 10000)
20577 Since
20579 4.0
20580 AudiodevJackPerDirectionOptions (Object)
20582 Options of the JACK backend that are used for both playback and record‐
20583 ing.
20584 Members
20586 server-name: string (optional)
20587 select from among several possible concurrent server instances
20588 (default: environment variable $JACK_DEFAULT_SERVER if set, else
20589 "default")
20590 client-name: string (optional)
20592 the client name to use. The server will modify this name to cre‐
20593 ate a unique variant, if needed unless exact-name is true (de‐
20594 fault: the guest's name)
20595 connect-ports: string (optional)
20597 if set, a regular expression of JACK client port name(s) to mon‐
20598 itor for and automatically connect to
20599 start-server: boolean (optional)
20601 start a jack server process if one is not already present (de‐
20602 fault: false)
20603 exact-name: boolean (optional)
20605 use the exact name requested otherwise JACK automatically gener‐
20606 ates a unique one, if needed (default: false)
20607 The members of AudiodevPerDirectionOptions
20609 Since
20611 5.1
20612 AudiodevJackOptions (Object)
20614 Options of the JACK audio backend.
20615 Members
20617 in: AudiodevJackPerDirectionOptions (optional)
20618 options of the capture stream
20619 out: AudiodevJackPerDirectionOptions (optional)
20621 options of the playback stream
20622 Since
20624 5.1
20625 AudiodevOssPerDirectionOptions (Object)
20627 Options of the OSS backend that are used for both playback and record‐
20628 ing.
20629 Members
20631 dev: string (optional)
20632 file name of the OSS device (default '/dev/dsp')
20633 buffer-count: int (optional)
20635 number of buffers
20636 try-poll: boolean (optional)
20638 attempt to use poll mode, falling back to non-polling access on
20639 failure (default true)
20640 The members of AudiodevPerDirectionOptions
20642 Since
20644 4.0
20645 AudiodevOssOptions (Object)
20647 Options of the OSS audio backend.
20648 Members
20650 in: AudiodevOssPerDirectionOptions (optional)
20651 options of the capture stream
20652 out: AudiodevOssPerDirectionOptions (optional)
20654 options of the playback stream
20655 try-mmap: boolean (optional)
20657 try using memory-mapped access, falling back to non-mem‐
20658 ory-mapped access on failure (default true)
20659 exclusive: boolean (optional)
20661 open device in exclusive mode (vmix won't work) (default false)
20662 dsp-policy: int (optional)
20664 set the timing policy of the device (between 0 and 10, where
20665 smaller number means smaller latency but higher CPU usage) or -1
20666 to use fragment mode (option ignored on some platforms) (default
20667 5)
20668 Since
20670 4.0
20671 AudiodevPaPerDirectionOptions (Object)
20673 Options of the Pulseaudio backend that are used for both playback and
20674 recording.
20675 Members
20677 name: string (optional)
20678 name of the sink/source to use
20679 stream-name: string (optional)
20681 name of the PulseAudio stream created by qemu. Can be used to
20682 identify the stream in PulseAudio when you create multiple
20683 PulseAudio devices or run multiple qemu instances (default: au‐
20684 diodev's id, since 4.2)
20685 latency: int (optional)
20687 latency you want PulseAudio to achieve in microseconds (default
20688 15000)
20689 The members of AudiodevPerDirectionOptions
20691 Since
20693 4.0
20694 AudiodevPaOptions (Object)
20696 Options of the PulseAudio audio backend.
20697 Members
20699 in: AudiodevPaPerDirectionOptions (optional)
20700 options of the capture stream
20701 out: AudiodevPaPerDirectionOptions (optional)
20703 options of the playback stream
20704 server: string (optional)
20706 PulseAudio server address (default: let PulseAudio choose)
20707 Since
20709 4.0
20710 AudiodevSdlPerDirectionOptions (Object)
20712 Options of the SDL audio backend that are used for both playback and
20713 recording.
20714 Members
20716 buffer-count: int (optional)
20717 number of buffers (default 4)
20718 The members of AudiodevPerDirectionOptions
20720 Since
20722 6.0
20723 AudiodevSdlOptions (Object)
20725 Options of the SDL audio backend.
20726 Members
20728 in: AudiodevSdlPerDirectionOptions (optional)
20729 options of the recording stream
20730 out: AudiodevSdlPerDirectionOptions (optional)
20732 options of the playback stream
20733 Since
20735 6.0
20736 AudiodevWavOptions (Object)
20738 Options of the wav audio backend.
20739 Members
20741 in: AudiodevPerDirectionOptions (optional)
20742 options of the capture stream
20743 out: AudiodevPerDirectionOptions (optional)
20745 options of the playback stream
20746 path: string (optional)
20748 name of the wav file to record (default 'qemu.wav')
20749 Since
20751 4.0
20752 AudioFormat (Enum)
20754 An enumeration of possible audio formats.
20755 Values
20757 u8 unsigned 8 bit integer
20758 s8 signed 8 bit integer
20760 u16 unsigned 16 bit integer
20762 s16 signed 16 bit integer
20764 u32 unsigned 32 bit integer
20766 s32 signed 32 bit integer
20768 f32 single precision floating-point (since 5.0)
20770 Since
20772 4.0
20773 AudiodevDriver (Enum)
20775 An enumeration of possible audio backend drivers.
20776 Values
20778 jack JACK audio backend (since 5.1)
20779 none Not documented
20781 alsa Not documented
20783 coreaudio
20785 Not documented
20786 dbus Not documented
20788 dsound Not documented
20790 oss Not documented
20792 pa Not documented
20794 sdl Not documented
20796 spice Not documented
20798 wav Not documented
20800 Since
20802 4.0
20803 Audiodev (Object)
20805 Options of an audio backend.
20806 Members
20808 id: string
20809 identifier of the backend
20810 driver: AudiodevDriver
20812 the backend driver to use
20813 timer-period: int (optional)
20815 timer period (in microseconds, 0: use lowest possible)
20816 The members of AudiodevGenericOptions when driver is "none"
20818 The members of AudiodevAlsaOptions when driver is "alsa"
20820 The members of AudiodevCoreaudioOptions when driver is "coreaudio"
20822 The members of AudiodevGenericOptions when driver is "dbus"
20824 The members of AudiodevDsoundOptions when driver is "dsound"
20826 The members of AudiodevJackOptions when driver is "jack"
20828 The members of AudiodevOssOptions when driver is "oss"
20830 The members of AudiodevPaOptions when driver is "pa"
20832 The members of AudiodevSdlOptions when driver is "sdl"
20834 The members of AudiodevGenericOptions when driver is "spice"
20836 The members of AudiodevWavOptions when driver is "wav"
20838 Since
20840 4.0
20841
20843 AcpiTableOptions (Object)
20844 Specify an ACPI table on the command line to load.
20845 At most one of file and data can be specified. The list of files speci‐
20847 fied by any one of them is loaded and concatenated in order. If both
20848 are omitted, data is implied.
20849 Other fields / optargs can be used to override fields of the generic
20851 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
20852 System Description Table Header. If a header field is not overridden,
20853 then the corresponding value from the concatenated blob is used (in
20854 case of file), or it is filled in with a hard-coded value (in case of
20855 data).
20856 String fields are copied into the matching ACPI member from lowest ad‐
20858 dress upwards, and silently truncated / NUL-padded to length.
20859 Members
20861 sig: string (optional)
20862 table signature / identifier (4 bytes)
20863 rev: int (optional)
20865 table revision number (dependent on signature, 1 byte)
20866 oem_id: string (optional)
20868 OEM identifier (6 bytes)
20869 oem_table_id: string (optional)
20871 OEM table identifier (8 bytes)
20872 oem_rev: int (optional)
20874 OEM-supplied revision number (4 bytes)
20875 asl_compiler_id: string (optional)
20877 identifier of the utility that created the table (4 bytes)
20878 asl_compiler_rev: int (optional)
20880 revision number of the utility that created the table (4 bytes)
20881 file: string (optional)
20883 colon (:) separated list of pathnames to load and concatenate as
20884 table data. The resultant binary blob is expected to have an
20885 ACPI table header. At least one file is required. This field ex‐
20886 cludes data.
20887 data: string (optional)
20889 colon (:) separated list of pathnames to load and concatenate as
20890 table data. The resultant binary blob must not have an ACPI ta‐
20891 ble header. At least one file is required. This field excludes
20892 file.
20893 Since
20895 1.5
20896 ACPISlotType (Enum)
20898 Values
20899 DIMM memory slot
20900 CPU logical CPU slot (since 2.7)
20902 ACPIOSTInfo (Object)
20904 OSPM Status Indication for a device For description of possible values
20905 of source and status fields see "_OST (OSPM Status Indication)" chapter
20906 of ACPI5.0 spec.
20907 Members
20909 device: string (optional)
20910 device ID associated with slot
20911 slot: string
20913 slot ID, unique per slot of a given slot-type
20914 slot-type: ACPISlotType
20916 type of the slot
20917 source: int
20919 an integer containing the source event
20920 status: int
20922 an integer containing the status code
20923 Since
20925 2.1
20926 query-acpi-ospm-status (Command)
20928 Return a list of ACPIOSTInfo for devices that support status reporting
20929 via ACPI _OST method.
20930 Since
20932 2.1
20933 Example
20935 -> { "execute": "query-acpi-ospm-status" }
20936 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
20937 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
20938 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
20939 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
20940 ]}
20941 ACPI_DEVICE_OST (Event)
20943 Emitted when guest executes ACPI _OST method.
20944 Arguments
20946 info: ACPIOSTInfo
20947 OSPM Status Indication
20948 Since
20950 2.1
20951 Example
20953 <- { "event": "ACPI_DEVICE_OST",
20954 "data": { "info": { "device": "d1", "slot": "0",
20955 "slot-type": "DIMM", "source": 1, "status": 0 } },
20956 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
20957
20959 PciMemoryRange (Object)
20960 A PCI device memory region
20961 Members
20963 base: int
20964 the starting address (guest physical)
20965 limit: int
20967 the ending address (guest physical)
20968 Since
20970 0.14
20971 PciMemoryRegion (Object)
20973 Information about a PCI device I/O region.
20974 Members
20976 bar: int
20977 the index of the Base Address Register for this region
20978 type: string
20980 • 'io' if the region is a PIO region
20982 • 'memory' if the region is a MMIO region
20984 size: int
20986 memory size
20987 prefetch: boolean (optional)
20989 if type is 'memory', true if the memory is prefetchable
20990 mem_type_64: boolean (optional)
20992 if type is 'memory', true if the BAR is 64-bit
20993 address: int
20995 Not documented
20996 Since
20998 0.14
20999 PciBusInfo (Object)
21001 Information about a bus of a PCI Bridge device
21002 Members
21004 number: int
21005 primary bus interface number. This should be the number of the
21006 bus the device resides on.
21007 secondary: int
21009 secondary bus interface number. This is the number of the main
21010 bus for the bridge
21011 subordinate: int
21013 This is the highest number bus that resides below the bridge.
21014 io_range: PciMemoryRange
21016 The PIO range for all devices on this bridge
21017 memory_range: PciMemoryRange
21019 The MMIO range for all devices on this bridge
21020 prefetchable_range: PciMemoryRange
21022 The range of prefetchable MMIO for all devices on this bridge
21023 Since
21025 2.4
21026 PciBridgeInfo (Object)
21028 Information about a PCI Bridge device
21029 Members
21031 bus: PciBusInfo
21032 information about the bus the device resides on
21033 devices: array of PciDeviceInfo (optional)
21035 a list of PciDeviceInfo for each device on this bridge
21036 Since
21038 0.14
21039 PciDeviceClass (Object)
21041 Information about the Class of a PCI device
21042 Members
21044 desc: string (optional)
21045 a string description of the device's class
21046 class: int
21048 the class code of the device
21049 Since
21051 2.4
21052 PciDeviceId (Object)
21054 Information about the Id of a PCI device
21055 Members
21057 device: int
21058 the PCI device id
21059 vendor: int
21061 the PCI vendor id
21062 subsystem: int (optional)
21064 the PCI subsystem id (since 3.1)
21065 subsystem-vendor: int (optional)
21067 the PCI subsystem vendor id (since 3.1)
21068 Since
21070 2.4
21071 PciDeviceInfo (Object)
21073 Information about a PCI device
21074 Members
21076 bus: int
21077 the bus number of the device
21078 slot: int
21080 the slot the device is located in
21081 function: int
21083 the function of the slot used by the device
21084 class_info: PciDeviceClass
21086 the class of the device
21087 id: PciDeviceId
21089 the PCI device id
21090 irq: int (optional)
21092 if an IRQ is assigned to the device, the IRQ number
21093 irq_pin: int
21095 the IRQ pin, zero means no IRQ (since 5.1)
21096 qdev_id: string
21098 the device name of the PCI device
21099 pci_bridge: PciBridgeInfo (optional)
21101 if the device is a PCI bridge, the bridge information
21102 regions: array of PciMemoryRegion
21104 a list of the PCI I/O regions associated with the device
21105 Notes
21107 the contents of class_info.desc are not stable and should only be
21108 treated as informational.
21109 Since
21111 0.14
21112 PciInfo (Object)
21114 Information about a PCI bus
21115 Members
21117 bus: int
21118 the bus index
21119 devices: array of PciDeviceInfo
21121 a list of devices on this bus
21122 Since
21124 0.14
21125 query-pci (Command)
21127 Return information about the PCI bus topology of the guest.
21128 Returns
21130 a list of PciInfo for each PCI bus. Each bus is represented by a
21131 json-object, which has a key with a json-array of all PCI devices at‐
21132 tached to it. Each device is represented by a json-object.
21133 Since
21135 0.14
21136 Example
21138 -> { "execute": "query-pci" }
21139 <- { "return": [
21140 {
21141 "bus": 0,
21142 "devices": [
21143 {
21144 "bus": 0,
21145 "qdev_id": "",
21146 "slot": 0,
21147 "class_info": {
21148 "class": 1536,
21149 "desc": "Host bridge"
21150 },
21151 "id": {
21152 "device": 32902,
21153 "vendor": 4663
21154 },
21155 "function": 0,
21156 "regions": [
21157 ]
21158 },
21159 {
21160 "bus": 0,
21161 "qdev_id": "",
21162 "slot": 1,
21163 "class_info": {
21164 "class": 1537,
21165 "desc": "ISA bridge"
21166 },
21167 "id": {
21168 "device": 32902,
21169 "vendor": 28672
21170 },
21171 "function": 0,
21172 "regions": [
21173 ]
21174 },
21175 {
21176 "bus": 0,
21177 "qdev_id": "",
21178 "slot": 1,
21179 "class_info": {
21180 "class": 257,
21181 "desc": "IDE controller"
21182 },
21183 "id": {
21184 "device": 32902,
21185 "vendor": 28688
21186 },
21187 "function": 1,
21188 "regions": [
21189 {
21190 "bar": 4,
21191 "size": 16,
21192 "address": 49152,
21193 "type": "io"
21194 }
21195 ]
21196 },
21197 {
21198 "bus": 0,
21199 "qdev_id": "",
21200 "slot": 2,
21201 "class_info": {
21202 "class": 768,
21203 "desc": "VGA controller"
21204 },
21205 "id": {
21206 "device": 4115,
21207 "vendor": 184
21208 },
21209 "function": 0,
21210 "regions": [
21211 {
21212 "prefetch": true,
21213 "mem_type_64": false,
21214 "bar": 0,
21215 "size": 33554432,
21216 "address": 4026531840,
21217 "type": "memory"
21218 },
21219 {
21220 "prefetch": false,
21221 "mem_type_64": false,
21222 "bar": 1,
21223 "size": 4096,
21224 "address": 4060086272,
21225 "type": "memory"
21226 },
21227 {
21228 "prefetch": false,
21229 "mem_type_64": false,
21230 "bar": 6,
21231 "size": 65536,
21232 "address": -1,
21233 "type": "memory"
21234 }
21235 ]
21236 },
21237 {
21238 "bus": 0,
21239 "qdev_id": "",
21240 "irq": 11,
21241 "slot": 4,
21242 "class_info": {
21243 "class": 1280,
21244 "desc": "RAM controller"
21245 },
21246 "id": {
21247 "device": 6900,
21248 "vendor": 4098
21249 },
21250 "function": 0,
21251 "regions": [
21252 {
21253 "bar": 0,
21254 "size": 32,
21255 "address": 49280,
21256 "type": "io"
21257 }
21258 ]
21259 }
21260 ]
21261 }
21262 ]
21263 }
21264 Note
21266 This example has been shortened as the real response is too long.
21267
21269 2023, The QEMU Project Developers
212707.0.0 Jan 19, 2023 QEMU-QMP-REF(7)