1QEMU-QMP-REF.7(7) QEMU-QMP-REF.7(7)
2
6 qemu-qmp-ref - QEMU QMP Reference Manual
7
9 Introduction
10 This document describes all commands currently supported by QMP.
11 Most of the time their usage is exactly the same as in the user
13 Monitor, this means that any other document which also describe
14 commands (the manpage, QEMU's manual, etc) can and should be consulted.
15 QMP has two types of commands: regular and query commands. Regular
17 commands usually change the Virtual Machine's state someway, while
18 query commands just return information. The sections below are divided
19 accordingly.
20 It's important to observe that all communication examples are formatted
22 in a reader-friendly way, so that they're easier to understand.
23 However, in real protocol usage, they're emitted as a single line.
24 Also, the following notation is used to denote data flow:
26 Example:
28 -> data issued by the Client
30 <- Server data response
34 Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
36 detailed information on the Server command and response formats.
37 Stability Considerations
39 The current QMP command set (described in this file) may be useful for
40 a number of use cases, however it's limited and several commands have
41 bad defined semantics, specially with regard to command completion.
42 These problems are going to be solved incrementally in the next QEMU
44 releases and we're going to establish a deprecation policy for badly
45 defined commands.
46 If you're planning to adopt QMP, please observe the following:
48 1. The deprecation policy will take effect and be documented soon,
50 please check the documentation of each used command as soon as a
51 new release of QEMU is available
52 2. DO NOT rely on anything which is not explicit documented
54 3. Errors, in special, are not documented. Applications should NOT
56 check for specific errors classes or data (it's strongly
57 recommended to only check for the "error" key)
58 QMP errors
60 QapiErrorClass (Enum)
61 QEMU error classes
63 Values:
65 "GenericError"
67 this is used for errors that don't require a specific error class.
68 This should be the default case for most errors
69 "CommandNotFound"
71 the requested command has not been found
72 "DeviceNotActive"
74 a device has failed to be become active
75 "DeviceNotFound"
77 the requested device has not been found
78 "KVMMissingCap"
80 the requested operation can't be fulfilled because a required KVM
81 capability is missing
82 Since: 1.2
84 Common data types
86 IoOperationType (Enum)
87 An enumeration of the I/O operation types
89 Values:
91 "read"
93 read operation
94 "write"
96 write operation
97 Since: 2.1
99 OnOffAuto (Enum)
101 An enumeration of three options: on, off, and auto
103 Values:
105 "auto"
107 QEMU selects the value between on and off
108 "on"
110 Enabled
111 "off"
113 Disabled
114 Since: 2.2
116 OnOffSplit (Enum)
118 An enumeration of three values: on, off, and split
120 Values:
122 "on"
124 Enabled
125 "off"
127 Disabled
128 "split"
130 Mixed
131 Since: 2.6
133 String (Object)
135 A fat type wrapping 'str', to be embedded in lists.
137 Members:
139 "str: string"
141 Not documented
142 Since: 1.2
144 StrOrNull (Alternate)
146 This is a string value or the explicit lack of a string (null pointer
148 in C). Intended for cases when 'optional absent' already has a
149 different meaning.
150 Members:
152 "s: string"
154 the string value
155 "n: null"
157 no string value
158 Since: 2.10
160 OffAutoPCIBAR (Enum)
162 An enumeration of options for specifying a PCI BAR
164 Values:
166 "off"
168 The specified feature is disabled
169 "auto"
171 The PCI BAR for the feature is automatically selected
172 "bar0"
174 PCI BAR0 is used for the feature
175 "bar1"
177 PCI BAR1 is used for the feature
178 "bar2"
180 PCI BAR2 is used for the feature
181 "bar3"
183 PCI BAR3 is used for the feature
184 "bar4"
186 PCI BAR4 is used for the feature
187 "bar5"
189 PCI BAR5 is used for the feature
190 Since: 2.12
192 PCIELinkSpeed (Enum)
194 An enumeration of PCIe link speeds in units of GT/s
196 Values:
198 "2_5"
200 2.5GT/s
201 5 5.0GT/s
203 8 8.0GT/s
205 16 16.0GT/s
207 Since: 4.0
209 PCIELinkWidth (Enum)
211 An enumeration of PCIe link width
213 Values:
215 1 x1
217 2 x2
219 4 x4
221 8 x8
223 12 x12
225 16 x16
227 32 x32
229 Since: 4.0
231 Socket data types
233 NetworkAddressFamily (Enum)
234 The network address family
236 Values:
238 "ipv4"
240 IPV4 family
241 "ipv6"
243 IPV6 family
244 "unix"
246 unix socket
247 "vsock"
249 vsock family (since 2.8)
250 "unknown"
252 otherwise
253 Since: 2.1
255 InetSocketAddressBase (Object)
257 Members:
259 "host: string"
261 host part of the address
262 "port: string"
264 port part of the address
265 InetSocketAddress (Object)
267 Captures a socket address or address range in the Internet namespace.
269 Members:
271 "numeric: boolean" (optional)
273 true if the host/port are guaranteed to be numeric, false if name
274 resolution should be attempted. Defaults to false. (Since 2.9)
275 "to: int" (optional)
277 If present, this is range of possible addresses, with port between
278 "port" and "to".
279 "ipv4: boolean" (optional)
281 whether to accept IPv4 addresses, default try both IPv4 and IPv6
282 "ipv6: boolean" (optional)
284 whether to accept IPv6 addresses, default try both IPv4 and IPv6
285 "keep-alive: boolean" (optional)
287 enable keep-alive when connecting to this socket. Not supported for
288 passive sockets. (Since 4.2)
289 The members of "InetSocketAddressBase"
291 Since: 1.3
293 UnixSocketAddress (Object)
295 Captures a socket address in the local ("Unix socket") namespace.
297 Members:
299 "path: string"
301 filesystem path to use
302 "tight: boolean" (optional)
304 pass a socket address length confined to the minimum length of the
305 abstract string, rather than the full sockaddr_un record length
306 (only matters for abstract sockets, default true). (Since 5.1)
307 "abstract: boolean" (optional)
309 whether this is an abstract address, default false. (Since 5.1)
310 Since: 1.3
312 VsockSocketAddress (Object)
314 Captures a socket address in the vsock namespace.
316 Members:
318 "cid: string"
320 unique host identifier
321 "port: string"
323 port
324 Note: string types are used to allow for possible future hostname or
326 service resolution support.
327 Since: 2.8
329 SocketAddressLegacy (Object)
331 Captures the address of a socket, which could also be a named file
333 descriptor
334 Members:
336 "type"
338 One of "inet", "unix", "vsock", "fd"
339 "data: InetSocketAddress" when "type" is "inet"
341 "data: UnixSocketAddress" when "type" is "unix"
342 "data: VsockSocketAddress" when "type" is "vsock"
343 "data: String" when "type" is "fd"
344 Note: This type is deprecated in favor of SocketAddress. The
346 difference between SocketAddressLegacy and SocketAddress is that the
347 latter is a flat union rather than a simple union. Flat is nicer
348 because it avoids nesting on the wire, i.e. that form has fewer {}.
349 Since: 1.3
351 SocketAddressType (Enum)
353 Available SocketAddress types
355 Values:
357 "inet"
359 Internet address
360 "unix"
362 Unix domain socket
363 "vsock"
365 VMCI address
366 "fd"
368 decimal is for file descriptor number, otherwise a file descriptor
369 name. Named file descriptors are permitted in monitor commands, in
370 combination with the 'getfd' command. Decimal file descriptors are
371 permitted at startup or other contexts where no monitor context is
372 active.
373 Since: 2.9
375 SocketAddress (Object)
377 Captures the address of a socket, which could also be a named file
379 descriptor
380 Members:
382 "type: SocketAddressType"
384 Transport type
385 The members of "InetSocketAddress" when "type" is "inet"
387 The members of "UnixSocketAddress" when "type" is "unix"
388 The members of "VsockSocketAddress" when "type" is "vsock"
389 The members of "String" when "type" is "fd"
390 Since: 2.9
392 VM run state
394 RunState (Enum)
395 An enumeration of VM run states.
397 Values:
399 "debug"
401 QEMU is running on a debugger
402 "finish-migrate"
404 guest is paused to finish the migration process
405 "inmigrate"
407 guest is paused waiting for an incoming migration. Note that this
408 state does not tell whether the machine will start at the end of
409 the migration. This depends on the command-line -S option and any
410 invocation of 'stop' or 'cont' that has happened since QEMU was
411 started.
412 "internal-error"
414 An internal error that prevents further guest execution has
415 occurred
416 "io-error"
418 the last IOP has failed and the device is configured to pause on
419 I/O errors
420 "paused"
422 guest has been paused via the 'stop' command
423 "postmigrate"
425 guest is paused following a successful 'migrate'
426 "prelaunch"
428 QEMU was started with -S and guest has not started
429 "restore-vm"
431 guest is paused to restore VM state
432 "running"
434 guest is actively running
435 "save-vm"
437 guest is paused to save the VM state
438 "shutdown"
440 guest is shut down (and -no-shutdown is in use)
441 "suspended"
443 guest is suspended (ACPI S3)
444 "watchdog"
446 the watchdog action is configured to pause and has been triggered
447 "guest-panicked"
449 guest has been panicked as a result of guest OS panic
450 "colo"
452 guest is paused to save/restore VM state under colo checkpoint, VM
453 can not get into this state unless colo capability is enabled for
454 migration. (since 2.8)
455 "preconfig"
457 QEMU is paused before board specific init callback is executed.
458 The state is reachable only if the --preconfig CLI option is used.
459 (Since 3.0)
460 ShutdownCause (Enum)
462 An enumeration of reasons for a Shutdown.
464 Values:
466 "none"
468 No shutdown request pending
469 "host-error"
471 An error prevents further use of guest
472 "host-qmp-quit"
474 Reaction to the QMP command 'quit'
475 "host-qmp-system-reset"
477 Reaction to the QMP command 'system_reset'
478 "host-signal"
480 Reaction to a signal, such as SIGINT
481 "host-ui"
483 Reaction to a UI event, like window close
484 "guest-shutdown"
486 Guest shutdown/suspend request, via ACPI or other hardware-specific
487 means
488 "guest-reset"
490 Guest reset request, and command line turns that into a shutdown
491 "guest-panic"
493 Guest panicked, and command line turns that into a shutdown
494 "subsystem-reset"
496 Partial guest reset that does not trigger QMP events and ignores
497 --no-reboot. This is useful for sanitizing hypercalls on s390 that
498 are used during kexec/kdump/boot
499 StatusInfo (Object)
501 Information about VCPU run state
503 Members:
505 "running: boolean"
507 true if all VCPUs are runnable, false if not runnable
508 "singlestep: boolean"
510 true if VCPUs are in single-step mode
511 "status: RunState"
513 the virtual machine "RunState"
514 Since: 0.14.0
516 Notes: "singlestep" is enabled through the GDB stub
518 query-status (Command) Query the run status of all VCPUs
520 Returns: "StatusInfo" reflecting all VCPUs
522 Since: 0.14.0
524 Example:
526 -> { "execute": "query-status" }
528 <- { "return": { "running": true,
529 "singlestep": false,
530 "status": "running" } }
531 SHUTDOWN (Event) Emitted when the virtual machine has shut down,
533 indicating that qemu is about to exit.
534 Arguments:
536 "guest: boolean"
538 If true, the shutdown was triggered by a guest request (such as a
539 guest-initiated ACPI shutdown request or other hardware-specific
540 action) rather than a host request (such as sending qemu a SIGINT).
541 (since 2.10)
542 "reason: ShutdownCause"
544 The "ShutdownCause" which resulted in the SHUTDOWN. (since 4.0)
545 Note: If the command-line option "-no-shutdown" has been specified,
547 qemu will not exit, and a STOP event will eventually follow the
548 SHUTDOWN event
549 Since: 0.12.0
551 Example:
553 <- { "event": "SHUTDOWN", "data": { "guest": true },
555 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
556 POWERDOWN (Event) Emitted when the virtual machine is powered down
558 through the power control system, such as via ACPI.
559 Since: 0.12.0
561 Example:
563 <- { "event": "POWERDOWN",
565 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
566 RESET (Event) Emitted when the virtual machine is reset
568 Arguments:
570 "guest: boolean"
572 If true, the reset was triggered by a guest request (such as a
573 guest-initiated ACPI reboot request or other hardware-specific
574 action) rather than a host request (such as the QMP command
575 system_reset). (since 2.10)
576 "reason: ShutdownCause"
578 The "ShutdownCause" of the RESET. (since 4.0)
579 Since: 0.12.0
581 Example:
583 <- { "event": "RESET", "data": { "guest": false },
585 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
586 STOP (Event) Emitted when the virtual machine is stopped
588 Since: 0.12.0
590 Example:
592 <- { "event": "STOP",
594 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
595 RESUME (Event) Emitted when the virtual machine resumes execution
597 Since: 0.12.0
599 Example:
601 <- { "event": "RESUME",
603 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
604 SUSPEND (Event) Emitted when guest enters a hardware suspension state,
606 for example, S3 state, which is sometimes called standby state
607 Since: 1.1
609 Example:
611 <- { "event": "SUSPEND",
613 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
614 SUSPEND_DISK (Event) Emitted when guest enters a hardware suspension
616 state with data saved on disk, for example, S4 state, which is
617 sometimes called hibernate state
618 Note: QEMU shuts down (similar to event "SHUTDOWN") when entering this
620 state
621 Since: 1.2
623 Example:
625 <- { "event": "SUSPEND_DISK",
627 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
628 WAKEUP (Event) Emitted when the guest has woken up from suspend state
630 and is running
631 Since: 1.1
633 Example:
635 <- { "event": "WAKEUP",
637 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
638 WATCHDOG (Event) Emitted when the watchdog device's timer is expired
640 Arguments:
642 "action: WatchdogAction"
644 action that has been taken
645 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event
647 is followed respectively by the RESET, SHUTDOWN, or STOP events
648 Note: This event is rate-limited.
650 Since: 0.13.0
652 Example:
654 <- { "event": "WATCHDOG",
656 "data": { "action": "reset" },
657 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
658 WatchdogAction (Enum)
660 An enumeration of the actions taken when the watchdog device's timer is
662 expired
663 Values:
665 "reset"
667 system resets
668 "shutdown"
670 system shutdown, note that it is similar to "powerdown", which
671 tries to set to system status and notify guest
672 "poweroff"
674 system poweroff, the emulator program exits
675 "pause"
677 system pauses, similar to "stop"
678 "debug"
680 system enters debug state
681 "none"
683 nothing is done
684 "inject-nmi"
686 a non-maskable interrupt is injected into the first VCPU (all VCPUS
687 on x86) (since 2.4)
688 Since: 2.1
690 watchdog-set-action (Command) Set watchdog action
692 Arguments:
694 "action: WatchdogAction"
696 Not documented
697 Since: 2.11
699 GUEST_PANICKED (Event) Emitted when guest OS panic is detected
701 Arguments:
703 "action: GuestPanicAction"
705 action that has been taken, currently always "pause"
706 "info: GuestPanicInformation" (optional)
708 information about a panic (since 2.9)
709 Since: 1.5
711 Example:
713 <- { "event": "GUEST_PANICKED",
715 "data": { "action": "pause" } }
716 GUEST_CRASHLOADED (Event) Emitted when guest OS crash loaded is
718 detected
719 Arguments:
721 "action: GuestPanicAction"
723 action that has been taken, currently always "run"
724 "info: GuestPanicInformation" (optional)
726 information about a panic
727 Since: 5.0
729 Example:
731 <- { "event": "GUEST_CRASHLOADED",
733 "data": { "action": "run" } }
734 GuestPanicAction (Enum)
736 An enumeration of the actions taken when guest OS panic is detected
738 Values:
740 "pause"
742 system pauses
743 "poweroff"
745 Not documented
746 "run"
748 Not documented
749 Since: 2.1 (poweroff since 2.8, run since 5.0)
751 GuestPanicInformationType (Enum)
753 An enumeration of the guest panic information types
755 Values:
757 "hyper-v"
759 hyper-v guest panic information type
760 "s390"
762 s390 guest panic information type (Since: 2.12)
763 Since: 2.9
765 GuestPanicInformation (Object)
767 Information about a guest panic
769 Members:
771 "type: GuestPanicInformationType"
773 Crash type that defines the hypervisor specific information
774 The members of "GuestPanicInformationHyperV" when "type" is "hyper-v"
776 The members of "GuestPanicInformationS390" when "type" is "s390"
777 Since: 2.9
779 GuestPanicInformationHyperV (Object)
781 Hyper-V specific guest panic information (HV crash MSRs)
783 Members:
785 "arg1: int"
787 Not documented
788 "arg2: int"
790 Not documented
791 "arg3: int"
793 Not documented
794 "arg4: int"
796 Not documented
797 "arg5: int"
799 Not documented
800 Since: 2.9
802 S390CrashReason (Enum)
804 Reason why the CPU is in a crashed state.
806 Values:
808 "unknown"
810 no crash reason was set
811 "disabled-wait"
813 the CPU has entered a disabled wait state
814 "extint-loop"
816 clock comparator or cpu timer interrupt with new PSW enabled for
817 external interrupts
818 "pgmint-loop"
820 program interrupt with BAD new PSW
821 "opint-loop"
823 operation exception interrupt with invalid code at the program
824 interrupt new PSW
825 Since: 2.12
827 GuestPanicInformationS390 (Object)
829 S390 specific guest panic information (PSW)
831 Members:
833 "core: int"
835 core id of the CPU that crashed
836 "psw-mask: int"
838 control fields of guest PSW
839 "psw-addr: int"
841 guest instruction address
842 "reason: S390CrashReason"
844 guest crash reason
845 Since: 2.12
847 Cryptography
849 QCryptoTLSCredsEndpoint (Enum)
850 The type of network endpoint that will be using the credentials. Most
852 types of credential require different setup / structures depending on
853 whether they will be used in a server versus a client.
854 Values:
856 "client"
858 the network endpoint is acting as the client
859 "server"
861 the network endpoint is acting as the server
862 Since: 2.5
864 QCryptoSecretFormat (Enum)
866 The data format that the secret is provided in
868 Values:
870 "raw"
872 raw bytes. When encoded in JSON only valid UTF-8 sequences can be
873 used
874 "base64"
876 arbitrary base64 encoded binary data
877 Since: 2.6
879 QCryptoHashAlgorithm (Enum)
881 The supported algorithms for computing content digests
883 Values:
885 "md5"
887 MD5. Should not be used in any new code, legacy compat only
888 "sha1"
890 SHA-1. Should not be used in any new code, legacy compat only
891 "sha224"
893 SHA-224. (since 2.7)
894 "sha256"
896 SHA-256. Current recommended strong hash.
897 "sha384"
899 SHA-384. (since 2.7)
900 "sha512"
902 SHA-512. (since 2.7)
903 "ripemd160"
905 RIPEMD-160. (since 2.7)
906 Since: 2.6
908 QCryptoCipherAlgorithm (Enum)
910 The supported algorithms for content encryption ciphers
912 Values:
914 "aes-128"
916 AES with 128 bit / 16 byte keys
917 "aes-192"
919 AES with 192 bit / 24 byte keys
920 "aes-256"
922 AES with 256 bit / 32 byte keys
923 "des-rfb"
925 RFB specific variant of single DES. Do not use except in VNC.
926 "3des"
928 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
929 "cast5-128"
931 Cast5 with 128 bit / 16 byte keys
932 "serpent-128"
934 Serpent with 128 bit / 16 byte keys
935 "serpent-192"
937 Serpent with 192 bit / 24 byte keys
938 "serpent-256"
940 Serpent with 256 bit / 32 byte keys
941 "twofish-128"
943 Twofish with 128 bit / 16 byte keys
944 "twofish-192"
946 Twofish with 192 bit / 24 byte keys
947 "twofish-256"
949 Twofish with 256 bit / 32 byte keys
950 Since: 2.6
952 QCryptoCipherMode (Enum)
954 The supported modes for content encryption ciphers
956 Values:
958 "ecb"
960 Electronic Code Book
961 "cbc"
963 Cipher Block Chaining
964 "xts"
966 XEX with tweaked code book and ciphertext stealing
967 "ctr"
969 Counter (Since 2.8)
970 Since: 2.6
972 QCryptoIVGenAlgorithm (Enum)
974 The supported algorithms for generating initialization vectors for full
976 disk encryption. The 'plain' generator should not be used for disks
977 with sector numbers larger than 2^32, except where compatibility with
978 pre-existing Linux dm-crypt volumes is required.
979 Values:
981 "plain"
983 64-bit sector number truncated to 32-bits
984 "plain64"
986 64-bit sector number
987 "essiv"
989 64-bit sector number encrypted with a hash of the encryption key
990 Since: 2.6
992 QCryptoBlockFormat (Enum)
994 The supported full disk encryption formats
996 Values:
998 "qcow"
1000 QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
1001 data from old images.
1002 "luks"
1004 LUKS encryption format. Recommended for new images
1005 Since: 2.6
1007 QCryptoBlockOptionsBase (Object)
1009 The common options that apply to all full disk encryption formats
1011 Members:
1013 "format: QCryptoBlockFormat"
1015 the encryption format
1016 Since: 2.6
1018 QCryptoBlockOptionsQCow (Object)
1020 The options that apply to QCow/QCow2 AES-CBC encryption format
1022 Members:
1024 "key-secret: string" (optional)
1026 the ID of a QCryptoSecret object providing the decryption key.
1027 Mandatory except when probing image for metadata only.
1028 Since: 2.6
1030 QCryptoBlockOptionsLUKS (Object)
1032 The options that apply to LUKS encryption format
1034 Members:
1036 "key-secret: string" (optional)
1038 the ID of a QCryptoSecret object providing the decryption key.
1039 Mandatory except when probing image for metadata only.
1040 Since: 2.6
1042 QCryptoBlockCreateOptionsLUKS (Object)
1044 The options that apply to LUKS encryption format initialization
1046 Members:
1048 "cipher-alg: QCryptoCipherAlgorithm" (optional)
1050 the cipher algorithm for data encryption Currently defaults to
1051 'aes-256'.
1052 "cipher-mode: QCryptoCipherMode" (optional)
1054 the cipher mode for data encryption Currently defaults to 'xts'
1055 "ivgen-alg: QCryptoIVGenAlgorithm" (optional)
1057 the initialization vector generator Currently defaults to 'plain64'
1058 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1060 the initialization vector generator hash Currently defaults to
1061 'sha256'
1062 "hash-alg: QCryptoHashAlgorithm" (optional)
1064 the master key hash algorithm Currently defaults to 'sha256'
1065 "iter-time: int" (optional)
1067 number of milliseconds to spend in PBKDF passphrase processing.
1068 Currently defaults to 2000. (since 2.8)
1069 The members of "QCryptoBlockOptionsLUKS"
1071 Since: 2.6
1073 QCryptoBlockOpenOptions (Object)
1075 The options that are available for all encryption formats when opening
1077 an existing volume
1078 Members:
1080 The members of "QCryptoBlockOptionsBase"
1082 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1083 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
1084 Since: 2.6
1086 QCryptoBlockCreateOptions (Object)
1088 The options that are available for all encryption formats when
1090 initializing a new volume
1091 Members:
1093 The members of "QCryptoBlockOptionsBase"
1095 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1096 The members of "QCryptoBlockCreateOptionsLUKS" when "format" is "luks"
1097 Since: 2.6
1099 QCryptoBlockInfoBase (Object)
1101 The common information that applies to all full disk encryption formats
1103 Members:
1105 "format: QCryptoBlockFormat"
1107 the encryption format
1108 Since: 2.7
1110 QCryptoBlockInfoLUKSSlot (Object)
1112 Information about the LUKS block encryption key slot options
1114 Members:
1116 "active: boolean"
1118 whether the key slot is currently in use
1119 "key-offset: int"
1121 offset to the key material in bytes
1122 "iters: int" (optional)
1124 number of PBKDF2 iterations for key material
1125 "stripes: int" (optional)
1127 number of stripes for splitting key material
1128 Since: 2.7
1130 QCryptoBlockInfoLUKS (Object)
1132 Information about the LUKS block encryption options
1134 Members:
1136 "cipher-alg: QCryptoCipherAlgorithm"
1138 the cipher algorithm for data encryption
1139 "cipher-mode: QCryptoCipherMode"
1141 the cipher mode for data encryption
1142 "ivgen-alg: QCryptoIVGenAlgorithm"
1144 the initialization vector generator
1145 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1147 the initialization vector generator hash
1148 "hash-alg: QCryptoHashAlgorithm"
1150 the master key hash algorithm
1151 "payload-offset: int"
1153 offset to the payload data in bytes
1154 "master-key-iters: int"
1156 number of PBKDF2 iterations for key material
1157 "uuid: string"
1159 unique identifier for the volume
1160 "slots: array of QCryptoBlockInfoLUKSSlot"
1162 information about each key slot
1163 Since: 2.7
1165 QCryptoBlockInfo (Object)
1167 Information about the block encryption options
1169 Members:
1171 The members of "QCryptoBlockInfoBase"
1173 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1174 Since: 2.7
1176 QCryptoBlockLUKSKeyslotState (Enum)
1178 Defines state of keyslots that are affected by the update
1180 Values:
1182 "active"
1184 The slots contain the given password and marked as active
1185 "inactive"
1187 The slots are erased (contain garbage) and marked as inactive
1188 Since: 5.1
1190 QCryptoBlockAmendOptionsLUKS (Object)
1192 This struct defines the update parameters that activate/de-activate set
1194 of keyslots
1195 Members:
1197 "state: QCryptoBlockLUKSKeyslotState"
1199 the desired state of the keyslots
1200 "new-secret: string" (optional)
1202 The ID of a QCryptoSecret object providing the password to be
1203 written into added active keyslots
1204 "old-secret: string" (optional)
1206 Optional (for deactivation only) If given will deactive all
1207 keyslots that match password located in QCryptoSecret with this ID
1208 "iter-time: int" (optional)
1210 Optional (for activation only) Number of milliseconds to spend in
1211 PBKDF passphrase processing for the newly activated keyslot.
1212 Currently defaults to 2000.
1213 "keyslot: int" (optional)
1215 Optional. ID of the keyslot to activate/deactivate. For keyslot
1216 activation, keyslot should not be active already (this is unsafe to
1217 update an active keyslot), but possible if 'force' parameter is
1218 given. If keyslot is not given, first free keyslot will be
1219 written.
1220 For keyslot deactivation, this parameter specifies the exact
1222 keyslot to deactivate
1223 "secret: string" (optional)
1225 Optional. The ID of a QCryptoSecret object providing the password
1226 to use to retrive current master key. Defaults to the same secret
1227 that was used to open the image
1228 Since 5.1
1230 QCryptoBlockAmendOptions (Object)
1232 The options that are available for all encryption formats when amending
1234 encryption settings
1235 Members:
1237 The members of "QCryptoBlockOptionsBase"
1239 The members of "QCryptoBlockAmendOptionsLUKS" when "format" is "luks"
1240 Since: 5.1
1242 Block devices
1244 Block core (VM unrelated)
1245 Background jobs
1247 JobType (Enum)
1249 Type of a background job.
1251 Values:
1253 "commit"
1255 block commit job type, see "block-commit"
1256 "stream"
1258 block stream job type, see "block-stream"
1259 "mirror"
1261 drive mirror job type, see "drive-mirror"
1262 "backup"
1264 drive backup job type, see "drive-backup"
1265 "create"
1267 image creation job type, see "blockdev-create" (since 3.0)
1268 "amend"
1270 image options amend job type, see "x-blockdev-amend" (since 5.1)
1271 Since: 1.7
1273 JobStatus (Enum)
1275 Indicates the present state of a given job in its lifetime.
1277 Values:
1279 "undefined"
1281 Erroneous, default state. Should not ever be visible.
1282 "created"
1284 The job has been created, but not yet started.
1285 "running"
1287 The job is currently running.
1288 "paused"
1290 The job is running, but paused. The pause may be requested by
1291 either the QMP user or by internal processes.
1292 "ready"
1294 The job is running, but is ready for the user to signal completion.
1295 This is used for long-running jobs like mirror that are designed to
1296 run indefinitely.
1297 "standby"
1299 The job is ready, but paused. This is nearly identical to "paused".
1300 The job may return to "ready" or otherwise be canceled.
1301 "waiting"
1303 The job is waiting for other jobs in the transaction to converge to
1304 the waiting state. This status will likely not be visible for the
1305 last job in a transaction.
1306 "pending"
1308 The job has finished its work, but has finalization steps that it
1309 needs to make prior to completing. These changes will require
1310 manual intervention via "job-finalize" if auto-finalize was set to
1311 false. These pending changes may still fail.
1312 "aborting"
1314 The job is in the process of being aborted, and will finish with an
1315 error. The job will afterwards report that it is "concluded". This
1316 status may not be visible to the management process.
1317 "concluded"
1319 The job has finished all work. If auto-dismiss was set to false,
1320 the job will remain in the query list until it is dismissed via
1321 "job-dismiss".
1322 "null"
1324 The job is in the process of being dismantled. This state should
1325 not ever be visible externally.
1326 Since: 2.12
1328 JobVerb (Enum)
1330 Represents command verbs that can be applied to a job.
1332 Values:
1334 "cancel"
1336 see "job-cancel"
1337 "pause"
1339 see "job-pause"
1340 "resume"
1342 see "job-resume"
1343 "set-speed"
1345 see "block-job-set-speed"
1346 "complete"
1348 see "job-complete"
1349 "dismiss"
1351 see "job-dismiss"
1352 "finalize"
1354 see "job-finalize"
1355 Since: 2.12
1357 JOB_STATUS_CHANGE (Event) Emitted when a job transitions to a
1359 different status.
1360 Arguments:
1362 "id: string"
1364 The job identifier
1365 "status: JobStatus"
1367 The new job status
1368 Since: 3.0
1370 job-pause (Command) Pause an active job.
1372 This command returns immediately after marking the active job for
1374 pausing. Pausing an already paused job is an error.
1375 The job will pause as soon as possible, which means transitioning into
1377 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1378 The corresponding JOB_STATUS_CHANGE event will be emitted.
1379 Cancelling a paused job automatically resumes it.
1381 Arguments:
1383 "id: string"
1385 The job identifier.
1386 Since: 3.0
1388 job-resume (Command) Resume a paused job.
1390 This command returns immediately after resuming a paused job. Resuming
1392 an already running job is an error.
1393 "id" : The job identifier.
1395 Arguments:
1397 "id: string"
1399 Not documented
1400 Since: 3.0
1402 job-cancel (Command) Instruct an active background job to cancel at
1404 the next opportunity. This command returns immediately after marking
1405 the active job for cancellation.
1406 The job will cancel as soon as possible and then emit a
1408 JOB_STATUS_CHANGE event. Usually, the status will change to ABORTING,
1409 but it is possible that a job successfully completes (e.g. because it
1410 was almost done and there was no opportunity to cancel earlier than
1411 completing the job) and transitions to PENDING instead.
1412 Arguments:
1414 "id: string"
1416 The job identifier.
1417 Since: 3.0
1419 job-complete (Command) Manually trigger completion of an active job in
1421 the READY state.
1422 Arguments:
1424 "id: string"
1426 The job identifier.
1427 Since: 3.0
1429 job-dismiss (Command) Deletes a job that is in the CONCLUDED state.
1431 This command only needs to be run explicitly for jobs that don't have
1432 automatic dismiss enabled.
1433 This command will refuse to operate on any job that has not yet reached
1435 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1436 JOB_READY event, job-cancel or job-complete will still need to be used
1437 as appropriate.
1438 Arguments:
1440 "id: string"
1442 The job identifier.
1443 Since: 3.0
1445 job-finalize (Command) Instructs all jobs in a transaction (or a
1447 single job if it is not part of any transaction) to finalize any graph
1448 changes and do any necessary cleanup. This command requires that all
1449 involved jobs are in the PENDING state.
1450 For jobs in a transaction, instructing one job to finalize will force
1452 ALL jobs in the transaction to finalize, so it is only necessary to
1453 instruct a single member job to finalize.
1454 Arguments:
1456 "id: string"
1458 The identifier of any job in the transaction, or of a job that is
1459 not part of any transaction.
1460 Since: 3.0
1462 JobInfo (Object)
1464 Information about a job.
1466 Members:
1468 "id: string"
1470 The job identifier
1471 "type: JobType"
1473 The kind of job that is being performed
1474 "status: JobStatus"
1476 Current job state/status
1477 "current-progress: int"
1479 Progress made until now. The unit is arbitrary and the value can
1480 only meaningfully be used for the ratio of "current-progress" to
1481 "total-progress". The value is monotonically increasing.
1482 "total-progress: int"
1484 Estimated "current-progress" value at the completion of the job.
1485 This value can arbitrarily change while the job is running, in both
1486 directions.
1487 "error: string" (optional)
1489 If this field is present, the job failed; if it is still missing in
1490 the CONCLUDED state, this indicates successful completion.
1491 The value is a human-readable error message to describe the reason
1493 for the job failure. It should not be parsed by applications.
1494 Since: 3.0
1496 query-jobs (Command) Return information about jobs.
1498 Returns: a list with a "JobInfo" for each active job
1500 Since: 3.0
1502 SnapshotInfo (Object)
1504 Members:
1506 "id: string"
1508 unique snapshot id
1509 "name: string"
1511 user chosen name
1512 "vm-state-size: int"
1514 size of the VM state
1515 "date-sec: int"
1517 UTC date of the snapshot in seconds
1518 "date-nsec: int"
1520 fractional part in nano seconds to be used with date-sec
1521 "vm-clock-sec: int"
1523 VM clock relative to boot in seconds
1524 "vm-clock-nsec: int"
1526 fractional part in nano seconds to be used with vm-clock-sec
1527 Since: 1.3
1529 ImageInfoSpecificQCow2EncryptionBase (Object)
1531 Members:
1533 "format: BlockdevQcow2EncryptionFormat"
1535 The encryption format
1536 Since: 2.10
1538 ImageInfoSpecificQCow2Encryption (Object)
1540 Members:
1542 The members of "ImageInfoSpecificQCow2EncryptionBase"
1544 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1545 Since: 2.10
1547 ImageInfoSpecificQCow2 (Object)
1549 Members:
1551 "compat: string"
1553 compatibility level
1554 "data-file: string" (optional)
1556 the filename of the external data file that is stored in the image
1557 and used as a default for opening the image (since: 4.0)
1558 "data-file-raw: boolean" (optional)
1560 True if the external data file must stay valid as a standalone
1561 (read-only) raw image without looking at qcow2 metadata (since:
1562 4.0)
1563 "lazy-refcounts: boolean" (optional)
1565 on or off; only valid for compat >= 1.1
1566 "corrupt: boolean" (optional)
1568 true if the image has been marked corrupt; only valid for compat >=
1569 1.1 (since 2.2)
1570 "refcount-bits: int"
1572 width of a refcount entry in bits (since 2.3)
1573 "encrypt: ImageInfoSpecificQCow2Encryption" (optional)
1575 details about encryption parameters; only set if image is encrypted
1576 (since 2.10)
1577 "bitmaps: array of Qcow2BitmapInfo" (optional)
1579 A list of qcow2 bitmap details (since 4.0)
1580 "compression-type: Qcow2CompressionType"
1582 the image cluster compression method (since 5.1)
1583 Since: 1.7
1585 ImageInfoSpecificVmdk (Object)
1587 Members:
1589 "create-type: string"
1591 The create type of VMDK image
1592 "cid: int"
1594 Content id of image
1595 "parent-cid: int"
1597 Parent VMDK image's cid
1598 "extents: array of ImageInfo"
1600 List of extent files
1601 Since: 1.7
1603 ImageInfoSpecific (Object)
1605 A discriminated record of image format specific information structures.
1607 Members:
1609 "type"
1611 One of "qcow2", "vmdk", "luks"
1612 "data: ImageInfoSpecificQCow2" when "type" is "qcow2"
1614 "data: ImageInfoSpecificVmdk" when "type" is "vmdk"
1615 "data: QCryptoBlockInfoLUKS" when "type" is "luks"
1616 Since: 1.7
1618 ImageInfo (Object)
1620 Information about a QEMU image file
1622 Members:
1624 "filename: string"
1626 name of the image file
1627 "format: string"
1629 format of the image file
1630 "virtual-size: int"
1632 maximum capacity in bytes of the image
1633 "actual-size: int" (optional)
1635 actual size on disk in bytes of the image
1636 "dirty-flag: boolean" (optional)
1638 true if image is not cleanly closed
1639 "cluster-size: int" (optional)
1641 size of a cluster in bytes
1642 "encrypted: boolean" (optional)
1644 true if the image is encrypted
1645 "compressed: boolean" (optional)
1647 true if the image is compressed (Since 1.7)
1648 "backing-filename: string" (optional)
1650 name of the backing file
1651 "full-backing-filename: string" (optional)
1653 full path of the backing file
1654 "backing-filename-format: string" (optional)
1656 the format of the backing file
1657 "snapshots: array of SnapshotInfo" (optional)
1659 list of VM snapshots
1660 "backing-image: ImageInfo" (optional)
1662 info of the backing image (since 1.6)
1663 "format-specific: ImageInfoSpecific" (optional)
1665 structure supplying additional format-specific information (since
1666 1.7)
1667 Since: 1.3
1669 ImageCheck (Object)
1671 Information about a QEMU image file check
1673 Members:
1675 "filename: string"
1677 name of the image file checked
1678 "format: string"
1680 format of the image file checked
1681 "check-errors: int"
1683 number of unexpected errors occurred during check
1684 "image-end-offset: int" (optional)
1686 offset (in bytes) where the image ends, this field is present if
1687 the driver for the image format supports it
1688 "corruptions: int" (optional)
1690 number of corruptions found during the check if any
1691 "leaks: int" (optional)
1693 number of leaks found during the check if any
1694 "corruptions-fixed: int" (optional)
1696 number of corruptions fixed during the check if any
1697 "leaks-fixed: int" (optional)
1699 number of leaks fixed during the check if any
1700 "total-clusters: int" (optional)
1702 total number of clusters, this field is present if the driver for
1703 the image format supports it
1704 "allocated-clusters: int" (optional)
1706 total number of allocated clusters, this field is present if the
1707 driver for the image format supports it
1708 "fragmented-clusters: int" (optional)
1710 total number of fragmented clusters, this field is present if the
1711 driver for the image format supports it
1712 "compressed-clusters: int" (optional)
1714 total number of compressed clusters, this field is present if the
1715 driver for the image format supports it
1716 Since: 1.4
1718 MapEntry (Object)
1720 Mapping information from a virtual block range to a host file range
1722 Members:
1724 "start: int"
1726 the start byte of the mapped virtual range
1727 "length: int"
1729 the number of bytes of the mapped virtual range
1730 "data: boolean"
1732 whether the mapped range has data
1733 "zero: boolean"
1735 whether the virtual blocks are zeroed
1736 "depth: int"
1738 the depth of the mapping
1739 "offset: int" (optional)
1741 the offset in file that the virtual sectors are mapped to
1742 "filename: string" (optional)
1744 filename that is referred to by "offset"
1745 Since: 2.6
1747 BlockdevCacheInfo (Object)
1749 Cache mode information for a block device
1751 Members:
1753 "writeback: boolean"
1755 true if writeback mode is enabled
1756 "direct: boolean"
1758 true if the host page cache is bypassed (O_DIRECT)
1759 "no-flush: boolean"
1761 true if flush requests are ignored for the device
1762 Since: 2.3
1764 BlockDeviceInfo (Object)
1766 Information about the backing device for a block device.
1768 Members:
1770 "file: string"
1772 the filename of the backing device
1773 "node-name: string" (optional)
1775 the name of the block driver node (Since 2.0)
1776 "ro: boolean"
1778 true if the backing device was open read-only
1779 "drv: string"
1781 the name of the block format used to open the backing device. As of
1782 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
1783 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', 'http',
1784 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2', 'raw', 'vdi',
1785 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added, 'cow' dropped 2.3:
1786 'host_floppy' deprecated 2.5: 'host_floppy' dropped 2.6: 'luks'
1787 added 2.8: 'replication' added, 'tftp' dropped 2.9: 'archipelago'
1788 dropped
1789 "backing_file: string" (optional)
1791 the name of the backing file (for copy-on-write)
1792 "backing_file_depth: int"
1794 number of files in the backing file chain (since: 1.2)
1795 "encrypted: boolean"
1797 true if the backing device is encrypted
1798 "encryption_key_missing: boolean"
1800 always false
1801 "detect_zeroes: BlockdevDetectZeroesOptions"
1803 detect and optimize zero writes (Since 2.1)
1804 "bps: int"
1806 total throughput limit in bytes per second is specified
1807 "bps_rd: int"
1809 read throughput limit in bytes per second is specified
1810 "bps_wr: int"
1812 write throughput limit in bytes per second is specified
1813 "iops: int"
1815 total I/O operations per second is specified
1816 "iops_rd: int"
1818 read I/O operations per second is specified
1819 "iops_wr: int"
1821 write I/O operations per second is specified
1822 "image: ImageInfo"
1824 the info of image used (since: 1.6)
1825 "bps_max: int" (optional)
1827 total throughput limit during bursts, in bytes (Since 1.7)
1828 "bps_rd_max: int" (optional)
1830 read throughput limit during bursts, in bytes (Since 1.7)
1831 "bps_wr_max: int" (optional)
1833 write throughput limit during bursts, in bytes (Since 1.7)
1834 "iops_max: int" (optional)
1836 total I/O operations per second during bursts, in bytes (Since 1.7)
1837 "iops_rd_max: int" (optional)
1839 read I/O operations per second during bursts, in bytes (Since 1.7)
1840 "iops_wr_max: int" (optional)
1842 write I/O operations per second during bursts, in bytes (Since 1.7)
1843 "bps_max_length: int" (optional)
1845 maximum length of the "bps_max" burst period, in seconds. (Since
1846 2.6)
1847 "bps_rd_max_length: int" (optional)
1849 maximum length of the "bps_rd_max" burst period, in seconds. (Since
1850 2.6)
1851 "bps_wr_max_length: int" (optional)
1853 maximum length of the "bps_wr_max" burst period, in seconds. (Since
1854 2.6)
1855 "iops_max_length: int" (optional)
1857 maximum length of the "iops" burst period, in seconds. (Since 2.6)
1858 "iops_rd_max_length: int" (optional)
1860 maximum length of the "iops_rd_max" burst period, in seconds.
1861 (Since 2.6)
1862 "iops_wr_max_length: int" (optional)
1864 maximum length of the "iops_wr_max" burst period, in seconds.
1865 (Since 2.6)
1866 "iops_size: int" (optional)
1868 an I/O size in bytes (Since 1.7)
1869 "group: string" (optional)
1871 throttle group name (Since 2.4)
1872 "cache: BlockdevCacheInfo"
1874 the cache mode used for the block device (since: 2.3)
1875 "write_threshold: int"
1877 configured write threshold for the device. 0 if disabled. (Since
1878 2.3)
1879 "dirty-bitmaps: array of BlockDirtyInfo" (optional)
1881 dirty bitmaps information (only present if node has one or more
1882 dirty bitmaps) (Since 4.2)
1883 Features:
1885 "deprecated"
1887 Member "encryption_key_missing" is deprecated. It is always false.
1888 Since: 0.14.0
1890 BlockDeviceIoStatus (Enum)
1892 An enumeration of block device I/O status.
1894 Values:
1896 "ok"
1898 The last I/O operation has succeeded
1899 "failed"
1901 The last I/O operation has failed
1902 "nospace"
1904 The last I/O operation has failed due to a no-space condition
1905 Since: 1.0
1907 BlockDeviceMapEntry (Object)
1909 Entry in the metadata map of the device (returned by "qemu-img map")
1911 Members:
1913 "start: int"
1915 Offset in the image of the first byte described by this entry (in
1916 bytes)
1917 "length: int"
1919 Length of the range described by this entry (in bytes)
1920 "depth: int"
1922 Number of layers (0 = top image, 1 = top image's backing file,
1923 etc.) before reaching one for which the range is allocated. The
1924 value is in the range 0 to the depth of the image chain - 1.
1925 "zero: boolean"
1927 the sectors in this range read as zeros
1928 "data: boolean"
1930 reading the image will actually read data from a file (in
1931 particular, if "offset" is present this means that the sectors are
1932 not simply preallocated, but contain actual data in raw format)
1933 "offset: int" (optional)
1935 if present, the image file stores the data for this range in raw
1936 format at the given offset.
1937 Since: 1.7
1939 DirtyBitmapStatus (Enum)
1941 An enumeration of possible states that a dirty bitmap can report to the
1943 user.
1944 Values:
1946 "frozen"
1948 The bitmap is currently in-use by some operation and is immutable.
1949 If the bitmap was "active" prior to the operation, new writes by
1950 the guest are being recorded in a temporary buffer, and will not be
1951 lost. Generally, bitmaps are cleared on successful use in an
1952 operation and the temporary buffer is committed into the bitmap. On
1953 failure, the temporary buffer is merged back into the bitmap
1954 without first clearing it. Please refer to the documentation for
1955 each bitmap-using operation, See also "blockdev-backup",
1956 "drive-backup".
1957 "disabled"
1959 The bitmap is not currently recording new writes by the guest.
1960 This is requested explicitly via "block-dirty-bitmap-disable". It
1961 can still be cleared, deleted, or used for backup operations.
1962 "active"
1964 The bitmap is actively monitoring for new writes, and can be
1965 cleared, deleted, or used for backup operations.
1966 "locked"
1968 The bitmap is currently in-use by some operation and is immutable.
1969 If the bitmap was "active" prior to the operation, it is still
1970 recording new writes. If the bitmap was "disabled", it is not
1971 recording new writes. (Since 2.12)
1972 "inconsistent"
1974 This is a persistent dirty bitmap that was marked in-use on disk,
1975 and is unusable by QEMU. It can only be deleted. Please rely on
1976 the inconsistent field in "BlockDirtyInfo" instead, as the status
1977 field is deprecated. (Since 4.0)
1978 Since: 2.4
1980 BlockDirtyInfo (Object)
1982 Block dirty bitmap information.
1984 Members:
1986 "name: string" (optional)
1988 the name of the dirty bitmap (Since 2.4)
1989 "count: int"
1991 number of dirty bytes according to the dirty bitmap
1992 "granularity: int"
1994 granularity of the dirty bitmap in bytes (since 1.4)
1995 "status: DirtyBitmapStatus"
1997 current status of the dirty bitmap (since 2.4)
1998 "recording: boolean"
2000 true if the bitmap is recording new writes from the guest.
2001 Replaces `active` and `disabled` statuses. (since 4.0)
2002 "busy: boolean"
2004 true if the bitmap is in-use by some operation (NBD or jobs) and
2005 cannot be modified via QMP or used by another operation. Replaces
2006 `locked` and `frozen` statuses. (since 4.0)
2007 "persistent: boolean"
2009 true if the bitmap was stored on disk, is scheduled to be stored on
2010 disk, or both. (since 4.0)
2011 "inconsistent: boolean" (optional)
2013 true if this is a persistent bitmap that was improperly stored.
2014 Implies "persistent" to be true; "recording" and "busy" to be
2015 false. This bitmap cannot be used. To remove it, use
2016 "block-dirty-bitmap-remove". (Since 4.0)
2017 Features:
2019 "deprecated"
2021 Member "status" is deprecated. Use "recording" and "locked"
2022 instead.
2023 Since: 1.3
2025 Qcow2BitmapInfoFlags (Enum)
2027 An enumeration of flags that a bitmap can report to the user.
2029 Values:
2031 "in-use"
2033 This flag is set by any process actively modifying the qcow2 file,
2034 and cleared when the updated bitmap is flushed to the qcow2 image.
2035 The presence of this flag in an offline image means that the bitmap
2036 was not saved correctly after its last usage, and may contain
2037 inconsistent data.
2038 "auto"
2040 The bitmap must reflect all changes of the virtual disk by any
2041 application that would write to this qcow2 file.
2042 Since: 4.0
2044 Qcow2BitmapInfo (Object)
2046 Qcow2 bitmap information.
2048 Members:
2050 "name: string"
2052 the name of the bitmap
2053 "granularity: int"
2055 granularity of the bitmap in bytes
2056 "flags: array of Qcow2BitmapInfoFlags"
2058 flags of the bitmap
2059 Since: 4.0
2061 BlockLatencyHistogramInfo (Object)
2063 Block latency histogram.
2065 Members:
2067 "boundaries: array of int"
2069 list of interval boundary values in nanoseconds, all greater than
2070 zero and in ascending order. For example, the list [10, 50, 100]
2071 produces the following histogram intervals: [0, 10), [10, 50), [50,
2072 100), [100, +inf).
2073 "bins: array of int"
2075 list of io request counts corresponding to histogram intervals.
2076 len("bins") = len("boundaries") + 1 For the example above, "bins"
2077 may be something like [3, 1, 5, 2], and corresponding histogram
2078 looks like:
2079 5| *
2081 4| *
2085 3| B< >
2089 2| B< > *
2093 1| B< > B< >
2097 +------------------
2101 10 50 100
2105 Since: 4.0
2107 BlockInfo (Object)
2109 Block device information. This structure describes a virtual device
2111 and the backing device associated with it.
2112 Members:
2114 "device: string"
2116 The device name associated with the virtual device.
2117 "qdev: string" (optional)
2119 The qdev ID, or if no ID is assigned, the QOM path of the block
2120 device. (since 2.10)
2121 "type: string"
2123 This field is returned only for compatibility reasons, it should
2124 not be used (always returns 'unknown')
2125 "removable: boolean"
2127 True if the device supports removable media.
2128 "locked: boolean"
2130 True if the guest has locked this device from having its media
2131 removed
2132 "tray_open: boolean" (optional)
2134 True if the device's tray is open (only present if it has a tray)
2135 "dirty-bitmaps: array of BlockDirtyInfo" (optional)
2137 dirty bitmaps information (only present if the driver has one or
2138 more dirty bitmaps) (Since 2.0)
2139 "io-status: BlockDeviceIoStatus" (optional)
2141 "BlockDeviceIoStatus". Only present if the device supports it and
2142 the VM is configured to stop on errors (supported device models:
2143 virtio-blk, IDE, SCSI except scsi-generic)
2144 "inserted: BlockDeviceInfo" (optional)
2146 "BlockDeviceInfo" describing the device if media is present
2147 Features:
2149 "deprecated"
2151 Member "dirty-bitmaps" is deprecated. Use "inserted" member
2152 "dirty-bitmaps" instead.
2153 Since: 0.14.0
2155 BlockMeasureInfo (Object)
2157 Image file size calculation information. This structure describes the
2159 size requirements for creating a new image file.
2160 The size requirements depend on the new image file format. File size
2162 always equals virtual disk size for the 'raw' format, even for sparse
2163 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2164 zero regions efficiently so file size may be smaller than virtual disk
2165 size.
2166 The values are upper bounds that are guaranteed to fit the new image
2168 file. Subsequent modification, such as internal snapshot or further
2169 bitmap creation, may require additional space and is not covered here.
2170 Members:
2172 "required: int"
2174 Size required for a new image file, in bytes, when copying just
2175 allocated guest-visible contents.
2176 "fully-allocated: int"
2178 Image file size, in bytes, once data has been written to all
2179 sectors, when copying just guest-visible contents.
2180 "bitmaps: int" (optional)
2182 Additional size required if all the top-level bitmap metadata in
2183 the source image were to be copied to the destination, present only
2184 when source and destination both support persistent bitmaps. (since
2185 5.1)
2186 Since: 2.10
2188 query-block (Command) Get a list of BlockInfo for all virtual block
2190 devices.
2191 Returns: a list of "BlockInfo" describing each virtual block device.
2193 Filter nodes that were created implicitly are skipped over.
2194 Since: 0.14.0
2196 Example:
2198 -> { "execute": "query-block" }
2200 <- {
2201 "return":[
2202 {
2203 "io-status": "ok",
2204 "device":"ide0-hd0",
2205 "locked":false,
2206 "removable":false,
2207 "inserted":{
2208 "ro":false,
2209 "drv":"qcow2",
2210 "encrypted":false,
2211 "file":"disks/test.qcow2",
2212 "backing_file_depth":1,
2213 "bps":1000000,
2214 "bps_rd":0,
2215 "bps_wr":0,
2216 "iops":1000000,
2217 "iops_rd":0,
2218 "iops_wr":0,
2219 "bps_max": 8000000,
2220 "bps_rd_max": 0,
2221 "bps_wr_max": 0,
2222 "iops_max": 0,
2223 "iops_rd_max": 0,
2224 "iops_wr_max": 0,
2225 "iops_size": 0,
2226 "detect_zeroes": "on",
2227 "write_threshold": 0,
2228 "image":{
2229 "filename":"disks/test.qcow2",
2230 "format":"qcow2",
2231 "virtual-size":2048000,
2232 "backing_file":"base.qcow2",
2233 "full-backing-filename":"disks/base.qcow2",
2234 "backing-filename-format":"qcow2",
2235 "snapshots":[
2236 {
2237 "id": "1",
2238 "name": "snapshot1",
2239 "vm-state-size": 0,
2240 "date-sec": 10000200,
2241 "date-nsec": 12,
2242 "vm-clock-sec": 206,
2243 "vm-clock-nsec": 30
2244 }
2245 ],
2246 "backing-image":{
2247 "filename":"disks/base.qcow2",
2248 "format":"qcow2",
2249 "virtual-size":2048000
2250 }
2251 }
2252 },
2253 "qdev": "ide_disk",
2254 "type":"unknown"
2255 },
2256 {
2257 "io-status": "ok",
2258 "device":"ide1-cd0",
2259 "locked":false,
2260 "removable":true,
2261 "qdev": "/machine/unattached/device[23]",
2262 "tray_open": false,
2263 "type":"unknown"
2264 },
2265 {
2266 "device":"floppy0",
2267 "locked":false,
2268 "removable":true,
2269 "qdev": "/machine/unattached/device[20]",
2270 "type":"unknown"
2271 },
2272 {
2273 "device":"sd0",
2274 "locked":false,
2275 "removable":true,
2276 "type":"unknown"
2277 }
2278 ]
2279 }
2280 BlockDeviceTimedStats (Object)
2282 Statistics of a block device during a given interval of time.
2284 Members:
2286 "interval_length: int"
2288 Interval used for calculating the statistics, in seconds.
2289 "min_rd_latency_ns: int"
2291 Minimum latency of read operations in the defined interval, in
2292 nanoseconds.
2293 "min_wr_latency_ns: int"
2295 Minimum latency of write operations in the defined interval, in
2296 nanoseconds.
2297 "min_flush_latency_ns: int"
2299 Minimum latency of flush operations in the defined interval, in
2300 nanoseconds.
2301 "max_rd_latency_ns: int"
2303 Maximum latency of read operations in the defined interval, in
2304 nanoseconds.
2305 "max_wr_latency_ns: int"
2307 Maximum latency of write operations in the defined interval, in
2308 nanoseconds.
2309 "max_flush_latency_ns: int"
2311 Maximum latency of flush operations in the defined interval, in
2312 nanoseconds.
2313 "avg_rd_latency_ns: int"
2315 Average latency of read operations in the defined interval, in
2316 nanoseconds.
2317 "avg_wr_latency_ns: int"
2319 Average latency of write operations in the defined interval, in
2320 nanoseconds.
2321 "avg_flush_latency_ns: int"
2323 Average latency of flush operations in the defined interval, in
2324 nanoseconds.
2325 "avg_rd_queue_depth: number"
2327 Average number of pending read operations in the defined interval.
2328 "avg_wr_queue_depth: number"
2330 Average number of pending write operations in the defined interval.
2331 Since: 2.5
2333 BlockDeviceStats (Object)
2335 Statistics of a virtual block device or a block backing device.
2337 Members:
2339 "rd_bytes: int"
2341 The number of bytes read by the device.
2342 "wr_bytes: int"
2344 The number of bytes written by the device.
2345 "unmap_bytes: int"
2347 The number of bytes unmapped by the device (Since 4.2)
2348 "rd_operations: int"
2350 The number of read operations performed by the device.
2351 "wr_operations: int"
2353 The number of write operations performed by the device.
2354 "flush_operations: int"
2356 The number of cache flush operations performed by the device (since
2357 0.15.0)
2358 "unmap_operations: int"
2360 The number of unmap operations performed by the device (Since 4.2)
2361 "rd_total_time_ns: int"
2363 Total time spent on reads in nanoseconds (since 0.15.0).
2364 "wr_total_time_ns: int"
2366 Total time spent on writes in nanoseconds (since 0.15.0).
2367 "flush_total_time_ns: int"
2369 Total time spent on cache flushes in nanoseconds (since 0.15.0).
2370 "unmap_total_time_ns: int"
2372 Total time spent on unmap operations in nanoseconds (Since 4.2)
2373 "wr_highest_offset: int"
2375 The offset after the greatest byte written to the device. The
2376 intended use of this information is for growable sparse files (like
2377 qcow2) that are used on top of a physical device.
2378 "rd_merged: int"
2380 Number of read requests that have been merged into another request
2381 (Since 2.3).
2382 "wr_merged: int"
2384 Number of write requests that have been merged into another request
2385 (Since 2.3).
2386 "unmap_merged: int"
2388 Number of unmap requests that have been merged into another request
2389 (Since 4.2)
2390 "idle_time_ns: int" (optional)
2392 Time since the last I/O operation, in nanoseconds. If the field is
2393 absent it means that there haven't been any operations yet (Since
2394 2.5).
2395 "failed_rd_operations: int"
2397 The number of failed read operations performed by the device (Since
2398 2.5)
2399 "failed_wr_operations: int"
2401 The number of failed write operations performed by the device
2402 (Since 2.5)
2403 "failed_flush_operations: int"
2405 The number of failed flush operations performed by the device
2406 (Since 2.5)
2407 "failed_unmap_operations: int"
2409 The number of failed unmap operations performed by the device
2410 (Since 4.2)
2411 "invalid_rd_operations: int"
2413 The number of invalid read operations performed by the device
2414 (Since 2.5)
2415 "invalid_wr_operations: int"
2417 The number of invalid write operations performed by the device
2418 (Since 2.5)
2419 "invalid_flush_operations: int"
2421 The number of invalid flush operations performed by the device
2422 (Since 2.5)
2423 "invalid_unmap_operations: int"
2425 The number of invalid unmap operations performed by the device
2426 (Since 4.2)
2427 "account_invalid: boolean"
2429 Whether invalid operations are included in the last access
2430 statistics (Since 2.5)
2431 "account_failed: boolean"
2433 Whether failed operations are included in the latency and last
2434 access statistics (Since 2.5)
2435 "timed_stats: array of BlockDeviceTimedStats"
2437 Statistics specific to the set of previously defined intervals of
2438 time (Since 2.5)
2439 "rd_latency_histogram: BlockLatencyHistogramInfo" (optional)
2441 "BlockLatencyHistogramInfo". (Since 4.0)
2442 "wr_latency_histogram: BlockLatencyHistogramInfo" (optional)
2444 "BlockLatencyHistogramInfo". (Since 4.0)
2445 "flush_latency_histogram: BlockLatencyHistogramInfo" (optional)
2447 "BlockLatencyHistogramInfo". (Since 4.0)
2448 Since: 0.14.0
2450 BlockStatsSpecificFile (Object)
2452 File driver statistics
2454 Members:
2456 "discard-nb-ok: int"
2458 The number of successful discard operations performed by the
2459 driver.
2460 "discard-nb-failed: int"
2462 The number of failed discard operations performed by the driver.
2463 "discard-bytes-ok: int"
2465 The number of bytes discarded by the driver.
2466 Since: 4.2
2468 BlockStatsSpecific (Object)
2470 Block driver specific statistics
2472 Members:
2474 "driver: BlockdevDriver"
2476 Not documented
2477 The members of "BlockStatsSpecificFile" when "driver" is "file"
2479 The members of "BlockStatsSpecificFile" when "driver" is "host_device"
2480 Since: 4.2
2482 BlockStats (Object)
2484 Statistics of a virtual block device or a block backing device.
2486 Members:
2488 "device: string" (optional)
2490 If the stats are for a virtual block device, the name corresponding
2491 to the virtual block device.
2492 "node-name: string" (optional)
2494 The node name of the device. (Since 2.3)
2495 "qdev: string" (optional)
2497 The qdev ID, or if no ID is assigned, the QOM path of the block
2498 device. (since 3.0)
2499 "stats: BlockDeviceStats"
2501 A "BlockDeviceStats" for the device.
2502 "driver-specific: BlockStatsSpecific" (optional)
2504 Optional driver-specific stats. (Since 4.2)
2505 "parent: BlockStats" (optional)
2507 This describes the file block device if it has one. Contains
2508 recursively the statistics of the underlying protocol (e.g. the
2509 host file for a qcow2 image). If there is no underlying protocol,
2510 this field is omitted
2511 "backing: BlockStats" (optional)
2513 This describes the backing block device if it has one. (Since 2.0)
2514 Since: 0.14.0
2516 query-blockstats (Command) Query the "BlockStats" for all virtual
2518 block devices.
2519 Arguments:
2521 "query-nodes: boolean" (optional)
2523 If true, the command will query all the block nodes that have a
2524 node name, in a list which will include "parent" information, but
2525 not "backing". If false or omitted, the behavior is as before -
2526 query all the device backends, recursively including their "parent"
2527 and "backing". Filter nodes that were created implicitly are
2528 skipped over in this mode. (Since 2.3)
2529 Returns: A list of "BlockStats" for each virtual block devices.
2531 Since: 0.14.0
2533 Example:
2535 -> { "execute": "query-blockstats" }
2537 <- {
2538 "return":[
2539 {
2540 "device":"ide0-hd0",
2541 "parent":{
2542 "stats":{
2543 "wr_highest_offset":3686448128,
2544 "wr_bytes":9786368,
2545 "wr_operations":751,
2546 "rd_bytes":122567168,
2547 "rd_operations":36772
2548 "wr_total_times_ns":313253456
2549 "rd_total_times_ns":3465673657
2550 "flush_total_times_ns":49653
2551 "flush_operations":61,
2552 "rd_merged":0,
2553 "wr_merged":0,
2554 "idle_time_ns":2953431879,
2555 "account_invalid":true,
2556 "account_failed":false
2557 }
2558 },
2559 "stats":{
2560 "wr_highest_offset":2821110784,
2561 "wr_bytes":9786368,
2562 "wr_operations":692,
2563 "rd_bytes":122739200,
2564 "rd_operations":36604
2565 "flush_operations":51,
2566 "wr_total_times_ns":313253456
2567 "rd_total_times_ns":3465673657
2568 "flush_total_times_ns":49653,
2569 "rd_merged":0,
2570 "wr_merged":0,
2571 "idle_time_ns":2953431879,
2572 "account_invalid":true,
2573 "account_failed":false
2574 },
2575 "qdev": "/machine/unattached/device[23]"
2576 },
2577 {
2578 "device":"ide1-cd0",
2579 "stats":{
2580 "wr_highest_offset":0,
2581 "wr_bytes":0,
2582 "wr_operations":0,
2583 "rd_bytes":0,
2584 "rd_operations":0
2585 "flush_operations":0,
2586 "wr_total_times_ns":0
2587 "rd_total_times_ns":0
2588 "flush_total_times_ns":0,
2589 "rd_merged":0,
2590 "wr_merged":0,
2591 "account_invalid":false,
2592 "account_failed":false
2593 },
2594 "qdev": "/machine/unattached/device[24]"
2595 },
2596 {
2597 "device":"floppy0",
2598 "stats":{
2599 "wr_highest_offset":0,
2600 "wr_bytes":0,
2601 "wr_operations":0,
2602 "rd_bytes":0,
2603 "rd_operations":0
2604 "flush_operations":0,
2605 "wr_total_times_ns":0
2606 "rd_total_times_ns":0
2607 "flush_total_times_ns":0,
2608 "rd_merged":0,
2609 "wr_merged":0,
2610 "account_invalid":false,
2611 "account_failed":false
2612 },
2613 "qdev": "/machine/unattached/device[16]"
2614 },
2615 {
2616 "device":"sd0",
2617 "stats":{
2618 "wr_highest_offset":0,
2619 "wr_bytes":0,
2620 "wr_operations":0,
2621 "rd_bytes":0,
2622 "rd_operations":0
2623 "flush_operations":0,
2624 "wr_total_times_ns":0
2625 "rd_total_times_ns":0
2626 "flush_total_times_ns":0,
2627 "rd_merged":0,
2628 "wr_merged":0,
2629 "account_invalid":false,
2630 "account_failed":false
2631 }
2632 }
2633 ]
2634 }
2635 BlockdevOnError (Enum)
2637 An enumeration of possible behaviors for errors on I/O operations. The
2639 exact meaning depends on whether the I/O was initiated by a guest or by
2640 a block job
2641 Values:
2643 "report"
2645 for guest operations, report the error to the guest; for jobs,
2646 cancel the job
2647 "ignore"
2649 ignore the error, only report a QMP event (BLOCK_IO_ERROR or
2650 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
2651 the failing request later and may still complete successfully. The
2652 stream block job continues to stream and will complete with an
2653 error.
2654 "enospc"
2656 same as "stop" on ENOSPC, same as "report" otherwise.
2657 "stop"
2659 for guest operations, stop the virtual machine; for jobs, pause the
2660 job
2661 "auto"
2663 inherit the error handling policy of the backend (since: 2.7)
2664 Since: 1.3
2666 MirrorSyncMode (Enum)
2668 An enumeration of possible behaviors for the initial synchronization
2670 phase of storage mirroring.
2671 Values:
2673 "top"
2675 copies data in the topmost image to the destination
2676 "full"
2678 copies data from all images to the destination
2679 "none"
2681 only copy data written from now on
2682 "incremental"
2684 only copy data described by the dirty bitmap. (since: 2.4)
2685 "bitmap"
2687 only copy data described by the dirty bitmap. (since: 4.2) Behavior
2688 on completion is determined by the BitmapSyncMode.
2689 Since: 1.3
2691 BitmapSyncMode (Enum)
2693 An enumeration of possible behaviors for the synchronization of a
2695 bitmap when used for data copy operations.
2696 Values:
2698 "on-success"
2700 The bitmap is only synced when the operation is successful. This
2701 is the behavior always used for 'INCREMENTAL' backups.
2702 "never"
2704 The bitmap is never synchronized with the operation, and is treated
2705 solely as a read-only manifest of blocks to copy.
2706 "always"
2708 The bitmap is always synchronized with the operation, regardless of
2709 whether or not the operation was successful.
2710 Since: 4.2
2712 MirrorCopyMode (Enum)
2714 An enumeration whose values tell the mirror block job when to trigger
2716 writes to the target.
2717 Values:
2719 "background"
2721 copy data in background only.
2722 "write-blocking"
2724 when data is written to the source, write it (synchronously) to the
2725 target as well. In addition, data is copied in background just
2726 like in "background" mode.
2727 Since: 3.0
2729 BlockJobInfo (Object)
2731 Information about a long-running block device operation.
2733 Members:
2735 "type: string"
2737 the job type ('stream' for image streaming)
2738 "device: string"
2740 The job identifier. Originally the device name but other values are
2741 allowed since QEMU 2.7
2742 "len: int"
2744 Estimated "offset" value at the completion of the job. This value
2745 can arbitrarily change while the job is running, in both
2746 directions.
2747 "offset: int"
2749 Progress made until now. The unit is arbitrary and the value can
2750 only meaningfully be used for the ratio of "offset" to "len". The
2751 value is monotonically increasing.
2752 "busy: boolean"
2754 false if the job is known to be in a quiescent state, with no
2755 pending I/O. Since 1.3.
2756 "paused: boolean"
2758 whether the job is paused or, if "busy" is true, will pause itself
2759 as soon as possible. Since 1.3.
2760 "speed: int"
2762 the rate limit, bytes per second
2763 "io-status: BlockDeviceIoStatus"
2765 the status of the job (since 1.3)
2766 "ready: boolean"
2768 true if the job may be completed (since 2.2)
2769 "status: JobStatus"
2771 Current job state/status (since 2.12)
2772 "auto-finalize: boolean"
2774 Job will finalize itself when PENDING, moving to the CONCLUDED
2775 state. (since 2.12)
2776 "auto-dismiss: boolean"
2778 Job will dismiss itself when CONCLUDED, moving to the NULL state
2779 and disappearing from the query list. (since 2.12)
2780 "error: string" (optional)
2782 Error information if the job did not complete successfully. Not
2783 set if the job completed successfully. (since 2.12.1)
2784 Since: 1.1
2786 query-block-jobs (Command) Return information about long-running block
2788 device operations.
2789 Returns: a list of "BlockJobInfo" for each active block job
2791 Since: 1.1
2793 block_passwd (Command) This command sets the password of a block
2795 device that has not been open with a password and requires one.
2796 This command is now obsolete and will always return an error since 2.10
2798 Arguments:
2800 "device: string" (optional)
2802 Not documented
2803 "node-name: string" (optional)
2805 Not documented
2806 "password: string"
2808 Not documented
2809 block_resize (Command) Resize a block image while a guest is running.
2811 Either "device" or "node-name" must be set but not both.
2813 Arguments:
2815 "device: string" (optional)
2817 the name of the device to get the image resized
2818 "node-name: string" (optional)
2820 graph node name to get the image resized (Since 2.0)
2821 "size: int"
2823 new image size in bytes
2824 Returns:
2826 - nothing on success
2828 - If "device" is not a valid block device, DeviceNotFound
2830 Since: 0.14.0
2832 Example:
2834 -> { "execute": "block_resize",
2836 "arguments": { "device": "scratch", "size": 1073741824 } }
2837 <- { "return": {} }
2838 NewImageMode (Enum)
2840 An enumeration that tells QEMU how to set the backing file path in a
2842 new image file.
2843 Values:
2845 "existing"
2847 QEMU should look for an existing image file.
2848 "absolute-paths"
2850 QEMU should create a new image with absolute paths for the backing
2851 file. If there is no backing file available, the new image will not
2852 be backed either.
2853 Since: 1.1
2855 BlockdevSnapshotSync (Object)
2857 Either "device" or "node-name" must be set but not both.
2859 Members:
2861 "device: string" (optional)
2863 the name of the device to take a snapshot of.
2864 "node-name: string" (optional)
2866 graph node name to generate the snapshot from (Since 2.0)
2867 "snapshot-file: string"
2869 the target of the new overlay image. If the file exists, or if it
2870 is a device, the overlay will be created in the existing
2871 file/device. Otherwise, a new file will be created.
2872 "snapshot-node-name: string" (optional)
2874 the graph node name of the new image (Since 2.0)
2875 "format: string" (optional)
2877 the format of the overlay image, default is 'qcow2'.
2878 "mode: NewImageMode" (optional)
2880 whether and how QEMU should create a new image, default is
2881 'absolute-paths'.
2882 BlockdevSnapshot (Object)
2884 Members:
2886 "node: string"
2888 device or node name that will have a snapshot taken.
2889 "overlay: string"
2891 reference to the existing block device that will become the overlay
2892 of "node", as part of taking the snapshot. It must not have a
2893 current backing file (this can be achieved by passing "backing":
2894 null to blockdev-add).
2895 Since: 2.5
2897 BackupCommon (Object)
2899 Members:
2901 "job-id: string" (optional)
2903 identifier for the newly-created block job. If omitted, the device
2904 name will be used. (Since 2.7)
2905 "device: string"
2907 the device name or node-name of a root node which should be copied.
2908 "sync: MirrorSyncMode"
2910 what parts of the disk image should be copied to the destination
2911 (all the disk, only the sectors allocated in the topmost image,
2912 from a dirty bitmap, or only new I/O).
2913 "speed: int" (optional)
2915 the maximum speed, in bytes per second. The default is 0, for
2916 unlimited.
2917 "bitmap: string" (optional)
2919 The name of a dirty bitmap to use. Must be present if sync is
2920 "bitmap" or "incremental". Can be present if sync is "full" or
2921 "top". Must not be present otherwise. (Since 2.4 (drive-backup),
2922 3.1 (blockdev-backup))
2923 "bitmap-mode: BitmapSyncMode" (optional)
2925 Specifies the type of data the bitmap should contain after the
2926 operation concludes. Must be present if a bitmap was provided,
2927 Must NOT be present otherwise. (Since 4.2)
2928 "compress: boolean" (optional)
2930 true to compress data, if the target format supports it. (default:
2931 false) (since 2.8)
2932 "on-source-error: BlockdevOnError" (optional)
2934 the action to take on an error on the source, default 'report'.
2935 'stop' and 'enospc' can only be used if the block device supports
2936 io-status (see BlockInfo).
2937 "on-target-error: BlockdevOnError" (optional)
2939 the action to take on an error on the target, default 'report' (no
2940 limitations, since this applies to a different block device than
2941 "device").
2942 "auto-finalize: boolean" (optional)
2944 When false, this job will wait in a PENDING state after it has
2945 finished its work, waiting for "block-job-finalize" before making
2946 any block graph changes. When true, this job will automatically
2947 perform its abort or commit actions. Defaults to true. (Since
2948 2.12)
2949 "auto-dismiss: boolean" (optional)
2951 When false, this job will wait in a CONCLUDED state after it has
2952 completely ceased all work, and awaits "block-job-dismiss". When
2953 true, this job will automatically disappear from the query list
2954 without user intervention. Defaults to true. (Since 2.12)
2955 "filter-node-name: string" (optional)
2957 the node name that should be assigned to the filter driver that the
2958 backup job inserts into the graph above node specified by "drive".
2959 If this option is not given, a node name is autogenerated. (Since:
2960 4.2)
2961 Note: "on-source-error" and "on-target-error" only affect background
2963 I/O. If an error occurs during a guest write request, the device's
2964 rerror/werror actions will be used.
2965 Since: 4.2
2967 DriveBackup (Object)
2969 Members:
2971 "target: string"
2973 the target of the new image. If the file exists, or if it is a
2974 device, the existing file/device will be used as the new
2975 destination. If it does not exist, a new file will be created.
2976 "format: string" (optional)
2978 the format of the new destination, default is to probe if "mode" is
2979 'existing', else the format of the source
2980 "mode: NewImageMode" (optional)
2982 whether and how QEMU should create a new image, default is
2983 'absolute-paths'.
2984 The members of "BackupCommon"
2986 Since: 1.6
2988 BlockdevBackup (Object)
2990 Members:
2992 "target: string"
2994 the device name or node-name of the backup target node.
2995 The members of "BackupCommon"
2997 Since: 2.3
2999 blockdev-snapshot-sync (Command) Takes a synchronous snapshot of a
3001 block device.
3002 For the arguments, see the documentation of BlockdevSnapshotSync.
3004 Returns:
3006 - nothing on success
3008 - If "device" is not a valid block device, DeviceNotFound
3010 Since: 0.14.0
3012 Example:
3014 -> { "execute": "blockdev-snapshot-sync",
3016 "arguments": { "device": "ide-hd0",
3017 "snapshot-file":
3018 "/some/place/my-image",
3019 "format": "qcow2" } }
3020 <- { "return": {} }
3021 blockdev-snapshot (Command) Takes a snapshot of a block device.
3023 Take a snapshot, by installing 'node' as the backing image of
3025 'overlay'. Additionally, if 'node' is associated with a block device,
3026 the block device changes to using 'overlay' as its new active image.
3027 For the arguments, see the documentation of BlockdevSnapshot.
3029 Features:
3031 "allow-write-only-overlay"
3033 If present, the check whether this operation is safe was relaxed so
3034 that it can be used to change backing file of a destination of a
3035 blockdev-mirror. (since 5.0)
3036 Since: 2.5
3038 Example:
3040 -> { "execute": "blockdev-add",
3042 "arguments": { "driver": "qcow2",
3043 "node-name": "node1534",
3044 "file": { "driver": "file",
3045 "filename": "hd1.qcow2" },
3046 "backing": null } }
3047 <- { "return": {} }
3049 -> { "execute": "blockdev-snapshot",
3051 "arguments": { "node": "ide-hd0",
3052 "overlay": "node1534" } }
3053 <- { "return": {} }
3054 change-backing-file (Command) Change the backing file in the image
3056 file metadata. This does not cause QEMU to reopen the image file to
3057 reparse the backing filename (it may, however, perform a reopen to
3058 change permissions from r/o -> r/w -> r/o, if needed). The new backing
3059 file string is written into the image file metadata, and the QEMU
3060 internal strings are updated.
3061 Arguments:
3063 "image-node-name: string"
3065 The name of the block driver state node of the image to modify. The
3066 "device" argument is used to verify "image-node-name" is in the
3067 chain described by "device".
3068 "device: string"
3070 The device name or node-name of the root node that owns image-node-
3071 name.
3072 "backing-file: string"
3074 The string to write as the backing file. This string is not
3075 validated, so care should be taken when specifying the string or
3076 the image chain may not be able to be reopened again.
3077 Returns:
3079 - Nothing on success
3081 - If "device" does not exist or cannot be determined, DeviceNotFound
3083 Since: 2.1
3085 block-commit (Command) Live commit of data from overlay image nodes
3087 into backing nodes - i.e., writes data between 'top' and 'base' into
3088 'base'.
3089 Arguments:
3091 "job-id: string" (optional)
3093 identifier for the newly-created block job. If omitted, the device
3094 name will be used. (Since 2.7)
3095 "device: string"
3097 the device name or node-name of a root node
3098 "base-node: string" (optional)
3100 The node name of the backing image to write data into. If not
3101 specified, this is the deepest backing image. (since: 3.1)
3102 "base: string" (optional)
3104 Same as "base-node", except that it is a file name rather than a
3105 node name. This must be the exact filename string that was used to
3106 open the node; other strings, even if addressing the same file, are
3107 not accepted
3108 "top-node: string" (optional)
3110 The node name of the backing image within the image chain which
3111 contains the topmost data to be committed down. If not specified,
3112 this is the active layer. (since: 3.1)
3113 "top: string" (optional)
3115 Same as "top-node", except that it is a file name rather than a
3116 node name. This must be the exact filename string that was used to
3117 open the node; other strings, even if addressing the same file, are
3118 not accepted
3119 "backing-file: string" (optional)
3121 The backing file string to write into the overlay image of 'top'.
3122 If 'top' is the active layer, specifying a backing file string is
3123 an error. This filename is not validated.
3124 If a pathname string is such that it cannot be resolved by QEMU,
3126 that means that subsequent QMP or HMP commands must use node-names
3127 for the image in question, as filename lookup methods will fail.
3128 If not specified, QEMU will automatically determine the backing
3130 file string to use, or error out if there is no obvious choice.
3131 Care should be taken when specifying the string, to specify a valid
3132 filename or protocol. (Since 2.1)
3133 If top == base, that is an error. If top == active, the job will
3135 not be completed by itself, user needs to complete the job with the
3136 block-job-complete command after getting the ready event. (Since
3137 2.0)
3138 If the base image is smaller than top, then the base image will be
3140 resized to be the same size as top. If top is smaller than the
3141 base image, the base will not be truncated. If you want the base
3142 image size to match the size of the smaller top, you can safely
3143 truncate it yourself once the commit operation successfully
3144 completes.
3145 "speed: int" (optional)
3147 the maximum speed, in bytes per second
3148 "on-error: BlockdevOnError" (optional)
3150 the action to take on an error. 'ignore' means that the request
3151 should be retried. (default: report; Since: 5.0)
3152 "filter-node-name: string" (optional)
3154 the node name that should be assigned to the filter driver that the
3155 commit job inserts into the graph above "top". If this option is
3156 not given, a node name is autogenerated. (Since: 2.9)
3157 "auto-finalize: boolean" (optional)
3159 When false, this job will wait in a PENDING state after it has
3160 finished its work, waiting for "block-job-finalize" before making
3161 any block graph changes. When true, this job will automatically
3162 perform its abort or commit actions. Defaults to true. (Since 3.1)
3163 "auto-dismiss: boolean" (optional)
3165 When false, this job will wait in a CONCLUDED state after it has
3166 completely ceased all work, and awaits "block-job-dismiss". When
3167 true, this job will automatically disappear from the query list
3168 without user intervention. Defaults to true. (Since 3.1)
3169 Features:
3171 "deprecated"
3173 Members "base" and "top" are deprecated. Use "base-node" and
3174 "top-node" instead.
3175 Returns:
3177 - Nothing on success
3179 - If "device" does not exist, DeviceNotFound
3181 - Any other error returns a GenericError.
3183 Since: 1.3
3185 Example:
3187 -> { "execute": "block-commit",
3189 "arguments": { "device": "virtio0",
3190 "top": "/tmp/snap1.qcow2" } }
3191 <- { "return": {} }
3192 drive-backup (Command) Start a point-in-time copy of a block device to
3194 a new destination. The status of ongoing drive-backup operations can
3195 be checked with query-block-jobs where the BlockJobInfo.type field has
3196 the value 'backup'. The operation can be stopped before it has
3197 completed using the block-job-cancel command.
3198 Arguments: the members of "DriveBackup"
3200 Returns:
3202 - nothing on success
3204 - If "device" is not a valid block device, GenericError
3206 Since: 1.6
3208 Example:
3210 -> { "execute": "drive-backup",
3212 "arguments": { "device": "drive0",
3213 "sync": "full",
3214 "target": "backup.img" } }
3215 <- { "return": {} }
3216 blockdev-backup (Command) Start a point-in-time copy of a block device
3218 to a new destination. The status of ongoing blockdev-backup operations
3219 can be checked with query-block-jobs where the BlockJobInfo.type field
3220 has the value 'backup'. The operation can be stopped before it has
3221 completed using the block-job-cancel command.
3222 Arguments: the members of "BlockdevBackup"
3224 Returns:
3226 - nothing on success
3228 - If "device" is not a valid block device, DeviceNotFound
3230 Since: 2.3
3232 Example:
3234 -> { "execute": "blockdev-backup",
3236 "arguments": { "device": "src-id",
3237 "sync": "full",
3238 "target": "tgt-id" } }
3239 <- { "return": {} }
3240 query-named-block-nodes (Command) Get the named block driver list
3242 Arguments:
3244 "flat: boolean" (optional)
3246 Omit the nested data about backing image ("backing-image" key) if
3247 true. Default is false (Since 5.0)
3248 Returns: the list of BlockDeviceInfo
3250 Since: 2.0
3252 Example:
3254 -> { "execute": "query-named-block-nodes" }
3256 <- { "return": [ { "ro":false,
3257 "drv":"qcow2",
3258 "encrypted":false,
3259 "file":"disks/test.qcow2",
3260 "node-name": "my-node",
3261 "backing_file_depth":1,
3262 "bps":1000000,
3263 "bps_rd":0,
3264 "bps_wr":0,
3265 "iops":1000000,
3266 "iops_rd":0,
3267 "iops_wr":0,
3268 "bps_max": 8000000,
3269 "bps_rd_max": 0,
3270 "bps_wr_max": 0,
3271 "iops_max": 0,
3272 "iops_rd_max": 0,
3273 "iops_wr_max": 0,
3274 "iops_size": 0,
3275 "write_threshold": 0,
3276 "image":{
3277 "filename":"disks/test.qcow2",
3278 "format":"qcow2",
3279 "virtual-size":2048000,
3280 "backing_file":"base.qcow2",
3281 "full-backing-filename":"disks/base.qcow2",
3282 "backing-filename-format":"qcow2",
3283 "snapshots":[
3284 {
3285 "id": "1",
3286 "name": "snapshot1",
3287 "vm-state-size": 0,
3288 "date-sec": 10000200,
3289 "date-nsec": 12,
3290 "vm-clock-sec": 206,
3291 "vm-clock-nsec": 30
3292 }
3293 ],
3294 "backing-image":{
3295 "filename":"disks/base.qcow2",
3296 "format":"qcow2",
3297 "virtual-size":2048000
3298 }
3299 } } ] }
3300 XDbgBlockGraphNodeType (Enum)
3302 Values:
3304 "block-backend"
3306 corresponds to BlockBackend
3307 "block-job"
3309 corresonds to BlockJob
3310 "block-driver"
3312 corresponds to BlockDriverState
3313 Since: 4.0
3315 XDbgBlockGraphNode (Object)
3317 Members:
3319 "id: int"
3321 Block graph node identifier. This "id" is generated only for
3322 x-debug-query-block-graph and does not relate to any other
3323 identifiers in Qemu.
3324 "type: XDbgBlockGraphNodeType"
3326 Type of graph node. Can be one of block-backend, block-job or
3327 block-driver-state.
3328 "name: string"
3330 Human readable name of the node. Corresponds to node-name for
3331 block-driver-state nodes; is not guaranteed to be unique in the
3332 whole graph (with block-jobs and block-backends).
3333 Since: 4.0
3335 BlockPermission (Enum)
3337 Enum of base block permissions.
3339 Values:
3341 "consistent-read"
3343 A user that has the "permission" of consistent reads is guaranteed
3344 that their view of the contents of the block device is complete and
3345 self-consistent, representing the contents of a disk at a specific
3346 point. For most block devices (including their backing files) this
3347 is true, but the property cannot be maintained in a few situations
3348 like for intermediate nodes of a commit block job.
3349 "write"
3351 This permission is required to change the visible disk contents.
3352 "write-unchanged"
3354 This permission (which is weaker than BLK_PERM_WRITE) is both
3355 enough and required for writes to the block node when the caller
3356 promises that the visible disk content doesn't change. As the
3357 BLK_PERM_WRITE permission is strictly stronger, either is
3358 sufficient to perform an unchanging write.
3359 "resize"
3361 This permission is required to change the size of a block node.
3362 "graph-mod"
3364 This permission is required to change the node that this BdrvChild
3365 points to.
3366 Since: 4.0
3368 XDbgBlockGraphEdge (Object)
3370 Block Graph edge description for x-debug-query-block-graph.
3372 Members:
3374 "parent: int"
3376 parent id
3377 "child: int"
3379 child id
3380 "name: string"
3382 name of the relation (examples are 'file' and 'backing')
3383 "perm: array of BlockPermission"
3385 granted permissions for the parent operating on the child
3386 "shared-perm: array of BlockPermission"
3388 permissions that can still be granted to other users of the child
3389 while it is still attached to this parent
3390 Since: 4.0
3392 XDbgBlockGraph (Object)
3394 Block Graph - list of nodes and list of edges.
3396 Members:
3398 "nodes: array of XDbgBlockGraphNode"
3400 Not documented
3401 "edges: array of XDbgBlockGraphEdge"
3403 Not documented
3404 Since: 4.0
3406 x-debug-query-block-graph (Command) Get the block graph.
3408 Since: 4.0
3410 drive-mirror (Command) Start mirroring a block device's writes to a
3412 new destination. target specifies the target of the new image. If the
3413 file exists, or if it is a device, it will be used as the new
3414 destination for writes. If it does not exist, a new file will be
3415 created. format specifies the format of the mirror image, default is to
3416 probe if mode='existing', else the format of the source.
3417 Arguments: the members of "DriveMirror"
3419 Returns:
3421 - nothing on success
3423 - If "device" is not a valid block device, GenericError
3425 Since: 1.3
3427 Example:
3429 -> { "execute": "drive-mirror",
3431 "arguments": { "device": "ide-hd0",
3432 "target": "/some/place/my-image",
3433 "sync": "full",
3434 "format": "qcow2" } }
3435 <- { "return": {} }
3436 DriveMirror (Object)
3438 A set of parameters describing drive mirror setup.
3440 Members:
3442 "job-id: string" (optional)
3444 identifier for the newly-created block job. If omitted, the device
3445 name will be used. (Since 2.7)
3446 "device: string"
3448 the device name or node-name of a root node whose writes should be
3449 mirrored.
3450 "target: string"
3452 the target of the new image. If the file exists, or if it is a
3453 device, the existing file/device will be used as the new
3454 destination. If it does not exist, a new file will be created.
3455 "format: string" (optional)
3457 the format of the new destination, default is to probe if "mode" is
3458 'existing', else the format of the source
3459 "node-name: string" (optional)
3461 the new block driver state node name in the graph (Since 2.1)
3462 "replaces: string" (optional)
3464 with sync=full graph node name to be replaced by the new image when
3465 a whole image copy is done. This can be used to repair broken
3466 Quorum files. (Since 2.1)
3467 "mode: NewImageMode" (optional)
3469 whether and how QEMU should create a new image, default is
3470 'absolute-paths'.
3471 "speed: int" (optional)
3473 the maximum speed, in bytes per second
3474 "sync: MirrorSyncMode"
3476 what parts of the disk image should be copied to the destination
3477 (all the disk, only the sectors allocated in the topmost image, or
3478 only new I/O).
3479 "granularity: int" (optional)
3481 granularity of the dirty bitmap, default is 64K if the image format
3482 doesn't have clusters, 4K if the clusters are smaller than that,
3483 else the cluster size. Must be a power of 2 between 512 and 64M
3484 (since 1.4).
3485 "buf-size: int" (optional)
3487 maximum amount of data in flight from source to target (since 1.4).
3488 "on-source-error: BlockdevOnError" (optional)
3490 the action to take on an error on the source, default 'report'.
3491 'stop' and 'enospc' can only be used if the block device supports
3492 io-status (see BlockInfo).
3493 "on-target-error: BlockdevOnError" (optional)
3495 the action to take on an error on the target, default 'report' (no
3496 limitations, since this applies to a different block device than
3497 "device").
3498 "unmap: boolean" (optional)
3500 Whether to try to unmap target sectors where source has only zero.
3501 If true, and target unallocated sectors will read as zero, target
3502 image sectors will be unmapped; otherwise, zeroes will be written.
3503 Both will result in identical contents. Default is true. (Since
3504 2.4)
3505 "copy-mode: MirrorCopyMode" (optional)
3507 when to copy data to the destination; defaults to 'background'
3508 (Since: 3.0)
3509 "auto-finalize: boolean" (optional)
3511 When false, this job will wait in a PENDING state after it has
3512 finished its work, waiting for "block-job-finalize" before making
3513 any block graph changes. When true, this job will automatically
3514 perform its abort or commit actions. Defaults to true. (Since 3.1)
3515 "auto-dismiss: boolean" (optional)
3517 When false, this job will wait in a CONCLUDED state after it has
3518 completely ceased all work, and awaits "block-job-dismiss". When
3519 true, this job will automatically disappear from the query list
3520 without user intervention. Defaults to true. (Since 3.1)
3521 Since: 1.3
3523 BlockDirtyBitmap (Object)
3525 Members:
3527 "node: string"
3529 name of device/node which the bitmap is tracking
3530 "name: string"
3532 name of the dirty bitmap
3533 Since: 2.4
3535 BlockDirtyBitmapAdd (Object)
3537 Members:
3539 "node: string"
3541 name of device/node which the bitmap is tracking
3542 "name: string"
3544 name of the dirty bitmap (must be less than 1024 bytes)
3545 "granularity: int" (optional)
3547 the bitmap granularity, default is 64k for block-dirty-bitmap-add
3548 "persistent: boolean" (optional)
3550 the bitmap is persistent, i.e. it will be saved to the
3551 corresponding block device image file on its close. For now only
3552 Qcow2 disks support persistent bitmaps. Default is false for block-
3553 dirty-bitmap-add. (Since: 2.10)
3554 "disabled: boolean" (optional)
3556 the bitmap is created in the disabled state, which means that it
3557 will not track drive changes. The bitmap may be enabled with block-
3558 dirty-bitmap-enable. Default is false. (Since: 4.0)
3559 Since: 2.4
3561 BlockDirtyBitmapMergeSource (Alternate)
3563 Members:
3565 "local: string"
3567 name of the bitmap, attached to the same node as target bitmap.
3568 "external: BlockDirtyBitmap"
3570 bitmap with specified node
3571 Since: 4.1
3573 BlockDirtyBitmapMerge (Object)
3575 Members:
3577 "node: string"
3579 name of device/node which the "target" bitmap is tracking
3580 "target: string"
3582 name of the destination dirty bitmap
3583 "bitmaps: array of BlockDirtyBitmapMergeSource"
3585 name(s) of the source dirty bitmap(s) at "node" and/or fully
3586 specifed BlockDirtyBitmap elements. The latter are supported since
3587 4.1.
3588 Since: 4.0
3590 block-dirty-bitmap-add (Command) Create a dirty bitmap with a name on
3592 the node, and start tracking the writes.
3593 Returns:
3595 - nothing on success
3597 - If "node" is not a valid block device or node, DeviceNotFound
3599 - If "name" is already taken, GenericError with an explanation
3601 Since: 2.4
3603 Example:
3605 -> { "execute": "block-dirty-bitmap-add",
3607 "arguments": { "node": "drive0", "name": "bitmap0" } }
3608 <- { "return": {} }
3609 block-dirty-bitmap-remove (Command) Stop write tracking and remove the
3611 dirty bitmap that was created with block-dirty-bitmap-add. If the
3612 bitmap is persistent, remove it from its storage too.
3613 Returns:
3615 - nothing on success
3617 - If "node" is not a valid block device or node, DeviceNotFound
3619 - If "name" is not found, GenericError with an explanation
3621 - if "name" is frozen by an operation, GenericError
3623 Since: 2.4
3625 Example:
3627 -> { "execute": "block-dirty-bitmap-remove",
3629 "arguments": { "node": "drive0", "name": "bitmap0" } }
3630 <- { "return": {} }
3631 block-dirty-bitmap-clear (Command) Clear (reset) a dirty bitmap on the
3633 device, so that an incremental backup from this point in time forward
3634 will only backup clusters modified after this clear operation.
3635 Returns:
3637 - nothing on success
3639 - If "node" is not a valid block device, DeviceNotFound
3641 - If "name" is not found, GenericError with an explanation
3643 Since: 2.4
3645 Example:
3647 -> { "execute": "block-dirty-bitmap-clear",
3649 "arguments": { "node": "drive0", "name": "bitmap0" } }
3650 <- { "return": {} }
3651 block-dirty-bitmap-enable (Command) Enables a dirty bitmap so that it
3653 will begin tracking disk changes.
3654 Returns:
3656 - nothing on success
3658 - If "node" is not a valid block device, DeviceNotFound
3660 - If "name" is not found, GenericError with an explanation
3662 Since: 4.0
3664 Example:
3666 -> { "execute": "block-dirty-bitmap-enable",
3668 "arguments": { "node": "drive0", "name": "bitmap0" } }
3669 <- { "return": {} }
3670 block-dirty-bitmap-disable (Command) Disables a dirty bitmap so that
3672 it will stop tracking disk changes.
3673 Returns:
3675 - nothing on success
3677 - If "node" is not a valid block device, DeviceNotFound
3679 - If "name" is not found, GenericError with an explanation
3681 Since: 4.0
3683 Example:
3685 -> { "execute": "block-dirty-bitmap-disable",
3687 "arguments": { "node": "drive0", "name": "bitmap0" } }
3688 <- { "return": {} }
3689 block-dirty-bitmap-merge (Command) Merge dirty bitmaps listed in
3691 "bitmaps" to the "target" dirty bitmap. Dirty bitmaps in "bitmaps"
3692 will be unchanged, except if it also appears as the "target" bitmap.
3693 Any bits already set in "target" will still be set after the merge,
3694 i.e., this operation does not clear the target. On error, "target" is
3695 unchanged.
3696 The resulting bitmap will count as dirty any clusters that were dirty
3698 in any of the source bitmaps. This can be used to achieve backup
3699 checkpoints, or in simpler usages, to copy bitmaps.
3700 Returns:
3702 - nothing on success
3704 - If "node" is not a valid block device, DeviceNotFound
3706 - If any bitmap in "bitmaps" or "target" is not found, GenericError
3708 - If any of the bitmaps have different sizes or granularities,
3710 GenericError
3711 Since: 4.0
3713 Example:
3715 -> { "execute": "block-dirty-bitmap-merge",
3717 "arguments": { "node": "drive0", "target": "bitmap0",
3718 "bitmaps": ["bitmap1"] } }
3719 <- { "return": {} }
3720 BlockDirtyBitmapSha256 (Object)
3722 SHA256 hash of dirty bitmap data
3724 Members:
3726 "sha256: string"
3728 ASCII representation of SHA256 bitmap hash
3729 Since: 2.10
3731 x-debug-block-dirty-bitmap-sha256 (Command) Get bitmap SHA256.
3733 Returns:
3735 - BlockDirtyBitmapSha256 on success
3737 - If "node" is not a valid block device, DeviceNotFound
3739 - If "name" is not found or if hashing has failed, GenericError with
3741 an explanation
3742 Since: 2.10
3744 blockdev-mirror (Command) Start mirroring a block device's writes to a
3746 new destination.
3747 Arguments:
3749 "job-id: string" (optional)
3751 identifier for the newly-created block job. If omitted, the device
3752 name will be used. (Since 2.7)
3753 "device: string"
3755 The device name or node-name of a root node whose writes should be
3756 mirrored.
3757 "target: string"
3759 the id or node-name of the block device to mirror to. This mustn't
3760 be attached to guest.
3761 "replaces: string" (optional)
3763 with sync=full graph node name to be replaced by the new image when
3764 a whole image copy is done. This can be used to repair broken
3765 Quorum files.
3766 "speed: int" (optional)
3768 the maximum speed, in bytes per second
3769 "sync: MirrorSyncMode"
3771 what parts of the disk image should be copied to the destination
3772 (all the disk, only the sectors allocated in the topmost image, or
3773 only new I/O).
3774 "granularity: int" (optional)
3776 granularity of the dirty bitmap, default is 64K if the image format
3777 doesn't have clusters, 4K if the clusters are smaller than that,
3778 else the cluster size. Must be a power of 2 between 512 and 64M
3779 "buf-size: int" (optional)
3781 maximum amount of data in flight from source to target
3782 "on-source-error: BlockdevOnError" (optional)
3784 the action to take on an error on the source, default 'report'.
3785 'stop' and 'enospc' can only be used if the block device supports
3786 io-status (see BlockInfo).
3787 "on-target-error: BlockdevOnError" (optional)
3789 the action to take on an error on the target, default 'report' (no
3790 limitations, since this applies to a different block device than
3791 "device").
3792 "filter-node-name: string" (optional)
3794 the node name that should be assigned to the filter driver that the
3795 mirror job inserts into the graph above "device". If this option is
3796 not given, a node name is autogenerated. (Since: 2.9)
3797 "copy-mode: MirrorCopyMode" (optional)
3799 when to copy data to the destination; defaults to 'background'
3800 (Since: 3.0)
3801 "auto-finalize: boolean" (optional)
3803 When false, this job will wait in a PENDING state after it has
3804 finished its work, waiting for "block-job-finalize" before making
3805 any block graph changes. When true, this job will automatically
3806 perform its abort or commit actions. Defaults to true. (Since 3.1)
3807 "auto-dismiss: boolean" (optional)
3809 When false, this job will wait in a CONCLUDED state after it has
3810 completely ceased all work, and awaits "block-job-dismiss". When
3811 true, this job will automatically disappear from the query list
3812 without user intervention. Defaults to true. (Since 3.1)
3813 Returns: nothing on success.
3815 Since: 2.6
3817 Example:
3819 -> { "execute": "blockdev-mirror",
3821 "arguments": { "device": "ide-hd0",
3822 "target": "target0",
3823 "sync": "full" } }
3824 <- { "return": {} }
3825 BlockIOThrottle (Object)
3827 A set of parameters describing block throttling.
3829 Members:
3831 "device: string" (optional)
3833 Block device name
3834 "id: string" (optional)
3836 The name or QOM path of the guest device (since: 2.8)
3837 "bps: int"
3839 total throughput limit in bytes per second
3840 "bps_rd: int"
3842 read throughput limit in bytes per second
3843 "bps_wr: int"
3845 write throughput limit in bytes per second
3846 "iops: int"
3848 total I/O operations per second
3849 "iops_rd: int"
3851 read I/O operations per second
3852 "iops_wr: int"
3854 write I/O operations per second
3855 "bps_max: int" (optional)
3857 total throughput limit during bursts, in bytes (Since 1.7)
3858 "bps_rd_max: int" (optional)
3860 read throughput limit during bursts, in bytes (Since 1.7)
3861 "bps_wr_max: int" (optional)
3863 write throughput limit during bursts, in bytes (Since 1.7)
3864 "iops_max: int" (optional)
3866 total I/O operations per second during bursts, in bytes (Since 1.7)
3867 "iops_rd_max: int" (optional)
3869 read I/O operations per second during bursts, in bytes (Since 1.7)
3870 "iops_wr_max: int" (optional)
3872 write I/O operations per second during bursts, in bytes (Since 1.7)
3873 "bps_max_length: int" (optional)
3875 maximum length of the "bps_max" burst period, in seconds. It must
3876 only be set if "bps_max" is set as well. Defaults to 1. (Since
3877 2.6)
3878 "bps_rd_max_length: int" (optional)
3880 maximum length of the "bps_rd_max" burst period, in seconds. It
3881 must only be set if "bps_rd_max" is set as well. Defaults to 1.
3882 (Since 2.6)
3883 "bps_wr_max_length: int" (optional)
3885 maximum length of the "bps_wr_max" burst period, in seconds. It
3886 must only be set if "bps_wr_max" is set as well. Defaults to 1.
3887 (Since 2.6)
3888 "iops_max_length: int" (optional)
3890 maximum length of the "iops" burst period, in seconds. It must only
3891 be set if "iops_max" is set as well. Defaults to 1. (Since 2.6)
3892 "iops_rd_max_length: int" (optional)
3894 maximum length of the "iops_rd_max" burst period, in seconds. It
3895 must only be set if "iops_rd_max" is set as well. Defaults to 1.
3896 (Since 2.6)
3897 "iops_wr_max_length: int" (optional)
3899 maximum length of the "iops_wr_max" burst period, in seconds. It
3900 must only be set if "iops_wr_max" is set as well. Defaults to 1.
3901 (Since 2.6)
3902 "iops_size: int" (optional)
3904 an I/O size in bytes (Since 1.7)
3905 "group: string" (optional)
3907 throttle group name (Since 2.4)
3908 Features:
3910 "deprecated"
3912 Member "device" is deprecated. Use "id" instead.
3913 Since: 1.1
3915 ThrottleLimits (Object)
3917 Limit parameters for throttling. Since some limit combinations are
3919 illegal, limits should always be set in one transaction. All fields are
3920 optional. When setting limits, if a field is missing the current value
3921 is not changed.
3922 Members:
3924 "iops-total: int" (optional)
3926 limit total I/O operations per second
3927 "iops-total-max: int" (optional)
3929 I/O operations burst
3930 "iops-total-max-length: int" (optional)
3932 length of the iops-total-max burst period, in seconds It must only
3933 be set if "iops-total-max" is set as well.
3934 "iops-read: int" (optional)
3936 limit read operations per second
3937 "iops-read-max: int" (optional)
3939 I/O operations read burst
3940 "iops-read-max-length: int" (optional)
3942 length of the iops-read-max burst period, in seconds It must only
3943 be set if "iops-read-max" is set as well.
3944 "iops-write: int" (optional)
3946 limit write operations per second
3947 "iops-write-max: int" (optional)
3949 I/O operations write burst
3950 "iops-write-max-length: int" (optional)
3952 length of the iops-write-max burst period, in seconds It must only
3953 be set if "iops-write-max" is set as well.
3954 "bps-total: int" (optional)
3956 limit total bytes per second
3957 "bps-total-max: int" (optional)
3959 total bytes burst
3960 "bps-total-max-length: int" (optional)
3962 length of the bps-total-max burst period, in seconds. It must only
3963 be set if "bps-total-max" is set as well.
3964 "bps-read: int" (optional)
3966 limit read bytes per second
3967 "bps-read-max: int" (optional)
3969 total bytes read burst
3970 "bps-read-max-length: int" (optional)
3972 length of the bps-read-max burst period, in seconds It must only be
3973 set if "bps-read-max" is set as well.
3974 "bps-write: int" (optional)
3976 limit write bytes per second
3977 "bps-write-max: int" (optional)
3979 total bytes write burst
3980 "bps-write-max-length: int" (optional)
3982 length of the bps-write-max burst period, in seconds It must only
3983 be set if "bps-write-max" is set as well.
3984 "iops-size: int" (optional)
3986 when limiting by iops max size of an I/O in bytes
3987 Since: 2.11
3989 block-stream (Command) Copy data from a backing file into a block
3991 device.
3992 The block streaming operation is performed in the background until the
3994 entire backing file has been copied. This command returns immediately
3995 once streaming has started. The status of ongoing block streaming
3996 operations can be checked with query-block-jobs. The operation can be
3997 stopped before it has completed using the block-job-cancel command.
3998 The node that receives the data is called the top image, can be located
4000 in any part of the chain (but always above the base image; see below)
4001 and can be specified using its device or node name. Earlier qemu
4002 versions only allowed 'device' to name the top level node; presence of
4003 the 'base-node' parameter during introspection can be used as a witness
4004 of the enhanced semantics of 'device'.
4005 If a base file is specified then sectors are not copied from that base
4007 file and its backing chain. When streaming completes the image file
4008 will have the base file as its backing file. This can be used to
4009 stream a subset of the backing file chain instead of flattening the
4010 entire image.
4011 On successful completion the image file is updated to drop the backing
4013 file and the BLOCK_JOB_COMPLETED event is emitted.
4014 Arguments:
4016 "job-id: string" (optional)
4018 identifier for the newly-created block job. If omitted, the device
4019 name will be used. (Since 2.7)
4020 "device: string"
4022 the device or node name of the top image
4023 "base: string" (optional)
4025 the common backing file name. It cannot be set if "base-node" is
4026 also set.
4027 "base-node: string" (optional)
4029 the node name of the backing file. It cannot be set if "base" is
4030 also set. (Since 2.8)
4031 "backing-file: string" (optional)
4033 The backing file string to write into the top image. This filename
4034 is not validated.
4035 If a pathname string is such that it cannot be resolved by QEMU,
4037 that means that subsequent QMP or HMP commands must use node-names
4038 for the image in question, as filename lookup methods will fail.
4039 If not specified, QEMU will automatically determine the backing
4041 file string to use, or error out if there is no obvious choice.
4042 Care should be taken when specifying the string, to specify a valid
4043 filename or protocol. (Since 2.1)
4044 "speed: int" (optional)
4046 the maximum speed, in bytes per second
4047 "on-error: BlockdevOnError" (optional)
4049 the action to take on an error (default report). 'stop' and
4050 'enospc' can only be used if the block device supports io-status
4051 (see BlockInfo). Since 1.3.
4052 "auto-finalize: boolean" (optional)
4054 When false, this job will wait in a PENDING state after it has
4055 finished its work, waiting for "block-job-finalize" before making
4056 any block graph changes. When true, this job will automatically
4057 perform its abort or commit actions. Defaults to true. (Since 3.1)
4058 "auto-dismiss: boolean" (optional)
4060 When false, this job will wait in a CONCLUDED state after it has
4061 completely ceased all work, and awaits "block-job-dismiss". When
4062 true, this job will automatically disappear from the query list
4063 without user intervention. Defaults to true. (Since 3.1)
4064 Returns:
4066 - Nothing on success.
4068 - If "device" does not exist, DeviceNotFound.
4070 Since: 1.1
4072 Example:
4074 -> { "execute": "block-stream",
4076 "arguments": { "device": "virtio0",
4077 "base": "/tmp/master.qcow2" } }
4078 <- { "return": {} }
4079 block-job-set-speed (Command) Set maximum speed for a background block
4081 operation.
4082 This command can only be issued when there is an active block job.
4084 Throttling can be disabled by setting the speed to 0.
4086 Arguments:
4088 "device: string"
4090 The job identifier. This used to be a device name (hence the name
4091 of the parameter), but since QEMU 2.7 it can have other values.
4092 "speed: int"
4094 the maximum speed, in bytes per second, or 0 for unlimited.
4095 Defaults to 0.
4096 Returns:
4098 - Nothing on success
4100 - If no background operation is active on this device,
4102 DeviceNotActive
4103 Since: 1.1
4105 block-job-cancel (Command) Stop an active background block operation.
4107 This command returns immediately after marking the active background
4109 block operation for cancellation. It is an error to call this command
4110 if no operation is in progress.
4111 The operation will cancel as soon as possible and then emit the
4113 BLOCK_JOB_CANCELLED event. Before that happens the job is still
4114 visible when enumerated using query-block-jobs.
4115 Note that if you issue 'block-job-cancel' after 'drive-mirror' has
4117 indicated (via the event BLOCK_JOB_READY) that the source and
4118 destination are synchronized, then the event triggered by this command
4119 changes to BLOCK_JOB_COMPLETED, to indicate that the mirroring has
4120 ended and the destination now has a point-in-time copy tied to the time
4121 of the cancellation.
4122 For streaming, the image file retains its backing file unless the
4124 streaming operation happens to complete just as it is being cancelled.
4125 A new streaming operation can be started at a later time to finish
4126 copying all data from the backing file.
4127 Arguments:
4129 "device: string"
4131 The job identifier. This used to be a device name (hence the name
4132 of the parameter), but since QEMU 2.7 it can have other values.
4133 "force: boolean" (optional)
4135 If true, and the job has already emitted the event BLOCK_JOB_READY,
4136 abandon the job immediately (even if it is paused) instead of
4137 waiting for the destination to complete its final synchronization
4138 (since 1.3)
4139 Returns:
4141 - Nothing on success
4143 - If no background operation is active on this device,
4145 DeviceNotActive
4146 Since: 1.1
4148 block-job-pause (Command) Pause an active background block operation.
4150 This command returns immediately after marking the active background
4152 block operation for pausing. It is an error to call this command if no
4153 operation is in progress or if the job is already paused.
4154 The operation will pause as soon as possible. No event is emitted when
4156 the operation is actually paused. Cancelling a paused job
4157 automatically resumes it.
4158 Arguments:
4160 "device: string"
4162 The job identifier. This used to be a device name (hence the name
4163 of the parameter), but since QEMU 2.7 it can have other values.
4164 Returns:
4166 - Nothing on success
4168 - If no background operation is active on this device,
4170 DeviceNotActive
4171 Since: 1.3
4173 block-job-resume (Command) Resume an active background block
4175 operation.
4176 This command returns immediately after resuming a paused background
4178 block operation. It is an error to call this command if no operation
4179 is in progress or if the job is not paused.
4180 This command also clears the error status of the job.
4182 Arguments:
4184 "device: string"
4186 The job identifier. This used to be a device name (hence the name
4187 of the parameter), but since QEMU 2.7 it can have other values.
4188 Returns:
4190 - Nothing on success
4192 - If no background operation is active on this device,
4194 DeviceNotActive
4195 Since: 1.3
4197 block-job-complete (Command) Manually trigger completion of an active
4199 background block operation. This is supported for drive mirroring,
4200 where it also switches the device to write to the target path only.
4201 The ability to complete is signaled with a BLOCK_JOB_READY event.
4202 This command completes an active background block operation
4204 synchronously. The ordering of this command's return with the
4205 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4206 occurs during the processing of this command: 1) the command itself
4207 will fail; 2) the error will be processed according to the
4208 rerror/werror arguments that were specified when starting the
4209 operation.
4210 A cancelled or paused job cannot be completed.
4212 Arguments:
4214 "device: string"
4216 The job identifier. This used to be a device name (hence the name
4217 of the parameter), but since QEMU 2.7 it can have other values.
4218 Returns:
4220 - Nothing on success
4222 - If no background operation is active on this device,
4224 DeviceNotActive
4225 Since: 1.3
4227 block-job-dismiss (Command) For jobs that have already concluded,
4229 remove them from the block-job-query list. This command only needs to
4230 be run for jobs which were started with QEMU 2.12+ job lifetime
4231 management semantics.
4232 This command will refuse to operate on any job that has not yet reached
4234 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4235 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4236 still need to be used as appropriate.
4237 Arguments:
4239 "id: string"
4241 The job identifier.
4242 Returns: Nothing on success
4244 Since: 2.12
4246 block-job-finalize (Command) Once a job that has manual=true reaches
4248 the pending state, it can be instructed to finalize any graph changes
4249 and do any necessary cleanup via this command. For jobs in a
4250 transaction, instructing one job to finalize will force ALL jobs in the
4251 transaction to finalize, so it is only necessary to instruct a single
4252 member job to finalize.
4253 Arguments:
4255 "id: string"
4257 The job identifier.
4258 Returns: Nothing on success
4260 Since: 2.12
4262 BlockdevDiscardOptions (Enum)
4264 Determines how to handle discard requests.
4266 Values:
4268 "ignore"
4270 Ignore the request
4271 "unmap"
4273 Forward as an unmap request
4274 Since: 2.9
4276 BlockdevDetectZeroesOptions (Enum)
4278 Describes the operation mode for the automatic conversion of plain zero
4280 writes by the OS to driver specific optimized zero write commands.
4281 Values:
4283 "off"
4285 Disabled (default)
4286 "on"
4288 Enabled
4289 "unmap"
4291 Enabled and even try to unmap blocks if possible. This requires
4292 also that "BlockdevDiscardOptions" is set to unmap for this device.
4293 Since: 2.1
4295 BlockdevAioOptions (Enum)
4297 Selects the AIO backend to handle I/O requests
4299 Values:
4301 "threads"
4303 Use qemu's thread pool
4304 "native"
4306 Use native AIO backend (only Linux and Windows)
4307 "io_uring"
4309 Use linux io_uring (since 5.0) If: "defined(CONFIG_LINUX_IO_URING)"
4310 Since: 2.9
4312 BlockdevCacheOptions (Object)
4314 Includes cache-related options for block devices
4316 Members:
4318 "direct: boolean" (optional)
4320 enables use of O_DIRECT (bypass the host page cache; default:
4321 false)
4322 "no-flush: boolean" (optional)
4324 ignore any flush requests for the device (default: false)
4325 Since: 2.9
4327 BlockdevDriver (Enum)
4329 Drivers that are supported in block device operations.
4331 Values:
4333 "throttle"
4335 Since 2.11
4336 "nvme"
4338 Since 2.12
4339 "copy-on-read"
4341 Since 3.0
4342 "blklogwrites"
4344 Since 3.0
4345 "blkreplay"
4347 Since 4.2
4348 "compress"
4350 Since 5.0
4351 "blkdebug"
4353 Not documented
4354 "blkverify"
4356 Not documented
4357 "bochs"
4359 Not documented
4360 "cloop"
4362 Not documented
4363 "dmg"
4365 Not documented
4366 "file"
4368 Not documented
4369 "ftp"
4371 Not documented
4372 "ftps"
4374 Not documented
4375 "gluster"
4377 Not documented
4378 "host_cdrom"
4380 Not documented
4381 "host_device"
4383 Not documented
4384 "http"
4386 Not documented
4387 "https"
4389 Not documented
4390 "iscsi"
4392 Not documented
4393 "luks"
4395 Not documented
4396 "nbd"
4398 Not documented
4399 "nfs"
4401 Not documented
4402 "null-aio"
4404 Not documented
4405 "null-co"
4407 Not documented
4408 "parallels"
4410 Not documented
4411 "qcow"
4413 Not documented
4414 "qcow2"
4416 Not documented
4417 "qed"
4419 Not documented
4420 "quorum"
4422 Not documented
4423 "raw"
4425 Not documented
4426 "rbd"
4428 Not documented
4429 "replication"
4431 Not documented If: "defined(CONFIG_REPLICATION)"
4432 "sheepdog"
4434 Not documented
4435 "ssh"
4437 Not documented
4438 "vdi"
4440 Not documented
4441 "vhdx"
4443 Not documented
4444 "vmdk"
4446 Not documented
4447 "vpc"
4449 Not documented
4450 "vvfat"
4452 Not documented
4453 Since: 2.9
4455 BlockdevOptionsFile (Object)
4457 Driver specific block device options for the file backend.
4459 Members:
4461 "filename: string"
4463 path to the image file
4464 "pr-manager: string" (optional)
4466 the id for the object that will handle persistent reservations for
4467 this device (default: none, forward the commands via SG_IO; since
4468 2.11)
4469 "aio: BlockdevAioOptions" (optional)
4471 AIO backend (default: threads) (since: 2.8)
4472 "locking: OnOffAuto" (optional)
4474 whether to enable file locking. If set to 'auto', only enable when
4475 Open File Descriptor (OFD) locking API is available (default: auto,
4476 since 2.10)
4477 "drop-cache: boolean" (optional)
4479 invalidate page cache during live migration. This prevents stale
4480 data on the migration destination with cache.direct=off. Currently
4481 only supported on Linux hosts. (default: on, since: 4.0) If:
4482 "defined(CONFIG_LINUX)"
4483 "x-check-cache-dropped: boolean" (optional)
4485 whether to check that page cache was dropped on live migration.
4486 May cause noticeable delays if the image file is large, do not use
4487 in production. (default: off) (since: 3.0)
4488 Features:
4490 "dynamic-auto-read-only"
4492 If present, enabled auto-read-only means that the driver will open
4493 the image read-only at first, dynamically reopen the image file
4494 read-write when the first writer is attached to the node and reopen
4495 read-only when the last writer is detached. This allows giving QEMU
4496 write permissions only on demand when an operation actually needs
4497 write access.
4498 Since: 2.9
4500 BlockdevOptionsNull (Object)
4502 Driver specific block device options for the null backend.
4504 Members:
4506 "size: int" (optional)
4508 size of the device in bytes.
4509 "latency-ns: int" (optional)
4511 emulated latency (in nanoseconds) in processing requests. Default
4512 to zero which completes requests immediately. (Since 2.4)
4513 "read-zeroes: boolean" (optional)
4515 if true, reads from the device produce zeroes; if false, the buffer
4516 is left unchanged. (default: false; since: 4.1)
4517 Since: 2.9
4519 BlockdevOptionsNVMe (Object)
4521 Driver specific block device options for the NVMe backend.
4523 Members:
4525 "device: string"
4527 PCI controller address of the NVMe device in format hhhh:bb:ss.f
4528 (host:bus:slot.function)
4529 "namespace: int"
4531 namespace number of the device, starting from 1.
4532 Note that the PCI "device" must have been unbound from any host kernel
4534 driver before instructing QEMU to add the blockdev.
4535 Since: 2.12
4537 BlockdevOptionsVVFAT (Object)
4539 Driver specific block device options for the vvfat protocol.
4541 Members:
4543 "dir: string"
4545 directory to be exported as FAT image
4546 "fat-type: int" (optional)
4548 FAT type: 12, 16 or 32
4549 "floppy: boolean" (optional)
4551 whether to export a floppy image (true) or partitioned hard disk
4552 (false; default)
4553 "label: string" (optional)
4555 set the volume label, limited to 11 bytes. FAT16 and FAT32
4556 traditionally have some restrictions on labels, which are ignored
4557 by most operating systems. Defaults to "QEMU VVFAT". (since 2.4)
4558 "rw: boolean" (optional)
4560 whether to allow write operations (default: false)
4561 Since: 2.9
4563 BlockdevOptionsGenericFormat (Object)
4565 Driver specific block device options for image format that have no
4567 option besides their data source.
4568 Members:
4570 "file: BlockdevRef"
4572 reference to or definition of the data source block device
4573 Since: 2.9
4575 BlockdevOptionsLUKS (Object)
4577 Driver specific block device options for LUKS.
4579 Members:
4581 "key-secret: string" (optional)
4583 the ID of a QCryptoSecret object providing the decryption key
4584 (since 2.6). Mandatory except when doing a metadata-only probe of
4585 the image.
4586 The members of "BlockdevOptionsGenericFormat"
4588 Since: 2.9
4590 BlockdevOptionsGenericCOWFormat (Object)
4592 Driver specific block device options for image format that have no
4594 option besides their data source and an optional backing file.
4595 Members:
4597 "backing: BlockdevRefOrNull" (optional)
4599 reference to or definition of the backing file block device, null
4600 disables the backing file entirely. Defaults to the backing file
4601 stored the image file.
4602 The members of "BlockdevOptionsGenericFormat"
4604 Since: 2.9
4606 Qcow2OverlapCheckMode (Enum)
4608 General overlap check modes.
4610 Values:
4612 "none"
4614 Do not perform any checks
4615 "constant"
4617 Perform only checks which can be done in constant time and without
4618 reading anything from disk
4619 "cached"
4621 Perform only checks which can be done without reading anything from
4622 disk
4623 "all"
4625 Perform all available overlap checks
4626 Since: 2.9
4628 Qcow2OverlapCheckFlags (Object)
4630 Structure of flags for each metadata structure. Setting a field to
4632 'true' makes qemu guard that structure against unintended overwriting.
4633 The default value is chosen according to the template given.
4634 Members:
4636 "template: Qcow2OverlapCheckMode" (optional)
4638 Specifies a template mode which can be adjusted using the other
4639 flags, defaults to 'cached'
4640 "bitmap-directory: boolean" (optional)
4642 since 3.0
4643 "main-header: boolean" (optional)
4645 Not documented
4646 "active-l1: boolean" (optional)
4648 Not documented
4649 "active-l2: boolean" (optional)
4651 Not documented
4652 "refcount-table: boolean" (optional)
4654 Not documented
4655 "refcount-block: boolean" (optional)
4657 Not documented
4658 "snapshot-table: boolean" (optional)
4660 Not documented
4661 "inactive-l1: boolean" (optional)
4663 Not documented
4664 "inactive-l2: boolean" (optional)
4666 Not documented
4667 Since: 2.9
4669 Qcow2OverlapChecks (Alternate)
4671 Specifies which metadata structures should be guarded against
4673 unintended overwriting.
4674 Members:
4676 "flags: Qcow2OverlapCheckFlags"
4678 set of flags for separate specification of each metadata structure
4679 type
4680 "mode: Qcow2OverlapCheckMode"
4682 named mode which chooses a specific set of flags
4683 Since: 2.9
4685 BlockdevQcowEncryptionFormat (Enum)
4687 Values:
4689 "aes"
4691 AES-CBC with plain64 initialization vectors
4692 Since: 2.10
4694 BlockdevQcowEncryption (Object)
4696 Members:
4698 "format: BlockdevQcowEncryptionFormat"
4700 Not documented
4701 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4703 Since: 2.10
4705 BlockdevOptionsQcow (Object)
4707 Driver specific block device options for qcow.
4709 Members:
4711 "encrypt: BlockdevQcowEncryption" (optional)
4713 Image decryption options. Mandatory for encrypted images, except
4714 when doing a metadata-only probe of the image.
4715 The members of "BlockdevOptionsGenericCOWFormat"
4717 Since: 2.10
4719 BlockdevQcow2EncryptionFormat (Enum)
4721 Values:
4723 "aes"
4725 AES-CBC with plain64 initialization vectors
4726 "luks"
4728 Not documented
4729 Since: 2.10
4731 BlockdevQcow2Encryption (Object)
4733 Members:
4735 "format: BlockdevQcow2EncryptionFormat"
4737 Not documented
4738 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4740 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
4741 Since: 2.10
4743 BlockdevOptionsQcow2 (Object)
4745 Driver specific block device options for qcow2.
4747 Members:
4749 "lazy-refcounts: boolean" (optional)
4751 whether to enable the lazy refcounts feature (default is taken from
4752 the image file)
4753 "pass-discard-request: boolean" (optional)
4755 whether discard requests to the qcow2 device should be forwarded to
4756 the data source
4757 "pass-discard-snapshot: boolean" (optional)
4759 whether discard requests for the data source should be issued when
4760 a snapshot operation (e.g. deleting a snapshot) frees clusters in
4761 the qcow2 file
4762 "pass-discard-other: boolean" (optional)
4764 whether discard requests for the data source should be issued on
4765 other occasions where a cluster gets freed
4766 "overlap-check: Qcow2OverlapChecks" (optional)
4768 which overlap checks to perform for writes to the image, defaults
4769 to 'cached' (since 2.2)
4770 "cache-size: int" (optional)
4772 the maximum total size of the L2 table and refcount block caches in
4773 bytes (since 2.2)
4774 "l2-cache-size: int" (optional)
4776 the maximum size of the L2 table cache in bytes (since 2.2)
4777 "l2-cache-entry-size: int" (optional)
4779 the size of each entry in the L2 cache in bytes. It must be a power
4780 of two between 512 and the cluster size. The default value is the
4781 cluster size (since 2.12)
4782 "refcount-cache-size: int" (optional)
4784 the maximum size of the refcount block cache in bytes (since 2.2)
4785 "cache-clean-interval: int" (optional)
4787 clean unused entries in the L2 and refcount caches. The interval is
4788 in seconds. The default value is 600 on supporting platforms, and 0
4789 on other platforms. 0 disables this feature. (since 2.5)
4790 "encrypt: BlockdevQcow2Encryption" (optional)
4792 Image decryption options. Mandatory for encrypted images, except
4793 when doing a metadata-only probe of the image. (since 2.10)
4794 "data-file: BlockdevRef" (optional)
4796 reference to or definition of the external data file. This may
4797 only be specified for images that require an external data file. If
4798 it is not specified for such an image, the data file name is loaded
4799 from the image file. (since 4.0)
4800 The members of "BlockdevOptionsGenericCOWFormat"
4802 Since: 2.9
4804 SshHostKeyCheckMode (Enum)
4806 Values:
4808 "none"
4810 Don't check the host key at all
4811 "hash"
4813 Compare the host key with a given hash
4814 "known_hosts"
4816 Check the host key against the known_hosts file
4817 Since: 2.12
4819 SshHostKeyCheckHashType (Enum)
4821 Values:
4823 "md5"
4825 The given hash is an md5 hash
4826 "sha1"
4828 The given hash is an sha1 hash
4829 Since: 2.12
4831 SshHostKeyHash (Object)
4833 Members:
4835 "type: SshHostKeyCheckHashType"
4837 The hash algorithm used for the hash
4838 "hash: string"
4840 The expected hash value
4841 Since: 2.12
4843 SshHostKeyCheck (Object)
4845 Members:
4847 "mode: SshHostKeyCheckMode"
4849 Not documented
4850 The members of "SshHostKeyHash" when "mode" is "hash"
4852 Since: 2.12
4854 BlockdevOptionsSsh (Object)
4856 Members:
4858 "server: InetSocketAddress"
4860 host address
4861 "path: string"
4863 path to the image on the host
4864 "user: string" (optional)
4866 user as which to connect, defaults to current local user name
4867 "host-key-check: SshHostKeyCheck" (optional)
4869 Defines how and what to check the host key against (default:
4870 known_hosts)
4871 Since: 2.9
4873 BlkdebugEvent (Enum)
4875 Trigger events supported by blkdebug.
4877 Values:
4879 "l1_shrink_write_table"
4881 write zeros to the l1 table to shrink image. (since 2.11)
4882 "l1_shrink_free_l2_clusters"
4884 discard the l2 tables. (since 2.11)
4885 "cor_write"
4887 a write due to copy-on-read (since 2.11)
4888 "cluster_alloc_space"
4890 an allocation of file space for a cluster (since 4.1)
4891 "none"
4893 triggers once at creation of the blkdebug node (since 4.1)
4894 "l1_update"
4896 Not documented
4897 "l1_grow_alloc_table"
4899 Not documented
4900 "l1_grow_write_table"
4902 Not documented
4903 "l1_grow_activate_table"
4905 Not documented
4906 "l2_load"
4908 Not documented
4909 "l2_update"
4911 Not documented
4912 "l2_update_compressed"
4914 Not documented
4915 "l2_alloc_cow_read"
4917 Not documented
4918 "l2_alloc_write"
4920 Not documented
4921 "read_aio"
4923 Not documented
4924 "read_backing_aio"
4926 Not documented
4927 "read_compressed"
4929 Not documented
4930 "write_aio"
4932 Not documented
4933 "write_compressed"
4935 Not documented
4936 "vmstate_load"
4938 Not documented
4939 "vmstate_save"
4941 Not documented
4942 "cow_read"
4944 Not documented
4945 "cow_write"
4947 Not documented
4948 "reftable_load"
4950 Not documented
4951 "reftable_grow"
4953 Not documented
4954 "reftable_update"
4956 Not documented
4957 "refblock_load"
4959 Not documented
4960 "refblock_update"
4962 Not documented
4963 "refblock_update_part"
4965 Not documented
4966 "refblock_alloc"
4968 Not documented
4969 "refblock_alloc_hookup"
4971 Not documented
4972 "refblock_alloc_write"
4974 Not documented
4975 "refblock_alloc_write_blocks"
4977 Not documented
4978 "refblock_alloc_write_table"
4980 Not documented
4981 "refblock_alloc_switch_table"
4983 Not documented
4984 "cluster_alloc"
4986 Not documented
4987 "cluster_alloc_bytes"
4989 Not documented
4990 "cluster_free"
4992 Not documented
4993 "flush_to_os"
4995 Not documented
4996 "flush_to_disk"
4998 Not documented
4999 "pwritev_rmw_head"
5001 Not documented
5002 "pwritev_rmw_after_head"
5004 Not documented
5005 "pwritev_rmw_tail"
5007 Not documented
5008 "pwritev_rmw_after_tail"
5010 Not documented
5011 "pwritev"
5013 Not documented
5014 "pwritev_zero"
5016 Not documented
5017 "pwritev_done"
5019 Not documented
5020 "empty_image_prepare"
5022 Not documented
5023 Since: 2.9
5025 BlkdebugIOType (Enum)
5027 Kinds of I/O that blkdebug can inject errors in.
5029 Values:
5031 "read"
5033 .bdrv_co_preadv()
5034 "write"
5036 .bdrv_co_pwritev()
5037 "write-zeroes"
5039 .bdrv_co_pwrite_zeroes()
5040 "discard"
5042 .bdrv_co_pdiscard()
5043 "flush"
5045 .bdrv_co_flush_to_disk()
5046 "block-status"
5048 .bdrv_co_block_status()
5049 Since: 4.1
5051 BlkdebugInjectErrorOptions (Object)
5053 Describes a single error injection for blkdebug.
5055 Members:
5057 "event: BlkdebugEvent"
5059 trigger event
5060 "state: int" (optional)
5062 the state identifier blkdebug needs to be in to actually trigger
5063 the event; defaults to "any"
5064 "iotype: BlkdebugIOType" (optional)
5066 the type of I/O operations on which this error should be injected;
5067 defaults to "all read, write, write-zeroes, discard, and flush
5068 operations" (since: 4.1)
5069 "errno: int" (optional)
5071 error identifier (errno) to be returned; defaults to EIO
5072 "sector: int" (optional)
5074 specifies the sector index which has to be affected in order to
5075 actually trigger the event; defaults to "any sector"
5076 "once: boolean" (optional)
5078 disables further events after this one has been triggered; defaults
5079 to false
5080 "immediately: boolean" (optional)
5082 fail immediately; defaults to false
5083 Since: 2.9
5085 BlkdebugSetStateOptions (Object)
5087 Describes a single state-change event for blkdebug.
5089 Members:
5091 "event: BlkdebugEvent"
5093 trigger event
5094 "state: int" (optional)
5096 the current state identifier blkdebug needs to be in; defaults to
5097 "any"
5098 "new_state: int"
5100 the state identifier blkdebug is supposed to assume if this event
5101 is triggered
5102 Since: 2.9
5104 BlockdevOptionsBlkdebug (Object)
5106 Driver specific block device options for blkdebug.
5108 Members:
5110 "image: BlockdevRef"
5112 underlying raw block device (or image file)
5113 "config: string" (optional)
5115 filename of the configuration file
5116 "align: int" (optional)
5118 required alignment for requests in bytes, must be positive power of
5119 2, or 0 for default
5120 "max-transfer: int" (optional)
5122 maximum size for I/O transfers in bytes, must be positive multiple
5123 of "align" and of the underlying file's request alignment (but need
5124 not be a power of 2), or 0 for default (since 2.10)
5125 "opt-write-zero: int" (optional)
5127 preferred alignment for write zero requests in bytes, must be
5128 positive multiple of "align" and of the underlying file's request
5129 alignment (but need not be a power of 2), or 0 for default (since
5130 2.10)
5131 "max-write-zero: int" (optional)
5133 maximum size for write zero requests in bytes, must be positive
5134 multiple of "align", of "opt-write-zero", and of the underlying
5135 file's request alignment (but need not be a power of 2), or 0 for
5136 default (since 2.10)
5137 "opt-discard: int" (optional)
5139 preferred alignment for discard requests in bytes, must be positive
5140 multiple of "align" and of the underlying file's request alignment
5141 (but need not be a power of 2), or 0 for default (since 2.10)
5142 "max-discard: int" (optional)
5144 maximum size for discard requests in bytes, must be positive
5145 multiple of "align", of "opt-discard", and of the underlying file's
5146 request alignment (but need not be a power of 2), or 0 for default
5147 (since 2.10)
5148 "inject-error: array of BlkdebugInjectErrorOptions" (optional)
5150 array of error injection descriptions
5151 "set-state: array of BlkdebugSetStateOptions" (optional)
5153 array of state-change descriptions
5154 "take-child-perms: array of BlockPermission" (optional)
5156 Permissions to take on "image" in addition to what is necessary
5157 anyway (which depends on how the blkdebug node is used). Defaults
5158 to none. (since 5.0)
5159 "unshare-child-perms: array of BlockPermission" (optional)
5161 Permissions not to share on "image" in addition to what cannot be
5162 shared anyway (which depends on how the blkdebug node is used).
5163 Defaults to none. (since 5.0)
5164 Since: 2.9
5166 BlockdevOptionsBlklogwrites (Object)
5168 Driver specific block device options for blklogwrites.
5170 Members:
5172 "file: BlockdevRef"
5174 block device
5175 "log: BlockdevRef"
5177 block device used to log writes to "file"
5178 "log-sector-size: int" (optional)
5180 sector size used in logging writes to "file", determines
5181 granularity of offsets and sizes of writes (default: 512)
5182 "log-append: boolean" (optional)
5184 append to an existing log (default: false)
5185 "log-super-update-interval: int" (optional)
5187 interval of write requests after which the log super block is
5188 updated to disk (default: 4096)
5189 Since: 3.0
5191 BlockdevOptionsBlkverify (Object)
5193 Driver specific block device options for blkverify.
5195 Members:
5197 "test: BlockdevRef"
5199 block device to be tested
5200 "raw: BlockdevRef"
5202 raw image used for verification
5203 Since: 2.9
5205 BlockdevOptionsBlkreplay (Object)
5207 Driver specific block device options for blkreplay.
5209 Members:
5211 "image: BlockdevRef"
5213 disk image which should be controlled with blkreplay
5214 Since: 4.2
5216 QuorumReadPattern (Enum)
5218 An enumeration of quorum read patterns.
5220 Values:
5222 "quorum"
5224 read all the children and do a quorum vote on reads
5225 "fifo"
5227 read only from the first child that has not failed
5228 Since: 2.9
5230 BlockdevOptionsQuorum (Object)
5232 Driver specific block device options for Quorum
5234 Members:
5236 "blkverify: boolean" (optional)
5238 true if the driver must print content mismatch set to false by
5239 default
5240 "children: array of BlockdevRef"
5242 the children block devices to use
5243 "vote-threshold: int"
5245 the vote limit under which a read will fail
5246 "rewrite-corrupted: boolean" (optional)
5248 rewrite corrupted data when quorum is reached (Since 2.1)
5249 "read-pattern: QuorumReadPattern" (optional)
5251 choose read pattern and set to quorum by default (Since 2.2)
5252 Since: 2.9
5254 BlockdevOptionsGluster (Object)
5256 Driver specific block device options for Gluster
5258 Members:
5260 "volume: string"
5262 name of gluster volume where VM image resides
5263 "path: string"
5265 absolute path to image file in gluster volume
5266 "server: array of SocketAddress"
5268 gluster servers description
5269 "debug: int" (optional)
5271 libgfapi log level (default '4' which is Error) (Since 2.8)
5272 "logfile: string" (optional)
5274 libgfapi log file (default /dev/stderr) (Since 2.8)
5275 Since: 2.9
5277 IscsiTransport (Enum)
5279 An enumeration of libiscsi transport types
5281 Values:
5283 "tcp"
5285 Not documented
5286 "iser"
5288 Not documented
5289 Since: 2.9
5291 IscsiHeaderDigest (Enum)
5293 An enumeration of header digests supported by libiscsi
5295 Values:
5297 "crc32c"
5299 Not documented
5300 "none"
5302 Not documented
5303 "crc32c-none"
5305 Not documented
5306 "none-crc32c"
5308 Not documented
5309 Since: 2.9
5311 BlockdevOptionsIscsi (Object)
5313 Members:
5315 "transport: IscsiTransport"
5317 The iscsi transport type
5318 "portal: string"
5320 The address of the iscsi portal
5321 "target: string"
5323 The target iqn name
5324 "lun: int" (optional)
5326 LUN to connect to. Defaults to 0.
5327 "user: string" (optional)
5329 User name to log in with. If omitted, no CHAP authentication is
5330 performed.
5331 "password-secret: string" (optional)
5333 The ID of a QCryptoSecret object providing the password for the
5334 login. This option is required if "user" is specified.
5335 "initiator-name: string" (optional)
5337 The iqn name we want to identify to the target as. If this option
5338 is not specified, an initiator name is generated automatically.
5339 "header-digest: IscsiHeaderDigest" (optional)
5341 The desired header digest. Defaults to none-crc32c.
5342 "timeout: int" (optional)
5344 Timeout in seconds after which a request will timeout. 0 means no
5345 timeout and is the default.
5346 Driver specific block device options for iscsi
5348 Since: 2.9
5350 RbdAuthMode (Enum)
5352 Values:
5354 "cephx"
5356 Not documented
5357 "none"
5359 Not documented
5360 Since: 3.0
5362 BlockdevOptionsRbd (Object)
5364 Members:
5366 "pool: string"
5368 Ceph pool name.
5369 "namespace: string" (optional)
5371 Rados namespace name in the Ceph pool. (Since 5.0)
5372 "image: string"
5374 Image name in the Ceph pool.
5375 "conf: string" (optional)
5377 path to Ceph configuration file. Values in the configuration file
5378 will be overridden by options specified via QAPI.
5379 "snapshot: string" (optional)
5381 Ceph snapshot name.
5382 "user: string" (optional)
5384 Ceph id name.
5385 "auth-client-required: array of RbdAuthMode" (optional)
5387 Acceptable authentication modes. This maps to Ceph configuration
5388 option "auth_client_required". (Since 3.0)
5389 "key-secret: string" (optional)
5391 ID of a QCryptoSecret object providing a key for cephx
5392 authentication. This maps to Ceph configuration option "key".
5393 (Since 3.0)
5394 "server: array of InetSocketAddressBase" (optional)
5396 Monitor host address and port. This maps to the "mon_host" Ceph
5397 option.
5398 Since: 2.9
5400 BlockdevOptionsSheepdog (Object)
5402 Driver specific block device options for sheepdog
5404 Members:
5406 "vdi: string"
5408 Virtual disk image name
5409 "server: SocketAddress"
5411 The Sheepdog server to connect to
5412 "snap-id: int" (optional)
5414 Snapshot ID
5415 "tag: string" (optional)
5417 Snapshot tag name
5418 Only one of "snap-id" and "tag" may be present.
5420 Since: 2.9
5422 ReplicationMode (Enum)
5424 An enumeration of replication modes.
5426 Values:
5428 "primary"
5430 Primary mode, the vm's state will be sent to secondary QEMU.
5431 "secondary"
5433 Secondary mode, receive the vm's state from primary QEMU.
5434 Since: 2.9
5436 If: "defined(CONFIG_REPLICATION)"
5438 BlockdevOptionsReplication (Object)
5440 Driver specific block device options for replication
5442 Members:
5444 "mode: ReplicationMode"
5446 the replication mode
5447 "top-id: string" (optional)
5449 In secondary mode, node name or device ID of the root node who owns
5450 the replication node chain. Must not be given in primary mode.
5451 The members of "BlockdevOptionsGenericFormat"
5453 Since: 2.9
5455 If: "defined(CONFIG_REPLICATION)"
5457 NFSTransport (Enum)
5459 An enumeration of NFS transport types
5461 Values:
5463 "inet"
5465 TCP transport
5466 Since: 2.9
5468 NFSServer (Object)
5470 Captures the address of the socket
5472 Members:
5474 "type: NFSTransport"
5476 transport type used for NFS (only TCP supported)
5477 "host: string"
5479 host address for NFS server
5480 Since: 2.9
5482 BlockdevOptionsNfs (Object)
5484 Driver specific block device option for NFS
5486 Members:
5488 "server: NFSServer"
5490 host address
5491 "path: string"
5493 path of the image on the host
5494 "user: int" (optional)
5496 UID value to use when talking to the server (defaults to 65534 on
5497 Windows and getuid() on unix)
5498 "group: int" (optional)
5500 GID value to use when talking to the server (defaults to 65534 on
5501 Windows and getgid() in unix)
5502 "tcp-syn-count: int" (optional)
5504 number of SYNs during the session establishment (defaults to libnfs
5505 default)
5506 "readahead-size: int" (optional)
5508 set the readahead size in bytes (defaults to libnfs default)
5509 "page-cache-size: int" (optional)
5511 set the pagecache size in bytes (defaults to libnfs default)
5512 "debug: int" (optional)
5514 set the NFS debug level (max 2) (defaults to libnfs default)
5515 Since: 2.9
5517 BlockdevOptionsCurlBase (Object)
5519 Driver specific block device options shared by all protocols supported
5521 by the curl backend.
5522 Members:
5524 "url: string"
5526 URL of the image file
5527 "readahead: int" (optional)
5529 Size of the read-ahead cache; must be a multiple of 512 (defaults
5530 to 256 kB)
5531 "timeout: int" (optional)
5533 Timeout for connections, in seconds (defaults to 5)
5534 "username: string" (optional)
5536 Username for authentication (defaults to none)
5537 "password-secret: string" (optional)
5539 ID of a QCryptoSecret object providing a password for
5540 authentication (defaults to no password)
5541 "proxy-username: string" (optional)
5543 Username for proxy authentication (defaults to none)
5544 "proxy-password-secret: string" (optional)
5546 ID of a QCryptoSecret object providing a password for proxy
5547 authentication (defaults to no password)
5548 Since: 2.9
5550 BlockdevOptionsCurlHttp (Object)
5552 Driver specific block device options for HTTP connections over the curl
5554 backend. URLs must start with "http://".
5555 Members:
5557 "cookie: string" (optional)
5559 List of cookies to set; format is "name1=content1; name2=content2;"
5560 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5561 "cookie-secret: string" (optional)
5563 ID of a QCryptoSecret object providing the cookie data in a secure
5564 way. See "cookie" for the format. (since 2.10)
5565 The members of "BlockdevOptionsCurlBase"
5567 Since: 2.9
5569 BlockdevOptionsCurlHttps (Object)
5571 Driver specific block device options for HTTPS connections over the
5573 curl backend. URLs must start with "https://".
5574 Members:
5576 "cookie: string" (optional)
5578 List of cookies to set; format is "name1=content1; name2=content2;"
5579 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5580 "sslverify: boolean" (optional)
5582 Whether to verify the SSL certificate's validity (defaults to true)
5583 "cookie-secret: string" (optional)
5585 ID of a QCryptoSecret object providing the cookie data in a secure
5586 way. See "cookie" for the format. (since 2.10)
5587 The members of "BlockdevOptionsCurlBase"
5589 Since: 2.9
5591 BlockdevOptionsCurlFtp (Object)
5593 Driver specific block device options for FTP connections over the curl
5595 backend. URLs must start with "ftp://".
5596 Members:
5598 The members of "BlockdevOptionsCurlBase"
5600 Since: 2.9
5602 BlockdevOptionsCurlFtps (Object)
5604 Driver specific block device options for FTPS connections over the curl
5606 backend. URLs must start with "ftps://".
5607 Members:
5609 "sslverify: boolean" (optional)
5611 Whether to verify the SSL certificate's validity (defaults to true)
5612 The members of "BlockdevOptionsCurlBase"
5614 Since: 2.9
5616 BlockdevOptionsNbd (Object)
5618 Driver specific block device options for NBD.
5620 Members:
5622 "server: SocketAddress"
5624 NBD server address
5625 "export: string" (optional)
5627 export name
5628 "tls-creds: string" (optional)
5630 TLS credentials ID
5631 "x-dirty-bitmap: string" (optional)
5633 A "qemu:dirty-bitmap:NAME" string to query in place of traditional
5634 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
5635 the NBD protocol) (since 3.0)
5636 "reconnect-delay: int" (optional)
5638 On an unexpected disconnect, the nbd client tries to connect again
5639 until succeeding or encountering a serious error. During the first
5640 "reconnect-delay" seconds, all requests are paused and will be
5641 rerun on a successful reconnect. After that time, any delayed
5642 requests and all future requests before a successful reconnect will
5643 immediately fail. Default 0 (Since 4.2)
5644 Since: 2.9
5646 BlockdevOptionsRaw (Object)
5648 Driver specific block device options for the raw driver.
5650 Members:
5652 "offset: int" (optional)
5654 position where the block device starts
5655 "size: int" (optional)
5657 the assumed size of the device
5658 The members of "BlockdevOptionsGenericFormat"
5660 Since: 2.9
5662 BlockdevOptionsThrottle (Object)
5664 Driver specific block device options for the throttle driver
5666 Members:
5668 "throttle-group: string"
5670 the name of the throttle-group object to use. It must already
5671 exist.
5672 "file: BlockdevRef"
5674 reference to or definition of the data source block device
5675 Since: 2.11
5677 BlockdevOptions (Object)
5679 Options for creating a block device. Many options are available for
5681 all block devices, independent of the block driver:
5682 Members:
5684 "driver: BlockdevDriver"
5686 block driver name
5687 "node-name: string" (optional)
5689 the node name of the new node (Since 2.0). This option is required
5690 on the top level of blockdev-add. Valid node names start with an
5691 alphabetic character and may contain only alphanumeric characters,
5692 '-', '.' and '_'. Their maximum length is 31 characters.
5693 "discard: BlockdevDiscardOptions" (optional)
5695 discard-related options (default: ignore)
5696 "cache: BlockdevCacheOptions" (optional)
5698 cache-related options
5699 "read-only: boolean" (optional)
5701 whether the block device should be read-only (default: false).
5702 Note that some block drivers support only read-only access, either
5703 generally or in certain configurations. In this case, the default
5704 value does not work and the option must be specified explicitly.
5705 "auto-read-only: boolean" (optional)
5707 if true and "read-only" is false, QEMU may automatically decide not
5708 to open the image read-write as requested, but fall back to read-
5709 only instead (and switch between the modes later), e.g. depending
5710 on whether the image file is writable or whether a writing user is
5711 attached to the node (default: false, since 3.1)
5712 "detect-zeroes: BlockdevDetectZeroesOptions" (optional)
5714 detect and optimize zero writes (Since 2.1) (default: off)
5715 "force-share: boolean" (optional)
5717 force share all permission on added nodes. Requires
5718 read-only=true. (Since 2.10)
5719 The members of "BlockdevOptionsBlkdebug" when "driver" is "blkdebug"
5721 The members of "BlockdevOptionsBlklogwrites" when "driver" is
5722 "blklogwrites"
5723 The members of "BlockdevOptionsBlkverify" when "driver" is "blkverify"
5724 The members of "BlockdevOptionsBlkreplay" when "driver" is "blkreplay"
5725 The members of "BlockdevOptionsGenericFormat" when "driver" is "bochs"
5726 The members of "BlockdevOptionsGenericFormat" when "driver" is "cloop"
5727 The members of "BlockdevOptionsGenericFormat" when "driver" is
5728 "compress"
5729 The members of "BlockdevOptionsGenericFormat" when "driver" is "copy-
5730 on-read"
5731 The members of "BlockdevOptionsGenericFormat" when "driver" is "dmg"
5732 The members of "BlockdevOptionsFile" when "driver" is "file"
5733 The members of "BlockdevOptionsCurlFtp" when "driver" is "ftp"
5734 The members of "BlockdevOptionsCurlFtps" when "driver" is "ftps"
5735 The members of "BlockdevOptionsGluster" when "driver" is "gluster"
5736 The members of "BlockdevOptionsFile" when "driver" is "host_cdrom"
5737 The members of "BlockdevOptionsFile" when "driver" is "host_device"
5738 The members of "BlockdevOptionsCurlHttp" when "driver" is "http"
5739 The members of "BlockdevOptionsCurlHttps" when "driver" is "https"
5740 The members of "BlockdevOptionsIscsi" when "driver" is "iscsi"
5741 The members of "BlockdevOptionsLUKS" when "driver" is "luks"
5742 The members of "BlockdevOptionsNbd" when "driver" is "nbd"
5743 The members of "BlockdevOptionsNfs" when "driver" is "nfs"
5744 The members of "BlockdevOptionsNull" when "driver" is "null-aio"
5745 The members of "BlockdevOptionsNull" when "driver" is "null-co"
5746 The members of "BlockdevOptionsNVMe" when "driver" is "nvme"
5747 The members of "BlockdevOptionsGenericFormat" when "driver" is
5748 "parallels"
5749 The members of "BlockdevOptionsQcow2" when "driver" is "qcow2"
5750 The members of "BlockdevOptionsQcow" when "driver" is "qcow"
5751 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is "qed"
5752 The members of "BlockdevOptionsQuorum" when "driver" is "quorum"
5753 The members of "BlockdevOptionsRaw" when "driver" is "raw"
5754 The members of "BlockdevOptionsRbd" when "driver" is "rbd"
5755 The members of "BlockdevOptionsReplication" when "driver" is
5756 "replication" (If: "defined(CONFIG_REPLICATION)")
5757 The members of "BlockdevOptionsSheepdog" when "driver" is "sheepdog"
5758 The members of "BlockdevOptionsSsh" when "driver" is "ssh"
5759 The members of "BlockdevOptionsThrottle" when "driver" is "throttle"
5760 The members of "BlockdevOptionsGenericFormat" when "driver" is "vdi"
5761 The members of "BlockdevOptionsGenericFormat" when "driver" is "vhdx"
5762 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is
5763 "vmdk"
5764 The members of "BlockdevOptionsGenericFormat" when "driver" is "vpc"
5765 The members of "BlockdevOptionsVVFAT" when "driver" is "vvfat"
5766 Remaining options are determined by the block driver.
5768 Since: 2.9
5770 BlockdevRef (Alternate)
5772 Reference to a block device.
5774 Members:
5776 "definition: BlockdevOptions"
5778 defines a new block device inline
5779 "reference: string"
5781 references the ID of an existing block device
5782 Since: 2.9
5784 BlockdevRefOrNull (Alternate)
5786 Reference to a block device.
5788 Members:
5790 "definition: BlockdevOptions"
5792 defines a new block device inline
5793 "reference: string"
5795 references the ID of an existing block device. An empty string
5796 means that no block device should be referenced. Deprecated; use
5797 null instead.
5798 "null: null"
5800 No block device should be referenced (since 2.10)
5801 Since: 2.9
5803 blockdev-add (Command) Creates a new block device. If the "id" option
5805 is given at the top level, a BlockBackend will be created; otherwise,
5806 "node-name" is mandatory at the top level and no BlockBackend will be
5807 created.
5808 Arguments: the members of "BlockdevOptions"
5810 Since: 2.9
5812 Example:
5814 1.
5816 -> { "execute": "blockdev-add",
5817 "arguments": {
5818 "driver": "qcow2",
5819 "node-name": "test1",
5820 "file": {
5821 "driver": "file",
5822 "filename": "test.qcow2"
5823 }
5824 }
5825 }
5826 <- { "return": {} }
5827 2.
5829 -> { "execute": "blockdev-add",
5830 "arguments": {
5831 "driver": "qcow2",
5832 "node-name": "node0",
5833 "discard": "unmap",
5834 "cache": {
5835 "direct": true
5836 },
5837 "file": {
5838 "driver": "file",
5839 "filename": "/tmp/test.qcow2"
5840 },
5841 "backing": {
5842 "driver": "raw",
5843 "file": {
5844 "driver": "file",
5845 "filename": "/dev/fdset/4"
5846 }
5847 }
5848 }
5849 }
5850 <- { "return": {} }
5852 x-blockdev-reopen (Command) Reopens a block device using the given set
5854 of options. Any option not specified will be reset to its default value
5855 regardless of its previous status. If an option cannot be changed or a
5856 particular driver does not support reopening then the command will
5857 return an error.
5858 The top-level "node-name" option (from BlockdevOptions) must be
5860 specified and is used to select the block device to be reopened. Other
5861 "node-name" options must be either omitted or set to the current name
5862 of the appropriate node. This command won't change any node name and
5863 any attempt to do it will result in an error.
5864 In the case of options that refer to child nodes, the behavior of this
5866 command depends on the value:
5867 1) A set of options (BlockdevOptions): the child is reopened with the
5869 specified set of options.
5870 2) A reference to the current child: the child is reopened using its
5872 existing set of options.
5873 3) A reference to a different node: the current child is replaced with
5875 the specified one.
5876 4) NULL: the current child (if any) is detached.
5878 Options (1) and (2) are supported in all cases, but at the moment only
5880 "backing" allows replacing or detaching an existing child.
5881 Unlike with blockdev-add, the "backing" option must always be present
5883 unless the node being reopened does not have a backing file and its
5884 image does not have a default backing file name as part of its
5885 metadata.
5886 Arguments: the members of "BlockdevOptions"
5888 Since: 4.0
5890 blockdev-del (Command) Deletes a block device that has been added
5892 using blockdev-add. The command will fail if the node is attached to a
5893 device or is otherwise being used.
5894 Arguments:
5896 "node-name: string"
5898 Name of the graph node to delete.
5899 Since: 2.9
5901 Example:
5903 -> { "execute": "blockdev-add",
5905 "arguments": {
5906 "driver": "qcow2",
5907 "node-name": "node0",
5908 "file": {
5909 "driver": "file",
5910 "filename": "test.qcow2"
5911 }
5912 }
5913 }
5914 <- { "return": {} }
5915 -> { "execute": "blockdev-del",
5917 "arguments": { "node-name": "node0" }
5918 }
5919 <- { "return": {} }
5920 BlockdevCreateOptionsFile (Object)
5922 Driver specific image creation options for file.
5924 Members:
5926 "filename: string"
5928 Filename for the new image file
5929 "size: int"
5931 Size of the virtual disk in bytes
5932 "preallocation: PreallocMode" (optional)
5934 Preallocation mode for the new image (default: off; allowed values:
5935 off, falloc (if defined CONFIG_POSIX_FALLOCATE), full (if defined
5936 CONFIG_POSIX))
5937 "nocow: boolean" (optional)
5939 Turn off copy-on-write (valid only on btrfs; default: off)
5940 "extent-size-hint: int" (optional)
5942 Extent size hint to add to the image file; 0 for not adding an
5943 extent size hint (default: 1 MB, since 5.1)
5944 Since: 2.12
5946 BlockdevCreateOptionsGluster (Object)
5948 Driver specific image creation options for gluster.
5950 Members:
5952 "location: BlockdevOptionsGluster"
5954 Where to store the new image file
5955 "size: int"
5957 Size of the virtual disk in bytes
5958 "preallocation: PreallocMode" (optional)
5960 Preallocation mode for the new image (default: off; allowed values:
5961 off, falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), full (if
5962 defined CONFIG_GLUSTERFS_ZEROFILL))
5963 Since: 2.12
5965 BlockdevCreateOptionsLUKS (Object)
5967 Driver specific image creation options for LUKS.
5969 Members:
5971 "file: BlockdevRef"
5973 Node to create the image format on
5974 "size: int"
5976 Size of the virtual disk in bytes
5977 "preallocation: PreallocMode" (optional)
5979 Preallocation mode for the new image (since: 4.2) (default: off;
5980 allowed values: off, metadata, falloc, full)
5981 The members of "QCryptoBlockCreateOptionsLUKS"
5983 Since: 2.12
5985 BlockdevCreateOptionsNfs (Object)
5987 Driver specific image creation options for NFS.
5989 Members:
5991 "location: BlockdevOptionsNfs"
5993 Where to store the new image file
5994 "size: int"
5996 Size of the virtual disk in bytes
5997 Since: 2.12
5999 BlockdevCreateOptionsParallels (Object)
6001 Driver specific image creation options for parallels.
6003 Members:
6005 "file: BlockdevRef"
6007 Node to create the image format on
6008 "size: int"
6010 Size of the virtual disk in bytes
6011 "cluster-size: int" (optional)
6013 Cluster size in bytes (default: 1 MB)
6014 Since: 2.12
6016 BlockdevCreateOptionsQcow (Object)
6018 Driver specific image creation options for qcow.
6020 Members:
6022 "file: BlockdevRef"
6024 Node to create the image format on
6025 "size: int"
6027 Size of the virtual disk in bytes
6028 "backing-file: string" (optional)
6030 File name of the backing file if a backing file should be used
6031 "encrypt: QCryptoBlockCreateOptions" (optional)
6033 Encryption options if the image should be encrypted
6034 Since: 2.12
6036 BlockdevQcow2Version (Enum)
6038 Values:
6040 "v2"
6042 The original QCOW2 format as introduced in qemu 0.10 (version 2)
6043 "v3"
6045 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
6046 Since: 2.12
6048 Qcow2CompressionType (Enum)
6050 Compression type used in qcow2 image file
6052 Values:
6054 "zlib"
6056 zlib compression, see <http://zlib.net/>
6057 "zstd"
6059 zstd compression, see <http://github.com/facebook/zstd> If:
6060 "defined(CONFIG_ZSTD)"
6061 Since: 5.1
6063 BlockdevCreateOptionsQcow2 (Object)
6065 Driver specific image creation options for qcow2.
6067 Members:
6069 "file: BlockdevRef"
6071 Node to create the image format on
6072 "data-file: BlockdevRef" (optional)
6074 Node to use as an external data file in which all guest data is
6075 stored so that only metadata remains in the qcow2 file (since: 4.0)
6076 "data-file-raw: boolean" (optional)
6078 True if the external data file must stay valid as a standalone
6079 (read-only) raw image without looking at qcow2 metadata (default:
6080 false; since: 4.0)
6081 "size: int"
6083 Size of the virtual disk in bytes
6084 "version: BlockdevQcow2Version" (optional)
6086 Compatibility level (default: v3)
6087 "backing-file: string" (optional)
6089 File name of the backing file if a backing file should be used
6090 "backing-fmt: BlockdevDriver" (optional)
6092 Name of the block driver to use for the backing file
6093 "encrypt: QCryptoBlockCreateOptions" (optional)
6095 Encryption options if the image should be encrypted
6096 "cluster-size: int" (optional)
6098 qcow2 cluster size in bytes (default: 65536)
6099 "preallocation: PreallocMode" (optional)
6101 Preallocation mode for the new image (default: off; allowed values:
6102 off, falloc, full, metadata)
6103 "lazy-refcounts: boolean" (optional)
6105 True if refcounts may be updated lazily (default: off)
6106 "refcount-bits: int" (optional)
6108 Width of reference counts in bits (default: 16)
6109 "compression-type: Qcow2CompressionType" (optional)
6111 The image cluster compression method (default: zlib, since 5.1)
6112 Since: 2.12
6114 BlockdevCreateOptionsQed (Object)
6116 Driver specific image creation options for qed.
6118 Members:
6120 "file: BlockdevRef"
6122 Node to create the image format on
6123 "size: int"
6125 Size of the virtual disk in bytes
6126 "backing-file: string" (optional)
6128 File name of the backing file if a backing file should be used
6129 "backing-fmt: BlockdevDriver" (optional)
6131 Name of the block driver to use for the backing file
6132 "cluster-size: int" (optional)
6134 Cluster size in bytes (default: 65536)
6135 "table-size: int" (optional)
6137 L1/L2 table size (in clusters)
6138 Since: 2.12
6140 BlockdevCreateOptionsRbd (Object)
6142 Driver specific image creation options for rbd/Ceph.
6144 Members:
6146 "location: BlockdevOptionsRbd"
6148 Where to store the new image file. This location cannot point to a
6149 snapshot.
6150 "size: int"
6152 Size of the virtual disk in bytes
6153 "cluster-size: int" (optional)
6155 RBD object size
6156 Since: 2.12
6158 BlockdevVmdkSubformat (Enum)
6160 Subformat options for VMDK images
6162 Values:
6164 "monolithicSparse"
6166 Single file image with sparse cluster allocation
6167 "monolithicFlat"
6169 Single flat data image and a descriptor file
6170 "twoGbMaxExtentSparse"
6172 Data is split into 2GB (per virtual LBA) sparse extent files, in
6173 addition to a descriptor file
6174 "twoGbMaxExtentFlat"
6176 Data is split into 2GB (per virtual LBA) flat extent files, in
6177 addition to a descriptor file
6178 "streamOptimized"
6180 Single file image sparse cluster allocation, optimized for
6181 streaming over network.
6182 Since: 4.0
6184 BlockdevVmdkAdapterType (Enum)
6186 Adapter type info for VMDK images
6188 Values:
6190 "ide"
6192 Not documented
6193 "buslogic"
6195 Not documented
6196 "lsilogic"
6198 Not documented
6199 "legacyESX"
6201 Not documented
6202 Since: 4.0
6204 BlockdevCreateOptionsVmdk (Object)
6206 Driver specific image creation options for VMDK.
6208 Members:
6210 "file: BlockdevRef"
6212 Where to store the new image file. This refers to the image file
6213 for monolithcSparse and streamOptimized format, or the descriptor
6214 file for other formats.
6215 "size: int"
6217 Size of the virtual disk in bytes
6218 "extents: array of BlockdevRef" (optional)
6220 Where to store the data extents. Required for monolithcFlat,
6221 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For
6222 monolithicFlat, only one entry is required; for twoGbMaxExtent*
6223 formats, the number of entries required is calculated as
6224 extent_number = virtual_size / 2GB. Providing more extents than
6225 will be used is an error.
6226 "subformat: BlockdevVmdkSubformat" (optional)
6228 The subformat of the VMDK image. Default: "monolithicSparse".
6229 "backing-file: string" (optional)
6231 The path of backing file. Default: no backing file is used.
6232 "adapter-type: BlockdevVmdkAdapterType" (optional)
6234 The adapter type used to fill in the descriptor. Default: ide.
6235 "hwversion: string" (optional)
6237 Hardware version. The meaningful options are "4" or "6". Default:
6238 "4".
6239 "zeroed-grain: boolean" (optional)
6241 Whether to enable zeroed-grain feature for sparse subformats.
6242 Default: false.
6243 Since: 4.0
6245 SheepdogRedundancyType (Enum)
6247 Values:
6249 "full"
6251 Create a fully replicated vdi with x copies
6252 "erasure-coded"
6254 Create an erasure coded vdi with x data strips and y parity strips
6255 Since: 2.12
6257 SheepdogRedundancyFull (Object)
6259 Members:
6261 "copies: int"
6263 Number of copies to use (between 1 and 31)
6264 Since: 2.12
6266 SheepdogRedundancyErasureCoded (Object)
6268 Members:
6270 "data-strips: int"
6272 Number of data strips to use (one of {2,4,8,16})
6273 "parity-strips: int"
6275 Number of parity strips to use (between 1 and 15)
6276 Since: 2.12
6278 SheepdogRedundancy (Object)
6280 Members:
6282 "type: SheepdogRedundancyType"
6284 Not documented
6285 The members of "SheepdogRedundancyFull" when "type" is "full"
6287 The members of "SheepdogRedundancyErasureCoded" when "type" is
6288 "erasure-coded"
6289 Since: 2.12
6291 BlockdevCreateOptionsSheepdog (Object)
6293 Driver specific image creation options for Sheepdog.
6295 Members:
6297 "location: BlockdevOptionsSheepdog"
6299 Where to store the new image file
6300 "size: int"
6302 Size of the virtual disk in bytes
6303 "backing-file: string" (optional)
6305 File name of a base image
6306 "preallocation: PreallocMode" (optional)
6308 Preallocation mode for the new image (default: off; allowed values:
6309 off, full)
6310 "redundancy: SheepdogRedundancy" (optional)
6312 Redundancy of the image
6313 "object-size: int" (optional)
6315 Object size of the image
6316 Since: 2.12
6318 BlockdevCreateOptionsSsh (Object)
6320 Driver specific image creation options for SSH.
6322 Members:
6324 "location: BlockdevOptionsSsh"
6326 Where to store the new image file
6327 "size: int"
6329 Size of the virtual disk in bytes
6330 Since: 2.12
6332 BlockdevCreateOptionsVdi (Object)
6334 Driver specific image creation options for VDI.
6336 Members:
6338 "file: BlockdevRef"
6340 Node to create the image format on
6341 "size: int"
6343 Size of the virtual disk in bytes
6344 "preallocation: PreallocMode" (optional)
6346 Preallocation mode for the new image (default: off; allowed values:
6347 off, metadata)
6348 Since: 2.12
6350 BlockdevVhdxSubformat (Enum)
6352 Values:
6354 "dynamic"
6356 Growing image file
6357 "fixed"
6359 Preallocated fixed-size image file
6360 Since: 2.12
6362 BlockdevCreateOptionsVhdx (Object)
6364 Driver specific image creation options for vhdx.
6366 Members:
6368 "file: BlockdevRef"
6370 Node to create the image format on
6371 "size: int"
6373 Size of the virtual disk in bytes
6374 "log-size: int" (optional)
6376 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
6377 "block-size: int" (optional)
6379 Block size in bytes, must be a multiple of 1 MB and not larger than
6380 256 MB (default: automatically choose a block size depending on the
6381 image size)
6382 "subformat: BlockdevVhdxSubformat" (optional)
6384 vhdx subformat (default: dynamic)
6385 "block-state-zero: boolean" (optional)
6387 Force use of payload blocks of type 'ZERO'. Non-standard, but
6388 default. Do not set to 'off' when using 'qemu-img convert' with
6389 subformat=dynamic.
6390 Since: 2.12
6392 BlockdevVpcSubformat (Enum)
6394 Values:
6396 "dynamic"
6398 Growing image file
6399 "fixed"
6401 Preallocated fixed-size image file
6402 Since: 2.12
6404 BlockdevCreateOptionsVpc (Object)
6406 Driver specific image creation options for vpc (VHD).
6408 Members:
6410 "file: BlockdevRef"
6412 Node to create the image format on
6413 "size: int"
6415 Size of the virtual disk in bytes
6416 "subformat: BlockdevVpcSubformat" (optional)
6418 vhdx subformat (default: dynamic)
6419 "force-size: boolean" (optional)
6421 Force use of the exact byte size instead of rounding to the next
6422 size that can be represented in CHS geometry (default: false)
6423 Since: 2.12
6425 BlockdevCreateOptions (Object)
6427 Options for creating an image format on a given node.
6429 Members:
6431 "driver: BlockdevDriver"
6433 block driver to create the image format
6434 The members of "BlockdevCreateOptionsFile" when "driver" is "file"
6436 The members of "BlockdevCreateOptionsGluster" when "driver" is
6437 "gluster"
6438 The members of "BlockdevCreateOptionsLUKS" when "driver" is "luks"
6439 The members of "BlockdevCreateOptionsNfs" when "driver" is "nfs"
6440 The members of "BlockdevCreateOptionsParallels" when "driver" is
6441 "parallels"
6442 The members of "BlockdevCreateOptionsQcow" when "driver" is "qcow"
6443 The members of "BlockdevCreateOptionsQcow2" when "driver" is "qcow2"
6444 The members of "BlockdevCreateOptionsQed" when "driver" is "qed"
6445 The members of "BlockdevCreateOptionsRbd" when "driver" is "rbd"
6446 The members of "BlockdevCreateOptionsSheepdog" when "driver" is
6447 "sheepdog"
6448 The members of "BlockdevCreateOptionsSsh" when "driver" is "ssh"
6449 The members of "BlockdevCreateOptionsVdi" when "driver" is "vdi"
6450 The members of "BlockdevCreateOptionsVhdx" when "driver" is "vhdx"
6451 The members of "BlockdevCreateOptionsVmdk" when "driver" is "vmdk"
6452 The members of "BlockdevCreateOptionsVpc" when "driver" is "vpc"
6453 Since: 2.12
6455 blockdev-create (Command) Starts a job to create an image format on a
6457 given node. The job is automatically finalized, but a manual job-
6458 dismiss is required.
6459 Arguments:
6461 "job-id: string"
6463 Identifier for the newly created job.
6464 "options: BlockdevCreateOptions"
6466 Options for the image creation.
6467 Since: 3.0
6469 BlockdevAmendOptionsLUKS (Object)
6471 Driver specific image amend options for LUKS.
6473 Members:
6475 The members of "QCryptoBlockAmendOptionsLUKS"
6477 Since: 5.1
6479 BlockdevAmendOptionsQcow2 (Object)
6481 Driver specific image amend options for qcow2. For now, only
6483 encryption options can be amended
6484 "encrypt" Encryption options to be amended
6486 Members:
6488 "encrypt: QCryptoBlockAmendOptions" (optional)
6490 Not documented
6491 Since: 5.1
6493 BlockdevAmendOptions (Object)
6495 Options for amending an image format
6497 Members:
6499 "driver: BlockdevDriver"
6501 Block driver of the node to amend.
6502 The members of "BlockdevAmendOptionsLUKS" when "driver" is "luks"
6504 The members of "BlockdevAmendOptionsQcow2" when "driver" is "qcow2"
6505 Since: 5.1
6507 x-blockdev-amend (Command) Starts a job to amend format specific
6509 options of an existing open block device The job is automatically
6510 finalized, but a manual job-dismiss is required.
6511 Arguments:
6513 "job-id: string"
6515 Identifier for the newly created job.
6516 "node-name: string"
6518 Name of the block node to work on
6519 "options: BlockdevAmendOptions"
6521 Options (driver specific)
6522 "force: boolean" (optional)
6524 Allow unsafe operations, format specific For luks that allows erase
6525 of the last active keyslot (permanent loss of data), and
6526 replacement of an active keyslot (possible loss of data if IO error
6527 happens)
6528 Since: 5.1
6530 BlockErrorAction (Enum)
6532 An enumeration of action that has been taken when a DISK I/O occurs
6534 Values:
6536 "ignore"
6538 error has been ignored
6539 "report"
6541 error has been reported to the device
6542 "stop"
6544 error caused VM to be stopped
6545 Since: 2.1
6547 BLOCK_IMAGE_CORRUPTED (Event) Emitted when a disk image is being
6549 marked corrupt. The image can be identified by its device or node name.
6550 The 'device' field is always present for compatibility reasons, but it
6551 can be empty ("") if the image does not have a device name associated.
6552 Arguments:
6554 "device: string"
6556 device name. This is always present for compatibility reasons, but
6557 it can be empty ("") if the image does not have a device name
6558 associated.
6559 "node-name: string" (optional)
6561 node name (Since: 2.4)
6562 "msg: string"
6564 informative message for human consumption, such as the kind of
6565 corruption being detected. It should not be parsed by machine as it
6566 is not guaranteed to be stable
6567 "offset: int" (optional)
6569 if the corruption resulted from an image access, this is the host's
6570 access offset into the image
6571 "size: int" (optional)
6573 if the corruption resulted from an image access, this is the access
6574 size
6575 "fatal: boolean"
6577 if set, the image is marked corrupt and therefore unusable after
6578 this event and must be repaired (Since 2.2; before, every
6579 BLOCK_IMAGE_CORRUPTED event was fatal)
6580 Note: If action is "stop", a STOP event will eventually follow the
6582 BLOCK_IO_ERROR event.
6583 Example:
6585 <- { "event": "BLOCK_IMAGE_CORRUPTED",
6587 "data": { "device": "ide0-hd0", "node-name": "node0",
6588 "msg": "Prevented active L1 table overwrite", "offset": 196608,
6589 "size": 65536 },
6590 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
6591 Since: 1.7
6593 BLOCK_IO_ERROR (Event) Emitted when a disk I/O error occurs
6595 Arguments:
6597 "device: string"
6599 device name. This is always present for compatibility reasons, but
6600 it can be empty ("") if the image does not have a device name
6601 associated.
6602 "node-name: string" (optional)
6604 node name. Note that errors may be reported for the root node that
6605 is directly attached to a guest device rather than for the node
6606 where the error occurred. The node name is not present if the drive
6607 is empty. (Since: 2.8)
6608 "operation: IoOperationType"
6610 I/O operation
6611 "action: BlockErrorAction"
6613 action that has been taken
6614 "nospace: boolean" (optional)
6616 true if I/O error was caused due to a no-space condition. This key
6617 is only present if query-block's io-status is present, please see
6618 query-block documentation for more information (since: 2.2)
6619 "reason: string"
6621 human readable string describing the error cause. (This field is a
6622 debugging aid for humans, it should not be parsed by applications)
6623 (since: 2.2)
6624 Note: If action is "stop", a STOP event will eventually follow the
6626 BLOCK_IO_ERROR event
6627 Since: 0.13.0
6629 Example:
6631 <- { "event": "BLOCK_IO_ERROR",
6633 "data": { "device": "ide0-hd1",
6634 "node-name": "#block212",
6635 "operation": "write",
6636 "action": "stop" },
6637 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6638 BLOCK_JOB_COMPLETED (Event) Emitted when a block job has completed
6640 Arguments:
6642 "type: JobType"
6644 job type
6645 "device: string"
6647 The job identifier. Originally the device name but other values are
6648 allowed since QEMU 2.7
6649 "len: int"
6651 maximum progress value
6652 "offset: int"
6654 current progress value. On success this is equal to len. On
6655 failure this is less than len
6656 "speed: int"
6658 rate limit, bytes per second
6659 "error: string" (optional)
6661 error message. Only present on failure. This field contains a
6662 human-readable error message. There are no semantics other than
6663 that streaming has failed and clients should not try to interpret
6664 the error string
6665 Since: 1.1
6667 Example:
6669 <- { "event": "BLOCK_JOB_COMPLETED",
6671 "data": { "type": "stream", "device": "virtio-disk0",
6672 "len": 10737418240, "offset": 10737418240,
6673 "speed": 0 },
6674 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6675 BLOCK_JOB_CANCELLED (Event) Emitted when a block job has been
6677 cancelled
6678 Arguments:
6680 "type: JobType"
6682 job type
6683 "device: string"
6685 The job identifier. Originally the device name but other values are
6686 allowed since QEMU 2.7
6687 "len: int"
6689 maximum progress value
6690 "offset: int"
6692 current progress value. On success this is equal to len. On
6693 failure this is less than len
6694 "speed: int"
6696 rate limit, bytes per second
6697 Since: 1.1
6699 Example:
6701 <- { "event": "BLOCK_JOB_CANCELLED",
6703 "data": { "type": "stream", "device": "virtio-disk0",
6704 "len": 10737418240, "offset": 134217728,
6705 "speed": 0 },
6706 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6707 BLOCK_JOB_ERROR (Event) Emitted when a block job encounters an error
6709 Arguments:
6711 "device: string"
6713 The job identifier. Originally the device name but other values are
6714 allowed since QEMU 2.7
6715 "operation: IoOperationType"
6717 I/O operation
6718 "action: BlockErrorAction"
6720 action that has been taken
6721 Since: 1.3
6723 Example:
6725 <- { "event": "BLOCK_JOB_ERROR",
6727 "data": { "device": "ide0-hd1",
6728 "operation": "write",
6729 "action": "stop" },
6730 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6731 BLOCK_JOB_READY (Event) Emitted when a block job is ready to complete
6733 Arguments:
6735 "type: JobType"
6737 job type
6738 "device: string"
6740 The job identifier. Originally the device name but other values are
6741 allowed since QEMU 2.7
6742 "len: int"
6744 maximum progress value
6745 "offset: int"
6747 current progress value. On success this is equal to len. On
6748 failure this is less than len
6749 "speed: int"
6751 rate limit, bytes per second
6752 Note: The "ready to complete" status is always reset by a
6754 "BLOCK_JOB_ERROR" event
6755 Since: 1.3
6757 Example:
6759 <- { "event": "BLOCK_JOB_READY",
6761 "data": { "device": "drive0", "type": "mirror", "speed": 0,
6762 "len": 2097152, "offset": 2097152 }
6763 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6764 BLOCK_JOB_PENDING (Event) Emitted when a block job is awaiting
6766 explicit authorization to finalize graph changes via
6767 "block-job-finalize". If this job is part of a transaction, it will not
6768 emit this event until the transaction has converged first.
6769 Arguments:
6771 "type: JobType"
6773 job type
6774 "id: string"
6776 The job identifier.
6777 Since: 2.12
6779 Example:
6781 <- { "event": "BLOCK_JOB_WAITING",
6783 "data": { "device": "drive0", "type": "mirror" },
6784 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6785 PreallocMode (Enum)
6787 Preallocation mode of QEMU image file
6789 Values:
6791 "off"
6793 no preallocation
6794 "metadata"
6796 preallocate only for metadata
6797 "falloc"
6799 like "full" preallocation but allocate disk space by
6800 posix_fallocate() rather than writing data.
6801 "full"
6803 preallocate all data by writing it to the device to ensure disk
6804 space is really available. This data may or may not be zero,
6805 depending on the image format and storage. "full" preallocation
6806 also sets up metadata correctly.
6807 Since: 2.2
6809 BLOCK_WRITE_THRESHOLD (Event) Emitted when writes on block device
6811 reaches or exceeds the configured write threshold. For thin-provisioned
6812 devices, this means the device should be extended to avoid pausing for
6813 disk exhaustion. The event is one shot. Once triggered, it needs to be
6814 re-registered with another block-set-write-threshold command.
6815 Arguments:
6817 "node-name: string"
6819 graph node name on which the threshold was exceeded.
6820 "amount-exceeded: int"
6822 amount of data which exceeded the threshold, in bytes.
6823 "write-threshold: int"
6825 last configured threshold, in bytes.
6826 Since: 2.3
6828 block-set-write-threshold (Command) Change the write threshold for a
6830 block drive. An event will be delivered if a write to this block drive
6831 crosses the configured threshold. The threshold is an offset, thus
6832 must be non-negative. Default is no write threshold. Setting the
6833 threshold to zero disables it.
6834 This is useful to transparently resize thin-provisioned drives without
6836 the guest OS noticing.
6837 Arguments:
6839 "node-name: string"
6841 graph node name on which the threshold must be set.
6842 "write-threshold: int"
6844 configured threshold for the block device, bytes. Use 0 to disable
6845 the threshold.
6846 Since: 2.3
6848 Example:
6850 -> { "execute": "block-set-write-threshold",
6852 "arguments": { "node-name": "mydev",
6853 "write-threshold": 17179869184 } }
6854 <- { "return": {} }
6855 x-blockdev-change (Command) Dynamically reconfigure the block driver
6857 state graph. It can be used to add, remove, insert or replace a graph
6858 node. Currently only the Quorum driver implements this feature to add
6859 or remove its child. This is useful to fix a broken quorum child.
6860 If "node" is specified, it will be inserted under "parent". "child" may
6862 not be specified in this case. If both "parent" and "child" are
6863 specified but "node" is not, "child" will be detached from "parent".
6864 Arguments:
6866 "parent: string"
6868 the id or name of the parent node.
6869 "child: string" (optional)
6871 the name of a child under the given parent node.
6872 "node: string" (optional)
6874 the name of the node that will be added.
6875 Note: this command is experimental, and its API is not stable. It does
6877 not support all kinds of operations, all kinds of children, nor all
6878 block drivers.
6879 FIXME Removing children from a quorum node means introducing gaps in
6881 the child indices. This cannot be represented in the 'children' list of
6882 BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
6883 Warning: The data in a new quorum child MUST be consistent with that of
6885 the rest of the array.
6886 Since: 2.7
6888 Example:
6890 1. Add a new node to a quorum
6892 -> { "execute": "blockdev-add",
6893 "arguments": {
6894 "driver": "raw",
6895 "node-name": "new_node",
6896 "file": { "driver": "file",
6897 "filename": "test.raw" } } }
6898 <- { "return": {} }
6899 -> { "execute": "x-blockdev-change",
6900 "arguments": { "parent": "disk1",
6901 "node": "new_node" } }
6902 <- { "return": {} }
6903 2. Delete a quorum's node
6905 -> { "execute": "x-blockdev-change",
6906 "arguments": { "parent": "disk1",
6907 "child": "children.1" } }
6908 <- { "return": {} }
6909 x-blockdev-set-iothread (Command) Move "node" and its children into
6911 the "iothread". If "iothread" is null then move "node" and its
6912 children into the main loop.
6913 The node must not be attached to a BlockBackend.
6915 Arguments:
6917 "node-name: string"
6919 the name of the block driver node
6920 "iothread: StrOrNull"
6922 the name of the IOThread object or null for the main loop
6923 "force: boolean" (optional)
6925 true if the node and its children should be moved when a
6926 BlockBackend is already attached
6927 Note: this command is experimental and intended for test cases that
6929 need control over IOThreads only.
6930 Since: 2.12
6932 Example:
6934 1. Move a node into an IOThread
6936 -> { "execute": "x-blockdev-set-iothread",
6937 "arguments": { "node-name": "disk1",
6938 "iothread": "iothread0" } }
6939 <- { "return": {} }
6940 2. Move a node into the main loop
6942 -> { "execute": "x-blockdev-set-iothread",
6943 "arguments": { "node-name": "disk1",
6944 "iothread": null } }
6945 <- { "return": {} }
6946 NbdServerOptions (Object)
6948 Members:
6950 "addr: SocketAddress"
6952 Address on which to listen.
6953 "tls-creds: string" (optional)
6955 ID of the TLS credentials object (since 2.6).
6956 "tls-authz: string" (optional)
6958 ID of the QAuthZ authorization object used to validate the client's
6959 x509 distinguished name. This object is is only resolved at time of
6960 use, so can be deleted and recreated on the fly while the NBD
6961 server is active. If missing, it will default to denying access
6962 (since 4.0).
6963 Keep this type consistent with the nbd-server-start arguments. The only
6965 intended difference is using SocketAddress instead of
6966 SocketAddressLegacy.
6967 Since: 4.2
6969 nbd-server-start (Command) Start an NBD server listening on the given
6971 host and port. Block devices can then be exported using
6972 "nbd-server-add". The NBD server will present them as named exports;
6973 for example, another QEMU instance could refer to them as
6974 "nbd:HOST:PORT:exportname=NAME".
6975 Arguments:
6977 "addr: SocketAddressLegacy"
6979 Address on which to listen.
6980 "tls-creds: string" (optional)
6982 ID of the TLS credentials object (since 2.6).
6983 "tls-authz: string" (optional)
6985 ID of the QAuthZ authorization object used to validate the client's
6986 x509 distinguished name. This object is is only resolved at time of
6987 use, so can be deleted and recreated on the fly while the NBD
6988 server is active. If missing, it will default to denying access
6989 (since 4.0).
6990 Returns: error if the server is already running.
6992 Keep this type consistent with the NbdServerOptions type. The only
6994 intended difference is using SocketAddressLegacy instead of
6995 SocketAddress.
6996 Since: 1.3.0
6998 BlockExportNbd (Object)
7000 An NBD block export.
7002 Members:
7004 "device: string"
7006 The device name or node name of the node to be exported
7007 "name: string" (optional)
7009 Export name. If unspecified, the "device" parameter is used as the
7010 export name. (Since 2.12)
7011 "description: string" (optional)
7013 Free-form description of the export, up to 4096 bytes. (Since 5.0)
7014 "writable: boolean" (optional)
7016 Whether clients should be able to write to the device via the NBD
7017 connection (default false).
7018 "bitmap: string" (optional)
7020 Also export the dirty bitmap reachable from "device", so the NBD
7021 client can use NBD_OPT_SET_META_CONTEXT with
7022 "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0)
7023 Since: 5.0
7025 nbd-server-add (Command) Export a block node to QEMU's embedded NBD
7027 server.
7028 Arguments: the members of "BlockExportNbd"
7030 Returns: error if the server is not running, or export with the same
7032 name already exists.
7033 Since: 1.3.0
7035 NbdServerRemoveMode (Enum)
7037 Mode for removing an NBD export.
7039 Values:
7041 "safe"
7043 Remove export if there are no existing connections, fail otherwise.
7044 "hard"
7046 Drop all connections immediately and remove export.
7047 Potential additional modes to be added in the future:
7049 hide: Just hide export from new clients, leave existing connections as
7051 is. Remove export after all clients are disconnected.
7052 soft: Hide export from new clients, answer with ESHUTDOWN for all
7054 further requests from existing clients.
7055 Since: 2.12
7057 nbd-server-remove (Command) Remove NBD export by name.
7059 Arguments:
7061 "name: string"
7063 Export name.
7064 "mode: NbdServerRemoveMode" (optional)
7066 Mode of command operation. See "NbdServerRemoveMode" description.
7067 Default is 'safe'.
7068 Returns: error if
7070 - the server is not running
7072 - export is not found
7074 - mode is 'safe' and there are existing connections
7076 Since: 2.12
7078 nbd-server-stop (Command) Stop QEMU's embedded NBD server, and
7080 unregister all devices previously added via "nbd-server-add".
7081 Since: 1.3.0
7083 BlockExportType (Enum)
7085 An enumeration of block export types
7087 Values:
7089 "nbd"
7091 NBD export
7092 Since: 4.2
7094 BlockExport (Object)
7096 Describes a block export, i.e. how single node should be exported on an
7098 external interface.
7099 Members:
7101 "type: BlockExportType"
7103 Not documented
7104 The members of "BlockExportNbd" when "type" is "nbd"
7106 Since: 4.2
7108 QuorumOpType (Enum)
7110 An enumeration of the quorum operation types
7112 Values:
7114 "read"
7116 read operation
7117 "write"
7119 write operation
7120 "flush"
7122 flush operation
7123 Since: 2.6
7125 QUORUM_FAILURE (Event) Emitted by the Quorum block driver if it fails
7127 to establish a quorum
7128 Arguments:
7130 "reference: string"
7132 device name if defined else node name
7133 "sector-num: int"
7135 number of the first sector of the failed read operation
7136 "sectors-count: int"
7138 failed read operation sector count
7139 Note: This event is rate-limited.
7141 Since: 2.0
7143 Example:
7145 <- { "event": "QUORUM_FAILURE",
7147 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7148 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7149 QUORUM_REPORT_BAD (Event) Emitted to report a corruption of a Quorum
7151 file
7152 Arguments:
7154 "type: QuorumOpType"
7156 quorum operation type (Since 2.6)
7157 "error: string" (optional)
7159 error message. Only present on failure. This field contains a
7160 human-readable error message. There are no semantics other than
7161 that the block layer reported an error and clients should not try
7162 to interpret the error string.
7163 "node-name: string"
7165 the graph node name of the block driver state
7166 "sector-num: int"
7168 number of the first sector of the failed read operation
7169 "sectors-count: int"
7171 failed read operation sector count
7172 Note: This event is rate-limited.
7174 Since: 2.0
7176 Example:
7178 1. Read operation
7180 { "event": "QUORUM_REPORT_BAD",
7182 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7183 "type": "read" },
7184 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7185 2. Flush operation
7187 { "event": "QUORUM_REPORT_BAD",
7189 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7190 "type": "flush", "error": "Broken pipe" },
7191 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7192 BlockdevSnapshotInternal (Object)
7194 Members:
7196 "device: string"
7198 the device name or node-name of a root node to generate the
7199 snapshot from
7200 "name: string"
7202 the name of the internal snapshot to be created
7203 Notes: In transaction, if "name" is empty, or any snapshot matching
7205 "name" exists, the operation will fail. Only some image formats support
7206 it, for example, qcow2, rbd, and sheepdog.
7207 Since: 1.7
7209 blockdev-snapshot-internal-sync (Command) Synchronously take an
7211 internal snapshot of a block device, when the format of the image used
7212 supports it. If the name is an empty string, or a snapshot with name
7213 already exists, the operation will fail.
7214 For the arguments, see the documentation of BlockdevSnapshotInternal.
7216 Returns:
7218 - nothing on success
7220 - If "device" is not a valid block device, GenericError
7222 - If any snapshot matching "name" exists, or "name" is empty,
7224 GenericError
7225 - If the format of the image used does not support it,
7227 BlockFormatFeatureNotSupported
7228 Since: 1.7
7230 Example:
7232 -> { "execute": "blockdev-snapshot-internal-sync",
7234 "arguments": { "device": "ide-hd0",
7235 "name": "snapshot0" }
7236 }
7237 <- { "return": {} }
7238 blockdev-snapshot-delete-internal-sync (Command) Synchronously delete
7240 an internal snapshot of a block device, when the format of the image
7241 used support it. The snapshot is identified by name or id or both. One
7242 of the name or id is required. Return SnapshotInfo for the successfully
7243 deleted snapshot.
7244 Arguments:
7246 "device: string"
7248 the device name or node-name of a root node to delete the snapshot
7249 from
7250 "id: string" (optional)
7252 optional the snapshot's ID to be deleted
7253 "name: string" (optional)
7255 optional the snapshot's name to be deleted
7256 Returns:
7258 - SnapshotInfo on success
7260 - If "device" is not a valid block device, GenericError
7262 - If snapshot not found, GenericError
7264 - If the format of the image used does not support it,
7266 BlockFormatFeatureNotSupported
7267 - If "id" and "name" are both not specified, GenericError
7269 Since: 1.7
7271 Example:
7273 -> { "execute": "blockdev-snapshot-delete-internal-sync",
7275 "arguments": { "device": "ide-hd0",
7276 "name": "snapshot0" }
7277 }
7278 <- { "return": {
7279 "id": "1",
7280 "name": "snapshot0",
7281 "vm-state-size": 0,
7282 "date-sec": 1000012,
7283 "date-nsec": 10,
7284 "vm-clock-sec": 100,
7285 "vm-clock-nsec": 20
7286 }
7287 }
7288 Additional block stuff (VM related)
7290 BiosAtaTranslation (Enum)
7292 Policy that BIOS should use to interpret cylinder/head/sector
7294 addresses. Note that Bochs BIOS and SeaBIOS will not actually
7295 translate logical CHS to physical; instead, they will use logical block
7296 addressing.
7297 Values:
7299 "auto"
7301 If cylinder/heads/sizes are passed, choose between none and LBA
7302 depending on the size of the disk. If they are not passed, choose
7303 none if QEMU can guess that the disk had 16 or fewer heads, large
7304 if QEMU can guess that the disk had 131072 or fewer tracks across
7305 all heads (i.e. cylinders*heads<131072), otherwise LBA.
7306 "none"
7308 The physical disk geometry is equal to the logical geometry.
7309 "lba"
7311 Assume 63 sectors per track and one of 16, 32, 64, 128 or 255 heads
7312 (if fewer than 255 are enough to cover the whole disk with 1024
7313 cylinders/head). The number of cylinders/head is then computed
7314 based on the number of sectors and heads.
7315 "large"
7317 The number of cylinders per head is scaled down to 1024 by
7318 correspondingly scaling up the number of heads.
7319 "rechs"
7321 Same as "large", but first convert a 16-head geometry to 15-head,
7322 by proportionally scaling up the number of cylinders/head.
7323 Since: 2.0
7325 FloppyDriveType (Enum)
7327 Type of Floppy drive to be emulated by the Floppy Disk Controller.
7329 Values:
7331 144 1.44MB 3.5" drive
7333 288 2.88MB 3.5" drive
7335 120 1.2MB 5.25" drive
7337 "none"
7339 No drive connected
7340 "auto"
7342 Automatically determined by inserted media at boot
7343 Since: 2.6
7345 PRManagerInfo (Object)
7347 Information about a persistent reservation manager
7349 Members:
7351 "id: string"
7353 the identifier of the persistent reservation manager
7354 "connected: boolean"
7356 true if the persistent reservation manager is connected to the
7357 underlying storage or helper
7358 Since: 3.0
7360 query-pr-managers (Command) Returns a list of information about each
7362 persistent reservation manager.
7363 Returns: a list of "PRManagerInfo" for each persistent reservation
7365 manager
7366 Since: 3.0
7368 eject (Command) Ejects the medium from a removable drive.
7370 Arguments:
7372 "device: string" (optional)
7374 Block device name
7375 "id: string" (optional)
7377 The name or QOM path of the guest device (since: 2.8)
7378 "force: boolean" (optional)
7380 If true, eject regardless of whether the drive is locked. If not
7381 specified, the default value is false.
7382 Features:
7384 "deprecated"
7386 Member "device" is deprecated. Use "id" instead.
7387 Returns:
7389 - Nothing on success
7391 - If "device" is not a valid block device, DeviceNotFound
7393 Notes: Ejecting a device with no media results in success
7395 Since: 0.14.0
7397 Example:
7399 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
7401 <- { "return": {} }
7402 blockdev-open-tray (Command) Opens a block device's tray. If there is
7404 a block driver state tree inserted as a medium, it will become
7405 inaccessible to the guest (but it will remain associated to the block
7406 device, so closing the tray will make it accessible again).
7407 If the tray was already open before, this will be a no-op.
7409 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
7411 cases in which no such event will be generated, these include:
7412 - if the guest has locked the tray, "force" is false and the guest
7414 does not respond to the eject request
7415 - if the BlockBackend denoted by "device" does not have a guest
7417 device attached to it
7418 - if the guest device does not have an actual tray
7420 Arguments:
7422 "device: string" (optional)
7424 Block device name
7425 "id: string" (optional)
7427 The name or QOM path of the guest device (since: 2.8)
7428 "force: boolean" (optional)
7430 if false (the default), an eject request will be sent to the guest
7431 if it has locked the tray (and the tray will not be opened
7432 immediately); if true, the tray will be opened regardless of
7433 whether it is locked
7434 Features:
7436 "deprecated"
7438 Member "device" is deprecated. Use "id" instead.
7439 Since: 2.5
7441 Example:
7443 -> { "execute": "blockdev-open-tray",
7445 "arguments": { "id": "ide0-1-0" } }
7446 <- { "timestamp": { "seconds": 1418751016,
7448 "microseconds": 716996 },
7449 "event": "DEVICE_TRAY_MOVED",
7450 "data": { "device": "ide1-cd0",
7451 "id": "ide0-1-0",
7452 "tray-open": true } }
7453 <- { "return": {} }
7455 blockdev-close-tray (Command) Closes a block device's tray. If there
7457 is a block driver state tree associated with the block device (which is
7458 currently ejected), that tree will be loaded as the medium.
7459 If the tray was already closed before, this will be a no-op.
7461 Arguments:
7463 "device: string" (optional)
7465 Block device name
7466 "id: string" (optional)
7468 The name or QOM path of the guest device (since: 2.8)
7469 Features:
7471 "deprecated"
7473 Member "device" is deprecated. Use "id" instead.
7474 Since: 2.5
7476 Example:
7478 -> { "execute": "blockdev-close-tray",
7480 "arguments": { "id": "ide0-1-0" } }
7481 <- { "timestamp": { "seconds": 1418751345,
7483 "microseconds": 272147 },
7484 "event": "DEVICE_TRAY_MOVED",
7485 "data": { "device": "ide1-cd0",
7486 "id": "ide0-1-0",
7487 "tray-open": false } }
7488 <- { "return": {} }
7490 blockdev-remove-medium (Command) Removes a medium (a block driver
7492 state tree) from a block device. That block device's tray must
7493 currently be open (unless there is no attached guest device).
7494 If the tray is open and there is no medium inserted, this will be a no-
7496 op.
7497 Arguments:
7499 "id: string"
7501 The name or QOM path of the guest device
7502 Since: 2.12
7504 Example:
7506 -> { "execute": "blockdev-remove-medium",
7508 "arguments": { "id": "ide0-1-0" } }
7509 <- { "error": { "class": "GenericError",
7511 "desc": "Tray of device 'ide0-1-0' is not open" } }
7512 -> { "execute": "blockdev-open-tray",
7514 "arguments": { "id": "ide0-1-0" } }
7515 <- { "timestamp": { "seconds": 1418751627,
7517 "microseconds": 549958 },
7518 "event": "DEVICE_TRAY_MOVED",
7519 "data": { "device": "ide1-cd0",
7520 "id": "ide0-1-0",
7521 "tray-open": true } }
7522 <- { "return": {} }
7524 -> { "execute": "blockdev-remove-medium",
7526 "arguments": { "id": "ide0-1-0" } }
7527 <- { "return": {} }
7529 blockdev-insert-medium (Command) Inserts a medium (a block driver
7531 state tree) into a block device. That block device's tray must
7532 currently be open (unless there is no attached guest device) and there
7533 must be no medium inserted already.
7534 Arguments:
7536 "id: string"
7538 The name or QOM path of the guest device
7539 "node-name: string"
7541 name of a node in the block driver state graph
7542 Since: 2.12
7544 Example:
7546 -> { "execute": "blockdev-add",
7548 "arguments": {
7549 "node-name": "node0",
7550 "driver": "raw",
7551 "file": { "driver": "file",
7552 "filename": "fedora.iso" } } }
7553 <- { "return": {} }
7554 -> { "execute": "blockdev-insert-medium",
7556 "arguments": { "id": "ide0-1-0",
7557 "node-name": "node0" } }
7558 <- { "return": {} }
7560 BlockdevChangeReadOnlyMode (Enum)
7562 Specifies the new read-only mode of a block device subject to the
7564 "blockdev-change-medium" command.
7565 Values:
7567 "retain"
7569 Retains the current read-only mode
7570 "read-only"
7572 Makes the device read-only
7573 "read-write"
7575 Makes the device writable
7576 Since: 2.3
7578 blockdev-change-medium (Command) Changes the medium inserted into a
7580 block device by ejecting the current medium and loading a new image
7581 file which is inserted as the new medium (this command combines
7582 blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium and
7583 blockdev-close-tray).
7584 Arguments:
7586 "device: string" (optional)
7588 Block device name
7589 "id: string" (optional)
7591 The name or QOM path of the guest device (since: 2.8)
7592 "filename: string"
7594 filename of the new image to be loaded
7595 "format: string" (optional)
7597 format to open the new image with (defaults to the probed format)
7598 "read-only-mode: BlockdevChangeReadOnlyMode" (optional)
7600 change the read-only mode of the device; defaults to 'retain'
7601 Features:
7603 "deprecated"
7605 Member "device" is deprecated. Use "id" instead.
7606 Since: 2.5
7608 Examples:
7610 1. Change a removable medium
7612 -> { "execute": "blockdev-change-medium",
7614 "arguments": { "id": "ide0-1-0",
7615 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
7616 "format": "raw" } }
7617 <- { "return": {} }
7618 2. Load a read-only medium into a writable drive
7620 -> { "execute": "blockdev-change-medium",
7622 "arguments": { "id": "floppyA",
7623 "filename": "/srv/images/ro.img",
7624 "format": "raw",
7625 "read-only-mode": "retain" } }
7626 <- { "error":
7628 { "class": "GenericError",
7629 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
7630 -> { "execute": "blockdev-change-medium",
7632 "arguments": { "id": "floppyA",
7633 "filename": "/srv/images/ro.img",
7634 "format": "raw",
7635 "read-only-mode": "read-only" } }
7636 <- { "return": {} }
7638 DEVICE_TRAY_MOVED (Event) Emitted whenever the tray of a removable
7640 device is moved by the guest or by HMP/QMP commands
7641 Arguments:
7643 "device: string"
7645 Block device name. This is always present for compatibility
7646 reasons, but it can be empty ("") if the image does not have a
7647 device name associated.
7648 "id: string"
7650 The name or QOM path of the guest device (since 2.8)
7651 "tray-open: boolean"
7653 true if the tray has been opened or false if it has been closed
7654 Since: 1.1
7656 Example:
7658 <- { "event": "DEVICE_TRAY_MOVED",
7660 "data": { "device": "ide1-cd0",
7661 "id": "/machine/unattached/device[22]",
7662 "tray-open": true
7663 },
7664 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7665 PR_MANAGER_STATUS_CHANGED (Event) Emitted whenever the connected
7667 status of a persistent reservation manager changes.
7668 Arguments:
7670 "id: string"
7672 The id of the PR manager object
7673 "connected: boolean"
7675 true if the PR manager is connected to a backend
7676 Since: 3.0
7678 Example:
7680 <- { "event": "PR_MANAGER_STATUS_CHANGED",
7682 "data": { "id": "pr-helper0",
7683 "connected": true
7684 },
7685 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
7686 block_set_io_throttle (Command) Change I/O throttle limits for a block
7688 drive.
7689 Since QEMU 2.4, each device with I/O limits is member of a throttle
7691 group.
7692 If two or more devices are members of the same group, the limits will
7694 apply to the combined I/O of the whole group in a round-robin fashion.
7695 Therefore, setting new I/O limits to a device will affect the whole
7696 group.
7697 The name of the group can be specified using the 'group' parameter. If
7699 the parameter is unset, it is assumed to be the current group of that
7700 device. If it's not in any group yet, the name of the device will be
7701 used as the name for its group.
7702 The 'group' parameter can also be used to move a device to a different
7704 group. In this case the limits specified in the parameters will be
7705 applied to the new group only.
7706 I/O limits can be disabled by setting all of them to 0. In this case
7708 the device will be removed from its group and the rest of its members
7709 will not be affected. The 'group' parameter is ignored.
7710 Arguments: the members of "BlockIOThrottle"
7712 Returns:
7714 - Nothing on success
7716 - If "device" is not a valid block device, DeviceNotFound
7718 Since: 1.1
7720 Example:
7722 -> { "execute": "block_set_io_throttle",
7724 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
7725 "bps": 0,
7726 "bps_rd": 0,
7727 "bps_wr": 0,
7728 "iops": 512,
7729 "iops_rd": 0,
7730 "iops_wr": 0,
7731 "bps_max": 0,
7732 "bps_rd_max": 0,
7733 "bps_wr_max": 0,
7734 "iops_max": 0,
7735 "iops_rd_max": 0,
7736 "iops_wr_max": 0,
7737 "bps_max_length": 0,
7738 "iops_size": 0 } }
7739 <- { "return": {} }
7740 -> { "execute": "block_set_io_throttle",
7742 "arguments": { "id": "ide0-1-0",
7743 "bps": 1000000,
7744 "bps_rd": 0,
7745 "bps_wr": 0,
7746 "iops": 0,
7747 "iops_rd": 0,
7748 "iops_wr": 0,
7749 "bps_max": 8000000,
7750 "bps_rd_max": 0,
7751 "bps_wr_max": 0,
7752 "iops_max": 0,
7753 "iops_rd_max": 0,
7754 "iops_wr_max": 0,
7755 "bps_max_length": 60,
7756 "iops_size": 0 } }
7757 <- { "return": {} }
7758 block-latency-histogram-set (Command) Manage read, write and flush
7760 latency histograms for the device.
7761 If only "id" parameter is specified, remove all present latency
7763 histograms for the device. Otherwise, add/reset some of (or all)
7764 latency histograms.
7765 Arguments:
7767 "id: string"
7769 The name or QOM path of the guest device.
7770 "boundaries: array of int" (optional)
7772 list of interval boundary values (see description in
7773 BlockLatencyHistogramInfo definition). If specified, all latency
7774 histograms are removed, and empty ones created for all io types
7775 with intervals corresponding to "boundaries" (except for io types,
7776 for which specific boundaries are set through the following
7777 parameters).
7778 "boundaries-read: array of int" (optional)
7780 list of interval boundary values for read latency histogram. If
7781 specified, old read latency histogram is removed, and empty one
7782 created with intervals corresponding to "boundaries-read". The
7783 parameter has higher priority then "boundaries".
7784 "boundaries-write: array of int" (optional)
7786 list of interval boundary values for write latency histogram.
7787 "boundaries-flush: array of int" (optional)
7789 list of interval boundary values for flush latency histogram.
7790 Returns: error if device is not found or any boundary arrays are
7792 invalid.
7793 Since: 4.0
7795 Example:
7797 set new histograms for all io types with intervals
7799 [0, 10), [10, 50), [50, 100), [100, +inf):
7800 -> { "execute": "block-latency-histogram-set",
7802 "arguments": { "id": "drive0",
7803 "boundaries": [10, 50, 100] } }
7804 <- { "return": {} }
7805 Example:
7807 set new histogram only for write, other histograms will remain
7809 not changed (or not created):
7810 -> { "execute": "block-latency-histogram-set",
7812 "arguments": { "id": "drive0",
7813 "boundaries-write": [10, 50, 100] } }
7814 <- { "return": {} }
7815 Example:
7817 set new histograms with the following intervals:
7819 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
7820 write: [0, 1000), [1000, 5000), [5000, +inf)
7821 -> { "execute": "block-latency-histogram-set",
7823 "arguments": { "id": "drive0",
7824 "boundaries": [10, 50, 100],
7825 "boundaries-write": [1000, 5000] } }
7826 <- { "return": {} }
7827 Example:
7829 remove all latency histograms:
7831 -> { "execute": "block-latency-histogram-set",
7833 "arguments": { "id": "drive0" } }
7834 <- { "return": {} }
7835 Character devices
7837 ChardevInfo (Object)
7838 Information about a character device.
7840 Members:
7842 "label: string"
7844 the label of the character device
7845 "filename: string"
7847 the filename of the character device
7848 "frontend-open: boolean"
7850 shows whether the frontend device attached to this backend (eg.
7851 with the chardev=... option) is in open or closed state (since 2.1)
7852 Notes: "filename" is encoded using the QEMU command line character
7854 device encoding. See the QEMU man page for details.
7855 Since: 0.14.0
7857 query-chardev (Command) Returns information about current character
7859 devices.
7860 Returns: a list of "ChardevInfo"
7862 Since: 0.14.0
7864 Example:
7866 -> { "execute": "query-chardev" }
7868 <- {
7869 "return": [
7870 {
7871 "label": "charchannel0",
7872 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
7873 "frontend-open": false
7874 },
7875 {
7876 "label": "charmonitor",
7877 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
7878 "frontend-open": true
7879 },
7880 {
7881 "label": "charserial0",
7882 "filename": "pty:/dev/pts/2",
7883 "frontend-open": true
7884 }
7885 ]
7886 }
7887 ChardevBackendInfo (Object)
7889 Information about a character device backend
7891 Members:
7893 "name: string"
7895 The backend name
7896 Since: 2.0
7898 query-chardev-backends (Command) Returns information about character
7900 device backends.
7901 Returns: a list of "ChardevBackendInfo"
7903 Since: 2.0
7905 Example:
7907 -> { "execute": "query-chardev-backends" }
7909 <- {
7910 "return":[
7911 {
7912 "name":"udp"
7913 },
7914 {
7915 "name":"tcp"
7916 },
7917 {
7918 "name":"unix"
7919 },
7920 {
7921 "name":"spiceport"
7922 }
7923 ]
7924 }
7925 DataFormat (Enum)
7927 An enumeration of data format.
7929 Values:
7931 "utf8"
7933 Data is a UTF-8 string (RFC 3629)
7934 "base64"
7936 Data is Base64 encoded binary (RFC 3548)
7937 Since: 1.4
7939 ringbuf-write (Command) Write to a ring buffer character device.
7941 Arguments:
7943 "device: string"
7945 the ring buffer character device name
7946 "data: string"
7948 data to write
7949 "format: DataFormat" (optional)
7951 data encoding (default 'utf8').
7952 - base64: data must be base64 encoded text. Its binary decoding
7954 gets written.
7955 - utf8: data's UTF-8 encoding is written
7957 - data itself is always Unicode regardless of format, like any
7959 other string.
7960 Returns: Nothing on success
7962 Since: 1.4
7964 Example:
7966 -> { "execute": "ringbuf-write",
7968 "arguments": { "device": "foo",
7969 "data": "abcdefgh",
7970 "format": "utf8" } }
7971 <- { "return": {} }
7972 ringbuf-read (Command) Read from a ring buffer character device.
7974 Arguments:
7976 "device: string"
7978 the ring buffer character device name
7979 "size: int"
7981 how many bytes to read at most
7982 "format: DataFormat" (optional)
7984 data encoding (default 'utf8').
7985 - base64: the data read is returned in base64 encoding.
7987 - utf8: the data read is interpreted as UTF-8. Bug: can screw up
7989 when the buffer contains invalid UTF-8 sequences, NUL
7990 characters, after the ring buffer lost data, and when reading
7991 stops because the size limit is reached.
7992 - The return value is always Unicode regardless of format, like
7994 any other string.
7995 Returns: data read from the device
7997 Since: 1.4
7999 Example:
8001 -> { "execute": "ringbuf-read",
8003 "arguments": { "device": "foo",
8004 "size": 1000,
8005 "format": "utf8" } }
8006 <- { "return": "abcdefgh" }
8007 ChardevCommon (Object)
8009 Configuration shared across all chardev backends
8011 Members:
8013 "logfile: string" (optional)
8015 The name of a logfile to save output
8016 "logappend: boolean" (optional)
8018 true to append instead of truncate (default to false to truncate)
8019 Since: 2.6
8021 ChardevFile (Object)
8023 Configuration info for file chardevs.
8025 Members:
8027 "in: string" (optional)
8029 The name of the input file
8030 "out: string"
8032 The name of the output file
8033 "append: boolean" (optional)
8035 Open the file in append mode (default false to truncate) (Since
8036 2.6)
8037 The members of "ChardevCommon"
8039 Since: 1.4
8041 ChardevHostdev (Object)
8043 Configuration info for device and pipe chardevs.
8045 Members:
8047 "device: string"
8049 The name of the special file for the device, i.e. /dev/ttyS0 on
8050 Unix or COM1: on Windows
8051 The members of "ChardevCommon"
8053 Since: 1.4
8055 ChardevSocket (Object)
8057 Configuration info for (stream) socket chardevs.
8059 Members:
8061 "addr: SocketAddressLegacy"
8063 socket address to listen on (server=true) or connect to
8064 (server=false)
8065 "tls-creds: string" (optional)
8067 the ID of the TLS credentials object (since 2.6)
8068 "tls-authz: string" (optional)
8070 the ID of the QAuthZ authorization object against which the
8071 client's x509 distinguished name will be validated. This object is
8072 only resolved at time of use, so can be deleted and recreated on
8073 the fly while the chardev server is active. If missing, it will
8074 default to denying access (since 4.0)
8075 "server: boolean" (optional)
8077 create server socket (default: true)
8078 "wait: boolean" (optional)
8080 wait for incoming connection on server sockets (default: false).
8081 Silently ignored with server: false. This use is deprecated.
8082 "nodelay: boolean" (optional)
8084 set TCP_NODELAY socket option (default: false)
8085 "telnet: boolean" (optional)
8087 enable telnet protocol on server sockets (default: false)
8088 "tn3270: boolean" (optional)
8090 enable tn3270 protocol on server sockets (default: false) (Since:
8091 2.10)
8092 "websocket: boolean" (optional)
8094 enable websocket protocol on server sockets (default: false)
8095 (Since: 3.1)
8096 "reconnect: int" (optional)
8098 For a client socket, if a socket is disconnected, then attempt a
8099 reconnect after the given number of seconds. Setting this to zero
8100 disables this function. (default: 0) (Since: 2.2)
8101 The members of "ChardevCommon"
8103 Since: 1.4
8105 ChardevUdp (Object)
8107 Configuration info for datagram socket chardevs.
8109 Members:
8111 "remote: SocketAddressLegacy"
8113 remote address
8114 "local: SocketAddressLegacy" (optional)
8116 local address
8117 The members of "ChardevCommon"
8119 Since: 1.5
8121 ChardevMux (Object)
8123 Configuration info for mux chardevs.
8125 Members:
8127 "chardev: string"
8129 name of the base chardev.
8130 The members of "ChardevCommon"
8132 Since: 1.5
8134 ChardevStdio (Object)
8136 Configuration info for stdio chardevs.
8138 Members:
8140 "signal: boolean" (optional)
8142 Allow signals (such as SIGINT triggered by ^C) be delivered to
8143 qemu. Default: true in -nographic mode, false otherwise.
8144 The members of "ChardevCommon"
8146 Since: 1.5
8148 ChardevSpiceChannel (Object)
8150 Configuration info for spice vm channel chardevs.
8152 Members:
8154 "type: string"
8156 kind of channel (for example vdagent).
8157 The members of "ChardevCommon"
8159 Since: 1.5
8161 If: "defined(CONFIG_SPICE)"
8163 ChardevSpicePort (Object)
8165 Configuration info for spice port chardevs.
8167 Members:
8169 "fqdn: string"
8171 name of the channel (see docs/spice-port-fqdn.txt)
8172 The members of "ChardevCommon"
8174 Since: 1.5
8176 If: "defined(CONFIG_SPICE)"
8178 ChardevVC (Object)
8180 Configuration info for virtual console chardevs.
8182 Members:
8184 "width: int" (optional)
8186 console width, in pixels
8187 "height: int" (optional)
8189 console height, in pixels
8190 "cols: int" (optional)
8192 console width, in chars
8193 "rows: int" (optional)
8195 console height, in chars
8196 The members of "ChardevCommon"
8198 Since: 1.5
8200 ChardevRingbuf (Object)
8202 Configuration info for ring buffer chardevs.
8204 Members:
8206 "size: int" (optional)
8208 ring buffer size, must be power of two, default is 65536
8209 The members of "ChardevCommon"
8211 Since: 1.5
8213 ChardevBackend (Object)
8215 Configuration info for the new chardev backend.
8217 Members:
8219 "type"
8221 One of "file", "serial", "parallel", "pipe", "socket", "udp",
8222 "pty", "null", "mux", "msmouse", "wctablet", "braille", "testdev",
8223 "stdio", "console", "spicevmc", "spiceport", "vc", "ringbuf",
8224 "memory"
8225 "data: ChardevFile" when "type" is "file"
8227 "data: ChardevHostdev" when "type" is "serial"
8228 "data: ChardevHostdev" when "type" is "parallel"
8229 "data: ChardevHostdev" when "type" is "pipe"
8230 "data: ChardevSocket" when "type" is "socket"
8231 "data: ChardevUdp" when "type" is "udp"
8232 "data: ChardevCommon" when "type" is "pty"
8233 "data: ChardevCommon" when "type" is "null"
8234 "data: ChardevMux" when "type" is "mux"
8235 "data: ChardevCommon" when "type" is "msmouse"
8236 "data: ChardevCommon" when "type" is "wctablet"
8237 "data: ChardevCommon" when "type" is "braille"
8238 "data: ChardevCommon" when "type" is "testdev"
8239 "data: ChardevStdio" when "type" is "stdio"
8240 "data: ChardevCommon" when "type" is "console"
8241 "data: ChardevSpiceChannel" when "type" is "spicevmc" (If:
8242 "defined(CONFIG_SPICE)")
8243 "data: ChardevSpicePort" when "type" is "spiceport" (If:
8244 "defined(CONFIG_SPICE)")
8245 "data: ChardevVC" when "type" is "vc"
8246 "data: ChardevRingbuf" when "type" is "ringbuf"
8247 "data: ChardevRingbuf" when "type" is "memory"
8248 Since: 1.4 (testdev since 2.2, wctablet since 2.9)
8250 ChardevReturn (Object)
8252 Return info about the chardev backend just created.
8254 Members:
8256 "pty: string" (optional)
8258 name of the slave pseudoterminal device, present if and only if a
8259 chardev of type 'pty' was created
8260 Since: 1.4
8262 chardev-add (Command) Add a character device backend
8264 Arguments:
8266 "id: string"
8268 the chardev's ID, must be unique
8269 "backend: ChardevBackend"
8271 backend type and parameters
8272 Returns: ChardevReturn.
8274 Since: 1.4
8276 Example:
8278 -> { "execute" : "chardev-add",
8280 "arguments" : { "id" : "foo",
8281 "backend" : { "type" : "null", "data" : {} } } }
8282 <- { "return": {} }
8283 -> { "execute" : "chardev-add",
8285 "arguments" : { "id" : "bar",
8286 "backend" : { "type" : "file",
8287 "data" : { "out" : "/tmp/bar.log" } } } }
8288 <- { "return": {} }
8289 -> { "execute" : "chardev-add",
8291 "arguments" : { "id" : "baz",
8292 "backend" : { "type" : "pty", "data" : {} } } }
8293 <- { "return": { "pty" : "/dev/pty/42" } }
8294 chardev-change (Command) Change a character device backend
8296 Arguments:
8298 "id: string"
8300 the chardev's ID, must exist
8301 "backend: ChardevBackend"
8303 new backend type and parameters
8304 Returns: ChardevReturn.
8306 Since: 2.10
8308 Example:
8310 -> { "execute" : "chardev-change",
8312 "arguments" : { "id" : "baz",
8313 "backend" : { "type" : "pty", "data" : {} } } }
8314 <- { "return": { "pty" : "/dev/pty/42" } }
8315 -> {"execute" : "chardev-change",
8317 "arguments" : {
8318 "id" : "charchannel2",
8319 "backend" : {
8320 "type" : "socket",
8321 "data" : {
8322 "addr" : {
8323 "type" : "unix" ,
8324 "data" : {
8325 "path" : "/tmp/charchannel2.socket"
8326 }
8327 },
8328 "server" : true,
8329 "wait" : false }}}}
8330 <- {"return": {}}
8331 chardev-remove (Command) Remove a character device backend
8333 Arguments:
8335 "id: string"
8337 the chardev's ID, must exist and not be in use
8338 Returns: Nothing on success
8340 Since: 1.4
8342 Example:
8344 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8346 <- { "return": {} }
8347 chardev-send-break (Command) Send a break to a character device
8349 Arguments:
8351 "id: string"
8353 the chardev's ID, must exist
8354 Returns: Nothing on success
8356 Since: 2.10
8358 Example:
8360 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8362 <- { "return": {} }
8363 VSERPORT_CHANGE (Event) Emitted when the guest opens or closes a
8365 virtio-serial port.
8366 Arguments:
8368 "id: string"
8370 device identifier of the virtio-serial port
8371 "open: boolean"
8373 true if the guest has opened the virtio-serial port
8374 Since: 2.1
8376 Example:
8378 <- { "event": "VSERPORT_CHANGE",
8380 "data": { "id": "channel0", "open": true },
8381 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8382 Dump guest memory
8384 DumpGuestMemoryFormat (Enum)
8385 An enumeration of guest-memory-dump's format.
8387 Values:
8389 "elf"
8391 elf format
8392 "kdump-zlib"
8394 kdump-compressed format with zlib-compressed
8395 "kdump-lzo"
8397 kdump-compressed format with lzo-compressed
8398 "kdump-snappy"
8400 kdump-compressed format with snappy-compressed
8401 "win-dmp"
8403 Windows full crashdump format, can be used instead of ELF
8404 converting (since 2.13)
8405 Since: 2.0
8407 dump-guest-memory (Command) Dump guest's memory to vmcore. It is a
8409 synchronous operation that can take very long depending on the amount
8410 of guest memory.
8411 Arguments:
8413 "paging: boolean"
8415 if true, do paging to get guest's memory mapping. This allows using
8416 gdb to process the core file.
8417 IMPORTANT: this option can make QEMU allocate several gigabytes of
8419 RAM. This can happen for a large guest, or a malicious guest
8420 pretending to be large.
8421 Also, paging=true has the following limitations:
8423 1. The guest may be in a catastrophic state or can have corrupted
8425 memory, which cannot be trusted
8426 2. The guest can be in real-mode even if paging is enabled. For
8428 example, the guest uses ACPI to sleep, and ACPI sleep state
8429 goes in real-mode
8430 3. Currently only supported on i386 and x86_64.
8432 "protocol: string"
8434 the filename or file descriptor of the vmcore. The supported
8435 protocols are:
8436 1. file: the protocol starts with "file:", and the following
8438 string is the file's path.
8439 2. fd: the protocol starts with "fd:", and the following string is
8441 the fd's name.
8442 "detach: boolean" (optional)
8444 if true, QMP will return immediately rather than waiting for the
8445 dump to finish. The user can track progress using "query-dump".
8446 (since 2.6).
8447 "begin: int" (optional)
8449 if specified, the starting physical address.
8450 "length: int" (optional)
8452 if specified, the memory size, in bytes. If you don't want to dump
8453 all guest's memory, please specify the start "begin" and "length"
8454 "format: DumpGuestMemoryFormat" (optional)
8456 if specified, the format of guest memory dump. But non-elf format
8457 is conflict with paging and filter, ie. "paging", "begin" and
8458 "length" is not allowed to be specified with non-elf "format" at
8459 the same time (since 2.0)
8460 Note: All boolean arguments default to false
8462 Returns: nothing on success
8464 Since: 1.2
8466 Example:
8468 -> { "execute": "dump-guest-memory",
8470 "arguments": { "protocol": "fd:dump" } }
8471 <- { "return": {} }
8472 DumpStatus (Enum)
8474 Describe the status of a long-running background guest memory dump.
8476 Values:
8478 "none"
8480 no dump-guest-memory has started yet.
8481 "active"
8483 there is one dump running in background.
8484 "completed"
8486 the last dump has finished successfully.
8487 "failed"
8489 the last dump has failed.
8490 Since: 2.6
8492 DumpQueryResult (Object)
8494 The result format for 'query-dump'.
8496 Members:
8498 "status: DumpStatus"
8500 enum of "DumpStatus", which shows current dump status
8501 "completed: int"
8503 bytes written in latest dump (uncompressed)
8504 "total: int"
8506 total bytes to be written in latest dump (uncompressed)
8507 Since: 2.6
8509 query-dump (Command) Query latest dump status.
8511 Returns: A "DumpStatus" object showing the dump status.
8513 Since: 2.6
8515 Example:
8517 -> { "execute": "query-dump" }
8519 <- { "return": { "status": "active", "completed": 1024000,
8520 "total": 2048000 } }
8521 DUMP_COMPLETED (Event) Emitted when background dump has completed
8523 Arguments:
8525 "result: DumpQueryResult"
8527 final dump status
8528 "error: string" (optional)
8530 human-readable error string that provides hint on why dump failed.
8531 Only presents on failure. The user should not try to interpret the
8532 error string.
8533 Since: 2.6
8535 Example:
8537 { "event": "DUMP_COMPLETED",
8539 "data": {"result": {"total": 1090650112, "status": "completed",
8540 "completed": 1090650112} } }
8541 DumpGuestMemoryCapability (Object)
8543 A list of the available formats for dump-guest-memory
8545 Members:
8547 "formats: array of DumpGuestMemoryFormat"
8549 Not documented
8550 Since: 2.0
8552 query-dump-guest-memory-capability (Command) Returns the available
8554 formats for dump-guest-memory
8555 Returns: A "DumpGuestMemoryCapability" object listing available formats
8557 for dump-guest-memory
8558 Since: 2.0
8560 Example:
8562 -> { "execute": "query-dump-guest-memory-capability" }
8564 <- { "return": { "formats":
8565 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
8566 Net devices
8568 set_link (Command) Sets the link status of a virtual network adapter.
8569 Arguments:
8571 "name: string"
8573 the device name of the virtual network adapter
8574 "up: boolean"
8576 true to set the link status to be up
8577 Returns: Nothing on success If "name" is not a valid network device,
8579 DeviceNotFound
8580 Since: 0.14.0
8582 Notes: Not all network adapters support setting link status. This
8584 command will succeed even if the network adapter does not support link
8585 status notification.
8586 Example:
8588 -> { "execute": "set_link",
8590 "arguments": { "name": "e1000.0", "up": false } }
8591 <- { "return": {} }
8592 netdev_add (Command) Add a network backend.
8594 Additional arguments depend on the type.
8596 Arguments: the members of "Netdev"
8598 Since: 0.14.0
8600 Returns: Nothing on success If "type" is not a valid network backend,
8602 DeviceNotFound
8603 Example:
8605 -> { "execute": "netdev_add",
8607 "arguments": { "type": "user", "id": "netdev1",
8608 "dnssearch": "example.org" } }
8609 <- { "return": {} }
8610 netdev_del (Command) Remove a network backend.
8612 Arguments:
8614 "id: string"
8616 the name of the network backend to remove
8617 Returns: Nothing on success If "id" is not a valid network backend,
8619 DeviceNotFound
8620 Since: 0.14.0
8622 Example:
8624 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
8626 <- { "return": {} }
8627 NetLegacyNicOptions (Object)
8629 Create a new Network Interface Card.
8631 Members:
8633 "netdev: string" (optional)
8635 id of -netdev to connect to
8636 "macaddr: string" (optional)
8638 MAC address
8639 "model: string" (optional)
8641 device model (e1000, rtl8139, virtio etc.)
8642 "addr: string" (optional)
8644 PCI device address
8645 "vectors: int" (optional)
8647 number of MSI-x vectors, 0 to disable MSI-X
8648 Since: 1.2
8650 NetdevUserOptions (Object)
8652 Use the user mode network stack which requires no administrator
8654 privilege to run.
8655 Members:
8657 "hostname: string" (optional)
8659 client hostname reported by the builtin DHCP server
8660 "restrict: boolean" (optional)
8662 isolate the guest from the host
8663 "ipv4: boolean" (optional)
8665 whether to support IPv4, default true for enabled (since 2.6)
8666 "ipv6: boolean" (optional)
8668 whether to support IPv6, default true for enabled (since 2.6)
8669 "ip: string" (optional)
8671 legacy parameter, use net= instead
8672 "net: string" (optional)
8674 IP network address that the guest will see, in the form
8675 addr[/netmask] The netmask is optional, and can be either in the
8676 form a.b.c.d or as a number of valid top-most bits. Default is
8677 10.0.2.0/24.
8678 "host: string" (optional)
8680 guest-visible address of the host
8681 "tftp: string" (optional)
8683 root directory of the built-in TFTP server
8684 "bootfile: string" (optional)
8686 BOOTP filename, for use with tftp=
8687 "dhcpstart: string" (optional)
8689 the first of the 16 IPs the built-in DHCP server can assign
8690 "dns: string" (optional)
8692 guest-visible address of the virtual nameserver
8693 "dnssearch: array of String" (optional)
8695 list of DNS suffixes to search, passed as DHCP option to the guest
8696 "domainname: string" (optional)
8698 guest-visible domain name of the virtual nameserver (since 3.0)
8699 "ipv6-prefix: string" (optional)
8701 IPv6 network prefix (default is fec0::) (since 2.6). The network
8702 prefix is given in the usual hexadecimal IPv6 address notation.
8703 "ipv6-prefixlen: int" (optional)
8705 IPv6 network prefix length (default is 64) (since 2.6)
8706 "ipv6-host: string" (optional)
8708 guest-visible IPv6 address of the host (since 2.6)
8709 "ipv6-dns: string" (optional)
8711 guest-visible IPv6 address of the virtual nameserver (since 2.6)
8712 "smb: string" (optional)
8714 root directory of the built-in SMB server
8715 "smbserver: string" (optional)
8717 IP address of the built-in SMB server
8718 "hostfwd: array of String" (optional)
8720 redirect incoming TCP or UDP host connections to guest endpoints
8721 "guestfwd: array of String" (optional)
8723 forward guest TCP connections
8724 "tftp-server-name: string" (optional)
8726 RFC2132 "TFTP server name" string (Since 3.1)
8727 Since: 1.2
8729 NetdevTapOptions (Object)
8731 Used to configure a host TAP network interface backend.
8733 Members:
8735 "ifname: string" (optional)
8737 interface name
8738 "fd: string" (optional)
8740 file descriptor of an already opened tap
8741 "fds: string" (optional)
8743 multiple file descriptors of already opened multiqueue capable tap
8744 "script: string" (optional)
8746 script to initialize the interface
8747 "downscript: string" (optional)
8749 script to shut down the interface
8750 "br: string" (optional)
8752 bridge name (since 2.8)
8753 "helper: string" (optional)
8755 command to execute to configure bridge
8756 "sndbuf: int" (optional)
8758 send buffer limit. Understands [TGMKkb] suffixes.
8759 "vnet_hdr: boolean" (optional)
8761 enable the IFF_VNET_HDR flag on the tap interface
8762 "vhost: boolean" (optional)
8764 enable vhost-net network accelerator
8765 "vhostfd: string" (optional)
8767 file descriptor of an already opened vhost net device
8768 "vhostfds: string" (optional)
8770 file descriptors of multiple already opened vhost net devices
8771 "vhostforce: boolean" (optional)
8773 vhost on for non-MSIX virtio guests
8774 "queues: int" (optional)
8776 number of queues to be created for multiqueue capable tap
8777 "poll-us: int" (optional)
8779 maximum number of microseconds that could be spent on busy polling
8780 for tap (since 2.7)
8781 Since: 1.2
8783 NetdevSocketOptions (Object)
8785 Socket netdevs are used to establish a network connection to another
8787 QEMU virtual machine via a TCP socket.
8788 Members:
8790 "fd: string" (optional)
8792 file descriptor of an already opened socket
8793 "listen: string" (optional)
8795 port number, and optional hostname, to listen on
8796 "connect: string" (optional)
8798 port number, and optional hostname, to connect to
8799 "mcast: string" (optional)
8801 UDP multicast address and port number
8802 "localaddr: string" (optional)
8804 source address and port for multicast and udp packets
8805 "udp: string" (optional)
8807 UDP unicast address and port number
8808 Since: 1.2
8810 NetdevL2TPv3Options (Object)
8812 Configure an Ethernet over L2TPv3 tunnel.
8814 Members:
8816 "src: string"
8818 source address
8819 "dst: string"
8821 destination address
8822 "srcport: string" (optional)
8824 source port - mandatory for udp, optional for ip
8825 "dstport: string" (optional)
8827 destination port - mandatory for udp, optional for ip
8828 "ipv6: boolean" (optional)
8830 force the use of ipv6
8831 "udp: boolean" (optional)
8833 use the udp version of l2tpv3 encapsulation
8834 "cookie64: boolean" (optional)
8836 use 64 bit coookies
8837 "counter: boolean" (optional)
8839 have sequence counter
8840 "pincounter: boolean" (optional)
8842 pin sequence counter to zero - workaround for buggy implementations
8843 or networks with packet reorder
8844 "txcookie: int" (optional)
8846 32 or 64 bit transmit cookie
8847 "rxcookie: int" (optional)
8849 32 or 64 bit receive cookie
8850 "txsession: int"
8852 32 bit transmit session
8853 "rxsession: int" (optional)
8855 32 bit receive session - if not specified set to the same value as
8856 transmit
8857 "offset: int" (optional)
8859 additional offset - allows the insertion of additional application-
8860 specific data before the packet payload
8861 Since: 2.1
8863 NetdevVdeOptions (Object)
8865 Connect to a vde switch running on the host.
8867 Members:
8869 "sock: string" (optional)
8871 socket path
8872 "port: int" (optional)
8874 port number
8875 "group: string" (optional)
8877 group owner of socket
8878 "mode: int" (optional)
8880 permissions for socket
8881 Since: 1.2
8883 NetdevBridgeOptions (Object)
8885 Connect a host TAP network interface to a host bridge device.
8887 Members:
8889 "br: string" (optional)
8891 bridge name
8892 "helper: string" (optional)
8894 command to execute to configure bridge
8895 Since: 1.2
8897 NetdevHubPortOptions (Object)
8899 Connect two or more net clients through a software hub.
8901 Members:
8903 "hubid: int"
8905 hub identifier number
8906 "netdev: string" (optional)
8908 used to connect hub to a netdev instead of a device (since 2.12)
8909 Since: 1.2
8911 NetdevNetmapOptions (Object)
8913 Connect a client to a netmap-enabled NIC or to a VALE switch port
8915 Members:
8917 "ifname: string"
8919 Either the name of an existing network interface supported by
8920 netmap, or the name of a VALE port (created on the fly). A VALE
8921 port name is in the form 'valeXXX:YYY', where XXX and YYY are non-
8922 negative integers. XXX identifies a switch and YYY identifies a
8923 port of the switch. VALE ports having the same XXX are therefore
8924 connected to the same switch.
8925 "devname: string" (optional)
8927 path of the netmap device (default: '/dev/netmap').
8928 Since: 2.0
8930 NetdevVhostUserOptions (Object)
8932 Vhost-user network backend
8934 Members:
8936 "chardev: string"
8938 name of a unix socket chardev
8939 "vhostforce: boolean" (optional)
8941 vhost on for non-MSIX virtio guests (default: false).
8942 "queues: int" (optional)
8944 number of queues to be created for multiqueue vhost-user (default:
8945 1) (Since 2.5)
8946 Since: 2.1
8948 NetdevVhostVDPAOptions (Object)
8950 Vhost-vdpa network backend
8952 vDPA device is a device that uses a datapath which complies with the
8954 virtio specifications with a vendor specific control path.
8955 Members:
8957 "vhostdev: string" (optional)
8959 path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
8960 "queues: int" (optional)
8962 number of queues to be created for multiqueue vhost-vdpa (default:
8963 1)
8964 Since: 5.1
8966 NetClientDriver (Enum)
8968 Available netdev drivers.
8970 Values:
8972 "none"
8974 Not documented
8975 "nic"
8977 Not documented
8978 "user"
8980 Not documented
8981 "tap"
8983 Not documented
8984 "l2tpv3"
8986 Not documented
8987 "socket"
8989 Not documented
8990 "vde"
8992 Not documented
8993 "bridge"
8995 Not documented
8996 "hubport"
8998 Not documented
8999 "netmap"
9001 Not documented
9002 "vhost-user"
9004 Not documented
9005 "vhost-vdpa"
9007 Not documented
9008 Since: 2.7
9010 "vhost-vdpa" since 5.1
9012 Netdev (Object)
9014 Captures the configuration of a network device.
9016 Members:
9018 "id: string"
9020 identifier for monitor commands.
9021 "type: NetClientDriver"
9023 Specify the driver used for interpreting remaining arguments.
9024 The members of "NetLegacyNicOptions" when "type" is "nic"
9026 The members of "NetdevUserOptions" when "type" is "user"
9027 The members of "NetdevTapOptions" when "type" is "tap"
9028 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
9029 The members of "NetdevSocketOptions" when "type" is "socket"
9030 The members of "NetdevVdeOptions" when "type" is "vde"
9031 The members of "NetdevBridgeOptions" when "type" is "bridge"
9032 The members of "NetdevHubPortOptions" when "type" is "hubport"
9033 The members of "NetdevNetmapOptions" when "type" is "netmap"
9034 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
9035 The members of "NetdevVhostVDPAOptions" when "type" is "vhost-vdpa"
9036 Since: 1.2
9038 'l2tpv3' - since 2.1
9040 NetFilterDirection (Enum)
9042 Indicates whether a netfilter is attached to a netdev's transmit queue
9044 or receive queue or both.
9045 Values:
9047 "all"
9049 the filter is attached both to the receive and the transmit queue
9050 of the netdev (default).
9051 "rx"
9053 the filter is attached to the receive queue of the netdev, where it
9054 will receive packets sent to the netdev.
9055 "tx"
9057 the filter is attached to the transmit queue of the netdev, where
9058 it will receive packets sent by the netdev.
9059 Since: 2.5
9061 RxState (Enum)
9063 Packets receiving state
9065 Values:
9067 "normal"
9069 filter assigned packets according to the mac-table
9070 "none"
9072 don't receive any assigned packet
9073 "all"
9075 receive all assigned packets
9076 Since: 1.6
9078 RxFilterInfo (Object)
9080 Rx-filter information for a NIC.
9082 Members:
9084 "name: string"
9086 net client name
9087 "promiscuous: boolean"
9089 whether promiscuous mode is enabled
9090 "multicast: RxState"
9092 multicast receive state
9093 "unicast: RxState"
9095 unicast receive state
9096 "vlan: RxState"
9098 vlan receive state (Since 2.0)
9099 "broadcast-allowed: boolean"
9101 whether to receive broadcast
9102 "multicast-overflow: boolean"
9104 multicast table is overflowed or not
9105 "unicast-overflow: boolean"
9107 unicast table is overflowed or not
9108 "main-mac: string"
9110 the main macaddr string
9111 "vlan-table: array of int"
9113 a list of active vlan id
9114 "unicast-table: array of string"
9116 a list of unicast macaddr string
9117 "multicast-table: array of string"
9119 a list of multicast macaddr string
9120 Since: 1.6
9122 query-rx-filter (Command) Return rx-filter information for all NICs
9124 (or for the given NIC).
9125 Arguments:
9127 "name: string" (optional)
9129 net client name
9130 Returns: list of "RxFilterInfo" for all NICs (or for the given NIC).
9132 Returns an error if the given "name" doesn't exist, or given NIC
9133 doesn't support rx-filter querying, or given net client isn't a NIC.
9134 Since: 1.6
9136 Example:
9138 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
9140 <- { "return": [
9141 {
9142 "promiscuous": true,
9143 "name": "vnet0",
9144 "main-mac": "52:54:00:12:34:56",
9145 "unicast": "normal",
9146 "vlan": "normal",
9147 "vlan-table": [
9148 4,
9149 0
9150 ],
9151 "unicast-table": [
9152 ],
9153 "multicast": "normal",
9154 "multicast-overflow": false,
9155 "unicast-overflow": false,
9156 "multicast-table": [
9157 "01:00:5e:00:00:01",
9158 "33:33:00:00:00:01",
9159 "33:33:ff:12:34:56"
9160 ],
9161 "broadcast-allowed": false
9162 }
9163 ]
9164 }
9165 NIC_RX_FILTER_CHANGED (Event) Emitted once until the 'query-rx-filter'
9167 command is executed, the first event will always be emitted
9168 Arguments:
9170 "name: string" (optional)
9172 net client name
9173 "path: string"
9175 device path
9176 Since: 1.6
9178 Example:
9180 <- { "event": "NIC_RX_FILTER_CHANGED",
9182 "data": { "name": "vnet0",
9183 "path": "/machine/peripheral/vnet0/virtio-backend" },
9184 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
9185 }
9186 AnnounceParameters (Object)
9188 Parameters for self-announce timers
9190 Members:
9192 "initial: int"
9194 Initial delay (in ms) before sending the first GARP/RARP
9195 announcement
9196 "max: int"
9198 Maximum delay (in ms) between GARP/RARP announcement packets
9199 "rounds: int"
9201 Number of self-announcement attempts
9202 "step: int"
9204 Delay increase (in ms) after each self-announcement attempt
9205 "interfaces: array of string" (optional)
9207 An optional list of interface names, which restricts the
9208 announcement to the listed interfaces. (Since 4.1)
9209 "id: string" (optional)
9211 A name to be used to identify an instance of announce-timers and to
9212 allow it to modified later. Not for use as part of the migration
9213 parameters. (Since 4.1)
9214 Since: 4.0
9216 announce-self (Command) Trigger generation of broadcast RARP frames to
9218 update network switches. This can be useful when network bonds fail-
9219 over the active slave.
9220 Arguments: the members of "AnnounceParameters"
9222 Example:
9224 -> { "execute": "announce-self",
9226 "arguments": {
9227 "initial": 50, "max": 550, "rounds": 10, "step": 50,
9228 "interfaces": ["vn2", "vn3"], "id": "bob" } }
9229 <- { "return": {} }
9230 Since: 4.0
9232 FAILOVER_NEGOTIATED (Event) Emitted when VIRTIO_NET_F_STANDBY was
9234 enabled during feature negotiation. Failover primary devices which
9235 were hidden (not hotplugged when requested) before will now be
9236 hotplugged by the virtio-net standby device.
9237 device-id: QEMU device id of the unplugged device
9239 Arguments:
9241 "device-id: string"
9243 Not documented
9244 Since: 4.2
9246 Example:
9248 <- { "event": "FAILOVER_NEGOTIATED",
9250 "data": "net1" }
9251 RDMA device
9253 RDMA_GID_STATUS_CHANGED (Event) Emitted when guest driver adds/deletes
9254 GID to/from device
9255 Arguments:
9257 "netdev: string"
9259 RoCE Network Device name
9260 "gid-status: boolean"
9262 Add or delete indication
9263 "subnet-prefix: int"
9265 Subnet Prefix
9266 "interface-id: int"
9268 Not documented
9269 "interface-id" : Interface ID
9271 Since: 4.0
9273 Example:
9275 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
9277 "event": "RDMA_GID_STATUS_CHANGED",
9278 "data":
9279 {"netdev": "bridge0",
9280 "interface-id": 15880512517475447892,
9281 "gid-status": true,
9282 "subnet-prefix": 33022}}
9283 Rocker switch device
9285 RockerSwitch (Object)
9286 Rocker switch information.
9288 Members:
9290 "name: string"
9292 switch name
9293 "id: int"
9295 switch ID
9296 "ports: int"
9298 number of front-panel ports
9299 Since: 2.4
9301 query-rocker (Command) Return rocker switch information.
9303 Arguments:
9305 "name: string"
9307 Not documented
9308 Returns: "Rocker" information
9310 Since: 2.4
9312 Example:
9314 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
9316 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
9317 RockerPortDuplex (Enum)
9319 An eumeration of port duplex states.
9321 Values:
9323 "half"
9325 half duplex
9326 "full"
9328 full duplex
9329 Since: 2.4
9331 RockerPortAutoneg (Enum)
9333 An eumeration of port autoneg states.
9335 Values:
9337 "off"
9339 autoneg is off
9340 "on"
9342 autoneg is on
9343 Since: 2.4
9345 RockerPort (Object)
9347 Rocker switch port information.
9349 Members:
9351 "name: string"
9353 port name
9354 "enabled: boolean"
9356 port is enabled for I/O
9357 "link-up: boolean"
9359 physical link is UP on port
9360 "speed: int"
9362 port link speed in Mbps
9363 "duplex: RockerPortDuplex"
9365 port link duplex
9366 "autoneg: RockerPortAutoneg"
9368 port link autoneg
9369 Since: 2.4
9371 query-rocker-ports (Command) Return rocker switch port information.
9373 Arguments:
9375 "name: string"
9377 Not documented
9378 Returns: a list of "RockerPort" information
9380 Since: 2.4
9382 Example:
9384 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
9386 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
9387 "autoneg": "off", "link-up": true, "speed": 10000},
9388 {"duplex": "full", "enabled": true, "name": "sw1.2",
9389 "autoneg": "off", "link-up": true, "speed": 10000}
9390 ]}
9391 RockerOfDpaFlowKey (Object)
9393 Rocker switch OF-DPA flow key
9395 Members:
9397 "priority: int"
9399 key priority, 0 being lowest priority
9400 "tbl-id: int"
9402 flow table ID
9403 "in-pport: int" (optional)
9405 physical input port
9406 "tunnel-id: int" (optional)
9408 tunnel ID
9409 "vlan-id: int" (optional)
9411 VLAN ID
9412 "eth-type: int" (optional)
9414 Ethernet header type
9415 "eth-src: string" (optional)
9417 Ethernet header source MAC address
9418 "eth-dst: string" (optional)
9420 Ethernet header destination MAC address
9421 "ip-proto: int" (optional)
9423 IP Header protocol field
9424 "ip-tos: int" (optional)
9426 IP header TOS field
9427 "ip-dst: string" (optional)
9429 IP header destination address
9430 Note: optional members may or may not appear in the flow key depending
9432 if they're relevant to the flow key.
9433 Since: 2.4
9435 RockerOfDpaFlowMask (Object)
9437 Rocker switch OF-DPA flow mask
9439 Members:
9441 "in-pport: int" (optional)
9443 physical input port
9444 "tunnel-id: int" (optional)
9446 tunnel ID
9447 "vlan-id: int" (optional)
9449 VLAN ID
9450 "eth-src: string" (optional)
9452 Ethernet header source MAC address
9453 "eth-dst: string" (optional)
9455 Ethernet header destination MAC address
9456 "ip-proto: int" (optional)
9458 IP Header protocol field
9459 "ip-tos: int" (optional)
9461 IP header TOS field
9462 Note: optional members may or may not appear in the flow mask depending
9464 if they're relevant to the flow mask.
9465 Since: 2.4
9467 RockerOfDpaFlowAction (Object)
9469 Rocker switch OF-DPA flow action
9471 Members:
9473 "goto-tbl: int" (optional)
9475 next table ID
9476 "group-id: int" (optional)
9478 group ID
9479 "tunnel-lport: int" (optional)
9481 tunnel logical port ID
9482 "vlan-id: int" (optional)
9484 VLAN ID
9485 "new-vlan-id: int" (optional)
9487 new VLAN ID
9488 "out-pport: int" (optional)
9490 physical output port
9491 Note: optional members may or may not appear in the flow action
9493 depending if they're relevant to the flow action.
9494 Since: 2.4
9496 RockerOfDpaFlow (Object)
9498 Rocker switch OF-DPA flow
9500 Members:
9502 "cookie: int"
9504 flow unique cookie ID
9505 "hits: int"
9507 count of matches (hits) on flow
9508 "key: RockerOfDpaFlowKey"
9510 flow key
9511 "mask: RockerOfDpaFlowMask"
9513 flow mask
9514 "action: RockerOfDpaFlowAction"
9516 flow action
9517 Since: 2.4
9519 query-rocker-of-dpa-flows (Command) Return rocker OF-DPA flow
9521 information.
9522 Arguments:
9524 "name: string"
9526 switch name
9527 "tbl-id: int" (optional)
9529 flow table ID. If tbl-id is not specified, returns flow
9530 information for all tables.
9531 Returns: rocker OF-DPA flow information
9533 Since: 2.4
9535 Example:
9537 -> { "execute": "query-rocker-of-dpa-flows",
9539 "arguments": { "name": "sw1" } }
9540 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
9541 "hits": 138,
9542 "cookie": 0,
9543 "action": {"goto-tbl": 10},
9544 "mask": {"in-pport": 4294901760}
9545 },
9546 {...more...},
9547 ]}
9548 RockerOfDpaGroup (Object)
9550 Rocker switch OF-DPA group
9552 Members:
9554 "id: int"
9556 group unique ID
9557 "type: int"
9559 group type
9560 "vlan-id: int" (optional)
9562 VLAN ID
9563 "pport: int" (optional)
9565 physical port number
9566 "index: int" (optional)
9568 group index, unique with group type
9569 "out-pport: int" (optional)
9571 output physical port number
9572 "group-id: int" (optional)
9574 next group ID
9575 "set-vlan-id: int" (optional)
9577 VLAN ID to set
9578 "pop-vlan: int" (optional)
9580 pop VLAN headr from packet
9581 "group-ids: array of int" (optional)
9583 list of next group IDs
9584 "set-eth-src: string" (optional)
9586 set source MAC address in Ethernet header
9587 "set-eth-dst: string" (optional)
9589 set destination MAC address in Ethernet header
9590 "ttl-check: int" (optional)
9592 perform TTL check
9593 Note: optional members may or may not appear in the group depending if
9595 they're relevant to the group type.
9596 Since: 2.4
9598 query-rocker-of-dpa-groups (Command) Return rocker OF-DPA group
9600 information.
9601 Arguments:
9603 "name: string"
9605 switch name
9606 "type: int" (optional)
9608 group type. If type is not specified, returns group information
9609 for all group types.
9610 Returns: rocker OF-DPA group information
9612 Since: 2.4
9614 Example:
9616 -> { "execute": "query-rocker-of-dpa-groups",
9618 "arguments": { "name": "sw1" } }
9619 <- { "return": [ {"type": 0, "out-pport": 2,
9620 "pport": 2, "vlan-id": 3841,
9621 "pop-vlan": 1, "id": 251723778},
9622 {"type": 0, "out-pport": 0,
9623 "pport": 0, "vlan-id": 3841,
9624 "pop-vlan": 1, "id": 251723776},
9625 {"type": 0, "out-pport": 1,
9626 "pport": 1, "vlan-id": 3840,
9627 "pop-vlan": 1, "id": 251658241},
9628 {"type": 0, "out-pport": 0,
9629 "pport": 0, "vlan-id": 3840,
9630 "pop-vlan": 1, "id": 251658240}
9631 ]}
9632 TPM (trusted platform module) devices
9634 TpmModel (Enum)
9635 An enumeration of TPM models
9637 Values:
9639 "tpm-tis"
9641 TPM TIS model
9642 "tpm-crb"
9644 TPM CRB model (since 2.12)
9645 "tpm-spapr"
9647 TPM SPAPR model (since 5.0)
9648 Since: 1.5
9650 query-tpm-models (Command) Return a list of supported TPM models
9652 Returns: a list of TpmModel
9654 Since: 1.5
9656 Example:
9658 -> { "execute": "query-tpm-models" }
9660 <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
9661 TpmType (Enum)
9663 An enumeration of TPM types
9665 Values:
9667 "passthrough"
9669 TPM passthrough type
9670 "emulator"
9672 Software Emulator TPM type Since: 2.11
9673 Since: 1.5
9675 query-tpm-types (Command) Return a list of supported TPM types
9677 Returns: a list of TpmType
9679 Since: 1.5
9681 Example:
9683 -> { "execute": "query-tpm-types" }
9685 <- { "return": [ "passthrough", "emulator" ] }
9686 TPMPassthroughOptions (Object)
9688 Information about the TPM passthrough type
9690 Members:
9692 "path: string" (optional)
9694 string describing the path used for accessing the TPM device
9695 "cancel-path: string" (optional)
9697 string showing the TPM's sysfs cancel file for cancellation of TPM
9698 commands while they are executing
9699 Since: 1.5
9701 TPMEmulatorOptions (Object)
9703 Information about the TPM emulator type
9705 Members:
9707 "chardev: string"
9709 Name of a unix socket chardev
9710 Since: 2.11
9712 TpmTypeOptions (Object)
9714 A union referencing different TPM backend types' configuration options
9716 Members:
9718 "type"
9720 - 'passthrough' The configuration options for the TPM passthrough
9721 type
9722 - 'emulator' The configuration options for TPM emulator backend
9724 type
9725 "data: TPMPassthroughOptions" when "type" is "passthrough"
9727 "data: TPMEmulatorOptions" when "type" is "emulator"
9728 Since: 1.5
9730 TPMInfo (Object)
9732 Information about the TPM
9734 Members:
9736 "id: string"
9738 The Id of the TPM
9739 "model: TpmModel"
9741 The TPM frontend model
9742 "options: TpmTypeOptions"
9744 The TPM (backend) type configuration options
9745 Since: 1.5
9747 query-tpm (Command) Return information about the TPM device
9749 Returns: "TPMInfo" on success
9751 Since: 1.5
9753 Example:
9755 -> { "execute": "query-tpm" }
9757 <- { "return":
9758 [
9759 { "model": "tpm-tis",
9760 "options":
9761 { "type": "passthrough",
9762 "data":
9763 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
9764 "path": "/dev/tpm0"
9765 }
9766 },
9767 "id": "tpm0"
9768 }
9769 ]
9770 }
9771 Remote desktop
9773 set_password (Command) Sets the password of a remote display session.
9774 Arguments:
9776 "protocol: string"
9778 - 'vnc' to modify the VNC server password
9779 - 'spice' to modify the Spice server password
9781 "password: string"
9783 the new password
9784 "connected: string" (optional)
9786 how to handle existing clients when changing the password. If
9787 nothing is specified, defaults to 'keep' 'fail' to fail the command
9788 if clients are connected 'disconnect' to disconnect existing
9789 clients 'keep' to maintain existing clients
9790 Returns:
9792 - Nothing on success
9794 - If Spice is not enabled, DeviceNotFound
9796 Since: 0.14.0
9798 Example:
9800 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
9802 "password": "secret" } }
9803 <- { "return": {} }
9804 expire_password (Command) Expire the password of a remote display
9806 server.
9807 Arguments:
9809 "protocol: string"
9811 the name of the remote display protocol 'vnc' or 'spice'
9812 "time: string"
9814 when to expire the password.
9815 - 'now' to expire the password immediately
9817 - 'never' to cancel password expiration
9819 - '+INT' where INT is the number of seconds from now (integer)
9821 - 'INT' where INT is the absolute time in seconds
9823 Returns:
9825 - Nothing on success
9827 - If "protocol" is 'spice' and Spice is not active, DeviceNotFound
9829 Since: 0.14.0
9831 Notes: Time is relative to the server and currently there is no way to
9833 coordinate server time with client time. It is not recommended to use
9834 the absolute time version of the "time" parameter unless you're sure
9835 you are on the same machine as the QEMU instance.
9836 Example:
9838 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
9840 "time": "+60" } }
9841 <- { "return": {} }
9842 screendump (Command) Write a PPM of the VGA screen to a file.
9844 Arguments:
9846 "filename: string"
9848 the path of a new PPM file to store the image
9849 "device: string" (optional)
9851 ID of the display device that should be dumped. If this parameter
9852 is missing, the primary display will be used. (Since 2.12)
9853 "head: int" (optional)
9855 head to use in case the device supports multiple heads. If this
9856 parameter is missing, head #0 will be used. Also note that the head
9857 can only be specified in conjunction with the device ID. (Since
9858 2.12)
9859 Returns: Nothing on success
9861 Since: 0.14.0
9863 Example:
9865 -> { "execute": "screendump",
9867 "arguments": { "filename": "/tmp/image" } }
9868 <- { "return": {} }
9869 Spice
9871 SpiceBasicInfo (Object)
9873 The basic information for SPICE network connection
9875 Members:
9877 "host: string"
9879 IP address
9880 "port: string"
9882 port number
9883 "family: NetworkAddressFamily"
9885 address family
9886 Since: 2.1
9888 If: "defined(CONFIG_SPICE)"
9890 SpiceServerInfo (Object)
9892 Information about a SPICE server
9894 Members:
9896 "auth: string" (optional)
9898 authentication method
9899 The members of "SpiceBasicInfo"
9901 Since: 2.1
9903 If: "defined(CONFIG_SPICE)"
9905 SpiceChannel (Object)
9907 Information about a SPICE client channel.
9909 Members:
9911 "connection-id: int"
9913 SPICE connection id number. All channels with the same id belong
9914 to the same SPICE session.
9915 "channel-type: int"
9917 SPICE channel type number. "1" is the main control channel, filter
9918 for this one if you want to track spice sessions only
9919 "channel-id: int"
9921 SPICE channel ID number. Usually "0", might be different when
9922 multiple channels of the same type exist, such as multiple display
9923 channels in a multihead setup
9924 "tls: boolean"
9926 true if the channel is encrypted, false otherwise.
9927 The members of "SpiceBasicInfo"
9929 Since: 0.14.0
9931 If: "defined(CONFIG_SPICE)"
9933 SpiceQueryMouseMode (Enum)
9935 An enumeration of Spice mouse states.
9937 Values:
9939 "client"
9941 Mouse cursor position is determined by the client.
9942 "server"
9944 Mouse cursor position is determined by the server.
9945 "unknown"
9947 No information is available about mouse mode used by the spice
9948 server.
9949 Note: spice/enums.h has a SpiceMouseMode already, hence the name.
9951 Since: 1.1
9953 If: "defined(CONFIG_SPICE)"
9955 SpiceInfo (Object)
9957 Information about the SPICE session.
9959 Members:
9961 "enabled: boolean"
9963 true if the SPICE server is enabled, false otherwise
9964 "migrated: boolean"
9966 true if the last guest migration completed and spice migration had
9967 completed as well. false otherwise. (since 1.4)
9968 "host: string" (optional)
9970 The hostname the SPICE server is bound to. This depends on the
9971 name resolution on the host and may be an IP address.
9972 "port: int" (optional)
9974 The SPICE server's port number.
9975 "compiled-version: string" (optional)
9977 SPICE server version.
9978 "tls-port: int" (optional)
9980 The SPICE server's TLS port number.
9981 "auth: string" (optional)
9983 the current authentication type used by the server
9984 - 'none' if no authentication is being used
9986 - 'spice' uses SASL or direct TLS authentication, depending on
9988 command line options
9989 "mouse-mode: SpiceQueryMouseMode"
9991 The mode in which the mouse cursor is displayed currently. Can be
9992 determined by the client or the server, or unknown if spice server
9993 doesn't provide this information. (since: 1.1)
9994 "channels: array of SpiceChannel" (optional)
9996 a list of "SpiceChannel" for each active spice channel
9997 Since: 0.14.0
9999 If: "defined(CONFIG_SPICE)"
10001 query-spice (Command) Returns information about the current SPICE
10003 server
10004 Returns: "SpiceInfo"
10006 Since: 0.14.0
10008 Example:
10010 -> { "execute": "query-spice" }
10012 <- { "return": {
10013 "enabled": true,
10014 "auth": "spice",
10015 "port": 5920,
10016 "tls-port": 5921,
10017 "host": "0.0.0.0",
10018 "channels": [
10019 {
10020 "port": "54924",
10021 "family": "ipv4",
10022 "channel-type": 1,
10023 "connection-id": 1804289383,
10024 "host": "127.0.0.1",
10025 "channel-id": 0,
10026 "tls": true
10027 },
10028 {
10029 "port": "36710",
10030 "family": "ipv4",
10031 "channel-type": 4,
10032 "connection-id": 1804289383,
10033 "host": "127.0.0.1",
10034 "channel-id": 0,
10035 "tls": false
10036 },
10037 [ ... more channels follow ... ]
10038 ]
10039 }
10040 }
10041 If: "defined(CONFIG_SPICE)"
10043 SPICE_CONNECTED (Event) Emitted when a SPICE client establishes a
10045 connection
10046 Arguments:
10048 "server: SpiceBasicInfo"
10050 server information
10051 "client: SpiceBasicInfo"
10053 client information
10054 Since: 0.14.0
10056 Example:
10058 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
10060 "event": "SPICE_CONNECTED",
10061 "data": {
10062 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
10063 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
10064 }}
10065 If: "defined(CONFIG_SPICE)"
10067 SPICE_INITIALIZED (Event) Emitted after initial handshake and
10069 authentication takes place (if any) and the SPICE channel is up and
10070 running
10071 Arguments:
10073 "server: SpiceServerInfo"
10075 server information
10076 "client: SpiceChannel"
10078 client information
10079 Since: 0.14.0
10081 Example:
10083 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
10085 "event": "SPICE_INITIALIZED",
10086 "data": {"server": {"auth": "spice", "port": "5921",
10087 "family": "ipv4", "host": "127.0.0.1"},
10088 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
10089 "connection-id": 1804289383, "host": "127.0.0.1",
10090 "channel-id": 0, "tls": true}
10091 }}
10092 If: "defined(CONFIG_SPICE)"
10094 SPICE_DISCONNECTED (Event) Emitted when the SPICE connection is closed
10096 Arguments:
10098 "server: SpiceBasicInfo"
10100 server information
10101 "client: SpiceBasicInfo"
10103 client information
10104 Since: 0.14.0
10106 Example:
10108 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
10110 "event": "SPICE_DISCONNECTED",
10111 "data": {
10112 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
10113 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
10114 }}
10115 If: "defined(CONFIG_SPICE)"
10117 SPICE_MIGRATE_COMPLETED (Event) Emitted when SPICE migration has
10119 completed
10120 Since: 1.3
10122 Example:
10124 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
10126 "event": "SPICE_MIGRATE_COMPLETED" }
10127 If: "defined(CONFIG_SPICE)"
10129 VNC
10131 VncBasicInfo (Object)
10133 The basic information for vnc network connection
10135 Members:
10137 "host: string"
10139 IP address
10140 "service: string"
10142 The service name of the vnc port. This may depend on the host
10143 system's service database so symbolic names should not be relied
10144 on.
10145 "family: NetworkAddressFamily"
10147 address family
10148 "websocket: boolean"
10150 true in case the socket is a websocket (since 2.3).
10151 Since: 2.1
10153 If: "defined(CONFIG_VNC)"
10155 VncServerInfo (Object)
10157 The network connection information for server
10159 Members:
10161 "auth: string" (optional)
10163 authentication method used for the plain (non-websocket) VNC server
10164 The members of "VncBasicInfo"
10166 Since: 2.1
10168 If: "defined(CONFIG_VNC)"
10170 VncClientInfo (Object)
10172 Information about a connected VNC client.
10174 Members:
10176 "x509_dname: string" (optional)
10178 If x509 authentication is in use, the Distinguished Name of the
10179 client.
10180 "sasl_username: string" (optional)
10182 If SASL authentication is in use, the SASL username used for
10183 authentication.
10184 The members of "VncBasicInfo"
10186 Since: 0.14.0
10188 If: "defined(CONFIG_VNC)"
10190 VncInfo (Object)
10192 Information about the VNC session.
10194 Members:
10196 "enabled: boolean"
10198 true if the VNC server is enabled, false otherwise
10199 "host: string" (optional)
10201 The hostname the VNC server is bound to. This depends on the name
10202 resolution on the host and may be an IP address.
10203 "family: NetworkAddressFamily" (optional)
10205 - 'ipv6' if the host is listening for IPv6 connections
10206 - 'ipv4' if the host is listening for IPv4 connections
10208 - 'unix' if the host is listening on a unix domain socket
10210 - 'unknown' otherwise
10212 "service: string" (optional)
10214 The service name of the server's port. This may depends on the
10215 host system's service database so symbolic names should not be
10216 relied on.
10217 "auth: string" (optional)
10219 the current authentication type used by the server
10220 - 'none' if no authentication is being used
10222 - 'vnc' if VNC authentication is being used
10224 - 'vencrypt+plain' if VEncrypt is used with plain text
10226 authentication
10227 - 'vencrypt+tls+none' if VEncrypt is used with TLS and no
10229 authentication
10230 - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC
10232 authentication
10233 - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain
10235 text auth
10236 - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
10238 - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
10240 - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain
10242 text auth
10243 - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
10245 - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
10247 auth
10248 "clients: array of VncClientInfo" (optional)
10250 a list of "VncClientInfo" of all currently connected clients
10251 Since: 0.14.0
10253 If: "defined(CONFIG_VNC)"
10255 VncPrimaryAuth (Enum)
10257 vnc primary authentication method.
10259 Values:
10261 "none"
10263 Not documented
10264 "vnc"
10266 Not documented
10267 "ra2"
10269 Not documented
10270 "ra2ne"
10272 Not documented
10273 "tight"
10275 Not documented
10276 "ultra"
10278 Not documented
10279 "tls"
10281 Not documented
10282 "vencrypt"
10284 Not documented
10285 "sasl"
10287 Not documented
10288 Since: 2.3
10290 If: "defined(CONFIG_VNC)"
10292 VncVencryptSubAuth (Enum)
10294 vnc sub authentication method with vencrypt.
10296 Values:
10298 "plain"
10300 Not documented
10301 "tls-none"
10303 Not documented
10304 "x509-none"
10306 Not documented
10307 "tls-vnc"
10309 Not documented
10310 "x509-vnc"
10312 Not documented
10313 "tls-plain"
10315 Not documented
10316 "x509-plain"
10318 Not documented
10319 "tls-sasl"
10321 Not documented
10322 "x509-sasl"
10324 Not documented
10325 Since: 2.3
10327 If: "defined(CONFIG_VNC)"
10329 VncServerInfo2 (Object)
10331 The network connection information for server
10333 Members:
10335 "auth: VncPrimaryAuth"
10337 The current authentication type used by the servers
10338 "vencrypt: VncVencryptSubAuth" (optional)
10340 The vencrypt sub authentication type used by the servers, only
10341 specified in case auth == vencrypt.
10342 The members of "VncBasicInfo"
10344 Since: 2.9
10346 If: "defined(CONFIG_VNC)"
10348 VncInfo2 (Object)
10350 Information about a vnc server
10352 Members:
10354 "id: string"
10356 vnc server name.
10357 "server: array of VncServerInfo2"
10359 A list of "VncBasincInfo" describing all listening sockets. The
10360 list can be empty (in case the vnc server is disabled). It also
10361 may have multiple entries: normal + websocket, possibly also ipv4 +
10362 ipv6 in the future.
10363 "clients: array of VncClientInfo"
10365 A list of "VncClientInfo" of all currently connected clients. The
10366 list can be empty, for obvious reasons.
10367 "auth: VncPrimaryAuth"
10369 The current authentication type used by the non-websockets servers
10370 "vencrypt: VncVencryptSubAuth" (optional)
10372 The vencrypt authentication type used by the servers, only
10373 specified in case auth == vencrypt.
10374 "display: string" (optional)
10376 The display device the vnc server is linked to.
10377 Since: 2.3
10379 If: "defined(CONFIG_VNC)"
10381 query-vnc (Command) Returns information about the current VNC server
10383 Returns: "VncInfo"
10385 Since: 0.14.0
10387 Example:
10389 -> { "execute": "query-vnc" }
10391 <- { "return": {
10392 "enabled":true,
10393 "host":"0.0.0.0",
10394 "service":"50402",
10395 "auth":"vnc",
10396 "family":"ipv4",
10397 "clients":[
10398 {
10399 "host":"127.0.0.1",
10400 "service":"50401",
10401 "family":"ipv4"
10402 }
10403 ]
10404 }
10405 }
10406 If: "defined(CONFIG_VNC)"
10408 query-vnc-servers (Command) Returns a list of vnc servers. The list
10410 can be empty.
10411 Returns: a list of "VncInfo2"
10413 Since: 2.3
10415 If: "defined(CONFIG_VNC)"
10417 change-vnc-password (Command) Change the VNC server password.
10419 Arguments:
10421 "password: string"
10423 the new password to use with VNC authentication
10424 Since: 1.1
10426 Notes: An empty password in this command will set the password to the
10428 empty string. Existing clients are unaffected by executing this
10429 command.
10430 If: "defined(CONFIG_VNC)"
10432 VNC_CONNECTED (Event) Emitted when a VNC client establishes a
10434 connection
10435 Arguments:
10437 "server: VncServerInfo"
10439 server information
10440 "client: VncBasicInfo"
10442 client information
10443 Note: This event is emitted before any authentication takes place, thus
10445 the authentication ID is not provided
10446 Since: 0.13.0
10448 Example:
10450 <- { "event": "VNC_CONNECTED",
10452 "data": {
10453 "server": { "auth": "sasl", "family": "ipv4",
10454 "service": "5901", "host": "0.0.0.0" },
10455 "client": { "family": "ipv4", "service": "58425",
10456 "host": "127.0.0.1" } },
10457 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10458 If: "defined(CONFIG_VNC)"
10460 VNC_INITIALIZED (Event) Emitted after authentication takes place (if
10462 any) and the VNC session is made active
10463 Arguments:
10465 "server: VncServerInfo"
10467 server information
10468 "client: VncClientInfo"
10470 client information
10471 Since: 0.13.0
10473 Example:
10475 <- { "event": "VNC_INITIALIZED",
10477 "data": {
10478 "server": { "auth": "sasl", "family": "ipv4",
10479 "service": "5901", "host": "0.0.0.0"},
10480 "client": { "family": "ipv4", "service": "46089",
10481 "host": "127.0.0.1", "sasl_username": "luiz" } },
10482 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
10483 If: "defined(CONFIG_VNC)"
10485 VNC_DISCONNECTED (Event) Emitted when the connection is closed
10487 Arguments:
10489 "server: VncServerInfo"
10491 server information
10492 "client: VncClientInfo"
10494 client information
10495 Since: 0.13.0
10497 Example:
10499 <- { "event": "VNC_DISCONNECTED",
10501 "data": {
10502 "server": { "auth": "sasl", "family": "ipv4",
10503 "service": "5901", "host": "0.0.0.0" },
10504 "client": { "family": "ipv4", "service": "58425",
10505 "host": "127.0.0.1", "sasl_username": "luiz" } },
10506 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10507 If: "defined(CONFIG_VNC)"
10509 Input
10511 MouseInfo (Object)
10512 Information about a mouse device.
10514 Members:
10516 "name: string"
10518 the name of the mouse device
10519 "index: int"
10521 the index of the mouse device
10522 "current: boolean"
10524 true if this device is currently receiving mouse events
10525 "absolute: boolean"
10527 true if this device supports absolute coordinates as input
10528 Since: 0.14.0
10530 query-mice (Command) Returns information about each active mouse
10532 device
10533 Returns: a list of "MouseInfo" for each device
10535 Since: 0.14.0
10537 Example:
10539 -> { "execute": "query-mice" }
10541 <- { "return": [
10542 {
10543 "name":"QEMU Microsoft Mouse",
10544 "index":0,
10545 "current":false,
10546 "absolute":false
10547 },
10548 {
10549 "name":"QEMU PS/2 Mouse",
10550 "index":1,
10551 "current":true,
10552 "absolute":true
10553 }
10554 ]
10555 }
10556 QKeyCode (Enum)
10558 An enumeration of key name.
10560 This is used by the "send-key" command.
10562 Values:
10564 "unmapped"
10566 since 2.0
10567 "pause"
10569 since 2.0
10570 "ro"
10572 since 2.4
10573 "kp_comma"
10575 since 2.4
10576 "kp_equals"
10578 since 2.6
10579 "power"
10581 since 2.6
10582 "hiragana"
10584 since 2.9
10585 "henkan"
10587 since 2.9
10588 "yen"
10590 since 2.9
10591 "sleep"
10593 since 2.10
10594 "wake"
10596 since 2.10
10597 "audionext"
10599 since 2.10
10600 "audioprev"
10602 since 2.10
10603 "audiostop"
10605 since 2.10
10606 "audioplay"
10608 since 2.10
10609 "audiomute"
10611 since 2.10
10612 "volumeup"
10614 since 2.10
10615 "volumedown"
10617 since 2.10
10618 "mediaselect"
10620 since 2.10
10621 "mail"
10623 since 2.10
10624 "calculator"
10626 since 2.10
10627 "computer"
10629 since 2.10
10630 "ac_home"
10632 since 2.10
10633 "ac_back"
10635 since 2.10
10636 "ac_forward"
10638 since 2.10
10639 "ac_refresh"
10641 since 2.10
10642 "ac_bookmarks"
10644 since 2.10
10645 "muhenkan"
10647 since 2.12
10648 "katakanahiragana"
10650 since 2.12
10651 "shift"
10653 Not documented
10654 "shift_r"
10656 Not documented
10657 "alt"
10659 Not documented
10660 "alt_r"
10662 Not documented
10663 "ctrl"
10665 Not documented
10666 "ctrl_r"
10668 Not documented
10669 "menu"
10671 Not documented
10672 "esc"
10674 Not documented
10675 1 Not documented
10677 2 Not documented
10679 3 Not documented
10681 4 Not documented
10683 5 Not documented
10685 6 Not documented
10687 7 Not documented
10689 8 Not documented
10691 9 Not documented
10693 0 Not documented
10695 "minus"
10697 Not documented
10698 "equal"
10700 Not documented
10701 "backspace"
10703 Not documented
10704 "tab"
10706 Not documented
10707 "q" Not documented
10709 "w" Not documented
10711 "e" Not documented
10713 "r" Not documented
10715 "t" Not documented
10717 "y" Not documented
10719 "u" Not documented
10721 "i" Not documented
10723 "o" Not documented
10725 "p" Not documented
10727 "bracket_left"
10729 Not documented
10730 "bracket_right"
10732 Not documented
10733 "ret"
10735 Not documented
10736 "a" Not documented
10738 "s" Not documented
10740 "d" Not documented
10742 "f" Not documented
10744 "g" Not documented
10746 "h" Not documented
10748 "j" Not documented
10750 "k" Not documented
10752 "l" Not documented
10754 "semicolon"
10756 Not documented
10757 "apostrophe"
10759 Not documented
10760 "grave_accent"
10762 Not documented
10763 "backslash"
10765 Not documented
10766 "z" Not documented
10768 "x" Not documented
10770 "c" Not documented
10772 "v" Not documented
10774 "b" Not documented
10776 "n" Not documented
10778 "m" Not documented
10780 "comma"
10782 Not documented
10783 "dot"
10785 Not documented
10786 "slash"
10788 Not documented
10789 "asterisk"
10791 Not documented
10792 "spc"
10794 Not documented
10795 "caps_lock"
10797 Not documented
10798 "f1"
10800 Not documented
10801 "f2"
10803 Not documented
10804 "f3"
10806 Not documented
10807 "f4"
10809 Not documented
10810 "f5"
10812 Not documented
10813 "f6"
10815 Not documented
10816 "f7"
10818 Not documented
10819 "f8"
10821 Not documented
10822 "f9"
10824 Not documented
10825 "f10"
10827 Not documented
10828 "num_lock"
10830 Not documented
10831 "scroll_lock"
10833 Not documented
10834 "kp_divide"
10836 Not documented
10837 "kp_multiply"
10839 Not documented
10840 "kp_subtract"
10842 Not documented
10843 "kp_add"
10845 Not documented
10846 "kp_enter"
10848 Not documented
10849 "kp_decimal"
10851 Not documented
10852 "sysrq"
10854 Not documented
10855 "kp_0"
10857 Not documented
10858 "kp_1"
10860 Not documented
10861 "kp_2"
10863 Not documented
10864 "kp_3"
10866 Not documented
10867 "kp_4"
10869 Not documented
10870 "kp_5"
10872 Not documented
10873 "kp_6"
10875 Not documented
10876 "kp_7"
10878 Not documented
10879 "kp_8"
10881 Not documented
10882 "kp_9"
10884 Not documented
10885 "less"
10887 Not documented
10888 "f11"
10890 Not documented
10891 "f12"
10893 Not documented
10894 "print"
10896 Not documented
10897 "home"
10899 Not documented
10900 "pgup"
10902 Not documented
10903 "pgdn"
10905 Not documented
10906 "end"
10908 Not documented
10909 "left"
10911 Not documented
10912 "up"
10914 Not documented
10915 "down"
10917 Not documented
10918 "right"
10920 Not documented
10921 "insert"
10923 Not documented
10924 "delete"
10926 Not documented
10927 "stop"
10929 Not documented
10930 "again"
10932 Not documented
10933 "props"
10935 Not documented
10936 "undo"
10938 Not documented
10939 "front"
10941 Not documented
10942 "copy"
10944 Not documented
10945 "open"
10947 Not documented
10948 "paste"
10950 Not documented
10951 "find"
10953 Not documented
10954 "cut"
10956 Not documented
10957 "lf"
10959 Not documented
10960 "help"
10962 Not documented
10963 "meta_l"
10965 Not documented
10966 "meta_r"
10968 Not documented
10969 "compose"
10971 Not documented
10972 'sysrq' was mistakenly added to hack around the fact that the ps2
10974 driver was not generating correct scancodes sequences when 'alt+print'
10975 was pressed. This flaw is now fixed and the 'sysrq' key serves no
10976 further purpose. Any further use of 'sysrq' will be transparently
10977 changed to 'print', so they are effectively synonyms.
10978 Since: 1.3.0
10980 KeyValue (Object)
10982 Represents a keyboard key.
10984 Members:
10986 "type"
10988 One of "number", "qcode"
10989 "data: int" when "type" is "number"
10991 "data: QKeyCode" when "type" is "qcode"
10992 Since: 1.3.0
10994 send-key (Command) Send keys to guest.
10996 Arguments:
10998 "keys: array of KeyValue"
11000 An array of "KeyValue" elements. All "KeyValues" in this array are
11001 simultaneously sent to the guest. A "KeyValue".number value is sent
11002 directly to the guest, while "KeyValue".qcode must be a valid
11003 "QKeyCode" value
11004 "hold-time: int" (optional)
11006 time to delay key up events, milliseconds. Defaults to 100
11007 Returns:
11009 - Nothing on success
11011 - If key is unknown or redundant, InvalidParameter
11013 Since: 1.3.0
11015 Example:
11017 -> { "execute": "send-key",
11019 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
11020 { "type": "qcode", "data": "alt" },
11021 { "type": "qcode", "data": "delete" } ] } }
11022 <- { "return": {} }
11023 InputButton (Enum)
11025 Button of a pointer input device (mouse, tablet).
11027 Values:
11029 "side"
11031 front side button of a 5-button mouse (since 2.9)
11032 "extra"
11034 rear side button of a 5-button mouse (since 2.9)
11035 "left"
11037 Not documented
11038 "middle"
11040 Not documented
11041 "right"
11043 Not documented
11044 "wheel-up"
11046 Not documented
11047 "wheel-down"
11049 Not documented
11050 Since: 2.0
11052 InputAxis (Enum)
11054 Position axis of a pointer input device (mouse, tablet).
11056 Values:
11058 "x" Not documented
11060 "y" Not documented
11062 Since: 2.0
11064 InputKeyEvent (Object)
11066 Keyboard input event.
11068 Members:
11070 "key: KeyValue"
11072 Which key this event is for.
11073 "down: boolean"
11075 True for key-down and false for key-up events.
11076 Since: 2.0
11078 InputBtnEvent (Object)
11080 Pointer button input event.
11082 Members:
11084 "button: InputButton"
11086 Which button this event is for.
11087 "down: boolean"
11089 True for key-down and false for key-up events.
11090 Since: 2.0
11092 InputMoveEvent (Object)
11094 Pointer motion input event.
11096 Members:
11098 "axis: InputAxis"
11100 Which axis is referenced by "value".
11101 "value: int"
11103 Pointer position. For absolute coordinates the valid range is 0 ->
11104 0x7ffff
11105 Since: 2.0
11107 InputEvent (Object)
11109 Input event union.
11111 Members:
11113 "type"
11115 the input type, one of:
11116 - 'key': Input event of Keyboard
11118 - 'btn': Input event of pointer buttons
11120 - 'rel': Input event of relative pointer motion
11122 - 'abs': Input event of absolute pointer motion
11124 "data: InputKeyEvent" when "type" is "key"
11126 "data: InputBtnEvent" when "type" is "btn"
11127 "data: InputMoveEvent" when "type" is "rel"
11128 "data: InputMoveEvent" when "type" is "abs"
11129 Since: 2.0
11131 input-send-event (Command) Send input event(s) to guest.
11133 The "device" and "head" parameters can be used to send the input event
11135 to specific input devices in case (a) multiple input devices of the
11136 same kind are added to the virtual machine and (b) you have configured
11137 input routing (see docs/multiseat.txt) for those input devices. The
11138 parameters work exactly like the device and head properties of input
11139 devices. If "device" is missing, only devices that have no input
11140 routing config are admissible. If "device" is specified, both input
11141 devices with and without input routing config are admissible, but
11142 devices with input routing config take precedence.
11143 Arguments:
11145 "device: string" (optional)
11147 display device to send event(s) to.
11148 "head: int" (optional)
11150 head to send event(s) to, in case the display device supports
11151 multiple scanouts.
11152 "events: array of InputEvent"
11154 List of InputEvent union.
11155 Returns: Nothing on success.
11157 Since: 2.6
11159 Note: The consoles are visible in the qom tree, under
11161 /backend/console[$index]. They have a device link and head property, so
11162 it is possible to map which console belongs to which device and
11163 display.
11164 Example:
11166 1. Press left mouse button.
11168 -> { "execute": "input-send-event",
11170 "arguments": { "device": "video0",
11171 "events": [ { "type": "btn",
11172 "data" : { "down": true, "button": "left" } } ] } }
11173 <- { "return": {} }
11174 -> { "execute": "input-send-event",
11176 "arguments": { "device": "video0",
11177 "events": [ { "type": "btn",
11178 "data" : { "down": false, "button": "left" } } ] } }
11179 <- { "return": {} }
11180 2. Press ctrl-alt-del.
11182 -> { "execute": "input-send-event",
11184 "arguments": { "events": [
11185 { "type": "key", "data" : { "down": true,
11186 "key": {"type": "qcode", "data": "ctrl" } } },
11187 { "type": "key", "data" : { "down": true,
11188 "key": {"type": "qcode", "data": "alt" } } },
11189 { "type": "key", "data" : { "down": true,
11190 "key": {"type": "qcode", "data": "delete" } } } ] } }
11191 <- { "return": {} }
11192 3. Move mouse pointer to absolute coordinates (20000, 400).
11194 -> { "execute": "input-send-event" ,
11196 "arguments": { "events": [
11197 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
11198 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
11199 <- { "return": {} }
11200 GrabToggleKeys (Enum)
11202 Keys to toggle input-linux between host and guest.
11204 Values:
11206 "ctrl-ctrl"
11208 Not documented
11209 "alt-alt"
11211 Not documented
11212 "shift-shift"
11214 Not documented
11215 "meta-meta"
11217 Not documented
11218 "scrolllock"
11220 Not documented
11221 "ctrl-scrolllock"
11223 Not documented
11224 Since: 4.0
11226 DisplayGTK (Object)
11228 GTK display options.
11230 Members:
11232 "grab-on-hover: boolean" (optional)
11234 Grab keyboard input on mouse hover.
11235 "zoom-to-fit: boolean" (optional)
11237 Zoom guest display to fit into the host window. When turned off
11238 the host window will be resized instead. In case the display
11239 device can notify the guest on window resizes (virtio-gpu) this
11240 will default to "on", assuming the guest will resize the display to
11241 match the window size then. Otherwise it defaults to "off". Since
11242 3.1
11243 Since: 2.12
11245 DisplayEGLHeadless (Object)
11247 EGL headless display options.
11249 Members:
11251 "rendernode: string" (optional)
11253 Which DRM render node should be used. Default is the first
11254 available node on the host.
11255 Since: 3.1
11257 DisplayGLMode (Enum)
11259 Display OpenGL mode.
11261 Values:
11263 "off"
11265 Disable OpenGL (default).
11266 "on"
11268 Use OpenGL, pick context type automatically. Would better be named
11269 'auto' but is called 'on' for backward compatibility with bool
11270 type.
11271 "core"
11273 Use OpenGL with Core (desktop) Context.
11274 "es"
11276 Use OpenGL with ES (embedded systems) Context.
11277 Since: 3.0
11279 DisplayCurses (Object)
11281 Curses display options.
11283 Members:
11285 "charset: string" (optional)
11287 Font charset used by guest (default: CP437).
11288 Since: 4.0
11290 DisplayType (Enum)
11292 Display (user interface) type.
11294 Values:
11296 "default"
11298 The default user interface, selecting from the first available of
11299 gtk, sdl, cocoa, and vnc.
11300 "none"
11302 No user interface or video output display. The guest will still see
11303 an emulated graphics card, but its output will not be displayed to
11304 the QEMU user.
11305 "gtk"
11307 The GTK user interface.
11308 "sdl"
11310 The SDL user interface.
11311 "egl-headless"
11313 No user interface, offload GL operations to a local DRI device.
11314 Graphical display need to be paired with VNC or Spice. (Since 3.1)
11315 "curses"
11317 Display video output via curses. For graphics device models which
11318 support a text mode, QEMU can display this output using a
11319 curses/ncurses interface. Nothing is displayed when the graphics
11320 device is in graphical mode or if the graphics device does not
11321 support a text mode. Generally only the VGA device models support
11322 text mode.
11323 "cocoa"
11325 The Cocoa user interface.
11326 "spice-app"
11328 Set up a Spice server and run the default associated application to
11329 connect to it. The server will redirect the serial console and QEMU
11330 monitors. (Since 4.0)
11331 Since: 2.12
11333 DisplayOptions (Object)
11335 Display (user interface) options.
11337 Members:
11339 "type: DisplayType"
11341 Which DisplayType qemu should use.
11342 "full-screen: boolean" (optional)
11344 Start user interface in fullscreen mode (default: off).
11345 "window-close: boolean" (optional)
11347 Allow to quit qemu with window close button (default: on).
11348 "show-cursor: boolean" (optional)
11350 Force showing the mouse cursor (default: off). (since: 5.0)
11351 "gl: DisplayGLMode" (optional)
11353 Enable OpenGL support (default: off).
11354 The members of "DisplayGTK" when "type" is "gtk"
11356 The members of "DisplayCurses" when "type" is "curses"
11357 The members of "DisplayEGLHeadless" when "type" is "egl-headless"
11358 Since: 2.12
11360 query-display-options (Command) Returns information about display
11362 configuration
11363 Returns: "DisplayOptions"
11365 Since: 3.1
11367 QAuthZListPolicy (Enum)
11369 The authorization policy result
11371 Values:
11373 "deny"
11375 deny access
11376 "allow"
11378 allow access
11379 Since: 4.0
11381 QAuthZListFormat (Enum)
11383 The authorization policy match format
11385 Values:
11387 "exact"
11389 an exact string match
11390 "glob"
11392 string with ? and * shell wildcard support
11393 Since: 4.0
11395 QAuthZListRule (Object)
11397 A single authorization rule.
11399 Members:
11401 "match: string"
11403 a string or glob to match against a user identity
11404 "policy: QAuthZListPolicy"
11406 the result to return if "match" evaluates to true
11407 "format: QAuthZListFormat" (optional)
11409 the format of the "match" rule (default 'exact')
11410 Since: 4.0
11412 QAuthZListRuleListHack (Object)
11414 Not exposed via QMP; hack to generate QAuthZListRuleList for use
11416 internally by the code.
11417 Members:
11419 "unused: array of QAuthZListRule"
11421 Not documented
11422 Since: 4.0
11424 Migration
11426 MigrationStats (Object)
11427 Detailed migration status.
11429 Members:
11431 "transferred: int"
11433 amount of bytes already transferred to the target VM
11434 "remaining: int"
11436 amount of bytes remaining to be transferred to the target VM
11437 "total: int"
11439 total amount of bytes involved in the migration process
11440 "duplicate: int"
11442 number of duplicate (zero) pages (since 1.2)
11443 "skipped: int"
11445 number of skipped zero pages (since 1.5)
11446 "normal: int"
11448 number of normal pages (since 1.2)
11449 "normal-bytes: int"
11451 number of normal bytes sent (since 1.2)
11452 "dirty-pages-rate: int"
11454 number of pages dirtied by second by the guest (since 1.3)
11455 "mbps: number"
11457 throughput in megabits/sec. (since 1.6)
11458 "dirty-sync-count: int"
11460 number of times that dirty ram was synchronized (since 2.1)
11461 "postcopy-requests: int"
11463 The number of page requests received from the destination (since
11464 2.7)
11465 "page-size: int"
11467 The number of bytes per page for the various page-based statistics
11468 (since 2.10)
11469 "multifd-bytes: int"
11471 The number of bytes sent through multifd (since 3.0)
11472 "pages-per-second: int"
11474 the number of memory pages transferred per second (Since 4.0)
11475 Since: 0.14.0
11477 XBZRLECacheStats (Object)
11479 Detailed XBZRLE migration cache statistics
11481 Members:
11483 "cache-size: int"
11485 XBZRLE cache size
11486 "bytes: int"
11488 amount of bytes already transferred to the target VM
11489 "pages: int"
11491 amount of pages transferred to the target VM
11492 "cache-miss: int"
11494 number of cache miss
11495 "cache-miss-rate: number"
11497 rate of cache miss (since 2.1)
11498 "encoding-rate: number"
11500 rate of encoded bytes (since 5.1)
11501 "overflow: int"
11503 number of overflows
11504 Since: 1.2
11506 CompressionStats (Object)
11508 Detailed migration compression statistics
11510 Members:
11512 "pages: int"
11514 amount of pages compressed and transferred to the target VM
11515 "busy: int"
11517 count of times that no free thread was available to compress data
11518 "busy-rate: number"
11520 rate of thread busy
11521 "compressed-size: int"
11523 amount of bytes after compression
11524 "compression-rate: number"
11526 rate of compressed size
11527 Since: 3.1
11529 MigrationStatus (Enum)
11531 An enumeration of migration status.
11533 Values:
11535 "none"
11537 no migration has ever happened.
11538 "setup"
11540 migration process has been initiated.
11541 "cancelling"
11543 in the process of cancelling migration.
11544 "cancelled"
11546 cancelling migration is finished.
11547 "active"
11549 in the process of doing migration.
11550 "postcopy-active"
11552 like active, but now in postcopy mode. (since 2.5)
11553 "postcopy-paused"
11555 during postcopy but paused. (since 3.0)
11556 "postcopy-recover"
11558 trying to recover from a paused postcopy. (since 3.0)
11559 "completed"
11561 migration is finished.
11562 "failed"
11564 some error occurred during migration process.
11565 "colo"
11567 VM is in the process of fault tolerance, VM can not get into this
11568 state unless colo capability is enabled for migration. (since 2.8)
11569 "pre-switchover"
11571 Paused before device serialisation. (since 2.11)
11572 "device"
11574 During device serialisation when pause-before-switchover is enabled
11575 (since 2.11)
11576 "wait-unplug"
11578 wait for device unplug request by guest OS to be completed. (since
11579 4.2)
11580 Since: 2.3
11582 MigrationInfo (Object)
11584 Information about current migration process.
11586 Members:
11588 "status: MigrationStatus" (optional)
11590 "MigrationStatus" describing the current migration status. If this
11591 field is not returned, no migration process has been initiated
11592 "ram: MigrationStats" (optional)
11594 "MigrationStats" containing detailed migration status, only
11595 returned if status is 'active' or 'completed'(since 1.2)
11596 "disk: MigrationStats" (optional)
11598 "MigrationStats" containing detailed disk migration status, only
11599 returned if status is 'active' and it is a block migration
11600 "xbzrle-cache: XBZRLECacheStats" (optional)
11602 "XBZRLECacheStats" containing detailed XBZRLE migration statistics,
11603 only returned if XBZRLE feature is on and status is 'active' or
11604 'completed' (since 1.2)
11605 "total-time: int" (optional)
11607 total amount of milliseconds since migration started. If migration
11608 has ended, it returns the total migration time. (since 1.2)
11609 "downtime: int" (optional)
11611 only present when migration finishes correctly total downtime in
11612 milliseconds for the guest. (since 1.3)
11613 "expected-downtime: int" (optional)
11615 only present while migration is active expected downtime in
11616 milliseconds for the guest in last walk of the dirty bitmap. (since
11617 1.3)
11618 "setup-time: int" (optional)
11620 amount of setup time in milliseconds before the iterations begin
11621 but after the QMP command is issued. This is designed to provide an
11622 accounting of any activities (such as RDMA pinning) which may be
11623 expensive, but do not actually occur during the iterative migration
11624 rounds themselves. (since 1.6)
11625 "cpu-throttle-percentage: int" (optional)
11627 percentage of time guest cpus are being throttled during auto-
11628 converge. This is only present when auto-converge has started
11629 throttling guest cpus. (Since 2.7)
11630 "error-desc: string" (optional)
11632 the human readable error description string, when "status" is
11633 'failed'. Clients should not attempt to parse the error strings.
11634 (Since 2.7)
11635 "postcopy-blocktime: int" (optional)
11637 total time when all vCPU were blocked during postcopy live
11638 migration. This is only present when the postcopy-blocktime
11639 migration capability is enabled. (Since 3.0)
11640 "postcopy-vcpu-blocktime: array of int" (optional)
11642 list of the postcopy blocktime per vCPU. This is only present when
11643 the postcopy-blocktime migration capability is enabled. (Since 3.0)
11644 "compression: CompressionStats" (optional)
11646 migration compression statistics, only returned if compression
11647 feature is on and status is 'active' or 'completed' (Since 3.1)
11648 "socket-address: array of SocketAddress" (optional)
11650 Only used for tcp, to know what the real port is (Since 4.0)
11651 Since: 0.14.0
11653 query-migrate (Command) Returns information about current migration
11655 process. If migration is active there will be another json-object with
11656 RAM migration status and if block migration is active another one with
11657 block migration status.
11658 Returns: "MigrationInfo"
11660 Since: 0.14.0
11662 Example:
11664 1. Before the first migration
11666 -> { "execute": "query-migrate" }
11668 <- { "return": {} }
11669 2. Migration is done and has succeeded
11671 -> { "execute": "query-migrate" }
11673 <- { "return": {
11674 "status": "completed",
11675 "total-time":12345,
11676 "setup-time":12345,
11677 "downtime":12345,
11678 "ram":{
11679 "transferred":123,
11680 "remaining":123,
11681 "total":246,
11682 "duplicate":123,
11683 "normal":123,
11684 "normal-bytes":123456,
11685 "dirty-sync-count":15
11686 }
11687 }
11688 }
11689 3. Migration is done and has failed
11691 -> { "execute": "query-migrate" }
11693 <- { "return": { "status": "failed" } }
11694 4. Migration is being performed and is not a block migration:
11696 -> { "execute": "query-migrate" }
11698 <- {
11699 "return":{
11700 "status":"active",
11701 "total-time":12345,
11702 "setup-time":12345,
11703 "expected-downtime":12345,
11704 "ram":{
11705 "transferred":123,
11706 "remaining":123,
11707 "total":246,
11708 "duplicate":123,
11709 "normal":123,
11710 "normal-bytes":123456,
11711 "dirty-sync-count":15
11712 }
11713 }
11714 }
11715 5. Migration is being performed and is a block migration:
11717 -> { "execute": "query-migrate" }
11719 <- {
11720 "return":{
11721 "status":"active",
11722 "total-time":12345,
11723 "setup-time":12345,
11724 "expected-downtime":12345,
11725 "ram":{
11726 "total":1057024,
11727 "remaining":1053304,
11728 "transferred":3720,
11729 "duplicate":123,
11730 "normal":123,
11731 "normal-bytes":123456,
11732 "dirty-sync-count":15
11733 },
11734 "disk":{
11735 "total":20971520,
11736 "remaining":20880384,
11737 "transferred":91136
11738 }
11739 }
11740 }
11741 6. Migration is being performed and XBZRLE is active:
11743 -> { "execute": "query-migrate" }
11745 <- {
11746 "return":{
11747 "status":"active",
11748 "total-time":12345,
11749 "setup-time":12345,
11750 "expected-downtime":12345,
11751 "ram":{
11752 "total":1057024,
11753 "remaining":1053304,
11754 "transferred":3720,
11755 "duplicate":10,
11756 "normal":3333,
11757 "normal-bytes":3412992,
11758 "dirty-sync-count":15
11759 },
11760 "xbzrle-cache":{
11761 "cache-size":67108864,
11762 "bytes":20971520,
11763 "pages":2444343,
11764 "cache-miss":2244,
11765 "cache-miss-rate":0.123,
11766 "encoding-rate":80.1,
11767 "overflow":34434
11768 }
11769 }
11770 }
11771 MigrationCapability (Enum)
11773 Migration capabilities enumeration
11775 Values:
11777 "xbzrle"
11779 Migration supports xbzrle (Xor Based Zero Run Length Encoding).
11780 This feature allows us to minimize migration traffic for certain
11781 work loads, by sending compressed difference of the pages
11782 "rdma-pin-all"
11784 Controls whether or not the entire VM memory footprint is mlock()'d
11785 on demand or all at once. Refer to docs/rdma.txt for usage.
11786 Disabled by default. (since 2.0)
11787 "zero-blocks"
11789 During storage migration encode blocks of zeroes efficiently. This
11790 essentially saves 1MB of zeroes per block on the wire. Enabling
11791 requires source and target VM to support this feature. To enable it
11792 is sufficient to enable the capability on the source VM. The
11793 feature is disabled by default. (since 1.6)
11794 "compress"
11796 Use multiple compression threads to accelerate live migration.
11797 This feature can help to reduce the migration traffic, by sending
11798 compressed pages. Please note that if compress and xbzrle are both
11799 on, compress only takes effect in the ram bulk stage, after that,
11800 it will be disabled and only xbzrle takes effect, this can help to
11801 minimize migration traffic. The feature is disabled by default.
11802 (since 2.4 )
11803 "events"
11805 generate events for each migration state change (since 2.4 )
11806 "auto-converge"
11808 If enabled, QEMU will automatically throttle down the guest to
11809 speed up convergence of RAM migration. (since 1.6)
11810 "postcopy-ram"
11812 Start executing on the migration target before all of RAM has been
11813 migrated, pulling the remaining pages along as needed. The capacity
11814 must have the same setting on both source and target or migration
11815 will not even start. NOTE: If the migration fails during postcopy
11816 the VM will fail. (since 2.6)
11817 "x-colo"
11819 If enabled, migration will never end, and the state of the VM on
11820 the primary side will be migrated continuously to the VM on
11821 secondary side, this process is called COarse-Grain LOck Stepping
11822 (COLO) for Non-stop Service. (since 2.8)
11823 "release-ram"
11825 if enabled, qemu will free the migrated ram pages on the source
11826 during postcopy-ram migration. (since 2.9)
11827 "block"
11829 If enabled, QEMU will also migrate the contents of all block
11830 devices. Default is disabled. A possible alternative uses mirror
11831 jobs to a builtin NBD server on the destination, which offers more
11832 flexibility. (Since 2.10)
11833 "return-path"
11835 If enabled, migration will use the return path even for precopy.
11836 (since 2.10)
11837 "pause-before-switchover"
11839 Pause outgoing migration before serialising device state and before
11840 disabling block IO (since 2.11)
11841 "multifd"
11843 Use more than one fd for migration (since 4.0)
11844 "dirty-bitmaps"
11846 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
11847 "postcopy-blocktime"
11849 Calculate downtime for postcopy live migration (since 3.0)
11850 "late-block-activate"
11852 If enabled, the destination will not activate block devices (and
11853 thus take locks) immediately at the end of migration. (since 3.0)
11854 "x-ignore-shared"
11856 If enabled, QEMU will not migrate shared memory (since 4.0)
11857 "validate-uuid"
11859 Send the UUID of the source to allow the destination to ensure it
11860 is the same. (since 4.2)
11861 Since: 1.2
11863 MigrationCapabilityStatus (Object)
11865 Migration capability information
11867 Members:
11869 "capability: MigrationCapability"
11871 capability enum
11872 "state: boolean"
11874 capability state bool
11875 Since: 1.2
11877 migrate-set-capabilities (Command) Enable/Disable the following
11879 migration capabilities (like xbzrle)
11880 Arguments:
11882 "capabilities: array of MigrationCapabilityStatus"
11884 json array of capability modifications to make
11885 Since: 1.2
11887 Example:
11889 -> { "execute": "migrate-set-capabilities" , "arguments":
11891 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
11892 query-migrate-capabilities (Command) Returns information about the
11894 current migration capabilities status
11895 Returns: "MigrationCapabilitiesStatus"
11897 Since: 1.2
11899 Example:
11901 -> { "execute": "query-migrate-capabilities" }
11903 <- { "return": [
11904 {"state": false, "capability": "xbzrle"},
11905 {"state": false, "capability": "rdma-pin-all"},
11906 {"state": false, "capability": "auto-converge"},
11907 {"state": false, "capability": "zero-blocks"},
11908 {"state": false, "capability": "compress"},
11909 {"state": true, "capability": "events"},
11910 {"state": false, "capability": "postcopy-ram"},
11911 {"state": false, "capability": "x-colo"}
11912 ]}
11913 MultiFDCompression (Enum)
11915 An enumeration of multifd compression methods.
11917 Values:
11919 "none"
11921 no compression.
11922 "zlib"
11924 use zlib compression method.
11925 "zstd"
11927 use zstd compression method. If: "defined(CONFIG_ZSTD)"
11928 Since: 5.0
11930 MigrationParameter (Enum)
11932 Migration parameters enumeration
11934 Values:
11936 "announce-initial"
11938 Initial delay (in milliseconds) before sending the first announce
11939 (Since 4.0)
11940 "announce-max"
11942 Maximum delay (in milliseconds) between packets in the announcement
11943 (Since 4.0)
11944 "announce-rounds"
11946 Number of self-announce packets sent after migration (Since 4.0)
11947 "announce-step"
11949 Increase in delay (in milliseconds) between subsequent packets in
11950 the announcement (Since 4.0)
11951 "compress-level"
11953 Set the compression level to be used in live migration, the
11954 compression level is an integer between 0 and 9, where 0 means no
11955 compression, 1 means the best compression speed, and 9 means best
11956 compression ratio which will consume more CPU.
11957 "compress-threads"
11959 Set compression thread count to be used in live migration, the
11960 compression thread count is an integer between 1 and 255.
11961 "compress-wait-thread"
11963 Controls behavior when all compression threads are currently busy.
11964 If true (default), wait for a free compression thread to become
11965 available; otherwise, send the page uncompressed. (Since 3.1)
11966 "decompress-threads"
11968 Set decompression thread count to be used in live migration, the
11969 decompression thread count is an integer between 1 and 255.
11970 Usually, decompression is at least 4 times as fast as compression,
11971 so set the decompress-threads to the number about 1/4 of compress-
11972 threads is adequate.
11973 "throttle-trigger-threshold"
11975 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
11976 throttling. It is expressed as percentage. The default value is
11977 50. (Since 5.0)
11978 "cpu-throttle-initial"
11980 Initial percentage of time guest cpus are throttled when migration
11981 auto-converge is activated. The default value is 20. (Since 2.7)
11982 "cpu-throttle-increment"
11984 throttle percentage increase each time auto-converge detects that
11985 migration is not making progress. The default value is 10. (Since
11986 2.7)
11987 "cpu-throttle-tailslow"
11989 Make CPU throttling slower at tail stage At the tail stage of
11990 throttling, the Guest is very sensitive to CPU percentage while the
11991 "cpu-throttle" -increment is excessive usually at tail stage. If
11992 this parameter is true, we will compute the ideal CPU percentage
11993 used by the Guest, which may exactly make the dirty rate match the
11994 dirty rate threshold. Then we will choose a smaller throttle
11995 increment between the one specified by "cpu-throttle-increment" and
11996 the one generated by ideal CPU percentage. Therefore, it is
11997 compatible to traditional throttling, meanwhile the throttle
11998 increment won't be excessive at tail stage. The default value is
11999 false. (Since 5.1)
12000 "tls-creds"
12002 ID of the 'tls-creds' object that provides credentials for
12003 establishing a TLS connection over the migration data channel. On
12004 the outgoing side of the migration, the credentials must be for a
12005 'client' endpoint, while for the incoming side the credentials must
12006 be for a 'server' endpoint. Setting this will enable TLS for all
12007 migrations. The default is unset, resulting in unsecured migration
12008 at the QEMU level. (Since 2.7)
12009 "tls-hostname"
12011 hostname of the target host for the migration. This is required
12012 when using x509 based TLS credentials and the migration URI does
12013 not already include a hostname. For example if using fd: or exec:
12014 based migration, the hostname must be provided so that the server's
12015 x509 certificate identity can be validated. (Since 2.7)
12016 "tls-authz"
12018 ID of the 'authz' object subclass that provides access control
12019 checking of the TLS x509 certificate distinguished name. This
12020 object is only resolved at time of use, so can be deleted and
12021 recreated on the fly while the migration server is active. If
12022 missing, it will default to denying access (Since 4.0)
12023 "max-bandwidth"
12025 to set maximum speed for migration. maximum speed in bytes per
12026 second. (Since 2.8)
12027 "downtime-limit"
12029 set maximum tolerated downtime for migration. maximum downtime in
12030 milliseconds (Since 2.8)
12031 "x-checkpoint-delay"
12033 The delay time (in ms) between two COLO checkpoints in periodic
12034 mode. (Since 2.8)
12035 "block-incremental"
12037 Affects how much storage is migrated when the block migration
12038 capability is enabled. When false, the entire storage backing
12039 chain is migrated into a flattened image at the destination; when
12040 true, only the active qcow2 layer is migrated and the destination
12041 must already have access to the same backing chain as was used on
12042 the source. (since 2.10)
12043 "multifd-channels"
12045 Number of channels used to migrate data in parallel. This is the
12046 same number that the number of sockets used for migration. The
12047 default value is 2 (since 4.0)
12048 "xbzrle-cache-size"
12050 cache size to be used by XBZRLE migration. It needs to be a
12051 multiple of the target page size and a power of 2 (Since 2.11)
12052 "max-postcopy-bandwidth"
12054 Background transfer bandwidth during postcopy. Defaults to 0
12055 (unlimited). In bytes per second. (Since 3.0)
12056 "max-cpu-throttle"
12058 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
12059 "multifd-compression"
12061 Which compression method to use. Defaults to none. (Since 5.0)
12062 "multifd-zlib-level"
12064 Set the compression level to be used in live migration, the
12065 compression level is an integer between 0 and 9, where 0 means no
12066 compression, 1 means the best compression speed, and 9 means best
12067 compression ratio which will consume more CPU. Defaults to 1.
12068 (Since 5.0)
12069 "multifd-zstd-level"
12071 Set the compression level to be used in live migration, the
12072 compression level is an integer between 0 and 20, where 0 means no
12073 compression, 1 means the best compression speed, and 20 means best
12074 compression ratio which will consume more CPU. Defaults to 1.
12075 (Since 5.0)
12076 Since: 2.4
12078 MigrateSetParameters (Object)
12080 Members:
12082 "announce-initial: int" (optional)
12084 Initial delay (in milliseconds) before sending the first announce
12085 (Since 4.0)
12086 "announce-max: int" (optional)
12088 Maximum delay (in milliseconds) between packets in the announcement
12089 (Since 4.0)
12090 "announce-rounds: int" (optional)
12092 Number of self-announce packets sent after migration (Since 4.0)
12093 "announce-step: int" (optional)
12095 Increase in delay (in milliseconds) between subsequent packets in
12096 the announcement (Since 4.0)
12097 "compress-level: int" (optional)
12099 compression level
12100 "compress-threads: int" (optional)
12102 compression thread count
12103 "compress-wait-thread: boolean" (optional)
12105 Controls behavior when all compression threads are currently busy.
12106 If true (default), wait for a free compression thread to become
12107 available; otherwise, send the page uncompressed. (Since 3.1)
12108 "decompress-threads: int" (optional)
12110 decompression thread count
12111 "throttle-trigger-threshold: int" (optional)
12113 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
12114 throttling. It is expressed as percentage. The default value is
12115 50. (Since 5.0)
12116 "cpu-throttle-initial: int" (optional)
12118 Initial percentage of time guest cpus are throttled when migration
12119 auto-converge is activated. The default value is 20. (Since 2.7)
12120 "cpu-throttle-increment: int" (optional)
12122 throttle percentage increase each time auto-converge detects that
12123 migration is not making progress. The default value is 10. (Since
12124 2.7)
12125 "cpu-throttle-tailslow: boolean" (optional)
12127 Make CPU throttling slower at tail stage At the tail stage of
12128 throttling, the Guest is very sensitive to CPU percentage while the
12129 "cpu-throttle" -increment is excessive usually at tail stage. If
12130 this parameter is true, we will compute the ideal CPU percentage
12131 used by the Guest, which may exactly make the dirty rate match the
12132 dirty rate threshold. Then we will choose a smaller throttle
12133 increment between the one specified by "cpu-throttle-increment" and
12134 the one generated by ideal CPU percentage. Therefore, it is
12135 compatible to traditional throttling, meanwhile the throttle
12136 increment won't be excessive at tail stage. The default value is
12137 false. (Since 5.1)
12138 "tls-creds: StrOrNull" (optional)
12140 ID of the 'tls-creds' object that provides credentials for
12141 establishing a TLS connection over the migration data channel. On
12142 the outgoing side of the migration, the credentials must be for a
12143 'client' endpoint, while for the incoming side the credentials must
12144 be for a 'server' endpoint. Setting this to a non-empty string
12145 enables TLS for all migrations. An empty string means that QEMU
12146 will use plain text mode for migration, rather than TLS (Since 2.9)
12147 Previously (since 2.7), this was reported by omitting tls-creds
12148 instead.
12149 "tls-hostname: StrOrNull" (optional)
12151 hostname of the target host for the migration. This is required
12152 when using x509 based TLS credentials and the migration URI does
12153 not already include a hostname. For example if using fd: or exec:
12154 based migration, the hostname must be provided so that the server's
12155 x509 certificate identity can be validated. (Since 2.7) An empty
12156 string means that QEMU will use the hostname associated with the
12157 migration URI, if any. (Since 2.9) Previously (since 2.7), this was
12158 reported by omitting tls-hostname instead.
12159 "max-bandwidth: int" (optional)
12161 to set maximum speed for migration. maximum speed in bytes per
12162 second. (Since 2.8)
12163 "downtime-limit: int" (optional)
12165 set maximum tolerated downtime for migration. maximum downtime in
12166 milliseconds (Since 2.8)
12167 "x-checkpoint-delay: int" (optional)
12169 the delay time between two COLO checkpoints. (Since 2.8)
12170 "block-incremental: boolean" (optional)
12172 Affects how much storage is migrated when the block migration
12173 capability is enabled. When false, the entire storage backing
12174 chain is migrated into a flattened image at the destination; when
12175 true, only the active qcow2 layer is migrated and the destination
12176 must already have access to the same backing chain as was used on
12177 the source. (since 2.10)
12178 "multifd-channels: int" (optional)
12180 Number of channels used to migrate data in parallel. This is the
12181 same number that the number of sockets used for migration. The
12182 default value is 2 (since 4.0)
12183 "xbzrle-cache-size: int" (optional)
12185 cache size to be used by XBZRLE migration. It needs to be a
12186 multiple of the target page size and a power of 2 (Since 2.11)
12187 "max-postcopy-bandwidth: int" (optional)
12189 Background transfer bandwidth during postcopy. Defaults to 0
12190 (unlimited). In bytes per second. (Since 3.0)
12191 "max-cpu-throttle: int" (optional)
12193 maximum cpu throttle percentage. The default value is 99. (Since
12194 3.1)
12195 "multifd-compression: MultiFDCompression" (optional)
12197 Which compression method to use. Defaults to none. (Since 5.0)
12198 "multifd-zlib-level: int" (optional)
12200 Set the compression level to be used in live migration, the
12201 compression level is an integer between 0 and 9, where 0 means no
12202 compression, 1 means the best compression speed, and 9 means best
12203 compression ratio which will consume more CPU. Defaults to 1.
12204 (Since 5.0)
12205 "multifd-zstd-level: int" (optional)
12207 Set the compression level to be used in live migration, the
12208 compression level is an integer between 0 and 20, where 0 means no
12209 compression, 1 means the best compression speed, and 20 means best
12210 compression ratio which will consume more CPU. Defaults to 1.
12211 (Since 5.0)
12212 "tls-authz: StrOrNull" (optional)
12214 Not documented
12215 Since: 2.4
12217 migrate-set-parameters (Command) Set various migration parameters.
12219 Arguments: the members of "MigrateSetParameters"
12221 Since: 2.4
12223 Example:
12225 -> { "execute": "migrate-set-parameters" ,
12227 "arguments": { "compress-level": 1 } }
12228 MigrationParameters (Object)
12230 The optional members aren't actually optional.
12232 Members:
12234 "announce-initial: int" (optional)
12236 Initial delay (in milliseconds) before sending the first announce
12237 (Since 4.0)
12238 "announce-max: int" (optional)
12240 Maximum delay (in milliseconds) between packets in the announcement
12241 (Since 4.0)
12242 "announce-rounds: int" (optional)
12244 Number of self-announce packets sent after migration (Since 4.0)
12245 "announce-step: int" (optional)
12247 Increase in delay (in milliseconds) between subsequent packets in
12248 the announcement (Since 4.0)
12249 "compress-level: int" (optional)
12251 compression level
12252 "compress-threads: int" (optional)
12254 compression thread count
12255 "compress-wait-thread: boolean" (optional)
12257 Controls behavior when all compression threads are currently busy.
12258 If true (default), wait for a free compression thread to become
12259 available; otherwise, send the page uncompressed. (Since 3.1)
12260 "decompress-threads: int" (optional)
12262 decompression thread count
12263 "throttle-trigger-threshold: int" (optional)
12265 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
12266 throttling. It is expressed as percentage. The default value is
12267 50. (Since 5.0)
12268 "cpu-throttle-initial: int" (optional)
12270 Initial percentage of time guest cpus are throttled when migration
12271 auto-converge is activated. (Since 2.7)
12272 "cpu-throttle-increment: int" (optional)
12274 throttle percentage increase each time auto-converge detects that
12275 migration is not making progress. (Since 2.7)
12276 "cpu-throttle-tailslow: boolean" (optional)
12278 Make CPU throttling slower at tail stage At the tail stage of
12279 throttling, the Guest is very sensitive to CPU percentage while the
12280 "cpu-throttle" -increment is excessive usually at tail stage. If
12281 this parameter is true, we will compute the ideal CPU percentage
12282 used by the Guest, which may exactly make the dirty rate match the
12283 dirty rate threshold. Then we will choose a smaller throttle
12284 increment between the one specified by "cpu-throttle-increment" and
12285 the one generated by ideal CPU percentage. Therefore, it is
12286 compatible to traditional throttling, meanwhile the throttle
12287 increment won't be excessive at tail stage. The default value is
12288 false. (Since 5.1)
12289 "tls-creds: string" (optional)
12291 ID of the 'tls-creds' object that provides credentials for
12292 establishing a TLS connection over the migration data channel. On
12293 the outgoing side of the migration, the credentials must be for a
12294 'client' endpoint, while for the incoming side the credentials must
12295 be for a 'server' endpoint. An empty string means that QEMU will
12296 use plain text mode for migration, rather than TLS (Since 2.7)
12297 Note: 2.8 reports this by omitting tls-creds instead.
12298 "tls-hostname: string" (optional)
12300 hostname of the target host for the migration. This is required
12301 when using x509 based TLS credentials and the migration URI does
12302 not already include a hostname. For example if using fd: or exec:
12303 based migration, the hostname must be provided so that the server's
12304 x509 certificate identity can be validated. (Since 2.7) An empty
12305 string means that QEMU will use the hostname associated with the
12306 migration URI, if any. (Since 2.9) Note: 2.8 reports this by
12307 omitting tls-hostname instead.
12308 "tls-authz: string" (optional)
12310 ID of the 'authz' object subclass that provides access control
12311 checking of the TLS x509 certificate distinguished name. (Since
12312 4.0)
12313 "max-bandwidth: int" (optional)
12315 to set maximum speed for migration. maximum speed in bytes per
12316 second. (Since 2.8)
12317 "downtime-limit: int" (optional)
12319 set maximum tolerated downtime for migration. maximum downtime in
12320 milliseconds (Since 2.8)
12321 "x-checkpoint-delay: int" (optional)
12323 the delay time between two COLO checkpoints. (Since 2.8)
12324 "block-incremental: boolean" (optional)
12326 Affects how much storage is migrated when the block migration
12327 capability is enabled. When false, the entire storage backing
12328 chain is migrated into a flattened image at the destination; when
12329 true, only the active qcow2 layer is migrated and the destination
12330 must already have access to the same backing chain as was used on
12331 the source. (since 2.10)
12332 "multifd-channels: int" (optional)
12334 Number of channels used to migrate data in parallel. This is the
12335 same number that the number of sockets used for migration. The
12336 default value is 2 (since 4.0)
12337 "xbzrle-cache-size: int" (optional)
12339 cache size to be used by XBZRLE migration. It needs to be a
12340 multiple of the target page size and a power of 2 (Since 2.11)
12341 "max-postcopy-bandwidth: int" (optional)
12343 Background transfer bandwidth during postcopy. Defaults to 0
12344 (unlimited). In bytes per second. (Since 3.0)
12345 "max-cpu-throttle: int" (optional)
12347 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
12348 "multifd-compression: MultiFDCompression" (optional)
12350 Which compression method to use. Defaults to none. (Since 5.0)
12351 "multifd-zlib-level: int" (optional)
12353 Set the compression level to be used in live migration, the
12354 compression level is an integer between 0 and 9, where 0 means no
12355 compression, 1 means the best compression speed, and 9 means best
12356 compression ratio which will consume more CPU. Defaults to 1.
12357 (Since 5.0)
12358 "multifd-zstd-level: int" (optional)
12360 Set the compression level to be used in live migration, the
12361 compression level is an integer between 0 and 20, where 0 means no
12362 compression, 1 means the best compression speed, and 20 means best
12363 compression ratio which will consume more CPU. Defaults to 1.
12364 (Since 5.0)
12365 Since: 2.4
12367 query-migrate-parameters (Command) Returns information about the
12369 current migration parameters
12370 Returns: "MigrationParameters"
12372 Since: 2.4
12374 Example:
12376 -> { "execute": "query-migrate-parameters" }
12378 <- { "return": {
12379 "decompress-threads": 2,
12380 "cpu-throttle-increment": 10,
12381 "compress-threads": 8,
12382 "compress-level": 1,
12383 "cpu-throttle-initial": 20,
12384 "max-bandwidth": 33554432,
12385 "downtime-limit": 300
12386 }
12387 }
12388 client_migrate_info (Command) Set migration information for remote
12390 display. This makes the server ask the client to automatically
12391 reconnect using the new parameters once migration finished
12392 successfully. Only implemented for SPICE.
12393 Arguments:
12395 "protocol: string"
12397 must be "spice"
12398 "hostname: string"
12400 migration target hostname
12401 "port: int" (optional)
12403 spice tcp port for plaintext channels
12404 "tls-port: int" (optional)
12406 spice tcp port for tls-secured channels
12407 "cert-subject: string" (optional)
12409 server certificate subject
12410 Since: 0.14.0
12412 Example:
12414 -> { "execute": "client_migrate_info",
12416 "arguments": { "protocol": "spice",
12417 "hostname": "virt42.lab.kraxel.org",
12418 "port": 1234 } }
12419 <- { "return": {} }
12420 migrate-start-postcopy (Command) Followup to a migration command to
12422 switch the migration to postcopy mode. The postcopy-ram capability
12423 must be set on both source and destination before the original
12424 migration command.
12425 Since: 2.5
12427 Example:
12429 -> { "execute": "migrate-start-postcopy" }
12431 <- { "return": {} }
12432 MIGRATION (Event) Emitted when a migration event happens
12434 Arguments:
12436 "status: MigrationStatus"
12438 "MigrationStatus" describing the current migration status.
12439 Since: 2.4
12441 Example:
12443 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
12445 "event": "MIGRATION",
12446 "data": {"status": "completed"} }
12447 MIGRATION_PASS (Event) Emitted from the source side of a migration at
12449 the start of each pass (when it syncs the dirty bitmap)
12450 Arguments:
12452 "pass: int"
12454 An incrementing count (starting at 1 on the first pass)
12455 Since: 2.6
12457 Example:
12459 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
12461 "event": "MIGRATION_PASS", "data": {"pass": 2} }
12462 COLOMessage (Enum)
12464 The message transmission between Primary side and Secondary side.
12466 Values:
12468 "checkpoint-ready"
12470 Secondary VM (SVM) is ready for checkpointing
12471 "checkpoint-request"
12473 Primary VM (PVM) tells SVM to prepare for checkpointing
12474 "checkpoint-reply"
12476 SVM gets PVM's checkpoint request
12477 "vmstate-send"
12479 VM's state will be sent by PVM.
12480 "vmstate-size"
12482 The total size of VMstate.
12483 "vmstate-received"
12485 VM's state has been received by SVM.
12486 "vmstate-loaded"
12488 VM's state has been loaded by SVM.
12489 Since: 2.8
12491 COLOMode (Enum)
12493 The COLO current mode.
12495 Values:
12497 "none"
12499 COLO is disabled.
12500 "primary"
12502 COLO node in primary side.
12503 "secondary"
12505 COLO node in slave side.
12506 Since: 2.8
12508 FailoverStatus (Enum)
12510 An enumeration of COLO failover status
12512 Values:
12514 "none"
12516 no failover has ever happened
12517 "require"
12519 got failover requirement but not handled
12520 "active"
12522 in the process of doing failover
12523 "completed"
12525 finish the process of failover
12526 "relaunch"
12528 restart the failover process, from 'none' -> 'completed' (Since
12529 2.9)
12530 Since: 2.8
12532 COLO_EXIT (Event) Emitted when VM finishes COLO mode due to some
12534 errors happening or at the request of users.
12535 Arguments:
12537 "mode: COLOMode"
12539 report COLO mode when COLO exited.
12540 "reason: COLOExitReason"
12542 describes the reason for the COLO exit.
12543 Since: 3.1
12545 Example:
12547 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
12549 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
12550 COLOExitReason (Enum)
12552 The reason for a COLO exit.
12554 Values:
12556 "none"
12558 failover has never happened. This state does not occur in the
12559 COLO_EXIT event, and is only visible in the result of query-colo-
12560 status.
12561 "request"
12563 COLO exit is due to an external request.
12564 "error"
12566 COLO exit is due to an internal error.
12567 "processing"
12569 COLO is currently handling a failover (since 4.0).
12570 Since: 3.1
12572 x-colo-lost-heartbeat (Command) Tell qemu that heartbeat is lost,
12574 request it to do takeover procedures. If this command is sent to the
12575 PVM, the Primary side will exit COLO mode. If sent to the Secondary,
12576 the Secondary side will run failover work, then takes over server
12577 operation to become the service VM.
12578 Since: 2.8
12580 Example:
12582 -> { "execute": "x-colo-lost-heartbeat" }
12584 <- { "return": {} }
12585 migrate_cancel (Command) Cancel the current executing migration
12587 process.
12588 Returns: nothing on success
12590 Notes: This command succeeds even if there is no migration process
12592 running.
12593 Since: 0.14.0
12595 Example:
12597 -> { "execute": "migrate_cancel" }
12599 <- { "return": {} }
12600 migrate-continue (Command) Continue migration when it's in a paused
12602 state.
12603 Arguments:
12605 "state: MigrationStatus"
12607 The state the migration is currently expected to be in
12608 Returns: nothing on success
12610 Since: 2.11
12612 Example:
12614 -> { "execute": "migrate-continue" , "arguments":
12616 { "state": "pre-switchover" } }
12617 <- { "return": {} }
12618 migrate_set_downtime (Command) Set maximum tolerated downtime for
12620 migration.
12621 Arguments:
12623 "value: number"
12625 maximum downtime in seconds
12626 Features:
12628 "deprecated"
12630 This command is deprecated. Use 'migrate-set-parameters' instead.
12631 Returns: nothing on success
12633 Since: 0.14.0
12635 Example:
12637 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
12639 <- { "return": {} }
12640 migrate_set_speed (Command) Set maximum speed for migration.
12642 Arguments:
12644 "value: int"
12646 maximum speed in bytes per second.
12647 Features:
12649 "deprecated"
12651 This command is deprecated. Use 'migrate-set-parameters' instead.
12652 Returns: nothing on success
12654 Since: 0.14.0
12656 Example:
12658 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
12660 <- { "return": {} }
12661 migrate-set-cache-size (Command) Set cache size to be used by XBZRLE
12663 migration
12664 Arguments:
12666 "value: int"
12668 cache size in bytes
12669 Features:
12671 "deprecated"
12673 This command is deprecated. Use 'migrate-set-parameters' instead.
12674 The size will be rounded down to the nearest power of 2. The cache
12676 size can be modified before and during ongoing migration
12677 Returns: nothing on success
12679 Since: 1.2
12681 Example:
12683 -> { "execute": "migrate-set-cache-size",
12685 "arguments": { "value": 536870912 } }
12686 <- { "return": {} }
12687 query-migrate-cache-size (Command) Query migration XBZRLE cache size
12689 Features:
12691 "deprecated"
12693 This command is deprecated. Use 'query-migrate-parameters'
12694 instead.
12695 Returns: XBZRLE cache size in bytes
12697 Since: 1.2
12699 Example:
12701 -> { "execute": "query-migrate-cache-size" }
12703 <- { "return": 67108864 }
12704 migrate (Command) Migrates the current running guest to another
12706 Virtual Machine.
12707 Arguments:
12709 "uri: string"
12711 the Uniform Resource Identifier of the destination VM
12712 "blk: boolean" (optional)
12714 do block migration (full disk copy)
12715 "inc: boolean" (optional)
12717 incremental disk copy migration
12718 "detach: boolean" (optional)
12720 this argument exists only for compatibility reasons and is ignored
12721 by QEMU
12722 "resume: boolean" (optional)
12724 resume one paused migration, default "off". (since 3.0)
12725 Returns: nothing on success
12727 Since: 0.14.0
12729 Notes:
12731 1. The 'query-migrate' command should be used to check migration's
12733 progress and final result (this information is provided by the
12734 'status' member)
12735 2. All boolean arguments default to false
12737 3. The user Monitor's "detach" argument is invalid in QMP and should
12739 not be used
12740 Example:
12742 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
12744 <- { "return": {} }
12745 migrate-incoming (Command) Start an incoming migration, the qemu must
12747 have been started with -incoming defer
12748 Arguments:
12750 "uri: string"
12752 The Uniform Resource Identifier identifying the source or address
12753 to listen on
12754 Returns: nothing on success
12756 Since: 2.3
12758 Notes:
12760 1. It's a bad idea to use a string for the uri, but it needs to stay
12762 compatible with -incoming and the format of the uri is already
12763 exposed above libvirt.
12764 2. QEMU must be started with -incoming defer to allow migrate-incoming
12766 to be used.
12767 3. The uri format is the same as for -incoming
12769 Example:
12771 -> { "execute": "migrate-incoming",
12773 "arguments": { "uri": "tcp::4446" } }
12774 <- { "return": {} }
12775 xen-save-devices-state (Command) Save the state of all devices to
12777 file. The RAM and the block devices of the VM are not saved by this
12778 command.
12779 Arguments:
12781 "filename: string"
12783 the file to save the state of the devices to as binary data. See
12784 xen-save-devices-state.txt for a description of the binary format.
12785 "live: boolean" (optional)
12787 Optional argument to ask QEMU to treat this command as part of a
12788 live migration. Default to true. (since 2.11)
12789 Returns: Nothing on success
12791 Since: 1.1
12793 Example:
12795 -> { "execute": "xen-save-devices-state",
12797 "arguments": { "filename": "/tmp/save" } }
12798 <- { "return": {} }
12799 xen-set-replication (Command) Enable or disable replication.
12801 Arguments:
12803 "enable: boolean"
12805 true to enable, false to disable.
12806 "primary: boolean"
12808 true for primary or false for secondary.
12809 "failover: boolean" (optional)
12811 true to do failover, false to stop. but cannot be specified if
12812 'enable' is true. default value is false.
12813 Returns: nothing.
12815 Example:
12817 -> { "execute": "xen-set-replication",
12819 "arguments": {"enable": true, "primary": false} }
12820 <- { "return": {} }
12821 Since: 2.9
12823 If: "defined(CONFIG_REPLICATION)"
12825 ReplicationStatus (Object)
12827 The result format for 'query-xen-replication-status'.
12829 Members:
12831 "error: boolean"
12833 true if an error happened, false if replication is normal.
12834 "desc: string" (optional)
12836 the human readable error description string, when "error" is
12837 'true'.
12838 Since: 2.9
12840 If: "defined(CONFIG_REPLICATION)"
12842 query-xen-replication-status (Command) Query replication status while
12844 the vm is running.
12845 Returns: A "ReplicationResult" object showing the status.
12847 Example:
12849 -> { "execute": "query-xen-replication-status" }
12851 <- { "return": { "error": false } }
12852 Since: 2.9
12854 If: "defined(CONFIG_REPLICATION)"
12856 xen-colo-do-checkpoint (Command) Xen uses this command to notify
12858 replication to trigger a checkpoint.
12859 Returns: nothing.
12861 Example:
12863 -> { "execute": "xen-colo-do-checkpoint" }
12865 <- { "return": {} }
12866 Since: 2.9
12868 If: "defined(CONFIG_REPLICATION)"
12870 COLOStatus (Object)
12872 The result format for 'query-colo-status'.
12874 Members:
12876 "mode: COLOMode"
12878 COLO running mode. If COLO is running, this field will return
12879 'primary' or 'secondary'.
12880 "last-mode: COLOMode"
12882 COLO last running mode. If COLO is running, this field will return
12883 same like mode field, after failover we can use this field to get
12884 last colo mode. (since 4.0)
12885 "reason: COLOExitReason"
12887 describes the reason for the COLO exit.
12888 Since: 3.1
12890 query-colo-status (Command) Query COLO status while the vm is running.
12892 Returns: A "COLOStatus" object showing the status.
12894 Example:
12896 -> { "execute": "query-colo-status" }
12898 <- { "return": { "mode": "primary", "reason": "request" } }
12899 Since: 3.1
12901 migrate-recover (Command) Provide a recovery migration stream URI.
12903 Arguments:
12905 "uri: string"
12907 the URI to be used for the recovery of migration stream.
12908 Returns: nothing.
12910 Example:
12912 -> { "execute": "migrate-recover",
12914 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
12915 <- { "return": {} }
12916 Since: 3.0
12918 migrate-pause (Command) Pause a migration. Currently it only supports
12920 postcopy.
12921 Returns: nothing.
12923 Example:
12925 -> { "execute": "migrate-pause" }
12927 <- { "return": {} }
12928 Since: 3.0
12930 UNPLUG_PRIMARY (Event) Emitted from source side of a migration when
12932 migration state is WAIT_UNPLUG. Device was unplugged by guest operating
12933 system. Device resources in QEMU are kept on standby to be able to re-
12934 plug it in case of migration failure.
12935 Arguments:
12937 "device-id: string"
12939 QEMU device id of the unplugged device
12940 Since: 4.2
12942 Example:
12944 {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} }
12946 Transactions
12948 Abort (Object)
12949 This action can be used to test transaction failure.
12951 Since: 1.6
12953 ActionCompletionMode (Enum)
12955 An enumeration of Transactional completion modes.
12957 Values:
12959 "individual"
12961 Do not attempt to cancel any other Actions if any Actions fail
12962 after the Transaction request succeeds. All Actions that can
12963 complete successfully will do so without waiting on others. This
12964 is the default.
12965 "grouped"
12967 If any Action fails after the Transaction succeeds, cancel all
12968 Actions. Actions do not complete until all Actions are ready to
12969 complete. May be rejected by Actions that do not support this
12970 completion mode.
12971 Since: 2.5
12973 TransactionAction (Object)
12975 A discriminated record of operations that can be performed with
12977 "transaction". Action "type" can be:
12978 - "abort": since 1.6
12980 - "block-dirty-bitmap-add": since 2.5
12982 - "block-dirty-bitmap-remove": since 4.2
12984 - "block-dirty-bitmap-clear": since 2.5
12986 - "block-dirty-bitmap-enable": since 4.0
12988 - "block-dirty-bitmap-disable": since 4.0
12990 - "block-dirty-bitmap-merge": since 4.0
12992 - "blockdev-backup": since 2.3
12994 - "blockdev-snapshot": since 2.5
12996 - "blockdev-snapshot-internal-sync": since 1.7
12998 - "blockdev-snapshot-sync": since 1.1
13000 - "drive-backup": since 1.6
13002 Members:
13004 "type"
13006 One of "abort", "block-dirty-bitmap-add", "block-dirty-bitmap-
13007 remove", "block-dirty-bitmap-clear", "block-dirty-bitmap-enable",
13008 "block-dirty-bitmap-disable", "block-dirty-bitmap-merge",
13009 "blockdev-backup", "blockdev-snapshot", "blockdev-snapshot-
13010 internal-sync", "blockdev-snapshot-sync", "drive-backup"
13011 "data: Abort" when "type" is "abort"
13013 "data: BlockDirtyBitmapAdd" when "type" is "block-dirty-bitmap-add"
13014 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-remove"
13015 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-clear"
13016 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-enable"
13017 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-disable"
13018 "data: BlockDirtyBitmapMerge" when "type" is "block-dirty-bitmap-merge"
13019 "data: BlockdevBackup" when "type" is "blockdev-backup"
13020 "data: BlockdevSnapshot" when "type" is "blockdev-snapshot"
13021 "data: BlockdevSnapshotInternal" when "type" is "blockdev-snapshot-
13022 internal-sync"
13023 "data: BlockdevSnapshotSync" when "type" is "blockdev-snapshot-sync"
13024 "data: DriveBackup" when "type" is "drive-backup"
13025 Since: 1.1
13027 TransactionProperties (Object)
13029 Optional arguments to modify the behavior of a Transaction.
13031 Members:
13033 "completion-mode: ActionCompletionMode" (optional)
13035 Controls how jobs launched asynchronously by Actions will complete
13036 or fail as a group. See "ActionCompletionMode" for details.
13037 Since: 2.5
13039 transaction (Command) Executes a number of transactionable QMP
13041 commands atomically. If any operation fails, then the entire set of
13042 actions will be abandoned and the appropriate error returned.
13043 For external snapshots, the dictionary contains the device, the file to
13045 use for the new snapshot, and the format. The default format, if not
13046 specified, is qcow2.
13047 Each new snapshot defaults to being created by QEMU (wiping any
13049 contents if the file already exists), but it is also possible to reuse
13050 an externally-created file. In the latter case, you should ensure that
13051 the new image file has the same contents as the current one; QEMU
13052 cannot perform any meaningful check. Typically this is achieved by
13053 using the current image file as the backing file for the new image.
13054 On failure, the original disks pre-snapshot attempt will be used.
13056 For internal snapshots, the dictionary contains the device and the
13058 snapshot's name. If an internal snapshot matching name already exists,
13059 the request will be rejected. Only some image formats support it, for
13060 example, qcow2, rbd, and sheepdog.
13061 On failure, qemu will try delete the newly created internal snapshot in
13063 the transaction. When an I/O error occurs during deletion, the user
13064 needs to fix it later with qemu-img or other command.
13065 Arguments:
13067 "actions: array of TransactionAction"
13069 List of "TransactionAction"; information needed for the respective
13070 operations.
13071 "properties: TransactionProperties" (optional)
13073 structure of additional options to control the execution of the
13074 transaction. See "TransactionProperties" for additional detail.
13075 Returns: nothing on success
13077 Errors depend on the operations of the transaction
13079 Note: The transaction aborts on the first failure. Therefore, there
13081 will be information on only one failed operation returned in an error
13082 condition, and subsequent actions will not have been attempted.
13083 Since: 1.1
13085 Example:
13087 -> { "execute": "transaction",
13089 "arguments": { "actions": [
13090 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
13091 "snapshot-file": "/some/place/my-image",
13092 "format": "qcow2" } },
13093 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
13094 "snapshot-file": "/some/place/my-image2",
13095 "snapshot-node-name": "node3432",
13096 "mode": "existing",
13097 "format": "qcow2" } },
13098 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
13099 "snapshot-file": "/some/place/my-image2",
13100 "mode": "existing",
13101 "format": "qcow2" } },
13102 { "type": "blockdev-snapshot-internal-sync", "data" : {
13103 "device": "ide-hd2",
13104 "name": "snapshot0" } } ] } }
13105 <- { "return": {} }
13106 Tracing
13108 TraceEventState (Enum)
13109 State of a tracing event.
13111 Values:
13113 "unavailable"
13115 The event is statically disabled.
13116 "disabled"
13118 The event is dynamically disabled.
13119 "enabled"
13121 The event is dynamically enabled.
13122 Since: 2.2
13124 TraceEventInfo (Object)
13126 Information of a tracing event.
13128 Members:
13130 "name: string"
13132 Event name.
13133 "state: TraceEventState"
13135 Tracing state.
13136 "vcpu: boolean"
13138 Whether this is a per-vCPU event (since 2.7).
13139 An event is per-vCPU if it has the "vcpu" property in the "trace-
13141 events" files.
13142 Since: 2.2
13144 trace-event-get-state (Command) Query the state of events.
13146 Arguments:
13148 "name: string"
13150 Event name pattern (case-sensitive glob).
13151 "vcpu: int" (optional)
13153 The vCPU to query (any by default; since 2.7).
13154 Returns: a list of "TraceEventInfo" for the matching events
13156 An event is returned if:
13158 - its name matches the "name" pattern, and
13160 - if "vcpu" is given, the event has the "vcpu" property.
13162 Therefore, if "vcpu" is given, the operation will only match per-vCPU
13164 events, returning their state on the specified vCPU. Special case: if
13165 "name" is an exact match, "vcpu" is given and the event does not have
13166 the "vcpu" property, an error is returned.
13167 Since: 2.2
13169 Example:
13171 -> { "execute": "trace-event-get-state",
13173 "arguments": { "name": "qemu_memalign" } }
13174 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
13175 trace-event-set-state (Command) Set the dynamic tracing state of
13177 events.
13178 Arguments:
13180 "name: string"
13182 Event name pattern (case-sensitive glob).
13183 "enable: boolean"
13185 Whether to enable tracing.
13186 "ignore-unavailable: boolean" (optional)
13188 Do not match unavailable events with "name".
13189 "vcpu: int" (optional)
13191 The vCPU to act upon (all by default; since 2.7).
13192 An event's state is modified if:
13194 - its name matches the "name" pattern, and
13196 - if "vcpu" is given, the event has the "vcpu" property.
13198 Therefore, if "vcpu" is given, the operation will only match per-vCPU
13200 events, setting their state on the specified vCPU. Special case: if
13201 "name" is an exact match, "vcpu" is given and the event does not have
13202 the "vcpu" property, an error is returned.
13203 Since: 2.2
13205 Example:
13207 -> { "execute": "trace-event-set-state",
13209 "arguments": { "name": "qemu_memalign", "enable": "true" } }
13210 <- { "return": {} }
13211 QMP monitor control
13213 qmp_capabilities (Command) Enable QMP capabilities.
13214 Arguments:
13216 Arguments:
13218 "enable: array of QMPCapability" (optional)
13220 An optional list of QMPCapability values to enable. The client
13221 must not enable any capability that is not mentioned in the QMP
13222 greeting message. If the field is not provided, it means no QMP
13223 capabilities will be enabled. (since 2.12)
13224 Example:
13226 -> { "execute": "qmp_capabilities",
13228 "arguments": { "enable": [ "oob" ] } }
13229 <- { "return": {} }
13230 Notes: This command is valid exactly when first connecting: it must be
13232 issued before any other command will be accepted, and will fail once
13233 the monitor is accepting other commands. (see qemu
13234 docs/interop/qmp-spec.txt)
13235 The QMP client needs to explicitly enable QMP capabilities, otherwise
13237 all the QMP capabilities will be turned off by default.
13238 Since: 0.13
13240 QMPCapability (Enum)
13242 Enumeration of capabilities to be advertised during initial client
13244 connection, used for agreeing on particular QMP extension behaviors.
13245 Values:
13247 "oob"
13249 QMP ability to support out-of-band requests. (Please refer to
13250 qmp-spec.txt for more information on OOB)
13251 Since: 2.12
13253 VersionTriple (Object)
13255 A three-part version number.
13257 Members:
13259 "major: int"
13261 The major version number.
13262 "minor: int"
13264 The minor version number.
13265 "micro: int"
13267 The micro version number.
13268 Since: 2.4
13270 VersionInfo (Object)
13272 A description of QEMU's version.
13274 Members:
13276 "qemu: VersionTriple"
13278 The version of QEMU. By current convention, a micro version of 50
13279 signifies a development branch. A micro version greater than or
13280 equal to 90 signifies a release candidate for the next minor
13281 version. A micro version of less than 50 signifies a stable
13282 release.
13283 "package: string"
13285 QEMU will always set this field to an empty string. Downstream
13286 versions of QEMU should set this to a non-empty string. The exact
13287 format depends on the downstream however it highly recommended that
13288 a unique name is used.
13289 Since: 0.14.0
13291 query-version (Command) Returns the current version of QEMU.
13293 Returns: A "VersionInfo" object describing the current version of QEMU.
13295 Since: 0.14.0
13297 Example:
13299 -> { "execute": "query-version" }
13301 <- {
13302 "return":{
13303 "qemu":{
13304 "major":0,
13305 "minor":11,
13306 "micro":5
13307 },
13308 "package":""
13309 }
13310 }
13311 CommandInfo (Object)
13313 Information about a QMP command
13315 Members:
13317 "name: string"
13319 The command name
13320 Since: 0.14.0
13322 query-commands (Command) Return a list of supported QMP commands by
13324 this server
13325 Returns: A list of "CommandInfo" for all supported commands
13327 Since: 0.14.0
13329 Example:
13331 -> { "execute": "query-commands" }
13333 <- {
13334 "return":[
13335 {
13336 "name":"query-balloon"
13337 },
13338 {
13339 "name":"system_powerdown"
13340 }
13341 ]
13342 }
13343 Note: This example has been shortened as the real response is too long.
13345 EventInfo (Object)
13347 Information about a QMP event
13349 Members:
13351 "name: string"
13353 The event name
13354 Since: 1.2.0
13356 query-events (Command) Return information on QMP events.
13358 Features:
13360 "deprecated"
13362 This command is deprecated, because its output doesn't reflect
13363 compile-time configuration. Use 'query-qmp-schema' instead.
13364 Returns: A list of "EventInfo".
13366 Since: 1.2.0
13368 Example:
13370 -> { "execute": "query-events" }
13372 <- {
13373 "return": [
13374 {
13375 "name":"SHUTDOWN"
13376 },
13377 {
13378 "name":"RESET"
13379 }
13380 ]
13381 }
13382 Note: This example has been shortened as the real response is too long.
13384 quit (Command) This command will cause the QEMU process to exit
13386 gracefully. While every attempt is made to send the QMP response
13387 before terminating, this is not guaranteed. When using this interface,
13388 a premature EOF would not be unexpected.
13389 Since: 0.14.0
13391 Example:
13393 -> { "execute": "quit" }
13395 <- { "return": {} }
13396 MonitorMode (Enum)
13398 An enumeration of monitor modes.
13400 Values:
13402 "readline"
13404 HMP monitor (human-oriented command line interface)
13405 "control"
13407 QMP monitor (JSON-based machine interface)
13408 Since: 5.0
13410 MonitorOptions (Object)
13412 Options to be used for adding a new monitor.
13414 Members:
13416 "id: string" (optional)
13418 Name of the monitor
13419 "mode: MonitorMode" (optional)
13421 Selects the monitor mode (default: readline in the system emulator,
13422 control in qemu-storage-daemon)
13423 "pretty: boolean" (optional)
13425 Enables pretty printing (QMP only)
13426 "chardev: string"
13428 Name of a character device to expose the monitor on
13429 Since: 5.0
13431 QMP introspection
13433 query-qmp-schema (Command) Command query-qmp-schema exposes the QMP
13434 wire ABI as an array of SchemaInfo. This lets QMP clients figure out
13435 what commands and events are available in this QEMU, and their
13436 parameters and results.
13437 However, the SchemaInfo can't reflect all the rules and restrictions
13439 that apply to QMP. It's interface introspection (figuring out what's
13440 there), not interface specification. The specification is in the QAPI
13441 schema.
13442 Furthermore, while we strive to keep the QMP wire format backwards-
13444 compatible across qemu versions, the introspection output is not
13445 guaranteed to have the same stability. For example, one version of
13446 qemu may list an object member as an optional non-variant, while
13447 another lists the same member only through the object's variants; or
13448 the type of a member may change from a generic string into a specific
13449 enum or from one specific type into an alternate that includes the
13450 original type alongside something else.
13451 Returns: array of "SchemaInfo", where each element describes an entity
13453 in the ABI: command, event, type, ...
13454 The order of the various SchemaInfo is unspecified; however, all names
13456 are guaranteed to be unique (no name will be duplicated with different
13457 meta-types).
13458 Note: the QAPI schema is also used to help define internal interfaces,
13460 by defining QAPI types. These are not part of the QMP wire ABI, and
13461 therefore not returned by this command.
13462 Since: 2.5
13464 SchemaMetaType (Enum)
13466 This is a "SchemaInfo"'s meta type, i.e. the kind of entity it
13468 describes.
13469 Values:
13471 "builtin"
13473 a predefined type such as 'int' or 'bool'.
13474 "enum"
13476 an enumeration type
13477 "array"
13479 an array type
13480 "object"
13482 an object type (struct or union)
13483 "alternate"
13485 an alternate type
13486 "command"
13488 a QMP command
13489 "event"
13491 a QMP event
13492 Since: 2.5
13494 SchemaInfo (Object)
13496 Members:
13498 "name: string"
13500 the entity's name, inherited from "base". The SchemaInfo is always
13501 referenced by this name. Commands and events have the name defined
13502 in the QAPI schema. Unlike command and event names, type names are
13503 not part of the wire ABI. Consequently, type names are meaningless
13504 strings here, although they are still guaranteed unique regardless
13505 of "meta-type".
13506 "meta-type: SchemaMetaType"
13508 the entity's meta type, inherited from "base".
13509 "features: array of string" (optional)
13511 names of features associated with the entity, in no particular
13512 order. (since 4.1 for object types, 4.2 for commands, 5.0 for the
13513 rest)
13514 The members of "SchemaInfoBuiltin" when "meta-type" is "builtin"
13516 The members of "SchemaInfoEnum" when "meta-type" is "enum"
13517 The members of "SchemaInfoArray" when "meta-type" is "array"
13518 The members of "SchemaInfoObject" when "meta-type" is "object"
13519 The members of "SchemaInfoAlternate" when "meta-type" is "alternate"
13520 The members of "SchemaInfoCommand" when "meta-type" is "command"
13521 The members of "SchemaInfoEvent" when "meta-type" is "event"
13522 Additional members depend on the value of "meta-type".
13524 Since: 2.5
13526 SchemaInfoBuiltin (Object)
13528 Additional SchemaInfo members for meta-type 'builtin'.
13530 Members:
13532 "json-type: JSONType"
13534 the JSON type used for this type on the wire.
13535 Since: 2.5
13537 JSONType (Enum)
13539 The four primitive and two structured types according to RFC 8259
13541 section 1, plus 'int' (split off 'number'), plus the obvious top type
13542 'value'.
13543 Values:
13545 "string"
13547 Not documented
13548 "number"
13550 Not documented
13551 "int"
13553 Not documented
13554 "boolean"
13556 Not documented
13557 "null"
13559 Not documented
13560 "object"
13562 Not documented
13563 "array"
13565 Not documented
13566 "value"
13568 Not documented
13569 Since: 2.5
13571 SchemaInfoEnum (Object)
13573 Additional SchemaInfo members for meta-type 'enum'.
13575 Members:
13577 "values: array of string"
13579 the enumeration type's values, in no particular order.
13580 Values of this type are JSON string on the wire.
13582 Since: 2.5
13584 SchemaInfoArray (Object)
13586 Additional SchemaInfo members for meta-type 'array'.
13588 Members:
13590 "element-type: string"
13592 the array type's element type.
13593 Values of this type are JSON array on the wire.
13595 Since: 2.5
13597 SchemaInfoObject (Object)
13599 Additional SchemaInfo members for meta-type 'object'.
13601 Members:
13603 "members: array of SchemaInfoObjectMember"
13605 the object type's (non-variant) members, in no particular order.
13606 "tag: string" (optional)
13608 the name of the member serving as type tag. An element of
13609 "members" with this name must exist.
13610 "variants: array of SchemaInfoObjectVariant" (optional)
13612 variant members, i.e. additional members that depend on the type
13613 tag's value. Present exactly when "tag" is present. The variants
13614 are in no particular order, and may even differ from the order of
13615 the values of the enum type of the "tag".
13616 Values of this type are JSON object on the wire.
13618 Since: 2.5
13620 SchemaInfoObjectMember (Object)
13622 An object member.
13624 Members:
13626 "name: string"
13628 the member's name, as defined in the QAPI schema.
13629 "type: string"
13631 the name of the member's type.
13632 "default: value" (optional)
13634 default when used as command parameter. If absent, the parameter
13635 is mandatory. If present, the value must be null. The parameter
13636 is optional, and behavior when it's missing is not specified here.
13637 Future extension: if present and non-null, the parameter is
13638 optional, and defaults to this value.
13639 "features: array of string" (optional)
13641 names of features associated with the member, in no particular
13642 order. (since 5.0)
13643 Since: 2.5
13645 SchemaInfoObjectVariant (Object)
13647 The variant members for a value of the type tag.
13649 Members:
13651 "case: string"
13653 a value of the type tag.
13654 "type: string"
13656 the name of the object type that provides the variant members when
13657 the type tag has value "case".
13658 Since: 2.5
13660 SchemaInfoAlternate (Object)
13662 Additional SchemaInfo members for meta-type 'alternate'.
13664 Members:
13666 "members: array of SchemaInfoAlternateMember"
13668 the alternate type's members, in no particular order. The members'
13669 wire encoding is distinct, see docs/devel/qapi-code-gen.txt section
13670 Alternate types.
13671 On the wire, this can be any of the members.
13673 Since: 2.5
13675 SchemaInfoAlternateMember (Object)
13677 An alternate member.
13679 Members:
13681 "type: string"
13683 the name of the member's type.
13684 Since: 2.5
13686 SchemaInfoCommand (Object)
13688 Additional SchemaInfo members for meta-type 'command'.
13690 Members:
13692 "arg-type: string"
13694 the name of the object type that provides the command's parameters.
13695 "ret-type: string"
13697 the name of the command's result type.
13698 "allow-oob: boolean" (optional)
13700 whether the command allows out-of-band execution, defaults to false
13701 (Since: 2.12)
13702 TODO: "success-response" (currently irrelevant, because it's QGA, not
13704 QMP)
13705 Since: 2.5
13707 SchemaInfoEvent (Object)
13709 Additional SchemaInfo members for meta-type 'event'.
13711 Members:
13713 "arg-type: string"
13715 the name of the object type that provides the event's parameters.
13716 Since: 2.5
13718 QEMU Object Model (QOM)
13720 ObjectPropertyInfo (Object)
13721 Members:
13723 "name: string"
13725 the name of the property
13726 "type: string"
13728 the type of the property. This will typically come in one of four
13729 forms:
13730 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or
13732 'double'. These types are mapped to the appropriate JSON type.
13733 2) A child type in the form 'child<subtype>' where subtype is a
13735 qdev device type name. Child properties create the composition
13736 tree.
13737 3) A link type in the form 'link<subtype>' where subtype is a qdev
13739 device type name. Link properties form the device model graph.
13740 "description: string" (optional)
13742 if specified, the description of the property.
13743 "default-value: value" (optional)
13745 the default value, if any (since 5.0)
13746 Since: 1.2
13748 qom-list (Command) This command will list any properties of a object
13750 given a path in the object model.
13751 Arguments:
13753 "path: string"
13755 the path within the object model. See "qom-get" for a description
13756 of this parameter.
13757 Returns: a list of "ObjectPropertyInfo" that describe the properties of
13759 the object.
13760 Since: 1.2
13762 Example:
13764 -> { "execute": "qom-list",
13766 "arguments": { "path": "/chardevs" } }
13767 <- { "return": [ { "name": "type", "type": "string" },
13768 { "name": "parallel0", "type": "child<chardev-vc>" },
13769 { "name": "serial0", "type": "child<chardev-vc>" },
13770 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
13771 qom-get (Command) This command will get a property from a object model
13773 path and return the value.
13774 Arguments:
13776 "path: string"
13778 The path within the object model. There are two forms of supported
13779 paths--absolute and partial paths.
13780 Absolute paths are derived from the root object and can follow
13782 child<> or link<> properties. Since they can follow link<>
13783 properties, they can be arbitrarily long. Absolute paths look like
13784 absolute filenames and are prefixed with a leading slash.
13785 Partial paths look like relative filenames. They do not begin with
13787 a prefix. The matching rules for partial paths are subtle but
13788 designed to make specifying objects easy. At each level of the
13789 composition tree, the partial path is matched as an absolute path.
13790 The first match is not returned. At least two matches are searched
13791 for. A successful result is only returned if only one match is
13792 found. If more than one match is found, a flag is return to
13793 indicate that the match was ambiguous.
13794 "property: string"
13796 The property name to read
13797 Returns: The property value. The type depends on the property type.
13799 child<> and link<> properties are returned as #str pathnames. All
13800 integer property types (u8, u16, etc) are returned as #int.
13801 Since: 1.2
13803 Example:
13805 1. Use absolute path
13807 -> { "execute": "qom-get",
13809 "arguments": { "path": "/machine/unattached/device[0]",
13810 "property": "hotplugged" } }
13811 <- { "return": false }
13812 2. Use partial path
13814 -> { "execute": "qom-get",
13816 "arguments": { "path": "unattached/sysbus",
13817 "property": "type" } }
13818 <- { "return": "System" }
13819 qom-set (Command) This command will set a property from a object model
13821 path.
13822 Arguments:
13824 "path: string"
13826 see "qom-get" for a description of this parameter
13827 "property: string"
13829 the property name to set
13830 "value: value"
13832 a value who's type is appropriate for the property type. See
13833 "qom-get" for a description of type mapping.
13834 Since: 1.2
13836 Example:
13838 -> { "execute": "qom-set",
13840 "arguments": { "path": "/machine",
13841 "property": "graphics",
13842 "value": false } }
13843 <- { "return": {} }
13844 ObjectTypeInfo (Object)
13846 This structure describes a search result from "qom-list-types"
13848 Members:
13850 "name: string"
13852 the type name found in the search
13853 "abstract: boolean" (optional)
13855 the type is abstract and can't be directly instantiated. Omitted
13856 if false. (since 2.10)
13857 "parent: string" (optional)
13859 Name of parent type, if any (since 2.10)
13860 Since: 1.1
13862 qom-list-types (Command) This command will return a list of types
13864 given search parameters
13865 Arguments:
13867 "implements: string" (optional)
13869 if specified, only return types that implement this type name
13870 "abstract: boolean" (optional)
13872 if true, include abstract types in the results
13873 Returns: a list of "ObjectTypeInfo" or an empty list if no results are
13875 found
13876 Since: 1.1
13878 qom-list-properties (Command) List properties associated with a QOM
13880 object.
13881 Arguments:
13883 "typename: string"
13885 the type name of an object
13886 Note: objects can create properties at runtime, for example to describe
13888 links between different devices and/or objects. These properties are
13889 not included in the output of this command.
13890 Returns: a list of ObjectPropertyInfo describing object properties
13892 Since: 2.12
13894 object-add (Command) Create a QOM object.
13896 Arguments:
13898 "qom-type: string"
13900 the class name for the object to be created
13901 "id: string"
13903 the name of the new object
13904 "props: value" (optional)
13906 a dictionary of properties to be passed to the backend. Deprecated
13907 since 5.0, specify the properties on the top level instead. It is
13908 an error to specify the same option both on the top level and in
13909 "props".
13910 Additional arguments depend on qom-type and are passed to the backend
13912 unchanged.
13913 Returns: Nothing on success Error if "qom-type" is not a valid class
13915 name
13916 Since: 2.0
13918 Example:
13920 -> { "execute": "object-add",
13922 "arguments": { "qom-type": "rng-random", "id": "rng1",
13923 "filename": "/dev/hwrng" } }
13924 <- { "return": {} }
13925 object-del (Command) Remove a QOM object.
13927 Arguments:
13929 "id: string"
13931 the name of the QOM object to remove
13932 Returns: Nothing on success Error if "id" is not a valid id for a QOM
13934 object
13935 Since: 2.0
13937 Example:
13939 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
13941 <- { "return": {} }
13942 Device infrastructure (qdev)
13944 device-list-properties (Command) List properties associated with a
13945 device.
13946 Arguments:
13948 "typename: string"
13950 the type name of a device
13951 Returns: a list of ObjectPropertyInfo describing a devices properties
13953 Note: objects can create properties at runtime, for example to describe
13955 links between different devices and/or objects. These properties are
13956 not included in the output of this command.
13957 Since: 1.2
13959 device_add (Command)
13961 Arguments:
13963 "driver: string"
13965 the name of the new device's driver
13966 "bus: string" (optional)
13968 the device's parent bus (device tree path)
13969 "id: string" (optional)
13971 the device's ID, must be unique
13972 Additional arguments depend on the type.
13974 Add a device.
13976 Notes:
13978 1. For detailed information about this command, please refer to the
13980 'docs/qdev-device-use.txt' file.
13981 2. It's possible to list device properties by running QEMU with the
13983 "-device DEVICE,help" command-line argument, where DEVICE is the
13984 device's name
13985 Example:
13987 -> { "execute": "device_add",
13989 "arguments": { "driver": "e1000", "id": "net1",
13990 "bus": "pci.0",
13991 "mac": "52:54:00:12:34:56" } }
13992 <- { "return": {} }
13993 TODO: This command effectively bypasses QAPI completely due to its
13995 "additional arguments" business. It shouldn't have been added to the
13996 schema in this form. It should be qapified properly, or replaced by a
13997 properly qapified command.
13998 Since: 0.13
14000 device_del (Command) Remove a device from a guest
14002 Arguments:
14004 "id: string"
14006 the device's ID or QOM path
14007 Returns: Nothing on success If "id" is not a valid device,
14009 DeviceNotFound
14010 Notes: When this command completes, the device may not be removed from
14012 the guest. Hot removal is an operation that requires guest
14013 cooperation. This command merely requests that the guest begin the hot
14014 removal process. Completion of the device removal process is signaled
14015 with a DEVICE_DELETED event. Guest reset will automatically complete
14016 removal for all devices.
14017 Since: 0.14.0
14019 Example:
14021 -> { "execute": "device_del",
14023 "arguments": { "id": "net1" } }
14024 <- { "return": {} }
14025 -> { "execute": "device_del",
14027 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
14028 <- { "return": {} }
14029 DEVICE_DELETED (Event) Emitted whenever the device removal completion
14031 is acknowledged by the guest. At this point, it's safe to reuse the
14032 specified device ID. Device removal can be initiated by the guest or by
14033 HMP/QMP commands.
14034 Arguments:
14036 "device: string" (optional)
14038 device name
14039 "path: string"
14041 device path
14042 Since: 1.5
14044 Example:
14046 <- { "event": "DEVICE_DELETED",
14048 "data": { "device": "virtio-net-pci-0",
14049 "path": "/machine/peripheral/virtio-net-pci-0" },
14050 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
14051 Machines
14053 SysEmuTarget (Enum)
14054 The comprehensive enumeration of QEMU system emulation ("softmmu")
14056 targets. Run "./configure --help" in the project root directory, and
14057 look for the *-softmmu targets near the "--target-list" option. The
14058 individual target constants are not documented here, for the time
14059 being.
14060 Values:
14062 "rx"
14064 since 5.0
14065 "avr"
14067 since 5.1
14068 "aarch64"
14070 Not documented
14071 "alpha"
14073 Not documented
14074 "arm"
14076 Not documented
14077 "cris"
14079 Not documented
14080 "hppa"
14082 Not documented
14083 "i386"
14085 Not documented
14086 "lm32"
14088 Not documented
14089 "m68k"
14091 Not documented
14092 "microblaze"
14094 Not documented
14095 "microblazeel"
14097 Not documented
14098 "mips"
14100 Not documented
14101 "mips64"
14103 Not documented
14104 "mips64el"
14106 Not documented
14107 "mipsel"
14109 Not documented
14110 "moxie"
14112 Not documented
14113 "nios2"
14115 Not documented
14116 "or1k"
14118 Not documented
14119 "ppc"
14121 Not documented
14122 "ppc64"
14124 Not documented
14125 "riscv32"
14127 Not documented
14128 "riscv64"
14130 Not documented
14131 "s390x"
14133 Not documented
14134 "sh4"
14136 Not documented
14137 "sh4eb"
14139 Not documented
14140 "sparc"
14142 Not documented
14143 "sparc64"
14145 Not documented
14146 "tricore"
14148 Not documented
14149 "unicore32"
14151 Not documented
14152 "x86_64"
14154 Not documented
14155 "xtensa"
14157 Not documented
14158 "xtensaeb"
14160 Not documented
14161 Notes: The resulting QMP strings can be appended to the "qemu-system-"
14163 prefix to produce the corresponding QEMU executable name. This is true
14164 even for "qemu-system-x86_64".
14165 Since: 3.0
14167 CpuInfoArch (Enum)
14169 An enumeration of cpu types that enable additional information during
14171 "query-cpus" and "query-cpus-fast".
14172 Values:
14174 "s390"
14176 since 2.12
14177 "riscv"
14179 since 2.12
14180 "x86"
14182 Not documented
14183 "sparc"
14185 Not documented
14186 "ppc"
14188 Not documented
14189 "mips"
14191 Not documented
14192 "tricore"
14194 Not documented
14195 "other"
14197 Not documented
14198 Since: 2.6
14200 CpuInfo (Object)
14202 Information about a virtual CPU
14204 Members:
14206 "CPU: int"
14208 the index of the virtual CPU
14209 "current: boolean"
14211 this only exists for backwards compatibility and should be ignored
14212 "halted: boolean"
14214 true if the virtual CPU is in the halt state. Halt usually refers
14215 to a processor specific low power mode.
14216 "qom_path: string"
14218 path to the CPU object in the QOM tree (since 2.4)
14219 "thread_id: int"
14221 ID of the underlying host thread
14222 "props: CpuInstanceProperties" (optional)
14224 properties describing to which node/socket/core/thread virtual CPU
14225 belongs to, provided if supported by board (since 2.10)
14226 "arch: CpuInfoArch"
14228 architecture of the cpu, which determines which additional fields
14229 will be listed (since 2.6)
14230 The members of "CpuInfoX86" when "arch" is "x86"
14232 The members of "CpuInfoSPARC" when "arch" is "sparc"
14233 The members of "CpuInfoPPC" when "arch" is "ppc"
14234 The members of "CpuInfoMIPS" when "arch" is "mips"
14235 The members of "CpuInfoTricore" when "arch" is "tricore"
14236 The members of "CpuInfoS390" when "arch" is "s390"
14237 The members of "CpuInfoRISCV" when "arch" is "riscv"
14238 Since: 0.14.0
14240 Notes: "halted" is a transient state that changes frequently. By the
14242 time the data is sent to the client, the guest may no longer be halted.
14243 CpuInfoX86 (Object)
14245 Additional information about a virtual i386 or x86_64 CPU
14247 Members:
14249 "pc: int"
14251 the 64-bit instruction pointer
14252 Since: 2.6
14254 CpuInfoSPARC (Object)
14256 Additional information about a virtual SPARC CPU
14258 Members:
14260 "pc: int"
14262 the PC component of the instruction pointer
14263 "npc: int"
14265 the NPC component of the instruction pointer
14266 Since: 2.6
14268 CpuInfoPPC (Object)
14270 Additional information about a virtual PPC CPU
14272 Members:
14274 "nip: int"
14276 the instruction pointer
14277 Since: 2.6
14279 CpuInfoMIPS (Object)
14281 Additional information about a virtual MIPS CPU
14283 Members:
14285 "PC: int"
14287 the instruction pointer
14288 Since: 2.6
14290 CpuInfoTricore (Object)
14292 Additional information about a virtual Tricore CPU
14294 Members:
14296 "PC: int"
14298 the instruction pointer
14299 Since: 2.6
14301 CpuInfoRISCV (Object)
14303 Additional information about a virtual RISCV CPU
14305 Members:
14307 "pc: int"
14309 the instruction pointer
14310 Since 2.12
14312 CpuS390State (Enum)
14314 An enumeration of cpu states that can be assumed by a virtual S390 CPU
14316 Values:
14318 "uninitialized"
14320 Not documented
14321 "stopped"
14323 Not documented
14324 "check-stop"
14326 Not documented
14327 "operating"
14329 Not documented
14330 "load"
14332 Not documented
14333 Since: 2.12
14335 CpuInfoS390 (Object)
14337 Additional information about a virtual S390 CPU
14339 Members:
14341 "cpu-state: CpuS390State"
14343 the virtual CPU's state
14344 Since: 2.12
14346 query-cpus (Command) Returns a list of information about each virtual
14348 CPU.
14349 This command causes vCPU threads to exit to userspace, which causes a
14351 small interruption to guest CPU execution. This will have a negative
14352 impact on realtime guests and other latency sensitive guest workloads.
14353 Features:
14355 "deprecated"
14357 This command is deprecated, because it interferes with the guest.
14358 Use 'query-cpus-fast' instead to avoid the vCPU interruption.
14359 Returns: a list of "CpuInfo" for each virtual CPU
14361 Since: 0.14.0
14363 Example:
14365 -> { "execute": "query-cpus" }
14367 <- { "return": [
14368 {
14369 "CPU":0,
14370 "current":true,
14371 "halted":false,
14372 "qom_path":"/machine/unattached/device[0]",
14373 "arch":"x86",
14374 "pc":3227107138,
14375 "thread_id":3134
14376 },
14377 {
14378 "CPU":1,
14379 "current":false,
14380 "halted":true,
14381 "qom_path":"/machine/unattached/device[2]",
14382 "arch":"x86",
14383 "pc":7108165,
14384 "thread_id":3135
14385 }
14386 ]
14387 }
14388 CpuInfoFast (Object)
14390 Information about a virtual CPU
14392 Members:
14394 "cpu-index: int"
14396 index of the virtual CPU
14397 "qom-path: string"
14399 path to the CPU object in the QOM tree
14400 "thread-id: int"
14402 ID of the underlying host thread
14403 "props: CpuInstanceProperties" (optional)
14405 properties describing to which node/socket/core/thread virtual CPU
14406 belongs to, provided if supported by board
14407 "arch: CpuInfoArch"
14409 base architecture of the cpu
14410 "target: SysEmuTarget"
14412 the QEMU system emulation target, which determines which additional
14413 fields will be listed (since 3.0)
14414 The members of "CpuInfoS390" when "target" is "s390x"
14416 Features:
14418 "deprecated"
14420 Member "arch" is deprecated. Use "target" instead.
14421 Since: 2.12
14423 query-cpus-fast (Command) Returns information about all virtual CPUs.
14425 This command does not incur a performance penalty and should be used in
14426 production instead of query-cpus.
14427 Returns: list of "CpuInfoFast"
14429 Since: 2.12
14431 Example:
14433 -> { "execute": "query-cpus-fast" }
14435 <- { "return": [
14436 {
14437 "thread-id": 25627,
14438 "props": {
14439 "core-id": 0,
14440 "thread-id": 0,
14441 "socket-id": 0
14442 },
14443 "qom-path": "/machine/unattached/device[0]",
14444 "arch":"x86",
14445 "target":"x86_64",
14446 "cpu-index": 0
14447 },
14448 {
14449 "thread-id": 25628,
14450 "props": {
14451 "core-id": 0,
14452 "thread-id": 0,
14453 "socket-id": 1
14454 },
14455 "qom-path": "/machine/unattached/device[2]",
14456 "arch":"x86",
14457 "target":"x86_64",
14458 "cpu-index": 1
14459 }
14460 ]
14461 }
14462 cpu-add (Command) Adds CPU with specified ID.
14464 Arguments:
14466 "id: int"
14468 ID of CPU to be created, valid values [0..max_cpus)
14469 Features:
14471 "deprecated"
14473 This command is deprecated. Use `device_add` instead. See the
14474 `query-hotpluggable-cpus` command for details.
14475 Returns: Nothing on success
14477 Since: 1.5
14479 Example:
14481 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
14483 <- { "return": {} }
14484 MachineInfo (Object)
14486 Information describing a machine.
14488 Members:
14490 "name: string"
14492 the name of the machine
14493 "alias: string" (optional)
14495 an alias for the machine name
14496 "is-default: boolean" (optional)
14498 whether the machine is default
14499 "cpu-max: int"
14501 maximum number of CPUs supported by the machine type (since 1.5.0)
14502 "hotpluggable-cpus: boolean"
14504 cpu hotplug via -device is supported (since 2.7.0)
14505 "numa-mem-supported: boolean"
14507 true if '-numa node,mem' option is supported by the machine type
14508 and false otherwise (since 4.1)
14509 "deprecated: boolean"
14511 if true, the machine type is deprecated and may be removed in
14512 future versions of QEMU according to the QEMU deprecation policy
14513 (since 4.1.0)
14514 "default-cpu-type: string" (optional)
14516 default CPU model typename if none is requested via the -cpu
14517 argument. (since 4.2)
14518 Since: 1.2.0
14520 query-machines (Command) Return a list of supported machines
14522 Returns: a list of MachineInfo
14524 Since: 1.2.0
14526 CurrentMachineParams (Object)
14528 Information describing the running machine parameters.
14530 Members:
14532 "wakeup-suspend-support: boolean"
14534 true if the machine supports wake up from suspend
14535 Since: 4.0
14537 query-current-machine (Command) Return information on the current
14539 virtual machine.
14540 Returns: CurrentMachineParams
14542 Since: 4.0
14544 TargetInfo (Object)
14546 Information describing the QEMU target.
14548 Members:
14550 "arch: SysEmuTarget"
14552 the target architecture
14553 Since: 1.2.0
14555 query-target (Command) Return information about the target for this
14557 QEMU
14558 Returns: TargetInfo
14560 Since: 1.2.0
14562 NumaOptionsType (Enum)
14564 Values:
14566 "node"
14568 NUMA nodes configuration
14569 "dist"
14571 NUMA distance configuration (since 2.10)
14572 "cpu"
14574 property based CPU(s) to node mapping (Since: 2.10)
14575 "hmat-lb"
14577 memory latency and bandwidth information (Since: 5.0)
14578 "hmat-cache"
14580 memory side cache information (Since: 5.0)
14581 Since: 2.1
14583 NumaOptions (Object)
14585 A discriminated record of NUMA options. (for OptsVisitor)
14587 Members:
14589 "type: NumaOptionsType"
14591 Not documented
14592 The members of "NumaNodeOptions" when "type" is "node"
14594 The members of "NumaDistOptions" when "type" is "dist"
14595 The members of "NumaCpuOptions" when "type" is "cpu"
14596 The members of "NumaHmatLBOptions" when "type" is "hmat-lb"
14597 The members of "NumaHmatCacheOptions" when "type" is "hmat-cache"
14598 Since: 2.1
14600 NumaNodeOptions (Object)
14602 Create a guest NUMA node. (for OptsVisitor)
14604 Members:
14606 "nodeid: int" (optional)
14608 NUMA node ID (increase by 1 from 0 if omitted)
14609 "cpus: array of int" (optional)
14611 VCPUs belonging to this node (assign VCPUS round-robin if omitted)
14612 "mem: int" (optional)
14614 memory size of this node; mutually exclusive with "memdev".
14615 Equally divide total memory among nodes if both "mem" and "memdev"
14616 are omitted.
14617 "memdev: string" (optional)
14619 memory backend object. If specified for one node, it must be
14620 specified for all nodes.
14621 "initiator: int" (optional)
14623 defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the
14624 nodeid which has the memory controller responsible for this NUMA
14625 node. This field provides additional information as to the
14626 initiator node that is closest (as in directly attached) to this
14627 node, and therefore has the best performance (since 5.0)
14628 Since: 2.1
14630 NumaDistOptions (Object)
14632 Set the distance between 2 NUMA nodes.
14634 Members:
14636 "src: int"
14638 source NUMA node.
14639 "dst: int"
14641 destination NUMA node.
14642 "val: int"
14644 NUMA distance from source node to destination node. When a node is
14645 unreachable from another node, set the distance between them to
14646 255.
14647 Since: 2.10
14649 X86CPURegister32 (Enum)
14651 A X86 32-bit register
14653 Values:
14655 "EAX"
14657 Not documented
14658 "EBX"
14660 Not documented
14661 "ECX"
14663 Not documented
14664 "EDX"
14666 Not documented
14667 "ESP"
14669 Not documented
14670 "EBP"
14672 Not documented
14673 "ESI"
14675 Not documented
14676 "EDI"
14678 Not documented
14679 Since: 1.5
14681 X86CPUFeatureWordInfo (Object)
14683 Information about a X86 CPU feature word
14685 Members:
14687 "cpuid-input-eax: int"
14689 Input EAX value for CPUID instruction for that feature word
14690 "cpuid-input-ecx: int" (optional)
14692 Input ECX value for CPUID instruction for that feature word
14693 "cpuid-register: X86CPURegister32"
14695 Output register containing the feature bits
14696 "features: int"
14698 value of output register, containing the feature bits
14699 Since: 1.5
14701 DummyForceArrays (Object)
14703 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList
14705 internally
14706 Members:
14708 "unused: array of X86CPUFeatureWordInfo"
14710 Not documented
14711 Since: 2.5
14713 NumaCpuOptions (Object)
14715 Option "-numa cpu" overrides default cpu to node mapping. It accepts
14717 the same set of cpu properties as returned by
14718 query-hotpluggable-cpus[].props, where node-id could be used to
14719 override default node mapping.
14720 Members:
14722 The members of "CpuInstanceProperties"
14724 Since: 2.10
14726 HmatLBMemoryHierarchy (Enum)
14728 The memory hierarchy in the System Locality Latency and Bandwidth
14730 Information Structure of HMAT (Heterogeneous Memory Attribute Table)
14731 For more information about "HmatLBMemoryHierarchy", see chapter
14733 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
14734 Values:
14736 "memory"
14738 the structure represents the memory performance
14739 "first-level"
14741 first level of memory side cache
14742 "second-level"
14744 second level of memory side cache
14745 "third-level"
14747 third level of memory side cache
14748 Since: 5.0
14750 HmatLBDataType (Enum)
14752 Data type in the System Locality Latency and Bandwidth Information
14754 Structure of HMAT (Heterogeneous Memory Attribute Table)
14755 For more information about "HmatLBDataType", see chapter 5.2.27.4:
14757 Table 5-146: Field "Data Type" of ACPI 6.3 spec.
14758 Values:
14760 "access-latency"
14762 access latency (nanoseconds)
14763 "read-latency"
14765 read latency (nanoseconds)
14766 "write-latency"
14768 write latency (nanoseconds)
14769 "access-bandwidth"
14771 access bandwidth (Bytes per second)
14772 "read-bandwidth"
14774 read bandwidth (Bytes per second)
14775 "write-bandwidth"
14777 write bandwidth (Bytes per second)
14778 Since: 5.0
14780 NumaHmatLBOptions (Object)
14782 Set the system locality latency and bandwidth information between
14784 Initiator and Target proximity Domains.
14785 For more information about "NumaHmatLBOptions", see chapter 5.2.27.4:
14787 Table 5-146 of ACPI 6.3 spec.
14788 Members:
14790 "initiator: int"
14792 the Initiator Proximity Domain.
14793 "target: int"
14795 the Target Proximity Domain.
14796 "hierarchy: HmatLBMemoryHierarchy"
14798 the Memory Hierarchy. Indicates the performance of memory or side
14799 cache.
14800 "data-type: HmatLBDataType"
14802 presents the type of data, access/read/write latency or hit
14803 latency.
14804 "latency: int" (optional)
14806 the value of latency from "initiator" to "target" proximity domain,
14807 the latency unit is "ns(nanosecond)".
14808 "bandwidth: int" (optional)
14810 the value of bandwidth between "initiator" and "target" proximity
14811 domain, the bandwidth unit is "Bytes per second".
14812 Since: 5.0
14814 HmatCacheAssociativity (Enum)
14816 Cache associativity in the Memory Side Cache Information Structure of
14818 HMAT
14819 For more information of "HmatCacheAssociativity", see chapter 5.2.27.5:
14821 Table 5-147 of ACPI 6.3 spec.
14822 Values:
14824 "none"
14826 None (no memory side cache in this proximity domain, or cache
14827 associativity unknown)
14828 "direct"
14830 Direct Mapped
14831 "complex"
14833 Complex Cache Indexing (implementation specific)
14834 Since: 5.0
14836 HmatCacheWritePolicy (Enum)
14838 Cache write policy in the Memory Side Cache Information Structure of
14840 HMAT
14841 For more information of "HmatCacheWritePolicy", see chapter 5.2.27.5:
14843 Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
14844 Values:
14846 "none"
14848 None (no memory side cache in this proximity domain, or cache write
14849 policy unknown)
14850 "write-back"
14852 Write Back (WB)
14853 "write-through"
14855 Write Through (WT)
14856 Since: 5.0
14858 NumaHmatCacheOptions (Object)
14860 Set the memory side cache information for a given memory domain.
14862 For more information of "NumaHmatCacheOptions", see chapter 5.2.27.5:
14864 Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
14865 Members:
14867 "node-id: int"
14869 the memory proximity domain to which the memory belongs.
14870 "size: int"
14872 the size of memory side cache in bytes.
14873 "level: int"
14875 the cache level described in this structure.
14876 "associativity: HmatCacheAssociativity"
14878 the cache associativity, none/direct-mapped/complex(complex cache
14879 indexing).
14880 "policy: HmatCacheWritePolicy"
14882 the write policy, none/write-back/write-through.
14883 "line: int"
14885 the cache Line size in bytes.
14886 Since: 5.0
14888 HostMemPolicy (Enum)
14890 Host memory policy types
14892 Values:
14894 "default"
14896 restore default policy, remove any nondefault policy
14897 "preferred"
14899 set the preferred host nodes for allocation
14900 "bind"
14902 a strict policy that restricts memory allocation to the host nodes
14903 specified
14904 "interleave"
14906 memory allocations are interleaved across the set of host nodes
14907 specified
14908 Since: 2.1
14910 Memdev (Object)
14912 Information about memory backend
14914 Members:
14916 "id: string" (optional)
14918 backend's ID if backend has 'id' property (since 2.9)
14919 "size: int"
14921 memory backend size
14922 "merge: boolean"
14924 enables or disables memory merge support
14925 "dump: boolean"
14927 includes memory backend's memory in a core dump or not
14928 "prealloc: boolean"
14930 enables or disables memory preallocation
14931 "host-nodes: array of int"
14933 host nodes for its memory policy
14934 "policy: HostMemPolicy"
14936 memory policy of memory backend
14937 Since: 2.1
14939 query-memdev (Command) Returns information for all memory backends.
14941 Returns: a list of "Memdev".
14943 Since: 2.1
14945 Example:
14947 -> { "execute": "query-memdev" }
14949 <- { "return": [
14950 {
14951 "id": "mem1",
14952 "size": 536870912,
14953 "merge": false,
14954 "dump": true,
14955 "prealloc": false,
14956 "host-nodes": [0, 1],
14957 "policy": "bind"
14958 },
14959 {
14960 "size": 536870912,
14961 "merge": false,
14962 "dump": true,
14963 "prealloc": true,
14964 "host-nodes": [2, 3],
14965 "policy": "preferred"
14966 }
14967 ]
14968 }
14969 CpuInstanceProperties (Object)
14971 List of properties to be used for hotplugging a CPU instance, it should
14973 be passed by management with device_add command when a CPU is being
14974 hotplugged.
14975 Members:
14977 "node-id: int" (optional)
14979 NUMA node ID the CPU belongs to
14980 "socket-id: int" (optional)
14982 socket number within node/board the CPU belongs to
14983 "die-id: int" (optional)
14985 die number within node/board the CPU belongs to (Since 4.1)
14986 "core-id: int" (optional)
14988 core number within die the CPU belongs to
14989 "thread-id: int" (optional)
14991 thread number within core the CPU belongs to
14992 Note: currently there are 5 properties that could be present but
14994 management should be prepared to pass through other properties with
14995 device_add command to allow for future interface extension. This also
14996 requires the filed names to be kept in sync with the properties passed
14997 to -device/device_add.
14998 Since: 2.7
15000 HotpluggableCPU (Object)
15002 Members:
15004 "type: string"
15006 CPU object type for usage with device_add command
15007 "props: CpuInstanceProperties"
15009 list of properties to be used for hotplugging CPU
15010 "vcpus-count: int"
15012 number of logical VCPU threads "HotpluggableCPU" provides
15013 "qom-path: string" (optional)
15015 link to existing CPU object if CPU is present or omitted if CPU is
15016 not present.
15017 Since: 2.7
15019 query-hotpluggable-cpus (Command)
15021 TODO: Better documentation; currently there is none.
15023 Returns: a list of HotpluggableCPU objects.
15025 Since: 2.7
15027 Example:
15029 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
15031 -> { "execute": "query-hotpluggable-cpus" }
15033 <- {"return": [
15034 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
15035 "vcpus-count": 1 },
15036 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
15037 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
15038 ]}'
15039 For pc machine type started with -smp 1,maxcpus=2:
15041 -> { "execute": "query-hotpluggable-cpus" }
15043 <- {"return": [
15044 {
15045 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
15046 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
15047 },
15048 {
15049 "qom-path": "/machine/unattached/device[0]",
15050 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
15051 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
15052 }
15053 ]}
15054 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
15056 (Since: 2.11):
15057 -> { "execute": "query-hotpluggable-cpus" }
15059 <- {"return": [
15060 {
15061 "type": "qemu-s390x-cpu", "vcpus-count": 1,
15062 "props": { "core-id": 1 }
15063 },
15064 {
15065 "qom-path": "/machine/unattached/device[0]",
15066 "type": "qemu-s390x-cpu", "vcpus-count": 1,
15067 "props": { "core-id": 0 }
15068 }
15069 ]}
15070 set-numa-node (Command) Runtime equivalent of '-numa' CLI option,
15072 available at preconfigure stage to configure numa mapping before
15073 initializing machine.
15074 Since 3.0
15076 Arguments: the members of "NumaOptions"
15078 CpuModelInfo (Object)
15080 Virtual CPU model.
15082 A CPU model consists of the name of a CPU definition, to which delta
15084 changes are applied (e.g. features added/removed). Most magic values
15085 that an architecture might require should be hidden behind the name.
15086 However, if required, architectures can expose relevant properties.
15087 Members:
15089 "name: string"
15091 the name of the CPU definition the model is based on
15092 "props: value" (optional)
15094 a dictionary of QOM properties to be applied
15095 Since: 2.8.0
15097 CpuModelExpansionType (Enum)
15099 An enumeration of CPU model expansion types.
15101 Values:
15103 "static"
15105 Expand to a static CPU model, a combination of a static base model
15106 name and property delta changes. As the static base model will
15107 never change, the expanded CPU model will be the same, independent
15108 of QEMU version, machine type, machine options, and accelerator
15109 options. Therefore, the resulting model can be used by tooling
15110 without having to specify a compatibility machine - e.g. when
15111 displaying the "host" model. The "static" CPU models are migration-
15112 safe.
15113 "full"
15115 Expand all properties. The produced model is not guaranteed to be
15116 migration-safe, but allows tooling to get an insight and work with
15117 model details.
15118 Note: When a non-migration-safe CPU model is expanded in static mode,
15120 some features enabled by the CPU model may be omitted, because they
15121 can't be implemented by a static CPU model definition (e.g. cache info
15122 passthrough and PMU passthrough in x86). If you need an accurate
15123 representation of the features enabled by a non-migration-safe CPU
15124 model, use "full". If you need a static representation that will keep
15125 ABI compatibility even when changing QEMU version or machine-type, use
15126 "static" (but keep in mind that some features may be omitted).
15127 Since: 2.8.0
15129 CpuModelCompareResult (Enum)
15131 An enumeration of CPU model comparison results. The result is usually
15133 calculated using e.g. CPU features or CPU generations.
15134 Values:
15136 "incompatible"
15138 If model A is incompatible to model B, model A is not guaranteed to
15139 run where model B runs and the other way around.
15140 "identical"
15142 If model A is identical to model B, model A is guaranteed to run
15143 where model B runs and the other way around.
15144 "superset"
15146 If model A is a superset of model B, model B is guaranteed to run
15147 where model A runs. There are no guarantees about the other way.
15148 "subset"
15150 If model A is a subset of model B, model A is guaranteed to run
15151 where model B runs. There are no guarantees about the other way.
15152 Since: 2.8.0
15154 CpuModelBaselineInfo (Object)
15156 The result of a CPU model baseline.
15158 Members:
15160 "model: CpuModelInfo"
15162 the baselined CpuModelInfo.
15163 Since: 2.8.0
15165 If: "defined(TARGET_S390X)"
15167 CpuModelCompareInfo (Object)
15169 The result of a CPU model comparison.
15171 Members:
15173 "result: CpuModelCompareResult"
15175 The result of the compare operation.
15176 "responsible-properties: array of string"
15178 List of properties that led to the comparison result not being
15179 identical.
15180 "responsible-properties" is a list of QOM property names that led to
15182 both CPUs not being detected as identical. For identical models, this
15183 list is empty. If a QOM property is read-only, that means there's no
15184 known way to make the CPU models identical. If the special property
15185 name "type" is included, the models are by definition not identical and
15186 cannot be made identical.
15187 Since: 2.8.0
15189 If: "defined(TARGET_S390X)"
15191 query-cpu-model-comparison (Command) Compares two CPU models,
15193 returning how they compare in a specific configuration. The results
15194 indicates how both models compare regarding runnability. This result
15195 can be used by tooling to make decisions if a certain CPU model will
15196 run in a certain configuration or if a compatible CPU model has to be
15197 created by baselining.
15198 Usually, a CPU model is compared against the maximum possible CPU model
15200 of a certain configuration (e.g. the "host" model for KVM). If that CPU
15201 model is identical or a subset, it will run in that configuration.
15202 The result returned by this command may be affected by:
15204 · QEMU version: CPU models may look different depending on the QEMU
15206 version. (Except for CPU models reported as "static" in query-cpu-
15207 definitions.)
15208 · machine-type: CPU model may look different depending on the
15210 machine-type. (Except for CPU models reported as "static" in
15211 query-cpu-definitions.)
15212 · machine options (including accelerator): in some architectures, CPU
15214 models may look different depending on machine and accelerator
15215 options. (Except for CPU models reported as "static" in query-cpu-
15216 definitions.)
15217 · "-cpu" arguments and global properties: arguments to the -cpu
15219 option and global properties may affect expansion of CPU models.
15220 Using query-cpu-model-expansion while using these is not advised.
15221 Some architectures may not support comparing CPU models. s390x supports
15223 comparing CPU models.
15224 Arguments:
15226 "modela: CpuModelInfo"
15228 Not documented
15229 "modelb: CpuModelInfo"
15231 Not documented
15232 Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU
15234 models is not supported, if a model cannot be used, if a model contains
15235 an unknown cpu definition name, unknown properties or properties with
15236 wrong types.
15237 Note: this command isn't specific to s390x, but is only implemented on
15239 this architecture currently.
15240 Since: 2.8.0
15242 If: "defined(TARGET_S390X)"
15244 query-cpu-model-baseline (Command) Baseline two CPU models, creating a
15246 compatible third model. The created model will always be a static,
15247 migration-safe CPU model (see "static" CPU model expansion for
15248 details).
15249 This interface can be used by tooling to create a compatible CPU model
15251 out two CPU models. The created CPU model will be identical to or a
15252 subset of both CPU models when comparing them. Therefore, the created
15253 CPU model is guaranteed to run where the given CPU models run.
15254 The result returned by this command may be affected by:
15256 · QEMU version: CPU models may look different depending on the QEMU
15258 version. (Except for CPU models reported as "static" in query-cpu-
15259 definitions.)
15260 · machine-type: CPU model may look different depending on the
15262 machine-type. (Except for CPU models reported as "static" in
15263 query-cpu-definitions.)
15264 · machine options (including accelerator): in some architectures, CPU
15266 models may look different depending on machine and accelerator
15267 options. (Except for CPU models reported as "static" in query-cpu-
15268 definitions.)
15269 · "-cpu" arguments and global properties: arguments to the -cpu
15271 option and global properties may affect expansion of CPU models.
15272 Using query-cpu-model-expansion while using these is not advised.
15273 Some architectures may not support baselining CPU models. s390x
15275 supports baselining CPU models.
15276 Arguments:
15278 "modela: CpuModelInfo"
15280 Not documented
15281 "modelb: CpuModelInfo"
15283 Not documented
15284 Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU
15286 models is not supported, if a model cannot be used, if a model contains
15287 an unknown cpu definition name, unknown properties or properties with
15288 wrong types.
15289 Note: this command isn't specific to s390x, but is only implemented on
15291 this architecture currently.
15292 Since: 2.8.0
15294 If: "defined(TARGET_S390X)"
15296 CpuModelExpansionInfo (Object)
15298 The result of a cpu model expansion.
15300 Members:
15302 "model: CpuModelInfo"
15304 the expanded CpuModelInfo.
15305 Since: 2.8.0
15307 If: "defined(TARGET_S390X) || defined(TARGET_I386) ||
15309 defined(TARGET_ARM)"
15310 query-cpu-model-expansion (Command) Expands a given CPU model (or a
15312 combination of CPU model + additional options) to different
15313 granularities, allowing tooling to get an understanding what a specific
15314 CPU model looks like in QEMU under a certain configuration.
15315 This interface can be used to query the "host" CPU model.
15317 The data returned by this command may be affected by:
15319 · QEMU version: CPU models may look different depending on the QEMU
15321 version. (Except for CPU models reported as "static" in query-cpu-
15322 definitions.)
15323 · machine-type: CPU model may look different depending on the
15325 machine-type. (Except for CPU models reported as "static" in
15326 query-cpu-definitions.)
15327 · machine options (including accelerator): in some architectures, CPU
15329 models may look different depending on machine and accelerator
15330 options. (Except for CPU models reported as "static" in query-cpu-
15331 definitions.)
15332 · "-cpu" arguments and global properties: arguments to the -cpu
15334 option and global properties may affect expansion of CPU models.
15335 Using query-cpu-model-expansion while using these is not advised.
15336 Some architectures may not support all expansion types. s390x supports
15338 "full" and "static". Arm only supports "full".
15339 Arguments:
15341 "type: CpuModelExpansionType"
15343 Not documented
15344 "model: CpuModelInfo"
15346 Not documented
15347 Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU
15349 models is not supported, if the model cannot be expanded, if the model
15350 contains an unknown CPU definition name, unknown properties or
15351 properties with a wrong type. Also returns an error if an expansion
15352 type is not supported.
15353 Since: 2.8.0
15355 If: "defined(TARGET_S390X) || defined(TARGET_I386) ||
15357 defined(TARGET_ARM)"
15358 CpuDefinitionInfo (Object)
15360 Virtual CPU definition.
15362 Members:
15364 "name: string"
15366 the name of the CPU definition
15367 "migration-safe: boolean" (optional)
15369 whether a CPU definition can be safely used for migration in
15370 combination with a QEMU compatibility machine when migrating
15371 between different QEMU versions and between hosts with different
15372 sets of (hardware or software) capabilities. If not provided,
15373 information is not available and callers should not assume the CPU
15374 definition to be migration-safe. (since 2.8)
15375 "static: boolean"
15377 whether a CPU definition is static and will not change depending on
15378 QEMU version, machine type, machine options and accelerator
15379 options. A static model is always migration-safe. (since 2.8)
15380 "unavailable-features: array of string" (optional)
15382 List of properties that prevent the CPU model from running in the
15383 current host. (since 2.8)
15384 "typename: string"
15386 Type name that can be used as argument to "device-list-properties",
15387 to introspect properties configurable using -cpu or -global.
15388 (since 2.9)
15389 "alias-of: string" (optional)
15391 Name of CPU model this model is an alias for. The target of the
15392 CPU model alias may change depending on the machine type.
15393 Management software is supposed to translate CPU model aliases in
15394 the VM configuration, because aliases may stop being migration-safe
15395 in the future (since 4.1)
15396 "unavailable-features" is a list of QOM property names that represent
15398 CPU model attributes that prevent the CPU from running. If the QOM
15399 property is read-only, that means there's no known way to make the CPU
15400 model run in the current host. Implementations that choose not to
15401 provide specific information return the property name "type". If the
15402 property is read-write, it means that it MAY be possible to run the CPU
15403 model in the current host if that property is changed. Management
15404 software can use it as hints to suggest or choose an alternative for
15405 the user, or just to generate meaningful error messages explaining why
15406 the CPU model can't be used. If "unavailable-features" is an empty
15407 list, the CPU model is runnable using the current host and machine-
15408 type. If "unavailable-features" is not present, runnability
15409 information for the CPU is not available.
15410 Since: 1.2.0
15412 If: "defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386)
15414 || defined(TARGET_S390X) || defined(TARGET_MIPS)"
15415 query-cpu-definitions (Command) Return a list of supported virtual CPU
15417 definitions
15418 Returns: a list of CpuDefInfo
15420 Since: 1.2.0
15422 If: "defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386)
15424 || defined(TARGET_S390X) || defined(TARGET_MIPS)"
15425 Miscellanea
15427 LostTickPolicy (Enum)
15428 Policy for handling lost ticks in timer devices. Ticks end up getting
15430 lost when, for example, the guest is paused.
15431 Values:
15433 "discard"
15435 throw away the missed ticks and continue with future injection
15436 normally. The guest OS will see the timer jump ahead by a
15437 potentially quite significant amount all at once, as if the
15438 intervening chunk of time had simply not existed; needless to say,
15439 such a sudden jump can easily confuse a guest OS which is not
15440 specifically prepared to deal with it. Assuming the guest OS can
15441 deal correctly with the time jump, the time in the guest and in the
15442 host should now match.
15443 "delay"
15445 continue to deliver ticks at the normal rate. The guest OS will
15446 not notice anything is amiss, as from its point of view time will
15447 have continued to flow normally. The time in the guest should now
15448 be behind the time in the host by exactly the amount of time during
15449 which ticks have been missed.
15450 "slew"
15452 deliver ticks at a higher rate to catch up with the missed ticks.
15453 The guest OS will not notice anything is amiss, as from its point
15454 of view time will have continued to flow normally. Once the timer
15455 has managed to catch up with all the missing ticks, the time in the
15456 guest and in the host should match.
15457 Since: 2.0
15459 add_client (Command) Allow client connections for VNC, Spice and
15461 socket based character devices to be passed in to QEMU via SCM_RIGHTS.
15462 Arguments:
15464 "protocol: string"
15466 protocol name. Valid names are "vnc", "spice" or the name of a
15467 character device (eg. from -chardev id=XXXX)
15468 "fdname: string"
15470 file descriptor name previously passed via 'getfd' command
15471 "skipauth: boolean" (optional)
15473 whether to skip authentication. Only applies to "vnc" and "spice"
15474 protocols
15475 "tls: boolean" (optional)
15477 whether to perform TLS. Only applies to the "spice" protocol
15478 Returns: nothing on success.
15480 Since: 0.14.0
15482 Example:
15484 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
15486 "fdname": "myclient" } }
15487 <- { "return": {} }
15488 NameInfo (Object)
15490 Guest name information.
15492 Members:
15494 "name: string" (optional)
15496 The name of the guest
15497 Since: 0.14.0
15499 query-name (Command) Return the name information of a guest.
15501 Returns: "NameInfo" of the guest
15503 Since: 0.14.0
15505 Example:
15507 -> { "execute": "query-name" }
15509 <- { "return": { "name": "qemu-name" } }
15510 KvmInfo (Object)
15512 Information about support for KVM acceleration
15514 Members:
15516 "enabled: boolean"
15518 true if KVM acceleration is active
15519 "present: boolean"
15521 true if KVM acceleration is built into this executable
15522 Since: 0.14.0
15524 query-kvm (Command) Returns information about KVM acceleration
15526 Returns: "KvmInfo"
15528 Since: 0.14.0
15530 Example:
15532 -> { "execute": "query-kvm" }
15534 <- { "return": { "enabled": true, "present": true } }
15535 UuidInfo (Object)
15537 Guest UUID information (Universally Unique Identifier).
15539 Members:
15541 "UUID: string"
15543 the UUID of the guest
15544 Since: 0.14.0
15546 Notes: If no UUID was specified for the guest, a null UUID is returned.
15548 query-uuid (Command) Query the guest UUID information.
15550 Returns: The "UuidInfo" for the guest
15552 Since: 0.14.0
15554 Example:
15556 -> { "execute": "query-uuid" }
15558 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
15559 IOThreadInfo (Object)
15561 Information about an iothread
15563 Members:
15565 "id: string"
15567 the identifier of the iothread
15568 "thread-id: int"
15570 ID of the underlying host thread
15571 "poll-max-ns: int"
15573 maximum polling time in ns, 0 means polling is disabled (since 2.9)
15574 "poll-grow: int"
15576 how many ns will be added to polling time, 0 means that it's not
15577 configured (since 2.9)
15578 "poll-shrink: int"
15580 how many ns will be removed from polling time, 0 means that it's
15581 not configured (since 2.9)
15582 Since: 2.0
15584 query-iothreads (Command) Returns a list of information about each
15586 iothread.
15587 Note: this list excludes the QEMU main loop thread, which is not
15589 declared using the -object iothread command-line option. It is always
15590 the main thread of the process.
15591 Returns: a list of "IOThreadInfo" for each iothread
15593 Since: 2.0
15595 Example:
15597 -> { "execute": "query-iothreads" }
15599 <- { "return": [
15600 {
15601 "id":"iothread0",
15602 "thread-id":3134
15603 },
15604 {
15605 "id":"iothread1",
15606 "thread-id":3135
15607 }
15608 ]
15609 }
15610 BalloonInfo (Object)
15612 Information about the guest balloon device.
15614 Members:
15616 "actual: int"
15618 the number of bytes the balloon currently contains
15619 Since: 0.14.0
15621 query-balloon (Command) Return information about the balloon device.
15623 Returns:
15625 - "BalloonInfo" on success
15627 - If the balloon driver is enabled but not functional because the KVM
15629 kernel module cannot support it, KvmMissingCap
15630 - If no balloon device is present, DeviceNotActive
15632 Since: 0.14.0
15634 Example:
15636 -> { "execute": "query-balloon" }
15638 <- { "return": {
15639 "actual": 1073741824,
15640 }
15641 }
15642 BALLOON_CHANGE (Event) Emitted when the guest changes the actual
15644 BALLOON level. This value is equivalent to the "actual" field return by
15645 the 'query-balloon' command
15646 Arguments:
15648 "actual: int"
15650 actual level of the guest memory balloon in bytes
15651 Note: this event is rate-limited.
15653 Since: 1.2
15655 Example:
15657 <- { "event": "BALLOON_CHANGE",
15659 "data": { "actual": 944766976 },
15660 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
15661 PciMemoryRange (Object)
15663 A PCI device memory region
15665 Members:
15667 "base: int"
15669 the starting address (guest physical)
15670 "limit: int"
15672 the ending address (guest physical)
15673 Since: 0.14.0
15675 PciMemoryRegion (Object)
15677 Information about a PCI device I/O region.
15679 Members:
15681 "bar: int"
15683 the index of the Base Address Register for this region
15684 "type: string"
15686 - 'io' if the region is a PIO region
15687 - 'memory' if the region is a MMIO region
15689 "size: int"
15691 memory size
15692 "prefetch: boolean" (optional)
15694 if "type" is 'memory', true if the memory is prefetchable
15695 "mem_type_64: boolean" (optional)
15697 if "type" is 'memory', true if the BAR is 64-bit
15698 "address: int"
15700 Not documented
15701 Since: 0.14.0
15703 PciBusInfo (Object)
15705 Information about a bus of a PCI Bridge device
15707 Members:
15709 "number: int"
15711 primary bus interface number. This should be the number of the bus
15712 the device resides on.
15713 "secondary: int"
15715 secondary bus interface number. This is the number of the main bus
15716 for the bridge
15717 "subordinate: int"
15719 This is the highest number bus that resides below the bridge.
15720 "io_range: PciMemoryRange"
15722 The PIO range for all devices on this bridge
15723 "memory_range: PciMemoryRange"
15725 The MMIO range for all devices on this bridge
15726 "prefetchable_range: PciMemoryRange"
15728 The range of prefetchable MMIO for all devices on this bridge
15729 Since: 2.4
15731 PciBridgeInfo (Object)
15733 Information about a PCI Bridge device
15735 Members:
15737 "bus: PciBusInfo"
15739 information about the bus the device resides on
15740 "devices: array of PciDeviceInfo" (optional)
15742 a list of "PciDeviceInfo" for each device on this bridge
15743 Since: 0.14.0
15745 PciDeviceClass (Object)
15747 Information about the Class of a PCI device
15749 Members:
15751 "desc: string" (optional)
15753 a string description of the device's class
15754 "class: int"
15756 the class code of the device
15757 Since: 2.4
15759 PciDeviceId (Object)
15761 Information about the Id of a PCI device
15763 Members:
15765 "device: int"
15767 the PCI device id
15768 "vendor: int"
15770 the PCI vendor id
15771 "subsystem: int" (optional)
15773 the PCI subsystem id (since 3.1)
15774 "subsystem-vendor: int" (optional)
15776 the PCI subsystem vendor id (since 3.1)
15777 Since: 2.4
15779 PciDeviceInfo (Object)
15781 Information about a PCI device
15783 Members:
15785 "bus: int"
15787 the bus number of the device
15788 "slot: int"
15790 the slot the device is located in
15791 "function: int"
15793 the function of the slot used by the device
15794 "class_info: PciDeviceClass"
15796 the class of the device
15797 "id: PciDeviceId"
15799 the PCI device id
15800 "irq: int" (optional)
15802 if an IRQ is assigned to the device, the IRQ number
15803 "irq_pin: int"
15805 the IRQ pin, zero means no IRQ (since 5.1)
15806 "qdev_id: string"
15808 the device name of the PCI device
15809 "pci_bridge: PciBridgeInfo" (optional)
15811 if the device is a PCI bridge, the bridge information
15812 "regions: array of PciMemoryRegion"
15814 a list of the PCI I/O regions associated with the device
15815 Notes: the contents of "class_info".desc are not stable and should only
15817 be treated as informational.
15818 Since: 0.14.0
15820 PciInfo (Object)
15822 Information about a PCI bus
15824 Members:
15826 "bus: int"
15828 the bus index
15829 "devices: array of PciDeviceInfo"
15831 a list of devices on this bus
15832 Since: 0.14.0
15834 query-pci (Command) Return information about the PCI bus topology of
15836 the guest.
15837 Returns: a list of "PciInfo" for each PCI bus. Each bus is represented
15839 by a json-object, which has a key with a json-array of all PCI devices
15840 attached to it. Each device is represented by a json-object.
15841 Since: 0.14.0
15843 Example:
15845 -> { "execute": "query-pci" }
15847 <- { "return": [
15848 {
15849 "bus": 0,
15850 "devices": [
15851 {
15852 "bus": 0,
15853 "qdev_id": "",
15854 "slot": 0,
15855 "class_info": {
15856 "class": 1536,
15857 "desc": "Host bridge"
15858 },
15859 "id": {
15860 "device": 32902,
15861 "vendor": 4663
15862 },
15863 "function": 0,
15864 "regions": [
15865 ]
15866 },
15867 {
15868 "bus": 0,
15869 "qdev_id": "",
15870 "slot": 1,
15871 "class_info": {
15872 "class": 1537,
15873 "desc": "ISA bridge"
15874 },
15875 "id": {
15876 "device": 32902,
15877 "vendor": 28672
15878 },
15879 "function": 0,
15880 "regions": [
15881 ]
15882 },
15883 {
15884 "bus": 0,
15885 "qdev_id": "",
15886 "slot": 1,
15887 "class_info": {
15888 "class": 257,
15889 "desc": "IDE controller"
15890 },
15891 "id": {
15892 "device": 32902,
15893 "vendor": 28688
15894 },
15895 "function": 1,
15896 "regions": [
15897 {
15898 "bar": 4,
15899 "size": 16,
15900 "address": 49152,
15901 "type": "io"
15902 }
15903 ]
15904 },
15905 {
15906 "bus": 0,
15907 "qdev_id": "",
15908 "slot": 2,
15909 "class_info": {
15910 "class": 768,
15911 "desc": "VGA controller"
15912 },
15913 "id": {
15914 "device": 4115,
15915 "vendor": 184
15916 },
15917 "function": 0,
15918 "regions": [
15919 {
15920 "prefetch": true,
15921 "mem_type_64": false,
15922 "bar": 0,
15923 "size": 33554432,
15924 "address": 4026531840,
15925 "type": "memory"
15926 },
15927 {
15928 "prefetch": false,
15929 "mem_type_64": false,
15930 "bar": 1,
15931 "size": 4096,
15932 "address": 4060086272,
15933 "type": "memory"
15934 },
15935 {
15936 "prefetch": false,
15937 "mem_type_64": false,
15938 "bar": 6,
15939 "size": 65536,
15940 "address": -1,
15941 "type": "memory"
15942 }
15943 ]
15944 },
15945 {
15946 "bus": 0,
15947 "qdev_id": "",
15948 "irq": 11,
15949 "slot": 4,
15950 "class_info": {
15951 "class": 1280,
15952 "desc": "RAM controller"
15953 },
15954 "id": {
15955 "device": 6900,
15956 "vendor": 4098
15957 },
15958 "function": 0,
15959 "regions": [
15960 {
15961 "bar": 0,
15962 "size": 32,
15963 "address": 49280,
15964 "type": "io"
15965 }
15966 ]
15967 }
15968 ]
15969 }
15970 ]
15971 }
15972 Note: This example has been shortened as the real response is too long.
15974 stop (Command) Stop all guest VCPU execution.
15976 Since: 0.14.0
15978 Notes: This function will succeed even if the guest is already in the
15980 stopped state. In "inmigrate" state, it will ensure that the guest
15981 remains paused once migration finishes, as if the -S option was passed
15982 on the command line.
15983 Example:
15985 -> { "execute": "stop" }
15987 <- { "return": {} }
15988 system_reset (Command) Performs a hard reset of a guest.
15990 Since: 0.14.0
15992 Example:
15994 -> { "execute": "system_reset" }
15996 <- { "return": {} }
15997 system_powerdown (Command) Requests that a guest perform a powerdown
15999 operation.
16000 Since: 0.14.0
16002 Notes: A guest may or may not respond to this command. This command
16004 returning does not indicate that a guest has accepted the request or
16005 that it has shut down. Many guests will respond to this command by
16006 prompting the user in some way.
16007 Example:
16009 -> { "execute": "system_powerdown" }
16011 <- { "return": {} }
16012 memsave (Command) Save a portion of guest memory to a file.
16014 Arguments:
16016 "val: int"
16018 the virtual address of the guest to start from
16019 "size: int"
16021 the size of memory region to save
16022 "filename: string"
16024 the file to save the memory to as binary data
16025 "cpu-index: int" (optional)
16027 the index of the virtual CPU to use for translating the virtual
16028 address (defaults to CPU 0)
16029 Returns: Nothing on success
16031 Since: 0.14.0
16033 Notes: Errors were not reliably returned until 1.1
16035 Example:
16037 -> { "execute": "memsave",
16039 "arguments": { "val": 10,
16040 "size": 100,
16041 "filename": "/tmp/virtual-mem-dump" } }
16042 <- { "return": {} }
16043 pmemsave (Command) Save a portion of guest physical memory to a file.
16045 Arguments:
16047 "val: int"
16049 the physical address of the guest to start from
16050 "size: int"
16052 the size of memory region to save
16053 "filename: string"
16055 the file to save the memory to as binary data
16056 Returns: Nothing on success
16058 Since: 0.14.0
16060 Notes: Errors were not reliably returned until 1.1
16062 Example:
16064 -> { "execute": "pmemsave",
16066 "arguments": { "val": 10,
16067 "size": 100,
16068 "filename": "/tmp/physical-mem-dump" } }
16069 <- { "return": {} }
16070 cont (Command) Resume guest VCPU execution.
16072 Since: 0.14.0
16074 Returns: If successful, nothing
16076 Notes: This command will succeed if the guest is currently running. It
16078 will also succeed if the guest is in the "inmigrate" state; in this
16079 case, the effect of the command is to make sure the guest starts once
16080 migration finishes, removing the effect of the -S command line option
16081 if it was passed.
16082 Example:
16084 -> { "execute": "cont" }
16086 <- { "return": {} }
16087 x-exit-preconfig (Command) Exit from "preconfig" state
16089 This command makes QEMU exit the preconfig state and proceed with VM
16091 initialization using configuration data provided on the command line
16092 and via the QMP monitor during the preconfig state. The command is only
16093 available during the preconfig state (i.e. when the --preconfig command
16094 line option was in use).
16095 Since 3.0
16097 Returns: nothing
16099 Example:
16101 -> { "execute": "x-exit-preconfig" }
16103 <- { "return": {} }
16104 system_wakeup (Command) Wake up guest from suspend. If the guest has
16106 wake-up from suspend support enabled (wakeup-suspend-support flag from
16107 query-current-machine), wake-up guest from suspend if the guest is in
16108 SUSPENDED state. Return an error otherwise.
16109 Since: 1.1
16111 Returns: nothing.
16113 Note: prior to 4.0, this command does nothing in case the guest isn't
16115 suspended.
16116 Example:
16118 -> { "execute": "system_wakeup" }
16120 <- { "return": {} }
16121 inject-nmi (Command) Injects a Non-Maskable Interrupt into the default
16123 CPU (x86/s390) or all CPUs (ppc64). The command fails when the guest
16124 doesn't support injecting.
16125 Returns: If successful, nothing
16127 Since: 0.14.0
16129 Note: prior to 2.1, this command was only supported for x86 and s390
16131 VMs
16132 Example:
16134 -> { "execute": "inject-nmi" }
16136 <- { "return": {} }
16137 balloon (Command) Request the balloon driver to change its balloon
16139 size.
16140 Arguments:
16142 "value: int"
16144 the target size of the balloon in bytes
16145 Returns:
16147 - Nothing on success
16149 - If the balloon driver is enabled but not functional because the KVM
16151 kernel module cannot support it, KvmMissingCap
16152 - If no balloon device is present, DeviceNotActive
16154 Notes: This command just issues a request to the guest. When it
16156 returns, the balloon size may not have changed. A guest can change the
16157 balloon size independent of this command.
16158 Since: 0.14.0
16160 Example:
16162 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
16164 <- { "return": {} }
16165 human-monitor-command (Command) Execute a command on the human monitor
16167 and return the output.
16168 Arguments:
16170 "command-line: string"
16172 the command to execute in the human monitor
16173 "cpu-index: int" (optional)
16175 The CPU to use for commands that require an implicit CPU
16176 Features:
16178 "savevm-monitor-nodes"
16180 If present, HMP command savevm only snapshots monitor-owned nodes
16181 if they have no parents. This allows the use of 'savevm' with
16182 -blockdev. (since 4.2)
16183 Returns: the output of the command as a string
16185 Since: 0.14.0
16187 Notes: This command only exists as a stop-gap. Its use is highly
16189 discouraged. The semantics of this command are not guaranteed: this
16190 means that command names, arguments and responses can change or be
16191 removed at ANY time. Applications that rely on long term stability
16192 guarantees should NOT use this command.
16193 Known limitations:
16195 · This command is stateless, this means that commands that depend on
16197 state information (such as getfd) might not work
16198 · Commands that prompt the user for data don't currently work
16200 Example:
16202 -> { "execute": "human-monitor-command",
16204 "arguments": { "command-line": "info kvm" } }
16205 <- { "return": "kvm support: enabled\r\n" }
16206 change (Command) This command is multiple commands multiplexed
16208 together.
16209 Arguments:
16211 "device: string"
16213 This is normally the name of a block device but it may also be
16214 'vnc'. when it's 'vnc', then sub command depends on "target"
16215 "target: string"
16217 If "device" is a block device, then this is the new filename. If
16218 "device" is 'vnc', then if the value 'password' selects the vnc
16219 change password command. Otherwise, this specifies a new server
16220 URI address to listen to for VNC connections.
16221 "arg: string" (optional)
16223 If "device" is a block device, then this is an optional format to
16224 open the device with. If "device" is 'vnc' and "target" is
16225 'password', this is the new VNC password to set. See change-vnc-
16226 password for additional notes.
16227 Features:
16229 "deprecated"
16231 This command is deprecated. For changing block devices, use
16232 'blockdev-change-medium' instead; for changing VNC parameters, use
16233 'change-vnc-password' instead.
16234 Returns:
16236 - Nothing on success.
16238 - If "device" is not a valid block device, DeviceNotFound
16240 Since: 0.14.0
16242 Example:
16244 1. Change a removable medium
16246 -> { "execute": "change",
16248 "arguments": { "device": "ide1-cd0",
16249 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
16250 <- { "return": {} }
16251 2. Change VNC password
16253 -> { "execute": "change",
16255 "arguments": { "device": "vnc", "target": "password",
16256 "arg": "foobar1" } }
16257 <- { "return": {} }
16258 xen-set-global-dirty-log (Command) Enable or disable the global dirty
16260 log mode.
16261 Arguments:
16263 "enable: boolean"
16265 true to enable, false to disable.
16266 Returns: nothing
16268 Since: 1.3
16270 Example:
16272 -> { "execute": "xen-set-global-dirty-log",
16274 "arguments": { "enable": true } }
16275 <- { "return": {} }
16276 getfd (Command) Receive a file descriptor via SCM rights and assign it
16278 a name
16279 Arguments:
16281 "fdname: string"
16283 file descriptor name
16284 Returns: Nothing on success
16286 Since: 0.14.0
16288 Notes: If "fdname" already exists, the file descriptor assigned to it
16290 will be closed and replaced by the received file descriptor.
16291 The 'closefd' command can be used to explicitly close the file
16293 descriptor when it is no longer needed.
16294 Example:
16296 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
16298 <- { "return": {} }
16299 closefd (Command) Close a file descriptor previously passed via SCM
16301 rights
16302 Arguments:
16304 "fdname: string"
16306 file descriptor name
16307 Returns: Nothing on success
16309 Since: 0.14.0
16311 Example:
16313 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
16315 <- { "return": {} }
16316 MemoryInfo (Object)
16318 Actual memory information in bytes.
16320 Members:
16322 "base-memory: int"
16324 size of "base" memory specified with command line option -m.
16325 "plugged-memory: int" (optional)
16327 size of memory that can be hot-unplugged. This field is omitted if
16328 target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE not
16329 defined at build time).
16330 Since: 2.11.0
16332 query-memory-size-summary (Command) Return the amount of initially
16334 allocated and present hotpluggable (if enabled) memory in bytes.
16335 Example:
16337 -> { "execute": "query-memory-size-summary" }
16339 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
16340 Since: 2.11.0
16342 AddfdInfo (Object)
16344 Information about a file descriptor that was added to an fd set.
16346 Members:
16348 "fdset-id: int"
16350 The ID of the fd set that "fd" was added to.
16351 "fd: int"
16353 The file descriptor that was received via SCM rights and added to
16354 the fd set.
16355 Since: 1.2.0
16357 add-fd (Command) Add a file descriptor, that was passed via SCM
16359 rights, to an fd set.
16360 Arguments:
16362 "fdset-id: int" (optional)
16364 The ID of the fd set to add the file descriptor to.
16365 "opaque: string" (optional)
16367 A free-form string that can be used to describe the fd.
16368 Returns:
16370 - "AddfdInfo" on success
16372 - If file descriptor was not received, FdNotSupplied
16374 - If "fdset-id" is a negative value, InvalidParameterValue
16376 Notes: The list of fd sets is shared by all monitor connections.
16378 If "fdset-id" is not specified, a new fd set will be created.
16380 Since: 1.2.0
16382 Example:
16384 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
16386 <- { "return": { "fdset-id": 1, "fd": 3 } }
16387 remove-fd (Command) Remove a file descriptor from an fd set.
16389 Arguments:
16391 "fdset-id: int"
16393 The ID of the fd set that the file descriptor belongs to.
16394 "fd: int" (optional)
16396 The file descriptor that is to be removed.
16397 Returns:
16399 - Nothing on success
16401 - If "fdset-id" or "fd" is not found, FdNotFound
16403 Since: 1.2.0
16405 Notes: The list of fd sets is shared by all monitor connections.
16407 If "fd" is not specified, all file descriptors in "fdset-id" will be
16409 removed.
16410 Example:
16412 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
16414 <- { "return": {} }
16415 FdsetFdInfo (Object)
16417 Information about a file descriptor that belongs to an fd set.
16419 Members:
16421 "fd: int"
16423 The file descriptor value.
16424 "opaque: string" (optional)
16426 A free-form string that can be used to describe the fd.
16427 Since: 1.2.0
16429 FdsetInfo (Object)
16431 Information about an fd set.
16433 Members:
16435 "fdset-id: int"
16437 The ID of the fd set.
16438 "fds: array of FdsetFdInfo"
16440 A list of file descriptors that belong to this fd set.
16441 Since: 1.2.0
16443 query-fdsets (Command) Return information describing all fd sets.
16445 Returns: A list of "FdsetInfo"
16447 Since: 1.2.0
16449 Note: The list of fd sets is shared by all monitor connections.
16451 Example:
16453 -> { "execute": "query-fdsets" }
16455 <- { "return": [
16456 {
16457 "fds": [
16458 {
16459 "fd": 30,
16460 "opaque": "rdonly:/path/to/file"
16461 },
16462 {
16463 "fd": 24,
16464 "opaque": "rdwr:/path/to/file"
16465 }
16466 ],
16467 "fdset-id": 1
16468 },
16469 {
16470 "fds": [
16471 {
16472 "fd": 28
16473 },
16474 {
16475 "fd": 29
16476 }
16477 ],
16478 "fdset-id": 0
16479 }
16480 ]
16481 }
16482 AcpiTableOptions (Object)
16484 Specify an ACPI table on the command line to load.
16486 At most one of "file" and "data" can be specified. The list of files
16488 specified by any one of them is loaded and concatenated in order. If
16489 both are omitted, "data" is implied.
16490 Other fields / optargs can be used to override fields of the generic
16492 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
16493 System Description Table Header. If a header field is not overridden,
16494 then the corresponding value from the concatenated blob is used (in
16495 case of "file"), or it is filled in with a hard-coded value (in case of
16496 "data").
16497 String fields are copied into the matching ACPI member from lowest
16499 address upwards, and silently truncated / NUL-padded to length.
16500 Members:
16502 "sig: string" (optional)
16504 table signature / identifier (4 bytes)
16505 "rev: int" (optional)
16507 table revision number (dependent on signature, 1 byte)
16508 "oem_id: string" (optional)
16510 OEM identifier (6 bytes)
16511 "oem_table_id: string" (optional)
16513 OEM table identifier (8 bytes)
16514 "oem_rev: int" (optional)
16516 OEM-supplied revision number (4 bytes)
16517 "asl_compiler_id: string" (optional)
16519 identifier of the utility that created the table (4 bytes)
16520 "asl_compiler_rev: int" (optional)
16522 revision number of the utility that created the table (4 bytes)
16523 "file: string" (optional)
16525 colon (:) separated list of pathnames to load and concatenate as
16526 table data. The resultant binary blob is expected to have an ACPI
16527 table header. At least one file is required. This field excludes
16528 "data".
16529 "data: string" (optional)
16531 colon (:) separated list of pathnames to load and concatenate as
16532 table data. The resultant binary blob must not have an ACPI table
16533 header. At least one file is required. This field excludes "file".
16534 Since: 1.5
16536 CommandLineParameterType (Enum)
16538 Possible types for an option parameter.
16540 Values:
16542 "string"
16544 accepts a character string
16545 "boolean"
16547 accepts "on" or "off"
16548 "number"
16550 accepts a number
16551 "size"
16553 accepts a number followed by an optional suffix (K)ilo, (M)ega,
16554 (G)iga, (T)era
16555 Since: 1.5
16557 CommandLineParameterInfo (Object)
16559 Details about a single parameter of a command line option.
16561 Members:
16563 "name: string"
16565 parameter name
16566 "type: CommandLineParameterType"
16568 parameter "CommandLineParameterType"
16569 "help: string" (optional)
16571 human readable text string, not suitable for parsing.
16572 "default: string" (optional)
16574 default value string (since 2.1)
16575 Since: 1.5
16577 CommandLineOptionInfo (Object)
16579 Details about a command line option, including its list of parameter
16581 details
16582 Members:
16584 "option: string"
16586 option name
16587 "parameters: array of CommandLineParameterInfo"
16589 an array of "CommandLineParameterInfo"
16590 Since: 1.5
16592 query-command-line-options (Command) Query command line option schema.
16594 Arguments:
16596 "option: string" (optional)
16598 option name
16599 Returns: list of "CommandLineOptionInfo" for all options (or for the
16601 given "option"). Returns an error if the given "option" doesn't exist.
16602 Since: 1.5
16604 Example:
16606 -> { "execute": "query-command-line-options",
16608 "arguments": { "option": "option-rom" } }
16609 <- { "return": [
16610 {
16611 "parameters": [
16612 {
16613 "name": "romfile",
16614 "type": "string"
16615 },
16616 {
16617 "name": "bootindex",
16618 "type": "number"
16619 }
16620 ],
16621 "option": "option-rom"
16622 }
16623 ]
16624 }
16625 PCDIMMDeviceInfo (Object)
16627 PCDIMMDevice state information
16629 Members:
16631 "id: string" (optional)
16633 device's ID
16634 "addr: int"
16636 physical address, where device is mapped
16637 "size: int"
16639 size of memory that the device provides
16640 "slot: int"
16642 slot number at which device is plugged in
16643 "node: int"
16645 NUMA node number where device is plugged in
16646 "memdev: string"
16648 memory backend linked with device
16649 "hotplugged: boolean"
16651 true if device was hotplugged
16652 "hotpluggable: boolean"
16654 true if device if could be added/removed while machine is running
16655 Since: 2.1
16657 VirtioPMEMDeviceInfo (Object)
16659 VirtioPMEM state information
16661 Members:
16663 "id: string" (optional)
16665 device's ID
16666 "memaddr: int"
16668 physical address in memory, where device is mapped
16669 "size: int"
16671 size of memory that the device provides
16672 "memdev: string"
16674 memory backend linked with device
16675 Since: 4.1
16677 VirtioMEMDeviceInfo (Object)
16679 VirtioMEMDevice state information
16681 Members:
16683 "id: string" (optional)
16685 device's ID
16686 "memaddr: int"
16688 physical address in memory, where device is mapped
16689 "requested-size: int"
16691 the user requested size of the device
16692 "size: int"
16694 the (current) size of memory that the device provides
16695 "max-size: int"
16697 the maximum size of memory that the device can provide
16698 "block-size: int"
16700 the block size of memory that the device provides
16701 "node: int"
16703 NUMA node number where device is assigned to
16704 "memdev: string"
16706 memory backend linked with the region
16707 Since: 5.1
16709 MemoryDeviceInfo (Object)
16711 Union containing information about a memory device
16713 nvdimm is included since 2.12. virtio-pmem is included since 4.1.
16715 virtio-mem is included since 5.1.
16716 Members:
16718 "type"
16720 One of "dimm", "nvdimm", "virtio-pmem", "virtio-mem"
16721 "data: PCDIMMDeviceInfo" when "type" is "dimm"
16723 "data: PCDIMMDeviceInfo" when "type" is "nvdimm"
16724 "data: VirtioPMEMDeviceInfo" when "type" is "virtio-pmem"
16725 "data: VirtioMEMDeviceInfo" when "type" is "virtio-mem"
16726 Since: 2.1
16728 query-memory-devices (Command) Lists available memory devices and
16730 their state
16731 Since: 2.1
16733 Example:
16735 -> { "execute": "query-memory-devices" }
16737 <- { "return": [ { "data":
16738 { "addr": 5368709120,
16739 "hotpluggable": true,
16740 "hotplugged": true,
16741 "id": "d1",
16742 "memdev": "/objects/memX",
16743 "node": 0,
16744 "size": 1073741824,
16745 "slot": 0},
16746 "type": "dimm"
16747 } ] }
16748 MEMORY_DEVICE_SIZE_CHANGE (Event) Emitted when the size of a memory
16750 device changes. Only emitted for memory devices that can actually
16751 change the size (e.g., virtio-mem due to guest action).
16752 Arguments:
16754 "id: string" (optional)
16756 device's ID
16757 "size: int"
16759 the new size of memory that the device provides
16760 Note: this event is rate-limited.
16762 Since: 5.1
16764 Example:
16766 <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
16768 "data": { "id": "vm0", "size": 1073741824},
16769 "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
16770 MEM_UNPLUG_ERROR (Event) Emitted when memory hot unplug error occurs.
16772 Arguments:
16774 "device: string"
16776 device name
16777 "msg: string"
16779 Informative message
16780 Since: 2.4
16782 Example:
16784 <- { "event": "MEM_UNPLUG_ERROR"
16786 "data": { "device": "dimm1",
16787 "msg": "acpi: device unplug for unsupported device"
16788 },
16789 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
16790 ACPISlotType (Enum)
16792 Values:
16794 "DIMM"
16796 memory slot
16797 "CPU"
16799 logical CPU slot (since 2.7)
16800 ACPIOSTInfo (Object)
16802 OSPM Status Indication for a device For description of possible values
16804 of "source" and "status" fields see "_OST (OSPM Status Indication)"
16805 chapter of ACPI5.0 spec.
16806 Members:
16808 "device: string" (optional)
16810 device ID associated with slot
16811 "slot: string"
16813 slot ID, unique per slot of a given "slot-type"
16814 "slot-type: ACPISlotType"
16816 type of the slot
16817 "source: int"
16819 an integer containing the source event
16820 "status: int"
16822 an integer containing the status code
16823 Since: 2.1
16825 query-acpi-ospm-status (Command) Return a list of ACPIOSTInfo for
16827 devices that support status reporting via ACPI _OST method.
16828 Since: 2.1
16830 Example:
16832 -> { "execute": "query-acpi-ospm-status" }
16834 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
16835 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
16836 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
16837 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
16838 ]}
16839 ACPI_DEVICE_OST (Event) Emitted when guest executes ACPI _OST method.
16841 Arguments:
16843 "info: ACPIOSTInfo"
16845 OSPM Status Indication
16846 Since: 2.1
16848 Example:
16850 <- { "event": "ACPI_DEVICE_OST",
16852 "data": { "device": "d1", "slot": "0",
16853 "slot-type": "DIMM", "source": 1, "status": 0 } }
16854 ReplayMode (Enum)
16856 Mode of the replay subsystem.
16858 Values:
16860 "none"
16862 normal execution mode. Replay or record are not enabled.
16863 "record"
16865 record mode. All non-deterministic data is written into the replay
16866 log.
16867 "play"
16869 replay mode. Non-deterministic data required for system execution
16870 is read from the log.
16871 Since: 2.5
16873 xen-load-devices-state (Command) Load the state of all devices from
16875 file. The RAM and the block devices of the VM are not loaded by this
16876 command.
16877 Arguments:
16879 "filename: string"
16881 the file to load the state of the devices from as binary data. See
16882 xen-save-devices-state.txt for a description of the binary format.
16883 Since: 2.7
16885 Example:
16887 -> { "execute": "xen-load-devices-state",
16889 "arguments": { "filename": "/tmp/resume" } }
16890 <- { "return": {} }
16891 GuidInfo (Object)
16893 GUID information.
16895 Members:
16897 "guid: string"
16899 the globally unique identifier
16900 Since: 2.9
16902 query-vm-generation-id (Command) Show Virtual Machine Generation ID
16904 Since: 2.9
16906 RTC_CHANGE (Event) Emitted when the guest changes the RTC time.
16908 Arguments:
16910 "offset: int"
16912 offset between base RTC clock (as specified by -rtc base), and new
16913 RTC clock value
16914 Note: This event is rate-limited.
16916 Since: 0.13.0
16918 Example:
16920 <- { "event": "RTC_CHANGE",
16922 "data": { "offset": 78 },
16923 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
16924 If: "defined(TARGET_ALPHA) || defined(TARGET_ARM) ||
16926 defined(TARGET_HPPA) || defined(TARGET_I386) || defined(TARGET_MIPS) ||
16927 defined(TARGET_MIPS64) || defined(TARGET_MOXIE) || defined(TARGET_PPC)
16928 || defined(TARGET_PPC64) || defined(TARGET_S390X) ||
16929 defined(TARGET_SH4) || defined(TARGET_SPARC)"
16930 rtc-reset-reinjection (Command) This command will reset the RTC
16932 interrupt reinjection backlog. Can be used if another mechanism to
16933 synchronize guest time is in effect, for example QEMU guest agent's
16934 guest-set-time command.
16935 Since: 2.1
16937 Example:
16939 -> { "execute": "rtc-reset-reinjection" }
16941 <- { "return": {} }
16942 If: "defined(TARGET_I386)"
16944 SevState (Enum)
16946 An enumeration of SEV state information used during "query-sev".
16948 Values:
16950 "uninit"
16952 The guest is uninitialized.
16953 "launch-update"
16955 The guest is currently being launched; plaintext data and register
16956 state is being imported.
16957 "launch-secret"
16959 The guest is currently being launched; ciphertext data is being
16960 imported.
16961 "running"
16963 The guest is fully launched or migrated in.
16964 "send-update"
16966 The guest is currently being migrated out to another machine.
16967 "receive-update"
16969 The guest is currently being migrated from another machine.
16970 Since: 2.12
16972 If: "defined(TARGET_I386)"
16974 SevInfo (Object)
16976 Information about Secure Encrypted Virtualization (SEV) support
16978 Members:
16980 "enabled: boolean"
16982 true if SEV is active
16983 "api-major: int"
16985 SEV API major version
16986 "api-minor: int"
16988 SEV API minor version
16989 "build-id: int"
16991 SEV FW build id
16992 "policy: int"
16994 SEV policy value
16995 "state: SevState"
16997 SEV guest state
16998 "handle: int"
17000 SEV firmware handle
17001 Since: 2.12
17003 If: "defined(TARGET_I386)"
17005 query-sev (Command) Returns information about SEV
17007 Returns: "SevInfo"
17009 Since: 2.12
17011 Example:
17013 -> { "execute": "query-sev" }
17015 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
17016 "build-id" : 0, "policy" : 0, "state" : "running",
17017 "handle" : 1 } }
17018 If: "defined(TARGET_I386)"
17020 SevLaunchMeasureInfo (Object)
17022 SEV Guest Launch measurement information
17024 Members:
17026 "data: string"
17028 the measurement value encoded in base64
17029 Since: 2.12
17031 If: "defined(TARGET_I386)"
17033 query-sev-launch-measure (Command) Query the SEV guest launch
17035 information.
17036 Returns: The "SevLaunchMeasureInfo" for the guest
17038 Since: 2.12
17040 Example:
17042 -> { "execute": "query-sev-launch-measure" }
17044 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
17045 If: "defined(TARGET_I386)"
17047 SevCapability (Object)
17049 The struct describes capability for a Secure Encrypted Virtualization
17051 feature.
17052 Members:
17054 "pdh: string"
17056 Platform Diffie-Hellman key (base64 encoded)
17057 "cert-chain: string"
17059 PDH certificate chain (base64 encoded)
17060 "cbitpos: int"
17062 C-bit location in page table entry
17063 "reduced-phys-bits: int"
17065 Number of physical Address bit reduction when SEV is enabled
17066 Since: 2.12
17068 If: "defined(TARGET_I386)"
17070 query-sev-capabilities (Command) This command is used to get the SEV
17072 capabilities, and is supported on AMD X86 platforms only.
17073 Returns: SevCapability objects.
17075 Since: 2.12
17077 Example:
17079 -> { "execute": "query-sev-capabilities" }
17081 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
17082 "cbitpos": 47, "reduced-phys-bits": 5}}
17083 If: "defined(TARGET_I386)"
17085 dump-skeys (Command) Dump guest's storage keys
17087 Arguments:
17089 "filename: string"
17091 the path to the file to dump to
17092 This command is only supported on s390 architecture.
17094 Since: 2.5
17096 Example:
17098 -> { "execute": "dump-skeys",
17100 "arguments": { "filename": "/tmp/skeys" } }
17101 <- { "return": {} }
17102 If: "defined(TARGET_S390X)"
17104 GICCapability (Object)
17106 The struct describes capability for a specific GIC (Generic Interrupt
17108 Controller) version. These bits are not only decided by QEMU/KVM
17109 software version, but also decided by the hardware that the program is
17110 running upon.
17111 Members:
17113 "version: int"
17115 version of GIC to be described. Currently, only 2 and 3 are
17116 supported.
17117 "emulated: boolean"
17119 whether current QEMU/hardware supports emulated GIC device in user
17120 space.
17121 "kernel: boolean"
17123 whether current QEMU/hardware supports hardware accelerated GIC
17124 device in kernel.
17125 Since: 2.6
17127 If: "defined(TARGET_ARM)"
17129 query-gic-capabilities (Command) This command is ARM-only. It will
17131 return a list of GICCapability objects that describe its capability
17132 bits.
17133 Returns: a list of GICCapability objects.
17135 Since: 2.6
17137 Example:
17139 -> { "execute": "query-gic-capabilities" }
17141 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
17142 { "version": 3, "emulated": false, "kernel": true } ] }
17143 If: "defined(TARGET_ARM)"
17145 AudiodevPerDirectionOptions (Object)
17147 General audio backend options that are used for both playback and
17149 recording.
17150 Members:
17152 "mixing-engine: boolean" (optional)
17154 use QEMU's mixing engine to mix all streams inside QEMU and convert
17155 audio formats when not supported by the backend. When set to off,
17156 fixed-settings must be also off (default on, since 4.2)
17157 "fixed-settings: boolean" (optional)
17159 use fixed settings for host input/output. When off, frequency,
17160 channels and format must not be specified (default true)
17161 "frequency: int" (optional)
17163 frequency to use when using fixed settings (default 44100)
17164 "channels: int" (optional)
17166 number of channels when using fixed settings (default 2)
17167 "voices: int" (optional)
17169 number of voices to use (default 1)
17170 "format: AudioFormat" (optional)
17172 sample format to use when using fixed settings (default s16)
17173 "buffer-length: int" (optional)
17175 the buffer length in microseconds
17176 Since: 4.0
17178 AudiodevGenericOptions (Object)
17180 Generic driver-specific options.
17182 Members:
17184 "in: AudiodevPerDirectionOptions" (optional)
17186 options of the capture stream
17187 "out: AudiodevPerDirectionOptions" (optional)
17189 options of the playback stream
17190 Since: 4.0
17192 AudiodevAlsaPerDirectionOptions (Object)
17194 Options of the ALSA backend that are used for both playback and
17196 recording.
17197 Members:
17199 "dev: string" (optional)
17201 the name of the ALSA device to use (default 'default')
17202 "period-length: int" (optional)
17204 the period length in microseconds
17205 "try-poll: boolean" (optional)
17207 attempt to use poll mode, falling back to non-polling access on
17208 failure (default true)
17209 The members of "AudiodevPerDirectionOptions"
17211 Since: 4.0
17213 AudiodevAlsaOptions (Object)
17215 Options of the ALSA audio backend.
17217 Members:
17219 "in: AudiodevAlsaPerDirectionOptions" (optional)
17221 options of the capture stream
17222 "out: AudiodevAlsaPerDirectionOptions" (optional)
17224 options of the playback stream
17225 "threshold: int" (optional)
17227 set the threshold (in microseconds) when playback starts
17228 Since: 4.0
17230 AudiodevCoreaudioPerDirectionOptions (Object)
17232 Options of the Core Audio backend that are used for both playback and
17234 recording.
17235 Members:
17237 "buffer-count: int" (optional)
17239 number of buffers
17240 The members of "AudiodevPerDirectionOptions"
17242 Since: 4.0
17244 AudiodevCoreaudioOptions (Object)
17246 Options of the coreaudio audio backend.
17248 Members:
17250 "in: AudiodevCoreaudioPerDirectionOptions" (optional)
17252 options of the capture stream
17253 "out: AudiodevCoreaudioPerDirectionOptions" (optional)
17255 options of the playback stream
17256 Since: 4.0
17258 AudiodevDsoundOptions (Object)
17260 Options of the DirectSound audio backend.
17262 Members:
17264 "in: AudiodevPerDirectionOptions" (optional)
17266 options of the capture stream
17267 "out: AudiodevPerDirectionOptions" (optional)
17269 options of the playback stream
17270 "latency: int" (optional)
17272 add extra latency to playback in microseconds (default 10000)
17273 Since: 4.0
17275 AudiodevJackPerDirectionOptions (Object)
17277 Options of the JACK backend that are used for both playback and
17279 recording.
17280 Members:
17282 "server-name: string" (optional)
17284 select from among several possible concurrent server instances
17285 (default: environment variable $JACK_DEFAULT_SERVER if set, else
17286 "default")
17287 "client-name: string" (optional)
17289 the client name to use. The server will modify this name to create
17290 a unique variant, if needed unless "exact-name" is true (default:
17291 the guest's name)
17292 "connect-ports: string" (optional)
17294 if set, a regular expression of JACK client port name(s) to monitor
17295 for and automatically connect to
17296 "start-server: boolean" (optional)
17298 start a jack server process if one is not already present (default:
17299 false)
17300 "exact-name: boolean" (optional)
17302 use the exact name requested otherwise JACK automatically generates
17303 a unique one, if needed (default: false)
17304 The members of "AudiodevPerDirectionOptions"
17306 Since: 5.1
17308 AudiodevJackOptions (Object)
17310 Options of the JACK audio backend.
17312 Members:
17314 "in: AudiodevJackPerDirectionOptions" (optional)
17316 options of the capture stream
17317 "out: AudiodevJackPerDirectionOptions" (optional)
17319 options of the playback stream
17320 Since: 5.1
17322 AudiodevOssPerDirectionOptions (Object)
17324 Options of the OSS backend that are used for both playback and
17326 recording.
17327 Members:
17329 "dev: string" (optional)
17331 file name of the OSS device (default '/dev/dsp')
17332 "buffer-count: int" (optional)
17334 number of buffers
17335 "try-poll: boolean" (optional)
17337 attempt to use poll mode, falling back to non-polling access on
17338 failure (default true)
17339 The members of "AudiodevPerDirectionOptions"
17341 Since: 4.0
17343 AudiodevOssOptions (Object)
17345 Options of the OSS audio backend.
17347 Members:
17349 "in: AudiodevOssPerDirectionOptions" (optional)
17351 options of the capture stream
17352 "out: AudiodevOssPerDirectionOptions" (optional)
17354 options of the playback stream
17355 "try-mmap: boolean" (optional)
17357 try using memory-mapped access, falling back to non-memory-mapped
17358 access on failure (default true)
17359 "exclusive: boolean" (optional)
17361 open device in exclusive mode (vmix won't work) (default false)
17362 "dsp-policy: int" (optional)
17364 set the timing policy of the device (between 0 and 10, where
17365 smaller number means smaller latency but higher CPU usage) or -1 to
17366 use fragment mode (option ignored on some platforms) (default 5)
17367 Since: 4.0
17369 AudiodevPaPerDirectionOptions (Object)
17371 Options of the Pulseaudio backend that are used for both playback and
17373 recording.
17374 Members:
17376 "name: string" (optional)
17378 name of the sink/source to use
17379 "stream-name: string" (optional)
17381 name of the PulseAudio stream created by qemu. Can be used to
17382 identify the stream in PulseAudio when you create multiple
17383 PulseAudio devices or run multiple qemu instances (default:
17384 audiodev's id, since 4.2)
17385 "latency: int" (optional)
17387 latency you want PulseAudio to achieve in microseconds (default
17388 15000)
17389 The members of "AudiodevPerDirectionOptions"
17391 Since: 4.0
17393 AudiodevPaOptions (Object)
17395 Options of the PulseAudio audio backend.
17397 Members:
17399 "in: AudiodevPaPerDirectionOptions" (optional)
17401 options of the capture stream
17402 "out: AudiodevPaPerDirectionOptions" (optional)
17404 options of the playback stream
17405 "server: string" (optional)
17407 PulseAudio server address (default: let PulseAudio choose)
17408 Since: 4.0
17410 AudiodevWavOptions (Object)
17412 Options of the wav audio backend.
17414 Members:
17416 "in: AudiodevPerDirectionOptions" (optional)
17418 options of the capture stream
17419 "out: AudiodevPerDirectionOptions" (optional)
17421 options of the playback stream
17422 "path: string" (optional)
17424 name of the wav file to record (default 'qemu.wav')
17425 Since: 4.0
17427 AudioFormat (Enum)
17429 An enumeration of possible audio formats.
17431 Values:
17433 "u8"
17435 unsigned 8 bit integer
17436 "s8"
17438 signed 8 bit integer
17439 "u16"
17441 unsigned 16 bit integer
17442 "s16"
17444 signed 16 bit integer
17445 "u32"
17447 unsigned 32 bit integer
17448 "s32"
17450 signed 32 bit integer
17451 "f32"
17453 single precision floating-point (since 5.0)
17454 Since: 4.0
17456 AudiodevDriver (Enum)
17458 An enumeration of possible audio backend drivers.
17460 Values:
17462 "jack"
17464 JACK audio backend (since 5.1)
17465 "none"
17467 Not documented
17468 "alsa"
17470 Not documented
17471 "coreaudio"
17473 Not documented
17474 "dsound"
17476 Not documented
17477 "oss"
17479 Not documented
17480 "pa"
17482 Not documented
17483 "sdl"
17485 Not documented
17486 "spice"
17488 Not documented
17489 "wav"
17491 Not documented
17492 Since: 4.0
17494 Audiodev (Object)
17496 Options of an audio backend.
17498 Members:
17500 "id: string"
17502 identifier of the backend
17503 "driver: AudiodevDriver"
17505 the backend driver to use
17506 "timer-period: int" (optional)
17508 timer period (in microseconds, 0: use lowest possible)
17509 The members of "AudiodevGenericOptions" when "driver" is "none"
17511 The members of "AudiodevAlsaOptions" when "driver" is "alsa"
17512 The members of "AudiodevCoreaudioOptions" when "driver" is "coreaudio"
17513 The members of "AudiodevDsoundOptions" when "driver" is "dsound"
17514 The members of "AudiodevJackOptions" when "driver" is "jack"
17515 The members of "AudiodevOssOptions" when "driver" is "oss"
17516 The members of "AudiodevPaOptions" when "driver" is "pa"
17517 The members of "AudiodevGenericOptions" when "driver" is "sdl"
17518 The members of "AudiodevGenericOptions" when "driver" is "spice"
17519 The members of "AudiodevWavOptions" when "driver" is "wav"
17520 Since: 4.0
17522 2021-01-11 QEMU-QMP-REF.7(7)