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 Since: 1.3
304 VsockSocketAddress (Object)
306 Captures a socket address in the vsock namespace.
308 Members:
310 "cid: string"
312 unique host identifier
313 "port: string"
315 port
316 Note: string types are used to allow for possible future hostname or
318 service resolution support.
319 Since: 2.8
321 SocketAddressLegacy (Object)
323 Captures the address of a socket, which could also be a named file
325 descriptor
326 Members:
328 "type"
330 One of "inet", "unix", "vsock", "fd"
331 "data: InetSocketAddress" when "type" is "inet"
333 "data: UnixSocketAddress" when "type" is "unix"
334 "data: VsockSocketAddress" when "type" is "vsock"
335 "data: String" when "type" is "fd"
336 Note: This type is deprecated in favor of SocketAddress. The
338 difference between SocketAddressLegacy and SocketAddress is that the
339 latter is a flat union rather than a simple union. Flat is nicer
340 because it avoids nesting on the wire, i.e. that form has fewer {}.
341 Since: 1.3
343 SocketAddressType (Enum)
345 Available SocketAddress types
347 Values:
349 "inet"
351 Internet address
352 "unix"
354 Unix domain socket
355 "vsock"
357 VMCI address
358 "fd"
360 decimal is for file descriptor number, otherwise a file descriptor
361 name. Named file descriptors are permitted in monitor commands, in
362 combination with the 'getfd' command. Decimal file descriptors are
363 permitted at startup or other contexts where no monitor context is
364 active.
365 Since: 2.9
367 SocketAddress (Object)
369 Captures the address of a socket, which could also be a named file
371 descriptor
372 Members:
374 "type: SocketAddressType"
376 Transport type
377 The members of "InetSocketAddress" when "type" is "inet"
379 The members of "UnixSocketAddress" when "type" is "unix"
380 The members of "VsockSocketAddress" when "type" is "vsock"
381 The members of "String" when "type" is "fd"
382 Since: 2.9
384 VM run state
386 RunState (Enum)
387 An enumeration of VM run states.
389 Values:
391 "debug"
393 QEMU is running on a debugger
394 "finish-migrate"
396 guest is paused to finish the migration process
397 "inmigrate"
399 guest is paused waiting for an incoming migration. Note that this
400 state does not tell whether the machine will start at the end of
401 the migration. This depends on the command-line -S option and any
402 invocation of 'stop' or 'cont' that has happened since QEMU was
403 started.
404 "internal-error"
406 An internal error that prevents further guest execution has
407 occurred
408 "io-error"
410 the last IOP has failed and the device is configured to pause on
411 I/O errors
412 "paused"
414 guest has been paused via the 'stop' command
415 "postmigrate"
417 guest is paused following a successful 'migrate'
418 "prelaunch"
420 QEMU was started with -S and guest has not started
421 "restore-vm"
423 guest is paused to restore VM state
424 "running"
426 guest is actively running
427 "save-vm"
429 guest is paused to save the VM state
430 "shutdown"
432 guest is shut down (and -no-shutdown is in use)
433 "suspended"
435 guest is suspended (ACPI S3)
436 "watchdog"
438 the watchdog action is configured to pause and has been triggered
439 "guest-panicked"
441 guest has been panicked as a result of guest OS panic
442 "colo"
444 guest is paused to save/restore VM state under colo checkpoint, VM
445 can not get into this state unless colo capability is enabled for
446 migration. (since 2.8)
447 "preconfig"
449 QEMU is paused before board specific init callback is executed.
450 The state is reachable only if the --preconfig CLI option is used.
451 (Since 3.0)
452 ShutdownCause (Enum)
454 An enumeration of reasons for a Shutdown.
456 Values:
458 "none"
460 No shutdown request pending
461 "host-error"
463 An error prevents further use of guest
464 "host-qmp-quit"
466 Reaction to the QMP command 'quit'
467 "host-qmp-system-reset"
469 Reaction to the QMP command 'system_reset'
470 "host-signal"
472 Reaction to a signal, such as SIGINT
473 "host-ui"
475 Reaction to a UI event, like window close
476 "guest-shutdown"
478 Guest shutdown/suspend request, via ACPI or other hardware-specific
479 means
480 "guest-reset"
482 Guest reset request, and command line turns that into a shutdown
483 "guest-panic"
485 Guest panicked, and command line turns that into a shutdown
486 "subsystem-reset"
488 Partial guest reset that does not trigger QMP events and ignores
489 --no-reboot. This is useful for sanitizing hypercalls on s390 that
490 are used during kexec/kdump/boot
491 StatusInfo (Object)
493 Information about VCPU run state
495 Members:
497 "running: boolean"
499 true if all VCPUs are runnable, false if not runnable
500 "singlestep: boolean"
502 true if VCPUs are in single-step mode
503 "status: RunState"
505 the virtual machine "RunState"
506 Since: 0.14.0
508 Notes: "singlestep" is enabled through the GDB stub
510 query-status (Command) Query the run status of all VCPUs
512 Returns: "StatusInfo" reflecting all VCPUs
514 Since: 0.14.0
516 Example:
518 -> { "execute": "query-status" }
520 <- { "return": { "running": true,
521 "singlestep": false,
522 "status": "running" } }
523 SHUTDOWN (Event) Emitted when the virtual machine has shut down,
525 indicating that qemu is about to exit.
526 Arguments:
528 "guest: boolean"
530 If true, the shutdown was triggered by a guest request (such as a
531 guest-initiated ACPI shutdown request or other hardware-specific
532 action) rather than a host request (such as sending qemu a SIGINT).
533 (since 2.10)
534 "reason: ShutdownCause"
536 The "ShutdownCause" which resulted in the SHUTDOWN. (since 4.0)
537 Note: If the command-line option "-no-shutdown" has been specified,
539 qemu will not exit, and a STOP event will eventually follow the
540 SHUTDOWN event
541 Since: 0.12.0
543 Example:
545 <- { "event": "SHUTDOWN", "data": { "guest": true },
547 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
548 POWERDOWN (Event) Emitted when the virtual machine is powered down
550 through the power control system, such as via ACPI.
551 Since: 0.12.0
553 Example:
555 <- { "event": "POWERDOWN",
557 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
558 RESET (Event) Emitted when the virtual machine is reset
560 Arguments:
562 "guest: boolean"
564 If true, the reset was triggered by a guest request (such as a
565 guest-initiated ACPI reboot request or other hardware-specific
566 action) rather than a host request (such as the QMP command
567 system_reset). (since 2.10)
568 "reason: ShutdownCause"
570 The "ShutdownCause" of the RESET. (since 4.0)
571 Since: 0.12.0
573 Example:
575 <- { "event": "RESET", "data": { "guest": false },
577 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
578 STOP (Event) Emitted when the virtual machine is stopped
580 Since: 0.12.0
582 Example:
584 <- { "event": "STOP",
586 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
587 RESUME (Event) Emitted when the virtual machine resumes execution
589 Since: 0.12.0
591 Example:
593 <- { "event": "RESUME",
595 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
596 SUSPEND (Event) Emitted when guest enters a hardware suspension state,
598 for example, S3 state, which is sometimes called standby state
599 Since: 1.1
601 Example:
603 <- { "event": "SUSPEND",
605 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
606 SUSPEND_DISK (Event) Emitted when guest enters a hardware suspension
608 state with data saved on disk, for example, S4 state, which is
609 sometimes called hibernate state
610 Note: QEMU shuts down (similar to event "SHUTDOWN") when entering this
612 state
613 Since: 1.2
615 Example:
617 <- { "event": "SUSPEND_DISK",
619 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
620 WAKEUP (Event) Emitted when the guest has woken up from suspend state
622 and is running
623 Since: 1.1
625 Example:
627 <- { "event": "WAKEUP",
629 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
630 WATCHDOG (Event) Emitted when the watchdog device's timer is expired
632 Arguments:
634 "action: WatchdogAction"
636 action that has been taken
637 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event
639 is followed respectively by the RESET, SHUTDOWN, or STOP events
640 Note: This event is rate-limited.
642 Since: 0.13.0
644 Example:
646 <- { "event": "WATCHDOG",
648 "data": { "action": "reset" },
649 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
650 WatchdogAction (Enum)
652 An enumeration of the actions taken when the watchdog device's timer is
654 expired
655 Values:
657 "reset"
659 system resets
660 "shutdown"
662 system shutdown, note that it is similar to "powerdown", which
663 tries to set to system status and notify guest
664 "poweroff"
666 system poweroff, the emulator program exits
667 "pause"
669 system pauses, similar to "stop"
670 "debug"
672 system enters debug state
673 "none"
675 nothing is done
676 "inject-nmi"
678 a non-maskable interrupt is injected into the first VCPU (all VCPUS
679 on x86) (since 2.4)
680 Since: 2.1
682 watchdog-set-action (Command) Set watchdog action
684 Arguments:
686 "action: WatchdogAction"
688 Not documented
689 Since: 2.11
691 GUEST_PANICKED (Event) Emitted when guest OS panic is detected
693 Arguments:
695 "action: GuestPanicAction"
697 action that has been taken, currently always "pause"
698 "info: GuestPanicInformation" (optional)
700 information about a panic (since 2.9)
701 Since: 1.5
703 Example:
705 <- { "event": "GUEST_PANICKED",
707 "data": { "action": "pause" } }
708 GuestPanicAction (Enum)
710 An enumeration of the actions taken when guest OS panic is detected
712 Values:
714 "pause"
716 system pauses
717 "poweroff"
719 Not documented
720 Since: 2.1 (poweroff since 2.8)
722 GuestPanicInformationType (Enum)
724 An enumeration of the guest panic information types
726 Values:
728 "hyper-v"
730 hyper-v guest panic information type
731 "s390"
733 s390 guest panic information type (Since: 2.12)
734 Since: 2.9
736 GuestPanicInformation (Object)
738 Information about a guest panic
740 Members:
742 "type: GuestPanicInformationType"
744 Crash type that defines the hypervisor specific information
745 The members of "GuestPanicInformationHyperV" when "type" is "hyper-v"
747 The members of "GuestPanicInformationS390" when "type" is "s390"
748 Since: 2.9
750 GuestPanicInformationHyperV (Object)
752 Hyper-V specific guest panic information (HV crash MSRs)
754 Members:
756 "arg1: int"
758 Not documented
759 "arg2: int"
761 Not documented
762 "arg3: int"
764 Not documented
765 "arg4: int"
767 Not documented
768 "arg5: int"
770 Not documented
771 Since: 2.9
773 S390CrashReason (Enum)
775 Reason why the CPU is in a crashed state.
777 Values:
779 "unknown"
781 no crash reason was set
782 "disabled-wait"
784 the CPU has entered a disabled wait state
785 "extint-loop"
787 clock comparator or cpu timer interrupt with new PSW enabled for
788 external interrupts
789 "pgmint-loop"
791 program interrupt with BAD new PSW
792 "opint-loop"
794 operation exception interrupt with invalid code at the program
795 interrupt new PSW
796 Since: 2.12
798 GuestPanicInformationS390 (Object)
800 S390 specific guest panic information (PSW)
802 Members:
804 "core: int"
806 core id of the CPU that crashed
807 "psw-mask: int"
809 control fields of guest PSW
810 "psw-addr: int"
812 guest instruction address
813 "reason: S390CrashReason"
815 guest crash reason
816 Since: 2.12
818 Cryptography
820 QCryptoTLSCredsEndpoint (Enum)
821 The type of network endpoint that will be using the credentials. Most
823 types of credential require different setup / structures depending on
824 whether they will be used in a server versus a client.
825 Values:
827 "client"
829 the network endpoint is acting as the client
830 "server"
832 the network endpoint is acting as the server
833 Since: 2.5
835 QCryptoSecretFormat (Enum)
837 The data format that the secret is provided in
839 Values:
841 "raw"
843 raw bytes. When encoded in JSON only valid UTF-8 sequences can be
844 used
845 "base64"
847 arbitrary base64 encoded binary data
848 Since: 2.6
850 QCryptoHashAlgorithm (Enum)
852 The supported algorithms for computing content digests
854 Values:
856 "md5"
858 MD5. Should not be used in any new code, legacy compat only
859 "sha1"
861 SHA-1. Should not be used in any new code, legacy compat only
862 "sha224"
864 SHA-224. (since 2.7)
865 "sha256"
867 SHA-256. Current recommended strong hash.
868 "sha384"
870 SHA-384. (since 2.7)
871 "sha512"
873 SHA-512. (since 2.7)
874 "ripemd160"
876 RIPEMD-160. (since 2.7)
877 Since: 2.6
879 QCryptoCipherAlgorithm (Enum)
881 The supported algorithms for content encryption ciphers
883 Values:
885 "aes-128"
887 AES with 128 bit / 16 byte keys
888 "aes-192"
890 AES with 192 bit / 24 byte keys
891 "aes-256"
893 AES with 256 bit / 32 byte keys
894 "des-rfb"
896 RFB specific variant of single DES. Do not use except in VNC.
897 "3des"
899 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
900 "cast5-128"
902 Cast5 with 128 bit / 16 byte keys
903 "serpent-128"
905 Serpent with 128 bit / 16 byte keys
906 "serpent-192"
908 Serpent with 192 bit / 24 byte keys
909 "serpent-256"
911 Serpent with 256 bit / 32 byte keys
912 "twofish-128"
914 Twofish with 128 bit / 16 byte keys
915 "twofish-192"
917 Twofish with 192 bit / 24 byte keys
918 "twofish-256"
920 Twofish with 256 bit / 32 byte keys
921 Since: 2.6
923 QCryptoCipherMode (Enum)
925 The supported modes for content encryption ciphers
927 Values:
929 "ecb"
931 Electronic Code Book
932 "cbc"
934 Cipher Block Chaining
935 "xts"
937 XEX with tweaked code book and ciphertext stealing
938 "ctr"
940 Counter (Since 2.8)
941 Since: 2.6
943 QCryptoIVGenAlgorithm (Enum)
945 The supported algorithms for generating initialization vectors for full
947 disk encryption. The 'plain' generator should not be used for disks
948 with sector numbers larger than 2^32, except where compatibility with
949 pre-existing Linux dm-crypt volumes is required.
950 Values:
952 "plain"
954 64-bit sector number truncated to 32-bits
955 "plain64"
957 64-bit sector number
958 "essiv"
960 64-bit sector number encrypted with a hash of the encryption key
961 Since: 2.6
963 QCryptoBlockFormat (Enum)
965 The supported full disk encryption formats
967 Values:
969 "qcow"
971 QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
972 data from old images.
973 "luks"
975 LUKS encryption format. Recommended for new images
976 Since: 2.6
978 QCryptoBlockOptionsBase (Object)
980 The common options that apply to all full disk encryption formats
982 Members:
984 "format: QCryptoBlockFormat"
986 the encryption format
987 Since: 2.6
989 QCryptoBlockOptionsQCow (Object)
991 The options that apply to QCow/QCow2 AES-CBC encryption format
993 Members:
995 "key-secret: string" (optional)
997 the ID of a QCryptoSecret object providing the decryption key.
998 Mandatory except when probing image for metadata only.
999 Since: 2.6
1001 QCryptoBlockOptionsLUKS (Object)
1003 The options that apply to LUKS encryption format
1005 Members:
1007 "key-secret: string" (optional)
1009 the ID of a QCryptoSecret object providing the decryption key.
1010 Mandatory except when probing image for metadata only.
1011 Since: 2.6
1013 QCryptoBlockCreateOptionsLUKS (Object)
1015 The options that apply to LUKS encryption format initialization
1017 Members:
1019 "cipher-alg: QCryptoCipherAlgorithm" (optional)
1021 the cipher algorithm for data encryption Currently defaults to
1022 'aes-256'.
1023 "cipher-mode: QCryptoCipherMode" (optional)
1025 the cipher mode for data encryption Currently defaults to 'xts'
1026 "ivgen-alg: QCryptoIVGenAlgorithm" (optional)
1028 the initialization vector generator Currently defaults to 'plain64'
1029 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1031 the initialization vector generator hash Currently defaults to
1032 'sha256'
1033 "hash-alg: QCryptoHashAlgorithm" (optional)
1035 the master key hash algorithm Currently defaults to 'sha256'
1036 "iter-time: int" (optional)
1038 number of milliseconds to spend in PBKDF passphrase processing.
1039 Currently defaults to 2000. (since 2.8)
1040 The members of "QCryptoBlockOptionsLUKS"
1042 Since: 2.6
1044 QCryptoBlockOpenOptions (Object)
1046 The options that are available for all encryption formats when opening
1048 an existing volume
1049 Members:
1051 The members of "QCryptoBlockOptionsBase"
1053 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1054 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
1055 Since: 2.6
1057 QCryptoBlockCreateOptions (Object)
1059 The options that are available for all encryption formats when
1061 initializing a new volume
1062 Members:
1064 The members of "QCryptoBlockOptionsBase"
1066 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1067 The members of "QCryptoBlockCreateOptionsLUKS" when "format" is "luks"
1068 Since: 2.6
1070 QCryptoBlockInfoBase (Object)
1072 The common information that applies to all full disk encryption formats
1074 Members:
1076 "format: QCryptoBlockFormat"
1078 the encryption format
1079 Since: 2.7
1081 QCryptoBlockInfoLUKSSlot (Object)
1083 Information about the LUKS block encryption key slot options
1085 Members:
1087 "active: boolean"
1089 whether the key slot is currently in use
1090 "key-offset: int"
1092 offset to the key material in bytes
1093 "iters: int" (optional)
1095 number of PBKDF2 iterations for key material
1096 "stripes: int" (optional)
1098 number of stripes for splitting key material
1099 Since: 2.7
1101 QCryptoBlockInfoLUKS (Object)
1103 Information about the LUKS block encryption options
1105 Members:
1107 "cipher-alg: QCryptoCipherAlgorithm"
1109 the cipher algorithm for data encryption
1110 "cipher-mode: QCryptoCipherMode"
1112 the cipher mode for data encryption
1113 "ivgen-alg: QCryptoIVGenAlgorithm"
1115 the initialization vector generator
1116 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1118 the initialization vector generator hash
1119 "hash-alg: QCryptoHashAlgorithm"
1121 the master key hash algorithm
1122 "payload-offset: int"
1124 offset to the payload data in bytes
1125 "master-key-iters: int"
1127 number of PBKDF2 iterations for key material
1128 "uuid: string"
1130 unique identifier for the volume
1131 "slots: array of QCryptoBlockInfoLUKSSlot"
1133 information about each key slot
1134 Since: 2.7
1136 QCryptoBlockInfo (Object)
1138 Information about the block encryption options
1140 Members:
1142 The members of "QCryptoBlockInfoBase"
1144 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1145 Since: 2.7
1147 Block devices
1149 Block core (VM unrelated)
1150 Background jobs
1152 JobType (Enum)
1154 Type of a background job.
1156 Values:
1158 "commit"
1160 block commit job type, see "block-commit"
1161 "stream"
1163 block stream job type, see "block-stream"
1164 "mirror"
1166 drive mirror job type, see "drive-mirror"
1167 "backup"
1169 drive backup job type, see "drive-backup"
1170 "create"
1172 image creation job type, see "blockdev-create" (since 3.0)
1173 Since: 1.7
1175 JobStatus (Enum)
1177 Indicates the present state of a given job in its lifetime.
1179 Values:
1181 "undefined"
1183 Erroneous, default state. Should not ever be visible.
1184 "created"
1186 The job has been created, but not yet started.
1187 "running"
1189 The job is currently running.
1190 "paused"
1192 The job is running, but paused. The pause may be requested by
1193 either the QMP user or by internal processes.
1194 "ready"
1196 The job is running, but is ready for the user to signal completion.
1197 This is used for long-running jobs like mirror that are designed to
1198 run indefinitely.
1199 "standby"
1201 The job is ready, but paused. This is nearly identical to "paused".
1202 The job may return to "ready" or otherwise be canceled.
1203 "waiting"
1205 The job is waiting for other jobs in the transaction to converge to
1206 the waiting state. This status will likely not be visible for the
1207 last job in a transaction.
1208 "pending"
1210 The job has finished its work, but has finalization steps that it
1211 needs to make prior to completing. These changes will require
1212 manual intervention via "job-finalize" if auto-finalize was set to
1213 false. These pending changes may still fail.
1214 "aborting"
1216 The job is in the process of being aborted, and will finish with an
1217 error. The job will afterwards report that it is "concluded". This
1218 status may not be visible to the management process.
1219 "concluded"
1221 The job has finished all work. If auto-dismiss was set to false,
1222 the job will remain in the query list until it is dismissed via
1223 "job-dismiss".
1224 "null"
1226 The job is in the process of being dismantled. This state should
1227 not ever be visible externally.
1228 Since: 2.12
1230 JobVerb (Enum)
1232 Represents command verbs that can be applied to a job.
1234 Values:
1236 "cancel"
1238 see "job-cancel"
1239 "pause"
1241 see "job-pause"
1242 "resume"
1244 see "job-resume"
1245 "set-speed"
1247 see "block-job-set-speed"
1248 "complete"
1250 see "job-complete"
1251 "dismiss"
1253 see "job-dismiss"
1254 "finalize"
1256 see "job-finalize"
1257 Since: 2.12
1259 JOB_STATUS_CHANGE (Event) Emitted when a job transitions to a
1261 different status.
1262 Arguments:
1264 "id: string"
1266 The job identifier
1267 "status: JobStatus"
1269 The new job status
1270 Since: 3.0
1272 job-pause (Command) Pause an active job.
1274 This command returns immediately after marking the active job for
1276 pausing. Pausing an already paused job is an error.
1277 The job will pause as soon as possible, which means transitioning into
1279 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1280 The corresponding JOB_STATUS_CHANGE event will be emitted.
1281 Cancelling a paused job automatically resumes it.
1283 Arguments:
1285 "id: string"
1287 The job identifier.
1288 Since: 3.0
1290 job-resume (Command) Resume a paused job.
1292 This command returns immediately after resuming a paused job. Resuming
1294 an already running job is an error.
1295 "id" : The job identifier.
1297 Arguments:
1299 "id: string"
1301 Not documented
1302 Since: 3.0
1304 job-cancel (Command) Instruct an active background job to cancel at
1306 the next opportunity. This command returns immediately after marking
1307 the active job for cancellation.
1308 The job will cancel as soon as possible and then emit a
1310 JOB_STATUS_CHANGE event. Usually, the status will change to ABORTING,
1311 but it is possible that a job successfully completes (e.g. because it
1312 was almost done and there was no opportunity to cancel earlier than
1313 completing the job) and transitions to PENDING instead.
1314 Arguments:
1316 "id: string"
1318 The job identifier.
1319 Since: 3.0
1321 job-complete (Command) Manually trigger completion of an active job in
1323 the READY state.
1324 Arguments:
1326 "id: string"
1328 The job identifier.
1329 Since: 3.0
1331 job-dismiss (Command) Deletes a job that is in the CONCLUDED state.
1333 This command only needs to be run explicitly for jobs that don't have
1334 automatic dismiss enabled.
1335 This command will refuse to operate on any job that has not yet reached
1337 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1338 JOB_READY event, job-cancel or job-complete will still need to be used
1339 as appropriate.
1340 Arguments:
1342 "id: string"
1344 The job identifier.
1345 Since: 3.0
1347 job-finalize (Command) Instructs all jobs in a transaction (or a
1349 single job if it is not part of any transaction) to finalize any graph
1350 changes and do any necessary cleanup. This command requires that all
1351 involved jobs are in the PENDING state.
1352 For jobs in a transaction, instructing one job to finalize will force
1354 ALL jobs in the transaction to finalize, so it is only necessary to
1355 instruct a single member job to finalize.
1356 Arguments:
1358 "id: string"
1360 The identifier of any job in the transaction, or of a job that is
1361 not part of any transaction.
1362 Since: 3.0
1364 JobInfo (Object)
1366 Information about a job.
1368 Members:
1370 "id: string"
1372 The job identifier
1373 "type: JobType"
1375 The kind of job that is being performed
1376 "status: JobStatus"
1378 Current job state/status
1379 "current-progress: int"
1381 Progress made until now. The unit is arbitrary and the value can
1382 only meaningfully be used for the ratio of "current-progress" to
1383 "total-progress". The value is monotonically increasing.
1384 "total-progress: int"
1386 Estimated "current-progress" value at the completion of the job.
1387 This value can arbitrarily change while the job is running, in both
1388 directions.
1389 "error: string" (optional)
1391 If this field is present, the job failed; if it is still missing in
1392 the CONCLUDED state, this indicates successful completion.
1393 The value is a human-readable error message to describe the reason
1395 for the job failure. It should not be parsed by applications.
1396 Since: 3.0
1398 query-jobs (Command) Return information about jobs.
1400 Returns: a list with a "JobInfo" for each active job
1402 Since: 3.0
1404 SnapshotInfo (Object)
1406 Members:
1408 "id: string"
1410 unique snapshot id
1411 "name: string"
1413 user chosen name
1414 "vm-state-size: int"
1416 size of the VM state
1417 "date-sec: int"
1419 UTC date of the snapshot in seconds
1420 "date-nsec: int"
1422 fractional part in nano seconds to be used with date-sec
1423 "vm-clock-sec: int"
1425 VM clock relative to boot in seconds
1426 "vm-clock-nsec: int"
1428 fractional part in nano seconds to be used with vm-clock-sec
1429 Since: 1.3
1431 ImageInfoSpecificQCow2EncryptionBase (Object)
1433 Members:
1435 "format: BlockdevQcow2EncryptionFormat"
1437 The encryption format
1438 Since: 2.10
1440 ImageInfoSpecificQCow2Encryption (Object)
1442 Members:
1444 The members of "ImageInfoSpecificQCow2EncryptionBase"
1446 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1447 Since: 2.10
1449 ImageInfoSpecificQCow2 (Object)
1451 Members:
1453 "compat: string"
1455 compatibility level
1456 "data-file: string" (optional)
1458 the filename of the external data file that is stored in the image
1459 and used as a default for opening the image (since: 4.0)
1460 "data-file-raw: boolean" (optional)
1462 True if the external data file must stay valid as a standalone
1463 (read-only) raw image without looking at qcow2 metadata (since:
1464 4.0)
1465 "lazy-refcounts: boolean" (optional)
1467 on or off; only valid for compat >= 1.1
1468 "corrupt: boolean" (optional)
1470 true if the image has been marked corrupt; only valid for compat >=
1471 1.1 (since 2.2)
1472 "refcount-bits: int"
1474 width of a refcount entry in bits (since 2.3)
1475 "encrypt: ImageInfoSpecificQCow2Encryption" (optional)
1477 details about encryption parameters; only set if image is encrypted
1478 (since 2.10)
1479 "bitmaps: array of Qcow2BitmapInfo" (optional)
1481 A list of qcow2 bitmap details (since 4.0)
1482 Since: 1.7
1484 ImageInfoSpecificVmdk (Object)
1486 Members:
1488 "create-type: string"
1490 The create type of VMDK image
1491 "cid: int"
1493 Content id of image
1494 "parent-cid: int"
1496 Parent VMDK image's cid
1497 "extents: array of ImageInfo"
1499 List of extent files
1500 Since: 1.7
1502 ImageInfoSpecific (Object)
1504 A discriminated record of image format specific information structures.
1506 Members:
1508 "type"
1510 One of "qcow2", "vmdk", "luks"
1511 "data: ImageInfoSpecificQCow2" when "type" is "qcow2"
1513 "data: ImageInfoSpecificVmdk" when "type" is "vmdk"
1514 "data: QCryptoBlockInfoLUKS" when "type" is "luks"
1515 Since: 1.7
1517 ImageInfo (Object)
1519 Information about a QEMU image file
1521 Members:
1523 "filename: string"
1525 name of the image file
1526 "format: string"
1528 format of the image file
1529 "virtual-size: int"
1531 maximum capacity in bytes of the image
1532 "actual-size: int" (optional)
1534 actual size on disk in bytes of the image
1535 "dirty-flag: boolean" (optional)
1537 true if image is not cleanly closed
1538 "cluster-size: int" (optional)
1540 size of a cluster in bytes
1541 "encrypted: boolean" (optional)
1543 true if the image is encrypted
1544 "compressed: boolean" (optional)
1546 true if the image is compressed (Since 1.7)
1547 "backing-filename: string" (optional)
1549 name of the backing file
1550 "full-backing-filename: string" (optional)
1552 full path of the backing file
1553 "backing-filename-format: string" (optional)
1555 the format of the backing file
1556 "snapshots: array of SnapshotInfo" (optional)
1558 list of VM snapshots
1559 "backing-image: ImageInfo" (optional)
1561 info of the backing image (since 1.6)
1562 "format-specific: ImageInfoSpecific" (optional)
1564 structure supplying additional format-specific information (since
1565 1.7)
1566 Since: 1.3
1568 ImageCheck (Object)
1570 Information about a QEMU image file check
1572 Members:
1574 "filename: string"
1576 name of the image file checked
1577 "format: string"
1579 format of the image file checked
1580 "check-errors: int"
1582 number of unexpected errors occurred during check
1583 "image-end-offset: int" (optional)
1585 offset (in bytes) where the image ends, this field is present if
1586 the driver for the image format supports it
1587 "corruptions: int" (optional)
1589 number of corruptions found during the check if any
1590 "leaks: int" (optional)
1592 number of leaks found during the check if any
1593 "corruptions-fixed: int" (optional)
1595 number of corruptions fixed during the check if any
1596 "leaks-fixed: int" (optional)
1598 number of leaks fixed during the check if any
1599 "total-clusters: int" (optional)
1601 total number of clusters, this field is present if the driver for
1602 the image format supports it
1603 "allocated-clusters: int" (optional)
1605 total number of allocated clusters, this field is present if the
1606 driver for the image format supports it
1607 "fragmented-clusters: int" (optional)
1609 total number of fragmented clusters, this field is present if the
1610 driver for the image format supports it
1611 "compressed-clusters: int" (optional)
1613 total number of compressed clusters, this field is present if the
1614 driver for the image format supports it
1615 Since: 1.4
1617 MapEntry (Object)
1619 Mapping information from a virtual block range to a host file range
1621 Members:
1623 "start: int"
1625 the start byte of the mapped virtual range
1626 "length: int"
1628 the number of bytes of the mapped virtual range
1629 "data: boolean"
1631 whether the mapped range has data
1632 "zero: boolean"
1634 whether the virtual blocks are zeroed
1635 "depth: int"
1637 the depth of the mapping
1638 "offset: int" (optional)
1640 the offset in file that the virtual sectors are mapped to
1641 "filename: string" (optional)
1643 filename that is referred to by "offset"
1644 Since: 2.6
1646 BlockdevCacheInfo (Object)
1648 Cache mode information for a block device
1650 Members:
1652 "writeback: boolean"
1654 true if writeback mode is enabled
1655 "direct: boolean"
1657 true if the host page cache is bypassed (O_DIRECT)
1658 "no-flush: boolean"
1660 true if flush requests are ignored for the device
1661 Since: 2.3
1663 BlockDeviceInfo (Object)
1665 Information about the backing device for a block device.
1667 Members:
1669 "file: string"
1671 the filename of the backing device
1672 "node-name: string" (optional)
1674 the name of the block driver node (Since 2.0)
1675 "ro: boolean"
1677 true if the backing device was open read-only
1678 "drv: string"
1680 the name of the block format used to open the backing device. As of
1681 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
1682 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', 'http',
1683 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2', 'raw', 'vdi',
1684 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added, 'cow' dropped 2.3:
1685 'host_floppy' deprecated 2.5: 'host_floppy' dropped 2.6: 'luks'
1686 added 2.8: 'replication' added, 'tftp' dropped 2.9: 'archipelago'
1687 dropped
1688 "backing_file: string" (optional)
1690 the name of the backing file (for copy-on-write)
1691 "backing_file_depth: int"
1693 number of files in the backing file chain (since: 1.2)
1694 "encrypted: boolean"
1696 true if the backing device is encrypted
1697 "encryption_key_missing: boolean"
1699 Deprecated; always false
1700 "detect_zeroes: BlockdevDetectZeroesOptions"
1702 detect and optimize zero writes (Since 2.1)
1703 "bps: int"
1705 total throughput limit in bytes per second is specified
1706 "bps_rd: int"
1708 read throughput limit in bytes per second is specified
1709 "bps_wr: int"
1711 write throughput limit in bytes per second is specified
1712 "iops: int"
1714 total I/O operations per second is specified
1715 "iops_rd: int"
1717 read I/O operations per second is specified
1718 "iops_wr: int"
1720 write I/O operations per second is specified
1721 "image: ImageInfo"
1723 the info of image used (since: 1.6)
1724 "bps_max: int" (optional)
1726 total throughput limit during bursts, in bytes (Since 1.7)
1727 "bps_rd_max: int" (optional)
1729 read throughput limit during bursts, in bytes (Since 1.7)
1730 "bps_wr_max: int" (optional)
1732 write throughput limit during bursts, in bytes (Since 1.7)
1733 "iops_max: int" (optional)
1735 total I/O operations per second during bursts, in bytes (Since 1.7)
1736 "iops_rd_max: int" (optional)
1738 read I/O operations per second during bursts, in bytes (Since 1.7)
1739 "iops_wr_max: int" (optional)
1741 write I/O operations per second during bursts, in bytes (Since 1.7)
1742 "bps_max_length: int" (optional)
1744 maximum length of the "bps_max" burst period, in seconds. (Since
1745 2.6)
1746 "bps_rd_max_length: int" (optional)
1748 maximum length of the "bps_rd_max" burst period, in seconds. (Since
1749 2.6)
1750 "bps_wr_max_length: int" (optional)
1752 maximum length of the "bps_wr_max" burst period, in seconds. (Since
1753 2.6)
1754 "iops_max_length: int" (optional)
1756 maximum length of the "iops" burst period, in seconds. (Since 2.6)
1757 "iops_rd_max_length: int" (optional)
1759 maximum length of the "iops_rd_max" burst period, in seconds.
1760 (Since 2.6)
1761 "iops_wr_max_length: int" (optional)
1763 maximum length of the "iops_wr_max" burst period, in seconds.
1764 (Since 2.6)
1765 "iops_size: int" (optional)
1767 an I/O size in bytes (Since 1.7)
1768 "group: string" (optional)
1770 throttle group name (Since 2.4)
1771 "cache: BlockdevCacheInfo"
1773 the cache mode used for the block device (since: 2.3)
1774 "write_threshold: int"
1776 configured write threshold for the device. 0 if disabled. (Since
1777 2.3)
1778 "dirty-bitmaps: array of BlockDirtyInfo" (optional)
1780 dirty bitmaps information (only present if node has one or more
1781 dirty bitmaps) (Since 4.2)
1782 Since: 0.14.0
1784 BlockDeviceIoStatus (Enum)
1786 An enumeration of block device I/O status.
1788 Values:
1790 "ok"
1792 The last I/O operation has succeeded
1793 "failed"
1795 The last I/O operation has failed
1796 "nospace"
1798 The last I/O operation has failed due to a no-space condition
1799 Since: 1.0
1801 BlockDeviceMapEntry (Object)
1803 Entry in the metadata map of the device (returned by "qemu-img map")
1805 Members:
1807 "start: int"
1809 Offset in the image of the first byte described by this entry (in
1810 bytes)
1811 "length: int"
1813 Length of the range described by this entry (in bytes)
1814 "depth: int"
1816 Number of layers (0 = top image, 1 = top image's backing file,
1817 etc.) before reaching one for which the range is allocated. The
1818 value is in the range 0 to the depth of the image chain - 1.
1819 "zero: boolean"
1821 the sectors in this range read as zeros
1822 "data: boolean"
1824 reading the image will actually read data from a file (in
1825 particular, if "offset" is present this means that the sectors are
1826 not simply preallocated, but contain actual data in raw format)
1827 "offset: int" (optional)
1829 if present, the image file stores the data for this range in raw
1830 format at the given offset.
1831 Since: 1.7
1833 DirtyBitmapStatus (Enum)
1835 An enumeration of possible states that a dirty bitmap can report to the
1837 user.
1838 Values:
1840 "frozen"
1842 The bitmap is currently in-use by some operation and is immutable.
1843 If the bitmap was "active" prior to the operation, new writes by
1844 the guest are being recorded in a temporary buffer, and will not be
1845 lost. Generally, bitmaps are cleared on successful use in an
1846 operation and the temporary buffer is committed into the bitmap. On
1847 failure, the temporary buffer is merged back into the bitmap
1848 without first clearing it. Please refer to the documentation for
1849 each bitmap-using operation, See also "blockdev-backup",
1850 "drive-backup".
1851 "disabled"
1853 The bitmap is not currently recording new writes by the guest.
1854 This is requested explicitly via "block-dirty-bitmap-disable". It
1855 can still be cleared, deleted, or used for backup operations.
1856 "active"
1858 The bitmap is actively monitoring for new writes, and can be
1859 cleared, deleted, or used for backup operations.
1860 "locked"
1862 The bitmap is currently in-use by some operation and is immutable.
1863 If the bitmap was "active" prior to the operation, it is still
1864 recording new writes. If the bitmap was "disabled", it is not
1865 recording new writes. (Since 2.12)
1866 "inconsistent"
1868 This is a persistent dirty bitmap that was marked in-use on disk,
1869 and is unusable by QEMU. It can only be deleted. Please rely on
1870 the inconsistent field in "BlockDirtyInfo" instead, as the status
1871 field is deprecated. (Since 4.0)
1872 Since: 2.4
1874 BlockDirtyInfo (Object)
1876 Block dirty bitmap information.
1878 Members:
1880 "name: string" (optional)
1882 the name of the dirty bitmap (Since 2.4)
1883 "count: int"
1885 number of dirty bytes according to the dirty bitmap
1886 "granularity: int"
1888 granularity of the dirty bitmap in bytes (since 1.4)
1889 "status: DirtyBitmapStatus"
1891 Deprecated in favor of "recording" and "locked". (since 2.4)
1892 "recording: boolean"
1894 true if the bitmap is recording new writes from the guest.
1895 Replaces `active` and `disabled` statuses. (since 4.0)
1896 "busy: boolean"
1898 true if the bitmap is in-use by some operation (NBD or jobs) and
1899 cannot be modified via QMP or used by another operation. Replaces
1900 `locked` and `frozen` statuses. (since 4.0)
1901 "persistent: boolean"
1903 true if the bitmap was stored on disk, is scheduled to be stored on
1904 disk, or both. (since 4.0)
1905 "inconsistent: boolean" (optional)
1907 true if this is a persistent bitmap that was improperly stored.
1908 Implies "persistent" to be true; "recording" and "busy" to be
1909 false. This bitmap cannot be used. To remove it, use
1910 "block-dirty-bitmap-remove". (Since 4.0)
1911 Since: 1.3
1913 Qcow2BitmapInfoFlags (Enum)
1915 An enumeration of flags that a bitmap can report to the user.
1917 Values:
1919 "in-use"
1921 This flag is set by any process actively modifying the qcow2 file,
1922 and cleared when the updated bitmap is flushed to the qcow2 image.
1923 The presence of this flag in an offline image means that the bitmap
1924 was not saved correctly after its last usage, and may contain
1925 inconsistent data.
1926 "auto"
1928 The bitmap must reflect all changes of the virtual disk by any
1929 application that would write to this qcow2 file.
1930 Since: 4.0
1932 Qcow2BitmapInfo (Object)
1934 Qcow2 bitmap information.
1936 Members:
1938 "name: string"
1940 the name of the bitmap
1941 "granularity: int"
1943 granularity of the bitmap in bytes
1944 "flags: array of Qcow2BitmapInfoFlags"
1946 flags of the bitmap
1947 Since: 4.0
1949 BlockLatencyHistogramInfo (Object)
1951 Block latency histogram.
1953 Members:
1955 "boundaries: array of int"
1957 list of interval boundary values in nanoseconds, all greater than
1958 zero and in ascending order. For example, the list [10, 50, 100]
1959 produces the following histogram intervals: [0, 10), [10, 50), [50,
1960 100), [100, +inf).
1961 "bins: array of int"
1963 list of io request counts corresponding to histogram intervals.
1964 len("bins") = len("boundaries") + 1 For the example above, "bins"
1965 may be something like [3, 1, 5, 2], and corresponding histogram
1966 looks like:
1967 5| * 4| * 3| 2| * 1|
1969 +------------------ 10 50 100
1970 Since: 4.0
1972 block-latency-histogram-set (Command) Manage read, write and flush
1974 latency histograms for the device.
1975 If only "id" parameter is specified, remove all present latency
1977 histograms for the device. Otherwise, add/reset some of (or all)
1978 latency histograms.
1979 Arguments:
1981 "id: string"
1983 The name or QOM path of the guest device.
1984 "boundaries: array of int" (optional)
1986 list of interval boundary values (see description in
1987 BlockLatencyHistogramInfo definition). If specified, all latency
1988 histograms are removed, and empty ones created for all io types
1989 with intervals corresponding to "boundaries" (except for io types,
1990 for which specific boundaries are set through the following
1991 parameters).
1992 "boundaries-read: array of int" (optional)
1994 list of interval boundary values for read latency histogram. If
1995 specified, old read latency histogram is removed, and empty one
1996 created with intervals corresponding to "boundaries-read". The
1997 parameter has higher priority then "boundaries".
1998 "boundaries-write: array of int" (optional)
2000 list of interval boundary values for write latency histogram.
2001 "boundaries-flush: array of int" (optional)
2003 list of interval boundary values for flush latency histogram.
2004 Returns: error if device is not found or any boundary arrays are
2006 invalid.
2007 Since: 4.0
2009 Example:
2011 set new histograms for all io types with intervals
2013 [0, 10), [10, 50), [50, 100), [100, +inf):
2014 -> { "execute": "block-latency-histogram-set",
2016 "arguments": { "id": "drive0",
2017 "boundaries": [10, 50, 100] } }
2018 <- { "return": {} }
2019 Example:
2021 set new histogram only for write, other histograms will remain
2023 not changed (or not created):
2024 -> { "execute": "block-latency-histogram-set",
2026 "arguments": { "id": "drive0",
2027 "boundaries-write": [10, 50, 100] } }
2028 <- { "return": {} }
2029 Example:
2031 set new histograms with the following intervals:
2033 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
2034 write: [0, 1000), [1000, 5000), [5000, +inf)
2035 -> { "execute": "block-latency-histogram-set",
2037 "arguments": { "id": "drive0",
2038 "boundaries": [10, 50, 100],
2039 "boundaries-write": [1000, 5000] } }
2040 <- { "return": {} }
2041 Example:
2043 remove all latency histograms:
2045 -> { "execute": "block-latency-histogram-set",
2047 "arguments": { "id": "drive0" } }
2048 <- { "return": {} }
2049 BlockInfo (Object)
2051 Block device information. This structure describes a virtual device
2053 and the backing device associated with it.
2054 Members:
2056 "device: string"
2058 The device name associated with the virtual device.
2059 "qdev: string" (optional)
2061 The qdev ID, or if no ID is assigned, the QOM path of the block
2062 device. (since 2.10)
2063 "type: string"
2065 This field is returned only for compatibility reasons, it should
2066 not be used (always returns 'unknown')
2067 "removable: boolean"
2069 True if the device supports removable media.
2070 "locked: boolean"
2072 True if the guest has locked this device from having its media
2073 removed
2074 "tray_open: boolean" (optional)
2076 True if the device's tray is open (only present if it has a tray)
2077 "dirty-bitmaps: array of BlockDirtyInfo" (optional)
2079 dirty bitmaps information (only present if the driver has one or
2080 more dirty bitmaps) (Since 2.0) Deprecated in 4.2; see
2081 BlockDeviceInfo instead.
2082 "io-status: BlockDeviceIoStatus" (optional)
2084 "BlockDeviceIoStatus". Only present if the device supports it and
2085 the VM is configured to stop on errors (supported device models:
2086 virtio-blk, IDE, SCSI except scsi-generic)
2087 "inserted: BlockDeviceInfo" (optional)
2089 "BlockDeviceInfo" describing the device if media is present
2090 Since: 0.14.0
2092 BlockMeasureInfo (Object)
2094 Image file size calculation information. This structure describes the
2096 size requirements for creating a new image file.
2097 The size requirements depend on the new image file format. File size
2099 always equals virtual disk size for the 'raw' format, even for sparse
2100 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2101 zero regions efficiently so file size may be smaller than virtual disk
2102 size.
2103 The values are upper bounds that are guaranteed to fit the new image
2105 file. Subsequent modification, such as internal snapshot or bitmap
2106 creation, may require additional space and is not covered here.
2107 Members:
2109 "required: int"
2111 Size required for a new image file, in bytes.
2112 "fully-allocated: int"
2114 Image file size, in bytes, once data has been written to all
2115 sectors.
2116 Since: 2.10
2118 query-block (Command) Get a list of BlockInfo for all virtual block
2120 devices.
2121 Returns: a list of "BlockInfo" describing each virtual block device.
2123 Filter nodes that were created implicitly are skipped over.
2124 Since: 0.14.0
2126 Example:
2128 -> { "execute": "query-block" }
2130 <- {
2131 "return":[
2132 {
2133 "io-status": "ok",
2134 "device":"ide0-hd0",
2135 "locked":false,
2136 "removable":false,
2137 "inserted":{
2138 "ro":false,
2139 "drv":"qcow2",
2140 "encrypted":false,
2141 "file":"disks/test.qcow2",
2142 "backing_file_depth":1,
2143 "bps":1000000,
2144 "bps_rd":0,
2145 "bps_wr":0,
2146 "iops":1000000,
2147 "iops_rd":0,
2148 "iops_wr":0,
2149 "bps_max": 8000000,
2150 "bps_rd_max": 0,
2151 "bps_wr_max": 0,
2152 "iops_max": 0,
2153 "iops_rd_max": 0,
2154 "iops_wr_max": 0,
2155 "iops_size": 0,
2156 "detect_zeroes": "on",
2157 "write_threshold": 0,
2158 "image":{
2159 "filename":"disks/test.qcow2",
2160 "format":"qcow2",
2161 "virtual-size":2048000,
2162 "backing_file":"base.qcow2",
2163 "full-backing-filename":"disks/base.qcow2",
2164 "backing-filename-format":"qcow2",
2165 "snapshots":[
2166 {
2167 "id": "1",
2168 "name": "snapshot1",
2169 "vm-state-size": 0,
2170 "date-sec": 10000200,
2171 "date-nsec": 12,
2172 "vm-clock-sec": 206,
2173 "vm-clock-nsec": 30
2174 }
2175 ],
2176 "backing-image":{
2177 "filename":"disks/base.qcow2",
2178 "format":"qcow2",
2179 "virtual-size":2048000
2180 }
2181 }
2182 },
2183 "qdev": "ide_disk",
2184 "type":"unknown"
2185 },
2186 {
2187 "io-status": "ok",
2188 "device":"ide1-cd0",
2189 "locked":false,
2190 "removable":true,
2191 "qdev": "/machine/unattached/device[23]",
2192 "tray_open": false,
2193 "type":"unknown"
2194 },
2195 {
2196 "device":"floppy0",
2197 "locked":false,
2198 "removable":true,
2199 "qdev": "/machine/unattached/device[20]",
2200 "type":"unknown"
2201 },
2202 {
2203 "device":"sd0",
2204 "locked":false,
2205 "removable":true,
2206 "type":"unknown"
2207 }
2208 ]
2209 }
2210 BlockDeviceTimedStats (Object)
2212 Statistics of a block device during a given interval of time.
2214 Members:
2216 "interval_length: int"
2218 Interval used for calculating the statistics, in seconds.
2219 "min_rd_latency_ns: int"
2221 Minimum latency of read operations in the defined interval, in
2222 nanoseconds.
2223 "min_wr_latency_ns: int"
2225 Minimum latency of write operations in the defined interval, in
2226 nanoseconds.
2227 "min_flush_latency_ns: int"
2229 Minimum latency of flush operations in the defined interval, in
2230 nanoseconds.
2231 "max_rd_latency_ns: int"
2233 Maximum latency of read operations in the defined interval, in
2234 nanoseconds.
2235 "max_wr_latency_ns: int"
2237 Maximum latency of write operations in the defined interval, in
2238 nanoseconds.
2239 "max_flush_latency_ns: int"
2241 Maximum latency of flush operations in the defined interval, in
2242 nanoseconds.
2243 "avg_rd_latency_ns: int"
2245 Average latency of read operations in the defined interval, in
2246 nanoseconds.
2247 "avg_wr_latency_ns: int"
2249 Average latency of write operations in the defined interval, in
2250 nanoseconds.
2251 "avg_flush_latency_ns: int"
2253 Average latency of flush operations in the defined interval, in
2254 nanoseconds.
2255 "avg_rd_queue_depth: number"
2257 Average number of pending read operations in the defined interval.
2258 "avg_wr_queue_depth: number"
2260 Average number of pending write operations in the defined interval.
2261 Since: 2.5
2263 BlockDeviceStats (Object)
2265 Statistics of a virtual block device or a block backing device.
2267 Members:
2269 "rd_bytes: int"
2271 The number of bytes read by the device.
2272 "wr_bytes: int"
2274 The number of bytes written by the device.
2275 "unmap_bytes: int"
2277 The number of bytes unmapped by the device (Since 4.2)
2278 "rd_operations: int"
2280 The number of read operations performed by the device.
2281 "wr_operations: int"
2283 The number of write operations performed by the device.
2284 "flush_operations: int"
2286 The number of cache flush operations performed by the device (since
2287 0.15.0)
2288 "unmap_operations: int"
2290 The number of unmap operations performed by the device (Since 4.2)
2291 "rd_total_time_ns: int"
2293 Total time spent on reads in nanoseconds (since 0.15.0).
2294 "wr_total_time_ns: int"
2296 Total time spent on writes in nanoseconds (since 0.15.0).
2297 "flush_total_time_ns: int"
2299 Total time spent on cache flushes in nanoseconds (since 0.15.0).
2300 "unmap_total_time_ns: int"
2302 Total time spent on unmap operations in nanoseconds (Since 4.2)
2303 "wr_highest_offset: int"
2305 The offset after the greatest byte written to the device. The
2306 intended use of this information is for growable sparse files (like
2307 qcow2) that are used on top of a physical device.
2308 "rd_merged: int"
2310 Number of read requests that have been merged into another request
2311 (Since 2.3).
2312 "wr_merged: int"
2314 Number of write requests that have been merged into another request
2315 (Since 2.3).
2316 "unmap_merged: int"
2318 Number of unmap requests that have been merged into another request
2319 (Since 4.2)
2320 "idle_time_ns: int" (optional)
2322 Time since the last I/O operation, in nanoseconds. If the field is
2323 absent it means that there haven't been any operations yet (Since
2324 2.5).
2325 "failed_rd_operations: int"
2327 The number of failed read operations performed by the device (Since
2328 2.5)
2329 "failed_wr_operations: int"
2331 The number of failed write operations performed by the device
2332 (Since 2.5)
2333 "failed_flush_operations: int"
2335 The number of failed flush operations performed by the device
2336 (Since 2.5)
2337 "failed_unmap_operations: int"
2339 The number of failed unmap operations performed by the device
2340 (Since 4.2)
2341 "invalid_rd_operations: int"
2343 The number of invalid read operations performed by the device
2344 (Since 2.5)
2345 "invalid_wr_operations: int"
2347 The number of invalid write operations performed by the device
2348 (Since 2.5)
2349 "invalid_flush_operations: int"
2351 The number of invalid flush operations performed by the device
2352 (Since 2.5)
2353 "invalid_unmap_operations: int"
2355 The number of invalid unmap operations performed by the device
2356 (Since 4.2)
2357 "account_invalid: boolean"
2359 Whether invalid operations are included in the last access
2360 statistics (Since 2.5)
2361 "account_failed: boolean"
2363 Whether failed operations are included in the latency and last
2364 access statistics (Since 2.5)
2365 "timed_stats: array of BlockDeviceTimedStats"
2367 Statistics specific to the set of previously defined intervals of
2368 time (Since 2.5)
2369 "rd_latency_histogram: BlockLatencyHistogramInfo" (optional)
2371 "BlockLatencyHistogramInfo". (Since 4.0)
2372 "wr_latency_histogram: BlockLatencyHistogramInfo" (optional)
2374 "BlockLatencyHistogramInfo". (Since 4.0)
2375 "flush_latency_histogram: BlockLatencyHistogramInfo" (optional)
2377 "BlockLatencyHistogramInfo". (Since 4.0)
2378 Since: 0.14.0
2380 BlockStatsSpecificFile (Object)
2382 File driver statistics
2384 Members:
2386 "discard-nb-ok: int"
2388 The number of successful discard operations performed by the
2389 driver.
2390 "discard-nb-failed: int"
2392 The number of failed discard operations performed by the driver.
2393 "discard-bytes-ok: int"
2395 The number of bytes discarded by the driver.
2396 Since: 4.2
2398 BlockStatsSpecific (Object)
2400 Block driver specific statistics
2402 Members:
2404 "driver: BlockdevDriver"
2406 Not documented
2407 The members of "BlockStatsSpecificFile" when "driver" is "file"
2409 The members of "BlockStatsSpecificFile" when "driver" is "host_device"
2410 Since: 4.2
2412 BlockStats (Object)
2414 Statistics of a virtual block device or a block backing device.
2416 Members:
2418 "device: string" (optional)
2420 If the stats are for a virtual block device, the name corresponding
2421 to the virtual block device.
2422 "node-name: string" (optional)
2424 The node name of the device. (Since 2.3)
2425 "qdev: string" (optional)
2427 The qdev ID, or if no ID is assigned, the QOM path of the block
2428 device. (since 3.0)
2429 "stats: BlockDeviceStats"
2431 A "BlockDeviceStats" for the device.
2432 "driver-specific: BlockStatsSpecific" (optional)
2434 Optional driver-specific stats. (Since 4.2)
2435 "parent: BlockStats" (optional)
2437 This describes the file block device if it has one. Contains
2438 recursively the statistics of the underlying protocol (e.g. the
2439 host file for a qcow2 image). If there is no underlying protocol,
2440 this field is omitted
2441 "backing: BlockStats" (optional)
2443 This describes the backing block device if it has one. (Since 2.0)
2444 Since: 0.14.0
2446 query-blockstats (Command) Query the "BlockStats" for all virtual
2448 block devices.
2449 Arguments:
2451 "query-nodes: boolean" (optional)
2453 If true, the command will query all the block nodes that have a
2454 node name, in a list which will include "parent" information, but
2455 not "backing". If false or omitted, the behavior is as before -
2456 query all the device backends, recursively including their "parent"
2457 and "backing". Filter nodes that were created implicitly are
2458 skipped over in this mode. (Since 2.3)
2459 Returns: A list of "BlockStats" for each virtual block devices.
2461 Since: 0.14.0
2463 Example:
2465 -> { "execute": "query-blockstats" }
2467 <- {
2468 "return":[
2469 {
2470 "device":"ide0-hd0",
2471 "parent":{
2472 "stats":{
2473 "wr_highest_offset":3686448128,
2474 "wr_bytes":9786368,
2475 "wr_operations":751,
2476 "rd_bytes":122567168,
2477 "rd_operations":36772
2478 "wr_total_times_ns":313253456
2479 "rd_total_times_ns":3465673657
2480 "flush_total_times_ns":49653
2481 "flush_operations":61,
2482 "rd_merged":0,
2483 "wr_merged":0,
2484 "idle_time_ns":2953431879,
2485 "account_invalid":true,
2486 "account_failed":false
2487 }
2488 },
2489 "stats":{
2490 "wr_highest_offset":2821110784,
2491 "wr_bytes":9786368,
2492 "wr_operations":692,
2493 "rd_bytes":122739200,
2494 "rd_operations":36604
2495 "flush_operations":51,
2496 "wr_total_times_ns":313253456
2497 "rd_total_times_ns":3465673657
2498 "flush_total_times_ns":49653,
2499 "rd_merged":0,
2500 "wr_merged":0,
2501 "idle_time_ns":2953431879,
2502 "account_invalid":true,
2503 "account_failed":false
2504 },
2505 "qdev": "/machine/unattached/device[23]"
2506 },
2507 {
2508 "device":"ide1-cd0",
2509 "stats":{
2510 "wr_highest_offset":0,
2511 "wr_bytes":0,
2512 "wr_operations":0,
2513 "rd_bytes":0,
2514 "rd_operations":0
2515 "flush_operations":0,
2516 "wr_total_times_ns":0
2517 "rd_total_times_ns":0
2518 "flush_total_times_ns":0,
2519 "rd_merged":0,
2520 "wr_merged":0,
2521 "account_invalid":false,
2522 "account_failed":false
2523 },
2524 "qdev": "/machine/unattached/device[24]"
2525 },
2526 {
2527 "device":"floppy0",
2528 "stats":{
2529 "wr_highest_offset":0,
2530 "wr_bytes":0,
2531 "wr_operations":0,
2532 "rd_bytes":0,
2533 "rd_operations":0
2534 "flush_operations":0,
2535 "wr_total_times_ns":0
2536 "rd_total_times_ns":0
2537 "flush_total_times_ns":0,
2538 "rd_merged":0,
2539 "wr_merged":0,
2540 "account_invalid":false,
2541 "account_failed":false
2542 },
2543 "qdev": "/machine/unattached/device[16]"
2544 },
2545 {
2546 "device":"sd0",
2547 "stats":{
2548 "wr_highest_offset":0,
2549 "wr_bytes":0,
2550 "wr_operations":0,
2551 "rd_bytes":0,
2552 "rd_operations":0
2553 "flush_operations":0,
2554 "wr_total_times_ns":0
2555 "rd_total_times_ns":0
2556 "flush_total_times_ns":0,
2557 "rd_merged":0,
2558 "wr_merged":0,
2559 "account_invalid":false,
2560 "account_failed":false
2561 }
2562 }
2563 ]
2564 }
2565 BlockdevOnError (Enum)
2567 An enumeration of possible behaviors for errors on I/O operations. The
2569 exact meaning depends on whether the I/O was initiated by a guest or by
2570 a block job
2571 Values:
2573 "report"
2575 for guest operations, report the error to the guest; for jobs,
2576 cancel the job
2577 "ignore"
2579 ignore the error, only report a QMP event (BLOCK_IO_ERROR or
2580 BLOCK_JOB_ERROR)
2581 "enospc"
2583 same as "stop" on ENOSPC, same as "report" otherwise.
2584 "stop"
2586 for guest operations, stop the virtual machine; for jobs, pause the
2587 job
2588 "auto"
2590 inherit the error handling policy of the backend (since: 2.7)
2591 Since: 1.3
2593 MirrorSyncMode (Enum)
2595 An enumeration of possible behaviors for the initial synchronization
2597 phase of storage mirroring.
2598 Values:
2600 "top"
2602 copies data in the topmost image to the destination
2603 "full"
2605 copies data from all images to the destination
2606 "none"
2608 only copy data written from now on
2609 "incremental"
2611 only copy data described by the dirty bitmap. (since: 2.4)
2612 "bitmap"
2614 only copy data described by the dirty bitmap. (since: 4.2) Behavior
2615 on completion is determined by the BitmapSyncMode.
2616 Since: 1.3
2618 BitmapSyncMode (Enum)
2620 An enumeration of possible behaviors for the synchronization of a
2622 bitmap when used for data copy operations.
2623 Values:
2625 "on-success"
2627 The bitmap is only synced when the operation is successful. This
2628 is the behavior always used for 'INCREMENTAL' backups.
2629 "never"
2631 The bitmap is never synchronized with the operation, and is treated
2632 solely as a read-only manifest of blocks to copy.
2633 "always"
2635 The bitmap is always synchronized with the operation, regardless of
2636 whether or not the operation was successful.
2637 Since: 4.2
2639 MirrorCopyMode (Enum)
2641 An enumeration whose values tell the mirror block job when to trigger
2643 writes to the target.
2644 Values:
2646 "background"
2648 copy data in background only.
2649 "write-blocking"
2651 when data is written to the source, write it (synchronously) to the
2652 target as well. In addition, data is copied in background just
2653 like in "background" mode.
2654 Since: 3.0
2656 BlockJobInfo (Object)
2658 Information about a long-running block device operation.
2660 Members:
2662 "type: string"
2664 the job type ('stream' for image streaming)
2665 "device: string"
2667 The job identifier. Originally the device name but other values are
2668 allowed since QEMU 2.7
2669 "len: int"
2671 Estimated "offset" value at the completion of the job. This value
2672 can arbitrarily change while the job is running, in both
2673 directions.
2674 "offset: int"
2676 Progress made until now. The unit is arbitrary and the value can
2677 only meaningfully be used for the ratio of "offset" to "len". The
2678 value is monotonically increasing.
2679 "busy: boolean"
2681 false if the job is known to be in a quiescent state, with no
2682 pending I/O. Since 1.3.
2683 "paused: boolean"
2685 whether the job is paused or, if "busy" is true, will pause itself
2686 as soon as possible. Since 1.3.
2687 "speed: int"
2689 the rate limit, bytes per second
2690 "io-status: BlockDeviceIoStatus"
2692 the status of the job (since 1.3)
2693 "ready: boolean"
2695 true if the job may be completed (since 2.2)
2696 "status: JobStatus"
2698 Current job state/status (since 2.12)
2699 "auto-finalize: boolean"
2701 Job will finalize itself when PENDING, moving to the CONCLUDED
2702 state. (since 2.12)
2703 "auto-dismiss: boolean"
2705 Job will dismiss itself when CONCLUDED, moving to the NULL state
2706 and disappearing from the query list. (since 2.12)
2707 "error: string" (optional)
2709 Error information if the job did not complete successfully. Not
2710 set if the job completed successfully. (since 2.12.1)
2711 Since: 1.1
2713 query-block-jobs (Command) Return information about long-running block
2715 device operations.
2716 Returns: a list of "BlockJobInfo" for each active block job
2718 Since: 1.1
2720 block_passwd (Command) This command sets the password of a block
2722 device that has not been open with a password and requires one.
2723 This command is now obsolete and will always return an error since 2.10
2725 Arguments:
2727 "device: string" (optional)
2729 Not documented
2730 "node-name: string" (optional)
2732 Not documented
2733 "password: string"
2735 Not documented
2736 block_resize (Command) Resize a block image while a guest is running.
2738 Either "device" or "node-name" must be set but not both.
2740 Arguments:
2742 "device: string" (optional)
2744 the name of the device to get the image resized
2745 "node-name: string" (optional)
2747 graph node name to get the image resized (Since 2.0)
2748 "size: int"
2750 new image size in bytes
2751 Returns: nothing on success If "device" is not a valid block device,
2753 DeviceNotFound
2754 Since: 0.14.0
2756 Example:
2758 -> { "execute": "block_resize",
2760 "arguments": { "device": "scratch", "size": 1073741824 } }
2761 <- { "return": {} }
2762 NewImageMode (Enum)
2764 An enumeration that tells QEMU how to set the backing file path in a
2766 new image file.
2767 Values:
2769 "existing"
2771 QEMU should look for an existing image file.
2772 "absolute-paths"
2774 QEMU should create a new image with absolute paths for the backing
2775 file. If there is no backing file available, the new image will not
2776 be backed either.
2777 Since: 1.1
2779 BlockdevSnapshotSync (Object)
2781 Either "device" or "node-name" must be set but not both.
2783 Members:
2785 "device: string" (optional)
2787 the name of the device to take a snapshot of.
2788 "node-name: string" (optional)
2790 graph node name to generate the snapshot from (Since 2.0)
2791 "snapshot-file: string"
2793 the target of the new overlay image. If the file exists, or if it
2794 is a device, the overlay will be created in the existing
2795 file/device. Otherwise, a new file will be created.
2796 "snapshot-node-name: string" (optional)
2798 the graph node name of the new image (Since 2.0)
2799 "format: string" (optional)
2801 the format of the overlay image, default is 'qcow2'.
2802 "mode: NewImageMode" (optional)
2804 whether and how QEMU should create a new image, default is
2805 'absolute-paths'.
2806 BlockdevSnapshot (Object)
2808 Members:
2810 "node: string"
2812 device or node name that will have a snapshot taken.
2813 "overlay: string"
2815 reference to the existing block device that will become the overlay
2816 of "node", as part of taking the snapshot. It must not have a
2817 current backing file (this can be achieved by passing "backing":
2818 null to blockdev-add).
2819 Since: 2.5
2821 BackupCommon (Object)
2823 Members:
2825 "job-id: string" (optional)
2827 identifier for the newly-created block job. If omitted, the device
2828 name will be used. (Since 2.7)
2829 "device: string"
2831 the device name or node-name of a root node which should be copied.
2832 "sync: MirrorSyncMode"
2834 what parts of the disk image should be copied to the destination
2835 (all the disk, only the sectors allocated in the topmost image,
2836 from a dirty bitmap, or only new I/O).
2837 "speed: int" (optional)
2839 the maximum speed, in bytes per second. The default is 0, for
2840 unlimited.
2841 "bitmap: string" (optional)
2843 The name of a dirty bitmap to use. Must be present if sync is
2844 "bitmap" or "incremental". Can be present if sync is "full" or
2845 "top". Must not be present otherwise. (Since 2.4 (drive-backup),
2846 3.1 (blockdev-backup))
2847 "bitmap-mode: BitmapSyncMode" (optional)
2849 Specifies the type of data the bitmap should contain after the
2850 operation concludes. Must be present if a bitmap was provided,
2851 Must NOT be present otherwise. (Since 4.2)
2852 "compress: boolean" (optional)
2854 true to compress data, if the target format supports it. (default:
2855 false) (since 2.8)
2856 "on-source-error: BlockdevOnError" (optional)
2858 the action to take on an error on the source, default 'report'.
2859 'stop' and 'enospc' can only be used if the block device supports
2860 io-status (see BlockInfo).
2861 "on-target-error: BlockdevOnError" (optional)
2863 the action to take on an error on the target, default 'report' (no
2864 limitations, since this applies to a different block device than
2865 "device").
2866 "auto-finalize: boolean" (optional)
2868 When false, this job will wait in a PENDING state after it has
2869 finished its work, waiting for "block-job-finalize" before making
2870 any block graph changes. When true, this job will automatically
2871 perform its abort or commit actions. Defaults to true. (Since
2872 2.12)
2873 "auto-dismiss: boolean" (optional)
2875 When false, this job will wait in a CONCLUDED state after it has
2876 completely ceased all work, and awaits "block-job-dismiss". When
2877 true, this job will automatically disappear from the query list
2878 without user intervention. Defaults to true. (Since 2.12)
2879 "filter-node-name: string" (optional)
2881 the node name that should be assigned to the filter driver that the
2882 backup job inserts into the graph above node specified by "drive".
2883 If this option is not given, a node name is autogenerated. (Since:
2884 4.2)
2885 Note: "on-source-error" and "on-target-error" only affect background
2887 I/O. If an error occurs during a guest write request, the device's
2888 rerror/werror actions will be used.
2889 Since: 4.2
2891 DriveBackup (Object)
2893 Members:
2895 "target: string"
2897 the target of the new image. If the file exists, or if it is a
2898 device, the existing file/device will be used as the new
2899 destination. If it does not exist, a new file will be created.
2900 "format: string" (optional)
2902 the format of the new destination, default is to probe if "mode" is
2903 'existing', else the format of the source
2904 "mode: NewImageMode" (optional)
2906 whether and how QEMU should create a new image, default is
2907 'absolute-paths'.
2908 The members of "BackupCommon"
2910 Since: 1.6
2912 BlockdevBackup (Object)
2914 Members:
2916 "target: string"
2918 the device name or node-name of the backup target node.
2919 The members of "BackupCommon"
2921 Since: 2.3
2923 blockdev-snapshot-sync (Command) Takes a synchronous snapshot of a
2925 block device.
2926 For the arguments, see the documentation of BlockdevSnapshotSync.
2928 Returns: nothing on success If "device" is not a valid block device,
2930 DeviceNotFound
2931 Since: 0.14.0
2933 Example:
2935 -> { "execute": "blockdev-snapshot-sync",
2937 "arguments": { "device": "ide-hd0",
2938 "snapshot-file":
2939 "/some/place/my-image",
2940 "format": "qcow2" } }
2941 <- { "return": {} }
2942 blockdev-snapshot (Command) Takes a snapshot of a block device.
2944 Take a snapshot, by installing 'node' as the backing image of
2946 'overlay'. Additionally, if 'node' is associated with a block device,
2947 the block device changes to using 'overlay' as its new active image.
2948 For the arguments, see the documentation of BlockdevSnapshot.
2950 Since: 2.5
2952 Example:
2954 -> { "execute": "blockdev-add",
2956 "arguments": { "driver": "qcow2",
2957 "node-name": "node1534",
2958 "file": { "driver": "file",
2959 "filename": "hd1.qcow2" },
2960 "backing": null } }
2961 <- { "return": {} }
2963 -> { "execute": "blockdev-snapshot",
2965 "arguments": { "node": "ide-hd0",
2966 "overlay": "node1534" } }
2967 <- { "return": {} }
2968 change-backing-file (Command) Change the backing file in the image
2970 file metadata. This does not cause QEMU to reopen the image file to
2971 reparse the backing filename (it may, however, perform a reopen to
2972 change permissions from r/o -> r/w -> r/o, if needed). The new backing
2973 file string is written into the image file metadata, and the QEMU
2974 internal strings are updated.
2975 Arguments:
2977 "image-node-name: string"
2979 The name of the block driver state node of the image to modify. The
2980 "device" argument is used to verify "image-node-name" is in the
2981 chain described by "device".
2982 "device: string"
2984 The device name or node-name of the root node that owns image-node-
2985 name.
2986 "backing-file: string"
2988 The string to write as the backing file. This string is not
2989 validated, so care should be taken when specifying the string or
2990 the image chain may not be able to be reopened again.
2991 Returns: Nothing on success
2993 If "device" does not exist or cannot be determined, DeviceNotFound
2995 Since: 2.1
2997 block-commit (Command) Live commit of data from overlay image nodes
2999 into backing nodes - i.e., writes data between 'top' and 'base' into
3000 'base'.
3001 Arguments:
3003 "job-id: string" (optional)
3005 identifier for the newly-created block job. If omitted, the device
3006 name will be used. (Since 2.7)
3007 "device: string"
3009 the device name or node-name of a root node
3010 "base-node: string" (optional)
3012 The node name of the backing image to write data into. If not
3013 specified, this is the deepest backing image. (since: 3.1)
3014 "base: string" (optional)
3016 Same as "base-node", except that it is a file name rather than a
3017 node name. This must be the exact filename string that was used to
3018 open the node; other strings, even if addressing the same file, are
3019 not accepted (deprecated, use "base-node" instead)
3020 "top-node: string" (optional)
3022 The node name of the backing image within the image chain which
3023 contains the topmost data to be committed down. If not specified,
3024 this is the active layer. (since: 3.1)
3025 "top: string" (optional)
3027 Same as "top-node", except that it is a file name rather than a
3028 node name. This must be the exact filename string that was used to
3029 open the node; other strings, even if addressing the same file, are
3030 not accepted (deprecated, use "base-node" instead)
3031 "backing-file: string" (optional)
3033 The backing file string to write into the overlay image of 'top'.
3034 If 'top' is the active layer, specifying a backing file string is
3035 an error. This filename is not validated.
3036 If a pathname string is such that it cannot be resolved by QEMU,
3038 that means that subsequent QMP or HMP commands must use node-names
3039 for the image in question, as filename lookup methods will fail.
3040 If not specified, QEMU will automatically determine the backing
3042 file string to use, or error out if there is no obvious choice.
3043 Care should be taken when specifying the string, to specify a valid
3044 filename or protocol. (Since 2.1)
3045 If top == base, that is an error. If top == active, the job will
3047 not be completed by itself, user needs to complete the job with the
3048 block-job-complete command after getting the ready event. (Since
3049 2.0)
3050 If the base image is smaller than top, then the base image will be
3052 resized to be the same size as top. If top is smaller than the
3053 base image, the base will not be truncated. If you want the base
3054 image size to match the size of the smaller top, you can safely
3055 truncate it yourself once the commit operation successfully
3056 completes.
3057 "speed: int" (optional)
3059 the maximum speed, in bytes per second
3060 "filter-node-name: string" (optional)
3062 the node name that should be assigned to the filter driver that the
3063 commit job inserts into the graph above "top". If this option is
3064 not given, a node name is autogenerated. (Since: 2.9)
3065 "auto-finalize: boolean" (optional)
3067 When false, this job will wait in a PENDING state after it has
3068 finished its work, waiting for "block-job-finalize" before making
3069 any block graph changes. When true, this job will automatically
3070 perform its abort or commit actions. Defaults to true. (Since 3.1)
3071 "auto-dismiss: boolean" (optional)
3073 When false, this job will wait in a CONCLUDED state after it has
3074 completely ceased all work, and awaits "block-job-dismiss". When
3075 true, this job will automatically disappear from the query list
3076 without user intervention. Defaults to true. (Since 3.1)
3077 Returns: Nothing on success If "device" does not exist, DeviceNotFound
3079 Any other error returns a GenericError.
3080 Since: 1.3
3082 Example:
3084 -> { "execute": "block-commit",
3086 "arguments": { "device": "virtio0",
3087 "top": "/tmp/snap1.qcow2" } }
3088 <- { "return": {} }
3089 drive-backup (Command) Start a point-in-time copy of a block device to
3091 a new destination. The status of ongoing drive-backup operations can
3092 be checked with query-block-jobs where the BlockJobInfo.type field has
3093 the value 'backup'. The operation can be stopped before it has
3094 completed using the block-job-cancel command.
3095 Arguments: the members of "DriveBackup"
3097 Returns: nothing on success If "device" is not a valid block device,
3099 GenericError
3100 Since: 1.6
3102 Example:
3104 -> { "execute": "drive-backup",
3106 "arguments": { "device": "drive0",
3107 "sync": "full",
3108 "target": "backup.img" } }
3109 <- { "return": {} }
3110 blockdev-backup (Command) Start a point-in-time copy of a block device
3112 to a new destination. The status of ongoing blockdev-backup operations
3113 can be checked with query-block-jobs where the BlockJobInfo.type field
3114 has the value 'backup'. The operation can be stopped before it has
3115 completed using the block-job-cancel command.
3116 Arguments: the members of "BlockdevBackup"
3118 Returns: nothing on success If "device" is not a valid block device,
3120 DeviceNotFound
3121 Since: 2.3
3123 Example:
3125 -> { "execute": "blockdev-backup",
3127 "arguments": { "device": "src-id",
3128 "sync": "full",
3129 "target": "tgt-id" } }
3130 <- { "return": {} }
3131 query-named-block-nodes (Command) Get the named block driver list
3133 Returns: the list of BlockDeviceInfo
3135 Since: 2.0
3137 Example:
3139 -> { "execute": "query-named-block-nodes" }
3141 <- { "return": [ { "ro":false,
3142 "drv":"qcow2",
3143 "encrypted":false,
3144 "file":"disks/test.qcow2",
3145 "node-name": "my-node",
3146 "backing_file_depth":1,
3147 "bps":1000000,
3148 "bps_rd":0,
3149 "bps_wr":0,
3150 "iops":1000000,
3151 "iops_rd":0,
3152 "iops_wr":0,
3153 "bps_max": 8000000,
3154 "bps_rd_max": 0,
3155 "bps_wr_max": 0,
3156 "iops_max": 0,
3157 "iops_rd_max": 0,
3158 "iops_wr_max": 0,
3159 "iops_size": 0,
3160 "write_threshold": 0,
3161 "image":{
3162 "filename":"disks/test.qcow2",
3163 "format":"qcow2",
3164 "virtual-size":2048000,
3165 "backing_file":"base.qcow2",
3166 "full-backing-filename":"disks/base.qcow2",
3167 "backing-filename-format":"qcow2",
3168 "snapshots":[
3169 {
3170 "id": "1",
3171 "name": "snapshot1",
3172 "vm-state-size": 0,
3173 "date-sec": 10000200,
3174 "date-nsec": 12,
3175 "vm-clock-sec": 206,
3176 "vm-clock-nsec": 30
3177 }
3178 ],
3179 "backing-image":{
3180 "filename":"disks/base.qcow2",
3181 "format":"qcow2",
3182 "virtual-size":2048000
3183 }
3184 } } ] }
3185 XDbgBlockGraphNodeType (Enum)
3187 Values:
3189 "block-backend"
3191 corresponds to BlockBackend
3192 "block-job"
3194 corresonds to BlockJob
3195 "block-driver"
3197 corresponds to BlockDriverState
3198 Since: 4.0
3200 XDbgBlockGraphNode (Object)
3202 Members:
3204 "id: int"
3206 Block graph node identifier. This "id" is generated only for
3207 x-debug-query-block-graph and does not relate to any other
3208 identifiers in Qemu.
3209 "type: XDbgBlockGraphNodeType"
3211 Type of graph node. Can be one of block-backend, block-job or
3212 block-driver-state.
3213 "name: string"
3215 Human readable name of the node. Corresponds to node-name for
3216 block-driver-state nodes; is not guaranteed to be unique in the
3217 whole graph (with block-jobs and block-backends).
3218 Since: 4.0
3220 BlockPermission (Enum)
3222 Enum of base block permissions.
3224 Values:
3226 "consistent-read"
3228 A user that has the "permission" of consistent reads is guaranteed
3229 that their view of the contents of the block device is complete and
3230 self-consistent, representing the contents of a disk at a specific
3231 point. For most block devices (including their backing files) this
3232 is true, but the property cannot be maintained in a few situations
3233 like for intermediate nodes of a commit block job.
3234 "write"
3236 This permission is required to change the visible disk contents.
3237 "write-unchanged"
3239 This permission (which is weaker than BLK_PERM_WRITE) is both
3240 enough and required for writes to the block node when the caller
3241 promises that the visible disk content doesn't change. As the
3242 BLK_PERM_WRITE permission is strictly stronger, either is
3243 sufficient to perform an unchanging write.
3244 "resize"
3246 This permission is required to change the size of a block node.
3247 "graph-mod"
3249 This permission is required to change the node that this BdrvChild
3250 points to.
3251 Since: 4.0
3253 XDbgBlockGraphEdge (Object)
3255 Block Graph edge description for x-debug-query-block-graph.
3257 Members:
3259 "parent: int"
3261 parent id
3262 "child: int"
3264 child id
3265 "name: string"
3267 name of the relation (examples are 'file' and 'backing')
3268 "perm: array of BlockPermission"
3270 granted permissions for the parent operating on the child
3271 "shared-perm: array of BlockPermission"
3273 permissions that can still be granted to other users of the child
3274 while it is still attached to this parent
3275 Since: 4.0
3277 XDbgBlockGraph (Object)
3279 Block Graph - list of nodes and list of edges.
3281 Members:
3283 "nodes: array of XDbgBlockGraphNode"
3285 Not documented
3286 "edges: array of XDbgBlockGraphEdge"
3288 Not documented
3289 Since: 4.0
3291 x-debug-query-block-graph (Command) Get the block graph.
3293 Since: 4.0
3295 drive-mirror (Command) Start mirroring a block device's writes to a
3297 new destination. target specifies the target of the new image. If the
3298 file exists, or if it is a device, it will be used as the new
3299 destination for writes. If it does not exist, a new file will be
3300 created. format specifies the format of the mirror image, default is to
3301 probe if mode='existing', else the format of the source.
3302 Arguments: the members of "DriveMirror"
3304 Returns: nothing on success If "device" is not a valid block device,
3306 GenericError
3307 Since: 1.3
3309 Example:
3311 -> { "execute": "drive-mirror",
3313 "arguments": { "device": "ide-hd0",
3314 "target": "/some/place/my-image",
3315 "sync": "full",
3316 "format": "qcow2" } }
3317 <- { "return": {} }
3318 DriveMirror (Object)
3320 A set of parameters describing drive mirror setup.
3322 Members:
3324 "job-id: string" (optional)
3326 identifier for the newly-created block job. If omitted, the device
3327 name will be used. (Since 2.7)
3328 "device: string"
3330 the device name or node-name of a root node whose writes should be
3331 mirrored.
3332 "target: string"
3334 the target of the new image. If the file exists, or if it is a
3335 device, the existing file/device will be used as the new
3336 destination. If it does not exist, a new file will be created.
3337 "format: string" (optional)
3339 the format of the new destination, default is to probe if "mode" is
3340 'existing', else the format of the source
3341 "node-name: string" (optional)
3343 the new block driver state node name in the graph (Since 2.1)
3344 "replaces: string" (optional)
3346 with sync=full graph node name to be replaced by the new image when
3347 a whole image copy is done. This can be used to repair broken
3348 Quorum files. (Since 2.1)
3349 "mode: NewImageMode" (optional)
3351 whether and how QEMU should create a new image, default is
3352 'absolute-paths'.
3353 "speed: int" (optional)
3355 the maximum speed, in bytes per second
3356 "sync: MirrorSyncMode"
3358 what parts of the disk image should be copied to the destination
3359 (all the disk, only the sectors allocated in the topmost image, or
3360 only new I/O).
3361 "granularity: int" (optional)
3363 granularity of the dirty bitmap, default is 64K if the image format
3364 doesn't have clusters, 4K if the clusters are smaller than that,
3365 else the cluster size. Must be a power of 2 between 512 and 64M
3366 (since 1.4).
3367 "buf-size: int" (optional)
3369 maximum amount of data in flight from source to target (since 1.4).
3370 "on-source-error: BlockdevOnError" (optional)
3372 the action to take on an error on the source, default 'report'.
3373 'stop' and 'enospc' can only be used if the block device supports
3374 io-status (see BlockInfo).
3375 "on-target-error: BlockdevOnError" (optional)
3377 the action to take on an error on the target, default 'report' (no
3378 limitations, since this applies to a different block device than
3379 "device").
3380 "unmap: boolean" (optional)
3382 Whether to try to unmap target sectors where source has only zero.
3383 If true, and target unallocated sectors will read as zero, target
3384 image sectors will be unmapped; otherwise, zeroes will be written.
3385 Both will result in identical contents. Default is true. (Since
3386 2.4)
3387 "copy-mode: MirrorCopyMode" (optional)
3389 when to copy data to the destination; defaults to 'background'
3390 (Since: 3.0)
3391 "auto-finalize: boolean" (optional)
3393 When false, this job will wait in a PENDING state after it has
3394 finished its work, waiting for "block-job-finalize" before making
3395 any block graph changes. When true, this job will automatically
3396 perform its abort or commit actions. Defaults to true. (Since 3.1)
3397 "auto-dismiss: boolean" (optional)
3399 When false, this job will wait in a CONCLUDED state after it has
3400 completely ceased all work, and awaits "block-job-dismiss". When
3401 true, this job will automatically disappear from the query list
3402 without user intervention. Defaults to true. (Since 3.1)
3403 Since: 1.3
3405 BlockDirtyBitmap (Object)
3407 Members:
3409 "node: string"
3411 name of device/node which the bitmap is tracking
3412 "name: string"
3414 name of the dirty bitmap
3415 Since: 2.4
3417 BlockDirtyBitmapAdd (Object)
3419 Members:
3421 "node: string"
3423 name of device/node which the bitmap is tracking
3424 "name: string"
3426 name of the dirty bitmap (must be less than 1024 bytes)
3427 "granularity: int" (optional)
3429 the bitmap granularity, default is 64k for block-dirty-bitmap-add
3430 "persistent: boolean" (optional)
3432 the bitmap is persistent, i.e. it will be saved to the
3433 corresponding block device image file on its close. For now only
3434 Qcow2 disks support persistent bitmaps. Default is false for block-
3435 dirty-bitmap-add. (Since: 2.10)
3436 "disabled: boolean" (optional)
3438 the bitmap is created in the disabled state, which means that it
3439 will not track drive changes. The bitmap may be enabled with block-
3440 dirty-bitmap-enable. Default is false. (Since: 4.0)
3441 Since: 2.4
3443 BlockDirtyBitmapMergeSource (Alternate)
3445 Members:
3447 "local: string"
3449 name of the bitmap, attached to the same node as target bitmap.
3450 "external: BlockDirtyBitmap"
3452 bitmap with specified node
3453 Since: 4.1
3455 BlockDirtyBitmapMerge (Object)
3457 Members:
3459 "node: string"
3461 name of device/node which the "target" bitmap is tracking
3462 "target: string"
3464 name of the destination dirty bitmap
3465 "bitmaps: array of BlockDirtyBitmapMergeSource"
3467 name(s) of the source dirty bitmap(s) at "node" and/or fully
3468 specifed BlockDirtyBitmap elements. The latter are supported since
3469 4.1.
3470 Since: 4.0
3472 block-dirty-bitmap-add (Command) Create a dirty bitmap with a name on
3474 the node, and start tracking the writes.
3475 Returns: nothing on success If "node" is not a valid block device or
3477 node, DeviceNotFound If "name" is already taken, GenericError with an
3478 explanation
3479 Since: 2.4
3481 Example:
3483 -> { "execute": "block-dirty-bitmap-add",
3485 "arguments": { "node": "drive0", "name": "bitmap0" } }
3486 <- { "return": {} }
3487 block-dirty-bitmap-remove (Command) Stop write tracking and remove the
3489 dirty bitmap that was created with block-dirty-bitmap-add. If the
3490 bitmap is persistent, remove it from its storage too.
3491 Returns: nothing on success If "node" is not a valid block device or
3493 node, DeviceNotFound If "name" is not found, GenericError with an
3494 explanation if "name" is frozen by an operation, GenericError
3495 Since: 2.4
3497 Example:
3499 -> { "execute": "block-dirty-bitmap-remove",
3501 "arguments": { "node": "drive0", "name": "bitmap0" } }
3502 <- { "return": {} }
3503 block-dirty-bitmap-clear (Command) Clear (reset) a dirty bitmap on the
3505 device, so that an incremental backup from this point in time forward
3506 will only backup clusters modified after this clear operation.
3507 Returns: nothing on success If "node" is not a valid block device,
3509 DeviceNotFound If "name" is not found, GenericError with an explanation
3510 Since: 2.4
3512 Example:
3514 -> { "execute": "block-dirty-bitmap-clear",
3516 "arguments": { "node": "drive0", "name": "bitmap0" } }
3517 <- { "return": {} }
3518 block-dirty-bitmap-enable (Command) Enables a dirty bitmap so that it
3520 will begin tracking disk changes.
3521 Returns: nothing on success If "node" is not a valid block device,
3523 DeviceNotFound If "name" is not found, GenericError with an explanation
3524 Since: 4.0
3526 Example:
3528 -> { "execute": "block-dirty-bitmap-enable",
3530 "arguments": { "node": "drive0", "name": "bitmap0" } }
3531 <- { "return": {} }
3532 block-dirty-bitmap-disable (Command) Disables a dirty bitmap so that
3534 it will stop tracking disk changes.
3535 Returns: nothing on success If "node" is not a valid block device,
3537 DeviceNotFound If "name" is not found, GenericError with an explanation
3538 Since: 4.0
3540 Example:
3542 -> { "execute": "block-dirty-bitmap-disable",
3544 "arguments": { "node": "drive0", "name": "bitmap0" } }
3545 <- { "return": {} }
3546 block-dirty-bitmap-merge (Command) Merge dirty bitmaps listed in
3548 "bitmaps" to the "target" dirty bitmap. Dirty bitmaps in "bitmaps"
3549 will be unchanged, except if it also appears as the "target" bitmap.
3550 Any bits already set in "target" will still be set after the merge,
3551 i.e., this operation does not clear the target. On error, "target" is
3552 unchanged.
3553 The resulting bitmap will count as dirty any clusters that were dirty
3555 in any of the source bitmaps. This can be used to achieve backup
3556 checkpoints, or in simpler usages, to copy bitmaps.
3557 Returns: nothing on success If "node" is not a valid block device,
3559 DeviceNotFound If any bitmap in "bitmaps" or "target" is not found,
3560 GenericError If any of the bitmaps have different sizes or
3561 granularities, GenericError
3562 Since: 4.0
3564 Example:
3566 -> { "execute": "block-dirty-bitmap-merge",
3568 "arguments": { "node": "drive0", "target": "bitmap0",
3569 "bitmaps": ["bitmap1"] } }
3570 <- { "return": {} }
3571 BlockDirtyBitmapSha256 (Object)
3573 SHA256 hash of dirty bitmap data
3575 Members:
3577 "sha256: string"
3579 ASCII representation of SHA256 bitmap hash
3580 Since: 2.10
3582 x-debug-block-dirty-bitmap-sha256 (Command) Get bitmap SHA256.
3584 Returns: BlockDirtyBitmapSha256 on success If "node" is not a valid
3586 block device, DeviceNotFound If "name" is not found or if hashing has
3587 failed, GenericError with an explanation
3588 Since: 2.10
3590 blockdev-mirror (Command) Start mirroring a block device's writes to a
3592 new destination.
3593 Arguments:
3595 "job-id: string" (optional)
3597 identifier for the newly-created block job. If omitted, the device
3598 name will be used. (Since 2.7)
3599 "device: string"
3601 The device name or node-name of a root node whose writes should be
3602 mirrored.
3603 "target: string"
3605 the id or node-name of the block device to mirror to. This mustn't
3606 be attached to guest.
3607 "replaces: string" (optional)
3609 with sync=full graph node name to be replaced by the new image when
3610 a whole image copy is done. This can be used to repair broken
3611 Quorum files.
3612 "speed: int" (optional)
3614 the maximum speed, in bytes per second
3615 "sync: MirrorSyncMode"
3617 what parts of the disk image should be copied to the destination
3618 (all the disk, only the sectors allocated in the topmost image, or
3619 only new I/O).
3620 "granularity: int" (optional)
3622 granularity of the dirty bitmap, default is 64K if the image format
3623 doesn't have clusters, 4K if the clusters are smaller than that,
3624 else the cluster size. Must be a power of 2 between 512 and 64M
3625 "buf-size: int" (optional)
3627 maximum amount of data in flight from source to target
3628 "on-source-error: BlockdevOnError" (optional)
3630 the action to take on an error on the source, default 'report'.
3631 'stop' and 'enospc' can only be used if the block device supports
3632 io-status (see BlockInfo).
3633 "on-target-error: BlockdevOnError" (optional)
3635 the action to take on an error on the target, default 'report' (no
3636 limitations, since this applies to a different block device than
3637 "device").
3638 "filter-node-name: string" (optional)
3640 the node name that should be assigned to the filter driver that the
3641 mirror job inserts into the graph above "device". If this option is
3642 not given, a node name is autogenerated. (Since: 2.9)
3643 "copy-mode: MirrorCopyMode" (optional)
3645 when to copy data to the destination; defaults to 'background'
3646 (Since: 3.0)
3647 "auto-finalize: boolean" (optional)
3649 When false, this job will wait in a PENDING state after it has
3650 finished its work, waiting for "block-job-finalize" before making
3651 any block graph changes. When true, this job will automatically
3652 perform its abort or commit actions. Defaults to true. (Since 3.1)
3653 "auto-dismiss: boolean" (optional)
3655 When false, this job will wait in a CONCLUDED state after it has
3656 completely ceased all work, and awaits "block-job-dismiss". When
3657 true, this job will automatically disappear from the query list
3658 without user intervention. Defaults to true. (Since 3.1)
3659 Returns: nothing on success.
3661 Since: 2.6
3663 Example:
3665 -> { "execute": "blockdev-mirror",
3667 "arguments": { "device": "ide-hd0",
3668 "target": "target0",
3669 "sync": "full" } }
3670 <- { "return": {} }
3671 block_set_io_throttle (Command) Change I/O throttle limits for a block
3673 drive.
3674 Since QEMU 2.4, each device with I/O limits is member of a throttle
3676 group.
3677 If two or more devices are members of the same group, the limits will
3679 apply to the combined I/O of the whole group in a round-robin fashion.
3680 Therefore, setting new I/O limits to a device will affect the whole
3681 group.
3682 The name of the group can be specified using the 'group' parameter. If
3684 the parameter is unset, it is assumed to be the current group of that
3685 device. If it's not in any group yet, the name of the device will be
3686 used as the name for its group.
3687 The 'group' parameter can also be used to move a device to a different
3689 group. In this case the limits specified in the parameters will be
3690 applied to the new group only.
3691 I/O limits can be disabled by setting all of them to 0. In this case
3693 the device will be removed from its group and the rest of its members
3694 will not be affected. The 'group' parameter is ignored.
3695 Arguments: the members of "BlockIOThrottle"
3697 Returns: Nothing on success If "device" is not a valid block device,
3699 DeviceNotFound
3700 Since: 1.1
3702 Example:
3704 -> { "execute": "block_set_io_throttle",
3706 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
3707 "bps": 0,
3708 "bps_rd": 0,
3709 "bps_wr": 0,
3710 "iops": 512,
3711 "iops_rd": 0,
3712 "iops_wr": 0,
3713 "bps_max": 0,
3714 "bps_rd_max": 0,
3715 "bps_wr_max": 0,
3716 "iops_max": 0,
3717 "iops_rd_max": 0,
3718 "iops_wr_max": 0,
3719 "bps_max_length": 0,
3720 "iops_size": 0 } }
3721 <- { "return": {} }
3722 -> { "execute": "block_set_io_throttle",
3724 "arguments": { "id": "ide0-1-0",
3725 "bps": 1000000,
3726 "bps_rd": 0,
3727 "bps_wr": 0,
3728 "iops": 0,
3729 "iops_rd": 0,
3730 "iops_wr": 0,
3731 "bps_max": 8000000,
3732 "bps_rd_max": 0,
3733 "bps_wr_max": 0,
3734 "iops_max": 0,
3735 "iops_rd_max": 0,
3736 "iops_wr_max": 0,
3737 "bps_max_length": 60,
3738 "iops_size": 0 } }
3739 <- { "return": {} }
3740 BlockIOThrottle (Object)
3742 A set of parameters describing block throttling.
3744 Members:
3746 "device: string" (optional)
3748 Block device name (deprecated, use "id" instead)
3749 "id: string" (optional)
3751 The name or QOM path of the guest device (since: 2.8)
3752 "bps: int"
3754 total throughput limit in bytes per second
3755 "bps_rd: int"
3757 read throughput limit in bytes per second
3758 "bps_wr: int"
3760 write throughput limit in bytes per second
3761 "iops: int"
3763 total I/O operations per second
3764 "iops_rd: int"
3766 read I/O operations per second
3767 "iops_wr: int"
3769 write I/O operations per second
3770 "bps_max: int" (optional)
3772 total throughput limit during bursts, in bytes (Since 1.7)
3773 "bps_rd_max: int" (optional)
3775 read throughput limit during bursts, in bytes (Since 1.7)
3776 "bps_wr_max: int" (optional)
3778 write throughput limit during bursts, in bytes (Since 1.7)
3779 "iops_max: int" (optional)
3781 total I/O operations per second during bursts, in bytes (Since 1.7)
3782 "iops_rd_max: int" (optional)
3784 read I/O operations per second during bursts, in bytes (Since 1.7)
3785 "iops_wr_max: int" (optional)
3787 write I/O operations per second during bursts, in bytes (Since 1.7)
3788 "bps_max_length: int" (optional)
3790 maximum length of the "bps_max" burst period, in seconds. It must
3791 only be set if "bps_max" is set as well. Defaults to 1. (Since
3792 2.6)
3793 "bps_rd_max_length: int" (optional)
3795 maximum length of the "bps_rd_max" burst period, in seconds. It
3796 must only be set if "bps_rd_max" is set as well. Defaults to 1.
3797 (Since 2.6)
3798 "bps_wr_max_length: int" (optional)
3800 maximum length of the "bps_wr_max" burst period, in seconds. It
3801 must only be set if "bps_wr_max" is set as well. Defaults to 1.
3802 (Since 2.6)
3803 "iops_max_length: int" (optional)
3805 maximum length of the "iops" burst period, in seconds. It must only
3806 be set if "iops_max" is set as well. Defaults to 1. (Since 2.6)
3807 "iops_rd_max_length: int" (optional)
3809 maximum length of the "iops_rd_max" burst period, in seconds. It
3810 must only be set if "iops_rd_max" is set as well. Defaults to 1.
3811 (Since 2.6)
3812 "iops_wr_max_length: int" (optional)
3814 maximum length of the "iops_wr_max" burst period, in seconds. It
3815 must only be set if "iops_wr_max" is set as well. Defaults to 1.
3816 (Since 2.6)
3817 "iops_size: int" (optional)
3819 an I/O size in bytes (Since 1.7)
3820 "group: string" (optional)
3822 throttle group name (Since 2.4)
3823 Since: 1.1
3825 ThrottleLimits (Object)
3827 Limit parameters for throttling. Since some limit combinations are
3829 illegal, limits should always be set in one transaction. All fields are
3830 optional. When setting limits, if a field is missing the current value
3831 is not changed.
3832 Members:
3834 "iops-total: int" (optional)
3836 limit total I/O operations per second
3837 "iops-total-max: int" (optional)
3839 I/O operations burst
3840 "iops-total-max-length: int" (optional)
3842 length of the iops-total-max burst period, in seconds It must only
3843 be set if "iops-total-max" is set as well.
3844 "iops-read: int" (optional)
3846 limit read operations per second
3847 "iops-read-max: int" (optional)
3849 I/O operations read burst
3850 "iops-read-max-length: int" (optional)
3852 length of the iops-read-max burst period, in seconds It must only
3853 be set if "iops-read-max" is set as well.
3854 "iops-write: int" (optional)
3856 limit write operations per second
3857 "iops-write-max: int" (optional)
3859 I/O operations write burst
3860 "iops-write-max-length: int" (optional)
3862 length of the iops-write-max burst period, in seconds It must only
3863 be set if "iops-write-max" is set as well.
3864 "bps-total: int" (optional)
3866 limit total bytes per second
3867 "bps-total-max: int" (optional)
3869 total bytes burst
3870 "bps-total-max-length: int" (optional)
3872 length of the bps-total-max burst period, in seconds. It must only
3873 be set if "bps-total-max" is set as well.
3874 "bps-read: int" (optional)
3876 limit read bytes per second
3877 "bps-read-max: int" (optional)
3879 total bytes read burst
3880 "bps-read-max-length: int" (optional)
3882 length of the bps-read-max burst period, in seconds It must only be
3883 set if "bps-read-max" is set as well.
3884 "bps-write: int" (optional)
3886 limit write bytes per second
3887 "bps-write-max: int" (optional)
3889 total bytes write burst
3890 "bps-write-max-length: int" (optional)
3892 length of the bps-write-max burst period, in seconds It must only
3893 be set if "bps-write-max" is set as well.
3894 "iops-size: int" (optional)
3896 when limiting by iops max size of an I/O in bytes
3897 Since: 2.11
3899 block-stream (Command) Copy data from a backing file into a block
3901 device.
3902 The block streaming operation is performed in the background until the
3904 entire backing file has been copied. This command returns immediately
3905 once streaming has started. The status of ongoing block streaming
3906 operations can be checked with query-block-jobs. The operation can be
3907 stopped before it has completed using the block-job-cancel command.
3908 The node that receives the data is called the top image, can be located
3910 in any part of the chain (but always above the base image; see below)
3911 and can be specified using its device or node name. Earlier qemu
3912 versions only allowed 'device' to name the top level node; presence of
3913 the 'base-node' parameter during introspection can be used as a witness
3914 of the enhanced semantics of 'device'.
3915 If a base file is specified then sectors are not copied from that base
3917 file and its backing chain. When streaming completes the image file
3918 will have the base file as its backing file. This can be used to
3919 stream a subset of the backing file chain instead of flattening the
3920 entire image.
3921 On successful completion the image file is updated to drop the backing
3923 file and the BLOCK_JOB_COMPLETED event is emitted.
3924 Arguments:
3926 "job-id: string" (optional)
3928 identifier for the newly-created block job. If omitted, the device
3929 name will be used. (Since 2.7)
3930 "device: string"
3932 the device or node name of the top image
3933 "base: string" (optional)
3935 the common backing file name. It cannot be set if "base-node" is
3936 also set.
3937 "base-node: string" (optional)
3939 the node name of the backing file. It cannot be set if "base" is
3940 also set. (Since 2.8)
3941 "backing-file: string" (optional)
3943 The backing file string to write into the top image. This filename
3944 is not validated.
3945 If a pathname string is such that it cannot be resolved by QEMU,
3947 that means that subsequent QMP or HMP commands must use node-names
3948 for the image in question, as filename lookup methods will fail.
3949 If not specified, QEMU will automatically determine the backing
3951 file string to use, or error out if there is no obvious choice.
3952 Care should be taken when specifying the string, to specify a valid
3953 filename or protocol. (Since 2.1)
3954 "speed: int" (optional)
3956 the maximum speed, in bytes per second
3957 "on-error: BlockdevOnError" (optional)
3959 the action to take on an error (default report). 'stop' and
3960 'enospc' can only be used if the block device supports io-status
3961 (see BlockInfo). Since 1.3.
3962 "auto-finalize: boolean" (optional)
3964 When false, this job will wait in a PENDING state after it has
3965 finished its work, waiting for "block-job-finalize" before making
3966 any block graph changes. When true, this job will automatically
3967 perform its abort or commit actions. Defaults to true. (Since 3.1)
3968 "auto-dismiss: boolean" (optional)
3970 When false, this job will wait in a CONCLUDED state after it has
3971 completely ceased all work, and awaits "block-job-dismiss". When
3972 true, this job will automatically disappear from the query list
3973 without user intervention. Defaults to true. (Since 3.1)
3974 Returns: Nothing on success. If "device" does not exist,
3976 DeviceNotFound.
3977 Since: 1.1
3979 Example:
3981 -> { "execute": "block-stream",
3983 "arguments": { "device": "virtio0",
3984 "base": "/tmp/master.qcow2" } }
3985 <- { "return": {} }
3986 block-job-set-speed (Command) Set maximum speed for a background block
3988 operation.
3989 This command can only be issued when there is an active block job.
3991 Throttling can be disabled by setting the speed to 0.
3993 Arguments:
3995 "device: string"
3997 The job identifier. This used to be a device name (hence the name
3998 of the parameter), but since QEMU 2.7 it can have other values.
3999 "speed: int"
4001 the maximum speed, in bytes per second, or 0 for unlimited.
4002 Defaults to 0.
4003 Returns: Nothing on success If no background operation is active on
4005 this device, DeviceNotActive
4006 Since: 1.1
4008 block-job-cancel (Command) Stop an active background block operation.
4010 This command returns immediately after marking the active background
4012 block operation for cancellation. It is an error to call this command
4013 if no operation is in progress.
4014 The operation will cancel as soon as possible and then emit the
4016 BLOCK_JOB_CANCELLED event. Before that happens the job is still
4017 visible when enumerated using query-block-jobs.
4018 Note that if you issue 'block-job-cancel' after 'drive-mirror' has
4020 indicated (via the event BLOCK_JOB_READY) that the source and
4021 destination are synchronized, then the event triggered by this command
4022 changes to BLOCK_JOB_COMPLETED, to indicate that the mirroring has
4023 ended and the destination now has a point-in-time copy tied to the time
4024 of the cancellation.
4025 For streaming, the image file retains its backing file unless the
4027 streaming operation happens to complete just as it is being cancelled.
4028 A new streaming operation can be started at a later time to finish
4029 copying all data from the backing file.
4030 Arguments:
4032 "device: string"
4034 The job identifier. This used to be a device name (hence the name
4035 of the parameter), but since QEMU 2.7 it can have other values.
4036 "force: boolean" (optional)
4038 If true, and the job has already emitted the event BLOCK_JOB_READY,
4039 abandon the job immediately (even if it is paused) instead of
4040 waiting for the destination to complete its final synchronization
4041 (since 1.3)
4042 Returns: Nothing on success If no background operation is active on
4044 this device, DeviceNotActive
4045 Since: 1.1
4047 block-job-pause (Command) Pause an active background block operation.
4049 This command returns immediately after marking the active background
4051 block operation for pausing. It is an error to call this command if no
4052 operation is in progress or if the job is already paused.
4053 The operation will pause as soon as possible. No event is emitted when
4055 the operation is actually paused. Cancelling a paused job
4056 automatically resumes it.
4057 Arguments:
4059 "device: string"
4061 The job identifier. This used to be a device name (hence the name
4062 of the parameter), but since QEMU 2.7 it can have other values.
4063 Returns: Nothing on success If no background operation is active on
4065 this device, DeviceNotActive
4066 Since: 1.3
4068 block-job-resume (Command) Resume an active background block
4070 operation.
4071 This command returns immediately after resuming a paused background
4073 block operation. It is an error to call this command if no operation
4074 is in progress or if the job is not paused.
4075 This command also clears the error status of the job.
4077 Arguments:
4079 "device: string"
4081 The job identifier. This used to be a device name (hence the name
4082 of the parameter), but since QEMU 2.7 it can have other values.
4083 Returns: Nothing on success If no background operation is active on
4085 this device, DeviceNotActive
4086 Since: 1.3
4088 block-job-complete (Command) Manually trigger completion of an active
4090 background block operation. This is supported for drive mirroring,
4091 where it also switches the device to write to the target path only.
4092 The ability to complete is signaled with a BLOCK_JOB_READY event.
4093 This command completes an active background block operation
4095 synchronously. The ordering of this command's return with the
4096 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4097 occurs during the processing of this command: 1) the command itself
4098 will fail; 2) the error will be processed according to the
4099 rerror/werror arguments that were specified when starting the
4100 operation.
4101 A cancelled or paused job cannot be completed.
4103 Arguments:
4105 "device: string"
4107 The job identifier. This used to be a device name (hence the name
4108 of the parameter), but since QEMU 2.7 it can have other values.
4109 Returns: Nothing on success If no background operation is active on
4111 this device, DeviceNotActive
4112 Since: 1.3
4114 block-job-dismiss (Command) For jobs that have already concluded,
4116 remove them from the block-job-query list. This command only needs to
4117 be run for jobs which were started with QEMU 2.12+ job lifetime
4118 management semantics.
4119 This command will refuse to operate on any job that has not yet reached
4121 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4122 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4123 still need to be used as appropriate.
4124 Arguments:
4126 "id: string"
4128 The job identifier.
4129 Returns: Nothing on success
4131 Since: 2.12
4133 block-job-finalize (Command) Once a job that has manual=true reaches
4135 the pending state, it can be instructed to finalize any graph changes
4136 and do any necessary cleanup via this command. For jobs in a
4137 transaction, instructing one job to finalize will force ALL jobs in the
4138 transaction to finalize, so it is only necessary to instruct a single
4139 member job to finalize.
4140 Arguments:
4142 "id: string"
4144 The job identifier.
4145 Returns: Nothing on success
4147 Since: 2.12
4149 BlockdevDiscardOptions (Enum)
4151 Determines how to handle discard requests.
4153 Values:
4155 "ignore"
4157 Ignore the request
4158 "unmap"
4160 Forward as an unmap request
4161 Since: 2.9
4163 BlockdevDetectZeroesOptions (Enum)
4165 Describes the operation mode for the automatic conversion of plain zero
4167 writes by the OS to driver specific optimized zero write commands.
4168 Values:
4170 "off"
4172 Disabled (default)
4173 "on"
4175 Enabled
4176 "unmap"
4178 Enabled and even try to unmap blocks if possible. This requires
4179 also that "BlockdevDiscardOptions" is set to unmap for this device.
4180 Since: 2.1
4182 BlockdevAioOptions (Enum)
4184 Selects the AIO backend to handle I/O requests
4186 Values:
4188 "threads"
4190 Use qemu's thread pool
4191 "native"
4193 Use native AIO backend (only Linux and Windows)
4194 Since: 2.9
4196 BlockdevCacheOptions (Object)
4198 Includes cache-related options for block devices
4200 Members:
4202 "direct: boolean" (optional)
4204 enables use of O_DIRECT (bypass the host page cache; default:
4205 false)
4206 "no-flush: boolean" (optional)
4208 ignore any flush requests for the device (default: false)
4209 Since: 2.9
4211 BlockdevDriver (Enum)
4213 Drivers that are supported in block device operations.
4215 Values:
4217 "vxhs"
4219 Since 2.10
4220 "throttle"
4222 Since 2.11
4223 "nvme"
4225 Since 2.12
4226 "copy-on-read"
4228 Since 3.0
4229 "blklogwrites"
4231 Since 3.0
4232 "blkreplay"
4234 Since 4.2
4235 "blkdebug"
4237 Not documented
4238 "blkverify"
4240 Not documented
4241 "bochs"
4243 Not documented
4244 "cloop"
4246 Not documented
4247 "dmg"
4249 Not documented
4250 "file"
4252 Not documented
4253 "ftp"
4255 Not documented
4256 "ftps"
4258 Not documented
4259 "gluster"
4261 Not documented
4262 "host_cdrom"
4264 Not documented
4265 "host_device"
4267 Not documented
4268 "http"
4270 Not documented
4271 "https"
4273 Not documented
4274 "iscsi"
4276 Not documented
4277 "luks"
4279 Not documented
4280 "nbd"
4282 Not documented
4283 "nfs"
4285 Not documented
4286 "null-aio"
4288 Not documented
4289 "null-co"
4291 Not documented
4292 "parallels"
4294 Not documented
4295 "qcow"
4297 Not documented
4298 "qcow2"
4300 Not documented
4301 "qed"
4303 Not documented
4304 "quorum"
4306 Not documented
4307 "raw"
4309 Not documented
4310 "rbd"
4312 Not documented
4313 "replication"
4315 Not documented If: "defined(CONFIG_REPLICATION)"
4316 "sheepdog"
4318 Not documented
4319 "ssh"
4321 Not documented
4322 "vdi"
4324 Not documented
4325 "vhdx"
4327 Not documented
4328 "vmdk"
4330 Not documented
4331 "vpc"
4333 Not documented
4334 "vvfat"
4336 Not documented
4337 Since: 2.9
4339 BlockdevOptionsFile (Object)
4341 Driver specific block device options for the file backend.
4343 Members:
4345 "filename: string"
4347 path to the image file
4348 "pr-manager: string" (optional)
4350 the id for the object that will handle persistent reservations for
4351 this device (default: none, forward the commands via SG_IO; since
4352 2.11)
4353 "aio: BlockdevAioOptions" (optional)
4355 AIO backend (default: threads) (since: 2.8)
4356 "locking: OnOffAuto" (optional)
4358 whether to enable file locking. If set to 'auto', only enable when
4359 Open File Descriptor (OFD) locking API is available (default: auto,
4360 since 2.10)
4361 "drop-cache: boolean" (optional)
4363 invalidate page cache during live migration. This prevents stale
4364 data on the migration destination with cache.direct=off. Currently
4365 only supported on Linux hosts. (default: on, since: 4.0) If:
4366 "defined(CONFIG_LINUX)"
4367 "x-check-cache-dropped: boolean" (optional)
4369 whether to check that page cache was dropped on live migration.
4370 May cause noticeable delays if the image file is large, do not use
4371 in production. (default: off) (since: 3.0)
4372 Features:
4374 "dynamic-auto-read-only"
4376 If present, enabled auto-read-only means that the driver will open
4377 the image read-only at first, dynamically reopen the image file
4378 read-write when the first writer is attached to the node and reopen
4379 read-only when the last writer is detached. This allows giving QEMU
4380 write permissions only on demand when an operation actually needs
4381 write access.
4382 Since: 2.9
4384 BlockdevOptionsNull (Object)
4386 Driver specific block device options for the null backend.
4388 Members:
4390 "size: int" (optional)
4392 size of the device in bytes.
4393 "latency-ns: int" (optional)
4395 emulated latency (in nanoseconds) in processing requests. Default
4396 to zero which completes requests immediately. (Since 2.4)
4397 "read-zeroes: boolean" (optional)
4399 if true, reads from the device produce zeroes; if false, the buffer
4400 is left unchanged. (default: false; since: 4.1)
4401 Since: 2.9
4403 BlockdevOptionsNVMe (Object)
4405 Driver specific block device options for the NVMe backend.
4407 Members:
4409 "device: string"
4411 controller address of the NVMe device.
4412 "namespace: int"
4414 namespace number of the device, starting from 1.
4415 Since: 2.12
4417 BlockdevOptionsVVFAT (Object)
4419 Driver specific block device options for the vvfat protocol.
4421 Members:
4423 "dir: string"
4425 directory to be exported as FAT image
4426 "fat-type: int" (optional)
4428 FAT type: 12, 16 or 32
4429 "floppy: boolean" (optional)
4431 whether to export a floppy image (true) or partitioned hard disk
4432 (false; default)
4433 "label: string" (optional)
4435 set the volume label, limited to 11 bytes. FAT16 and FAT32
4436 traditionally have some restrictions on labels, which are ignored
4437 by most operating systems. Defaults to "QEMU VVFAT". (since 2.4)
4438 "rw: boolean" (optional)
4440 whether to allow write operations (default: false)
4441 Since: 2.9
4443 BlockdevOptionsGenericFormat (Object)
4445 Driver specific block device options for image format that have no
4447 option besides their data source.
4448 Members:
4450 "file: BlockdevRef"
4452 reference to or definition of the data source block device
4453 Since: 2.9
4455 BlockdevOptionsLUKS (Object)
4457 Driver specific block device options for LUKS.
4459 Members:
4461 "key-secret: string" (optional)
4463 the ID of a QCryptoSecret object providing the decryption key
4464 (since 2.6). Mandatory except when doing a metadata-only probe of
4465 the image.
4466 The members of "BlockdevOptionsGenericFormat"
4468 Since: 2.9
4470 BlockdevOptionsGenericCOWFormat (Object)
4472 Driver specific block device options for image format that have no
4474 option besides their data source and an optional backing file.
4475 Members:
4477 "backing: BlockdevRefOrNull" (optional)
4479 reference to or definition of the backing file block device, null
4480 disables the backing file entirely. Defaults to the backing file
4481 stored the image file.
4482 The members of "BlockdevOptionsGenericFormat"
4484 Since: 2.9
4486 Qcow2OverlapCheckMode (Enum)
4488 General overlap check modes.
4490 Values:
4492 "none"
4494 Do not perform any checks
4495 "constant"
4497 Perform only checks which can be done in constant time and without
4498 reading anything from disk
4499 "cached"
4501 Perform only checks which can be done without reading anything from
4502 disk
4503 "all"
4505 Perform all available overlap checks
4506 Since: 2.9
4508 Qcow2OverlapCheckFlags (Object)
4510 Structure of flags for each metadata structure. Setting a field to
4512 'true' makes qemu guard that structure against unintended overwriting.
4513 The default value is chosen according to the template given.
4514 Members:
4516 "template: Qcow2OverlapCheckMode" (optional)
4518 Specifies a template mode which can be adjusted using the other
4519 flags, defaults to 'cached'
4520 "bitmap-directory: boolean" (optional)
4522 since 3.0
4523 "main-header: boolean" (optional)
4525 Not documented
4526 "active-l1: boolean" (optional)
4528 Not documented
4529 "active-l2: boolean" (optional)
4531 Not documented
4532 "refcount-table: boolean" (optional)
4534 Not documented
4535 "refcount-block: boolean" (optional)
4537 Not documented
4538 "snapshot-table: boolean" (optional)
4540 Not documented
4541 "inactive-l1: boolean" (optional)
4543 Not documented
4544 "inactive-l2: boolean" (optional)
4546 Not documented
4547 Since: 2.9
4549 Qcow2OverlapChecks (Alternate)
4551 Specifies which metadata structures should be guarded against
4553 unintended overwriting.
4554 Members:
4556 "flags: Qcow2OverlapCheckFlags"
4558 set of flags for separate specification of each metadata structure
4559 type
4560 "mode: Qcow2OverlapCheckMode"
4562 named mode which chooses a specific set of flags
4563 Since: 2.9
4565 BlockdevQcowEncryptionFormat (Enum)
4567 Values:
4569 "aes"
4571 AES-CBC with plain64 initialization vectors
4572 Since: 2.10
4574 BlockdevQcowEncryption (Object)
4576 Members:
4578 "format: BlockdevQcowEncryptionFormat"
4580 Not documented
4581 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4583 Since: 2.10
4585 BlockdevOptionsQcow (Object)
4587 Driver specific block device options for qcow.
4589 Members:
4591 "encrypt: BlockdevQcowEncryption" (optional)
4593 Image decryption options. Mandatory for encrypted images, except
4594 when doing a metadata-only probe of the image.
4595 The members of "BlockdevOptionsGenericCOWFormat"
4597 Since: 2.10
4599 BlockdevQcow2EncryptionFormat (Enum)
4601 Values:
4603 "aes"
4605 AES-CBC with plain64 initialization vectors
4606 "luks"
4608 Not documented
4609 Since: 2.10
4611 BlockdevQcow2Encryption (Object)
4613 Members:
4615 "format: BlockdevQcow2EncryptionFormat"
4617 Not documented
4618 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4620 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
4621 Since: 2.10
4623 BlockdevOptionsQcow2 (Object)
4625 Driver specific block device options for qcow2.
4627 Members:
4629 "lazy-refcounts: boolean" (optional)
4631 whether to enable the lazy refcounts feature (default is taken from
4632 the image file)
4633 "pass-discard-request: boolean" (optional)
4635 whether discard requests to the qcow2 device should be forwarded to
4636 the data source
4637 "pass-discard-snapshot: boolean" (optional)
4639 whether discard requests for the data source should be issued when
4640 a snapshot operation (e.g. deleting a snapshot) frees clusters in
4641 the qcow2 file
4642 "pass-discard-other: boolean" (optional)
4644 whether discard requests for the data source should be issued on
4645 other occasions where a cluster gets freed
4646 "overlap-check: Qcow2OverlapChecks" (optional)
4648 which overlap checks to perform for writes to the image, defaults
4649 to 'cached' (since 2.2)
4650 "cache-size: int" (optional)
4652 the maximum total size of the L2 table and refcount block caches in
4653 bytes (since 2.2)
4654 "l2-cache-size: int" (optional)
4656 the maximum size of the L2 table cache in bytes (since 2.2)
4657 "l2-cache-entry-size: int" (optional)
4659 the size of each entry in the L2 cache in bytes. It must be a power
4660 of two between 512 and the cluster size. The default value is the
4661 cluster size (since 2.12)
4662 "refcount-cache-size: int" (optional)
4664 the maximum size of the refcount block cache in bytes (since 2.2)
4665 "cache-clean-interval: int" (optional)
4667 clean unused entries in the L2 and refcount caches. The interval is
4668 in seconds. The default value is 600 on supporting platforms, and 0
4669 on other platforms. 0 disables this feature. (since 2.5)
4670 "encrypt: BlockdevQcow2Encryption" (optional)
4672 Image decryption options. Mandatory for encrypted images, except
4673 when doing a metadata-only probe of the image. (since 2.10)
4674 "data-file: BlockdevRef" (optional)
4676 reference to or definition of the external data file. This may
4677 only be specified for images that require an external data file. If
4678 it is not specified for such an image, the data file name is loaded
4679 from the image file. (since 4.0)
4680 The members of "BlockdevOptionsGenericCOWFormat"
4682 Since: 2.9
4684 SshHostKeyCheckMode (Enum)
4686 "none" Don't check the host key at all "hash"
4688 Compare the host key with a given hash "known_hosts" Check the
4689 host key against the known_hosts file
4690 Values:
4692 "none"
4694 Not documented
4695 "hash"
4697 Not documented
4698 "known_hosts"
4700 Not documented
4701 Since: 2.12
4703 SshHostKeyCheckHashType (Enum)
4705 "md5" The given hash is an md5 hash "sha1" The
4707 given hash is an sha1 hash
4708 Values:
4710 "md5"
4712 Not documented
4713 "sha1"
4715 Not documented
4716 Since: 2.12
4718 SshHostKeyHash (Object)
4720 "type" The hash algorithm used for the hash "hash"
4722 The expected hash value
4723 Members:
4725 "type: SshHostKeyCheckHashType"
4727 Not documented
4728 "hash: string"
4730 Not documented
4731 Since: 2.12
4733 SshHostKeyCheck (Object)
4735 Members:
4737 "mode: SshHostKeyCheckMode"
4739 Not documented
4740 The members of "SshHostKeyHash" when "mode" is "hash"
4742 Since: 2.12
4744 BlockdevOptionsSsh (Object)
4746 Members:
4748 "server: InetSocketAddress"
4750 host address
4751 "path: string"
4753 path to the image on the host
4754 "user: string" (optional)
4756 user as which to connect, defaults to current local user name
4757 "host-key-check: SshHostKeyCheck" (optional)
4759 Defines how and what to check the host key against (default:
4760 known_hosts)
4761 Since: 2.9
4763 BlkdebugEvent (Enum)
4765 Trigger events supported by blkdebug.
4767 Values:
4769 "l1_shrink_write_table"
4771 write zeros to the l1 table to shrink image. (since 2.11)
4772 "l1_shrink_free_l2_clusters"
4774 discard the l2 tables. (since 2.11)
4775 "cor_write"
4777 a write due to copy-on-read (since 2.11)
4778 "cluster_alloc_space"
4780 an allocation of file space for a cluster (since 4.1)
4781 "none"
4783 triggers once at creation of the blkdebug node (since 4.1)
4784 "l1_update"
4786 Not documented
4787 "l1_grow_alloc_table"
4789 Not documented
4790 "l1_grow_write_table"
4792 Not documented
4793 "l1_grow_activate_table"
4795 Not documented
4796 "l2_load"
4798 Not documented
4799 "l2_update"
4801 Not documented
4802 "l2_update_compressed"
4804 Not documented
4805 "l2_alloc_cow_read"
4807 Not documented
4808 "l2_alloc_write"
4810 Not documented
4811 "read_aio"
4813 Not documented
4814 "read_backing_aio"
4816 Not documented
4817 "read_compressed"
4819 Not documented
4820 "write_aio"
4822 Not documented
4823 "write_compressed"
4825 Not documented
4826 "vmstate_load"
4828 Not documented
4829 "vmstate_save"
4831 Not documented
4832 "cow_read"
4834 Not documented
4835 "cow_write"
4837 Not documented
4838 "reftable_load"
4840 Not documented
4841 "reftable_grow"
4843 Not documented
4844 "reftable_update"
4846 Not documented
4847 "refblock_load"
4849 Not documented
4850 "refblock_update"
4852 Not documented
4853 "refblock_update_part"
4855 Not documented
4856 "refblock_alloc"
4858 Not documented
4859 "refblock_alloc_hookup"
4861 Not documented
4862 "refblock_alloc_write"
4864 Not documented
4865 "refblock_alloc_write_blocks"
4867 Not documented
4868 "refblock_alloc_write_table"
4870 Not documented
4871 "refblock_alloc_switch_table"
4873 Not documented
4874 "cluster_alloc"
4876 Not documented
4877 "cluster_alloc_bytes"
4879 Not documented
4880 "cluster_free"
4882 Not documented
4883 "flush_to_os"
4885 Not documented
4886 "flush_to_disk"
4888 Not documented
4889 "pwritev_rmw_head"
4891 Not documented
4892 "pwritev_rmw_after_head"
4894 Not documented
4895 "pwritev_rmw_tail"
4897 Not documented
4898 "pwritev_rmw_after_tail"
4900 Not documented
4901 "pwritev"
4903 Not documented
4904 "pwritev_zero"
4906 Not documented
4907 "pwritev_done"
4909 Not documented
4910 "empty_image_prepare"
4912 Not documented
4913 Since: 2.9
4915 BlkdebugIOType (Enum)
4917 Kinds of I/O that blkdebug can inject errors in.
4919 Values:
4921 "read"
4923 .bdrv_co_preadv()
4924 "write"
4926 .bdrv_co_pwritev()
4927 "write-zeroes"
4929 .bdrv_co_pwrite_zeroes()
4930 "discard"
4932 .bdrv_co_pdiscard()
4933 "flush"
4935 .bdrv_co_flush_to_disk()
4936 "block-status"
4938 .bdrv_co_block_status()
4939 Since: 4.1
4941 BlkdebugInjectErrorOptions (Object)
4943 Describes a single error injection for blkdebug.
4945 Members:
4947 "event: BlkdebugEvent"
4949 trigger event
4950 "state: int" (optional)
4952 the state identifier blkdebug needs to be in to actually trigger
4953 the event; defaults to "any"
4954 "iotype: BlkdebugIOType" (optional)
4956 the type of I/O operations on which this error should be injected;
4957 defaults to "all read, write, write-zeroes, discard, and flush
4958 operations" (since: 4.1)
4959 "errno: int" (optional)
4961 error identifier (errno) to be returned; defaults to EIO
4962 "sector: int" (optional)
4964 specifies the sector index which has to be affected in order to
4965 actually trigger the event; defaults to "any sector"
4966 "once: boolean" (optional)
4968 disables further events after this one has been triggered; defaults
4969 to false
4970 "immediately: boolean" (optional)
4972 fail immediately; defaults to false
4973 Since: 2.9
4975 BlkdebugSetStateOptions (Object)
4977 Describes a single state-change event for blkdebug.
4979 Members:
4981 "event: BlkdebugEvent"
4983 trigger event
4984 "state: int" (optional)
4986 the current state identifier blkdebug needs to be in; defaults to
4987 "any"
4988 "new_state: int"
4990 the state identifier blkdebug is supposed to assume if this event
4991 is triggered
4992 Since: 2.9
4994 BlockdevOptionsBlkdebug (Object)
4996 Driver specific block device options for blkdebug.
4998 Members:
5000 "image: BlockdevRef"
5002 underlying raw block device (or image file)
5003 "config: string" (optional)
5005 filename of the configuration file
5006 "align: int" (optional)
5008 required alignment for requests in bytes, must be positive power of
5009 2, or 0 for default
5010 "max-transfer: int" (optional)
5012 maximum size for I/O transfers in bytes, must be positive multiple
5013 of "align" and of the underlying file's request alignment (but need
5014 not be a power of 2), or 0 for default (since 2.10)
5015 "opt-write-zero: int" (optional)
5017 preferred alignment for write zero requests in bytes, must be
5018 positive multiple of "align" and of the underlying file's request
5019 alignment (but need not be a power of 2), or 0 for default (since
5020 2.10)
5021 "max-write-zero: int" (optional)
5023 maximum size for write zero requests in bytes, must be positive
5024 multiple of "align", of "opt-write-zero", and of the underlying
5025 file's request alignment (but need not be a power of 2), or 0 for
5026 default (since 2.10)
5027 "opt-discard: int" (optional)
5029 preferred alignment for discard requests in bytes, must be positive
5030 multiple of "align" and of the underlying file's request alignment
5031 (but need not be a power of 2), or 0 for default (since 2.10)
5032 "max-discard: int" (optional)
5034 maximum size for discard requests in bytes, must be positive
5035 multiple of "align", of "opt-discard", and of the underlying file's
5036 request alignment (but need not be a power of 2), or 0 for default
5037 (since 2.10)
5038 "inject-error: array of BlkdebugInjectErrorOptions" (optional)
5040 array of error injection descriptions
5041 "set-state: array of BlkdebugSetStateOptions" (optional)
5043 array of state-change descriptions
5044 Since: 2.9
5046 BlockdevOptionsBlklogwrites (Object)
5048 Driver specific block device options for blklogwrites.
5050 Members:
5052 "file: BlockdevRef"
5054 block device
5055 "log: BlockdevRef"
5057 block device used to log writes to "file"
5058 "log-sector-size: int" (optional)
5060 sector size used in logging writes to "file", determines
5061 granularity of offsets and sizes of writes (default: 512)
5062 "log-append: boolean" (optional)
5064 append to an existing log (default: false)
5065 "log-super-update-interval: int" (optional)
5067 interval of write requests after which the log super block is
5068 updated to disk (default: 4096)
5069 Since: 3.0
5071 BlockdevOptionsBlkverify (Object)
5073 Driver specific block device options for blkverify.
5075 Members:
5077 "test: BlockdevRef"
5079 block device to be tested
5080 "raw: BlockdevRef"
5082 raw image used for verification
5083 Since: 2.9
5085 BlockdevOptionsBlkreplay (Object)
5087 Driver specific block device options for blkreplay.
5089 Members:
5091 "image: BlockdevRef"
5093 disk image which should be controlled with blkreplay
5094 Since: 4.2
5096 QuorumReadPattern (Enum)
5098 An enumeration of quorum read patterns.
5100 Values:
5102 "quorum"
5104 read all the children and do a quorum vote on reads
5105 "fifo"
5107 read only from the first child that has not failed
5108 Since: 2.9
5110 BlockdevOptionsQuorum (Object)
5112 Driver specific block device options for Quorum
5114 Members:
5116 "blkverify: boolean" (optional)
5118 true if the driver must print content mismatch set to false by
5119 default
5120 "children: array of BlockdevRef"
5122 the children block devices to use
5123 "vote-threshold: int"
5125 the vote limit under which a read will fail
5126 "rewrite-corrupted: boolean" (optional)
5128 rewrite corrupted data when quorum is reached (Since 2.1)
5129 "read-pattern: QuorumReadPattern" (optional)
5131 choose read pattern and set to quorum by default (Since 2.2)
5132 Since: 2.9
5134 BlockdevOptionsGluster (Object)
5136 Driver specific block device options for Gluster
5138 Members:
5140 "volume: string"
5142 name of gluster volume where VM image resides
5143 "path: string"
5145 absolute path to image file in gluster volume
5146 "server: array of SocketAddress"
5148 gluster servers description
5149 "debug: int" (optional)
5151 libgfapi log level (default '4' which is Error) (Since 2.8)
5152 "logfile: string" (optional)
5154 libgfapi log file (default /dev/stderr) (Since 2.8)
5155 Since: 2.9
5157 IscsiTransport (Enum)
5159 An enumeration of libiscsi transport types
5161 Values:
5163 "tcp"
5165 Not documented
5166 "iser"
5168 Not documented
5169 Since: 2.9
5171 IscsiHeaderDigest (Enum)
5173 An enumeration of header digests supported by libiscsi
5175 Values:
5177 "crc32c"
5179 Not documented
5180 "none"
5182 Not documented
5183 "crc32c-none"
5185 Not documented
5186 "none-crc32c"
5188 Not documented
5189 Since: 2.9
5191 BlockdevOptionsIscsi (Object)
5193 Members:
5195 "transport: IscsiTransport"
5197 The iscsi transport type
5198 "portal: string"
5200 The address of the iscsi portal
5201 "target: string"
5203 The target iqn name
5204 "lun: int" (optional)
5206 LUN to connect to. Defaults to 0.
5207 "user: string" (optional)
5209 User name to log in with. If omitted, no CHAP authentication is
5210 performed.
5211 "password-secret: string" (optional)
5213 The ID of a QCryptoSecret object providing the password for the
5214 login. This option is required if "user" is specified.
5215 "initiator-name: string" (optional)
5217 The iqn name we want to identify to the target as. If this option
5218 is not specified, an initiator name is generated automatically.
5219 "header-digest: IscsiHeaderDigest" (optional)
5221 The desired header digest. Defaults to none-crc32c.
5222 "timeout: int" (optional)
5224 Timeout in seconds after which a request will timeout. 0 means no
5225 timeout and is the default.
5226 Driver specific block device options for iscsi
5228 Since: 2.9
5230 RbdAuthMode (Enum)
5232 Values:
5234 "cephx"
5236 Not documented
5237 "none"
5239 Not documented
5240 Since: 3.0
5242 BlockdevOptionsRbd (Object)
5244 Members:
5246 "pool: string"
5248 Ceph pool name.
5249 "image: string"
5251 Image name in the Ceph pool.
5252 "conf: string" (optional)
5254 path to Ceph configuration file. Values in the configuration file
5255 will be overridden by options specified via QAPI.
5256 "snapshot: string" (optional)
5258 Ceph snapshot name.
5259 "user: string" (optional)
5261 Ceph id name.
5262 "auth-client-required: array of RbdAuthMode" (optional)
5264 Acceptable authentication modes. This maps to Ceph configuration
5265 option "auth_client_required". (Since 3.0)
5266 "key-secret: string" (optional)
5268 ID of a QCryptoSecret object providing a key for cephx
5269 authentication. This maps to Ceph configuration option "key".
5270 (Since 3.0)
5271 "server: array of InetSocketAddressBase" (optional)
5273 Monitor host address and port. This maps to the "mon_host" Ceph
5274 option.
5275 Since: 2.9
5277 BlockdevOptionsSheepdog (Object)
5279 Driver specific block device options for sheepdog
5281 Members:
5283 "vdi: string"
5285 Virtual disk image name
5286 "server: SocketAddress"
5288 The Sheepdog server to connect to
5289 "snap-id: int" (optional)
5291 Snapshot ID
5292 "tag: string" (optional)
5294 Snapshot tag name
5295 Only one of "snap-id" and "tag" may be present.
5297 Since: 2.9
5299 ReplicationMode (Enum)
5301 An enumeration of replication modes.
5303 Values:
5305 "primary"
5307 Primary mode, the vm's state will be sent to secondary QEMU.
5308 "secondary"
5310 Secondary mode, receive the vm's state from primary QEMU.
5311 Since: 2.9
5313 If: "defined(CONFIG_REPLICATION)"
5315 BlockdevOptionsReplication (Object)
5317 Driver specific block device options for replication
5319 Members:
5321 "mode: ReplicationMode"
5323 the replication mode
5324 "top-id: string" (optional)
5326 In secondary mode, node name or device ID of the root node who owns
5327 the replication node chain. Must not be given in primary mode.
5328 The members of "BlockdevOptionsGenericFormat"
5330 Since: 2.9
5332 If: "defined(CONFIG_REPLICATION)"
5334 NFSTransport (Enum)
5336 An enumeration of NFS transport types
5338 Values:
5340 "inet"
5342 TCP transport
5343 Since: 2.9
5345 NFSServer (Object)
5347 Captures the address of the socket
5349 Members:
5351 "type: NFSTransport"
5353 transport type used for NFS (only TCP supported)
5354 "host: string"
5356 host address for NFS server
5357 Since: 2.9
5359 BlockdevOptionsNfs (Object)
5361 Driver specific block device option for NFS
5363 Members:
5365 "server: NFSServer"
5367 host address
5368 "path: string"
5370 path of the image on the host
5371 "user: int" (optional)
5373 UID value to use when talking to the server (defaults to 65534 on
5374 Windows and getuid() on unix)
5375 "group: int" (optional)
5377 GID value to use when talking to the server (defaults to 65534 on
5378 Windows and getgid() in unix)
5379 "tcp-syn-count: int" (optional)
5381 number of SYNs during the session establishment (defaults to libnfs
5382 default)
5383 "readahead-size: int" (optional)
5385 set the readahead size in bytes (defaults to libnfs default)
5386 "page-cache-size: int" (optional)
5388 set the pagecache size in bytes (defaults to libnfs default)
5389 "debug: int" (optional)
5391 set the NFS debug level (max 2) (defaults to libnfs default)
5392 Since: 2.9
5394 BlockdevOptionsCurlBase (Object)
5396 Driver specific block device options shared by all protocols supported
5398 by the curl backend.
5399 Members:
5401 "url: string"
5403 URL of the image file
5404 "readahead: int" (optional)
5406 Size of the read-ahead cache; must be a multiple of 512 (defaults
5407 to 256 kB)
5408 "timeout: int" (optional)
5410 Timeout for connections, in seconds (defaults to 5)
5411 "username: string" (optional)
5413 Username for authentication (defaults to none)
5414 "password-secret: string" (optional)
5416 ID of a QCryptoSecret object providing a password for
5417 authentication (defaults to no password)
5418 "proxy-username: string" (optional)
5420 Username for proxy authentication (defaults to none)
5421 "proxy-password-secret: string" (optional)
5423 ID of a QCryptoSecret object providing a password for proxy
5424 authentication (defaults to no password)
5425 Since: 2.9
5427 BlockdevOptionsCurlHttp (Object)
5429 Driver specific block device options for HTTP connections over the curl
5431 backend. URLs must start with "http://".
5432 Members:
5434 "cookie: string" (optional)
5436 List of cookies to set; format is "name1=content1; name2=content2;"
5437 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5438 "cookie-secret: string" (optional)
5440 ID of a QCryptoSecret object providing the cookie data in a secure
5441 way. See "cookie" for the format. (since 2.10)
5442 The members of "BlockdevOptionsCurlBase"
5444 Since: 2.9
5446 BlockdevOptionsCurlHttps (Object)
5448 Driver specific block device options for HTTPS connections over the
5450 curl backend. URLs must start with "https://".
5451 Members:
5453 "cookie: string" (optional)
5455 List of cookies to set; format is "name1=content1; name2=content2;"
5456 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5457 "sslverify: boolean" (optional)
5459 Whether to verify the SSL certificate's validity (defaults to true)
5460 "cookie-secret: string" (optional)
5462 ID of a QCryptoSecret object providing the cookie data in a secure
5463 way. See "cookie" for the format. (since 2.10)
5464 The members of "BlockdevOptionsCurlBase"
5466 Since: 2.9
5468 BlockdevOptionsCurlFtp (Object)
5470 Driver specific block device options for FTP connections over the curl
5472 backend. URLs must start with "ftp://".
5473 Members:
5475 The members of "BlockdevOptionsCurlBase"
5477 Since: 2.9
5479 BlockdevOptionsCurlFtps (Object)
5481 Driver specific block device options for FTPS connections over the curl
5483 backend. URLs must start with "ftps://".
5484 Members:
5486 "sslverify: boolean" (optional)
5488 Whether to verify the SSL certificate's validity (defaults to true)
5489 The members of "BlockdevOptionsCurlBase"
5491 Since: 2.9
5493 BlockdevOptionsNbd (Object)
5495 Driver specific block device options for NBD.
5497 Members:
5499 "server: SocketAddress"
5501 NBD server address
5502 "export: string" (optional)
5504 export name
5505 "tls-creds: string" (optional)
5507 TLS credentials ID
5508 "x-dirty-bitmap: string" (optional)
5510 A "qemu:dirty-bitmap:NAME" string to query in place of traditional
5511 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
5512 the NBD protocol) (since 3.0)
5513 "reconnect-delay: int" (optional)
5515 On an unexpected disconnect, the nbd client tries to connect again
5516 until succeeding or encountering a serious error. During the first
5517 "reconnect-delay" seconds, all requests are paused and will be
5518 rerun on a successful reconnect. After that time, any delayed
5519 requests and all future requests before a successful reconnect will
5520 immediately fail. Default 0 (Since 4.2)
5521 Since: 2.9
5523 BlockdevOptionsRaw (Object)
5525 Driver specific block device options for the raw driver.
5527 Members:
5529 "offset: int" (optional)
5531 position where the block device starts
5532 "size: int" (optional)
5534 the assumed size of the device
5535 The members of "BlockdevOptionsGenericFormat"
5537 Since: 2.9
5539 BlockdevOptionsVxHS (Object)
5541 Driver specific block device options for VxHS
5543 Members:
5545 "vdisk-id: string"
5547 UUID of VxHS volume
5548 "server: InetSocketAddressBase"
5550 vxhs server IP, port
5551 "tls-creds: string" (optional)
5553 TLS credentials ID
5554 Since: 2.10
5556 BlockdevOptionsThrottle (Object)
5558 Driver specific block device options for the throttle driver
5560 Members:
5562 "throttle-group: string"
5564 the name of the throttle-group object to use. It must already
5565 exist.
5566 "file: BlockdevRef"
5568 reference to or definition of the data source block device
5569 Since: 2.11
5571 BlockdevOptions (Object)
5573 Options for creating a block device. Many options are available for
5575 all block devices, independent of the block driver:
5576 Members:
5578 "driver: BlockdevDriver"
5580 block driver name
5581 "node-name: string" (optional)
5583 the node name of the new node (Since 2.0). This option is required
5584 on the top level of blockdev-add. Valid node names start with an
5585 alphabetic character and may contain only alphanumeric characters,
5586 '-', '.' and '_'. Their maximum length is 31 characters.
5587 "discard: BlockdevDiscardOptions" (optional)
5589 discard-related options (default: ignore)
5590 "cache: BlockdevCacheOptions" (optional)
5592 cache-related options
5593 "read-only: boolean" (optional)
5595 whether the block device should be read-only (default: false).
5596 Note that some block drivers support only read-only access, either
5597 generally or in certain configurations. In this case, the default
5598 value does not work and the option must be specified explicitly.
5599 "auto-read-only: boolean" (optional)
5601 if true and "read-only" is false, QEMU may automatically decide not
5602 to open the image read-write as requested, but fall back to read-
5603 only instead (and switch between the modes later), e.g. depending
5604 on whether the image file is writable or whether a writing user is
5605 attached to the node (default: false, since 3.1)
5606 "detect-zeroes: BlockdevDetectZeroesOptions" (optional)
5608 detect and optimize zero writes (Since 2.1) (default: off)
5609 "force-share: boolean" (optional)
5611 force share all permission on added nodes. Requires
5612 read-only=true. (Since 2.10)
5613 The members of "BlockdevOptionsBlkdebug" when "driver" is "blkdebug"
5615 The members of "BlockdevOptionsBlklogwrites" when "driver" is
5616 "blklogwrites"
5617 The members of "BlockdevOptionsBlkverify" when "driver" is "blkverify"
5618 The members of "BlockdevOptionsBlkreplay" when "driver" is "blkreplay"
5619 The members of "BlockdevOptionsGenericFormat" when "driver" is "bochs"
5620 The members of "BlockdevOptionsGenericFormat" when "driver" is "cloop"
5621 The members of "BlockdevOptionsGenericFormat" when "driver" is "copy-
5622 on-read"
5623 The members of "BlockdevOptionsGenericFormat" when "driver" is "dmg"
5624 The members of "BlockdevOptionsFile" when "driver" is "file"
5625 The members of "BlockdevOptionsCurlFtp" when "driver" is "ftp"
5626 The members of "BlockdevOptionsCurlFtps" when "driver" is "ftps"
5627 The members of "BlockdevOptionsGluster" when "driver" is "gluster"
5628 The members of "BlockdevOptionsFile" when "driver" is "host_cdrom"
5629 The members of "BlockdevOptionsFile" when "driver" is "host_device"
5630 The members of "BlockdevOptionsCurlHttp" when "driver" is "http"
5631 The members of "BlockdevOptionsCurlHttps" when "driver" is "https"
5632 The members of "BlockdevOptionsIscsi" when "driver" is "iscsi"
5633 The members of "BlockdevOptionsLUKS" when "driver" is "luks"
5634 The members of "BlockdevOptionsNbd" when "driver" is "nbd"
5635 The members of "BlockdevOptionsNfs" when "driver" is "nfs"
5636 The members of "BlockdevOptionsNull" when "driver" is "null-aio"
5637 The members of "BlockdevOptionsNull" when "driver" is "null-co"
5638 The members of "BlockdevOptionsNVMe" when "driver" is "nvme"
5639 The members of "BlockdevOptionsGenericFormat" when "driver" is
5640 "parallels"
5641 The members of "BlockdevOptionsQcow2" when "driver" is "qcow2"
5642 The members of "BlockdevOptionsQcow" when "driver" is "qcow"
5643 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is "qed"
5644 The members of "BlockdevOptionsQuorum" when "driver" is "quorum"
5645 The members of "BlockdevOptionsRaw" when "driver" is "raw"
5646 The members of "BlockdevOptionsRbd" when "driver" is "rbd"
5647 The members of "BlockdevOptionsReplication" when "driver" is
5648 "replication" (If: "defined(CONFIG_REPLICATION)")
5649 The members of "BlockdevOptionsSheepdog" when "driver" is "sheepdog"
5650 The members of "BlockdevOptionsSsh" when "driver" is "ssh"
5651 The members of "BlockdevOptionsThrottle" when "driver" is "throttle"
5652 The members of "BlockdevOptionsGenericFormat" when "driver" is "vdi"
5653 The members of "BlockdevOptionsGenericFormat" when "driver" is "vhdx"
5654 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is
5655 "vmdk"
5656 The members of "BlockdevOptionsGenericFormat" when "driver" is "vpc"
5657 The members of "BlockdevOptionsVVFAT" when "driver" is "vvfat"
5658 The members of "BlockdevOptionsVxHS" when "driver" is "vxhs"
5659 Remaining options are determined by the block driver.
5661 Since: 2.9
5663 BlockdevRef (Alternate)
5665 Reference to a block device.
5667 Members:
5669 "definition: BlockdevOptions"
5671 defines a new block device inline
5672 "reference: string"
5674 references the ID of an existing block device
5675 Since: 2.9
5677 BlockdevRefOrNull (Alternate)
5679 Reference to a block device.
5681 Members:
5683 "definition: BlockdevOptions"
5685 defines a new block device inline
5686 "reference: string"
5688 references the ID of an existing block device. An empty string
5689 means that no block device should be referenced. Deprecated; use
5690 null instead.
5691 "null: null"
5693 No block device should be referenced (since 2.10)
5694 Since: 2.9
5696 blockdev-add (Command) Creates a new block device. If the "id" option
5698 is given at the top level, a BlockBackend will be created; otherwise,
5699 "node-name" is mandatory at the top level and no BlockBackend will be
5700 created.
5701 Arguments: the members of "BlockdevOptions"
5703 Since: 2.9
5705 Example:
5707 1.
5709 -> { "execute": "blockdev-add",
5710 "arguments": {
5711 "driver": "qcow2",
5712 "node-name": "test1",
5713 "file": {
5714 "driver": "file",
5715 "filename": "test.qcow2"
5716 }
5717 }
5718 }
5719 <- { "return": {} }
5720 2.
5722 -> { "execute": "blockdev-add",
5723 "arguments": {
5724 "driver": "qcow2",
5725 "node-name": "node0",
5726 "discard": "unmap",
5727 "cache": {
5728 "direct": true
5729 },
5730 "file": {
5731 "driver": "file",
5732 "filename": "/tmp/test.qcow2"
5733 },
5734 "backing": {
5735 "driver": "raw",
5736 "file": {
5737 "driver": "file",
5738 "filename": "/dev/fdset/4"
5739 }
5740 }
5741 }
5742 }
5743 <- { "return": {} }
5745 x-blockdev-reopen (Command) Reopens a block device using the given set
5747 of options. Any option not specified will be reset to its default value
5748 regardless of its previous status. If an option cannot be changed or a
5749 particular driver does not support reopening then the command will
5750 return an error.
5751 The top-level "node-name" option (from BlockdevOptions) must be
5753 specified and is used to select the block device to be reopened. Other
5754 "node-name" options must be either omitted or set to the current name
5755 of the appropriate node. This command won't change any node name and
5756 any attempt to do it will result in an error.
5757 In the case of options that refer to child nodes, the behavior of this
5759 command depends on the value:
5760 1) A set of options (BlockdevOptions): the child is reopened with the
5762 specified set of options.
5763 2) A reference to the current child: the child is reopened using its
5765 existing set of options.
5766 3) A reference to a different node: the current child is replaced with
5768 the specified one.
5769 4) NULL: the current child (if any) is detached.
5771 Options (1) and (2) are supported in all cases, but at the moment only
5773 "backing" allows replacing or detaching an existing child.
5774 Unlike with blockdev-add, the "backing" option must always be present
5776 unless the node being reopened does not have a backing file and its
5777 image does not have a default backing file name as part of its
5778 metadata.
5779 Arguments: the members of "BlockdevOptions"
5781 Since: 4.0
5783 blockdev-del (Command) Deletes a block device that has been added
5785 using blockdev-add. The command will fail if the node is attached to a
5786 device or is otherwise being used.
5787 Arguments:
5789 "node-name: string"
5791 Name of the graph node to delete.
5792 Since: 2.9
5794 Example:
5796 -> { "execute": "blockdev-add",
5798 "arguments": {
5799 "driver": "qcow2",
5800 "node-name": "node0",
5801 "file": {
5802 "driver": "file",
5803 "filename": "test.qcow2"
5804 }
5805 }
5806 }
5807 <- { "return": {} }
5808 -> { "execute": "blockdev-del",
5810 "arguments": { "node-name": "node0" }
5811 }
5812 <- { "return": {} }
5813 BlockdevCreateOptionsFile (Object)
5815 Driver specific image creation options for file.
5817 "filename" Filename for the new image file "size"
5819 Size of the virtual disk in bytes "preallocation" Preallocation mode
5820 for the new image (default: off; allowed values: off, falloc (if
5821 defined CONFIG_POSIX_FALLOCATE), full (if defined CONFIG_POSIX))
5822 "nocow" Turn off copy-on-write (valid only on btrfs;
5823 default: off)
5824 Members:
5826 "filename: string"
5828 Not documented
5829 "size: int"
5831 Not documented
5832 "preallocation: PreallocMode" (optional)
5834 Not documented
5835 "nocow: boolean" (optional)
5837 Not documented
5838 Since: 2.12
5840 BlockdevCreateOptionsGluster (Object)
5842 Driver specific image creation options for gluster.
5844 "location" Where to store the new image file "size"
5846 Size of the virtual disk in bytes "preallocation" Preallocation mode
5847 for the new image (default: off; allowed values: off, falloc (if
5848 defined CONFIG_GLUSTERFS_FALLOCATE), full (if defined
5849 CONFIG_GLUSTERFS_ZEROFILL))
5850 Members:
5852 "location: BlockdevOptionsGluster"
5854 Not documented
5855 "size: int"
5857 Not documented
5858 "preallocation: PreallocMode" (optional)
5860 Not documented
5861 Since: 2.12
5863 BlockdevCreateOptionsLUKS (Object)
5865 Driver specific image creation options for LUKS.
5867 "file" Node to create the image format on "size"
5869 Size of the virtual disk in bytes "preallocation" Preallocation mode
5870 for the new image (since: 4.2) (default: off; allowed values: off,
5871 metadata, falloc, full)
5872 Members:
5874 "file: BlockdevRef"
5876 Not documented
5877 "size: int"
5879 Not documented
5880 "preallocation: PreallocMode" (optional)
5882 Not documented
5883 The members of "QCryptoBlockCreateOptionsLUKS"
5885 Since: 2.12
5887 BlockdevCreateOptionsNfs (Object)
5889 Driver specific image creation options for NFS.
5891 "location" Where to store the new image file "size"
5893 Size of the virtual disk in bytes
5894 Members:
5896 "location: BlockdevOptionsNfs"
5898 Not documented
5899 "size: int"
5901 Not documented
5902 Since: 2.12
5904 BlockdevCreateOptionsParallels (Object)
5906 Driver specific image creation options for parallels.
5908 "file" Node to create the image format on "size"
5910 Size of the virtual disk in bytes "cluster-size" Cluster size in
5911 bytes (default: 1 MB)
5912 Members:
5914 "file: BlockdevRef"
5916 Not documented
5917 "size: int"
5919 Not documented
5920 "cluster-size: int" (optional)
5922 Not documented
5923 Since: 2.12
5925 BlockdevCreateOptionsQcow (Object)
5927 Driver specific image creation options for qcow.
5929 "file" Node to create the image format on "size"
5931 Size of the virtual disk in bytes "backing-file" File name of the
5932 backing file if a backing file should be used "encrypt"
5933 Encryption options if the image should be encrypted
5934 Members:
5936 "file: BlockdevRef"
5938 Not documented
5939 "size: int"
5941 Not documented
5942 "backing-file: string" (optional)
5944 Not documented
5945 "encrypt: QCryptoBlockCreateOptions" (optional)
5947 Not documented
5948 Since: 2.12
5950 BlockdevQcow2Version (Enum)
5952 Values:
5954 "v2"
5956 The original QCOW2 format as introduced in qemu 0.10 (version 2)
5957 "v3"
5959 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
5960 Since: 2.12
5962 BlockdevCreateOptionsQcow2 (Object)
5964 Driver specific image creation options for qcow2.
5966 "file" Node to create the image format on "data-file"
5968 Node to use as an external data file in which all guest data is stored
5969 so that only metadata remains in the qcow2 file (since: 4.0)
5970 "data-file-raw" True if the external data file must stay valid as a
5971 standalone (read-only) raw image without looking at qcow2 metadata
5972 (default: false; since: 4.0) "size" Size of the virtual
5973 disk in bytes "version" Compatibility level (default: v3)
5974 "backing-file" File name of the backing file if a backing file
5975 should be used "backing-fmt" Name of the block driver to use for
5976 the backing file "encrypt" Encryption options if the image
5977 should be encrypted "cluster-size" qcow2 cluster size in bytes
5978 (default: 65536) "preallocation" Preallocation mode for the new
5979 image (default: off; allowed values: off, falloc, full, metadata)
5980 "lazy-refcounts" True if refcounts may be updated lazily (default:
5981 off) "refcount-bits" Width of reference counts in bits (default: 16)
5982 Members:
5984 "file: BlockdevRef"
5986 Not documented
5987 "data-file: BlockdevRef" (optional)
5989 Not documented
5990 "data-file-raw: boolean" (optional)
5992 Not documented
5993 "size: int"
5995 Not documented
5996 "version: BlockdevQcow2Version" (optional)
5998 Not documented
5999 "backing-file: string" (optional)
6001 Not documented
6002 "backing-fmt: BlockdevDriver" (optional)
6004 Not documented
6005 "encrypt: QCryptoBlockCreateOptions" (optional)
6007 Not documented
6008 "cluster-size: int" (optional)
6010 Not documented
6011 "preallocation: PreallocMode" (optional)
6013 Not documented
6014 "lazy-refcounts: boolean" (optional)
6016 Not documented
6017 "refcount-bits: int" (optional)
6019 Not documented
6020 Since: 2.12
6022 BlockdevCreateOptionsQed (Object)
6024 Driver specific image creation options for qed.
6026 "file" Node to create the image format on "size"
6028 Size of the virtual disk in bytes "backing-file" File name of the
6029 backing file if a backing file should be used "backing-fmt" Name
6030 of the block driver to use for the backing file "cluster-size"
6031 Cluster size in bytes (default: 65536) "table-size" L1/L2 table
6032 size (in clusters)
6033 Members:
6035 "file: BlockdevRef"
6037 Not documented
6038 "size: int"
6040 Not documented
6041 "backing-file: string" (optional)
6043 Not documented
6044 "backing-fmt: BlockdevDriver" (optional)
6046 Not documented
6047 "cluster-size: int" (optional)
6049 Not documented
6050 "table-size: int" (optional)
6052 Not documented
6053 Since: 2.12
6055 BlockdevCreateOptionsRbd (Object)
6057 Driver specific image creation options for rbd/Ceph.
6059 "location" Where to store the new image file. This location
6061 cannot point to a snapshot. "size" Size of the virtual
6062 disk in bytes "cluster-size" RBD object size
6063 Members:
6065 "location: BlockdevOptionsRbd"
6067 Not documented
6068 "size: int"
6070 Not documented
6071 "cluster-size: int" (optional)
6073 Not documented
6074 Since: 2.12
6076 BlockdevVmdkSubformat (Enum)
6078 Subformat options for VMDK images
6080 Values:
6082 "monolithicSparse"
6084 Single file image with sparse cluster allocation
6085 "monolithicFlat"
6087 Single flat data image and a descriptor file
6088 "twoGbMaxExtentSparse"
6090 Data is split into 2GB (per virtual LBA) sparse extent files, in
6091 addition to a descriptor file
6092 "twoGbMaxExtentFlat"
6094 Data is split into 2GB (per virtual LBA) flat extent files, in
6095 addition to a descriptor file
6096 "streamOptimized"
6098 Single file image sparse cluster allocation, optimized for
6099 streaming over network.
6100 Since: 4.0
6102 BlockdevVmdkAdapterType (Enum)
6104 Adapter type info for VMDK images
6106 Values:
6108 "ide"
6110 Not documented
6111 "buslogic"
6113 Not documented
6114 "lsilogic"
6116 Not documented
6117 "legacyESX"
6119 Not documented
6120 Since: 4.0
6122 BlockdevCreateOptionsVmdk (Object)
6124 Driver specific image creation options for VMDK.
6126 "file" Where to store the new image file. This refers to the
6128 image file for monolithcSparse and streamOptimized format, or the
6129 descriptor file for other formats. "size" Size of the virtual
6130 disk in bytes "extents" Where to store the data extents. Required
6131 for monolithcFlat, twoGbMaxExtentSparse and twoGbMaxExtentFlat formats.
6132 For monolithicFlat, only one entry is required; for twoGbMaxExtent*
6133 formats, the number of entries required is calculated as extent_number
6134 = virtual_size / 2GB. Providing more extents than will be used is an
6135 error. "subformat" The subformat of the VMDK image. Default:
6136 "monolithicSparse". "backing-file" The path of backing file. Default:
6137 no backing file is used. "adapter-type" The adapter type used to fill
6138 in the descriptor. Default: ide. "hwversion" Hardware version. The
6139 meaningful options are "4" or "6". Default: "4". "zeroed-grain"
6140 Whether to enable zeroed-grain feature for sparse subformats. Default:
6141 false.
6142 Members:
6144 "file: BlockdevRef"
6146 Not documented
6147 "size: int"
6149 Not documented
6150 "extents: array of BlockdevRef" (optional)
6152 Not documented
6153 "subformat: BlockdevVmdkSubformat" (optional)
6155 Not documented
6156 "backing-file: string" (optional)
6158 Not documented
6159 "adapter-type: BlockdevVmdkAdapterType" (optional)
6161 Not documented
6162 "hwversion: string" (optional)
6164 Not documented
6165 "zeroed-grain: boolean" (optional)
6167 Not documented
6168 Since: 4.0
6170 SheepdogRedundancyType (Enum)
6172 "full" Create a fully replicated vdi with x copies
6174 "erasure-coded" Create an erasure coded vdi with x data strips and y
6175 parity strips
6176 Values:
6178 "full"
6180 Not documented
6181 "erasure-coded"
6183 Not documented
6184 Since: 2.12
6186 SheepdogRedundancyFull (Object)
6188 "copies" Number of copies to use (between 1 and 31)
6190 Members:
6192 "copies: int"
6194 Not documented
6195 Since: 2.12
6197 SheepdogRedundancyErasureCoded (Object)
6199 "data-strips" Number of data strips to use (one of {2,4,8,16})
6201 "parity-strips" Number of parity strips to use (between 1 and 15)
6202 Members:
6204 "data-strips: int"
6206 Not documented
6207 "parity-strips: int"
6209 Not documented
6210 Since: 2.12
6212 SheepdogRedundancy (Object)
6214 Members:
6216 "type: SheepdogRedundancyType"
6218 Not documented
6219 The members of "SheepdogRedundancyFull" when "type" is "full"
6221 The members of "SheepdogRedundancyErasureCoded" when "type" is
6222 "erasure-coded"
6223 Since: 2.12
6225 BlockdevCreateOptionsSheepdog (Object)
6227 Driver specific image creation options for Sheepdog.
6229 "location" Where to store the new image file "size"
6231 Size of the virtual disk in bytes "backing-file" File name of a
6232 base image "preallocation" Preallocation mode for the new image
6233 (default: off; allowed values: off, full) "redundancy" Redundancy
6234 of the image "object-size" Object size of the image
6235 Members:
6237 "location: BlockdevOptionsSheepdog"
6239 Not documented
6240 "size: int"
6242 Not documented
6243 "backing-file: string" (optional)
6245 Not documented
6246 "preallocation: PreallocMode" (optional)
6248 Not documented
6249 "redundancy: SheepdogRedundancy" (optional)
6251 Not documented
6252 "object-size: int" (optional)
6254 Not documented
6255 Since: 2.12
6257 BlockdevCreateOptionsSsh (Object)
6259 Driver specific image creation options for SSH.
6261 "location" Where to store the new image file "size"
6263 Size of the virtual disk in bytes
6264 Members:
6266 "location: BlockdevOptionsSsh"
6268 Not documented
6269 "size: int"
6271 Not documented
6272 Since: 2.12
6274 BlockdevCreateOptionsVdi (Object)
6276 Driver specific image creation options for VDI.
6278 "file" Node to create the image format on "size"
6280 Size of the virtual disk in bytes "preallocation" Preallocation mode
6281 for the new image (default: off; allowed values: off, metadata)
6282 Members:
6284 "file: BlockdevRef"
6286 Not documented
6287 "size: int"
6289 Not documented
6290 "preallocation: PreallocMode" (optional)
6292 Not documented
6293 Since: 2.12
6295 BlockdevVhdxSubformat (Enum)
6297 Values:
6299 "dynamic"
6301 Growing image file
6302 "fixed"
6304 Preallocated fixed-size image file
6305 Since: 2.12
6307 BlockdevCreateOptionsVhdx (Object)
6309 Driver specific image creation options for vhdx.
6311 "file" Node to create the image format on "size"
6313 Size of the virtual disk in bytes "log-size" Log size in bytes,
6314 must be a multiple of 1 MB (default: 1 MB) "block-size" Block
6315 size in bytes, must be a multiple of 1 MB and not larger than 256 MB
6316 (default: automatically choose a block size depending on the image
6317 size) "subformat" vhdx subformat (default: dynamic)
6318 "block-state-zero" Force use of payload blocks of type 'ZERO'. Non-
6319 standard, but default. Do not set to 'off' when using 'qemu-img
6320 convert' with subformat=dynamic.
6321 Members:
6323 "file: BlockdevRef"
6325 Not documented
6326 "size: int"
6328 Not documented
6329 "log-size: int" (optional)
6331 Not documented
6332 "block-size: int" (optional)
6334 Not documented
6335 "subformat: BlockdevVhdxSubformat" (optional)
6337 Not documented
6338 "block-state-zero: boolean" (optional)
6340 Not documented
6341 Since: 2.12
6343 BlockdevVpcSubformat (Enum)
6345 Values:
6347 "dynamic"
6349 Growing image file
6350 "fixed"
6352 Preallocated fixed-size image file
6353 Since: 2.12
6355 BlockdevCreateOptionsVpc (Object)
6357 Driver specific image creation options for vpc (VHD).
6359 "file" Node to create the image format on "size"
6361 Size of the virtual disk in bytes "subformat" vhdx subformat
6362 (default: dynamic) "force-size" Force use of the exact byte size
6363 instead of rounding to the next size that can be represented in CHS
6364 geometry (default: false)
6365 Members:
6367 "file: BlockdevRef"
6369 Not documented
6370 "size: int"
6372 Not documented
6373 "subformat: BlockdevVpcSubformat" (optional)
6375 Not documented
6376 "force-size: boolean" (optional)
6378 Not documented
6379 Since: 2.12
6381 BlockdevCreateOptions (Object)
6383 Options for creating an image format on a given node.
6385 "driver" block driver to create the image format
6387 Members:
6389 "driver: BlockdevDriver"
6391 Not documented
6392 The members of "BlockdevCreateOptionsFile" when "driver" is "file"
6394 The members of "BlockdevCreateOptionsGluster" when "driver" is
6395 "gluster"
6396 The members of "BlockdevCreateOptionsLUKS" when "driver" is "luks"
6397 The members of "BlockdevCreateOptionsNfs" when "driver" is "nfs"
6398 The members of "BlockdevCreateOptionsParallels" when "driver" is
6399 "parallels"
6400 The members of "BlockdevCreateOptionsQcow" when "driver" is "qcow"
6401 The members of "BlockdevCreateOptionsQcow2" when "driver" is "qcow2"
6402 The members of "BlockdevCreateOptionsQed" when "driver" is "qed"
6403 The members of "BlockdevCreateOptionsRbd" when "driver" is "rbd"
6404 The members of "BlockdevCreateOptionsSheepdog" when "driver" is
6405 "sheepdog"
6406 The members of "BlockdevCreateOptionsSsh" when "driver" is "ssh"
6407 The members of "BlockdevCreateOptionsVdi" when "driver" is "vdi"
6408 The members of "BlockdevCreateOptionsVhdx" when "driver" is "vhdx"
6409 The members of "BlockdevCreateOptionsVmdk" when "driver" is "vmdk"
6410 The members of "BlockdevCreateOptionsVpc" when "driver" is "vpc"
6411 Since: 2.12
6413 blockdev-create (Command) Starts a job to create an image format on a
6415 given node. The job is automatically finalized, but a manual job-
6416 dismiss is required.
6417 Arguments:
6419 "job-id: string"
6421 Identifier for the newly created job.
6422 "options: BlockdevCreateOptions"
6424 Options for the image creation.
6425 Since: 3.0
6427 blockdev-open-tray (Command) Opens a block device's tray. If there is
6429 a block driver state tree inserted as a medium, it will become
6430 inaccessible to the guest (but it will remain associated to the block
6431 device, so closing the tray will make it accessible again).
6432 If the tray was already open before, this will be a no-op.
6434 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
6436 cases in which no such event will be generated, these include:
6437 - if the guest has locked the tray, "force" is false and the guest
6439 does not respond to the eject request
6440 - if the BlockBackend denoted by "device" does not have a guest
6442 device attached to it
6443 - if the guest device does not have an actual tray
6445 Arguments:
6447 "device: string" (optional)
6449 Block device name (deprecated, use "id" instead)
6450 "id: string" (optional)
6452 The name or QOM path of the guest device (since: 2.8)
6453 "force: boolean" (optional)
6455 if false (the default), an eject request will be sent to the guest
6456 if it has locked the tray (and the tray will not be opened
6457 immediately); if true, the tray will be opened regardless of
6458 whether it is locked
6459 Since: 2.5
6461 Example:
6463 -> { "execute": "blockdev-open-tray",
6465 "arguments": { "id": "ide0-1-0" } }
6466 <- { "timestamp": { "seconds": 1418751016,
6468 "microseconds": 716996 },
6469 "event": "DEVICE_TRAY_MOVED",
6470 "data": { "device": "ide1-cd0",
6471 "id": "ide0-1-0",
6472 "tray-open": true } }
6473 <- { "return": {} }
6475 blockdev-close-tray (Command) Closes a block device's tray. If there
6477 is a block driver state tree associated with the block device (which is
6478 currently ejected), that tree will be loaded as the medium.
6479 If the tray was already closed before, this will be a no-op.
6481 Arguments:
6483 "device: string" (optional)
6485 Block device name (deprecated, use "id" instead)
6486 "id: string" (optional)
6488 The name or QOM path of the guest device (since: 2.8)
6489 Since: 2.5
6491 Example:
6493 -> { "execute": "blockdev-close-tray",
6495 "arguments": { "id": "ide0-1-0" } }
6496 <- { "timestamp": { "seconds": 1418751345,
6498 "microseconds": 272147 },
6499 "event": "DEVICE_TRAY_MOVED",
6500 "data": { "device": "ide1-cd0",
6501 "id": "ide0-1-0",
6502 "tray-open": false } }
6503 <- { "return": {} }
6505 blockdev-remove-medium (Command) Removes a medium (a block driver
6507 state tree) from a block device. That block device's tray must
6508 currently be open (unless there is no attached guest device).
6509 If the tray is open and there is no medium inserted, this will be a no-
6511 op.
6512 Arguments:
6514 "id: string"
6516 The name or QOM path of the guest device
6517 Since: 2.12
6519 Example:
6521 -> { "execute": "blockdev-remove-medium",
6523 "arguments": { "id": "ide0-1-0" } }
6524 <- { "error": { "class": "GenericError",
6526 "desc": "Tray of device 'ide0-1-0' is not open" } }
6527 -> { "execute": "blockdev-open-tray",
6529 "arguments": { "id": "ide0-1-0" } }
6530 <- { "timestamp": { "seconds": 1418751627,
6532 "microseconds": 549958 },
6533 "event": "DEVICE_TRAY_MOVED",
6534 "data": { "device": "ide1-cd0",
6535 "id": "ide0-1-0",
6536 "tray-open": true } }
6537 <- { "return": {} }
6539 -> { "execute": "blockdev-remove-medium",
6541 "arguments": { "id": "ide0-1-0" } }
6542 <- { "return": {} }
6544 blockdev-insert-medium (Command) Inserts a medium (a block driver
6546 state tree) into a block device. That block device's tray must
6547 currently be open (unless there is no attached guest device) and there
6548 must be no medium inserted already.
6549 Arguments:
6551 "id: string"
6553 The name or QOM path of the guest device
6554 "node-name: string"
6556 name of a node in the block driver state graph
6557 Since: 2.12
6559 Example:
6561 -> { "execute": "blockdev-add",
6563 "arguments": {
6564 "node-name": "node0",
6565 "driver": "raw",
6566 "file": { "driver": "file",
6567 "filename": "fedora.iso" } } }
6568 <- { "return": {} }
6569 -> { "execute": "blockdev-insert-medium",
6571 "arguments": { "id": "ide0-1-0",
6572 "node-name": "node0" } }
6573 <- { "return": {} }
6575 BlockdevChangeReadOnlyMode (Enum)
6577 Specifies the new read-only mode of a block device subject to the
6579 "blockdev-change-medium" command.
6580 Values:
6582 "retain"
6584 Retains the current read-only mode
6585 "read-only"
6587 Makes the device read-only
6588 "read-write"
6590 Makes the device writable
6591 Since: 2.3
6593 blockdev-change-medium (Command) Changes the medium inserted into a
6595 block device by ejecting the current medium and loading a new image
6596 file which is inserted as the new medium (this command combines
6597 blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium and
6598 blockdev-close-tray).
6599 Arguments:
6601 "device: string" (optional)
6603 Block device name (deprecated, use "id" instead)
6604 "id: string" (optional)
6606 The name or QOM path of the guest device (since: 2.8)
6607 "filename: string"
6609 filename of the new image to be loaded
6610 "format: string" (optional)
6612 format to open the new image with (defaults to the probed format)
6613 "read-only-mode: BlockdevChangeReadOnlyMode" (optional)
6615 change the read-only mode of the device; defaults to 'retain'
6616 Since: 2.5
6618 Examples:
6620 1. Change a removable medium
6622 -> { "execute": "blockdev-change-medium",
6624 "arguments": { "id": "ide0-1-0",
6625 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
6626 "format": "raw" } }
6627 <- { "return": {} }
6628 2. Load a read-only medium into a writable drive
6630 -> { "execute": "blockdev-change-medium",
6632 "arguments": { "id": "floppyA",
6633 "filename": "/srv/images/ro.img",
6634 "format": "raw",
6635 "read-only-mode": "retain" } }
6636 <- { "error":
6638 { "class": "GenericError",
6639 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
6640 -> { "execute": "blockdev-change-medium",
6642 "arguments": { "id": "floppyA",
6643 "filename": "/srv/images/ro.img",
6644 "format": "raw",
6645 "read-only-mode": "read-only" } }
6646 <- { "return": {} }
6648 BlockErrorAction (Enum)
6650 An enumeration of action that has been taken when a DISK I/O occurs
6652 Values:
6654 "ignore"
6656 error has been ignored
6657 "report"
6659 error has been reported to the device
6660 "stop"
6662 error caused VM to be stopped
6663 Since: 2.1
6665 BLOCK_IMAGE_CORRUPTED (Event) Emitted when a disk image is being
6667 marked corrupt. The image can be identified by its device or node name.
6668 The 'device' field is always present for compatibility reasons, but it
6669 can be empty ("") if the image does not have a device name associated.
6670 Arguments:
6672 "device: string"
6674 device name. This is always present for compatibility reasons, but
6675 it can be empty ("") if the image does not have a device name
6676 associated.
6677 "node-name: string" (optional)
6679 node name (Since: 2.4)
6680 "msg: string"
6682 informative message for human consumption, such as the kind of
6683 corruption being detected. It should not be parsed by machine as it
6684 is not guaranteed to be stable
6685 "offset: int" (optional)
6687 if the corruption resulted from an image access, this is the host's
6688 access offset into the image
6689 "size: int" (optional)
6691 if the corruption resulted from an image access, this is the access
6692 size
6693 "fatal: boolean"
6695 if set, the image is marked corrupt and therefore unusable after
6696 this event and must be repaired (Since 2.2; before, every
6697 BLOCK_IMAGE_CORRUPTED event was fatal)
6698 Note: If action is "stop", a STOP event will eventually follow the
6700 BLOCK_IO_ERROR event.
6701 Example:
6703 <- { "event": "BLOCK_IMAGE_CORRUPTED",
6705 "data": { "device": "ide0-hd0", "node-name": "node0",
6706 "msg": "Prevented active L1 table overwrite", "offset": 196608,
6707 "size": 65536 },
6708 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
6709 Since: 1.7
6711 BLOCK_IO_ERROR (Event) Emitted when a disk I/O error occurs
6713 Arguments:
6715 "device: string"
6717 device name. This is always present for compatibility reasons, but
6718 it can be empty ("") if the image does not have a device name
6719 associated.
6720 "node-name: string" (optional)
6722 node name. Note that errors may be reported for the root node that
6723 is directly attached to a guest device rather than for the node
6724 where the error occurred. The node name is not present if the drive
6725 is empty. (Since: 2.8)
6726 "operation: IoOperationType"
6728 I/O operation
6729 "action: BlockErrorAction"
6731 action that has been taken
6732 "nospace: boolean" (optional)
6734 true if I/O error was caused due to a no-space condition. This key
6735 is only present if query-block's io-status is present, please see
6736 query-block documentation for more information (since: 2.2)
6737 "reason: string"
6739 human readable string describing the error cause. (This field is a
6740 debugging aid for humans, it should not be parsed by applications)
6741 (since: 2.2)
6742 Note: If action is "stop", a STOP event will eventually follow the
6744 BLOCK_IO_ERROR event
6745 Since: 0.13.0
6747 Example:
6749 <- { "event": "BLOCK_IO_ERROR",
6751 "data": { "device": "ide0-hd1",
6752 "node-name": "#block212",
6753 "operation": "write",
6754 "action": "stop" },
6755 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6756 BLOCK_JOB_COMPLETED (Event) Emitted when a block job has completed
6758 Arguments:
6760 "type: JobType"
6762 job type
6763 "device: string"
6765 The job identifier. Originally the device name but other values are
6766 allowed since QEMU 2.7
6767 "len: int"
6769 maximum progress value
6770 "offset: int"
6772 current progress value. On success this is equal to len. On
6773 failure this is less than len
6774 "speed: int"
6776 rate limit, bytes per second
6777 "error: string" (optional)
6779 error message. Only present on failure. This field contains a
6780 human-readable error message. There are no semantics other than
6781 that streaming has failed and clients should not try to interpret
6782 the error string
6783 Since: 1.1
6785 Example:
6787 <- { "event": "BLOCK_JOB_COMPLETED",
6789 "data": { "type": "stream", "device": "virtio-disk0",
6790 "len": 10737418240, "offset": 10737418240,
6791 "speed": 0 },
6792 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6793 BLOCK_JOB_CANCELLED (Event) Emitted when a block job has been
6795 cancelled
6796 Arguments:
6798 "type: JobType"
6800 job type
6801 "device: string"
6803 The job identifier. Originally the device name but other values are
6804 allowed since QEMU 2.7
6805 "len: int"
6807 maximum progress value
6808 "offset: int"
6810 current progress value. On success this is equal to len. On
6811 failure this is less than len
6812 "speed: int"
6814 rate limit, bytes per second
6815 Since: 1.1
6817 Example:
6819 <- { "event": "BLOCK_JOB_CANCELLED",
6821 "data": { "type": "stream", "device": "virtio-disk0",
6822 "len": 10737418240, "offset": 134217728,
6823 "speed": 0 },
6824 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6825 BLOCK_JOB_ERROR (Event) Emitted when a block job encounters an error
6827 Arguments:
6829 "device: string"
6831 The job identifier. Originally the device name but other values are
6832 allowed since QEMU 2.7
6833 "operation: IoOperationType"
6835 I/O operation
6836 "action: BlockErrorAction"
6838 action that has been taken
6839 Since: 1.3
6841 Example:
6843 <- { "event": "BLOCK_JOB_ERROR",
6845 "data": { "device": "ide0-hd1",
6846 "operation": "write",
6847 "action": "stop" },
6848 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6849 BLOCK_JOB_READY (Event) Emitted when a block job is ready to complete
6851 Arguments:
6853 "type: JobType"
6855 job type
6856 "device: string"
6858 The job identifier. Originally the device name but other values are
6859 allowed since QEMU 2.7
6860 "len: int"
6862 maximum progress value
6863 "offset: int"
6865 current progress value. On success this is equal to len. On
6866 failure this is less than len
6867 "speed: int"
6869 rate limit, bytes per second
6870 Note: The "ready to complete" status is always reset by a
6872 "BLOCK_JOB_ERROR" event
6873 Since: 1.3
6875 Example:
6877 <- { "event": "BLOCK_JOB_READY",
6879 "data": { "device": "drive0", "type": "mirror", "speed": 0,
6880 "len": 2097152, "offset": 2097152 }
6881 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6882 BLOCK_JOB_PENDING (Event) Emitted when a block job is awaiting
6884 explicit authorization to finalize graph changes via
6885 "block-job-finalize". If this job is part of a transaction, it will not
6886 emit this event until the transaction has converged first.
6887 Arguments:
6889 "type: JobType"
6891 job type
6892 "id: string"
6894 The job identifier.
6895 Since: 2.12
6897 Example:
6899 <- { "event": "BLOCK_JOB_WAITING",
6901 "data": { "device": "drive0", "type": "mirror" },
6902 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6903 PreallocMode (Enum)
6905 Preallocation mode of QEMU image file
6907 Values:
6909 "off"
6911 no preallocation
6912 "metadata"
6914 preallocate only for metadata
6915 "falloc"
6917 like "full" preallocation but allocate disk space by
6918 posix_fallocate() rather than writing data.
6919 "full"
6921 preallocate all data by writing it to the device to ensure disk
6922 space is really available. This data may or may not be zero,
6923 depending on the image format and storage. "full" preallocation
6924 also sets up metadata correctly.
6925 Since: 2.2
6927 BLOCK_WRITE_THRESHOLD (Event) Emitted when writes on block device
6929 reaches or exceeds the configured write threshold. For thin-provisioned
6930 devices, this means the device should be extended to avoid pausing for
6931 disk exhaustion. The event is one shot. Once triggered, it needs to be
6932 re-registered with another block-set-write-threshold command.
6933 Arguments:
6935 "node-name: string"
6937 graph node name on which the threshold was exceeded.
6938 "amount-exceeded: int"
6940 amount of data which exceeded the threshold, in bytes.
6941 "write-threshold: int"
6943 last configured threshold, in bytes.
6944 Since: 2.3
6946 block-set-write-threshold (Command) Change the write threshold for a
6948 block drive. An event will be delivered if a write to this block drive
6949 crosses the configured threshold. The threshold is an offset, thus
6950 must be non-negative. Default is no write threshold. Setting the
6951 threshold to zero disables it.
6952 This is useful to transparently resize thin-provisioned drives without
6954 the guest OS noticing.
6955 Arguments:
6957 "node-name: string"
6959 graph node name on which the threshold must be set.
6960 "write-threshold: int"
6962 configured threshold for the block device, bytes. Use 0 to disable
6963 the threshold.
6964 Since: 2.3
6966 Example:
6968 -> { "execute": "block-set-write-threshold",
6970 "arguments": { "node-name": "mydev",
6971 "write-threshold": 17179869184 } }
6972 <- { "return": {} }
6973 x-blockdev-change (Command) Dynamically reconfigure the block driver
6975 state graph. It can be used to add, remove, insert or replace a graph
6976 node. Currently only the Quorum driver implements this feature to add
6977 or remove its child. This is useful to fix a broken quorum child.
6978 If "node" is specified, it will be inserted under "parent". "child" may
6980 not be specified in this case. If both "parent" and "child" are
6981 specified but "node" is not, "child" will be detached from "parent".
6982 Arguments:
6984 "parent: string"
6986 the id or name of the parent node.
6987 "child: string" (optional)
6989 the name of a child under the given parent node.
6990 "node: string" (optional)
6992 the name of the node that will be added.
6993 Note: this command is experimental, and its API is not stable. It does
6995 not support all kinds of operations, all kinds of children, nor all
6996 block drivers.
6997 FIXME Removing children from a quorum node means introducing gaps in
6999 the child indices. This cannot be represented in the 'children' list of
7000 BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
7001 Warning: The data in a new quorum child MUST be consistent with that of
7003 the rest of the array.
7004 Since: 2.7
7006 Example:
7008 1. Add a new node to a quorum
7010 -> { "execute": "blockdev-add",
7011 "arguments": {
7012 "driver": "raw",
7013 "node-name": "new_node",
7014 "file": { "driver": "file",
7015 "filename": "test.raw" } } }
7016 <- { "return": {} }
7017 -> { "execute": "x-blockdev-change",
7018 "arguments": { "parent": "disk1",
7019 "node": "new_node" } }
7020 <- { "return": {} }
7021 2. Delete a quorum's node
7023 -> { "execute": "x-blockdev-change",
7024 "arguments": { "parent": "disk1",
7025 "child": "children.1" } }
7026 <- { "return": {} }
7027 x-blockdev-set-iothread (Command) Move "node" and its children into
7029 the "iothread". If "iothread" is null then move "node" and its
7030 children into the main loop.
7031 The node must not be attached to a BlockBackend.
7033 Arguments:
7035 "node-name: string"
7037 the name of the block driver node
7038 "iothread: StrOrNull"
7040 the name of the IOThread object or null for the main loop
7041 "force: boolean" (optional)
7043 true if the node and its children should be moved when a
7044 BlockBackend is already attached
7045 Note: this command is experimental and intended for test cases that
7047 need control over IOThreads only.
7048 Since: 2.12
7050 Example:
7052 1. Move a node into an IOThread
7054 -> { "execute": "x-blockdev-set-iothread",
7055 "arguments": { "node-name": "disk1",
7056 "iothread": "iothread0" } }
7057 <- { "return": {} }
7058 2. Move a node into the main loop
7060 -> { "execute": "x-blockdev-set-iothread",
7061 "arguments": { "node-name": "disk1",
7062 "iothread": null } }
7063 <- { "return": {} }
7064 Additional block stuff (VM related)
7066 BiosAtaTranslation (Enum)
7068 Policy that BIOS should use to interpret cylinder/head/sector
7070 addresses. Note that Bochs BIOS and SeaBIOS will not actually
7071 translate logical CHS to physical; instead, they will use logical block
7072 addressing.
7073 Values:
7075 "auto"
7077 If cylinder/heads/sizes are passed, choose between none and LBA
7078 depending on the size of the disk. If they are not passed, choose
7079 none if QEMU can guess that the disk had 16 or fewer heads, large
7080 if QEMU can guess that the disk had 131072 or fewer tracks across
7081 all heads (i.e. cylinders*heads<131072), otherwise LBA.
7082 "none"
7084 The physical disk geometry is equal to the logical geometry.
7085 "lba"
7087 Assume 63 sectors per track and one of 16, 32, 64, 128 or 255 heads
7088 (if fewer than 255 are enough to cover the whole disk with 1024
7089 cylinders/head). The number of cylinders/head is then computed
7090 based on the number of sectors and heads.
7091 "large"
7093 The number of cylinders per head is scaled down to 1024 by
7094 correspondingly scaling up the number of heads.
7095 "rechs"
7097 Same as "large", but first convert a 16-head geometry to 15-head,
7098 by proportionally scaling up the number of cylinders/head.
7099 Since: 2.0
7101 FloppyDriveType (Enum)
7103 Type of Floppy drive to be emulated by the Floppy Disk Controller.
7105 Values:
7107 144 1.44MB 3.5" drive
7109 288 2.88MB 3.5" drive
7111 120 1.2MB 5.25" drive
7113 "none"
7115 No drive connected
7116 "auto"
7118 Automatically determined by inserted media at boot
7119 Since: 2.6
7121 BlockdevSnapshotInternal (Object)
7123 Members:
7125 "device: string"
7127 the device name or node-name of a root node to generate the
7128 snapshot from
7129 "name: string"
7131 the name of the internal snapshot to be created
7132 Notes: In transaction, if "name" is empty, or any snapshot matching
7134 "name" exists, the operation will fail. Only some image formats support
7135 it, for example, qcow2, rbd, and sheepdog.
7136 Since: 1.7
7138 PRManagerInfo (Object)
7140 Information about a persistent reservation manager
7142 Members:
7144 "id: string"
7146 the identifier of the persistent reservation manager
7147 "connected: boolean"
7149 true if the persistent reservation manager is connected to the
7150 underlying storage or helper
7151 Since: 3.0
7153 query-pr-managers (Command) Returns a list of information about each
7155 persistent reservation manager.
7156 Returns: a list of "PRManagerInfo" for each persistent reservation
7158 manager
7159 Since: 3.0
7161 blockdev-snapshot-internal-sync (Command) Synchronously take an
7163 internal snapshot of a block device, when the format of the image used
7164 supports it. If the name is an empty string, or a snapshot with name
7165 already exists, the operation will fail.
7166 For the arguments, see the documentation of BlockdevSnapshotInternal.
7168 Returns: nothing on success
7170 If "device" is not a valid block device, GenericError
7172 If any snapshot matching "name" exists, or "name" is empty,
7174 GenericError
7175 If the format of the image used does not support it,
7177 BlockFormatFeatureNotSupported
7178 Since: 1.7
7180 Example:
7182 -> { "execute": "blockdev-snapshot-internal-sync",
7184 "arguments": { "device": "ide-hd0",
7185 "name": "snapshot0" }
7186 }
7187 <- { "return": {} }
7188 blockdev-snapshot-delete-internal-sync (Command) Synchronously delete
7190 an internal snapshot of a block device, when the format of the image
7191 used support it. The snapshot is identified by name or id or both. One
7192 of the name or id is required. Return SnapshotInfo for the successfully
7193 deleted snapshot.
7194 Arguments:
7196 "device: string"
7198 the device name or node-name of a root node to delete the snapshot
7199 from
7200 "id: string" (optional)
7202 optional the snapshot's ID to be deleted
7203 "name: string" (optional)
7205 optional the snapshot's name to be deleted
7206 Returns: SnapshotInfo on success If "device" is not a valid block
7208 device, GenericError If snapshot not found, GenericError If the format
7209 of the image used does not support it, BlockFormatFeatureNotSupported
7210 If "id" and "name" are both not specified, GenericError
7211 Since: 1.7
7213 Example:
7215 -> { "execute": "blockdev-snapshot-delete-internal-sync",
7217 "arguments": { "device": "ide-hd0",
7218 "name": "snapshot0" }
7219 }
7220 <- { "return": {
7221 "id": "1",
7222 "name": "snapshot0",
7223 "vm-state-size": 0,
7224 "date-sec": 1000012,
7225 "date-nsec": 10,
7226 "vm-clock-sec": 100,
7227 "vm-clock-nsec": 20
7228 }
7229 }
7230 eject (Command) Ejects a device from a removable drive.
7232 Arguments:
7234 "device: string" (optional)
7236 Block device name (deprecated, use "id" instead)
7237 "id: string" (optional)
7239 The name or QOM path of the guest device (since: 2.8)
7240 "force: boolean" (optional)
7242 If true, eject regardless of whether the drive is locked. If not
7243 specified, the default value is false.
7244 Returns: Nothing on success
7246 If "device" is not a valid block device, DeviceNotFound
7248 Notes: Ejecting a device with no media results in success
7250 Since: 0.14.0
7252 Example:
7254 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
7256 <- { "return": {} }
7257 nbd-server-start (Command) Start an NBD server listening on the given
7259 host and port. Block devices can then be exported using
7260 "nbd-server-add". The NBD server will present them as named exports;
7261 for example, another QEMU instance could refer to them as
7262 "nbd:HOST:PORT:exportname=NAME".
7263 Arguments:
7265 "addr: SocketAddressLegacy"
7267 Address on which to listen.
7268 "tls-creds: string" (optional)
7270 ID of the TLS credentials object (since 2.6).
7271 "tls-authz: string" (optional)
7273 ID of the QAuthZ authorization object used to validate the client's
7274 x509 distinguished name. This object is is only resolved at time of
7275 use, so can be deleted and recreated on the fly while the NBD
7276 server is active. If missing, it will default to denying access
7277 (since 4.0).
7278 Returns: error if the server is already running.
7280 Since: 1.3.0
7282 nbd-server-add (Command) Export a block node to QEMU's embedded NBD
7284 server.
7285 Arguments:
7287 "device: string"
7289 The device name or node name of the node to be exported
7290 "name: string" (optional)
7292 Export name. If unspecified, the "device" parameter is used as the
7293 export name. (Since 2.12)
7294 "writable: boolean" (optional)
7296 Whether clients should be able to write to the device via the NBD
7297 connection (default false).
7298 "bitmap: string" (optional)
7300 Also export the dirty bitmap reachable from "device", so the NBD
7301 client can use NBD_OPT_SET_META_CONTEXT with
7302 "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0)
7303 Returns: error if the server is not running, or export with the same
7305 name already exists.
7306 Since: 1.3.0
7308 NbdServerRemoveMode (Enum)
7310 Mode for removing an NBD export.
7312 Values:
7314 "safe"
7316 Remove export if there are no existing connections, fail otherwise.
7317 "hard"
7319 Drop all connections immediately and remove export.
7320 Potential additional modes to be added in the future:
7322 hide: Just hide export from new clients, leave existing connections as
7324 is. Remove export after all clients are disconnected.
7325 soft: Hide export from new clients, answer with ESHUTDOWN for all
7327 further requests from existing clients.
7328 Since: 2.12
7330 nbd-server-remove (Command) Remove NBD export by name.
7332 Arguments:
7334 "name: string"
7336 Export name.
7337 "mode: NbdServerRemoveMode" (optional)
7339 Mode of command operation. See "NbdServerRemoveMode" description.
7340 Default is 'safe'.
7341 Returns: error if
7343 - the server is not running
7345 - export is not found
7347 - mode is 'safe' and there are existing connections
7349 Since: 2.12
7351 nbd-server-stop (Command) Stop QEMU's embedded NBD server, and
7353 unregister all devices previously added via "nbd-server-add".
7354 Since: 1.3.0
7356 DEVICE_TRAY_MOVED (Event) Emitted whenever the tray of a removable
7358 device is moved by the guest or by HMP/QMP commands
7359 Arguments:
7361 "device: string"
7363 Block device name. This is always present for compatibility
7364 reasons, but it can be empty ("") if the image does not have a
7365 device name associated.
7366 "id: string"
7368 The name or QOM path of the guest device (since 2.8)
7369 "tray-open: boolean"
7371 true if the tray has been opened or false if it has been closed
7372 Since: 1.1
7374 Example:
7376 <- { "event": "DEVICE_TRAY_MOVED",
7378 "data": { "device": "ide1-cd0",
7379 "id": "/machine/unattached/device[22]",
7380 "tray-open": true
7381 },
7382 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7383 PR_MANAGER_STATUS_CHANGED (Event) Emitted whenever the connected
7385 status of a persistent reservation manager changes.
7386 Arguments:
7388 "id: string"
7390 The id of the PR manager object
7391 "connected: boolean"
7393 true if the PR manager is connected to a backend
7394 Since: 3.0
7396 Example:
7398 <- { "event": "PR_MANAGER_STATUS_CHANGED",
7400 "data": { "id": "pr-helper0",
7401 "connected": true
7402 },
7403 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
7404 QuorumOpType (Enum)
7406 An enumeration of the quorum operation types
7408 Values:
7410 "read"
7412 read operation
7413 "write"
7415 write operation
7416 "flush"
7418 flush operation
7419 Since: 2.6
7421 QUORUM_FAILURE (Event) Emitted by the Quorum block driver if it fails
7423 to establish a quorum
7424 Arguments:
7426 "reference: string"
7428 device name if defined else node name
7429 "sector-num: int"
7431 number of the first sector of the failed read operation
7432 "sectors-count: int"
7434 failed read operation sector count
7435 Note: This event is rate-limited.
7437 Since: 2.0
7439 Example:
7441 <- { "event": "QUORUM_FAILURE",
7443 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7444 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7445 QUORUM_REPORT_BAD (Event) Emitted to report a corruption of a Quorum
7447 file
7448 Arguments:
7450 "type: QuorumOpType"
7452 quorum operation type (Since 2.6)
7453 "error: string" (optional)
7455 error message. Only present on failure. This field contains a
7456 human-readable error message. There are no semantics other than
7457 that the block layer reported an error and clients should not try
7458 to interpret the error string.
7459 "node-name: string"
7461 the graph node name of the block driver state
7462 "sector-num: int"
7464 number of the first sector of the failed read operation
7465 "sectors-count: int"
7467 failed read operation sector count
7468 Note: This event is rate-limited.
7470 Since: 2.0
7472 Example:
7474 1. Read operation
7476 { "event": "QUORUM_REPORT_BAD",
7478 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7479 "type": "read" },
7480 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7481 2. Flush operation
7483 { "event": "QUORUM_REPORT_BAD",
7485 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7486 "type": "flush", "error": "Broken pipe" },
7487 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7488 Character devices
7490 ChardevInfo (Object)
7491 Information about a character device.
7493 Members:
7495 "label: string"
7497 the label of the character device
7498 "filename: string"
7500 the filename of the character device
7501 "frontend-open: boolean"
7503 shows whether the frontend device attached to this backend (eg.
7504 with the chardev=... option) is in open or closed state (since 2.1)
7505 Notes: "filename" is encoded using the QEMU command line character
7507 device encoding. See the QEMU man page for details.
7508 Since: 0.14.0
7510 query-chardev (Command) Returns information about current character
7512 devices.
7513 Returns: a list of "ChardevInfo"
7515 Since: 0.14.0
7517 Example:
7519 -> { "execute": "query-chardev" }
7521 <- {
7522 "return": [
7523 {
7524 "label": "charchannel0",
7525 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
7526 "frontend-open": false
7527 },
7528 {
7529 "label": "charmonitor",
7530 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
7531 "frontend-open": true
7532 },
7533 {
7534 "label": "charserial0",
7535 "filename": "pty:/dev/pts/2",
7536 "frontend-open": true
7537 }
7538 ]
7539 }
7540 ChardevBackendInfo (Object)
7542 Information about a character device backend
7544 Members:
7546 "name: string"
7548 The backend name
7549 Since: 2.0
7551 query-chardev-backends (Command) Returns information about character
7553 device backends.
7554 Returns: a list of "ChardevBackendInfo"
7556 Since: 2.0
7558 Example:
7560 -> { "execute": "query-chardev-backends" }
7562 <- {
7563 "return":[
7564 {
7565 "name":"udp"
7566 },
7567 {
7568 "name":"tcp"
7569 },
7570 {
7571 "name":"unix"
7572 },
7573 {
7574 "name":"spiceport"
7575 }
7576 ]
7577 }
7578 DataFormat (Enum)
7580 An enumeration of data format.
7582 Values:
7584 "utf8"
7586 Data is a UTF-8 string (RFC 3629)
7587 "base64"
7589 Data is Base64 encoded binary (RFC 3548)
7590 Since: 1.4
7592 ringbuf-write (Command) Write to a ring buffer character device.
7594 Arguments:
7596 "device: string"
7598 the ring buffer character device name
7599 "data: string"
7601 data to write
7602 "format: DataFormat" (optional)
7604 data encoding (default 'utf8').
7605 - base64: data must be base64 encoded text. Its binary decoding
7607 gets written.
7608 - utf8: data's UTF-8 encoding is written
7610 - data itself is always Unicode regardless of format, like any
7612 other string.
7613 Returns: Nothing on success
7615 Since: 1.4
7617 Example:
7619 -> { "execute": "ringbuf-write",
7621 "arguments": { "device": "foo",
7622 "data": "abcdefgh",
7623 "format": "utf8" } }
7624 <- { "return": {} }
7625 ringbuf-read (Command) Read from a ring buffer character device.
7627 Arguments:
7629 "device: string"
7631 the ring buffer character device name
7632 "size: int"
7634 how many bytes to read at most
7635 "format: DataFormat" (optional)
7637 data encoding (default 'utf8').
7638 - base64: the data read is returned in base64 encoding.
7640 - utf8: the data read is interpreted as UTF-8. Bug: can screw up
7642 when the buffer contains invalid UTF-8 sequences, NUL
7643 characters, after the ring buffer lost data, and when reading
7644 stops because the size limit is reached.
7645 - The return value is always Unicode regardless of format, like
7647 any other string.
7648 Returns: data read from the device
7650 Since: 1.4
7652 Example:
7654 -> { "execute": "ringbuf-read",
7656 "arguments": { "device": "foo",
7657 "size": 1000,
7658 "format": "utf8" } }
7659 <- { "return": "abcdefgh" }
7660 ChardevCommon (Object)
7662 Configuration shared across all chardev backends
7664 Members:
7666 "logfile: string" (optional)
7668 The name of a logfile to save output
7669 "logappend: boolean" (optional)
7671 true to append instead of truncate (default to false to truncate)
7672 Since: 2.6
7674 ChardevFile (Object)
7676 Configuration info for file chardevs.
7678 Members:
7680 "in: string" (optional)
7682 The name of the input file
7683 "out: string"
7685 The name of the output file
7686 "append: boolean" (optional)
7688 Open the file in append mode (default false to truncate) (Since
7689 2.6)
7690 The members of "ChardevCommon"
7692 Since: 1.4
7694 ChardevHostdev (Object)
7696 Configuration info for device and pipe chardevs.
7698 Members:
7700 "device: string"
7702 The name of the special file for the device, i.e. /dev/ttyS0 on
7703 Unix or COM1: on Windows
7704 The members of "ChardevCommon"
7706 Since: 1.4
7708 ChardevSocket (Object)
7710 Configuration info for (stream) socket chardevs.
7712 Members:
7714 "addr: SocketAddressLegacy"
7716 socket address to listen on (server=true) or connect to
7717 (server=false)
7718 "tls-creds: string" (optional)
7720 the ID of the TLS credentials object (since 2.6)
7721 "tls-authz: string" (optional)
7723 the ID of the QAuthZ authorization object against which the
7724 client's x509 distinguished name will be validated. This object is
7725 only resolved at time of use, so can be deleted and recreated on
7726 the fly while the chardev server is active. If missing, it will
7727 default to denying access (since 4.0)
7728 "server: boolean" (optional)
7730 create server socket (default: true)
7731 "wait: boolean" (optional)
7733 wait for incoming connection on server sockets (default: false).
7734 "nodelay: boolean" (optional)
7736 set TCP_NODELAY socket option (default: false)
7737 "telnet: boolean" (optional)
7739 enable telnet protocol on server sockets (default: false)
7740 "tn3270: boolean" (optional)
7742 enable tn3270 protocol on server sockets (default: false) (Since:
7743 2.10)
7744 "websocket: boolean" (optional)
7746 enable websocket protocol on server sockets (default: false)
7747 (Since: 3.1)
7748 "reconnect: int" (optional)
7750 For a client socket, if a socket is disconnected, then attempt a
7751 reconnect after the given number of seconds. Setting this to zero
7752 disables this function. (default: 0) (Since: 2.2)
7753 The members of "ChardevCommon"
7755 Since: 1.4
7757 ChardevUdp (Object)
7759 Configuration info for datagram socket chardevs.
7761 Members:
7763 "remote: SocketAddressLegacy"
7765 remote address
7766 "local: SocketAddressLegacy" (optional)
7768 local address
7769 The members of "ChardevCommon"
7771 Since: 1.5
7773 ChardevMux (Object)
7775 Configuration info for mux chardevs.
7777 Members:
7779 "chardev: string"
7781 name of the base chardev.
7782 The members of "ChardevCommon"
7784 Since: 1.5
7786 ChardevStdio (Object)
7788 Configuration info for stdio chardevs.
7790 Members:
7792 "signal: boolean" (optional)
7794 Allow signals (such as SIGINT triggered by ^C) be delivered to
7795 qemu. Default: true in -nographic mode, false otherwise.
7796 The members of "ChardevCommon"
7798 Since: 1.5
7800 ChardevSpiceChannel (Object)
7802 Configuration info for spice vm channel chardevs.
7804 Members:
7806 "type: string"
7808 kind of channel (for example vdagent).
7809 The members of "ChardevCommon"
7811 Since: 1.5
7813 If: "defined(CONFIG_SPICE)"
7815 ChardevSpicePort (Object)
7817 Configuration info for spice port chardevs.
7819 Members:
7821 "fqdn: string"
7823 name of the channel (see docs/spice-port-fqdn.txt)
7824 The members of "ChardevCommon"
7826 Since: 1.5
7828 If: "defined(CONFIG_SPICE)"
7830 ChardevVC (Object)
7832 Configuration info for virtual console chardevs.
7834 Members:
7836 "width: int" (optional)
7838 console width, in pixels
7839 "height: int" (optional)
7841 console height, in pixels
7842 "cols: int" (optional)
7844 console width, in chars
7845 "rows: int" (optional)
7847 console height, in chars
7848 The members of "ChardevCommon"
7850 Since: 1.5
7852 ChardevRingbuf (Object)
7854 Configuration info for ring buffer chardevs.
7856 Members:
7858 "size: int" (optional)
7860 ring buffer size, must be power of two, default is 65536
7861 The members of "ChardevCommon"
7863 Since: 1.5
7865 ChardevBackend (Object)
7867 Configuration info for the new chardev backend.
7869 Members:
7871 "type"
7873 One of "file", "serial", "parallel", "pipe", "socket", "udp",
7874 "pty", "null", "mux", "msmouse", "wctablet", "braille", "testdev",
7875 "stdio", "console", "spicevmc", "spiceport", "vc", "ringbuf",
7876 "memory"
7877 "data: ChardevFile" when "type" is "file"
7879 "data: ChardevHostdev" when "type" is "serial"
7880 "data: ChardevHostdev" when "type" is "parallel"
7881 "data: ChardevHostdev" when "type" is "pipe"
7882 "data: ChardevSocket" when "type" is "socket"
7883 "data: ChardevUdp" when "type" is "udp"
7884 "data: ChardevCommon" when "type" is "pty"
7885 "data: ChardevCommon" when "type" is "null"
7886 "data: ChardevMux" when "type" is "mux"
7887 "data: ChardevCommon" when "type" is "msmouse"
7888 "data: ChardevCommon" when "type" is "wctablet"
7889 "data: ChardevCommon" when "type" is "braille"
7890 "data: ChardevCommon" when "type" is "testdev"
7891 "data: ChardevStdio" when "type" is "stdio"
7892 "data: ChardevCommon" when "type" is "console"
7893 "data: ChardevSpiceChannel" when "type" is "spicevmc" (If:
7894 "defined(CONFIG_SPICE)")
7895 "data: ChardevSpicePort" when "type" is "spiceport" (If:
7896 "defined(CONFIG_SPICE)")
7897 "data: ChardevVC" when "type" is "vc"
7898 "data: ChardevRingbuf" when "type" is "ringbuf"
7899 "data: ChardevRingbuf" when "type" is "memory"
7900 Since: 1.4 (testdev since 2.2, wctablet since 2.9)
7902 ChardevReturn (Object)
7904 Return info about the chardev backend just created.
7906 Members:
7908 "pty: string" (optional)
7910 name of the slave pseudoterminal device, present if and only if a
7911 chardev of type 'pty' was created
7912 Since: 1.4
7914 chardev-add (Command) Add a character device backend
7916 Arguments:
7918 "id: string"
7920 the chardev's ID, must be unique
7921 "backend: ChardevBackend"
7923 backend type and parameters
7924 Returns: ChardevReturn.
7926 Since: 1.4
7928 Example:
7930 -> { "execute" : "chardev-add",
7932 "arguments" : { "id" : "foo",
7933 "backend" : { "type" : "null", "data" : {} } } }
7934 <- { "return": {} }
7935 -> { "execute" : "chardev-add",
7937 "arguments" : { "id" : "bar",
7938 "backend" : { "type" : "file",
7939 "data" : { "out" : "/tmp/bar.log" } } } }
7940 <- { "return": {} }
7941 -> { "execute" : "chardev-add",
7943 "arguments" : { "id" : "baz",
7944 "backend" : { "type" : "pty", "data" : {} } } }
7945 <- { "return": { "pty" : "/dev/pty/42" } }
7946 chardev-change (Command) Change a character device backend
7948 Arguments:
7950 "id: string"
7952 the chardev's ID, must exist
7953 "backend: ChardevBackend"
7955 new backend type and parameters
7956 Returns: ChardevReturn.
7958 Since: 2.10
7960 Example:
7962 -> { "execute" : "chardev-change",
7964 "arguments" : { "id" : "baz",
7965 "backend" : { "type" : "pty", "data" : {} } } }
7966 <- { "return": { "pty" : "/dev/pty/42" } }
7967 -> {"execute" : "chardev-change",
7969 "arguments" : {
7970 "id" : "charchannel2",
7971 "backend" : {
7972 "type" : "socket",
7973 "data" : {
7974 "addr" : {
7975 "type" : "unix" ,
7976 "data" : {
7977 "path" : "/tmp/charchannel2.socket"
7978 }
7979 },
7980 "server" : true,
7981 "wait" : false }}}}
7982 <- {"return": {}}
7983 chardev-remove (Command) Remove a character device backend
7985 Arguments:
7987 "id: string"
7989 the chardev's ID, must exist and not be in use
7990 Returns: Nothing on success
7992 Since: 1.4
7994 Example:
7996 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
7998 <- { "return": {} }
7999 chardev-send-break (Command) Send a break to a character device
8001 Arguments:
8003 "id: string"
8005 the chardev's ID, must exist
8006 Returns: Nothing on success
8008 Since: 2.10
8010 Example:
8012 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8014 <- { "return": {} }
8015 VSERPORT_CHANGE (Event) Emitted when the guest opens or closes a
8017 virtio-serial port.
8018 Arguments:
8020 "id: string"
8022 device identifier of the virtio-serial port
8023 "open: boolean"
8025 true if the guest has opened the virtio-serial port
8026 Since: 2.1
8028 Example:
8030 <- { "event": "VSERPORT_CHANGE",
8032 "data": { "id": "channel0", "open": true },
8033 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8034 Dump guest memory
8036 DumpGuestMemoryFormat (Enum)
8037 An enumeration of guest-memory-dump's format.
8039 Values:
8041 "elf"
8043 elf format
8044 "kdump-zlib"
8046 kdump-compressed format with zlib-compressed
8047 "kdump-lzo"
8049 kdump-compressed format with lzo-compressed
8050 "kdump-snappy"
8052 kdump-compressed format with snappy-compressed
8053 "win-dmp"
8055 Windows full crashdump format, can be used instead of ELF
8056 converting (since 2.13)
8057 Since: 2.0
8059 dump-guest-memory (Command) Dump guest's memory to vmcore. It is a
8061 synchronous operation that can take very long depending on the amount
8062 of guest memory.
8063 Arguments:
8065 "paging: boolean"
8067 if true, do paging to get guest's memory mapping. This allows using
8068 gdb to process the core file.
8069 IMPORTANT: this option can make QEMU allocate several gigabytes of
8071 RAM. This can happen for a large guest, or a malicious guest
8072 pretending to be large.
8073 Also, paging=true has the following limitations:
8075 1. The guest may be in a catastrophic state or can have corrupted
8077 memory, which cannot be trusted
8078 2. The guest can be in real-mode even if paging is enabled. For
8080 example, the guest uses ACPI to sleep, and ACPI sleep state
8081 goes in real-mode
8082 3. Currently only supported on i386 and x86_64.
8084 "protocol: string"
8086 the filename or file descriptor of the vmcore. The supported
8087 protocols are:
8088 1. file: the protocol starts with "file:", and the following
8090 string is the file's path.
8091 2. fd: the protocol starts with "fd:", and the following string is
8093 the fd's name.
8094 "detach: boolean" (optional)
8096 if true, QMP will return immediately rather than waiting for the
8097 dump to finish. The user can track progress using "query-dump".
8098 (since 2.6).
8099 "begin: int" (optional)
8101 if specified, the starting physical address.
8102 "length: int" (optional)
8104 if specified, the memory size, in bytes. If you don't want to dump
8105 all guest's memory, please specify the start "begin" and "length"
8106 "format: DumpGuestMemoryFormat" (optional)
8108 if specified, the format of guest memory dump. But non-elf format
8109 is conflict with paging and filter, ie. "paging", "begin" and
8110 "length" is not allowed to be specified with non-elf "format" at
8111 the same time (since 2.0)
8112 Note: All boolean arguments default to false
8114 Returns: nothing on success
8116 Since: 1.2
8118 Example:
8120 -> { "execute": "dump-guest-memory",
8122 "arguments": { "protocol": "fd:dump" } }
8123 <- { "return": {} }
8124 DumpStatus (Enum)
8126 Describe the status of a long-running background guest memory dump.
8128 Values:
8130 "none"
8132 no dump-guest-memory has started yet.
8133 "active"
8135 there is one dump running in background.
8136 "completed"
8138 the last dump has finished successfully.
8139 "failed"
8141 the last dump has failed.
8142 Since: 2.6
8144 DumpQueryResult (Object)
8146 The result format for 'query-dump'.
8148 Members:
8150 "status: DumpStatus"
8152 enum of "DumpStatus", which shows current dump status
8153 "completed: int"
8155 bytes written in latest dump (uncompressed)
8156 "total: int"
8158 total bytes to be written in latest dump (uncompressed)
8159 Since: 2.6
8161 query-dump (Command) Query latest dump status.
8163 Returns: A "DumpStatus" object showing the dump status.
8165 Since: 2.6
8167 Example:
8169 -> { "execute": "query-dump" }
8171 <- { "return": { "status": "active", "completed": 1024000,
8172 "total": 2048000 } }
8173 DUMP_COMPLETED (Event) Emitted when background dump has completed
8175 Arguments:
8177 "result: DumpQueryResult"
8179 final dump status
8180 "error: string" (optional)
8182 human-readable error string that provides hint on why dump failed.
8183 Only presents on failure. The user should not try to interpret the
8184 error string.
8185 Since: 2.6
8187 Example:
8189 { "event": "DUMP_COMPLETED",
8191 "data": {"result": {"total": 1090650112, "status": "completed",
8192 "completed": 1090650112} } }
8193 DumpGuestMemoryCapability (Object)
8195 A list of the available formats for dump-guest-memory
8197 Members:
8199 "formats: array of DumpGuestMemoryFormat"
8201 Not documented
8202 Since: 2.0
8204 query-dump-guest-memory-capability (Command) Returns the available
8206 formats for dump-guest-memory
8207 Returns: A "DumpGuestMemoryCapability" object listing available formats
8209 for dump-guest-memory
8210 Since: 2.0
8212 Example:
8214 -> { "execute": "query-dump-guest-memory-capability" }
8216 <- { "return": { "formats":
8217 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
8218 Net devices
8220 set_link (Command) Sets the link status of a virtual network adapter.
8221 Arguments:
8223 "name: string"
8225 the device name of the virtual network adapter
8226 "up: boolean"
8228 true to set the link status to be up
8229 Returns: Nothing on success If "name" is not a valid network device,
8231 DeviceNotFound
8232 Since: 0.14.0
8234 Notes: Not all network adapters support setting link status. This
8236 command will succeed even if the network adapter does not support link
8237 status notification.
8238 Example:
8240 -> { "execute": "set_link",
8242 "arguments": { "name": "e1000.0", "up": false } }
8243 <- { "return": {} }
8244 netdev_add (Command) Add a network backend.
8246 Arguments:
8248 "type: string"
8250 the type of network backend. Possible values are listed in
8251 NetClientDriver (excluding 'none' and 'nic')
8252 "id: string"
8254 the name of the new network backend
8255 Additional arguments depend on the type.
8257 TODO: This command effectively bypasses QAPI completely due to its
8259 "additional arguments" business. It shouldn't have been added to the
8260 schema in this form. It should be qapified properly, or replaced by a
8261 properly qapified command.
8262 Since: 0.14.0
8264 Returns: Nothing on success If "type" is not a valid network backend,
8266 DeviceNotFound
8267 Example:
8269 -> { "execute": "netdev_add",
8271 "arguments": { "type": "user", "id": "netdev1",
8272 "dnssearch": "example.org" } }
8273 <- { "return": {} }
8274 netdev_del (Command) Remove a network backend.
8276 Arguments:
8278 "id: string"
8280 the name of the network backend to remove
8281 Returns: Nothing on success If "id" is not a valid network backend,
8283 DeviceNotFound
8284 Since: 0.14.0
8286 Example:
8288 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
8290 <- { "return": {} }
8291 NetLegacyNicOptions (Object)
8293 Create a new Network Interface Card.
8295 Members:
8297 "netdev: string" (optional)
8299 id of -netdev to connect to
8300 "macaddr: string" (optional)
8302 MAC address
8303 "model: string" (optional)
8305 device model (e1000, rtl8139, virtio etc.)
8306 "addr: string" (optional)
8308 PCI device address
8309 "vectors: int" (optional)
8311 number of MSI-x vectors, 0 to disable MSI-X
8312 Since: 1.2
8314 NetdevUserOptions (Object)
8316 Use the user mode network stack which requires no administrator
8318 privilege to run.
8319 Members:
8321 "hostname: string" (optional)
8323 client hostname reported by the builtin DHCP server
8324 "restrict: boolean" (optional)
8326 isolate the guest from the host
8327 "ipv4: boolean" (optional)
8329 whether to support IPv4, default true for enabled (since 2.6)
8330 "ipv6: boolean" (optional)
8332 whether to support IPv6, default true for enabled (since 2.6)
8333 "ip: string" (optional)
8335 legacy parameter, use net= instead
8336 "net: string" (optional)
8338 IP network address that the guest will see, in the form
8339 addr[/netmask] The netmask is optional, and can be either in the
8340 form a.b.c.d or as a number of valid top-most bits. Default is
8341 10.0.2.0/24.
8342 "host: string" (optional)
8344 guest-visible address of the host
8345 "tftp: string" (optional)
8347 root directory of the built-in TFTP server
8348 "bootfile: string" (optional)
8350 BOOTP filename, for use with tftp=
8351 "dhcpstart: string" (optional)
8353 the first of the 16 IPs the built-in DHCP server can assign
8354 "dns: string" (optional)
8356 guest-visible address of the virtual nameserver
8357 "dnssearch: array of String" (optional)
8359 list of DNS suffixes to search, passed as DHCP option to the guest
8360 "domainname: string" (optional)
8362 guest-visible domain name of the virtual nameserver (since 3.0)
8363 "ipv6-prefix: string" (optional)
8365 IPv6 network prefix (default is fec0::) (since 2.6). The network
8366 prefix is given in the usual hexadecimal IPv6 address notation.
8367 "ipv6-prefixlen: int" (optional)
8369 IPv6 network prefix length (default is 64) (since 2.6)
8370 "ipv6-host: string" (optional)
8372 guest-visible IPv6 address of the host (since 2.6)
8373 "ipv6-dns: string" (optional)
8375 guest-visible IPv6 address of the virtual nameserver (since 2.6)
8376 "smb: string" (optional)
8378 root directory of the built-in SMB server
8379 "smbserver: string" (optional)
8381 IP address of the built-in SMB server
8382 "hostfwd: array of String" (optional)
8384 redirect incoming TCP or UDP host connections to guest endpoints
8385 "guestfwd: array of String" (optional)
8387 forward guest TCP connections
8388 "tftp-server-name: string" (optional)
8390 RFC2132 "TFTP server name" string (Since 3.1)
8391 Since: 1.2
8393 NetdevTapOptions (Object)
8395 Used to configure a host TAP network interface backend.
8397 Members:
8399 "ifname: string" (optional)
8401 interface name
8402 "fd: string" (optional)
8404 file descriptor of an already opened tap
8405 "fds: string" (optional)
8407 multiple file descriptors of already opened multiqueue capable tap
8408 "script: string" (optional)
8410 script to initialize the interface
8411 "downscript: string" (optional)
8413 script to shut down the interface
8414 "br: string" (optional)
8416 bridge name (since 2.8)
8417 "helper: string" (optional)
8419 command to execute to configure bridge
8420 "sndbuf: int" (optional)
8422 send buffer limit. Understands [TGMKkb] suffixes.
8423 "vnet_hdr: boolean" (optional)
8425 enable the IFF_VNET_HDR flag on the tap interface
8426 "vhost: boolean" (optional)
8428 enable vhost-net network accelerator
8429 "vhostfd: string" (optional)
8431 file descriptor of an already opened vhost net device
8432 "vhostfds: string" (optional)
8434 file descriptors of multiple already opened vhost net devices
8435 "vhostforce: boolean" (optional)
8437 vhost on for non-MSIX virtio guests
8438 "queues: int" (optional)
8440 number of queues to be created for multiqueue capable tap
8441 "poll-us: int" (optional)
8443 maximum number of microseconds that could be spent on busy polling
8444 for tap (since 2.7)
8445 Since: 1.2
8447 NetdevSocketOptions (Object)
8449 Socket netdevs are used to establish a network connection to another
8451 QEMU virtual machine via a TCP socket.
8452 Members:
8454 "fd: string" (optional)
8456 file descriptor of an already opened socket
8457 "listen: string" (optional)
8459 port number, and optional hostname, to listen on
8460 "connect: string" (optional)
8462 port number, and optional hostname, to connect to
8463 "mcast: string" (optional)
8465 UDP multicast address and port number
8466 "localaddr: string" (optional)
8468 source address and port for multicast and udp packets
8469 "udp: string" (optional)
8471 UDP unicast address and port number
8472 Since: 1.2
8474 NetdevL2TPv3Options (Object)
8476 Configure an Ethernet over L2TPv3 tunnel.
8478 Members:
8480 "src: string"
8482 source address
8483 "dst: string"
8485 destination address
8486 "srcport: string" (optional)
8488 source port - mandatory for udp, optional for ip
8489 "dstport: string" (optional)
8491 destination port - mandatory for udp, optional for ip
8492 "ipv6: boolean" (optional)
8494 force the use of ipv6
8495 "udp: boolean" (optional)
8497 use the udp version of l2tpv3 encapsulation
8498 "cookie64: boolean" (optional)
8500 use 64 bit coookies
8501 "counter: boolean" (optional)
8503 have sequence counter
8504 "pincounter: boolean" (optional)
8506 pin sequence counter to zero - workaround for buggy implementations
8507 or networks with packet reorder
8508 "txcookie: int" (optional)
8510 32 or 64 bit transmit cookie
8511 "rxcookie: int" (optional)
8513 32 or 64 bit receive cookie
8514 "txsession: int"
8516 32 bit transmit session
8517 "rxsession: int" (optional)
8519 32 bit receive session - if not specified set to the same value as
8520 transmit
8521 "offset: int" (optional)
8523 additional offset - allows the insertion of additional application-
8524 specific data before the packet payload
8525 Since: 2.1
8527 NetdevVdeOptions (Object)
8529 Connect to a vde switch running on the host.
8531 Members:
8533 "sock: string" (optional)
8535 socket path
8536 "port: int" (optional)
8538 port number
8539 "group: string" (optional)
8541 group owner of socket
8542 "mode: int" (optional)
8544 permissions for socket
8545 Since: 1.2
8547 NetdevBridgeOptions (Object)
8549 Connect a host TAP network interface to a host bridge device.
8551 Members:
8553 "br: string" (optional)
8555 bridge name
8556 "helper: string" (optional)
8558 command to execute to configure bridge
8559 Since: 1.2
8561 NetdevHubPortOptions (Object)
8563 Connect two or more net clients through a software hub.
8565 Members:
8567 "hubid: int"
8569 hub identifier number
8570 "netdev: string" (optional)
8572 used to connect hub to a netdev instead of a device (since 2.12)
8573 Since: 1.2
8575 NetdevNetmapOptions (Object)
8577 Connect a client to a netmap-enabled NIC or to a VALE switch port
8579 Members:
8581 "ifname: string"
8583 Either the name of an existing network interface supported by
8584 netmap, or the name of a VALE port (created on the fly). A VALE
8585 port name is in the form 'valeXXX:YYY', where XXX and YYY are non-
8586 negative integers. XXX identifies a switch and YYY identifies a
8587 port of the switch. VALE ports having the same XXX are therefore
8588 connected to the same switch.
8589 "devname: string" (optional)
8591 path of the netmap device (default: '/dev/netmap').
8592 Since: 2.0
8594 NetdevVhostUserOptions (Object)
8596 Vhost-user network backend
8598 Members:
8600 "chardev: string"
8602 name of a unix socket chardev
8603 "vhostforce: boolean" (optional)
8605 vhost on for non-MSIX virtio guests (default: false).
8606 "queues: int" (optional)
8608 number of queues to be created for multiqueue vhost-user (default:
8609 1) (Since 2.5)
8610 Since: 2.1
8612 NetClientDriver (Enum)
8614 Available netdev drivers.
8616 Values:
8618 "none"
8620 Not documented
8621 "nic"
8623 Not documented
8624 "user"
8626 Not documented
8627 "tap"
8629 Not documented
8630 "l2tpv3"
8632 Not documented
8633 "socket"
8635 Not documented
8636 "vde"
8638 Not documented
8639 "bridge"
8641 Not documented
8642 "hubport"
8644 Not documented
8645 "netmap"
8647 Not documented
8648 "vhost-user"
8650 Not documented
8651 Since: 2.7
8653 'dump': dropped in 2.12
8655 Netdev (Object)
8657 Captures the configuration of a network device.
8659 Members:
8661 "id: string"
8663 identifier for monitor commands.
8664 "type: NetClientDriver"
8666 Specify the driver used for interpreting remaining arguments.
8667 The members of "NetLegacyNicOptions" when "type" is "nic"
8669 The members of "NetdevUserOptions" when "type" is "user"
8670 The members of "NetdevTapOptions" when "type" is "tap"
8671 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
8672 The members of "NetdevSocketOptions" when "type" is "socket"
8673 The members of "NetdevVdeOptions" when "type" is "vde"
8674 The members of "NetdevBridgeOptions" when "type" is "bridge"
8675 The members of "NetdevHubPortOptions" when "type" is "hubport"
8676 The members of "NetdevNetmapOptions" when "type" is "netmap"
8677 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
8678 Since: 1.2
8680 'l2tpv3' - since 2.1
8682 NetLegacy (Object)
8684 Captures the configuration of a network device; legacy.
8686 Members:
8688 "id: string" (optional)
8690 identifier for monitor commands
8691 "name: string" (optional)
8693 identifier for monitor commands, ignored if "id" is present
8694 "opts: NetLegacyOptions"
8696 device type specific properties (legacy)
8697 Since: 1.2
8699 'vlan': dropped in 3.0
8701 NetLegacyOptionsType (Enum)
8703 Values:
8705 "none"
8707 Not documented
8708 "nic"
8710 Not documented
8711 "user"
8713 Not documented
8714 "tap"
8716 Not documented
8717 "l2tpv3"
8719 Not documented
8720 "socket"
8722 Not documented
8723 "vde"
8725 Not documented
8726 "bridge"
8728 Not documented
8729 "netmap"
8731 Not documented
8732 "vhost-user"
8734 Not documented
8735 Since: 1.2
8737 NetLegacyOptions (Object)
8739 Like Netdev, but for use only by the legacy command line options
8741 Members:
8743 "type: NetLegacyOptionsType"
8745 Not documented
8746 The members of "NetLegacyNicOptions" when "type" is "nic"
8748 The members of "NetdevUserOptions" when "type" is "user"
8749 The members of "NetdevTapOptions" when "type" is "tap"
8750 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
8751 The members of "NetdevSocketOptions" when "type" is "socket"
8752 The members of "NetdevVdeOptions" when "type" is "vde"
8753 The members of "NetdevBridgeOptions" when "type" is "bridge"
8754 The members of "NetdevNetmapOptions" when "type" is "netmap"
8755 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
8756 Since: 1.2
8758 NetFilterDirection (Enum)
8760 Indicates whether a netfilter is attached to a netdev's transmit queue
8762 or receive queue or both.
8763 Values:
8765 "all"
8767 the filter is attached both to the receive and the transmit queue
8768 of the netdev (default).
8769 "rx"
8771 the filter is attached to the receive queue of the netdev, where it
8772 will receive packets sent to the netdev.
8773 "tx"
8775 the filter is attached to the transmit queue of the netdev, where
8776 it will receive packets sent by the netdev.
8777 Since: 2.5
8779 RxState (Enum)
8781 Packets receiving state
8783 Values:
8785 "normal"
8787 filter assigned packets according to the mac-table
8788 "none"
8790 don't receive any assigned packet
8791 "all"
8793 receive all assigned packets
8794 Since: 1.6
8796 RxFilterInfo (Object)
8798 Rx-filter information for a NIC.
8800 Members:
8802 "name: string"
8804 net client name
8805 "promiscuous: boolean"
8807 whether promiscuous mode is enabled
8808 "multicast: RxState"
8810 multicast receive state
8811 "unicast: RxState"
8813 unicast receive state
8814 "vlan: RxState"
8816 vlan receive state (Since 2.0)
8817 "broadcast-allowed: boolean"
8819 whether to receive broadcast
8820 "multicast-overflow: boolean"
8822 multicast table is overflowed or not
8823 "unicast-overflow: boolean"
8825 unicast table is overflowed or not
8826 "main-mac: string"
8828 the main macaddr string
8829 "vlan-table: array of int"
8831 a list of active vlan id
8832 "unicast-table: array of string"
8834 a list of unicast macaddr string
8835 "multicast-table: array of string"
8837 a list of multicast macaddr string
8838 Since: 1.6
8840 query-rx-filter (Command) Return rx-filter information for all NICs
8842 (or for the given NIC).
8843 Arguments:
8845 "name: string" (optional)
8847 net client name
8848 Returns: list of "RxFilterInfo" for all NICs (or for the given NIC).
8850 Returns an error if the given "name" doesn't exist, or given NIC
8851 doesn't support rx-filter querying, or given net client isn't a NIC.
8852 Since: 1.6
8854 Example:
8856 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
8858 <- { "return": [
8859 {
8860 "promiscuous": true,
8861 "name": "vnet0",
8862 "main-mac": "52:54:00:12:34:56",
8863 "unicast": "normal",
8864 "vlan": "normal",
8865 "vlan-table": [
8866 4,
8867 0
8868 ],
8869 "unicast-table": [
8870 ],
8871 "multicast": "normal",
8872 "multicast-overflow": false,
8873 "unicast-overflow": false,
8874 "multicast-table": [
8875 "01:00:5e:00:00:01",
8876 "33:33:00:00:00:01",
8877 "33:33:ff:12:34:56"
8878 ],
8879 "broadcast-allowed": false
8880 }
8881 ]
8882 }
8883 NIC_RX_FILTER_CHANGED (Event) Emitted once until the 'query-rx-filter'
8885 command is executed, the first event will always be emitted
8886 Arguments:
8888 "name: string" (optional)
8890 net client name
8891 "path: string"
8893 device path
8894 Since: 1.6
8896 Example:
8898 <- { "event": "NIC_RX_FILTER_CHANGED",
8900 "data": { "name": "vnet0",
8901 "path": "/machine/peripheral/vnet0/virtio-backend" },
8902 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
8903 }
8904 AnnounceParameters (Object)
8906 Parameters for self-announce timers
8908 Members:
8910 "initial: int"
8912 Initial delay (in ms) before sending the first GARP/RARP
8913 announcement
8914 "max: int"
8916 Maximum delay (in ms) between GARP/RARP announcement packets
8917 "rounds: int"
8919 Number of self-announcement attempts
8920 "step: int"
8922 Delay increase (in ms) after each self-announcement attempt
8923 "interfaces: array of string" (optional)
8925 An optional list of interface names, which restricts the
8926 announcement to the listed interfaces. (Since 4.1)
8927 "id: string" (optional)
8929 A name to be used to identify an instance of announce-timers and to
8930 allow it to modified later. Not for use as part of the migration
8931 parameters. (Since 4.1)
8932 Since: 4.0
8934 announce-self (Command) Trigger generation of broadcast RARP frames to
8936 update network switches. This can be useful when network bonds fail-
8937 over the active slave.
8938 Arguments: the members of "AnnounceParameters"
8940 Example:
8942 -> { "execute": "announce-self",
8944 "arguments": {
8945 "initial": 50, "max": 550, "rounds": 10, "step": 50,
8946 "interfaces": ["vn2", "vn3"], "id": "bob" } }
8947 <- { "return": {} }
8948 Since: 4.0
8950 FAILOVER_NEGOTIATED (Event) Emitted when VIRTIO_NET_F_STANDBY was
8952 enabled during feature negotiation. Failover primary devices which
8953 were hidden (not hotplugged when requested) before will now be
8954 hotplugged by the virtio-net standby device.
8955 device-id: QEMU device id of the unplugged device
8957 Arguments:
8959 "device-id: string"
8961 Not documented
8962 Since: 4.2
8964 Example:
8966 <- { "event": "FAILOVER_NEGOTIATED",
8968 "data": "net1" }
8969 RDMA device
8971 RDMA_GID_STATUS_CHANGED (Event) Emitted when guest driver adds/deletes
8972 GID to/from device
8973 Arguments:
8975 "netdev: string"
8977 RoCE Network Device name
8978 "gid-status: boolean"
8980 Add or delete indication
8981 "subnet-prefix: int"
8983 Subnet Prefix
8984 "interface-id: int"
8986 Not documented
8987 "interface-id" : Interface ID
8989 Since: 4.0
8991 Example:
8993 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
8995 "event": "RDMA_GID_STATUS_CHANGED",
8996 "data":
8997 {"netdev": "bridge0",
8998 "interface-id": 15880512517475447892,
8999 "gid-status": true,
9000 "subnet-prefix": 33022}}
9001 Rocker switch device
9003 RockerSwitch (Object)
9004 Rocker switch information.
9006 Members:
9008 "name: string"
9010 switch name
9011 "id: int"
9013 switch ID
9014 "ports: int"
9016 number of front-panel ports
9017 Since: 2.4
9019 query-rocker (Command) Return rocker switch information.
9021 Arguments:
9023 "name: string"
9025 Not documented
9026 Returns: "Rocker" information
9028 Since: 2.4
9030 Example:
9032 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
9034 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
9035 RockerPortDuplex (Enum)
9037 An eumeration of port duplex states.
9039 Values:
9041 "half"
9043 half duplex
9044 "full"
9046 full duplex
9047 Since: 2.4
9049 RockerPortAutoneg (Enum)
9051 An eumeration of port autoneg states.
9053 Values:
9055 "off"
9057 autoneg is off
9058 "on"
9060 autoneg is on
9061 Since: 2.4
9063 RockerPort (Object)
9065 Rocker switch port information.
9067 Members:
9069 "name: string"
9071 port name
9072 "enabled: boolean"
9074 port is enabled for I/O
9075 "link-up: boolean"
9077 physical link is UP on port
9078 "speed: int"
9080 port link speed in Mbps
9081 "duplex: RockerPortDuplex"
9083 port link duplex
9084 "autoneg: RockerPortAutoneg"
9086 port link autoneg
9087 Since: 2.4
9089 query-rocker-ports (Command) Return rocker switch port information.
9091 Arguments:
9093 "name: string"
9095 Not documented
9096 Returns: a list of "RockerPort" information
9098 Since: 2.4
9100 Example:
9102 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
9104 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
9105 "autoneg": "off", "link-up": true, "speed": 10000},
9106 {"duplex": "full", "enabled": true, "name": "sw1.2",
9107 "autoneg": "off", "link-up": true, "speed": 10000}
9108 ]}
9109 RockerOfDpaFlowKey (Object)
9111 Rocker switch OF-DPA flow key
9113 Members:
9115 "priority: int"
9117 key priority, 0 being lowest priority
9118 "tbl-id: int"
9120 flow table ID
9121 "in-pport: int" (optional)
9123 physical input port
9124 "tunnel-id: int" (optional)
9126 tunnel ID
9127 "vlan-id: int" (optional)
9129 VLAN ID
9130 "eth-type: int" (optional)
9132 Ethernet header type
9133 "eth-src: string" (optional)
9135 Ethernet header source MAC address
9136 "eth-dst: string" (optional)
9138 Ethernet header destination MAC address
9139 "ip-proto: int" (optional)
9141 IP Header protocol field
9142 "ip-tos: int" (optional)
9144 IP header TOS field
9145 "ip-dst: string" (optional)
9147 IP header destination address
9148 Note: optional members may or may not appear in the flow key depending
9150 if they're relevant to the flow key.
9151 Since: 2.4
9153 RockerOfDpaFlowMask (Object)
9155 Rocker switch OF-DPA flow mask
9157 Members:
9159 "in-pport: int" (optional)
9161 physical input port
9162 "tunnel-id: int" (optional)
9164 tunnel ID
9165 "vlan-id: int" (optional)
9167 VLAN ID
9168 "eth-src: string" (optional)
9170 Ethernet header source MAC address
9171 "eth-dst: string" (optional)
9173 Ethernet header destination MAC address
9174 "ip-proto: int" (optional)
9176 IP Header protocol field
9177 "ip-tos: int" (optional)
9179 IP header TOS field
9180 Note: optional members may or may not appear in the flow mask depending
9182 if they're relevant to the flow mask.
9183 Since: 2.4
9185 RockerOfDpaFlowAction (Object)
9187 Rocker switch OF-DPA flow action
9189 Members:
9191 "goto-tbl: int" (optional)
9193 next table ID
9194 "group-id: int" (optional)
9196 group ID
9197 "tunnel-lport: int" (optional)
9199 tunnel logical port ID
9200 "vlan-id: int" (optional)
9202 VLAN ID
9203 "new-vlan-id: int" (optional)
9205 new VLAN ID
9206 "out-pport: int" (optional)
9208 physical output port
9209 Note: optional members may or may not appear in the flow action
9211 depending if they're relevant to the flow action.
9212 Since: 2.4
9214 RockerOfDpaFlow (Object)
9216 Rocker switch OF-DPA flow
9218 Members:
9220 "cookie: int"
9222 flow unique cookie ID
9223 "hits: int"
9225 count of matches (hits) on flow
9226 "key: RockerOfDpaFlowKey"
9228 flow key
9229 "mask: RockerOfDpaFlowMask"
9231 flow mask
9232 "action: RockerOfDpaFlowAction"
9234 flow action
9235 Since: 2.4
9237 query-rocker-of-dpa-flows (Command) Return rocker OF-DPA flow
9239 information.
9240 Arguments:
9242 "name: string"
9244 switch name
9245 "tbl-id: int" (optional)
9247 flow table ID. If tbl-id is not specified, returns flow
9248 information for all tables.
9249 Returns: rocker OF-DPA flow information
9251 Since: 2.4
9253 Example:
9255 -> { "execute": "query-rocker-of-dpa-flows",
9257 "arguments": { "name": "sw1" } }
9258 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
9259 "hits": 138,
9260 "cookie": 0,
9261 "action": {"goto-tbl": 10},
9262 "mask": {"in-pport": 4294901760}
9263 },
9264 {...more...},
9265 ]}
9266 RockerOfDpaGroup (Object)
9268 Rocker switch OF-DPA group
9270 Members:
9272 "id: int"
9274 group unique ID
9275 "type: int"
9277 group type
9278 "vlan-id: int" (optional)
9280 VLAN ID
9281 "pport: int" (optional)
9283 physical port number
9284 "index: int" (optional)
9286 group index, unique with group type
9287 "out-pport: int" (optional)
9289 output physical port number
9290 "group-id: int" (optional)
9292 next group ID
9293 "set-vlan-id: int" (optional)
9295 VLAN ID to set
9296 "pop-vlan: int" (optional)
9298 pop VLAN headr from packet
9299 "group-ids: array of int" (optional)
9301 list of next group IDs
9302 "set-eth-src: string" (optional)
9304 set source MAC address in Ethernet header
9305 "set-eth-dst: string" (optional)
9307 set destination MAC address in Ethernet header
9308 "ttl-check: int" (optional)
9310 perform TTL check
9311 Note: optional members may or may not appear in the group depending if
9313 they're relevant to the group type.
9314 Since: 2.4
9316 query-rocker-of-dpa-groups (Command) Return rocker OF-DPA group
9318 information.
9319 Arguments:
9321 "name: string"
9323 switch name
9324 "type: int" (optional)
9326 group type. If type is not specified, returns group information
9327 for all group types.
9328 Returns: rocker OF-DPA group information
9330 Since: 2.4
9332 Example:
9334 -> { "execute": "query-rocker-of-dpa-groups",
9336 "arguments": { "name": "sw1" } }
9337 <- { "return": [ {"type": 0, "out-pport": 2,
9338 "pport": 2, "vlan-id": 3841,
9339 "pop-vlan": 1, "id": 251723778},
9340 {"type": 0, "out-pport": 0,
9341 "pport": 0, "vlan-id": 3841,
9342 "pop-vlan": 1, "id": 251723776},
9343 {"type": 0, "out-pport": 1,
9344 "pport": 1, "vlan-id": 3840,
9345 "pop-vlan": 1, "id": 251658241},
9346 {"type": 0, "out-pport": 0,
9347 "pport": 0, "vlan-id": 3840,
9348 "pop-vlan": 1, "id": 251658240}
9349 ]}
9350 TPM (trusted platform module) devices
9352 TpmModel (Enum)
9353 An enumeration of TPM models
9355 Values:
9357 "tpm-tis"
9359 TPM TIS model
9360 "tpm-crb"
9362 TPM CRB model (since 2.12)
9363 Since: 1.5
9365 query-tpm-models (Command) Return a list of supported TPM models
9367 Returns: a list of TpmModel
9369 Since: 1.5
9371 Example:
9373 -> { "execute": "query-tpm-models" }
9375 <- { "return": [ "tpm-tis", "tpm-crb" ] }
9376 TpmType (Enum)
9378 An enumeration of TPM types
9380 Values:
9382 "passthrough"
9384 TPM passthrough type
9385 "emulator"
9387 Software Emulator TPM type Since: 2.11
9388 Since: 1.5
9390 query-tpm-types (Command) Return a list of supported TPM types
9392 Returns: a list of TpmType
9394 Since: 1.5
9396 Example:
9398 -> { "execute": "query-tpm-types" }
9400 <- { "return": [ "passthrough", "emulator" ] }
9401 TPMPassthroughOptions (Object)
9403 Information about the TPM passthrough type
9405 Members:
9407 "path: string" (optional)
9409 string describing the path used for accessing the TPM device
9410 "cancel-path: string" (optional)
9412 string showing the TPM's sysfs cancel file for cancellation of TPM
9413 commands while they are executing
9414 Since: 1.5
9416 TPMEmulatorOptions (Object)
9418 Information about the TPM emulator type
9420 Members:
9422 "chardev: string"
9424 Name of a unix socket chardev
9425 Since: 2.11
9427 TpmTypeOptions (Object)
9429 A union referencing different TPM backend types' configuration options
9431 Members:
9433 "type"
9435 'passthrough' The configuration options for the TPM passthrough
9436 type 'emulator' The configuration options for TPM emulator backend
9437 type
9438 "data: TPMPassthroughOptions" when "type" is "passthrough"
9440 "data: TPMEmulatorOptions" when "type" is "emulator"
9441 Since: 1.5
9443 TPMInfo (Object)
9445 Information about the TPM
9447 Members:
9449 "id: string"
9451 The Id of the TPM
9452 "model: TpmModel"
9454 The TPM frontend model
9455 "options: TpmTypeOptions"
9457 The TPM (backend) type configuration options
9458 Since: 1.5
9460 query-tpm (Command) Return information about the TPM device
9462 Returns: "TPMInfo" on success
9464 Since: 1.5
9466 Example:
9468 -> { "execute": "query-tpm" }
9470 <- { "return":
9471 [
9472 { "model": "tpm-tis",
9473 "options":
9474 { "type": "passthrough",
9475 "data":
9476 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
9477 "path": "/dev/tpm0"
9478 }
9479 },
9480 "id": "tpm0"
9481 }
9482 ]
9483 }
9484 Remote desktop
9486 set_password (Command) Sets the password of a remote display session.
9487 Arguments:
9489 "protocol: string"
9491 `vnc' to modify the VNC server password `spice' to modify the Spice
9492 server password
9493 "password: string"
9495 the new password
9496 "connected: string" (optional)
9498 how to handle existing clients when changing the password. If
9499 nothing is specified, defaults to `keep' `fail' to fail the command
9500 if clients are connected `disconnect' to disconnect existing
9501 clients `keep' to maintain existing clients
9502 Returns: Nothing on success If Spice is not enabled, DeviceNotFound
9504 Since: 0.14.0
9506 Example:
9508 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
9510 "password": "secret" } }
9511 <- { "return": {} }
9512 expire_password (Command) Expire the password of a remote display
9514 server.
9515 Arguments:
9517 "protocol: string"
9519 the name of the remote display protocol `vnc' or `spice'
9520 "time: string"
9522 when to expire the password. `now' to expire the password
9523 immediately `never' to cancel password expiration `+INT' where INT
9524 is the number of seconds from now (integer) `INT' where INT is the
9525 absolute time in seconds
9526 Returns: Nothing on success If "protocol" is `spice' and Spice is not
9528 active, DeviceNotFound
9529 Since: 0.14.0
9531 Notes: Time is relative to the server and currently there is no way to
9533 coordinate server time with client time. It is not recommended to use
9534 the absolute time version of the "time" parameter unless you're sure
9535 you are on the same machine as the QEMU instance.
9536 Example:
9538 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
9540 "time": "+60" } }
9541 <- { "return": {} }
9542 screendump (Command) Write a PPM of the VGA screen to a file.
9544 Arguments:
9546 "filename: string"
9548 the path of a new PPM file to store the image
9549 "device: string" (optional)
9551 ID of the display device that should be dumped. If this parameter
9552 is missing, the primary display will be used. (Since 2.12)
9553 "head: int" (optional)
9555 head to use in case the device supports multiple heads. If this
9556 parameter is missing, head #0 will be used. Also note that the head
9557 can only be specified in conjunction with the device ID. (Since
9558 2.12)
9559 Returns: Nothing on success
9561 Since: 0.14.0
9563 Example:
9565 -> { "execute": "screendump",
9567 "arguments": { "filename": "/tmp/image" } }
9568 <- { "return": {} }
9569 Spice
9571 SpiceBasicInfo (Object)
9573 The basic information for SPICE network connection
9575 Members:
9577 "host: string"
9579 IP address
9580 "port: string"
9582 port number
9583 "family: NetworkAddressFamily"
9585 address family
9586 Since: 2.1
9588 If: "defined(CONFIG_SPICE)"
9590 SpiceServerInfo (Object)
9592 Information about a SPICE server
9594 Members:
9596 "auth: string" (optional)
9598 authentication method
9599 The members of "SpiceBasicInfo"
9601 Since: 2.1
9603 If: "defined(CONFIG_SPICE)"
9605 SpiceChannel (Object)
9607 Information about a SPICE client channel.
9609 Members:
9611 "connection-id: int"
9613 SPICE connection id number. All channels with the same id belong
9614 to the same SPICE session.
9615 "channel-type: int"
9617 SPICE channel type number. "1" is the main control channel, filter
9618 for this one if you want to track spice sessions only
9619 "channel-id: int"
9621 SPICE channel ID number. Usually "0", might be different when
9622 multiple channels of the same type exist, such as multiple display
9623 channels in a multihead setup
9624 "tls: boolean"
9626 true if the channel is encrypted, false otherwise.
9627 The members of "SpiceBasicInfo"
9629 Since: 0.14.0
9631 If: "defined(CONFIG_SPICE)"
9633 SpiceQueryMouseMode (Enum)
9635 An enumeration of Spice mouse states.
9637 Values:
9639 "client"
9641 Mouse cursor position is determined by the client.
9642 "server"
9644 Mouse cursor position is determined by the server.
9645 "unknown"
9647 No information is available about mouse mode used by the spice
9648 server.
9649 Note: spice/enums.h has a SpiceMouseMode already, hence the name.
9651 Since: 1.1
9653 If: "defined(CONFIG_SPICE)"
9655 SpiceInfo (Object)
9657 Information about the SPICE session.
9659 Members:
9661 "enabled: boolean"
9663 true if the SPICE server is enabled, false otherwise
9664 "migrated: boolean"
9666 true if the last guest migration completed and spice migration had
9667 completed as well. false otherwise. (since 1.4)
9668 "host: string" (optional)
9670 The hostname the SPICE server is bound to. This depends on the
9671 name resolution on the host and may be an IP address.
9672 "port: int" (optional)
9674 The SPICE server's port number.
9675 "compiled-version: string" (optional)
9677 SPICE server version.
9678 "tls-port: int" (optional)
9680 The SPICE server's TLS port number.
9681 "auth: string" (optional)
9683 the current authentication type used by the server 'none' if no
9684 authentication is being used 'spice' uses SASL or direct TLS
9685 authentication, depending on command line options
9686 "mouse-mode: SpiceQueryMouseMode"
9688 The mode in which the mouse cursor is displayed currently. Can be
9689 determined by the client or the server, or unknown if spice server
9690 doesn't provide this information. (since: 1.1)
9691 "channels: array of SpiceChannel" (optional)
9693 a list of "SpiceChannel" for each active spice channel
9694 Since: 0.14.0
9696 If: "defined(CONFIG_SPICE)"
9698 query-spice (Command) Returns information about the current SPICE
9700 server
9701 Returns: "SpiceInfo"
9703 Since: 0.14.0
9705 Example:
9707 -> { "execute": "query-spice" }
9709 <- { "return": {
9710 "enabled": true,
9711 "auth": "spice",
9712 "port": 5920,
9713 "tls-port": 5921,
9714 "host": "0.0.0.0",
9715 "channels": [
9716 {
9717 "port": "54924",
9718 "family": "ipv4",
9719 "channel-type": 1,
9720 "connection-id": 1804289383,
9721 "host": "127.0.0.1",
9722 "channel-id": 0,
9723 "tls": true
9724 },
9725 {
9726 "port": "36710",
9727 "family": "ipv4",
9728 "channel-type": 4,
9729 "connection-id": 1804289383,
9730 "host": "127.0.0.1",
9731 "channel-id": 0,
9732 "tls": false
9733 },
9734 [ ... more channels follow ... ]
9735 ]
9736 }
9737 }
9738 If: "defined(CONFIG_SPICE)"
9740 SPICE_CONNECTED (Event) Emitted when a SPICE client establishes a
9742 connection
9743 Arguments:
9745 "server: SpiceBasicInfo"
9747 server information
9748 "client: SpiceBasicInfo"
9750 client information
9751 Since: 0.14.0
9753 Example:
9755 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
9757 "event": "SPICE_CONNECTED",
9758 "data": {
9759 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
9760 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
9761 }}
9762 If: "defined(CONFIG_SPICE)"
9764 SPICE_INITIALIZED (Event) Emitted after initial handshake and
9766 authentication takes place (if any) and the SPICE channel is up and
9767 running
9768 Arguments:
9770 "server: SpiceServerInfo"
9772 server information
9773 "client: SpiceChannel"
9775 client information
9776 Since: 0.14.0
9778 Example:
9780 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
9782 "event": "SPICE_INITIALIZED",
9783 "data": {"server": {"auth": "spice", "port": "5921",
9784 "family": "ipv4", "host": "127.0.0.1"},
9785 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
9786 "connection-id": 1804289383, "host": "127.0.0.1",
9787 "channel-id": 0, "tls": true}
9788 }}
9789 If: "defined(CONFIG_SPICE)"
9791 SPICE_DISCONNECTED (Event) Emitted when the SPICE connection is closed
9793 Arguments:
9795 "server: SpiceBasicInfo"
9797 server information
9798 "client: SpiceBasicInfo"
9800 client information
9801 Since: 0.14.0
9803 Example:
9805 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
9807 "event": "SPICE_DISCONNECTED",
9808 "data": {
9809 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
9810 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
9811 }}
9812 If: "defined(CONFIG_SPICE)"
9814 SPICE_MIGRATE_COMPLETED (Event) Emitted when SPICE migration has
9816 completed
9817 Since: 1.3
9819 Example:
9821 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
9823 "event": "SPICE_MIGRATE_COMPLETED" }
9824 If: "defined(CONFIG_SPICE)"
9826 VNC
9828 VncBasicInfo (Object)
9830 The basic information for vnc network connection
9832 Members:
9834 "host: string"
9836 IP address
9837 "service: string"
9839 The service name of the vnc port. This may depend on the host
9840 system's service database so symbolic names should not be relied
9841 on.
9842 "family: NetworkAddressFamily"
9844 address family
9845 "websocket: boolean"
9847 true in case the socket is a websocket (since 2.3).
9848 Since: 2.1
9850 If: "defined(CONFIG_VNC)"
9852 VncServerInfo (Object)
9854 The network connection information for server
9856 Members:
9858 "auth: string" (optional)
9860 authentication method used for the plain (non-websocket) VNC server
9861 The members of "VncBasicInfo"
9863 Since: 2.1
9865 If: "defined(CONFIG_VNC)"
9867 VncClientInfo (Object)
9869 Information about a connected VNC client.
9871 Members:
9873 "x509_dname: string" (optional)
9875 If x509 authentication is in use, the Distinguished Name of the
9876 client.
9877 "sasl_username: string" (optional)
9879 If SASL authentication is in use, the SASL username used for
9880 authentication.
9881 The members of "VncBasicInfo"
9883 Since: 0.14.0
9885 If: "defined(CONFIG_VNC)"
9887 VncInfo (Object)
9889 Information about the VNC session.
9891 Members:
9893 "enabled: boolean"
9895 true if the VNC server is enabled, false otherwise
9896 "host: string" (optional)
9898 The hostname the VNC server is bound to. This depends on the name
9899 resolution on the host and may be an IP address.
9900 "family: NetworkAddressFamily" (optional)
9902 'ipv6' if the host is listening for IPv6 connections 'ipv4' if the
9903 host is listening for IPv4 connections 'unix' if the host is
9904 listening on a unix domain socket 'unknown' otherwise
9905 "service: string" (optional)
9907 The service name of the server's port. This may depends on the
9908 host system's service database so symbolic names should not be
9909 relied on.
9910 "auth: string" (optional)
9912 the current authentication type used by the server 'none' if no
9913 authentication is being used 'vnc' if VNC authentication is being
9914 used 'vencrypt+plain' if VEncrypt is used with plain text
9915 authentication 'vencrypt+tls+none' if VEncrypt is used with TLS and
9916 no authentication 'vencrypt+tls+vnc' if VEncrypt is used with TLS
9917 and VNC authentication 'vencrypt+tls+plain' if VEncrypt is used
9918 with TLS and plain text auth 'vencrypt+x509+none' if VEncrypt is
9919 used with x509 and no auth 'vencrypt+x509+vnc' if VEncrypt is used
9920 with x509 and VNC auth 'vencrypt+x509+plain' if VEncrypt is used
9921 with x509 and plain text auth 'vencrypt+tls+sasl' if VEncrypt is
9922 used with TLS and SASL auth 'vencrypt+x509+sasl' if VEncrypt is
9923 used with x509 and SASL auth
9924 "clients: array of VncClientInfo" (optional)
9926 a list of "VncClientInfo" of all currently connected clients
9927 Since: 0.14.0
9929 If: "defined(CONFIG_VNC)"
9931 VncPrimaryAuth (Enum)
9933 vnc primary authentication method.
9935 Values:
9937 "none"
9939 Not documented
9940 "vnc"
9942 Not documented
9943 "ra2"
9945 Not documented
9946 "ra2ne"
9948 Not documented
9949 "tight"
9951 Not documented
9952 "ultra"
9954 Not documented
9955 "tls"
9957 Not documented
9958 "vencrypt"
9960 Not documented
9961 "sasl"
9963 Not documented
9964 Since: 2.3
9966 If: "defined(CONFIG_VNC)"
9968 VncVencryptSubAuth (Enum)
9970 vnc sub authentication method with vencrypt.
9972 Values:
9974 "plain"
9976 Not documented
9977 "tls-none"
9979 Not documented
9980 "x509-none"
9982 Not documented
9983 "tls-vnc"
9985 Not documented
9986 "x509-vnc"
9988 Not documented
9989 "tls-plain"
9991 Not documented
9992 "x509-plain"
9994 Not documented
9995 "tls-sasl"
9997 Not documented
9998 "x509-sasl"
10000 Not documented
10001 Since: 2.3
10003 If: "defined(CONFIG_VNC)"
10005 VncServerInfo2 (Object)
10007 The network connection information for server
10009 Members:
10011 "auth: VncPrimaryAuth"
10013 The current authentication type used by the servers
10014 "vencrypt: VncVencryptSubAuth" (optional)
10016 The vencrypt sub authentication type used by the servers, only
10017 specified in case auth == vencrypt.
10018 The members of "VncBasicInfo"
10020 Since: 2.9
10022 If: "defined(CONFIG_VNC)"
10024 VncInfo2 (Object)
10026 Information about a vnc server
10028 Members:
10030 "id: string"
10032 vnc server name.
10033 "server: array of VncServerInfo2"
10035 A list of "VncBasincInfo" describing all listening sockets. The
10036 list can be empty (in case the vnc server is disabled). It also
10037 may have multiple entries: normal + websocket, possibly also ipv4 +
10038 ipv6 in the future.
10039 "clients: array of VncClientInfo"
10041 A list of "VncClientInfo" of all currently connected clients. The
10042 list can be empty, for obvious reasons.
10043 "auth: VncPrimaryAuth"
10045 The current authentication type used by the non-websockets servers
10046 "vencrypt: VncVencryptSubAuth" (optional)
10048 The vencrypt authentication type used by the servers, only
10049 specified in case auth == vencrypt.
10050 "display: string" (optional)
10052 The display device the vnc server is linked to.
10053 Since: 2.3
10055 If: "defined(CONFIG_VNC)"
10057 query-vnc (Command) Returns information about the current VNC server
10059 Returns: "VncInfo"
10061 Since: 0.14.0
10063 Example:
10065 -> { "execute": "query-vnc" }
10067 <- { "return": {
10068 "enabled":true,
10069 "host":"0.0.0.0",
10070 "service":"50402",
10071 "auth":"vnc",
10072 "family":"ipv4",
10073 "clients":[
10074 {
10075 "host":"127.0.0.1",
10076 "service":"50401",
10077 "family":"ipv4"
10078 }
10079 ]
10080 }
10081 }
10082 If: "defined(CONFIG_VNC)"
10084 query-vnc-servers (Command) Returns a list of vnc servers. The list
10086 can be empty.
10087 Returns: a list of "VncInfo2"
10089 Since: 2.3
10091 If: "defined(CONFIG_VNC)"
10093 change-vnc-password (Command) Change the VNC server password.
10095 Arguments:
10097 "password: string"
10099 the new password to use with VNC authentication
10100 Since: 1.1
10102 Notes: An empty password in this command will set the password to the
10104 empty string. Existing clients are unaffected by executing this
10105 command.
10106 If: "defined(CONFIG_VNC)"
10108 VNC_CONNECTED (Event) Emitted when a VNC client establishes a
10110 connection
10111 Arguments:
10113 "server: VncServerInfo"
10115 server information
10116 "client: VncBasicInfo"
10118 client information
10119 Note: This event is emitted before any authentication takes place, thus
10121 the authentication ID is not provided
10122 Since: 0.13.0
10124 Example:
10126 <- { "event": "VNC_CONNECTED",
10128 "data": {
10129 "server": { "auth": "sasl", "family": "ipv4",
10130 "service": "5901", "host": "0.0.0.0" },
10131 "client": { "family": "ipv4", "service": "58425",
10132 "host": "127.0.0.1" } },
10133 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10134 If: "defined(CONFIG_VNC)"
10136 VNC_INITIALIZED (Event) Emitted after authentication takes place (if
10138 any) and the VNC session is made active
10139 Arguments:
10141 "server: VncServerInfo"
10143 server information
10144 "client: VncClientInfo"
10146 client information
10147 Since: 0.13.0
10149 Example:
10151 <- { "event": "VNC_INITIALIZED",
10153 "data": {
10154 "server": { "auth": "sasl", "family": "ipv4",
10155 "service": "5901", "host": "0.0.0.0"},
10156 "client": { "family": "ipv4", "service": "46089",
10157 "host": "127.0.0.1", "sasl_username": "luiz" } },
10158 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
10159 If: "defined(CONFIG_VNC)"
10161 VNC_DISCONNECTED (Event) Emitted when the connection is closed
10163 Arguments:
10165 "server: VncServerInfo"
10167 server information
10168 "client: VncClientInfo"
10170 client information
10171 Since: 0.13.0
10173 Example:
10175 <- { "event": "VNC_DISCONNECTED",
10177 "data": {
10178 "server": { "auth": "sasl", "family": "ipv4",
10179 "service": "5901", "host": "0.0.0.0" },
10180 "client": { "family": "ipv4", "service": "58425",
10181 "host": "127.0.0.1", "sasl_username": "luiz" } },
10182 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10183 If: "defined(CONFIG_VNC)"
10185 Input
10187 MouseInfo (Object)
10188 Information about a mouse device.
10190 Members:
10192 "name: string"
10194 the name of the mouse device
10195 "index: int"
10197 the index of the mouse device
10198 "current: boolean"
10200 true if this device is currently receiving mouse events
10201 "absolute: boolean"
10203 true if this device supports absolute coordinates as input
10204 Since: 0.14.0
10206 query-mice (Command) Returns information about each active mouse
10208 device
10209 Returns: a list of "MouseInfo" for each device
10211 Since: 0.14.0
10213 Example:
10215 -> { "execute": "query-mice" }
10217 <- { "return": [
10218 {
10219 "name":"QEMU Microsoft Mouse",
10220 "index":0,
10221 "current":false,
10222 "absolute":false
10223 },
10224 {
10225 "name":"QEMU PS/2 Mouse",
10226 "index":1,
10227 "current":true,
10228 "absolute":true
10229 }
10230 ]
10231 }
10232 QKeyCode (Enum)
10234 An enumeration of key name.
10236 This is used by the "send-key" command.
10238 Values:
10240 "unmapped"
10242 since 2.0
10243 "pause"
10245 since 2.0
10246 "ro"
10248 since 2.4
10249 "kp_comma"
10251 since 2.4
10252 "kp_equals"
10254 since 2.6
10255 "power"
10257 since 2.6
10258 "hiragana"
10260 since 2.9
10261 "henkan"
10263 since 2.9
10264 "yen"
10266 since 2.9
10267 "sleep"
10269 since 2.10
10270 "wake"
10272 since 2.10
10273 "audionext"
10275 since 2.10
10276 "audioprev"
10278 since 2.10
10279 "audiostop"
10281 since 2.10
10282 "audioplay"
10284 since 2.10
10285 "audiomute"
10287 since 2.10
10288 "volumeup"
10290 since 2.10
10291 "volumedown"
10293 since 2.10
10294 "mediaselect"
10296 since 2.10
10297 "mail"
10299 since 2.10
10300 "calculator"
10302 since 2.10
10303 "computer"
10305 since 2.10
10306 "ac_home"
10308 since 2.10
10309 "ac_back"
10311 since 2.10
10312 "ac_forward"
10314 since 2.10
10315 "ac_refresh"
10317 since 2.10
10318 "ac_bookmarks"
10320 since 2.10 altgr, altgr_r: dropped in 2.10
10321 "muhenkan"
10323 since 2.12
10324 "katakanahiragana"
10326 since 2.12
10327 "shift"
10329 Not documented
10330 "shift_r"
10332 Not documented
10333 "alt"
10335 Not documented
10336 "alt_r"
10338 Not documented
10339 "ctrl"
10341 Not documented
10342 "ctrl_r"
10344 Not documented
10345 "menu"
10347 Not documented
10348 "esc"
10350 Not documented
10351 1 Not documented
10353 2 Not documented
10355 3 Not documented
10357 4 Not documented
10359 5 Not documented
10361 6 Not documented
10363 7 Not documented
10365 8 Not documented
10367 9 Not documented
10369 0 Not documented
10371 "minus"
10373 Not documented
10374 "equal"
10376 Not documented
10377 "backspace"
10379 Not documented
10380 "tab"
10382 Not documented
10383 "q" Not documented
10385 "w" Not documented
10387 "e" Not documented
10389 "r" Not documented
10391 "t" Not documented
10393 "y" Not documented
10395 "u" Not documented
10397 "i" Not documented
10399 "o" Not documented
10401 "p" Not documented
10403 "bracket_left"
10405 Not documented
10406 "bracket_right"
10408 Not documented
10409 "ret"
10411 Not documented
10412 "a" Not documented
10414 "s" Not documented
10416 "d" Not documented
10418 "f" Not documented
10420 "g" Not documented
10422 "h" Not documented
10424 "j" Not documented
10426 "k" Not documented
10428 "l" Not documented
10430 "semicolon"
10432 Not documented
10433 "apostrophe"
10435 Not documented
10436 "grave_accent"
10438 Not documented
10439 "backslash"
10441 Not documented
10442 "z" Not documented
10444 "x" Not documented
10446 "c" Not documented
10448 "v" Not documented
10450 "b" Not documented
10452 "n" Not documented
10454 "m" Not documented
10456 "comma"
10458 Not documented
10459 "dot"
10461 Not documented
10462 "slash"
10464 Not documented
10465 "asterisk"
10467 Not documented
10468 "spc"
10470 Not documented
10471 "caps_lock"
10473 Not documented
10474 "f1"
10476 Not documented
10477 "f2"
10479 Not documented
10480 "f3"
10482 Not documented
10483 "f4"
10485 Not documented
10486 "f5"
10488 Not documented
10489 "f6"
10491 Not documented
10492 "f7"
10494 Not documented
10495 "f8"
10497 Not documented
10498 "f9"
10500 Not documented
10501 "f10"
10503 Not documented
10504 "num_lock"
10506 Not documented
10507 "scroll_lock"
10509 Not documented
10510 "kp_divide"
10512 Not documented
10513 "kp_multiply"
10515 Not documented
10516 "kp_subtract"
10518 Not documented
10519 "kp_add"
10521 Not documented
10522 "kp_enter"
10524 Not documented
10525 "kp_decimal"
10527 Not documented
10528 "sysrq"
10530 Not documented
10531 "kp_0"
10533 Not documented
10534 "kp_1"
10536 Not documented
10537 "kp_2"
10539 Not documented
10540 "kp_3"
10542 Not documented
10543 "kp_4"
10545 Not documented
10546 "kp_5"
10548 Not documented
10549 "kp_6"
10551 Not documented
10552 "kp_7"
10554 Not documented
10555 "kp_8"
10557 Not documented
10558 "kp_9"
10560 Not documented
10561 "less"
10563 Not documented
10564 "f11"
10566 Not documented
10567 "f12"
10569 Not documented
10570 "print"
10572 Not documented
10573 "home"
10575 Not documented
10576 "pgup"
10578 Not documented
10579 "pgdn"
10581 Not documented
10582 "end"
10584 Not documented
10585 "left"
10587 Not documented
10588 "up"
10590 Not documented
10591 "down"
10593 Not documented
10594 "right"
10596 Not documented
10597 "insert"
10599 Not documented
10600 "delete"
10602 Not documented
10603 "stop"
10605 Not documented
10606 "again"
10608 Not documented
10609 "props"
10611 Not documented
10612 "undo"
10614 Not documented
10615 "front"
10617 Not documented
10618 "copy"
10620 Not documented
10621 "open"
10623 Not documented
10624 "paste"
10626 Not documented
10627 "find"
10629 Not documented
10630 "cut"
10632 Not documented
10633 "lf"
10635 Not documented
10636 "help"
10638 Not documented
10639 "meta_l"
10641 Not documented
10642 "meta_r"
10644 Not documented
10645 "compose"
10647 Not documented
10648 'sysrq' was mistakenly added to hack around the fact that the ps2
10650 driver was not generating correct scancodes sequences when 'alt+print'
10651 was pressed. This flaw is now fixed and the 'sysrq' key serves no
10652 further purpose. Any further use of 'sysrq' will be transparently
10653 changed to 'print', so they are effectively synonyms.
10654 Since: 1.3.0
10656 KeyValue (Object)
10658 Represents a keyboard key.
10660 Members:
10662 "type"
10664 One of "number", "qcode"
10665 "data: int" when "type" is "number"
10667 "data: QKeyCode" when "type" is "qcode"
10668 Since: 1.3.0
10670 send-key (Command) Send keys to guest.
10672 Arguments:
10674 "keys: array of KeyValue"
10676 An array of "KeyValue" elements. All "KeyValues" in this array are
10677 simultaneously sent to the guest. A "KeyValue".number value is sent
10678 directly to the guest, while "KeyValue".qcode must be a valid
10679 "QKeyCode" value
10680 "hold-time: int" (optional)
10682 time to delay key up events, milliseconds. Defaults to 100
10683 Returns: Nothing on success If key is unknown or redundant,
10685 InvalidParameter
10686 Since: 1.3.0
10688 Example:
10690 -> { "execute": "send-key",
10692 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
10693 { "type": "qcode", "data": "alt" },
10694 { "type": "qcode", "data": "delete" } ] } }
10695 <- { "return": {} }
10696 InputButton (Enum)
10698 Button of a pointer input device (mouse, tablet).
10700 Values:
10702 "side"
10704 front side button of a 5-button mouse (since 2.9)
10705 "extra"
10707 rear side button of a 5-button mouse (since 2.9)
10708 "left"
10710 Not documented
10711 "middle"
10713 Not documented
10714 "right"
10716 Not documented
10717 "wheel-up"
10719 Not documented
10720 "wheel-down"
10722 Not documented
10723 Since: 2.0
10725 InputAxis (Enum)
10727 Position axis of a pointer input device (mouse, tablet).
10729 Values:
10731 "x" Not documented
10733 "y" Not documented
10735 Since: 2.0
10737 InputKeyEvent (Object)
10739 Keyboard input event.
10741 Members:
10743 "key: KeyValue"
10745 Which key this event is for.
10746 "down: boolean"
10748 True for key-down and false for key-up events.
10749 Since: 2.0
10751 InputBtnEvent (Object)
10753 Pointer button input event.
10755 Members:
10757 "button: InputButton"
10759 Which button this event is for.
10760 "down: boolean"
10762 True for key-down and false for key-up events.
10763 Since: 2.0
10765 InputMoveEvent (Object)
10767 Pointer motion input event.
10769 Members:
10771 "axis: InputAxis"
10773 Which axis is referenced by "value".
10774 "value: int"
10776 Pointer position. For absolute coordinates the valid range is 0 ->
10777 0x7ffff
10778 Since: 2.0
10780 InputEvent (Object)
10782 Input event union.
10784 Members:
10786 "type"
10788 the input type, one of:
10789 - 'key': Input event of Keyboard
10791 - 'btn': Input event of pointer buttons
10793 - 'rel': Input event of relative pointer motion
10795 - 'abs': Input event of absolute pointer motion
10797 "data: InputKeyEvent" when "type" is "key"
10799 "data: InputBtnEvent" when "type" is "btn"
10800 "data: InputMoveEvent" when "type" is "rel"
10801 "data: InputMoveEvent" when "type" is "abs"
10802 Since: 2.0
10804 input-send-event (Command) Send input event(s) to guest.
10806 Arguments:
10808 "device: string" (optional)
10810 display device to send event(s) to.
10811 "head: int" (optional)
10813 head to send event(s) to, in case the display device supports
10814 multiple scanouts.
10815 "events: array of InputEvent"
10817 List of InputEvent union.
10818 Returns: Nothing on success.
10820 The "device" and "head" parameters can be used to send the input event
10822 to specific input devices in case (a) multiple input devices of the
10823 same kind are added to the virtual machine and (b) you have configured
10824 input routing (see docs/multiseat.txt) for those input devices. The
10825 parameters work exactly like the device and head properties of input
10826 devices. If "device" is missing, only devices that have no input
10827 routing config are admissible. If "device" is specified, both input
10828 devices with and without input routing config are admissible, but
10829 devices with input routing config take precedence.
10830 Since: 2.6
10832 Note: The consoles are visible in the qom tree, under
10834 /backend/console[$index]. They have a device link and head property, so
10835 it is possible to map which console belongs to which device and
10836 display.
10837 Example:
10839 1. Press left mouse button.
10841 -> { "execute": "input-send-event",
10843 "arguments": { "device": "video0",
10844 "events": [ { "type": "btn",
10845 "data" : { "down": true, "button": "left" } } ] } }
10846 <- { "return": {} }
10847 -> { "execute": "input-send-event",
10849 "arguments": { "device": "video0",
10850 "events": [ { "type": "btn",
10851 "data" : { "down": false, "button": "left" } } ] } }
10852 <- { "return": {} }
10853 2. Press ctrl-alt-del.
10855 -> { "execute": "input-send-event",
10857 "arguments": { "events": [
10858 { "type": "key", "data" : { "down": true,
10859 "key": {"type": "qcode", "data": "ctrl" } } },
10860 { "type": "key", "data" : { "down": true,
10861 "key": {"type": "qcode", "data": "alt" } } },
10862 { "type": "key", "data" : { "down": true,
10863 "key": {"type": "qcode", "data": "delete" } } } ] } }
10864 <- { "return": {} }
10865 3. Move mouse pointer to absolute coordinates (20000, 400).
10867 -> { "execute": "input-send-event" ,
10869 "arguments": { "events": [
10870 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
10871 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
10872 <- { "return": {} }
10873 GrabToggleKeys (Enum)
10875 Keys to toggle input-linux between host and guest.
10877 Values:
10879 "ctrl-ctrl"
10881 Not documented
10882 "alt-alt"
10884 Not documented
10885 "shift-shift"
10887 Not documented
10888 "meta-meta"
10890 Not documented
10891 "scrolllock"
10893 Not documented
10894 "ctrl-scrolllock"
10896 Not documented
10897 Since: 4.0
10899 DisplayGTK (Object)
10901 GTK display options.
10903 Members:
10905 "grab-on-hover: boolean" (optional)
10907 Grab keyboard input on mouse hover.
10908 "zoom-to-fit: boolean" (optional)
10910 Zoom guest display to fit into the host window. When turned off
10911 the host window will be resized instead. In case the display
10912 device can notify the guest on window resizes (virtio-gpu) this
10913 will default to "on", assuming the guest will resize the display to
10914 match the window size then. Otherwise it defaults to "off". Since
10915 3.1
10916 Since: 2.12
10918 DisplayEGLHeadless (Object)
10920 EGL headless display options.
10922 Members:
10924 "rendernode: string" (optional)
10926 Which DRM render node should be used. Default is the first
10927 available node on the host.
10928 Since: 3.1
10930 DisplayGLMode (Enum)
10932 Display OpenGL mode.
10934 Values:
10936 "off"
10938 Disable OpenGL (default).
10939 "on"
10941 Use OpenGL, pick context type automatically. Would better be named
10942 'auto' but is called 'on' for backward compatibility with bool
10943 type.
10944 "core"
10946 Use OpenGL with Core (desktop) Context.
10947 "es"
10949 Use OpenGL with ES (embedded systems) Context.
10950 Since: 3.0
10952 DisplayCurses (Object)
10954 Curses display options.
10956 Members:
10958 "charset: string" (optional)
10960 Font charset used by guest (default: CP437).
10961 Since: 4.0
10963 DisplayType (Enum)
10965 Display (user interface) type.
10967 Values:
10969 "default"
10971 The default user interface, selecting from the first available of
10972 gtk, sdl, cocoa, and vnc.
10973 "none"
10975 No user interface or video output display. The guest will still see
10976 an emulated graphics card, but its output will not be displayed to
10977 the QEMU user.
10978 "gtk"
10980 The GTK user interface.
10981 "sdl"
10983 The SDL user interface.
10984 "egl-headless"
10986 No user interface, offload GL operations to a local DRI device.
10987 Graphical display need to be paired with VNC or Spice. (Since 3.1)
10988 "curses"
10990 Display video output via curses. For graphics device models which
10991 support a text mode, QEMU can display this output using a
10992 curses/ncurses interface. Nothing is displayed when the graphics
10993 device is in graphical mode or if the graphics device does not
10994 support a text mode. Generally only the VGA device models support
10995 text mode.
10996 "cocoa"
10998 The Cocoa user interface.
10999 "spice-app"
11001 Set up a Spice server and run the default associated application to
11002 connect to it. The server will redirect the serial console and QEMU
11003 monitors. (Since 4.0)
11004 Since: 2.12
11006 DisplayOptions (Object)
11008 Display (user interface) options.
11010 Members:
11012 "type: DisplayType"
11014 Which DisplayType qemu should use.
11015 "full-screen: boolean" (optional)
11017 Start user interface in fullscreen mode (default: off).
11018 "window-close: boolean" (optional)
11020 Allow to quit qemu with window close button (default: on).
11021 "gl: DisplayGLMode" (optional)
11023 Enable OpenGL support (default: off).
11024 The members of "DisplayGTK" when "type" is "gtk"
11026 The members of "DisplayCurses" when "type" is "curses"
11027 The members of "DisplayEGLHeadless" when "type" is "egl-headless"
11028 Since: 2.12
11030 query-display-options (Command) Returns information about display
11032 configuration
11033 Returns: "DisplayOptions"
11035 Since: 3.1
11037 QAuthZListPolicy (Enum)
11039 The authorization policy result
11041 Values:
11043 "deny"
11045 deny access
11046 "allow"
11048 allow access
11049 Since: 4.0
11051 QAuthZListFormat (Enum)
11053 The authorization policy match format
11055 Values:
11057 "exact"
11059 an exact string match
11060 "glob"
11062 string with ? and * shell wildcard support
11063 Since: 4.0
11065 QAuthZListRule (Object)
11067 A single authorization rule.
11069 Members:
11071 "match: string"
11073 a string or glob to match against a user identity
11074 "policy: QAuthZListPolicy"
11076 the result to return if "match" evaluates to true
11077 "format: QAuthZListFormat" (optional)
11079 the format of the "match" rule (default 'exact')
11080 Since: 4.0
11082 QAuthZListRuleListHack (Object)
11084 Not exposed via QMP; hack to generate QAuthZListRuleList for use
11086 internally by the code.
11087 Members:
11089 "unused: array of QAuthZListRule"
11091 Not documented
11092 Since: 4.0
11094 Migration
11096 MigrationStats (Object)
11097 Detailed migration status.
11099 Members:
11101 "transferred: int"
11103 amount of bytes already transferred to the target VM
11104 "remaining: int"
11106 amount of bytes remaining to be transferred to the target VM
11107 "total: int"
11109 total amount of bytes involved in the migration process
11110 "duplicate: int"
11112 number of duplicate (zero) pages (since 1.2)
11113 "skipped: int"
11115 number of skipped zero pages (since 1.5)
11116 "normal: int"
11118 number of normal pages (since 1.2)
11119 "normal-bytes: int"
11121 number of normal bytes sent (since 1.2)
11122 "dirty-pages-rate: int"
11124 number of pages dirtied by second by the guest (since 1.3)
11125 "mbps: number"
11127 throughput in megabits/sec. (since 1.6)
11128 "dirty-sync-count: int"
11130 number of times that dirty ram was synchronized (since 2.1)
11131 "postcopy-requests: int"
11133 The number of page requests received from the destination (since
11134 2.7)
11135 "page-size: int"
11137 The number of bytes per page for the various page-based statistics
11138 (since 2.10)
11139 "multifd-bytes: int"
11141 The number of bytes sent through multifd (since 3.0)
11142 "pages-per-second: int"
11144 the number of memory pages transferred per second (Since 4.0)
11145 Since: 0.14.0
11147 XBZRLECacheStats (Object)
11149 Detailed XBZRLE migration cache statistics
11151 Members:
11153 "cache-size: int"
11155 XBZRLE cache size
11156 "bytes: int"
11158 amount of bytes already transferred to the target VM
11159 "pages: int"
11161 amount of pages transferred to the target VM
11162 "cache-miss: int"
11164 number of cache miss
11165 "cache-miss-rate: number"
11167 rate of cache miss (since 2.1)
11168 "overflow: int"
11170 number of overflows
11171 Since: 1.2
11173 CompressionStats (Object)
11175 Detailed migration compression statistics
11177 Members:
11179 "pages: int"
11181 amount of pages compressed and transferred to the target VM
11182 "busy: int"
11184 count of times that no free thread was available to compress data
11185 "busy-rate: number"
11187 rate of thread busy
11188 "compressed-size: int"
11190 amount of bytes after compression
11191 "compression-rate: number"
11193 rate of compressed size
11194 Since: 3.1
11196 MigrationStatus (Enum)
11198 An enumeration of migration status.
11200 Values:
11202 "none"
11204 no migration has ever happened.
11205 "setup"
11207 migration process has been initiated.
11208 "cancelling"
11210 in the process of cancelling migration.
11211 "cancelled"
11213 cancelling migration is finished.
11214 "active"
11216 in the process of doing migration.
11217 "postcopy-active"
11219 like active, but now in postcopy mode. (since 2.5)
11220 "postcopy-paused"
11222 during postcopy but paused. (since 3.0)
11223 "postcopy-recover"
11225 trying to recover from a paused postcopy. (since 3.0)
11226 "completed"
11228 migration is finished.
11229 "failed"
11231 some error occurred during migration process.
11232 "colo"
11234 VM is in the process of fault tolerance, VM can not get into this
11235 state unless colo capability is enabled for migration. (since 2.8)
11236 "pre-switchover"
11238 Paused before device serialisation. (since 2.11)
11239 "device"
11241 During device serialisation when pause-before-switchover is enabled
11242 (since 2.11)
11243 "wait-unplug"
11245 wait for device unplug request by guest OS to be completed. (since
11246 4.2)
11247 Since: 2.3
11249 MigrationInfo (Object)
11251 Information about current migration process.
11253 Members:
11255 "status: MigrationStatus" (optional)
11257 "MigrationStatus" describing the current migration status. If this
11258 field is not returned, no migration process has been initiated
11259 "ram: MigrationStats" (optional)
11261 "MigrationStats" containing detailed migration status, only
11262 returned if status is 'active' or 'completed'(since 1.2)
11263 "disk: MigrationStats" (optional)
11265 "MigrationStats" containing detailed disk migration status, only
11266 returned if status is 'active' and it is a block migration
11267 "xbzrle-cache: XBZRLECacheStats" (optional)
11269 "XBZRLECacheStats" containing detailed XBZRLE migration statistics,
11270 only returned if XBZRLE feature is on and status is 'active' or
11271 'completed' (since 1.2)
11272 "total-time: int" (optional)
11274 total amount of milliseconds since migration started. If migration
11275 has ended, it returns the total migration time. (since 1.2)
11276 "downtime: int" (optional)
11278 only present when migration finishes correctly total downtime in
11279 milliseconds for the guest. (since 1.3)
11280 "expected-downtime: int" (optional)
11282 only present while migration is active expected downtime in
11283 milliseconds for the guest in last walk of the dirty bitmap. (since
11284 1.3)
11285 "setup-time: int" (optional)
11287 amount of setup time in milliseconds before the iterations begin
11288 but after the QMP command is issued. This is designed to provide an
11289 accounting of any activities (such as RDMA pinning) which may be
11290 expensive, but do not actually occur during the iterative migration
11291 rounds themselves. (since 1.6)
11292 "cpu-throttle-percentage: int" (optional)
11294 percentage of time guest cpus are being throttled during auto-
11295 converge. This is only present when auto-converge has started
11296 throttling guest cpus. (Since 2.7)
11297 "error-desc: string" (optional)
11299 the human readable error description string, when "status" is
11300 'failed'. Clients should not attempt to parse the error strings.
11301 (Since 2.7)
11302 "postcopy-blocktime: int" (optional)
11304 total time when all vCPU were blocked during postcopy live
11305 migration. This is only present when the postcopy-blocktime
11306 migration capability is enabled. (Since 3.0)
11307 "postcopy-vcpu-blocktime: array of int" (optional)
11309 list of the postcopy blocktime per vCPU. This is only present when
11310 the postcopy-blocktime migration capability is enabled. (Since 3.0)
11311 "compression: CompressionStats" (optional)
11313 migration compression statistics, only returned if compression
11314 feature is on and status is 'active' or 'completed' (Since 3.1)
11315 "socket-address: array of SocketAddress" (optional)
11317 Only used for tcp, to know what the real port is (Since 4.0)
11318 Since: 0.14.0
11320 query-migrate (Command) Returns information about current migration
11322 process. If migration is active there will be another json-object with
11323 RAM migration status and if block migration is active another one with
11324 block migration status.
11325 Returns: "MigrationInfo"
11327 Since: 0.14.0
11329 Example:
11331 1. Before the first migration
11333 -> { "execute": "query-migrate" }
11335 <- { "return": {} }
11336 2. Migration is done and has succeeded
11338 -> { "execute": "query-migrate" }
11340 <- { "return": {
11341 "status": "completed",
11342 "total-time":12345,
11343 "setup-time":12345,
11344 "downtime":12345,
11345 "ram":{
11346 "transferred":123,
11347 "remaining":123,
11348 "total":246,
11349 "duplicate":123,
11350 "normal":123,
11351 "normal-bytes":123456,
11352 "dirty-sync-count":15
11353 }
11354 }
11355 }
11356 3. Migration is done and has failed
11358 -> { "execute": "query-migrate" }
11360 <- { "return": { "status": "failed" } }
11361 4. Migration is being performed and is not a block migration:
11363 -> { "execute": "query-migrate" }
11365 <- {
11366 "return":{
11367 "status":"active",
11368 "total-time":12345,
11369 "setup-time":12345,
11370 "expected-downtime":12345,
11371 "ram":{
11372 "transferred":123,
11373 "remaining":123,
11374 "total":246,
11375 "duplicate":123,
11376 "normal":123,
11377 "normal-bytes":123456,
11378 "dirty-sync-count":15
11379 }
11380 }
11381 }
11382 5. Migration is being performed and is a block migration:
11384 -> { "execute": "query-migrate" }
11386 <- {
11387 "return":{
11388 "status":"active",
11389 "total-time":12345,
11390 "setup-time":12345,
11391 "expected-downtime":12345,
11392 "ram":{
11393 "total":1057024,
11394 "remaining":1053304,
11395 "transferred":3720,
11396 "duplicate":123,
11397 "normal":123,
11398 "normal-bytes":123456,
11399 "dirty-sync-count":15
11400 },
11401 "disk":{
11402 "total":20971520,
11403 "remaining":20880384,
11404 "transferred":91136
11405 }
11406 }
11407 }
11408 6. Migration is being performed and XBZRLE is active:
11410 -> { "execute": "query-migrate" }
11412 <- {
11413 "return":{
11414 "status":"active",
11415 "total-time":12345,
11416 "setup-time":12345,
11417 "expected-downtime":12345,
11418 "ram":{
11419 "total":1057024,
11420 "remaining":1053304,
11421 "transferred":3720,
11422 "duplicate":10,
11423 "normal":3333,
11424 "normal-bytes":3412992,
11425 "dirty-sync-count":15
11426 },
11427 "xbzrle-cache":{
11428 "cache-size":67108864,
11429 "bytes":20971520,
11430 "pages":2444343,
11431 "cache-miss":2244,
11432 "cache-miss-rate":0.123,
11433 "overflow":34434
11434 }
11435 }
11436 }
11437 MigrationCapability (Enum)
11439 Migration capabilities enumeration
11441 Values:
11443 "xbzrle"
11445 Migration supports xbzrle (Xor Based Zero Run Length Encoding).
11446 This feature allows us to minimize migration traffic for certain
11447 work loads, by sending compressed difference of the pages
11448 "rdma-pin-all"
11450 Controls whether or not the entire VM memory footprint is mlock()'d
11451 on demand or all at once. Refer to docs/rdma.txt for usage.
11452 Disabled by default. (since 2.0)
11453 "zero-blocks"
11455 During storage migration encode blocks of zeroes efficiently. This
11456 essentially saves 1MB of zeroes per block on the wire. Enabling
11457 requires source and target VM to support this feature. To enable it
11458 is sufficient to enable the capability on the source VM. The
11459 feature is disabled by default. (since 1.6)
11460 "compress"
11462 Use multiple compression threads to accelerate live migration.
11463 This feature can help to reduce the migration traffic, by sending
11464 compressed pages. Please note that if compress and xbzrle are both
11465 on, compress only takes effect in the ram bulk stage, after that,
11466 it will be disabled and only xbzrle takes effect, this can help to
11467 minimize migration traffic. The feature is disabled by default.
11468 (since 2.4 )
11469 "events"
11471 generate events for each migration state change (since 2.4 )
11472 "auto-converge"
11474 If enabled, QEMU will automatically throttle down the guest to
11475 speed up convergence of RAM migration. (since 1.6)
11476 "postcopy-ram"
11478 Start executing on the migration target before all of RAM has been
11479 migrated, pulling the remaining pages along as needed. The capacity
11480 must have the same setting on both source and target or migration
11481 will not even start. NOTE: If the migration fails during postcopy
11482 the VM will fail. (since 2.6)
11483 "x-colo"
11485 If enabled, migration will never end, and the state of the VM on
11486 the primary side will be migrated continuously to the VM on
11487 secondary side, this process is called COarse-Grain LOck Stepping
11488 (COLO) for Non-stop Service. (since 2.8)
11489 "release-ram"
11491 if enabled, qemu will free the migrated ram pages on the source
11492 during postcopy-ram migration. (since 2.9)
11493 "block"
11495 If enabled, QEMU will also migrate the contents of all block
11496 devices. Default is disabled. A possible alternative uses mirror
11497 jobs to a builtin NBD server on the destination, which offers more
11498 flexibility. (Since 2.10)
11499 "return-path"
11501 If enabled, migration will use the return path even for precopy.
11502 (since 2.10)
11503 "pause-before-switchover"
11505 Pause outgoing migration before serialising device state and before
11506 disabling block IO (since 2.11)
11507 "multifd"
11509 Use more than one fd for migration (since 4.0)
11510 "dirty-bitmaps"
11512 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
11513 "postcopy-blocktime"
11515 Calculate downtime for postcopy live migration (since 3.0)
11516 "late-block-activate"
11518 If enabled, the destination will not activate block devices (and
11519 thus take locks) immediately at the end of migration. (since 3.0)
11520 "x-ignore-shared"
11522 If enabled, QEMU will not migrate shared memory (since 4.0)
11523 "validate-uuid"
11525 Send the UUID of the source to allow the destination to ensure it
11526 is the same. (since 4.2)
11527 Since: 1.2
11529 MigrationCapabilityStatus (Object)
11531 Migration capability information
11533 Members:
11535 "capability: MigrationCapability"
11537 capability enum
11538 "state: boolean"
11540 capability state bool
11541 Since: 1.2
11543 migrate-set-capabilities (Command) Enable/Disable the following
11545 migration capabilities (like xbzrle)
11546 Arguments:
11548 "capabilities: array of MigrationCapabilityStatus"
11550 json array of capability modifications to make
11551 Since: 1.2
11553 Example:
11555 -> { "execute": "migrate-set-capabilities" , "arguments":
11557 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
11558 query-migrate-capabilities (Command) Returns information about the
11560 current migration capabilities status
11561 Returns: "MigrationCapabilitiesStatus"
11563 Since: 1.2
11565 Example:
11567 -> { "execute": "query-migrate-capabilities" }
11569 <- { "return": [
11570 {"state": false, "capability": "xbzrle"},
11571 {"state": false, "capability": "rdma-pin-all"},
11572 {"state": false, "capability": "auto-converge"},
11573 {"state": false, "capability": "zero-blocks"},
11574 {"state": false, "capability": "compress"},
11575 {"state": true, "capability": "events"},
11576 {"state": false, "capability": "postcopy-ram"},
11577 {"state": false, "capability": "x-colo"}
11578 ]}
11579 MigrationParameter (Enum)
11581 Migration parameters enumeration
11583 Values:
11585 "announce-initial"
11587 Initial delay (in milliseconds) before sending the first announce
11588 (Since 4.0)
11589 "announce-max"
11591 Maximum delay (in milliseconds) between packets in the announcement
11592 (Since 4.0)
11593 "announce-rounds"
11595 Number of self-announce packets sent after migration (Since 4.0)
11596 "announce-step"
11598 Increase in delay (in milliseconds) between subsequent packets in
11599 the announcement (Since 4.0)
11600 "compress-level"
11602 Set the compression level to be used in live migration, the
11603 compression level is an integer between 0 and 9, where 0 means no
11604 compression, 1 means the best compression speed, and 9 means best
11605 compression ratio which will consume more CPU.
11606 "compress-threads"
11608 Set compression thread count to be used in live migration, the
11609 compression thread count is an integer between 1 and 255.
11610 "compress-wait-thread"
11612 Controls behavior when all compression threads are currently busy.
11613 If true (default), wait for a free compression thread to become
11614 available; otherwise, send the page uncompressed. (Since 3.1)
11615 "decompress-threads"
11617 Set decompression thread count to be used in live migration, the
11618 decompression thread count is an integer between 1 and 255.
11619 Usually, decompression is at least 4 times as fast as compression,
11620 so set the decompress-threads to the number about 1/4 of compress-
11621 threads is adequate.
11622 "cpu-throttle-initial"
11624 Initial percentage of time guest cpus are throttled when migration
11625 auto-converge is activated. The default value is 20. (Since 2.7)
11626 "cpu-throttle-increment"
11628 throttle percentage increase each time auto-converge detects that
11629 migration is not making progress. The default value is 10. (Since
11630 2.7)
11631 "tls-creds"
11633 ID of the 'tls-creds' object that provides credentials for
11634 establishing a TLS connection over the migration data channel. On
11635 the outgoing side of the migration, the credentials must be for a
11636 'client' endpoint, while for the incoming side the credentials must
11637 be for a 'server' endpoint. Setting this will enable TLS for all
11638 migrations. The default is unset, resulting in unsecured migration
11639 at the QEMU level. (Since 2.7)
11640 "tls-hostname"
11642 hostname of the target host for the migration. This is required
11643 when using x509 based TLS credentials and the migration URI does
11644 not already include a hostname. For example if using fd: or exec:
11645 based migration, the hostname must be provided so that the server's
11646 x509 certificate identity can be validated. (Since 2.7)
11647 "tls-authz"
11649 ID of the 'authz' object subclass that provides access control
11650 checking of the TLS x509 certificate distinguished name. This
11651 object is only resolved at time of use, so can be deleted and
11652 recreated on the fly while the migration server is active. If
11653 missing, it will default to denying access (Since 4.0)
11654 "max-bandwidth"
11656 to set maximum speed for migration. maximum speed in bytes per
11657 second. (Since 2.8)
11658 "downtime-limit"
11660 set maximum tolerated downtime for migration. maximum downtime in
11661 milliseconds (Since 2.8)
11662 "x-checkpoint-delay"
11664 The delay time (in ms) between two COLO checkpoints in periodic
11665 mode. (Since 2.8)
11666 "block-incremental"
11668 Affects how much storage is migrated when the block migration
11669 capability is enabled. When false, the entire storage backing
11670 chain is migrated into a flattened image at the destination; when
11671 true, only the active qcow2 layer is migrated and the destination
11672 must already have access to the same backing chain as was used on
11673 the source. (since 2.10)
11674 "multifd-channels"
11676 Number of channels used to migrate data in parallel. This is the
11677 same number that the number of sockets used for migration. The
11678 default value is 2 (since 4.0)
11679 "xbzrle-cache-size"
11681 cache size to be used by XBZRLE migration. It needs to be a
11682 multiple of the target page size and a power of 2 (Since 2.11)
11683 "max-postcopy-bandwidth"
11685 Background transfer bandwidth during postcopy. Defaults to 0
11686 (unlimited). In bytes per second. (Since 3.0)
11687 "max-cpu-throttle"
11689 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
11690 Since: 2.4
11692 MigrateSetParameters (Object)
11694 Members:
11696 "announce-initial: int" (optional)
11698 Initial delay (in milliseconds) before sending the first announce
11699 (Since 4.0)
11700 "announce-max: int" (optional)
11702 Maximum delay (in milliseconds) between packets in the announcement
11703 (Since 4.0)
11704 "announce-rounds: int" (optional)
11706 Number of self-announce packets sent after migration (Since 4.0)
11707 "announce-step: int" (optional)
11709 Increase in delay (in milliseconds) between subsequent packets in
11710 the announcement (Since 4.0)
11711 "compress-level: int" (optional)
11713 compression level
11714 "compress-threads: int" (optional)
11716 compression thread count
11717 "compress-wait-thread: boolean" (optional)
11719 Controls behavior when all compression threads are currently busy.
11720 If true (default), wait for a free compression thread to become
11721 available; otherwise, send the page uncompressed. (Since 3.1)
11722 "decompress-threads: int" (optional)
11724 decompression thread count
11725 "cpu-throttle-initial: int" (optional)
11727 Initial percentage of time guest cpus are throttled when migration
11728 auto-converge is activated. The default value is 20. (Since 2.7)
11729 "cpu-throttle-increment: int" (optional)
11731 throttle percentage increase each time auto-converge detects that
11732 migration is not making progress. The default value is 10. (Since
11733 2.7)
11734 "tls-creds: StrOrNull" (optional)
11736 ID of the 'tls-creds' object that provides credentials for
11737 establishing a TLS connection over the migration data channel. On
11738 the outgoing side of the migration, the credentials must be for a
11739 'client' endpoint, while for the incoming side the credentials must
11740 be for a 'server' endpoint. Setting this to a non-empty string
11741 enables TLS for all migrations. An empty string means that QEMU
11742 will use plain text mode for migration, rather than TLS (Since 2.9)
11743 Previously (since 2.7), this was reported by omitting tls-creds
11744 instead.
11745 "tls-hostname: StrOrNull" (optional)
11747 hostname of the target host for the migration. This is required
11748 when using x509 based TLS credentials and the migration URI does
11749 not already include a hostname. For example if using fd: or exec:
11750 based migration, the hostname must be provided so that the server's
11751 x509 certificate identity can be validated. (Since 2.7) An empty
11752 string means that QEMU will use the hostname associated with the
11753 migration URI, if any. (Since 2.9) Previously (since 2.7), this was
11754 reported by omitting tls-hostname instead.
11755 "max-bandwidth: int" (optional)
11757 to set maximum speed for migration. maximum speed in bytes per
11758 second. (Since 2.8)
11759 "downtime-limit: int" (optional)
11761 set maximum tolerated downtime for migration. maximum downtime in
11762 milliseconds (Since 2.8)
11763 "x-checkpoint-delay: int" (optional)
11765 the delay time between two COLO checkpoints. (Since 2.8)
11766 "block-incremental: boolean" (optional)
11768 Affects how much storage is migrated when the block migration
11769 capability is enabled. When false, the entire storage backing
11770 chain is migrated into a flattened image at the destination; when
11771 true, only the active qcow2 layer is migrated and the destination
11772 must already have access to the same backing chain as was used on
11773 the source. (since 2.10)
11774 "multifd-channels: int" (optional)
11776 Number of channels used to migrate data in parallel. This is the
11777 same number that the number of sockets used for migration. The
11778 default value is 2 (since 4.0)
11779 "xbzrle-cache-size: int" (optional)
11781 cache size to be used by XBZRLE migration. It needs to be a
11782 multiple of the target page size and a power of 2 (Since 2.11)
11783 "max-postcopy-bandwidth: int" (optional)
11785 Background transfer bandwidth during postcopy. Defaults to 0
11786 (unlimited). In bytes per second. (Since 3.0)
11787 "max-cpu-throttle: int" (optional)
11789 maximum cpu throttle percentage. The default value is 99. (Since
11790 3.1)
11791 "tls-authz: StrOrNull" (optional)
11793 Not documented
11794 Since: 2.4
11796 migrate-set-parameters (Command) Set various migration parameters.
11798 Arguments: the members of "MigrateSetParameters"
11800 Since: 2.4
11802 Example:
11804 -> { "execute": "migrate-set-parameters" ,
11806 "arguments": { "compress-level": 1 } }
11807 MigrationParameters (Object)
11809 The optional members aren't actually optional.
11811 Members:
11813 "announce-initial: int" (optional)
11815 Initial delay (in milliseconds) before sending the first announce
11816 (Since 4.0)
11817 "announce-max: int" (optional)
11819 Maximum delay (in milliseconds) between packets in the announcement
11820 (Since 4.0)
11821 "announce-rounds: int" (optional)
11823 Number of self-announce packets sent after migration (Since 4.0)
11824 "announce-step: int" (optional)
11826 Increase in delay (in milliseconds) between subsequent packets in
11827 the announcement (Since 4.0)
11828 "compress-level: int" (optional)
11830 compression level
11831 "compress-threads: int" (optional)
11833 compression thread count
11834 "compress-wait-thread: boolean" (optional)
11836 Controls behavior when all compression threads are currently busy.
11837 If true (default), wait for a free compression thread to become
11838 available; otherwise, send the page uncompressed. (Since 3.1)
11839 "decompress-threads: int" (optional)
11841 decompression thread count
11842 "cpu-throttle-initial: int" (optional)
11844 Initial percentage of time guest cpus are throttled when migration
11845 auto-converge is activated. (Since 2.7)
11846 "cpu-throttle-increment: int" (optional)
11848 throttle percentage increase each time auto-converge detects that
11849 migration is not making progress. (Since 2.7)
11850 "tls-creds: string" (optional)
11852 ID of the 'tls-creds' object that provides credentials for
11853 establishing a TLS connection over the migration data channel. On
11854 the outgoing side of the migration, the credentials must be for a
11855 'client' endpoint, while for the incoming side the credentials must
11856 be for a 'server' endpoint. An empty string means that QEMU will
11857 use plain text mode for migration, rather than TLS (Since 2.7)
11858 Note: 2.8 reports this by omitting tls-creds instead.
11859 "tls-hostname: string" (optional)
11861 hostname of the target host for the migration. This is required
11862 when using x509 based TLS credentials and the migration URI does
11863 not already include a hostname. For example if using fd: or exec:
11864 based migration, the hostname must be provided so that the server's
11865 x509 certificate identity can be validated. (Since 2.7) An empty
11866 string means that QEMU will use the hostname associated with the
11867 migration URI, if any. (Since 2.9) Note: 2.8 reports this by
11868 omitting tls-hostname instead.
11869 "tls-authz: string" (optional)
11871 ID of the 'authz' object subclass that provides access control
11872 checking of the TLS x509 certificate distinguished name. (Since
11873 4.0)
11874 "max-bandwidth: int" (optional)
11876 to set maximum speed for migration. maximum speed in bytes per
11877 second. (Since 2.8)
11878 "downtime-limit: int" (optional)
11880 set maximum tolerated downtime for migration. maximum downtime in
11881 milliseconds (Since 2.8)
11882 "x-checkpoint-delay: int" (optional)
11884 the delay time between two COLO checkpoints. (Since 2.8)
11885 "block-incremental: boolean" (optional)
11887 Affects how much storage is migrated when the block migration
11888 capability is enabled. When false, the entire storage backing
11889 chain is migrated into a flattened image at the destination; when
11890 true, only the active qcow2 layer is migrated and the destination
11891 must already have access to the same backing chain as was used on
11892 the source. (since 2.10)
11893 "multifd-channels: int" (optional)
11895 Number of channels used to migrate data in parallel. This is the
11896 same number that the number of sockets used for migration. The
11897 default value is 2 (since 4.0)
11898 "xbzrle-cache-size: int" (optional)
11900 cache size to be used by XBZRLE migration. It needs to be a
11901 multiple of the target page size and a power of 2 (Since 2.11)
11902 "max-postcopy-bandwidth: int" (optional)
11904 Background transfer bandwidth during postcopy. Defaults to 0
11905 (unlimited). In bytes per second. (Since 3.0)
11906 "max-cpu-throttle: int" (optional)
11908 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
11909 Since: 2.4
11911 query-migrate-parameters (Command) Returns information about the
11913 current migration parameters
11914 Returns: "MigrationParameters"
11916 Since: 2.4
11918 Example:
11920 -> { "execute": "query-migrate-parameters" }
11922 <- { "return": {
11923 "decompress-threads": 2,
11924 "cpu-throttle-increment": 10,
11925 "compress-threads": 8,
11926 "compress-level": 1,
11927 "cpu-throttle-initial": 20,
11928 "max-bandwidth": 33554432,
11929 "downtime-limit": 300
11930 }
11931 }
11932 client_migrate_info (Command) Set migration information for remote
11934 display. This makes the server ask the client to automatically
11935 reconnect using the new parameters once migration finished
11936 successfully. Only implemented for SPICE.
11937 Arguments:
11939 "protocol: string"
11941 must be "spice"
11942 "hostname: string"
11944 migration target hostname
11945 "port: int" (optional)
11947 spice tcp port for plaintext channels
11948 "tls-port: int" (optional)
11950 spice tcp port for tls-secured channels
11951 "cert-subject: string" (optional)
11953 server certificate subject
11954 Since: 0.14.0
11956 Example:
11958 -> { "execute": "client_migrate_info",
11960 "arguments": { "protocol": "spice",
11961 "hostname": "virt42.lab.kraxel.org",
11962 "port": 1234 } }
11963 <- { "return": {} }
11964 migrate-start-postcopy (Command) Followup to a migration command to
11966 switch the migration to postcopy mode. The postcopy-ram capability
11967 must be set on both source and destination before the original
11968 migration command.
11969 Since: 2.5
11971 Example:
11973 -> { "execute": "migrate-start-postcopy" }
11975 <- { "return": {} }
11976 MIGRATION (Event) Emitted when a migration event happens
11978 Arguments:
11980 "status: MigrationStatus"
11982 "MigrationStatus" describing the current migration status.
11983 Since: 2.4
11985 Example:
11987 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
11989 "event": "MIGRATION",
11990 "data": {"status": "completed"} }
11991 MIGRATION_PASS (Event) Emitted from the source side of a migration at
11993 the start of each pass (when it syncs the dirty bitmap)
11994 Arguments:
11996 "pass: int"
11998 An incrementing count (starting at 1 on the first pass)
11999 Since: 2.6
12001 Example:
12003 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
12005 "event": "MIGRATION_PASS", "data": {"pass": 2} }
12006 COLOMessage (Enum)
12008 The message transmission between Primary side and Secondary side.
12010 Values:
12012 "checkpoint-ready"
12014 Secondary VM (SVM) is ready for checkpointing
12015 "checkpoint-request"
12017 Primary VM (PVM) tells SVM to prepare for checkpointing
12018 "checkpoint-reply"
12020 SVM gets PVM's checkpoint request
12021 "vmstate-send"
12023 VM's state will be sent by PVM.
12024 "vmstate-size"
12026 The total size of VMstate.
12027 "vmstate-received"
12029 VM's state has been received by SVM.
12030 "vmstate-loaded"
12032 VM's state has been loaded by SVM.
12033 Since: 2.8
12035 COLOMode (Enum)
12037 The COLO current mode.
12039 Values:
12041 "none"
12043 COLO is disabled.
12044 "primary"
12046 COLO node in primary side.
12047 "secondary"
12049 COLO node in slave side.
12050 Since: 2.8
12052 FailoverStatus (Enum)
12054 An enumeration of COLO failover status
12056 Values:
12058 "none"
12060 no failover has ever happened
12061 "require"
12063 got failover requirement but not handled
12064 "active"
12066 in the process of doing failover
12067 "completed"
12069 finish the process of failover
12070 "relaunch"
12072 restart the failover process, from 'none' -> 'completed' (Since
12073 2.9)
12074 Since: 2.8
12076 COLO_EXIT (Event) Emitted when VM finishes COLO mode due to some
12078 errors happening or at the request of users.
12079 Arguments:
12081 "mode: COLOMode"
12083 report COLO mode when COLO exited.
12084 "reason: COLOExitReason"
12086 describes the reason for the COLO exit.
12087 Since: 3.1
12089 Example:
12091 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
12093 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
12094 COLOExitReason (Enum)
12096 The reason for a COLO exit.
12098 Values:
12100 "none"
12102 failover has never happened. This state does not occur in the
12103 COLO_EXIT event, and is only visible in the result of query-colo-
12104 status.
12105 "request"
12107 COLO exit is due to an external request.
12108 "error"
12110 COLO exit is due to an internal error.
12111 "processing"
12113 COLO is currently handling a failover (since 4.0).
12114 Since: 3.1
12116 x-colo-lost-heartbeat (Command) Tell qemu that heartbeat is lost,
12118 request it to do takeover procedures. If this command is sent to the
12119 PVM, the Primary side will exit COLO mode. If sent to the Secondary,
12120 the Secondary side will run failover work, then takes over server
12121 operation to become the service VM.
12122 Since: 2.8
12124 Example:
12126 -> { "execute": "x-colo-lost-heartbeat" }
12128 <- { "return": {} }
12129 migrate_cancel (Command) Cancel the current executing migration
12131 process.
12132 Returns: nothing on success
12134 Notes: This command succeeds even if there is no migration process
12136 running.
12137 Since: 0.14.0
12139 Example:
12141 -> { "execute": "migrate_cancel" }
12143 <- { "return": {} }
12144 migrate-continue (Command) Continue migration when it's in a paused
12146 state.
12147 Arguments:
12149 "state: MigrationStatus"
12151 The state the migration is currently expected to be in
12152 Returns: nothing on success
12154 Since: 2.11
12156 Example:
12158 -> { "execute": "migrate-continue" , "arguments":
12160 { "state": "pre-switchover" } }
12161 <- { "return": {} }
12162 migrate_set_downtime (Command) Set maximum tolerated downtime for
12164 migration.
12165 Arguments:
12167 "value: number"
12169 maximum downtime in seconds
12170 Returns: nothing on success
12172 Notes: This command is deprecated in favor of 'migrate-set-parameters'
12174 Since: 0.14.0
12176 Example:
12178 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
12180 <- { "return": {} }
12181 migrate_set_speed (Command) Set maximum speed for migration.
12183 Arguments:
12185 "value: int"
12187 maximum speed in bytes per second.
12188 Returns: nothing on success
12190 Notes: This command is deprecated in favor of 'migrate-set-parameters'
12192 Since: 0.14.0
12194 Example:
12196 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
12198 <- { "return": {} }
12199 migrate-set-cache-size (Command) Set cache size to be used by XBZRLE
12201 migration
12202 Arguments:
12204 "value: int"
12206 cache size in bytes
12207 The size will be rounded down to the nearest power of 2. The cache
12209 size can be modified before and during ongoing migration
12210 Returns: nothing on success
12212 Notes: This command is deprecated in favor of 'migrate-set-parameters'
12214 Since: 1.2
12216 Example:
12218 -> { "execute": "migrate-set-cache-size",
12220 "arguments": { "value": 536870912 } }
12221 <- { "return": {} }
12222 query-migrate-cache-size (Command) Query migration XBZRLE cache size
12224 Returns: XBZRLE cache size in bytes
12226 Notes: This command is deprecated in favor of
12228 'query-migrate-parameters'
12229 Since: 1.2
12231 Example:
12233 -> { "execute": "query-migrate-cache-size" }
12235 <- { "return": 67108864 }
12236 migrate (Command) Migrates the current running guest to another
12238 Virtual Machine.
12239 Arguments:
12241 "uri: string"
12243 the Uniform Resource Identifier of the destination VM
12244 "blk: boolean" (optional)
12246 do block migration (full disk copy)
12247 "inc: boolean" (optional)
12249 incremental disk copy migration
12250 "detach: boolean" (optional)
12252 this argument exists only for compatibility reasons and is ignored
12253 by QEMU
12254 "resume: boolean" (optional)
12256 resume one paused migration, default "off". (since 3.0)
12257 Returns: nothing on success
12259 Since: 0.14.0
12261 Notes:
12263 1. The 'query-migrate' command should be used to check migration's
12265 progress and final result (this information is provided by the
12266 'status' member)
12267 2. All boolean arguments default to false
12269 3. The user Monitor's "detach" argument is invalid in QMP and should
12271 not be used
12272 Example:
12274 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
12276 <- { "return": {} }
12277 migrate-incoming (Command) Start an incoming migration, the qemu must
12279 have been started with -incoming defer
12280 Arguments:
12282 "uri: string"
12284 The Uniform Resource Identifier identifying the source or address
12285 to listen on
12286 Returns: nothing on success
12288 Since: 2.3
12290 Notes:
12292 1. It's a bad idea to use a string for the uri, but it needs to stay
12294 compatible with -incoming and the format of the uri is already
12295 exposed above libvirt.
12296 2. QEMU must be started with -incoming defer to allow migrate-incoming
12298 to be used.
12299 3. The uri format is the same as for -incoming
12301 Example:
12303 -> { "execute": "migrate-incoming",
12305 "arguments": { "uri": "tcp::4446" } }
12306 <- { "return": {} }
12307 xen-save-devices-state (Command) Save the state of all devices to
12309 file. The RAM and the block devices of the VM are not saved by this
12310 command.
12311 Arguments:
12313 "filename: string"
12315 the file to save the state of the devices to as binary data. See
12316 xen-save-devices-state.txt for a description of the binary format.
12317 "live: boolean" (optional)
12319 Optional argument to ask QEMU to treat this command as part of a
12320 live migration. Default to true. (since 2.11)
12321 Returns: Nothing on success
12323 Since: 1.1
12325 Example:
12327 -> { "execute": "xen-save-devices-state",
12329 "arguments": { "filename": "/tmp/save" } }
12330 <- { "return": {} }
12331 xen-set-replication (Command) Enable or disable replication.
12333 Arguments:
12335 "enable: boolean"
12337 true to enable, false to disable.
12338 "primary: boolean"
12340 true for primary or false for secondary.
12341 "failover: boolean" (optional)
12343 true to do failover, false to stop. but cannot be specified if
12344 'enable' is true. default value is false.
12345 Returns: nothing.
12347 Example:
12349 -> { "execute": "xen-set-replication",
12351 "arguments": {"enable": true, "primary": false} }
12352 <- { "return": {} }
12353 Since: 2.9
12355 If: "defined(CONFIG_REPLICATION)"
12357 ReplicationStatus (Object)
12359 The result format for 'query-xen-replication-status'.
12361 Members:
12363 "error: boolean"
12365 true if an error happened, false if replication is normal.
12366 "desc: string" (optional)
12368 the human readable error description string, when "error" is
12369 'true'.
12370 Since: 2.9
12372 If: "defined(CONFIG_REPLICATION)"
12374 query-xen-replication-status (Command) Query replication status while
12376 the vm is running.
12377 Returns: A "ReplicationResult" object showing the status.
12379 Example:
12381 -> { "execute": "query-xen-replication-status" }
12383 <- { "return": { "error": false } }
12384 Since: 2.9
12386 If: "defined(CONFIG_REPLICATION)"
12388 xen-colo-do-checkpoint (Command) Xen uses this command to notify
12390 replication to trigger a checkpoint.
12391 Returns: nothing.
12393 Example:
12395 -> { "execute": "xen-colo-do-checkpoint" }
12397 <- { "return": {} }
12398 Since: 2.9
12400 If: "defined(CONFIG_REPLICATION)"
12402 COLOStatus (Object)
12404 The result format for 'query-colo-status'.
12406 Members:
12408 "mode: COLOMode"
12410 COLO running mode. If COLO is running, this field will return
12411 'primary' or 'secondary'.
12412 "last-mode: COLOMode"
12414 COLO last running mode. If COLO is running, this field will return
12415 same like mode field, after failover we can use this field to get
12416 last colo mode. (since 4.0)
12417 "reason: COLOExitReason"
12419 describes the reason for the COLO exit.
12420 Since: 3.1
12422 query-colo-status (Command) Query COLO status while the vm is running.
12424 Returns: A "COLOStatus" object showing the status.
12426 Example:
12428 -> { "execute": "query-colo-status" }
12430 <- { "return": { "mode": "primary", "reason": "request" } }
12431 Since: 3.1
12433 migrate-recover (Command) Provide a recovery migration stream URI.
12435 Arguments:
12437 "uri: string"
12439 the URI to be used for the recovery of migration stream.
12440 Returns: nothing.
12442 Example:
12444 -> { "execute": "migrate-recover",
12446 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
12447 <- { "return": {} }
12448 Since: 3.0
12450 migrate-pause (Command) Pause a migration. Currently it only supports
12452 postcopy.
12453 Returns: nothing.
12455 Example:
12457 -> { "execute": "migrate-pause" }
12459 <- { "return": {} }
12460 Since: 3.0
12462 UNPLUG_PRIMARY (Event) Emitted from source side of a migration when
12464 migration state is WAIT_UNPLUG. Device was unplugged by guest operating
12465 system. Device resources in QEMU are kept on standby to be able to re-
12466 plug it in case of migration failure.
12467 Arguments:
12469 "device-id: string"
12471 QEMU device id of the unplugged device
12472 Since: 4.2
12474 Example:
12476 {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} }
12478 Transactions
12480 Abort (Object)
12481 This action can be used to test transaction failure.
12483 Since: 1.6
12485 ActionCompletionMode (Enum)
12487 An enumeration of Transactional completion modes.
12489 Values:
12491 "individual"
12493 Do not attempt to cancel any other Actions if any Actions fail
12494 after the Transaction request succeeds. All Actions that can
12495 complete successfully will do so without waiting on others. This
12496 is the default.
12497 "grouped"
12499 If any Action fails after the Transaction succeeds, cancel all
12500 Actions. Actions do not complete until all Actions are ready to
12501 complete. May be rejected by Actions that do not support this
12502 completion mode.
12503 Since: 2.5
12505 TransactionAction (Object)
12507 A discriminated record of operations that can be performed with
12509 "transaction". Action "type" can be:
12510 - "abort": since 1.6
12512 - "block-dirty-bitmap-add": since 2.5
12514 - "block-dirty-bitmap-remove": since 4.2
12516 - "block-dirty-bitmap-clear": since 2.5
12518 - "block-dirty-bitmap-enable": since 4.0
12520 - "block-dirty-bitmap-disable": since 4.0
12522 - "block-dirty-bitmap-merge": since 4.0
12524 - "blockdev-backup": since 2.3
12526 - "blockdev-snapshot": since 2.5
12528 - "blockdev-snapshot-internal-sync": since 1.7
12530 - "blockdev-snapshot-sync": since 1.1
12532 - "drive-backup": since 1.6
12534 Members:
12536 "type"
12538 One of "abort", "block-dirty-bitmap-add", "block-dirty-bitmap-
12539 remove", "block-dirty-bitmap-clear", "block-dirty-bitmap-enable",
12540 "block-dirty-bitmap-disable", "block-dirty-bitmap-merge",
12541 "blockdev-backup", "blockdev-snapshot", "blockdev-snapshot-
12542 internal-sync", "blockdev-snapshot-sync", "drive-backup"
12543 "data: Abort" when "type" is "abort"
12545 "data: BlockDirtyBitmapAdd" when "type" is "block-dirty-bitmap-add"
12546 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-remove"
12547 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-clear"
12548 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-enable"
12549 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-disable"
12550 "data: BlockDirtyBitmapMerge" when "type" is "block-dirty-bitmap-merge"
12551 "data: BlockdevBackup" when "type" is "blockdev-backup"
12552 "data: BlockdevSnapshot" when "type" is "blockdev-snapshot"
12553 "data: BlockdevSnapshotInternal" when "type" is "blockdev-snapshot-
12554 internal-sync"
12555 "data: BlockdevSnapshotSync" when "type" is "blockdev-snapshot-sync"
12556 "data: DriveBackup" when "type" is "drive-backup"
12557 Since: 1.1
12559 TransactionProperties (Object)
12561 Optional arguments to modify the behavior of a Transaction.
12563 Members:
12565 "completion-mode: ActionCompletionMode" (optional)
12567 Controls how jobs launched asynchronously by Actions will complete
12568 or fail as a group. See "ActionCompletionMode" for details.
12569 Since: 2.5
12571 transaction (Command) Executes a number of transactionable QMP
12573 commands atomically. If any operation fails, then the entire set of
12574 actions will be abandoned and the appropriate error returned.
12575 For external snapshots, the dictionary contains the device, the file to
12577 use for the new snapshot, and the format. The default format, if not
12578 specified, is qcow2.
12579 Each new snapshot defaults to being created by QEMU (wiping any
12581 contents if the file already exists), but it is also possible to reuse
12582 an externally-created file. In the latter case, you should ensure that
12583 the new image file has the same contents as the current one; QEMU
12584 cannot perform any meaningful check. Typically this is achieved by
12585 using the current image file as the backing file for the new image.
12586 On failure, the original disks pre-snapshot attempt will be used.
12588 For internal snapshots, the dictionary contains the device and the
12590 snapshot's name. If an internal snapshot matching name already exists,
12591 the request will be rejected. Only some image formats support it, for
12592 example, qcow2, rbd, and sheepdog.
12593 On failure, qemu will try delete the newly created internal snapshot in
12595 the transaction. When an I/O error occurs during deletion, the user
12596 needs to fix it later with qemu-img or other command.
12597 Arguments:
12599 "actions: array of TransactionAction"
12601 List of "TransactionAction"; information needed for the respective
12602 operations.
12603 "properties: TransactionProperties" (optional)
12605 structure of additional options to control the execution of the
12606 transaction. See "TransactionProperties" for additional detail.
12607 Returns: nothing on success
12609 Errors depend on the operations of the transaction
12611 Note: The transaction aborts on the first failure. Therefore, there
12613 will be information on only one failed operation returned in an error
12614 condition, and subsequent actions will not have been attempted.
12615 Since: 1.1
12617 Example:
12619 -> { "execute": "transaction",
12621 "arguments": { "actions": [
12622 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
12623 "snapshot-file": "/some/place/my-image",
12624 "format": "qcow2" } },
12625 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
12626 "snapshot-file": "/some/place/my-image2",
12627 "snapshot-node-name": "node3432",
12628 "mode": "existing",
12629 "format": "qcow2" } },
12630 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
12631 "snapshot-file": "/some/place/my-image2",
12632 "mode": "existing",
12633 "format": "qcow2" } },
12634 { "type": "blockdev-snapshot-internal-sync", "data" : {
12635 "device": "ide-hd2",
12636 "name": "snapshot0" } } ] } }
12637 <- { "return": {} }
12638 Tracing
12640 TraceEventState (Enum)
12641 State of a tracing event.
12643 Values:
12645 "unavailable"
12647 The event is statically disabled.
12648 "disabled"
12650 The event is dynamically disabled.
12651 "enabled"
12653 The event is dynamically enabled.
12654 Since: 2.2
12656 TraceEventInfo (Object)
12658 Information of a tracing event.
12660 Members:
12662 "name: string"
12664 Event name.
12665 "state: TraceEventState"
12667 Tracing state.
12668 "vcpu: boolean"
12670 Whether this is a per-vCPU event (since 2.7).
12671 An event is per-vCPU if it has the "vcpu" property in the "trace-
12673 events" files.
12674 Since: 2.2
12676 trace-event-get-state (Command) Query the state of events.
12678 Arguments:
12680 "name: string"
12682 Event name pattern (case-sensitive glob).
12683 "vcpu: int" (optional)
12685 The vCPU to query (any by default; since 2.7).
12686 Returns: a list of "TraceEventInfo" for the matching events
12688 An event is returned if:
12690 - its name matches the "name" pattern, and
12692 - if "vcpu" is given, the event has the "vcpu" property.
12694 Therefore, if "vcpu" is given, the operation will only match per-vCPU
12696 events, returning their state on the specified vCPU. Special case: if
12697 "name" is an exact match, "vcpu" is given and the event does not have
12698 the "vcpu" property, an error is returned.
12699 Since: 2.2
12701 Example:
12703 -> { "execute": "trace-event-get-state",
12705 "arguments": { "name": "qemu_memalign" } }
12706 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
12707 trace-event-set-state (Command) Set the dynamic tracing state of
12709 events.
12710 Arguments:
12712 "name: string"
12714 Event name pattern (case-sensitive glob).
12715 "enable: boolean"
12717 Whether to enable tracing.
12718 "ignore-unavailable: boolean" (optional)
12720 Do not match unavailable events with "name".
12721 "vcpu: int" (optional)
12723 The vCPU to act upon (all by default; since 2.7).
12724 An event's state is modified if:
12726 - its name matches the "name" pattern, and
12728 - if "vcpu" is given, the event has the "vcpu" property.
12730 Therefore, if "vcpu" is given, the operation will only match per-vCPU
12732 events, setting their state on the specified vCPU. Special case: if
12733 "name" is an exact match, "vcpu" is given and the event does not have
12734 the "vcpu" property, an error is returned.
12735 Since: 2.2
12737 Example:
12739 -> { "execute": "trace-event-set-state",
12741 "arguments": { "name": "qemu_memalign", "enable": "true" } }
12742 <- { "return": {} }
12743 QMP introspection
12745 query-qmp-schema (Command) Command query-qmp-schema exposes the QMP
12746 wire ABI as an array of SchemaInfo. This lets QMP clients figure out
12747 what commands and events are available in this QEMU, and their
12748 parameters and results.
12749 However, the SchemaInfo can't reflect all the rules and restrictions
12751 that apply to QMP. It's interface introspection (figuring out what's
12752 there), not interface specification. The specification is in the QAPI
12753 schema.
12754 Furthermore, while we strive to keep the QMP wire format backwards-
12756 compatible across qemu versions, the introspection output is not
12757 guaranteed to have the same stability. For example, one version of
12758 qemu may list an object member as an optional non-variant, while
12759 another lists the same member only through the object's variants; or
12760 the type of a member may change from a generic string into a specific
12761 enum or from one specific type into an alternate that includes the
12762 original type alongside something else.
12763 Returns: array of "SchemaInfo", where each element describes an entity
12765 in the ABI: command, event, type, ...
12766 The order of the various SchemaInfo is unspecified; however, all names
12768 are guaranteed to be unique (no name will be duplicated with different
12769 meta-types).
12770 Note: the QAPI schema is also used to help define internal interfaces,
12772 by defining QAPI types. These are not part of the QMP wire ABI, and
12773 therefore not returned by this command.
12774 Since: 2.5
12776 SchemaMetaType (Enum)
12778 This is a "SchemaInfo"'s meta type, i.e. the kind of entity it
12780 describes.
12781 Values:
12783 "builtin"
12785 a predefined type such as 'int' or 'bool'.
12786 "enum"
12788 an enumeration type
12789 "array"
12791 an array type
12792 "object"
12794 an object type (struct or union)
12795 "alternate"
12797 an alternate type
12798 "command"
12800 a QMP command
12801 "event"
12803 a QMP event
12804 Since: 2.5
12806 SchemaInfo (Object)
12808 Members:
12810 "name: string"
12812 the entity's name, inherited from "base". The SchemaInfo is always
12813 referenced by this name. Commands and events have the name defined
12814 in the QAPI schema. Unlike command and event names, type names are
12815 not part of the wire ABI. Consequently, type names are meaningless
12816 strings here, although they are still guaranteed unique regardless
12817 of "meta-type".
12818 "meta-type: SchemaMetaType"
12820 the entity's meta type, inherited from "base".
12821 The members of "SchemaInfoBuiltin" when "meta-type" is "builtin"
12823 The members of "SchemaInfoEnum" when "meta-type" is "enum"
12824 The members of "SchemaInfoArray" when "meta-type" is "array"
12825 The members of "SchemaInfoObject" when "meta-type" is "object"
12826 The members of "SchemaInfoAlternate" when "meta-type" is "alternate"
12827 The members of "SchemaInfoCommand" when "meta-type" is "command"
12828 The members of "SchemaInfoEvent" when "meta-type" is "event"
12829 Additional members depend on the value of "meta-type".
12831 Since: 2.5
12833 SchemaInfoBuiltin (Object)
12835 Additional SchemaInfo members for meta-type 'builtin'.
12837 Members:
12839 "json-type: JSONType"
12841 the JSON type used for this type on the wire.
12842 Since: 2.5
12844 JSONType (Enum)
12846 The four primitive and two structured types according to RFC 8259
12848 section 1, plus 'int' (split off 'number'), plus the obvious top type
12849 'value'.
12850 Values:
12852 "string"
12854 Not documented
12855 "number"
12857 Not documented
12858 "int"
12860 Not documented
12861 "boolean"
12863 Not documented
12864 "null"
12866 Not documented
12867 "object"
12869 Not documented
12870 "array"
12872 Not documented
12873 "value"
12875 Not documented
12876 Since: 2.5
12878 SchemaInfoEnum (Object)
12880 Additional SchemaInfo members for meta-type 'enum'.
12882 Members:
12884 "values: array of string"
12886 the enumeration type's values, in no particular order.
12887 Values of this type are JSON string on the wire.
12889 Since: 2.5
12891 SchemaInfoArray (Object)
12893 Additional SchemaInfo members for meta-type 'array'.
12895 Members:
12897 "element-type: string"
12899 the array type's element type.
12900 Values of this type are JSON array on the wire.
12902 Since: 2.5
12904 SchemaInfoObject (Object)
12906 Additional SchemaInfo members for meta-type 'object'.
12908 Members:
12910 "members: array of SchemaInfoObjectMember"
12912 the object type's (non-variant) members, in no particular order.
12913 "tag: string" (optional)
12915 the name of the member serving as type tag. An element of
12916 "members" with this name must exist.
12917 "variants: array of SchemaInfoObjectVariant" (optional)
12919 variant members, i.e. additional members that depend on the type
12920 tag's value. Present exactly when "tag" is present. The variants
12921 are in no particular order, and may even differ from the order of
12922 the values of the enum type of the "tag".
12923 "features: array of string" (optional)
12925 names of features associated with the type, in no particular order.
12926 (since: 4.1)
12927 Values of this type are JSON object on the wire.
12929 Since: 2.5
12931 SchemaInfoObjectMember (Object)
12933 An object member.
12935 Members:
12937 "name: string"
12939 the member's name, as defined in the QAPI schema.
12940 "type: string"
12942 the name of the member's type.
12943 "default: value" (optional)
12945 default when used as command parameter. If absent, the parameter
12946 is mandatory. If present, the value must be null. The parameter
12947 is optional, and behavior when it's missing is not specified here.
12948 Future extension: if present and non-null, the parameter is
12949 optional, and defaults to this value.
12950 Since: 2.5
12952 SchemaInfoObjectVariant (Object)
12954 The variant members for a value of the type tag.
12956 Members:
12958 "case: string"
12960 a value of the type tag.
12961 "type: string"
12963 the name of the object type that provides the variant members when
12964 the type tag has value "case".
12965 Since: 2.5
12967 SchemaInfoAlternate (Object)
12969 Additional SchemaInfo members for meta-type 'alternate'.
12971 Members:
12973 "members: array of SchemaInfoAlternateMember"
12975 the alternate type's members, in no particular order. The members'
12976 wire encoding is distinct, see docs/devel/qapi-code-gen.txt section
12977 Alternate types.
12978 On the wire, this can be any of the members.
12980 Since: 2.5
12982 SchemaInfoAlternateMember (Object)
12984 An alternate member.
12986 Members:
12988 "type: string"
12990 the name of the member's type.
12991 Since: 2.5
12993 SchemaInfoCommand (Object)
12995 Additional SchemaInfo members for meta-type 'command'.
12997 Members:
12999 "arg-type: string"
13001 the name of the object type that provides the command's parameters.
13002 "ret-type: string"
13004 the name of the command's result type.
13005 "allow-oob: boolean" (optional)
13007 whether the command allows out-of-band execution, defaults to false
13008 (Since: 2.12)
13009 "features: array of string" (optional)
13011 names of features associated with the command, in no particular
13012 order. (since 4.2)
13013 TODO: "success-response" (currently irrelevant, because it's QGA, not
13015 QMP)
13016 Since: 2.5
13018 SchemaInfoEvent (Object)
13020 Additional SchemaInfo members for meta-type 'event'.
13022 Members:
13024 "arg-type: string"
13026 the name of the object type that provides the event's parameters.
13027 Since: 2.5
13029 QEMU Object Model (QOM)
13031 ObjectPropertyInfo (Object)
13032 Members:
13034 "name: string"
13036 the name of the property
13037 "type: string"
13039 the type of the property. This will typically come in one of four
13040 forms:
13041 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or
13043 'double'. These types are mapped to the appropriate JSON type.
13044 2) A child type in the form 'child<subtype>' where subtype is a
13046 qdev device type name. Child properties create the composition
13047 tree.
13048 3) A link type in the form 'link<subtype>' where subtype is a qdev
13050 device type name. Link properties form the device model graph.
13051 "description: string" (optional)
13053 if specified, the description of the property.
13054 Since: 1.2
13056 qom-list (Command) This command will list any properties of a object
13058 given a path in the object model.
13059 Arguments:
13061 "path: string"
13063 the path within the object model. See "qom-get" for a description
13064 of this parameter.
13065 Returns: a list of "ObjectPropertyInfo" that describe the properties of
13067 the object.
13068 Since: 1.2
13070 Example:
13072 -> { "execute": "qom-list",
13074 "arguments": { "path": "/chardevs" } }
13075 <- { "return": [ { "name": "type", "type": "string" },
13076 { "name": "parallel0", "type": "child<chardev-vc>" },
13077 { "name": "serial0", "type": "child<chardev-vc>" },
13078 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
13079 qom-get (Command) This command will get a property from a object model
13081 path and return the value.
13082 Arguments:
13084 "path: string"
13086 The path within the object model. There are two forms of supported
13087 paths--absolute and partial paths.
13088 Absolute paths are derived from the root object and can follow
13090 child<> or link<> properties. Since they can follow link<>
13091 properties, they can be arbitrarily long. Absolute paths look like
13092 absolute filenames and are prefixed with a leading slash.
13093 Partial paths look like relative filenames. They do not begin with
13095 a prefix. The matching rules for partial paths are subtle but
13096 designed to make specifying objects easy. At each level of the
13097 composition tree, the partial path is matched as an absolute path.
13098 The first match is not returned. At least two matches are searched
13099 for. A successful result is only returned if only one match is
13100 found. If more than one match is found, a flag is return to
13101 indicate that the match was ambiguous.
13102 "property: string"
13104 The property name to read
13105 Returns: The property value. The type depends on the property type.
13107 child<> and link<> properties are returned as #str pathnames. All
13108 integer property types (u8, u16, etc) are returned as #int.
13109 Since: 1.2
13111 Example:
13113 1. Use absolute path
13115 -> { "execute": "qom-get",
13117 "arguments": { "path": "/machine/unattached/device[0]",
13118 "property": "hotplugged" } }
13119 <- { "return": false }
13120 2. Use partial path
13122 -> { "execute": "qom-get",
13124 "arguments": { "path": "unattached/sysbus",
13125 "property": "type" } }
13126 <- { "return": "System" }
13127 qom-set (Command) This command will set a property from a object model
13129 path.
13130 Arguments:
13132 "path: string"
13134 see "qom-get" for a description of this parameter
13135 "property: string"
13137 the property name to set
13138 "value: value"
13140 a value who's type is appropriate for the property type. See
13141 "qom-get" for a description of type mapping.
13142 Since: 1.2
13144 Example:
13146 -> { "execute": "qom-set",
13148 "arguments": { "path": "/machine",
13149 "property": "graphics",
13150 "value": false } }
13151 <- { "return": {} }
13152 ObjectTypeInfo (Object)
13154 This structure describes a search result from "qom-list-types"
13156 Members:
13158 "name: string"
13160 the type name found in the search
13161 "abstract: boolean" (optional)
13163 the type is abstract and can't be directly instantiated. Omitted
13164 if false. (since 2.10)
13165 "parent: string" (optional)
13167 Name of parent type, if any (since 2.10)
13168 Since: 1.1
13170 qom-list-types (Command) This command will return a list of types
13172 given search parameters
13173 Arguments:
13175 "implements: string" (optional)
13177 if specified, only return types that implement this type name
13178 "abstract: boolean" (optional)
13180 if true, include abstract types in the results
13181 Returns: a list of "ObjectTypeInfo" or an empty list if no results are
13183 found
13184 Since: 1.1
13186 qom-list-properties (Command) List properties associated with a QOM
13188 object.
13189 Arguments:
13191 "typename: string"
13193 the type name of an object
13194 Note: objects can create properties at runtime, for example to describe
13196 links between different devices and/or objects. These properties are
13197 not included in the output of this command.
13198 Returns: a list of ObjectPropertyInfo describing object properties
13200 Since: 2.12
13202 object-add (Command) Create a QOM object.
13204 Arguments:
13206 "qom-type: string"
13208 the class name for the object to be created
13209 "id: string"
13211 the name of the new object
13212 "props: value" (optional)
13214 a dictionary of properties to be passed to the backend
13215 Returns: Nothing on success Error if "qom-type" is not a valid class
13217 name
13218 Since: 2.0
13220 Example:
13222 -> { "execute": "object-add",
13224 "arguments": { "qom-type": "rng-random", "id": "rng1",
13225 "props": { "filename": "/dev/hwrng" } } }
13226 <- { "return": {} }
13227 object-del (Command) Remove a QOM object.
13229 Arguments:
13231 "id: string"
13233 the name of the QOM object to remove
13234 Returns: Nothing on success Error if "id" is not a valid id for a QOM
13236 object
13237 Since: 2.0
13239 Example:
13241 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
13243 <- { "return": {} }
13244 Device infrastructure (qdev)
13246 device-list-properties (Command) List properties associated with a
13247 device.
13248 Arguments:
13250 "typename: string"
13252 the type name of a device
13253 Returns: a list of ObjectPropertyInfo describing a devices properties
13255 Note: objects can create properties at runtime, for example to describe
13257 links between different devices and/or objects. These properties are
13258 not included in the output of this command.
13259 Since: 1.2
13261 device_add (Command)
13263 Arguments:
13265 "driver: string"
13267 the name of the new device's driver
13268 "bus: string" (optional)
13270 the device's parent bus (device tree path)
13271 "id: string" (optional)
13273 the device's ID, must be unique
13274 Additional arguments depend on the type.
13276 Add a device.
13278 Notes:
13280 1. For detailed information about this command, please refer to the
13282 'docs/qdev-device-use.txt' file.
13283 2. It's possible to list device properties by running QEMU with the
13285 "-device DEVICE,help" command-line argument, where DEVICE is the
13286 device's name
13287 Example:
13289 -> { "execute": "device_add",
13291 "arguments": { "driver": "e1000", "id": "net1",
13292 "bus": "pci.0",
13293 "mac": "52:54:00:12:34:56" } }
13294 <- { "return": {} }
13295 TODO: This command effectively bypasses QAPI completely due to its
13297 "additional arguments" business. It shouldn't have been added to the
13298 schema in this form. It should be qapified properly, or replaced by a
13299 properly qapified command.
13300 Since: 0.13
13302 device_del (Command) Remove a device from a guest
13304 Arguments:
13306 "id: string"
13308 the device's ID or QOM path
13309 Returns: Nothing on success If "id" is not a valid device,
13311 DeviceNotFound
13312 Notes: When this command completes, the device may not be removed from
13314 the guest. Hot removal is an operation that requires guest
13315 cooperation. This command merely requests that the guest begin the hot
13316 removal process. Completion of the device removal process is signaled
13317 with a DEVICE_DELETED event. Guest reset will automatically complete
13318 removal for all devices.
13319 Since: 0.14.0
13321 Example:
13323 -> { "execute": "device_del",
13325 "arguments": { "id": "net1" } }
13326 <- { "return": {} }
13327 -> { "execute": "device_del",
13329 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
13330 <- { "return": {} }
13331 DEVICE_DELETED (Event) Emitted whenever the device removal completion
13333 is acknowledged by the guest. At this point, it's safe to reuse the
13334 specified device ID. Device removal can be initiated by the guest or by
13335 HMP/QMP commands.
13336 Arguments:
13338 "device: string" (optional)
13340 device name
13341 "path: string"
13343 device path
13344 Since: 1.5
13346 Example:
13348 <- { "event": "DEVICE_DELETED",
13350 "data": { "device": "virtio-net-pci-0",
13351 "path": "/machine/peripheral/virtio-net-pci-0" },
13352 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
13353 Machines
13355 SysEmuTarget (Enum)
13356 The comprehensive enumeration of QEMU system emulation ("softmmu")
13358 targets. Run "./configure --help" in the project root directory, and
13359 look for the *-softmmu targets near the "--target-list" option. The
13360 individual target constants are not documented here, for the time
13361 being.
13362 Values:
13364 "aarch64"
13366 Not documented
13367 "alpha"
13369 Not documented
13370 "arm"
13372 Not documented
13373 "cris"
13375 Not documented
13376 "hppa"
13378 Not documented
13379 "i386"
13381 Not documented
13382 "lm32"
13384 Not documented
13385 "m68k"
13387 Not documented
13388 "microblaze"
13390 Not documented
13391 "microblazeel"
13393 Not documented
13394 "mips"
13396 Not documented
13397 "mips64"
13399 Not documented
13400 "mips64el"
13402 Not documented
13403 "mipsel"
13405 Not documented
13406 "moxie"
13408 Not documented
13409 "nios2"
13411 Not documented
13412 "or1k"
13414 Not documented
13415 "ppc"
13417 Not documented
13418 "ppc64"
13420 Not documented
13421 "riscv32"
13423 Not documented
13424 "riscv64"
13426 Not documented
13427 "s390x"
13429 Not documented
13430 "sh4"
13432 Not documented
13433 "sh4eb"
13435 Not documented
13436 "sparc"
13438 Not documented
13439 "sparc64"
13441 Not documented
13442 "tricore"
13444 Not documented
13445 "unicore32"
13447 Not documented
13448 "x86_64"
13450 Not documented
13451 "xtensa"
13453 Not documented
13454 "xtensaeb"
13456 Not documented
13457 Notes: The resulting QMP strings can be appended to the "qemu-system-"
13459 prefix to produce the corresponding QEMU executable name. This is true
13460 even for "qemu-system-x86_64".
13461 ppcemb: dropped in 3.1
13463 Since: 3.0
13465 CpuInfoArch (Enum)
13467 An enumeration of cpu types that enable additional information during
13469 "query-cpus" and "query-cpus-fast".
13470 Values:
13472 "s390"
13474 since 2.12
13475 "riscv"
13477 since 2.12
13478 "x86"
13480 Not documented
13481 "sparc"
13483 Not documented
13484 "ppc"
13486 Not documented
13487 "mips"
13489 Not documented
13490 "tricore"
13492 Not documented
13493 "other"
13495 Not documented
13496 Since: 2.6
13498 CpuInfo (Object)
13500 Information about a virtual CPU
13502 Members:
13504 "CPU: int"
13506 the index of the virtual CPU
13507 "current: boolean"
13509 this only exists for backwards compatibility and should be ignored
13510 "halted: boolean"
13512 true if the virtual CPU is in the halt state. Halt usually refers
13513 to a processor specific low power mode.
13514 "qom_path: string"
13516 path to the CPU object in the QOM tree (since 2.4)
13517 "thread_id: int"
13519 ID of the underlying host thread
13520 "props: CpuInstanceProperties" (optional)
13522 properties describing to which node/socket/core/thread virtual CPU
13523 belongs to, provided if supported by board (since 2.10)
13524 "arch: CpuInfoArch"
13526 architecture of the cpu, which determines which additional fields
13527 will be listed (since 2.6)
13528 The members of "CpuInfoX86" when "arch" is "x86"
13530 The members of "CpuInfoSPARC" when "arch" is "sparc"
13531 The members of "CpuInfoPPC" when "arch" is "ppc"
13532 The members of "CpuInfoMIPS" when "arch" is "mips"
13533 The members of "CpuInfoTricore" when "arch" is "tricore"
13534 The members of "CpuInfoS390" when "arch" is "s390"
13535 The members of "CpuInfoRISCV" when "arch" is "riscv"
13536 Since: 0.14.0
13538 Notes: "halted" is a transient state that changes frequently. By the
13540 time the data is sent to the client, the guest may no longer be halted.
13541 CpuInfoX86 (Object)
13543 Additional information about a virtual i386 or x86_64 CPU
13545 Members:
13547 "pc: int"
13549 the 64-bit instruction pointer
13550 Since: 2.6
13552 CpuInfoSPARC (Object)
13554 Additional information about a virtual SPARC CPU
13556 Members:
13558 "pc: int"
13560 the PC component of the instruction pointer
13561 "npc: int"
13563 the NPC component of the instruction pointer
13564 Since: 2.6
13566 CpuInfoPPC (Object)
13568 Additional information about a virtual PPC CPU
13570 Members:
13572 "nip: int"
13574 the instruction pointer
13575 Since: 2.6
13577 CpuInfoMIPS (Object)
13579 Additional information about a virtual MIPS CPU
13581 Members:
13583 "PC: int"
13585 the instruction pointer
13586 Since: 2.6
13588 CpuInfoTricore (Object)
13590 Additional information about a virtual Tricore CPU
13592 Members:
13594 "PC: int"
13596 the instruction pointer
13597 Since: 2.6
13599 CpuInfoRISCV (Object)
13601 Additional information about a virtual RISCV CPU
13603 Members:
13605 "pc: int"
13607 the instruction pointer
13608 Since 2.12
13610 CpuS390State (Enum)
13612 An enumeration of cpu states that can be assumed by a virtual S390 CPU
13614 Values:
13616 "uninitialized"
13618 Not documented
13619 "stopped"
13621 Not documented
13622 "check-stop"
13624 Not documented
13625 "operating"
13627 Not documented
13628 "load"
13630 Not documented
13631 Since: 2.12
13633 CpuInfoS390 (Object)
13635 Additional information about a virtual S390 CPU
13637 Members:
13639 "cpu-state: CpuS390State"
13641 the virtual CPU's state
13642 Since: 2.12
13644 query-cpus (Command) Returns a list of information about each virtual
13646 CPU.
13647 This command causes vCPU threads to exit to userspace, which causes a
13649 small interruption to guest CPU execution. This will have a negative
13650 impact on realtime guests and other latency sensitive guest workloads.
13651 It is recommended to use "query-cpus-fast" instead of this command to
13652 avoid the vCPU interruption.
13653 Returns: a list of "CpuInfo" for each virtual CPU
13655 Since: 0.14.0
13657 Example:
13659 -> { "execute": "query-cpus" }
13661 <- { "return": [
13662 {
13663 "CPU":0,
13664 "current":true,
13665 "halted":false,
13666 "qom_path":"/machine/unattached/device[0]",
13667 "arch":"x86",
13668 "pc":3227107138,
13669 "thread_id":3134
13670 },
13671 {
13672 "CPU":1,
13673 "current":false,
13674 "halted":true,
13675 "qom_path":"/machine/unattached/device[2]",
13676 "arch":"x86",
13677 "pc":7108165,
13678 "thread_id":3135
13679 }
13680 ]
13681 }
13682 Notes: This interface is deprecated (since 2.12.0), and it is strongly
13684 recommended that you avoid using it. Use "query-cpus-fast" to obtain
13685 information about virtual CPUs.
13686 CpuInfoFast (Object)
13688 Information about a virtual CPU
13690 Members:
13692 "cpu-index: int"
13694 index of the virtual CPU
13695 "qom-path: string"
13697 path to the CPU object in the QOM tree
13698 "thread-id: int"
13700 ID of the underlying host thread
13701 "props: CpuInstanceProperties" (optional)
13703 properties describing to which node/socket/core/thread virtual CPU
13704 belongs to, provided if supported by board
13705 "arch: CpuInfoArch"
13707 base architecture of the cpu; deprecated since 3.0.0 in favor of
13708 "target"
13709 "target: SysEmuTarget"
13711 the QEMU system emulation target, which determines which additional
13712 fields will be listed (since 3.0)
13713 The members of "CpuInfoS390" when "target" is "s390x"
13715 Since: 2.12
13717 query-cpus-fast (Command) Returns information about all virtual CPUs.
13719 This command does not incur a performance penalty and should be used in
13720 production instead of query-cpus.
13721 Returns: list of "CpuInfoFast"
13723 Since: 2.12
13725 Example:
13727 -> { "execute": "query-cpus-fast" }
13729 <- { "return": [
13730 {
13731 "thread-id": 25627,
13732 "props": {
13733 "core-id": 0,
13734 "thread-id": 0,
13735 "socket-id": 0
13736 },
13737 "qom-path": "/machine/unattached/device[0]",
13738 "arch":"x86",
13739 "target":"x86_64",
13740 "cpu-index": 0
13741 },
13742 {
13743 "thread-id": 25628,
13744 "props": {
13745 "core-id": 0,
13746 "thread-id": 0,
13747 "socket-id": 1
13748 },
13749 "qom-path": "/machine/unattached/device[2]",
13750 "arch":"x86",
13751 "target":"x86_64",
13752 "cpu-index": 1
13753 }
13754 ]
13755 }
13756 cpu-add (Command) Adds CPU with specified ID.
13758 Arguments:
13760 "id: int"
13762 ID of CPU to be created, valid values [0..max_cpus)
13763 Returns: Nothing on success
13765 Since: 1.5
13767 Note: This command is deprecated. The `device_add` command should be
13769 used instead. See the `query-hotpluggable-cpus` command for details.
13770 Example:
13772 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
13774 <- { "return": {} }
13775 MachineInfo (Object)
13777 Information describing a machine.
13779 Members:
13781 "name: string"
13783 the name of the machine
13784 "alias: string" (optional)
13786 an alias for the machine name
13787 "is-default: boolean" (optional)
13789 whether the machine is default
13790 "cpu-max: int"
13792 maximum number of CPUs supported by the machine type (since 1.5.0)
13793 "hotpluggable-cpus: boolean"
13795 cpu hotplug via -device is supported (since 2.7.0)
13796 "numa-mem-supported: boolean"
13798 true if '-numa node,mem' option is supported by the machine type
13799 and false otherwise (since 4.1)
13800 "deprecated: boolean"
13802 if true, the machine type is deprecated and may be removed in
13803 future versions of QEMU according to the QEMU deprecation policy
13804 (since 4.1.0)
13805 "default-cpu-type: string" (optional)
13807 default CPU model typename if none is requested via the -cpu
13808 argument. (since 4.2)
13809 Since: 1.2.0
13811 query-machines (Command) Return a list of supported machines
13813 Returns: a list of MachineInfo
13815 Since: 1.2.0
13817 CurrentMachineParams (Object)
13819 Information describing the running machine parameters.
13821 Members:
13823 "wakeup-suspend-support: boolean"
13825 true if the machine supports wake up from suspend
13826 Since: 4.0
13828 query-current-machine (Command) Return information on the current
13830 virtual machine.
13831 Returns: CurrentMachineParams
13833 Since: 4.0
13835 TargetInfo (Object)
13837 Information describing the QEMU target.
13839 Members:
13841 "arch: SysEmuTarget"
13843 the target architecture
13844 Since: 1.2.0
13846 query-target (Command) Return information about the target for this
13848 QEMU
13849 Returns: TargetInfo
13851 Since: 1.2.0
13853 NumaOptionsType (Enum)
13855 Values:
13857 "node"
13859 NUMA nodes configuration
13860 "dist"
13862 NUMA distance configuration (since 2.10)
13863 "cpu"
13865 property based CPU(s) to node mapping (Since: 2.10)
13866 Since: 2.1
13868 NumaOptions (Object)
13870 A discriminated record of NUMA options. (for OptsVisitor)
13872 Members:
13874 "type: NumaOptionsType"
13876 Not documented
13877 The members of "NumaNodeOptions" when "type" is "node"
13879 The members of "NumaDistOptions" when "type" is "dist"
13880 The members of "NumaCpuOptions" when "type" is "cpu"
13881 Since: 2.1
13883 NumaNodeOptions (Object)
13885 Create a guest NUMA node. (for OptsVisitor)
13887 Members:
13889 "nodeid: int" (optional)
13891 NUMA node ID (increase by 1 from 0 if omitted)
13892 "cpus: array of int" (optional)
13894 VCPUs belonging to this node (assign VCPUS round-robin if omitted)
13895 "mem: int" (optional)
13897 memory size of this node; mutually exclusive with "memdev".
13898 Equally divide total memory among nodes if both "mem" and "memdev"
13899 are omitted.
13900 "memdev: string" (optional)
13902 memory backend object. If specified for one node, it must be
13903 specified for all nodes.
13904 Since: 2.1
13906 NumaDistOptions (Object)
13908 Set the distance between 2 NUMA nodes.
13910 Members:
13912 "src: int"
13914 source NUMA node.
13915 "dst: int"
13917 destination NUMA node.
13918 "val: int"
13920 NUMA distance from source node to destination node. When a node is
13921 unreachable from another node, set the distance between them to
13922 255.
13923 Since: 2.10
13925 X86CPURegister32 (Enum)
13927 A X86 32-bit register
13929 Values:
13931 "EAX"
13933 Not documented
13934 "EBX"
13936 Not documented
13937 "ECX"
13939 Not documented
13940 "EDX"
13942 Not documented
13943 "ESP"
13945 Not documented
13946 "EBP"
13948 Not documented
13949 "ESI"
13951 Not documented
13952 "EDI"
13954 Not documented
13955 Since: 1.5
13957 X86CPUFeatureWordInfo (Object)
13959 Information about a X86 CPU feature word
13961 Members:
13963 "cpuid-input-eax: int"
13965 Input EAX value for CPUID instruction for that feature word
13966 "cpuid-input-ecx: int" (optional)
13968 Input ECX value for CPUID instruction for that feature word
13969 "cpuid-register: X86CPURegister32"
13971 Output register containing the feature bits
13972 "features: int"
13974 value of output register, containing the feature bits
13975 Since: 1.5
13977 DummyForceArrays (Object)
13979 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList
13981 internally
13982 Members:
13984 "unused: array of X86CPUFeatureWordInfo"
13986 Not documented
13987 Since: 2.5
13989 NumaCpuOptions (Object)
13991 Option "-numa cpu" overrides default cpu to node mapping. It accepts
13993 the same set of cpu properties as returned by
13994 query-hotpluggable-cpus[].props, where node-id could be used to
13995 override default node mapping.
13996 Members:
13998 The members of "CpuInstanceProperties"
14000 Since: 2.10
14002 HostMemPolicy (Enum)
14004 Host memory policy types
14006 Values:
14008 "default"
14010 restore default policy, remove any nondefault policy
14011 "preferred"
14013 set the preferred host nodes for allocation
14014 "bind"
14016 a strict policy that restricts memory allocation to the host nodes
14017 specified
14018 "interleave"
14020 memory allocations are interleaved across the set of host nodes
14021 specified
14022 Since: 2.1
14024 Memdev (Object)
14026 Information about memory backend
14028 Members:
14030 "id: string" (optional)
14032 backend's ID if backend has 'id' property (since 2.9)
14033 "size: int"
14035 memory backend size
14036 "merge: boolean"
14038 enables or disables memory merge support
14039 "dump: boolean"
14041 includes memory backend's memory in a core dump or not
14042 "prealloc: boolean"
14044 enables or disables memory preallocation
14045 "host-nodes: array of int"
14047 host nodes for its memory policy
14048 "policy: HostMemPolicy"
14050 memory policy of memory backend
14051 Since: 2.1
14053 query-memdev (Command) Returns information for all memory backends.
14055 Returns: a list of "Memdev".
14057 Since: 2.1
14059 Example:
14061 -> { "execute": "query-memdev" }
14063 <- { "return": [
14064 {
14065 "id": "mem1",
14066 "size": 536870912,
14067 "merge": false,
14068 "dump": true,
14069 "prealloc": false,
14070 "host-nodes": [0, 1],
14071 "policy": "bind"
14072 },
14073 {
14074 "size": 536870912,
14075 "merge": false,
14076 "dump": true,
14077 "prealloc": true,
14078 "host-nodes": [2, 3],
14079 "policy": "preferred"
14080 }
14081 ]
14082 }
14083 CpuInstanceProperties (Object)
14085 List of properties to be used for hotplugging a CPU instance, it should
14087 be passed by management with device_add command when a CPU is being
14088 hotplugged.
14089 Members:
14091 "node-id: int" (optional)
14093 NUMA node ID the CPU belongs to
14094 "socket-id: int" (optional)
14096 socket number within node/board the CPU belongs to
14097 "die-id: int" (optional)
14099 die number within node/board the CPU belongs to (Since 4.1)
14100 "core-id: int" (optional)
14102 core number within die the CPU belongs to# "thread-id": thread
14103 number within core the CPU belongs to
14104 "thread-id: int" (optional)
14106 Not documented
14107 Note: currently there are 5 properties that could be present but
14109 management should be prepared to pass through other properties with
14110 device_add command to allow for future interface extension. This also
14111 requires the filed names to be kept in sync with the properties passed
14112 to -device/device_add.
14113 Since: 2.7
14115 HotpluggableCPU (Object)
14117 Members:
14119 "type: string"
14121 CPU object type for usage with device_add command
14122 "props: CpuInstanceProperties"
14124 list of properties to be used for hotplugging CPU
14125 "vcpus-count: int"
14127 number of logical VCPU threads "HotpluggableCPU" provides
14128 "qom-path: string" (optional)
14130 link to existing CPU object if CPU is present or omitted if CPU is
14131 not present.
14132 Since: 2.7
14134 query-hotpluggable-cpus (Command)
14136 TODO: Better documentation; currently there is none.
14138 Returns: a list of HotpluggableCPU objects.
14140 Since: 2.7
14142 Example:
14144 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
14146 -> { "execute": "query-hotpluggable-cpus" }
14148 <- {"return": [
14149 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
14150 "vcpus-count": 1 },
14151 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
14152 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
14153 ]}'
14154 For pc machine type started with -smp 1,maxcpus=2:
14156 -> { "execute": "query-hotpluggable-cpus" }
14158 <- {"return": [
14159 {
14160 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
14161 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
14162 },
14163 {
14164 "qom-path": "/machine/unattached/device[0]",
14165 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
14166 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
14167 }
14168 ]}
14169 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
14171 (Since: 2.11):
14172 -> { "execute": "query-hotpluggable-cpus" }
14174 <- {"return": [
14175 {
14176 "type": "qemu-s390x-cpu", "vcpus-count": 1,
14177 "props": { "core-id": 1 }
14178 },
14179 {
14180 "qom-path": "/machine/unattached/device[0]",
14181 "type": "qemu-s390x-cpu", "vcpus-count": 1,
14182 "props": { "core-id": 0 }
14183 }
14184 ]}
14185 set-numa-node (Command) Runtime equivalent of '-numa' CLI option,
14187 available at preconfigure stage to configure numa mapping before
14188 initializing machine.
14189 Since 3.0
14191 Arguments: the members of "NumaOptions"
14193 CpuModelInfo (Object)
14195 Virtual CPU model.
14197 A CPU model consists of the name of a CPU definition, to which delta
14199 changes are applied (e.g. features added/removed). Most magic values
14200 that an architecture might require should be hidden behind the name.
14201 However, if required, architectures can expose relevant properties.
14202 Members:
14204 "name: string"
14206 the name of the CPU definition the model is based on
14207 "props: value" (optional)
14209 a dictionary of QOM properties to be applied
14210 Since: 2.8.0
14212 CpuModelExpansionType (Enum)
14214 An enumeration of CPU model expansion types.
14216 Values:
14218 "static"
14220 Expand to a static CPU model, a combination of a static base model
14221 name and property delta changes. As the static base model will
14222 never change, the expanded CPU model will be the same, independent
14223 of QEMU version, machine type, machine options, and accelerator
14224 options. Therefore, the resulting model can be used by tooling
14225 without having to specify a compatibility machine - e.g. when
14226 displaying the "host" model. The "static" CPU models are migration-
14227 safe.
14228 "full"
14230 Expand all properties. The produced model is not guaranteed to be
14231 migration-safe, but allows tooling to get an insight and work with
14232 model details.
14233 Note: When a non-migration-safe CPU model is expanded in static mode,
14235 some features enabled by the CPU model may be omitted, because they
14236 can't be implemented by a static CPU model definition (e.g. cache info
14237 passthrough and PMU passthrough in x86). If you need an accurate
14238 representation of the features enabled by a non-migration-safe CPU
14239 model, use "full". If you need a static representation that will keep
14240 ABI compatibility even when changing QEMU version or machine-type, use
14241 "static" (but keep in mind that some features may be omitted).
14242 Since: 2.8.0
14244 CpuModelCompareResult (Enum)
14246 An enumeration of CPU model comparison results. The result is usually
14248 calculated using e.g. CPU features or CPU generations.
14249 Values:
14251 "incompatible"
14253 If model A is incompatible to model B, model A is not guaranteed to
14254 run where model B runs and the other way around.
14255 "identical"
14257 If model A is identical to model B, model A is guaranteed to run
14258 where model B runs and the other way around.
14259 "superset"
14261 If model A is a superset of model B, model B is guaranteed to run
14262 where model A runs. There are no guarantees about the other way.
14263 "subset"
14265 If model A is a subset of model B, model A is guaranteed to run
14266 where model B runs. There are no guarantees about the other way.
14267 Since: 2.8.0
14269 CpuModelBaselineInfo (Object)
14271 The result of a CPU model baseline.
14273 Members:
14275 "model: CpuModelInfo"
14277 the baselined CpuModelInfo.
14278 Since: 2.8.0
14280 If: "defined(TARGET_S390X)"
14282 CpuModelCompareInfo (Object)
14284 The result of a CPU model comparison.
14286 Members:
14288 "result: CpuModelCompareResult"
14290 The result of the compare operation.
14291 "responsible-properties: array of string"
14293 List of properties that led to the comparison result not being
14294 identical.
14295 "responsible-properties" is a list of QOM property names that led to
14297 both CPUs not being detected as identical. For identical models, this
14298 list is empty. If a QOM property is read-only, that means there's no
14299 known way to make the CPU models identical. If the special property
14300 name "type" is included, the models are by definition not identical and
14301 cannot be made identical.
14302 Since: 2.8.0
14304 If: "defined(TARGET_S390X)"
14306 query-cpu-model-comparison (Command) Compares two CPU models,
14308 returning how they compare in a specific configuration. The results
14309 indicates how both models compare regarding runnability. This result
14310 can be used by tooling to make decisions if a certain CPU model will
14311 run in a certain configuration or if a compatible CPU model has to be
14312 created by baselining.
14313 Usually, a CPU model is compared against the maximum possible CPU model
14315 of a certain configuration (e.g. the "host" model for KVM). If that CPU
14316 model is identical or a subset, it will run in that configuration.
14317 The result returned by this command may be affected by:
14319 · QEMU version: CPU models may look different depending on the QEMU
14321 version. (Except for CPU models reported as "static" in query-cpu-
14322 definitions.)
14323 · machine-type: CPU model may look different depending on the
14325 machine-type. (Except for CPU models reported as "static" in
14326 query-cpu-definitions.)
14327 · machine options (including accelerator): in some architectures, CPU
14329 models may look different depending on machine and accelerator
14330 options. (Except for CPU models reported as "static" in query-cpu-
14331 definitions.)
14332 · "-cpu" arguments and global properties: arguments to the -cpu
14334 option and global properties may affect expansion of CPU models.
14335 Using query-cpu-model-expansion while using these is not advised.
14336 Some architectures may not support comparing CPU models. s390x supports
14338 comparing CPU models.
14339 Arguments:
14341 "modela: CpuModelInfo"
14343 Not documented
14344 "modelb: CpuModelInfo"
14346 Not documented
14347 Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU
14349 models is not supported, if a model cannot be used, if a model contains
14350 an unknown cpu definition name, unknown properties or properties with
14351 wrong types.
14352 Note: this command isn't specific to s390x, but is only implemented on
14354 this architecture currently.
14355 Since: 2.8.0
14357 If: "defined(TARGET_S390X)"
14359 query-cpu-model-baseline (Command) Baseline two CPU models, creating a
14361 compatible third model. The created model will always be a static,
14362 migration-safe CPU model (see "static" CPU model expansion for
14363 details).
14364 This interface can be used by tooling to create a compatible CPU model
14366 out two CPU models. The created CPU model will be identical to or a
14367 subset of both CPU models when comparing them. Therefore, the created
14368 CPU model is guaranteed to run where the given CPU models run.
14369 The result returned by this command may be affected by:
14371 · QEMU version: CPU models may look different depending on the QEMU
14373 version. (Except for CPU models reported as "static" in query-cpu-
14374 definitions.)
14375 · machine-type: CPU model may look different depending on the
14377 machine-type. (Except for CPU models reported as "static" in
14378 query-cpu-definitions.)
14379 · machine options (including accelerator): in some architectures, CPU
14381 models may look different depending on machine and accelerator
14382 options. (Except for CPU models reported as "static" in query-cpu-
14383 definitions.)
14384 · "-cpu" arguments and global properties: arguments to the -cpu
14386 option and global properties may affect expansion of CPU models.
14387 Using query-cpu-model-expansion while using these is not advised.
14388 Some architectures may not support baselining CPU models. s390x
14390 supports baselining CPU models.
14391 Arguments:
14393 "modela: CpuModelInfo"
14395 Not documented
14396 "modelb: CpuModelInfo"
14398 Not documented
14399 Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU
14401 models is not supported, if a model cannot be used, if a model contains
14402 an unknown cpu definition name, unknown properties or properties with
14403 wrong types.
14404 Note: this command isn't specific to s390x, but is only implemented on
14406 this architecture currently.
14407 Since: 2.8.0
14409 If: "defined(TARGET_S390X)"
14411 CpuModelExpansionInfo (Object)
14413 The result of a cpu model expansion.
14415 Members:
14417 "model: CpuModelInfo"
14419 the expanded CpuModelInfo.
14420 Since: 2.8.0
14422 If: "defined(TARGET_S390X) || defined(TARGET_I386) ||
14424 defined(TARGET_ARM)"
14425 query-cpu-model-expansion (Command) Expands a given CPU model (or a
14427 combination of CPU model + additional options) to different
14428 granularities, allowing tooling to get an understanding what a specific
14429 CPU model looks like in QEMU under a certain configuration.
14430 This interface can be used to query the "host" CPU model.
14432 The data returned by this command may be affected by:
14434 · QEMU version: CPU models may look different depending on the QEMU
14436 version. (Except for CPU models reported as "static" in query-cpu-
14437 definitions.)
14438 · machine-type: CPU model may look different depending on the
14440 machine-type. (Except for CPU models reported as "static" in
14441 query-cpu-definitions.)
14442 · machine options (including accelerator): in some architectures, CPU
14444 models may look different depending on machine and accelerator
14445 options. (Except for CPU models reported as "static" in query-cpu-
14446 definitions.)
14447 · "-cpu" arguments and global properties: arguments to the -cpu
14449 option and global properties may affect expansion of CPU models.
14450 Using query-cpu-model-expansion while using these is not advised.
14451 Some architectures may not support all expansion types. s390x supports
14453 "full" and "static". Arm only supports "full".
14454 Arguments:
14456 "type: CpuModelExpansionType"
14458 Not documented
14459 "model: CpuModelInfo"
14461 Not documented
14462 Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU
14464 models is not supported, if the model cannot be expanded, if the model
14465 contains an unknown CPU definition name, unknown properties or
14466 properties with a wrong type. Also returns an error if an expansion
14467 type is not supported.
14468 Since: 2.8.0
14470 If: "defined(TARGET_S390X) || defined(TARGET_I386) ||
14472 defined(TARGET_ARM)"
14473 CpuDefinitionInfo (Object)
14475 Virtual CPU definition.
14477 Members:
14479 "name: string"
14481 the name of the CPU definition
14482 "migration-safe: boolean" (optional)
14484 whether a CPU definition can be safely used for migration in
14485 combination with a QEMU compatibility machine when migrating
14486 between different QEMU versions and between hosts with different
14487 sets of (hardware or software) capabilities. If not provided,
14488 information is not available and callers should not assume the CPU
14489 definition to be migration-safe. (since 2.8)
14490 "static: boolean"
14492 whether a CPU definition is static and will not change depending on
14493 QEMU version, machine type, machine options and accelerator
14494 options. A static model is always migration-safe. (since 2.8)
14495 "unavailable-features: array of string" (optional)
14497 List of properties that prevent the CPU model from running in the
14498 current host. (since 2.8)
14499 "typename: string"
14501 Type name that can be used as argument to "device-list-properties",
14502 to introspect properties configurable using -cpu or -global.
14503 (since 2.9)
14504 "alias-of: string" (optional)
14506 Name of CPU model this model is an alias for. The target of the
14507 CPU model alias may change depending on the machine type.
14508 Management software is supposed to translate CPU model aliases in
14509 the VM configuration, because aliases may stop being migration-safe
14510 in the future (since 4.1)
14511 "unavailable-features" is a list of QOM property names that represent
14513 CPU model attributes that prevent the CPU from running. If the QOM
14514 property is read-only, that means there's no known way to make the CPU
14515 model run in the current host. Implementations that choose not to
14516 provide specific information return the property name "type". If the
14517 property is read-write, it means that it MAY be possible to run the CPU
14518 model in the current host if that property is changed. Management
14519 software can use it as hints to suggest or choose an alternative for
14520 the user, or just to generate meaningful error messages explaining why
14521 the CPU model can't be used. If "unavailable-features" is an empty
14522 list, the CPU model is runnable using the current host and machine-
14523 type. If "unavailable-features" is not present, runnability
14524 information for the CPU is not available.
14525 Since: 1.2.0
14527 If: "defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386)
14529 || defined(TARGET_S390X) || defined(TARGET_MIPS)"
14530 query-cpu-definitions (Command) Return a list of supported virtual CPU
14532 definitions
14533 Returns: a list of CpuDefInfo
14535 Since: 1.2.0
14537 If: "defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386)
14539 || defined(TARGET_S390X) || defined(TARGET_MIPS)"
14540 Miscellanea
14542 qmp_capabilities (Command) Enable QMP capabilities.
14543 Arguments:
14545 Arguments:
14547 "enable: array of QMPCapability" (optional)
14549 An optional list of QMPCapability values to enable. The client
14550 must not enable any capability that is not mentioned in the QMP
14551 greeting message. If the field is not provided, it means no QMP
14552 capabilities will be enabled. (since 2.12)
14553 Example:
14555 -> { "execute": "qmp_capabilities",
14557 "arguments": { "enable": [ "oob" ] } }
14558 <- { "return": {} }
14559 Notes: This command is valid exactly when first connecting: it must be
14561 issued before any other command will be accepted, and will fail once
14562 the monitor is accepting other commands. (see qemu
14563 docs/interop/qmp-spec.txt)
14564 The QMP client needs to explicitly enable QMP capabilities, otherwise
14566 all the QMP capabilities will be turned off by default.
14567 Since: 0.13
14569 QMPCapability (Enum)
14571 Enumeration of capabilities to be advertised during initial client
14573 connection, used for agreeing on particular QMP extension behaviors.
14574 Values:
14576 "oob"
14578 QMP ability to support out-of-band requests. (Please refer to
14579 qmp-spec.txt for more information on OOB)
14580 Since: 2.12
14582 VersionTriple (Object)
14584 A three-part version number.
14586 Members:
14588 "major: int"
14590 The major version number.
14591 "minor: int"
14593 The minor version number.
14594 "micro: int"
14596 The micro version number.
14597 Since: 2.4
14599 VersionInfo (Object)
14601 A description of QEMU's version.
14603 Members:
14605 "qemu: VersionTriple"
14607 The version of QEMU. By current convention, a micro version of 50
14608 signifies a development branch. A micro version greater than or
14609 equal to 90 signifies a release candidate for the next minor
14610 version. A micro version of less than 50 signifies a stable
14611 release.
14612 "package: string"
14614 QEMU will always set this field to an empty string. Downstream
14615 versions of QEMU should set this to a non-empty string. The exact
14616 format depends on the downstream however it highly recommended that
14617 a unique name is used.
14618 Since: 0.14.0
14620 query-version (Command) Returns the current version of QEMU.
14622 Returns: A "VersionInfo" object describing the current version of QEMU.
14624 Since: 0.14.0
14626 Example:
14628 -> { "execute": "query-version" }
14630 <- {
14631 "return":{
14632 "qemu":{
14633 "major":0,
14634 "minor":11,
14635 "micro":5
14636 },
14637 "package":""
14638 }
14639 }
14640 CommandInfo (Object)
14642 Information about a QMP command
14644 Members:
14646 "name: string"
14648 The command name
14649 Since: 0.14.0
14651 query-commands (Command) Return a list of supported QMP commands by
14653 this server
14654 Returns: A list of "CommandInfo" for all supported commands
14656 Since: 0.14.0
14658 Example:
14660 -> { "execute": "query-commands" }
14662 <- {
14663 "return":[
14664 {
14665 "name":"query-balloon"
14666 },
14667 {
14668 "name":"system_powerdown"
14669 }
14670 ]
14671 }
14672 Note: This example has been shortened as the real response is too long.
14674 LostTickPolicy (Enum)
14676 Policy for handling lost ticks in timer devices.
14678 Values:
14680 "discard"
14682 throw away the missed tick(s) and continue with future injection
14683 normally. Guest time may be delayed, unless the OS has explicit
14684 handling of lost ticks
14685 "delay"
14687 continue to deliver ticks at the normal rate. Guest time will be
14688 delayed due to the late tick
14689 "slew"
14691 deliver ticks at a higher rate to catch up with the missed tick.
14692 The guest time should not be delayed once catchup is complete.
14693 Since: 2.0
14695 add_client (Command) Allow client connections for VNC, Spice and
14697 socket based character devices to be passed in to QEMU via SCM_RIGHTS.
14698 Arguments:
14700 "protocol: string"
14702 protocol name. Valid names are "vnc", "spice" or the name of a
14703 character device (eg. from -chardev id=XXXX)
14704 "fdname: string"
14706 file descriptor name previously passed via 'getfd' command
14707 "skipauth: boolean" (optional)
14709 whether to skip authentication. Only applies to "vnc" and "spice"
14710 protocols
14711 "tls: boolean" (optional)
14713 whether to perform TLS. Only applies to the "spice" protocol
14714 Returns: nothing on success.
14716 Since: 0.14.0
14718 Example:
14720 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
14722 "fdname": "myclient" } }
14723 <- { "return": {} }
14724 NameInfo (Object)
14726 Guest name information.
14728 Members:
14730 "name: string" (optional)
14732 The name of the guest
14733 Since: 0.14.0
14735 query-name (Command) Return the name information of a guest.
14737 Returns: "NameInfo" of the guest
14739 Since: 0.14.0
14741 Example:
14743 -> { "execute": "query-name" }
14745 <- { "return": { "name": "qemu-name" } }
14746 KvmInfo (Object)
14748 Information about support for KVM acceleration
14750 Members:
14752 "enabled: boolean"
14754 true if KVM acceleration is active
14755 "present: boolean"
14757 true if KVM acceleration is built into this executable
14758 Since: 0.14.0
14760 query-kvm (Command) Returns information about KVM acceleration
14762 Returns: "KvmInfo"
14764 Since: 0.14.0
14766 Example:
14768 -> { "execute": "query-kvm" }
14770 <- { "return": { "enabled": true, "present": true } }
14771 UuidInfo (Object)
14773 Guest UUID information (Universally Unique Identifier).
14775 Members:
14777 "UUID: string"
14779 the UUID of the guest
14780 Since: 0.14.0
14782 Notes: If no UUID was specified for the guest, a null UUID is returned.
14784 query-uuid (Command) Query the guest UUID information.
14786 Returns: The "UuidInfo" for the guest
14788 Since: 0.14.0
14790 Example:
14792 -> { "execute": "query-uuid" }
14794 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
14795 EventInfo (Object)
14797 Information about a QMP event
14799 Members:
14801 "name: string"
14803 The event name
14804 Since: 1.2.0
14806 query-events (Command) Return information on QMP events.
14808 Returns: A list of "EventInfo".
14810 Since: 1.2.0
14812 Note: This command is deprecated, because its output doesn't reflect
14814 compile-time configuration. Use query-qmp-schema instead.
14815 Example:
14817 -> { "execute": "query-events" }
14819 <- {
14820 "return": [
14821 {
14822 "name":"SHUTDOWN"
14823 },
14824 {
14825 "name":"RESET"
14826 }
14827 ]
14828 }
14829 Note: This example has been shortened as the real response is too long.
14831 IOThreadInfo (Object)
14833 Information about an iothread
14835 Members:
14837 "id: string"
14839 the identifier of the iothread
14840 "thread-id: int"
14842 ID of the underlying host thread
14843 "poll-max-ns: int"
14845 maximum polling time in ns, 0 means polling is disabled (since 2.9)
14846 "poll-grow: int"
14848 how many ns will be added to polling time, 0 means that it's not
14849 configured (since 2.9)
14850 "poll-shrink: int"
14852 how many ns will be removed from polling time, 0 means that it's
14853 not configured (since 2.9)
14854 Since: 2.0
14856 query-iothreads (Command) Returns a list of information about each
14858 iothread.
14859 Note: this list excludes the QEMU main loop thread, which is not
14861 declared using the -object iothread command-line option. It is always
14862 the main thread of the process.
14863 Returns: a list of "IOThreadInfo" for each iothread
14865 Since: 2.0
14867 Example:
14869 -> { "execute": "query-iothreads" }
14871 <- { "return": [
14872 {
14873 "id":"iothread0",
14874 "thread-id":3134
14875 },
14876 {
14877 "id":"iothread1",
14878 "thread-id":3135
14879 }
14880 ]
14881 }
14882 BalloonInfo (Object)
14884 Information about the guest balloon device.
14886 Members:
14888 "actual: int"
14890 the number of bytes the balloon currently contains
14891 Since: 0.14.0
14893 query-balloon (Command) Return information about the balloon device.
14895 Returns: "BalloonInfo" on success
14897 If the balloon driver is enabled but not functional because the KVM
14899 kernel module cannot support it, KvmMissingCap
14900 If no balloon device is present, DeviceNotActive
14902 Since: 0.14.0
14904 Example:
14906 -> { "execute": "query-balloon" }
14908 <- { "return": {
14909 "actual": 1073741824,
14910 }
14911 }
14912 BALLOON_CHANGE (Event) Emitted when the guest changes the actual
14914 BALLOON level. This value is equivalent to the "actual" field return by
14915 the 'query-balloon' command
14916 Arguments:
14918 "actual: int"
14920 actual level of the guest memory balloon in bytes
14921 Note: this event is rate-limited.
14923 Since: 1.2
14925 Example:
14927 <- { "event": "BALLOON_CHANGE",
14929 "data": { "actual": 944766976 },
14930 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
14931 PciMemoryRange (Object)
14933 A PCI device memory region
14935 Members:
14937 "base: int"
14939 the starting address (guest physical)
14940 "limit: int"
14942 the ending address (guest physical)
14943 Since: 0.14.0
14945 PciMemoryRegion (Object)
14947 Information about a PCI device I/O region.
14949 Members:
14951 "bar: int"
14953 the index of the Base Address Register for this region
14954 "type: string"
14956 'io' if the region is a PIO region 'memory' if the region is a MMIO
14957 region
14958 "size: int"
14960 memory size
14961 "prefetch: boolean" (optional)
14963 if "type" is 'memory', true if the memory is prefetchable
14964 "mem_type_64: boolean" (optional)
14966 if "type" is 'memory', true if the BAR is 64-bit
14967 "address: int"
14969 Not documented
14970 Since: 0.14.0
14972 PciBusInfo (Object)
14974 Information about a bus of a PCI Bridge device
14976 Members:
14978 "number: int"
14980 primary bus interface number. This should be the number of the bus
14981 the device resides on.
14982 "secondary: int"
14984 secondary bus interface number. This is the number of the main bus
14985 for the bridge
14986 "subordinate: int"
14988 This is the highest number bus that resides below the bridge.
14989 "io_range: PciMemoryRange"
14991 The PIO range for all devices on this bridge
14992 "memory_range: PciMemoryRange"
14994 The MMIO range for all devices on this bridge
14995 "prefetchable_range: PciMemoryRange"
14997 The range of prefetchable MMIO for all devices on this bridge
14998 Since: 2.4
15000 PciBridgeInfo (Object)
15002 Information about a PCI Bridge device
15004 Members:
15006 "bus: PciBusInfo"
15008 information about the bus the device resides on
15009 "devices: array of PciDeviceInfo" (optional)
15011 a list of "PciDeviceInfo" for each device on this bridge
15012 Since: 0.14.0
15014 PciDeviceClass (Object)
15016 Information about the Class of a PCI device
15018 Members:
15020 "desc: string" (optional)
15022 a string description of the device's class
15023 "class: int"
15025 the class code of the device
15026 Since: 2.4
15028 PciDeviceId (Object)
15030 Information about the Id of a PCI device
15032 Members:
15034 "device: int"
15036 the PCI device id
15037 "vendor: int"
15039 the PCI vendor id
15040 "subsystem: int" (optional)
15042 the PCI subsystem id (since 3.1)
15043 "subsystem-vendor: int" (optional)
15045 the PCI subsystem vendor id (since 3.1)
15046 Since: 2.4
15048 PciDeviceInfo (Object)
15050 Information about a PCI device
15052 Members:
15054 "bus: int"
15056 the bus number of the device
15057 "slot: int"
15059 the slot the device is located in
15060 "function: int"
15062 the function of the slot used by the device
15063 "class_info: PciDeviceClass"
15065 the class of the device
15066 "id: PciDeviceId"
15068 the PCI device id
15069 "irq: int" (optional)
15071 if an IRQ is assigned to the device, the IRQ number
15072 "qdev_id: string"
15074 the device name of the PCI device
15075 "pci_bridge: PciBridgeInfo" (optional)
15077 if the device is a PCI bridge, the bridge information
15078 "regions: array of PciMemoryRegion"
15080 a list of the PCI I/O regions associated with the device
15081 Notes: the contents of "class_info".desc are not stable and should only
15083 be treated as informational.
15084 Since: 0.14.0
15086 PciInfo (Object)
15088 Information about a PCI bus
15090 Members:
15092 "bus: int"
15094 the bus index
15095 "devices: array of PciDeviceInfo"
15097 a list of devices on this bus
15098 Since: 0.14.0
15100 query-pci (Command) Return information about the PCI bus topology of
15102 the guest.
15103 Returns: a list of "PciInfo" for each PCI bus. Each bus is represented
15105 by a json-object, which has a key with a json-array of all PCI devices
15106 attached to it. Each device is represented by a json-object.
15107 Since: 0.14.0
15109 Example:
15111 -> { "execute": "query-pci" }
15113 <- { "return": [
15114 {
15115 "bus": 0,
15116 "devices": [
15117 {
15118 "bus": 0,
15119 "qdev_id": "",
15120 "slot": 0,
15121 "class_info": {
15122 "class": 1536,
15123 "desc": "Host bridge"
15124 },
15125 "id": {
15126 "device": 32902,
15127 "vendor": 4663
15128 },
15129 "function": 0,
15130 "regions": [
15131 ]
15132 },
15133 {
15134 "bus": 0,
15135 "qdev_id": "",
15136 "slot": 1,
15137 "class_info": {
15138 "class": 1537,
15139 "desc": "ISA bridge"
15140 },
15141 "id": {
15142 "device": 32902,
15143 "vendor": 28672
15144 },
15145 "function": 0,
15146 "regions": [
15147 ]
15148 },
15149 {
15150 "bus": 0,
15151 "qdev_id": "",
15152 "slot": 1,
15153 "class_info": {
15154 "class": 257,
15155 "desc": "IDE controller"
15156 },
15157 "id": {
15158 "device": 32902,
15159 "vendor": 28688
15160 },
15161 "function": 1,
15162 "regions": [
15163 {
15164 "bar": 4,
15165 "size": 16,
15166 "address": 49152,
15167 "type": "io"
15168 }
15169 ]
15170 },
15171 {
15172 "bus": 0,
15173 "qdev_id": "",
15174 "slot": 2,
15175 "class_info": {
15176 "class": 768,
15177 "desc": "VGA controller"
15178 },
15179 "id": {
15180 "device": 4115,
15181 "vendor": 184
15182 },
15183 "function": 0,
15184 "regions": [
15185 {
15186 "prefetch": true,
15187 "mem_type_64": false,
15188 "bar": 0,
15189 "size": 33554432,
15190 "address": 4026531840,
15191 "type": "memory"
15192 },
15193 {
15194 "prefetch": false,
15195 "mem_type_64": false,
15196 "bar": 1,
15197 "size": 4096,
15198 "address": 4060086272,
15199 "type": "memory"
15200 },
15201 {
15202 "prefetch": false,
15203 "mem_type_64": false,
15204 "bar": 6,
15205 "size": 65536,
15206 "address": -1,
15207 "type": "memory"
15208 }
15209 ]
15210 },
15211 {
15212 "bus": 0,
15213 "qdev_id": "",
15214 "irq": 11,
15215 "slot": 4,
15216 "class_info": {
15217 "class": 1280,
15218 "desc": "RAM controller"
15219 },
15220 "id": {
15221 "device": 6900,
15222 "vendor": 4098
15223 },
15224 "function": 0,
15225 "regions": [
15226 {
15227 "bar": 0,
15228 "size": 32,
15229 "address": 49280,
15230 "type": "io"
15231 }
15232 ]
15233 }
15234 ]
15235 }
15236 ]
15237 }
15238 Note: This example has been shortened as the real response is too long.
15240 quit (Command) This command will cause the QEMU process to exit
15242 gracefully. While every attempt is made to send the QMP response
15243 before terminating, this is not guaranteed. When using this interface,
15244 a premature EOF would not be unexpected.
15245 Since: 0.14.0
15247 Example:
15249 -> { "execute": "quit" }
15251 <- { "return": {} }
15252 stop (Command) Stop all guest VCPU execution.
15254 Since: 0.14.0
15256 Notes: This function will succeed even if the guest is already in the
15258 stopped state. In "inmigrate" state, it will ensure that the guest
15259 remains paused once migration finishes, as if the -S option was passed
15260 on the command line.
15261 Example:
15263 -> { "execute": "stop" }
15265 <- { "return": {} }
15266 system_reset (Command) Performs a hard reset of a guest.
15268 Since: 0.14.0
15270 Example:
15272 -> { "execute": "system_reset" }
15274 <- { "return": {} }
15275 system_powerdown (Command) Requests that a guest perform a powerdown
15277 operation.
15278 Since: 0.14.0
15280 Notes: A guest may or may not respond to this command. This command
15282 returning does not indicate that a guest has accepted the request or
15283 that it has shut down. Many guests will respond to this command by
15284 prompting the user in some way.
15285 Example:
15287 -> { "execute": "system_powerdown" }
15289 <- { "return": {} }
15290 memsave (Command) Save a portion of guest memory to a file.
15292 Arguments:
15294 "val: int"
15296 the virtual address of the guest to start from
15297 "size: int"
15299 the size of memory region to save
15300 "filename: string"
15302 the file to save the memory to as binary data
15303 "cpu-index: int" (optional)
15305 the index of the virtual CPU to use for translating the virtual
15306 address (defaults to CPU 0)
15307 Returns: Nothing on success
15309 Since: 0.14.0
15311 Notes: Errors were not reliably returned until 1.1
15313 Example:
15315 -> { "execute": "memsave",
15317 "arguments": { "val": 10,
15318 "size": 100,
15319 "filename": "/tmp/virtual-mem-dump" } }
15320 <- { "return": {} }
15321 pmemsave (Command) Save a portion of guest physical memory to a file.
15323 Arguments:
15325 "val: int"
15327 the physical address of the guest to start from
15328 "size: int"
15330 the size of memory region to save
15331 "filename: string"
15333 the file to save the memory to as binary data
15334 Returns: Nothing on success
15336 Since: 0.14.0
15338 Notes: Errors were not reliably returned until 1.1
15340 Example:
15342 -> { "execute": "pmemsave",
15344 "arguments": { "val": 10,
15345 "size": 100,
15346 "filename": "/tmp/physical-mem-dump" } }
15347 <- { "return": {} }
15348 cont (Command) Resume guest VCPU execution.
15350 Since: 0.14.0
15352 Returns: If successful, nothing
15354 Notes: This command will succeed if the guest is currently running. It
15356 will also succeed if the guest is in the "inmigrate" state; in this
15357 case, the effect of the command is to make sure the guest starts once
15358 migration finishes, removing the effect of the -S command line option
15359 if it was passed.
15360 Example:
15362 -> { "execute": "cont" }
15364 <- { "return": {} }
15365 x-exit-preconfig (Command) Exit from "preconfig" state
15367 This command makes QEMU exit the preconfig state and proceed with VM
15369 initialization using configuration data provided on the command line
15370 and via the QMP monitor during the preconfig state. The command is only
15371 available during the preconfig state (i.e. when the --preconfig command
15372 line option was in use).
15373 Since 3.0
15375 Returns: nothing
15377 Example:
15379 -> { "execute": "x-exit-preconfig" }
15381 <- { "return": {} }
15382 system_wakeup (Command) Wake up guest from suspend. If the guest has
15384 wake-up from suspend support enabled (wakeup-suspend-support flag from
15385 query-current-machine), wake-up guest from suspend if the guest is in
15386 SUSPENDED state. Return an error otherwise.
15387 Since: 1.1
15389 Returns: nothing.
15391 Note: prior to 4.0, this command does nothing in case the guest isn't
15393 suspended.
15394 Example:
15396 -> { "execute": "system_wakeup" }
15398 <- { "return": {} }
15399 inject-nmi (Command) Injects a Non-Maskable Interrupt into the default
15401 CPU (x86/s390) or all CPUs (ppc64). The command fails when the guest
15402 doesn't support injecting.
15403 Returns: If successful, nothing
15405 Since: 0.14.0
15407 Note: prior to 2.1, this command was only supported for x86 and s390
15409 VMs
15410 Example:
15412 -> { "execute": "inject-nmi" }
15414 <- { "return": {} }
15415 balloon (Command) Request the balloon driver to change its balloon
15417 size.
15418 Arguments:
15420 "value: int"
15422 the target size of the balloon in bytes
15423 Returns: Nothing on success If the balloon driver is enabled but not
15425 functional because the KVM kernel module cannot support it,
15426 KvmMissingCap If no balloon device is present, DeviceNotActive
15427 Notes: This command just issues a request to the guest. When it
15429 returns, the balloon size may not have changed. A guest can change the
15430 balloon size independent of this command.
15431 Since: 0.14.0
15433 Example:
15435 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
15437 <- { "return": {} }
15438 human-monitor-command (Command) Execute a command on the human monitor
15440 and return the output.
15441 Arguments:
15443 "command-line: string"
15445 the command to execute in the human monitor
15446 "cpu-index: int" (optional)
15448 The CPU to use for commands that require an implicit CPU
15449 Features:
15451 "savevm-monitor-nodes"
15453 If present, HMP command savevm only snapshots monitor-owned nodes
15454 if they have no parents. This allows the use of 'savevm' with
15455 -blockdev. (since 4.2)
15456 Returns: the output of the command as a string
15458 Since: 0.14.0
15460 Notes: This command only exists as a stop-gap. Its use is highly
15462 discouraged. The semantics of this command are not guaranteed: this
15463 means that command names, arguments and responses can change or be
15464 removed at ANY time. Applications that rely on long term stability
15465 guarantees should NOT use this command.
15466 Known limitations:
15468 · This command is stateless, this means that commands that depend on
15470 state information (such as getfd) might not work
15471 · Commands that prompt the user for data don't currently work
15473 Example:
15475 -> { "execute": "human-monitor-command",
15477 "arguments": { "command-line": "info kvm" } }
15478 <- { "return": "kvm support: enabled\r\n" }
15479 change (Command) This command is multiple commands multiplexed
15481 together.
15482 Arguments:
15484 "device: string"
15486 This is normally the name of a block device but it may also be
15487 'vnc'. when it's 'vnc', then sub command depends on "target"
15488 "target: string"
15490 If "device" is a block device, then this is the new filename. If
15491 "device" is 'vnc', then if the value 'password' selects the vnc
15492 change password command. Otherwise, this specifies a new server
15493 URI address to listen to for VNC connections.
15494 "arg: string" (optional)
15496 If "device" is a block device, then this is an optional format to
15497 open the device with. If "device" is 'vnc' and "target" is
15498 'password', this is the new VNC password to set. See change-vnc-
15499 password for additional notes.
15500 Returns: Nothing on success. If "device" is not a valid block device,
15502 DeviceNotFound
15503 Notes: This interface is deprecated, and it is strongly recommended
15505 that you avoid using it. For changing block devices, use blockdev-
15506 change-medium; for changing VNC parameters, use change-vnc-password.
15507 Since: 0.14.0
15509 Example:
15511 1. Change a removable medium
15513 -> { "execute": "change",
15515 "arguments": { "device": "ide1-cd0",
15516 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
15517 <- { "return": {} }
15518 2. Change VNC password
15520 -> { "execute": "change",
15522 "arguments": { "device": "vnc", "target": "password",
15523 "arg": "foobar1" } }
15524 <- { "return": {} }
15525 xen-set-global-dirty-log (Command) Enable or disable the global dirty
15527 log mode.
15528 Arguments:
15530 "enable: boolean"
15532 true to enable, false to disable.
15533 Returns: nothing
15535 Since: 1.3
15537 Example:
15539 -> { "execute": "xen-set-global-dirty-log",
15541 "arguments": { "enable": true } }
15542 <- { "return": {} }
15543 getfd (Command) Receive a file descriptor via SCM rights and assign it
15545 a name
15546 Arguments:
15548 "fdname: string"
15550 file descriptor name
15551 Returns: Nothing on success
15553 Since: 0.14.0
15555 Notes: If "fdname" already exists, the file descriptor assigned to it
15557 will be closed and replaced by the received file descriptor.
15558 The 'closefd' command can be used to explicitly close the file
15560 descriptor when it is no longer needed.
15561 Example:
15563 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
15565 <- { "return": {} }
15566 closefd (Command) Close a file descriptor previously passed via SCM
15568 rights
15569 Arguments:
15571 "fdname: string"
15573 file descriptor name
15574 Returns: Nothing on success
15576 Since: 0.14.0
15578 Example:
15580 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
15582 <- { "return": {} }
15583 MemoryInfo (Object)
15585 Actual memory information in bytes.
15587 Members:
15589 "base-memory: int"
15591 size of "base" memory specified with command line option -m.
15592 "plugged-memory: int" (optional)
15594 size of memory that can be hot-unplugged. This field is omitted if
15595 target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE not
15596 defined at build time).
15597 Since: 2.11.0
15599 query-memory-size-summary (Command) Return the amount of initially
15601 allocated and present hotpluggable (if enabled) memory in bytes.
15602 Example:
15604 -> { "execute": "query-memory-size-summary" }
15606 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
15607 Since: 2.11.0
15609 AddfdInfo (Object)
15611 Information about a file descriptor that was added to an fd set.
15613 Members:
15615 "fdset-id: int"
15617 The ID of the fd set that "fd" was added to.
15618 "fd: int"
15620 The file descriptor that was received via SCM rights and added to
15621 the fd set.
15622 Since: 1.2.0
15624 add-fd (Command) Add a file descriptor, that was passed via SCM
15626 rights, to an fd set.
15627 Arguments:
15629 "fdset-id: int" (optional)
15631 The ID of the fd set to add the file descriptor to.
15632 "opaque: string" (optional)
15634 A free-form string that can be used to describe the fd.
15635 Returns: "AddfdInfo" on success
15637 If file descriptor was not received, FdNotSupplied
15639 If "fdset-id" is a negative value, InvalidParameterValue
15641 Notes: The list of fd sets is shared by all monitor connections.
15643 If "fdset-id" is not specified, a new fd set will be created.
15645 Since: 1.2.0
15647 Example:
15649 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
15651 <- { "return": { "fdset-id": 1, "fd": 3 } }
15652 remove-fd (Command) Remove a file descriptor from an fd set.
15654 Arguments:
15656 "fdset-id: int"
15658 The ID of the fd set that the file descriptor belongs to.
15659 "fd: int" (optional)
15661 The file descriptor that is to be removed.
15662 Returns: Nothing on success If "fdset-id" or "fd" is not found,
15664 FdNotFound
15665 Since: 1.2.0
15667 Notes: The list of fd sets is shared by all monitor connections.
15669 If "fd" is not specified, all file descriptors in "fdset-id" will be
15671 removed.
15672 Example:
15674 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
15676 <- { "return": {} }
15677 FdsetFdInfo (Object)
15679 Information about a file descriptor that belongs to an fd set.
15681 Members:
15683 "fd: int"
15685 The file descriptor value.
15686 "opaque: string" (optional)
15688 A free-form string that can be used to describe the fd.
15689 Since: 1.2.0
15691 FdsetInfo (Object)
15693 Information about an fd set.
15695 Members:
15697 "fdset-id: int"
15699 The ID of the fd set.
15700 "fds: array of FdsetFdInfo"
15702 A list of file descriptors that belong to this fd set.
15703 Since: 1.2.0
15705 query-fdsets (Command) Return information describing all fd sets.
15707 Returns: A list of "FdsetInfo"
15709 Since: 1.2.0
15711 Note: The list of fd sets is shared by all monitor connections.
15713 Example:
15715 -> { "execute": "query-fdsets" }
15717 <- { "return": [
15718 {
15719 "fds": [
15720 {
15721 "fd": 30,
15722 "opaque": "rdonly:/path/to/file"
15723 },
15724 {
15725 "fd": 24,
15726 "opaque": "rdwr:/path/to/file"
15727 }
15728 ],
15729 "fdset-id": 1
15730 },
15731 {
15732 "fds": [
15733 {
15734 "fd": 28
15735 },
15736 {
15737 "fd": 29
15738 }
15739 ],
15740 "fdset-id": 0
15741 }
15742 ]
15743 }
15744 AcpiTableOptions (Object)
15746 Specify an ACPI table on the command line to load.
15748 At most one of "file" and "data" can be specified. The list of files
15750 specified by any one of them is loaded and concatenated in order. If
15751 both are omitted, "data" is implied.
15752 Other fields / optargs can be used to override fields of the generic
15754 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
15755 System Description Table Header. If a header field is not overridden,
15756 then the corresponding value from the concatenated blob is used (in
15757 case of "file"), or it is filled in with a hard-coded value (in case of
15758 "data").
15759 String fields are copied into the matching ACPI member from lowest
15761 address upwards, and silently truncated / NUL-padded to length.
15762 Members:
15764 "sig: string" (optional)
15766 table signature / identifier (4 bytes)
15767 "rev: int" (optional)
15769 table revision number (dependent on signature, 1 byte)
15770 "oem_id: string" (optional)
15772 OEM identifier (6 bytes)
15773 "oem_table_id: string" (optional)
15775 OEM table identifier (8 bytes)
15776 "oem_rev: int" (optional)
15778 OEM-supplied revision number (4 bytes)
15779 "asl_compiler_id: string" (optional)
15781 identifier of the utility that created the table (4 bytes)
15782 "asl_compiler_rev: int" (optional)
15784 revision number of the utility that created the table (4 bytes)
15785 "file: string" (optional)
15787 colon (:) separated list of pathnames to load and concatenate as
15788 table data. The resultant binary blob is expected to have an ACPI
15789 table header. At least one file is required. This field excludes
15790 "data".
15791 "data: string" (optional)
15793 colon (:) separated list of pathnames to load and concatenate as
15794 table data. The resultant binary blob must not have an ACPI table
15795 header. At least one file is required. This field excludes "file".
15796 Since: 1.5
15798 CommandLineParameterType (Enum)
15800 Possible types for an option parameter.
15802 Values:
15804 "string"
15806 accepts a character string
15807 "boolean"
15809 accepts "on" or "off"
15810 "number"
15812 accepts a number
15813 "size"
15815 accepts a number followed by an optional suffix (K)ilo, (M)ega,
15816 (G)iga, (T)era
15817 Since: 1.5
15819 CommandLineParameterInfo (Object)
15821 Details about a single parameter of a command line option.
15823 Members:
15825 "name: string"
15827 parameter name
15828 "type: CommandLineParameterType"
15830 parameter "CommandLineParameterType"
15831 "help: string" (optional)
15833 human readable text string, not suitable for parsing.
15834 "default: string" (optional)
15836 default value string (since 2.1)
15837 Since: 1.5
15839 CommandLineOptionInfo (Object)
15841 Details about a command line option, including its list of parameter
15843 details
15844 Members:
15846 "option: string"
15848 option name
15849 "parameters: array of CommandLineParameterInfo"
15851 an array of "CommandLineParameterInfo"
15852 Since: 1.5
15854 query-command-line-options (Command) Query command line option schema.
15856 Arguments:
15858 "option: string" (optional)
15860 option name
15861 Returns: list of "CommandLineOptionInfo" for all options (or for the
15863 given "option"). Returns an error if the given "option" doesn't exist.
15864 Since: 1.5
15866 Example:
15868 -> { "execute": "query-command-line-options",
15870 "arguments": { "option": "option-rom" } }
15871 <- { "return": [
15872 {
15873 "parameters": [
15874 {
15875 "name": "romfile",
15876 "type": "string"
15877 },
15878 {
15879 "name": "bootindex",
15880 "type": "number"
15881 }
15882 ],
15883 "option": "option-rom"
15884 }
15885 ]
15886 }
15887 PCDIMMDeviceInfo (Object)
15889 PCDIMMDevice state information
15891 Members:
15893 "id: string" (optional)
15895 device's ID
15896 "addr: int"
15898 physical address, where device is mapped
15899 "size: int"
15901 size of memory that the device provides
15902 "slot: int"
15904 slot number at which device is plugged in
15905 "node: int"
15907 NUMA node number where device is plugged in
15908 "memdev: string"
15910 memory backend linked with device
15911 "hotplugged: boolean"
15913 true if device was hotplugged
15914 "hotpluggable: boolean"
15916 true if device if could be added/removed while machine is running
15917 Since: 2.1
15919 VirtioPMEMDeviceInfo (Object)
15921 VirtioPMEM state information
15923 Members:
15925 "id: string" (optional)
15927 device's ID
15928 "memaddr: int"
15930 physical address in memory, where device is mapped
15931 "size: int"
15933 size of memory that the device provides
15934 "memdev: string"
15936 memory backend linked with device
15937 Since: 4.1
15939 MemoryDeviceInfo (Object)
15941 Union containing information about a memory device
15943 nvdimm is included since 2.12. virtio-pmem is included since 4.1.
15945 Members:
15947 "type"
15949 One of "dimm", "nvdimm", "virtio-pmem"
15950 "data: PCDIMMDeviceInfo" when "type" is "dimm"
15952 "data: PCDIMMDeviceInfo" when "type" is "nvdimm"
15953 "data: VirtioPMEMDeviceInfo" when "type" is "virtio-pmem"
15954 Since: 2.1
15956 query-memory-devices (Command) Lists available memory devices and
15958 their state
15959 Since: 2.1
15961 Example:
15963 -> { "execute": "query-memory-devices" }
15965 <- { "return": [ { "data":
15966 { "addr": 5368709120,
15967 "hotpluggable": true,
15968 "hotplugged": true,
15969 "id": "d1",
15970 "memdev": "/objects/memX",
15971 "node": 0,
15972 "size": 1073741824,
15973 "slot": 0},
15974 "type": "dimm"
15975 } ] }
15976 MEM_UNPLUG_ERROR (Event) Emitted when memory hot unplug error occurs.
15978 Arguments:
15980 "device: string"
15982 device name
15983 "msg: string"
15985 Informative message
15986 Since: 2.4
15988 Example:
15990 <- { "event": "MEM_UNPLUG_ERROR"
15992 "data": { "device": "dimm1",
15993 "msg": "acpi: device unplug for unsupported device"
15994 },
15995 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
15996 ACPISlotType (Enum)
15998 Values:
16000 "DIMM"
16002 memory slot
16003 "CPU"
16005 logical CPU slot (since 2.7)
16006 ACPIOSTInfo (Object)
16008 OSPM Status Indication for a device For description of possible values
16010 of "source" and "status" fields see "_OST (OSPM Status Indication)"
16011 chapter of ACPI5.0 spec.
16012 Members:
16014 "device: string" (optional)
16016 device ID associated with slot
16017 "slot: string"
16019 slot ID, unique per slot of a given "slot-type"
16020 "slot-type: ACPISlotType"
16022 type of the slot
16023 "source: int"
16025 an integer containing the source event
16026 "status: int"
16028 an integer containing the status code
16029 Since: 2.1
16031 query-acpi-ospm-status (Command) Return a list of ACPIOSTInfo for
16033 devices that support status reporting via ACPI _OST method.
16034 Since: 2.1
16036 Example:
16038 -> { "execute": "query-acpi-ospm-status" }
16040 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
16041 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
16042 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
16043 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
16044 ]}
16045 ACPI_DEVICE_OST (Event) Emitted when guest executes ACPI _OST method.
16047 Arguments:
16049 "info: ACPIOSTInfo"
16051 OSPM Status Indication
16052 Since: 2.1
16054 Example:
16056 <- { "event": "ACPI_DEVICE_OST",
16058 "data": { "device": "d1", "slot": "0",
16059 "slot-type": "DIMM", "source": 1, "status": 0 } }
16060 ReplayMode (Enum)
16062 Mode of the replay subsystem.
16064 Values:
16066 "none"
16068 normal execution mode. Replay or record are not enabled.
16069 "record"
16071 record mode. All non-deterministic data is written into the replay
16072 log.
16073 "play"
16075 replay mode. Non-deterministic data required for system execution
16076 is read from the log.
16077 Since: 2.5
16079 xen-load-devices-state (Command) Load the state of all devices from
16081 file. The RAM and the block devices of the VM are not loaded by this
16082 command.
16083 Arguments:
16085 "filename: string"
16087 the file to load the state of the devices from as binary data. See
16088 xen-save-devices-state.txt for a description of the binary format.
16089 Since: 2.7
16091 Example:
16093 -> { "execute": "xen-load-devices-state",
16095 "arguments": { "filename": "/tmp/resume" } }
16096 <- { "return": {} }
16097 GuidInfo (Object)
16099 GUID information.
16101 Members:
16103 "guid: string"
16105 the globally unique identifier
16106 Since: 2.9
16108 query-vm-generation-id (Command) Show Virtual Machine Generation ID
16110 Since: 2.9
16112 RTC_CHANGE (Event) Emitted when the guest changes the RTC time.
16114 Arguments:
16116 "offset: int"
16118 offset between base RTC clock (as specified by -rtc base), and new
16119 RTC clock value
16120 Note: This event is rate-limited.
16122 Since: 0.13.0
16124 Example:
16126 <- { "event": "RTC_CHANGE",
16128 "data": { "offset": 78 },
16129 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
16130 If: "defined(TARGET_ALPHA) || defined(TARGET_ARM) ||
16132 defined(TARGET_HPPA) || defined(TARGET_I386) || defined(TARGET_MIPS) ||
16133 defined(TARGET_MIPS64) || defined(TARGET_MOXIE) || defined(TARGET_PPC)
16134 || defined(TARGET_PPC64) || defined(TARGET_S390X) ||
16135 defined(TARGET_SH4) || defined(TARGET_SPARC)"
16136 rtc-reset-reinjection (Command) This command will reset the RTC
16138 interrupt reinjection backlog. Can be used if another mechanism to
16139 synchronize guest time is in effect, for example QEMU guest agent's
16140 guest-set-time command.
16141 Since: 2.1
16143 Example:
16145 -> { "execute": "rtc-reset-reinjection" }
16147 <- { "return": {} }
16148 If: "defined(TARGET_I386)"
16150 SevState (Enum)
16152 An enumeration of SEV state information used during "query-sev".
16154 Values:
16156 "uninit"
16158 The guest is uninitialized.
16159 "launch-update"
16161 The guest is currently being launched; plaintext data and register
16162 state is being imported.
16163 "launch-secret"
16165 The guest is currently being launched; ciphertext data is being
16166 imported.
16167 "running"
16169 The guest is fully launched or migrated in.
16170 "send-update"
16172 The guest is currently being migrated out to another machine.
16173 "receive-update"
16175 The guest is currently being migrated from another machine.
16176 Since: 2.12
16178 If: "defined(TARGET_I386)"
16180 SevInfo (Object)
16182 Information about Secure Encrypted Virtualization (SEV) support
16184 Members:
16186 "enabled: boolean"
16188 true if SEV is active
16189 "api-major: int"
16191 SEV API major version
16192 "api-minor: int"
16194 SEV API minor version
16195 "build-id: int"
16197 SEV FW build id
16198 "policy: int"
16200 SEV policy value
16201 "state: SevState"
16203 SEV guest state
16204 "handle: int"
16206 SEV firmware handle
16207 Since: 2.12
16209 If: "defined(TARGET_I386)"
16211 query-sev (Command) Returns information about SEV
16213 Returns: "SevInfo"
16215 Since: 2.12
16217 Example:
16219 -> { "execute": "query-sev" }
16221 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
16222 "build-id" : 0, "policy" : 0, "state" : "running",
16223 "handle" : 1 } }
16224 If: "defined(TARGET_I386)"
16226 SevLaunchMeasureInfo (Object)
16228 SEV Guest Launch measurement information
16230 Members:
16232 "data: string"
16234 the measurement value encoded in base64
16235 Since: 2.12
16237 If: "defined(TARGET_I386)"
16239 query-sev-launch-measure (Command) Query the SEV guest launch
16241 information.
16242 Returns: The "SevLaunchMeasureInfo" for the guest
16244 Since: 2.12
16246 Example:
16248 -> { "execute": "query-sev-launch-measure" }
16250 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
16251 If: "defined(TARGET_I386)"
16253 SevCapability (Object)
16255 The struct describes capability for a Secure Encrypted Virtualization
16257 feature.
16258 Members:
16260 "pdh: string"
16262 Platform Diffie-Hellman key (base64 encoded)
16263 "cert-chain: string"
16265 PDH certificate chain (base64 encoded)
16266 "cbitpos: int"
16268 C-bit location in page table entry
16269 "reduced-phys-bits: int"
16271 Number of physical Address bit reduction when SEV is enabled
16272 Since: 2.12
16274 If: "defined(TARGET_I386)"
16276 query-sev-capabilities (Command) This command is used to get the SEV
16278 capabilities, and is supported on AMD X86 platforms only.
16279 Returns: SevCapability objects.
16281 Since: 2.12
16283 Example:
16285 -> { "execute": "query-sev-capabilities" }
16287 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
16288 "cbitpos": 47, "reduced-phys-bits": 5}}
16289 If: "defined(TARGET_I386)"
16291 dump-skeys (Command) Dump guest's storage keys
16293 Arguments:
16295 "filename: string"
16297 the path to the file to dump to
16298 This command is only supported on s390 architecture.
16300 Since: 2.5
16302 Example:
16304 -> { "execute": "dump-skeys",
16306 "arguments": { "filename": "/tmp/skeys" } }
16307 <- { "return": {} }
16308 If: "defined(TARGET_S390X)"
16310 GICCapability (Object)
16312 The struct describes capability for a specific GIC (Generic Interrupt
16314 Controller) version. These bits are not only decided by QEMU/KVM
16315 software version, but also decided by the hardware that the program is
16316 running upon.
16317 Members:
16319 "version: int"
16321 version of GIC to be described. Currently, only 2 and 3 are
16322 supported.
16323 "emulated: boolean"
16325 whether current QEMU/hardware supports emulated GIC device in user
16326 space.
16327 "kernel: boolean"
16329 whether current QEMU/hardware supports hardware accelerated GIC
16330 device in kernel.
16331 Since: 2.6
16333 If: "defined(TARGET_ARM)"
16335 query-gic-capabilities (Command) This command is ARM-only. It will
16337 return a list of GICCapability objects that describe its capability
16338 bits.
16339 Returns: a list of GICCapability objects.
16341 Since: 2.6
16343 Example:
16345 -> { "execute": "query-gic-capabilities" }
16347 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
16348 { "version": 3, "emulated": false, "kernel": true } ] }
16349 If: "defined(TARGET_ARM)"
16351 AudiodevPerDirectionOptions (Object)
16353 General audio backend options that are used for both playback and
16355 recording.
16356 Members:
16358 "mixing-engine: boolean" (optional)
16360 use QEMU's mixing engine to mix all streams inside QEMU and convert
16361 audio formats when not supported by the backend. When set to off,
16362 fixed-settings must be also off (default on, since 4.2)
16363 "fixed-settings: boolean" (optional)
16365 use fixed settings for host input/output. When off, frequency,
16366 channels and format must not be specified (default true)
16367 "frequency: int" (optional)
16369 frequency to use when using fixed settings (default 44100)
16370 "channels: int" (optional)
16372 number of channels when using fixed settings (default 2)
16373 "voices: int" (optional)
16375 number of voices to use (default 1)
16376 "format: AudioFormat" (optional)
16378 sample format to use when using fixed settings (default s16)
16379 "buffer-length: int" (optional)
16381 the buffer length in microseconds
16382 Since: 4.0
16384 AudiodevGenericOptions (Object)
16386 Generic driver-specific options.
16388 Members:
16390 "in: AudiodevPerDirectionOptions" (optional)
16392 options of the capture stream
16393 "out: AudiodevPerDirectionOptions" (optional)
16395 options of the playback stream
16396 Since: 4.0
16398 AudiodevAlsaPerDirectionOptions (Object)
16400 Options of the ALSA backend that are used for both playback and
16402 recording.
16403 Members:
16405 "dev: string" (optional)
16407 the name of the ALSA device to use (default 'default')
16408 "period-length: int" (optional)
16410 the period length in microseconds
16411 "try-poll: boolean" (optional)
16413 attempt to use poll mode, falling back to non-polling access on
16414 failure (default true)
16415 The members of "AudiodevPerDirectionOptions"
16417 Since: 4.0
16419 AudiodevAlsaOptions (Object)
16421 Options of the ALSA audio backend.
16423 Members:
16425 "in: AudiodevAlsaPerDirectionOptions" (optional)
16427 options of the capture stream
16428 "out: AudiodevAlsaPerDirectionOptions" (optional)
16430 options of the playback stream
16431 "threshold: int" (optional)
16433 set the threshold (in microseconds) when playback starts
16434 Since: 4.0
16436 AudiodevCoreaudioPerDirectionOptions (Object)
16438 Options of the Core Audio backend that are used for both playback and
16440 recording.
16441 Members:
16443 "buffer-count: int" (optional)
16445 number of buffers
16446 The members of "AudiodevPerDirectionOptions"
16448 Since: 4.0
16450 AudiodevCoreaudioOptions (Object)
16452 Options of the coreaudio audio backend.
16454 Members:
16456 "in: AudiodevCoreaudioPerDirectionOptions" (optional)
16458 options of the capture stream
16459 "out: AudiodevCoreaudioPerDirectionOptions" (optional)
16461 options of the playback stream
16462 Since: 4.0
16464 AudiodevDsoundOptions (Object)
16466 Options of the DirectSound audio backend.
16468 Members:
16470 "in: AudiodevPerDirectionOptions" (optional)
16472 options of the capture stream
16473 "out: AudiodevPerDirectionOptions" (optional)
16475 options of the playback stream
16476 "latency: int" (optional)
16478 add extra latency to playback in microseconds (default 10000)
16479 Since: 4.0
16481 AudiodevOssPerDirectionOptions (Object)
16483 Options of the OSS backend that are used for both playback and
16485 recording.
16486 Members:
16488 "dev: string" (optional)
16490 file name of the OSS device (default '/dev/dsp')
16491 "buffer-count: int" (optional)
16493 number of buffers
16494 "try-poll: boolean" (optional)
16496 attempt to use poll mode, falling back to non-polling access on
16497 failure (default true)
16498 The members of "AudiodevPerDirectionOptions"
16500 Since: 4.0
16502 AudiodevOssOptions (Object)
16504 Options of the OSS audio backend.
16506 Members:
16508 "in: AudiodevOssPerDirectionOptions" (optional)
16510 options of the capture stream
16511 "out: AudiodevOssPerDirectionOptions" (optional)
16513 options of the playback stream
16514 "try-mmap: boolean" (optional)
16516 try using memory-mapped access, falling back to non-memory-mapped
16517 access on failure (default true)
16518 "exclusive: boolean" (optional)
16520 open device in exclusive mode (vmix won't work) (default false)
16521 "dsp-policy: int" (optional)
16523 set the timing policy of the device (between 0 and 10, where
16524 smaller number means smaller latency but higher CPU usage) or -1 to
16525 use fragment mode (option ignored on some platforms) (default 5)
16526 Since: 4.0
16528 AudiodevPaPerDirectionOptions (Object)
16530 Options of the Pulseaudio backend that are used for both playback and
16532 recording.
16533 Members:
16535 "name: string" (optional)
16537 name of the sink/source to use
16538 "stream-name: string" (optional)
16540 name of the PulseAudio stream created by qemu. Can be used to
16541 identify the stream in PulseAudio when you create multiple
16542 PulseAudio devices or run multiple qemu instances (default:
16543 audiodev's id, since 4.2)
16544 "latency: int" (optional)
16546 latency you want PulseAudio to achieve in microseconds (default
16547 15000)
16548 The members of "AudiodevPerDirectionOptions"
16550 Since: 4.0
16552 AudiodevPaOptions (Object)
16554 Options of the PulseAudio audio backend.
16556 Members:
16558 "in: AudiodevPaPerDirectionOptions" (optional)
16560 options of the capture stream
16561 "out: AudiodevPaPerDirectionOptions" (optional)
16563 options of the playback stream
16564 "server: string" (optional)
16566 PulseAudio server address (default: let PulseAudio choose)
16567 Since: 4.0
16569 AudiodevWavOptions (Object)
16571 Options of the wav audio backend.
16573 Members:
16575 "in: AudiodevPerDirectionOptions" (optional)
16577 options of the capture stream
16578 "out: AudiodevPerDirectionOptions" (optional)
16580 options of the playback stream
16581 "path: string" (optional)
16583 name of the wav file to record (default 'qemu.wav')
16584 Since: 4.0
16586 AudioFormat (Enum)
16588 An enumeration of possible audio formats.
16590 Values:
16592 "u8"
16594 Not documented
16595 "s8"
16597 Not documented
16598 "u16"
16600 Not documented
16601 "s16"
16603 Not documented
16604 "u32"
16606 Not documented
16607 "s32"
16609 Not documented
16610 Since: 4.0
16612 AudiodevDriver (Enum)
16614 An enumeration of possible audio backend drivers.
16616 Values:
16618 "none"
16620 Not documented
16621 "alsa"
16623 Not documented
16624 "coreaudio"
16626 Not documented
16627 "dsound"
16629 Not documented
16630 "oss"
16632 Not documented
16633 "pa"
16635 Not documented
16636 "sdl"
16638 Not documented
16639 "spice"
16641 Not documented
16642 "wav"
16644 Not documented
16645 Since: 4.0
16647 Audiodev (Object)
16649 Options of an audio backend.
16651 Members:
16653 "id: string"
16655 identifier of the backend
16656 "driver: AudiodevDriver"
16658 the backend driver to use
16659 "timer-period: int" (optional)
16661 timer period (in microseconds, 0: use lowest possible)
16662 The members of "AudiodevGenericOptions" when "driver" is "none"
16664 The members of "AudiodevAlsaOptions" when "driver" is "alsa"
16665 The members of "AudiodevCoreaudioOptions" when "driver" is "coreaudio"
16666 The members of "AudiodevDsoundOptions" when "driver" is "dsound"
16667 The members of "AudiodevOssOptions" when "driver" is "oss"
16668 The members of "AudiodevPaOptions" when "driver" is "pa"
16669 The members of "AudiodevGenericOptions" when "driver" is "sdl"
16670 The members of "AudiodevGenericOptions" when "driver" is "spice"
16671 The members of "AudiodevWavOptions" when "driver" is "wav"
16672 Since: 4.0
16674 2020-03-17 QEMU-QMP-REF.7(7)