blob: 020e5ee96c264c5c71895d7baa59e6fc848e2379 [file] [log] [blame]
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001HXCOMM QMP dispatch table and documentation
Alberto Garcia3599d462015-02-26 16:35:07 +02002HXCOMM Text between SQMP and EQMP is copied to the QMP documentation file and
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003HXCOMM does not show up in the other formats.
4
5SQMP
6 QMP Supported Commands
7 ----------------------
8
9This document describes all commands currently supported by QMP.
10
11Most of the time their usage is exactly the same as in the user Monitor, this
12means that any other document which also describe commands (the manpage,
13QEMU's manual, etc) can and should be consulted.
14
15QMP has two types of commands: regular and query commands. Regular commands
16usually change the Virtual Machine's state someway, while query commands just
17return information. The sections below are divided accordingly.
18
19It's important to observe that all communication examples are formatted in
20a reader-friendly way, so that they're easier to understand. However, in real
21protocol usage, they're emitted as a single line.
22
23Also, the following notation is used to denote data flow:
24
25-> data issued by the Client
26<- Server data response
27
28Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
29information on the Server command and response formats.
30
31NOTE: This document is temporary and will be replaced soon.
32
331. Stability Considerations
34===========================
35
36The current QMP command set (described in this file) may be useful for a
37number of use cases, however it's limited and several commands have bad
38defined semantics, specially with regard to command completion.
39
40These problems are going to be solved incrementally in the next QEMU releases
41and we're going to establish a deprecation policy for badly defined commands.
42
43If you're planning to adopt QMP, please observe the following:
44
Zhi Yong Wuc20cdf82011-07-27 14:32:56 +080045 1. The deprecation policy will take effect and be documented soon, please
Luiz Capitulino82a56f02010-09-13 12:26:00 -030046 check the documentation of each used command as soon as a new release of
47 QEMU is available
48
49 2. DO NOT rely on anything which is not explicit documented
50
51 3. Errors, in special, are not documented. Applications should NOT check
52 for specific errors classes or data (it's strongly recommended to only
53 check for the "error" key)
54
552. Regular Commands
56===================
57
58Server's responses in the examples below are always a success response, please
59refer to the QMP specification for more details on error responses.
60
61EQMP
62
63 {
64 .name = "quit",
65 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +020066 .mhandler.cmd_new = qmp_marshal_quit,
Luiz Capitulino82a56f02010-09-13 12:26:00 -030067 },
68
69SQMP
70quit
71----
72
73Quit the emulator.
74
75Arguments: None.
76
77Example:
78
79-> { "execute": "quit" }
80<- { "return": {} }
81
82EQMP
83
84 {
85 .name = "eject",
86 .args_type = "force:-f,device:B",
Markus Armbruster7fad30f2015-09-16 13:06:19 +020087 .mhandler.cmd_new = qmp_marshal_eject,
Luiz Capitulino82a56f02010-09-13 12:26:00 -030088 },
89
90SQMP
91eject
92-----
93
94Eject a removable medium.
95
96Arguments:
97
98- force: force ejection (json-bool, optional)
99- device: device name (json-string)
100
101Example:
102
103-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
104<- { "return": {} }
105
106Note: The "force" argument defaults to false.
107
108EQMP
109
110 {
111 .name = "change",
112 .args_type = "device:B,target:F,arg:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200113 .mhandler.cmd_new = qmp_marshal_change,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300114 },
115
116SQMP
117change
118------
119
120Change a removable medium or VNC configuration.
121
122Arguments:
123
124- "device": device name (json-string)
125- "target": filename or item (json-string)
126- "arg": additional argument (json-string, optional)
127
128Examples:
129
1301. Change a removable medium
131
132-> { "execute": "change",
133 "arguments": { "device": "ide1-cd0",
134 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
135<- { "return": {} }
136
1372. Change VNC password
138
139-> { "execute": "change",
140 "arguments": { "device": "vnc", "target": "password",
141 "arg": "foobar1" } }
142<- { "return": {} }
143
144EQMP
145
146 {
147 .name = "screendump",
148 .args_type = "filename:F",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200149 .mhandler.cmd_new = qmp_marshal_screendump,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300150 },
151
152SQMP
153screendump
154----------
155
156Save screen into PPM image.
157
158Arguments:
159
160- "filename": file path (json-string)
161
162Example:
163
164-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
165<- { "return": {} }
166
167EQMP
168
169 {
170 .name = "stop",
171 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200172 .mhandler.cmd_new = qmp_marshal_stop,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300173 },
174
175SQMP
176stop
177----
178
179Stop the emulator.
180
181Arguments: None.
182
183Example:
184
185-> { "execute": "stop" }
186<- { "return": {} }
187
188EQMP
189
190 {
191 .name = "cont",
192 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200193 .mhandler.cmd_new = qmp_marshal_cont,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300194 },
195
196SQMP
197cont
198----
199
200Resume emulation.
201
202Arguments: None.
203
204Example:
205
206-> { "execute": "cont" }
207<- { "return": {} }
208
209EQMP
210
211 {
Gerd Hoffmann9b9df252012-02-23 13:45:21 +0100212 .name = "system_wakeup",
213 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200214 .mhandler.cmd_new = qmp_marshal_system_wakeup,
Gerd Hoffmann9b9df252012-02-23 13:45:21 +0100215 },
216
217SQMP
218system_wakeup
219-------------
220
221Wakeup guest from suspend.
222
223Arguments: None.
224
225Example:
226
227-> { "execute": "system_wakeup" }
228<- { "return": {} }
229
230EQMP
231
232 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300233 .name = "system_reset",
234 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200235 .mhandler.cmd_new = qmp_marshal_system_reset,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300236 },
237
238SQMP
239system_reset
240------------
241
242Reset the system.
243
244Arguments: None.
245
246Example:
247
248-> { "execute": "system_reset" }
249<- { "return": {} }
250
251EQMP
252
253 {
254 .name = "system_powerdown",
255 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200256 .mhandler.cmd_new = qmp_marshal_system_powerdown,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300257 },
258
259SQMP
260system_powerdown
261----------------
262
263Send system power down event.
264
265Arguments: None.
266
267Example:
268
269-> { "execute": "system_powerdown" }
270<- { "return": {} }
271
272EQMP
273
274 {
275 .name = "device_add",
276 .args_type = "device:O",
277 .params = "driver[,prop=value][,...]",
278 .help = "add device, like -device on the command line",
Markus Armbruster485febc2015-03-13 17:25:50 +0100279 .mhandler.cmd_new = qmp_device_add,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300280 },
281
282SQMP
283device_add
284----------
285
286Add a device.
287
288Arguments:
289
290- "driver": the name of the new device's driver (json-string)
291- "bus": the device's parent bus (device tree path, json-string, optional)
292- "id": the device's ID, must be unique (json-string)
293- device properties
294
295Example:
296
297-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
298<- { "return": {} }
299
300Notes:
301
302(1) For detailed information about this command, please refer to the
303 'docs/qdev-device-use.txt' file.
304
305(2) It's possible to list device properties by running QEMU with the
306 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
307
308EQMP
309
310 {
311 .name = "device_del",
312 .args_type = "id:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200313 .mhandler.cmd_new = qmp_marshal_device_del,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300314 },
315
316SQMP
317device_del
318----------
319
320Remove a device.
321
322Arguments:
323
Daniel P. Berrange6287d822015-09-11 13:33:56 +0100324- "id": the device's ID or QOM path (json-string)
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300325
326Example:
327
328-> { "execute": "device_del", "arguments": { "id": "net1" } }
329<- { "return": {} }
330
Daniel P. Berrange6287d822015-09-11 13:33:56 +0100331Example:
332
333-> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
334<- { "return": {} }
335
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300336EQMP
337
338 {
Amos Konge4c8f002012-08-31 10:56:26 +0800339 .name = "send-key",
Paolo Bonzini43d0a2c2015-04-15 13:30:04 +0200340 .args_type = "keys:q,hold-time:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200341 .mhandler.cmd_new = qmp_marshal_send_key,
Amos Konge4c8f002012-08-31 10:56:26 +0800342 },
343
344SQMP
345send-key
346----------
347
348Send keys to VM.
349
350Arguments:
351
352keys array:
Amos Kongf9b1d9b2013-07-16 19:52:14 +0800353 - "key": key sequence (a json-array of key union values,
354 union can be number or qcode enum)
Amos Konge4c8f002012-08-31 10:56:26 +0800355
356- hold-time: time to delay key up events, milliseconds. Defaults to 100
357 (json-int, optional)
358
359Example:
360
361-> { "execute": "send-key",
Amos Kongf9b1d9b2013-07-16 19:52:14 +0800362 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
363 { "type": "qcode", "data": "alt" },
364 { "type": "qcode", "data": "delete" } ] } }
Amos Konge4c8f002012-08-31 10:56:26 +0800365<- { "return": {} }
366
367EQMP
368
369 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300370 .name = "cpu",
371 .args_type = "index:i",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200372 .mhandler.cmd_new = qmp_marshal_cpu,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300373 },
374
375SQMP
376cpu
377---
378
379Set the default CPU.
380
381Arguments:
382
383- "index": the CPU's index (json-int)
384
385Example:
386
387-> { "execute": "cpu", "arguments": { "index": 0 } }
388<- { "return": {} }
389
390Note: CPUs' indexes are obtained with the 'query-cpus' command.
391
392EQMP
393
394 {
Igor Mammedov69ca3ea2013-04-30 15:41:25 +0200395 .name = "cpu-add",
396 .args_type = "id:i",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200397 .mhandler.cmd_new = qmp_marshal_cpu_add,
Igor Mammedov69ca3ea2013-04-30 15:41:25 +0200398 },
399
400SQMP
401cpu-add
402-------
403
404Adds virtual cpu
405
406Arguments:
407
408- "id": cpu id (json-int)
409
410Example:
411
412-> { "execute": "cpu-add", "arguments": { "id": 2 } }
413<- { "return": {} }
414
415EQMP
416
417 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300418 .name = "memsave",
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -0200419 .args_type = "val:l,size:i,filename:s,cpu:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200420 .mhandler.cmd_new = qmp_marshal_memsave,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300421 },
422
423SQMP
424memsave
425-------
426
427Save to disk virtual memory dump starting at 'val' of size 'size'.
428
429Arguments:
430
431- "val": the starting address (json-int)
432- "size": the memory size, in bytes (json-int)
433- "filename": file path (json-string)
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -0200434- "cpu": virtual CPU index (json-int, optional)
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300435
436Example:
437
438-> { "execute": "memsave",
439 "arguments": { "val": 10,
440 "size": 100,
441 "filename": "/tmp/virtual-mem-dump" } }
442<- { "return": {} }
443
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300444EQMP
445
446 {
447 .name = "pmemsave",
448 .args_type = "val:l,size:i,filename:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200449 .mhandler.cmd_new = qmp_marshal_pmemsave,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300450 },
451
452SQMP
453pmemsave
454--------
455
456Save to disk physical memory dump starting at 'val' of size 'size'.
457
458Arguments:
459
460- "val": the starting address (json-int)
461- "size": the memory size, in bytes (json-int)
462- "filename": file path (json-string)
463
464Example:
465
466-> { "execute": "pmemsave",
467 "arguments": { "val": 10,
468 "size": 100,
469 "filename": "/tmp/physical-mem-dump" } }
470<- { "return": {} }
471
472EQMP
473
474 {
Lai Jiangshana4046662011-03-07 17:05:15 +0800475 .name = "inject-nmi",
476 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200477 .mhandler.cmd_new = qmp_marshal_inject_nmi,
Lai Jiangshana4046662011-03-07 17:05:15 +0800478 },
479
480SQMP
481inject-nmi
482----------
483
Alexey Kardashevskiy9cb805f2014-08-20 22:16:33 +1000484Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
Lai Jiangshana4046662011-03-07 17:05:15 +0800485
486Arguments: None.
487
488Example:
489
490-> { "execute": "inject-nmi" }
491<- { "return": {} }
492
Luiz Capitulinode253f12012-07-27 16:18:16 -0300493Note: inject-nmi fails when the guest doesn't support injecting.
Lai Jiangshana4046662011-03-07 17:05:15 +0800494
495EQMP
496
497 {
Markus Armbruster3949e592013-02-06 21:27:24 +0100498 .name = "ringbuf-write",
Markus Armbruster82e59a62013-02-06 21:27:14 +0100499 .args_type = "device:s,data:s,format:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200500 .mhandler.cmd_new = qmp_marshal_ringbuf_write,
Lei Li1f590cf2013-01-25 00:03:20 +0800501 },
502
503SQMP
Markus Armbruster3949e592013-02-06 21:27:24 +0100504ringbuf-write
Lei Li1f590cf2013-01-25 00:03:20 +0800505-------------
506
Markus Armbruster3949e592013-02-06 21:27:24 +0100507Write to a ring buffer character device.
Lei Li1f590cf2013-01-25 00:03:20 +0800508
509Arguments:
510
Markus Armbruster3949e592013-02-06 21:27:24 +0100511- "device": ring buffer character device name (json-string)
512- "data": data to write (json-string)
513- "format": data format (json-string, optional)
514 - Possible values: "utf8" (default), "base64"
Lei Li1f590cf2013-01-25 00:03:20 +0800515
516Example:
517
Markus Armbruster3949e592013-02-06 21:27:24 +0100518-> { "execute": "ringbuf-write",
519 "arguments": { "device": "foo",
Lei Li1f590cf2013-01-25 00:03:20 +0800520 "data": "abcdefgh",
521 "format": "utf8" } }
522<- { "return": {} }
523
524EQMP
525
526 {
Markus Armbruster3949e592013-02-06 21:27:24 +0100527 .name = "ringbuf-read",
Lei Li49b6d722013-01-25 00:03:21 +0800528 .args_type = "device:s,size:i,format:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200529 .mhandler.cmd_new = qmp_marshal_ringbuf_read,
Lei Li49b6d722013-01-25 00:03:21 +0800530 },
531
532SQMP
Markus Armbruster3949e592013-02-06 21:27:24 +0100533ringbuf-read
Lei Li49b6d722013-01-25 00:03:21 +0800534-------------
535
Markus Armbruster3949e592013-02-06 21:27:24 +0100536Read from a ring buffer character device.
Lei Li49b6d722013-01-25 00:03:21 +0800537
538Arguments:
539
Markus Armbruster3949e592013-02-06 21:27:24 +0100540- "device": ring buffer character device name (json-string)
541- "size": how many bytes to read at most (json-int)
542 - Number of data bytes, not number of characters in encoded data
543- "format": data format (json-string, optional)
544 - Possible values: "utf8" (default), "base64"
545 - Naturally, format "utf8" works only when the ring buffer
546 contains valid UTF-8 text. Invalid UTF-8 sequences get
547 replaced. Bug: replacement doesn't work. Bug: can screw
548 up on encountering NUL characters, after the ring buffer
549 lost data, and when reading stops because the size limit
550 is reached.
Lei Li49b6d722013-01-25 00:03:21 +0800551
552Example:
553
Markus Armbruster3949e592013-02-06 21:27:24 +0100554-> { "execute": "ringbuf-read",
555 "arguments": { "device": "foo",
Lei Li49b6d722013-01-25 00:03:21 +0800556 "size": 1000,
557 "format": "utf8" } }
Markus Armbruster3ab651f2013-02-06 21:27:15 +0100558<- {"return": "abcdefgh"}
Lei Li49b6d722013-01-25 00:03:21 +0800559
560EQMP
561
562 {
Stefano Stabellinia7ae8352012-01-25 12:24:51 +0000563 .name = "xen-save-devices-state",
564 .args_type = "filename:F",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200565 .mhandler.cmd_new = qmp_marshal_xen_save_devices_state,
Stefano Stabellinia7ae8352012-01-25 12:24:51 +0000566 },
567
568SQMP
569xen-save-devices-state
570-------
571
572Save the state of all devices to file. The RAM and the block devices
573of the VM are not saved by this command.
574
575Arguments:
576
577- "filename": the file to save the state of the devices to as binary
578data. See xen-save-devices-state.txt for a description of the binary
579format.
580
581Example:
582
583-> { "execute": "xen-save-devices-state",
584 "arguments": { "filename": "/tmp/save" } }
585<- { "return": {} }
586
587EQMP
588
589 {
Anthony PERARD39f42432012-10-03 13:48:19 +0000590 .name = "xen-set-global-dirty-log",
591 .args_type = "enable:b",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200592 .mhandler.cmd_new = qmp_marshal_xen_set_global_dirty_log,
Anthony PERARD39f42432012-10-03 13:48:19 +0000593 },
594
595SQMP
596xen-set-global-dirty-log
597-------
598
599Enable or disable the global dirty log mode.
600
601Arguments:
602
603- "enable": Enable it or disable it.
604
605Example:
606
607-> { "execute": "xen-set-global-dirty-log",
608 "arguments": { "enable": true } }
609<- { "return": {} }
610
611EQMP
612
613 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300614 .name = "migrate",
615 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200616 .mhandler.cmd_new = qmp_marshal_migrate,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300617 },
618
619SQMP
620migrate
621-------
622
623Migrate to URI.
624
625Arguments:
626
627- "blk": block migration, full disk copy (json-bool, optional)
628- "inc": incremental disk copy (json-bool, optional)
629- "uri": Destination URI (json-string)
630
631Example:
632
633-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
634<- { "return": {} }
635
636Notes:
637
638(1) The 'query-migrate' command should be used to check migration's progress
639 and final result (this information is provided by the 'status' member)
640(2) All boolean arguments default to false
641(3) The user Monitor's "detach" argument is invalid in QMP and should not
642 be used
643
644EQMP
645
646 {
647 .name = "migrate_cancel",
648 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200649 .mhandler.cmd_new = qmp_marshal_migrate_cancel,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300650 },
651
652SQMP
653migrate_cancel
654--------------
655
656Cancel the current migration.
657
658Arguments: None.
659
660Example:
661
662-> { "execute": "migrate_cancel" }
663<- { "return": {} }
664
665EQMP
Dr. David Alan Gilbertbf1ae1f2015-02-19 11:40:28 +0000666
667 {
668 .name = "migrate-incoming",
669 .args_type = "uri:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200670 .mhandler.cmd_new = qmp_marshal_migrate_incoming,
Dr. David Alan Gilbertbf1ae1f2015-02-19 11:40:28 +0000671 },
672
673SQMP
674migrate-incoming
675----------------
676
677Continue an incoming migration
678
679Arguments:
680
681- "uri": Source/listening URI (json-string)
682
683Example:
684
685-> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
686<- { "return": {} }
687
688Notes:
689
690(1) QEMU must be started with -incoming defer to allow migrate-incoming to
691 be used
Dr. David Alan Gilbert4aab6282015-06-03 19:43:56 +0100692(2) The uri format is the same as for -incoming
Dr. David Alan Gilbertbf1ae1f2015-02-19 11:40:28 +0000693
694EQMP
695 {
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300696 .name = "migrate-set-cache-size",
697 .args_type = "value:o",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200698 .mhandler.cmd_new = qmp_marshal_migrate_set_cache_size,
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300699 },
700
701SQMP
702migrate-set-cache-size
Juan Quintela817c6042013-02-11 15:11:10 +0100703----------------------
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300704
705Set cache size to be used by XBZRLE migration, the cache size will be rounded
706down to the nearest power of 2
707
708Arguments:
709
710- "value": cache size in bytes (json-int)
711
712Example:
713
714-> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
715<- { "return": {} }
716
717EQMP
718 {
Dr. David Alan Gilbert4886a1b2015-11-05 18:10:56 +0000719 .name = "migrate-start-postcopy",
720 .args_type = "",
721 .mhandler.cmd_new = qmp_marshal_migrate_start_postcopy,
722 },
723
724SQMP
725migrate-start-postcopy
726----------------------
727
728Switch an in-progress migration to postcopy mode. Ignored after the end of
729migration (or once already in postcopy).
730
731Example:
732-> { "execute": "migrate-start-postcopy" }
733<- { "return": {} }
734
735EQMP
736
737 {
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300738 .name = "query-migrate-cache-size",
739 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200740 .mhandler.cmd_new = qmp_marshal_query_migrate_cache_size,
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300741 },
742
743SQMP
744query-migrate-cache-size
Juan Quintela817c6042013-02-11 15:11:10 +0100745------------------------
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300746
747Show cache size to be used by XBZRLE migration
748
749returns a json-object with the following information:
750- "size" : json-int
751
752Example:
753
754-> { "execute": "query-migrate-cache-size" }
755<- { "return": 67108864 }
756
757EQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300758
759 {
760 .name = "migrate_set_speed",
Wen Congyang3a019b62010-11-25 09:06:05 +0800761 .args_type = "value:o",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200762 .mhandler.cmd_new = qmp_marshal_migrate_set_speed,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300763 },
764
765SQMP
766migrate_set_speed
767-----------------
768
769Set maximum speed for migrations.
770
771Arguments:
772
Luiz Capitulino5569fd72010-12-15 17:56:18 -0200773- "value": maximum speed, in bytes per second (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300774
775Example:
776
777-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
778<- { "return": {} }
779
780EQMP
781
782 {
783 .name = "migrate_set_downtime",
784 .args_type = "value:T",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200785 .mhandler.cmd_new = qmp_marshal_migrate_set_downtime,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300786 },
787
788SQMP
789migrate_set_downtime
790--------------------
791
792Set maximum tolerated downtime (in seconds) for migrations.
793
794Arguments:
795
796- "value": maximum downtime (json-number)
797
798Example:
799
800-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
801<- { "return": {} }
802
803EQMP
804
805 {
Jes Sorensenff73edf2011-03-09 14:31:06 +0100806 .name = "client_migrate_info",
807 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
808 .params = "protocol hostname port tls-port cert-subject",
Markus Armbruster13cadef2015-03-05 19:16:58 +0100809 .help = "set migration information for remote display",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200810 .mhandler.cmd_new = qmp_marshal_client_migrate_info,
Jes Sorensenff73edf2011-03-09 14:31:06 +0100811 },
812
813SQMP
814client_migrate_info
Markus Armbruster13cadef2015-03-05 19:16:58 +0100815-------------------
Jes Sorensenff73edf2011-03-09 14:31:06 +0100816
Markus Armbruster13cadef2015-03-05 19:16:58 +0100817Set migration information for remote display. This makes the server
818ask the client to automatically reconnect using the new parameters
819once migration finished successfully. Only implemented for SPICE.
Jes Sorensenff73edf2011-03-09 14:31:06 +0100820
821Arguments:
822
Markus Armbruster13cadef2015-03-05 19:16:58 +0100823- "protocol": must be "spice" (json-string)
Jes Sorensenff73edf2011-03-09 14:31:06 +0100824- "hostname": migration target hostname (json-string)
Markus Armbruster13cadef2015-03-05 19:16:58 +0100825- "port": spice tcp port for plaintext channels (json-int, optional)
Jes Sorensenff73edf2011-03-09 14:31:06 +0100826- "tls-port": spice tcp port for tls-secured channels (json-int, optional)
827- "cert-subject": server certificate subject (json-string, optional)
828
829Example:
830
831-> { "execute": "client_migrate_info",
832 "arguments": { "protocol": "spice",
833 "hostname": "virt42.lab.kraxel.org",
834 "port": 1234 } }
835<- { "return": {} }
836
837EQMP
838
839 {
Wen Congyang783e9b42012-05-07 12:10:47 +0800840 .name = "dump-guest-memory",
qiaonuohanb53ccc32014-02-18 14:11:36 +0800841 .args_type = "paging:b,protocol:s,begin:i?,end:i?,format:s?",
842 .params = "-p protocol [begin] [length] [format]",
Wen Congyang783e9b42012-05-07 12:10:47 +0800843 .help = "dump guest memory to file",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200844 .mhandler.cmd_new = qmp_marshal_dump_guest_memory,
Wen Congyang783e9b42012-05-07 12:10:47 +0800845 },
846
847SQMP
848dump
849
850
851Dump guest memory to file. The file can be processed with crash or gdb.
852
853Arguments:
854
855- "paging": do paging to get guest's memory mapping (json-bool)
856- "protocol": destination file(started with "file:") or destination file
857 descriptor (started with "fd:") (json-string)
858- "begin": the starting physical address. It's optional, and should be specified
859 with length together (json-int)
860- "length": the memory size, in bytes. It's optional, and should be specified
861 with begin together (json-int)
qiaonuohanb53ccc32014-02-18 14:11:36 +0800862- "format": the format of guest memory dump. It's optional, and can be
863 elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
864 conflict with paging and filter, ie. begin and length (json-string)
Wen Congyang783e9b42012-05-07 12:10:47 +0800865
866Example:
867
868-> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
869<- { "return": {} }
870
871Notes:
872
873(1) All boolean arguments default to false
874
875EQMP
876
877 {
qiaonuohan7d6dc7f2014-02-18 14:11:38 +0800878 .name = "query-dump-guest-memory-capability",
879 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200880 .mhandler.cmd_new = qmp_marshal_query_dump_guest_memory_capability,
qiaonuohan7d6dc7f2014-02-18 14:11:38 +0800881 },
882
883SQMP
884query-dump-guest-memory-capability
885----------
886
887Show available formats for 'dump-guest-memory'
888
889Example:
890
891-> { "execute": "query-dump-guest-memory-capability" }
892<- { "return": { "formats":
893 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
894
895EQMP
896
Jason J. Herne7ee0c3e2015-06-26 14:03:16 -0400897#if defined TARGET_S390X
898 {
899 .name = "dump-skeys",
900 .args_type = "filename:F",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200901 .mhandler.cmd_new = qmp_marshal_dump_skeys,
Jason J. Herne7ee0c3e2015-06-26 14:03:16 -0400902 },
903#endif
904
905SQMP
906dump-skeys
907----------
908
909Save guest storage keys to file.
910
911Arguments:
912
913- "filename": file path (json-string)
914
915Example:
916
917-> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
918<- { "return": {} }
919
920EQMP
921
qiaonuohan7d6dc7f2014-02-18 14:11:38 +0800922 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300923 .name = "netdev_add",
924 .args_type = "netdev:O",
Luiz Capitulino928059a2012-04-18 17:34:15 -0300925 .mhandler.cmd_new = qmp_netdev_add,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300926 },
927
928SQMP
929netdev_add
930----------
931
932Add host network device.
933
934Arguments:
935
936- "type": the device type, "tap", "user", ... (json-string)
937- "id": the device's ID, must be unique (json-string)
938- device options
939
940Example:
941
Markus Armbrusterb8a98322015-09-16 13:06:26 +0200942-> { "execute": "netdev_add",
943 "arguments": { "type": "user", "id": "netdev1",
944 "dnssearch": "example.org" } }
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300945<- { "return": {} }
946
Markus Armbrusteraf347aa2013-02-22 18:31:51 +0100947Note: The supported device options are the same ones supported by the '-netdev'
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300948 command-line argument, which are listed in the '-help' output or QEMU's
949 manual
950
951EQMP
952
953 {
954 .name = "netdev_del",
955 .args_type = "id:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200956 .mhandler.cmd_new = qmp_marshal_netdev_del,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300957 },
958
959SQMP
960netdev_del
961----------
962
963Remove host network device.
964
965Arguments:
966
967- "id": the device's ID, must be unique (json-string)
968
969Example:
970
971-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
972<- { "return": {} }
973
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +0100974
975EQMP
976
977 {
Paolo Bonzinicff8b2c2013-12-20 23:21:10 +0100978 .name = "object-add",
979 .args_type = "qom-type:s,id:s,props:q?",
Markus Armbruster6eb39372015-09-16 13:06:25 +0200980 .mhandler.cmd_new = qmp_marshal_object_add,
Paolo Bonzinicff8b2c2013-12-20 23:21:10 +0100981 },
982
983SQMP
984object-add
985----------
986
987Create QOM object.
988
989Arguments:
990
991- "qom-type": the object's QOM type, i.e. the class name (json-string)
992- "id": the object's ID, must be unique (json-string)
993- "props": a dictionary of object property values (optional, json-dict)
994
995Example:
996
997-> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
998 "props": { "filename": "/dev/hwrng" } } }
999<- { "return": {} }
1000
1001EQMP
1002
1003 {
Paolo Bonziniab2d0532013-12-20 23:21:09 +01001004 .name = "object-del",
1005 .args_type = "id:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001006 .mhandler.cmd_new = qmp_marshal_object_del,
Paolo Bonziniab2d0532013-12-20 23:21:09 +01001007 },
1008
1009SQMP
1010object-del
1011----------
1012
1013Remove QOM object.
1014
1015Arguments:
1016
1017- "id": the object's ID (json-string)
1018
1019Example:
1020
1021-> { "execute": "object-del", "arguments": { "id": "rng1" } }
1022<- { "return": {} }
1023
1024
1025EQMP
1026
1027
1028 {
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +01001029 .name = "block_resize",
Benoît Canet3b1dbd12014-01-23 21:31:37 +01001030 .args_type = "device:s?,node-name:s?,size:o",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001031 .mhandler.cmd_new = qmp_marshal_block_resize,
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +01001032 },
1033
1034SQMP
1035block_resize
1036------------
1037
1038Resize a block image while a guest is running.
1039
1040Arguments:
1041
1042- "device": the device's ID, must be unique (json-string)
Benoît Canet3b1dbd12014-01-23 21:31:37 +01001043- "node-name": the node name in the block driver state graph (json-string)
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +01001044- "size": new size
1045
1046Example:
1047
1048-> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
1049<- { "return": {} }
1050
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001051EQMP
1052
1053 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01001054 .name = "block-stream",
Jeff Cody13d8cc52014-06-25 15:40:11 -04001055 .args_type = "device:B,base:s?,speed:o?,backing-file:s?,on-error:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001056 .mhandler.cmd_new = qmp_marshal_block_stream,
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00001057 },
1058
Stefan Hajnocziec683d62015-04-15 11:43:42 +01001059SQMP
1060block-stream
1061------------
1062
1063Copy data from a backing file into a block device.
1064
1065Arguments:
1066
1067- "device": The device's ID, must be unique (json-string)
1068- "base": The file name of the backing image above which copying starts
1069 (json-string, optional)
1070- "backing-file": The backing file string to write into the active layer. This
1071 filename is not validated.
1072
1073 If a pathname string is such that it cannot be resolved by
1074 QEMU, that means that subsequent QMP or HMP commands must use
1075 node-names for the image in question, as filename lookup
1076 methods will fail.
1077
1078 If not specified, QEMU will automatically determine the
1079 backing file string to use, or error out if there is no
1080 obvious choice. Care should be taken when specifying the
1081 string, to specify a valid filename or protocol.
1082 (json-string, optional) (Since 2.1)
1083- "speed": the maximum speed, in bytes per second (json-int, optional)
1084- "on-error": the action to take on an error (default 'report'). 'stop' and
1085 'enospc' can only be used if the block device supports io-status.
1086 (json-string, optional) (Since 2.1)
1087
1088Example:
1089
1090-> { "execute": "block-stream", "arguments": { "device": "virtio0",
1091 "base": "/tmp/master.qcow2" } }
1092<- { "return": {} }
1093
1094EQMP
1095
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00001096 {
Jeff Codyed61fc12012-09-27 13:29:16 -04001097 .name = "block-commit",
Jeff Cody54e26902014-06-25 15:40:10 -04001098 .args_type = "device:B,base:s?,top:s?,backing-file:s?,speed:o?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001099 .mhandler.cmd_new = qmp_marshal_block_commit,
Jeff Codyed61fc12012-09-27 13:29:16 -04001100 },
1101
Jeff Cody37222902014-01-24 09:02:37 -05001102SQMP
1103block-commit
1104------------
1105
1106Live commit of data from overlay image nodes into backing nodes - i.e., writes
1107data between 'top' and 'base' into 'base'.
1108
1109Arguments:
1110
1111- "device": The device's ID, must be unique (json-string)
1112- "base": The file name of the backing image to write data into.
1113 If not specified, this is the deepest backing image
1114 (json-string, optional)
1115- "top": The file name of the backing image within the image chain,
Jeff Cody7676e2c2014-06-30 15:14:15 +02001116 which contains the topmost data to be committed down. If
1117 not specified, this is the active layer. (json-string, optional)
Jeff Cody37222902014-01-24 09:02:37 -05001118
Jeff Cody54e26902014-06-25 15:40:10 -04001119- backing-file: The backing file string to write into the overlay
1120 image of 'top'. If 'top' is the active layer,
1121 specifying a backing file string is an error. This
1122 filename is not validated.
1123
1124 If a pathname string is such that it cannot be
1125 resolved by QEMU, that means that subsequent QMP or
1126 HMP commands must use node-names for the image in
1127 question, as filename lookup methods will fail.
1128
1129 If not specified, QEMU will automatically determine
1130 the backing file string to use, or error out if
1131 there is no obvious choice. Care should be taken
1132 when specifying the string, to specify a valid
1133 filename or protocol.
1134 (json-string, optional) (Since 2.1)
1135
Jeff Cody37222902014-01-24 09:02:37 -05001136 If top == base, that is an error.
1137 If top == active, the job will not be completed by itself,
1138 user needs to complete the job with the block-job-complete
1139 command after getting the ready event. (Since 2.0)
1140
1141 If the base image is smaller than top, then the base image
1142 will be resized to be the same size as top. If top is
1143 smaller than the base image, the base will not be
1144 truncated. If you want the base image size to match the
1145 size of the smaller top, you can safely truncate it
1146 yourself once the commit operation successfully completes.
1147 (json-string)
1148- "speed": the maximum speed, in bytes per second (json-int, optional)
1149
1150
1151Example:
1152
1153-> { "execute": "block-commit", "arguments": { "device": "virtio0",
1154 "top": "/tmp/snap1.qcow2" } }
1155<- { "return": {} }
1156
1157EQMP
1158
Jeff Codyed61fc12012-09-27 13:29:16 -04001159 {
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001160 .name = "drive-backup",
Stefan Hajnoczib53169e2013-06-26 14:11:57 +02001161 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
John Snowd58d8452015-04-17 19:49:58 -04001162 "bitmap:s?,on-source-error:s?,on-target-error:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001163 .mhandler.cmd_new = qmp_marshal_drive_backup,
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001164 },
1165
1166SQMP
1167drive-backup
1168------------
1169
1170Start a point-in-time copy of a block device to a new destination. The
1171status of ongoing drive-backup operations can be checked with
1172query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
1173The operation can be stopped before it has completed using the
1174block-job-cancel command.
1175
1176Arguments:
1177
1178- "device": the name of the device which should be copied.
1179 (json-string)
1180- "target": the target of the new image. If the file exists, or if it is a
1181 device, the existing file/device will be used as the new
1182 destination. If it does not exist, a new file will be created.
1183 (json-string)
1184- "format": the format of the new destination, default is to probe if 'mode' is
1185 'existing', else the format of the source
1186 (json-string, optional)
Stefan Hajnoczib53169e2013-06-26 14:11:57 +02001187- "sync": what parts of the disk image should be copied to the destination;
1188 possibilities include "full" for all the disk, "top" for only the sectors
John Snow4b80ab22015-06-04 20:20:34 -04001189 allocated in the topmost image, "incremental" for only the dirty sectors in
John Snowd58d8452015-04-17 19:49:58 -04001190 the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
John Snow4b80ab22015-06-04 20:20:34 -04001191- "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
1192 is "incremental", must NOT be present otherwise.
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001193- "mode": whether and how QEMU should create a new image
1194 (NewImageMode, optional, default 'absolute-paths')
1195- "speed": the maximum speed, in bytes per second (json-int, optional)
1196- "on-source-error": the action to take on an error on the source, default
1197 'report'. 'stop' and 'enospc' can only be used
1198 if the block device supports io-status.
1199 (BlockdevOnError, optional)
1200- "on-target-error": the action to take on an error on the target, default
1201 'report' (no limitations, since this applies to
1202 a different block device than device).
1203 (BlockdevOnError, optional)
1204
1205Example:
1206-> { "execute": "drive-backup", "arguments": { "device": "drive0",
Ian Mainfc5d3f82013-07-26 11:39:04 -07001207 "sync": "full",
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001208 "target": "backup.img" } }
1209<- { "return": {} }
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001210
1211EQMP
1212
1213 {
1214 .name = "blockdev-backup",
1215 .args_type = "sync:s,device:B,target:B,speed:i?,"
1216 "on-source-error:s?,on-target-error:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001217 .mhandler.cmd_new = qmp_marshal_blockdev_backup,
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001218 },
1219
1220SQMP
1221blockdev-backup
1222---------------
1223
1224The device version of drive-backup: this command takes an existing named device
1225as backup target.
1226
1227Arguments:
1228
1229- "device": the name of the device which should be copied.
1230 (json-string)
1231- "target": the name of the backup target device. (json-string)
1232- "sync": what parts of the disk image should be copied to the destination;
1233 possibilities include "full" for all the disk, "top" for only the
1234 sectors allocated in the topmost image, or "none" to only replicate
1235 new I/O (MirrorSyncMode).
1236- "speed": the maximum speed, in bytes per second (json-int, optional)
1237- "on-source-error": the action to take on an error on the source, default
1238 'report'. 'stop' and 'enospc' can only be used
1239 if the block device supports io-status.
1240 (BlockdevOnError, optional)
1241- "on-target-error": the action to take on an error on the target, default
1242 'report' (no limitations, since this applies to
1243 a different block device than device).
1244 (BlockdevOnError, optional)
1245
1246Example:
1247-> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
1248 "sync": "full",
1249 "target": "tgt-id" } }
1250<- { "return": {} }
1251
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001252EQMP
1253
1254 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01001255 .name = "block-job-set-speed",
Stefan Hajnoczi882ec7c2012-04-25 16:51:02 +01001256 .args_type = "device:B,speed:o",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001257 .mhandler.cmd_new = qmp_marshal_block_job_set_speed,
Stefan Hajnoczi2d47c6e2012-01-18 14:40:47 +00001258 },
1259
1260 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01001261 .name = "block-job-cancel",
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02001262 .args_type = "device:B,force:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001263 .mhandler.cmd_new = qmp_marshal_block_job_cancel,
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00001264 },
Jeff Codyc1864022012-02-28 15:54:07 -05001265 {
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02001266 .name = "block-job-pause",
1267 .args_type = "device:B",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001268 .mhandler.cmd_new = qmp_marshal_block_job_pause,
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02001269 },
1270 {
1271 .name = "block-job-resume",
1272 .args_type = "device:B",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001273 .mhandler.cmd_new = qmp_marshal_block_job_resume,
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02001274 },
1275 {
Paolo Bonziniaeae8832012-10-18 16:49:21 +02001276 .name = "block-job-complete",
1277 .args_type = "device:B",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001278 .mhandler.cmd_new = qmp_marshal_block_job_complete,
Paolo Bonziniaeae8832012-10-18 16:49:21 +02001279 },
1280 {
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001281 .name = "transaction",
John Snow94d16a62015-11-05 18:13:18 -05001282 .args_type = "actions:q,properties:q?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001283 .mhandler.cmd_new = qmp_marshal_transaction,
Jeff Codyc1864022012-02-28 15:54:07 -05001284 },
1285
1286SQMP
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001287transaction
1288-----------
Jeff Codyc1864022012-02-28 15:54:07 -05001289
Kashyap Chamarthya9105232015-10-02 14:12:34 +02001290Atomically operate on one or more block devices. Operations that are
1291currently supported:
1292
1293 - drive-backup
1294 - blockdev-backup
1295 - blockdev-snapshot-sync
1296 - blockdev-snapshot-internal-sync
1297 - abort
1298 - block-dirty-bitmap-add
1299 - block-dirty-bitmap-clear
1300
1301Refer to the qemu/qapi-schema.json file for minimum required QEMU
1302versions for these operations. A list of dictionaries is accepted,
1303that contains the actions to be performed. If there is any failure
1304performing any of the operations, all operations for the group are
1305abandoned.
Jeff Codyc1864022012-02-28 15:54:07 -05001306
Wenchao Xiabbe86012013-09-11 14:04:34 +08001307For external snapshots, the dictionary contains the device, the file to use for
1308the new snapshot, and the format. The default format, if not specified, is
1309qcow2.
Jeff Codyc1864022012-02-28 15:54:07 -05001310
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001311Each new snapshot defaults to being created by QEMU (wiping any
1312contents if the file already exists), but it is also possible to reuse
1313an externally-created file. In the latter case, you should ensure that
1314the new image file has the same contents as the current one; QEMU cannot
1315perform any meaningful check. Typically this is achieved by using the
1316current image file as the backing file for the new image.
1317
Wenchao Xiabbe86012013-09-11 14:04:34 +08001318On failure, the original disks pre-snapshot attempt will be used.
1319
1320For internal snapshots, the dictionary contains the device and the snapshot's
1321name. If an internal snapshot matching name already exists, the request will
1322be rejected. Only some image formats support it, for example, qcow2, rbd,
1323and sheepdog.
1324
1325On failure, qemu will try delete the newly created internal snapshot in the
1326transaction. When an I/O error occurs during deletion, the user needs to fix
1327it later with qemu-img or other command.
1328
Jeff Codyc1864022012-02-28 15:54:07 -05001329Arguments:
1330
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001331actions array:
Kashyap Chamarthya9105232015-10-02 14:12:34 +02001332 - "type": the operation to perform (json-string). Possible
1333 values: "drive-backup", "blockdev-backup",
1334 "blockdev-snapshot-sync",
1335 "blockdev-snapshot-internal-sync",
1336 "abort", "block-dirty-bitmap-add",
1337 "block-dirty-bitmap-clear"
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001338 - "data": a dictionary. The contents depend on the value
1339 of "type". When "type" is "blockdev-snapshot-sync":
1340 - "device": device name to snapshot (json-string)
Benoît Canet0901f672014-01-23 21:31:38 +01001341 - "node-name": graph node name to snapshot (json-string)
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001342 - "snapshot-file": name of new image file (json-string)
Benoît Canet0901f672014-01-23 21:31:38 +01001343 - "snapshot-node-name": graph node name of the new snapshot (json-string)
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001344 - "format": format of new image (json-string, optional)
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001345 - "mode": whether and how QEMU should create the snapshot file
1346 (NewImageMode, optional, default "absolute-paths")
Wenchao Xiabbe86012013-09-11 14:04:34 +08001347 When "type" is "blockdev-snapshot-internal-sync":
1348 - "device": device name to snapshot (json-string)
1349 - "name": name of the new snapshot (json-string)
Jeff Codyc1864022012-02-28 15:54:07 -05001350
1351Example:
1352
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001353-> { "execute": "transaction",
1354 "arguments": { "actions": [
Eric Blakecd0c5382014-05-06 09:39:03 -06001355 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001356 "snapshot-file": "/some/place/my-image",
1357 "format": "qcow2" } },
Eric Blakecd0c5382014-05-06 09:39:03 -06001358 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
Benoît Canet0901f672014-01-23 21:31:38 +01001359 "snapshot-file": "/some/place/my-image2",
1360 "snapshot-node-name": "node3432",
1361 "mode": "existing",
1362 "format": "qcow2" } },
Eric Blakecd0c5382014-05-06 09:39:03 -06001363 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001364 "snapshot-file": "/some/place/my-image2",
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001365 "mode": "existing",
Wenchao Xiabbe86012013-09-11 14:04:34 +08001366 "format": "qcow2" } },
Eric Blakecd0c5382014-05-06 09:39:03 -06001367 { "type": "blockdev-snapshot-internal-sync", "data" : {
Wenchao Xiabbe86012013-09-11 14:04:34 +08001368 "device": "ide-hd2",
1369 "name": "snapshot0" } } ] } }
Jeff Codyc1864022012-02-28 15:54:07 -05001370<- { "return": {} }
1371
1372EQMP
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00001373
1374 {
John Snow341ebc22015-04-17 19:49:52 -04001375 .name = "block-dirty-bitmap-add",
1376 .args_type = "node:B,name:s,granularity:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001377 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_add,
John Snow341ebc22015-04-17 19:49:52 -04001378 },
1379
1380SQMP
1381
1382block-dirty-bitmap-add
1383----------------------
1384Since 2.4
1385
1386Create a dirty bitmap with a name on the device, and start tracking the writes.
1387
1388Arguments:
1389
1390- "node": device/node on which to create dirty bitmap (json-string)
1391- "name": name of the new dirty bitmap (json-string)
1392- "granularity": granularity to track writes with (int, optional)
1393
1394Example:
1395
1396-> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
1397 "name": "bitmap0" } }
1398<- { "return": {} }
1399
1400EQMP
1401
1402 {
1403 .name = "block-dirty-bitmap-remove",
1404 .args_type = "node:B,name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001405 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_remove,
John Snow341ebc22015-04-17 19:49:52 -04001406 },
1407
1408SQMP
1409
1410block-dirty-bitmap-remove
1411-------------------------
1412Since 2.4
1413
1414Stop write tracking and remove the dirty bitmap that was created with
1415block-dirty-bitmap-add.
1416
1417Arguments:
1418
1419- "node": device/node on which to remove dirty bitmap (json-string)
1420- "name": name of the dirty bitmap to remove (json-string)
1421
1422Example:
1423
1424-> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
1425 "name": "bitmap0" } }
1426<- { "return": {} }
1427
1428EQMP
1429
1430 {
John Snowe74e6b72015-04-17 19:49:59 -04001431 .name = "block-dirty-bitmap-clear",
1432 .args_type = "node:B,name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001433 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_clear,
John Snowe74e6b72015-04-17 19:49:59 -04001434 },
1435
1436SQMP
1437
1438block-dirty-bitmap-clear
1439------------------------
1440Since 2.4
1441
1442Reset the dirty bitmap associated with a node so that an incremental backup
1443from this point in time forward will only backup clusters modified after this
1444clear operation.
1445
1446Arguments:
1447
1448- "node": device/node on which to remove dirty bitmap (json-string)
1449- "name": name of the dirty bitmap to remove (json-string)
1450
1451Example:
1452
1453-> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
1454 "name": "bitmap0" } }
1455<- { "return": {} }
1456
1457EQMP
1458
1459 {
Jes Sorensend967b2f2011-07-11 20:01:09 +02001460 .name = "blockdev-snapshot-sync",
Benoît Canet0901f672014-01-23 21:31:38 +01001461 .args_type = "device:s?,node-name:s?,snapshot-file:s,snapshot-node-name:s?,format:s?,mode:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001462 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot_sync,
Jes Sorensend967b2f2011-07-11 20:01:09 +02001463 },
1464
1465SQMP
1466blockdev-snapshot-sync
1467----------------------
1468
1469Synchronous snapshot of a block device. snapshot-file specifies the
1470target of the new image. If the file exists, or if it is a device, the
1471snapshot will be created in the existing file/device. If does not
1472exist, a new file will be created. format specifies the format of the
1473snapshot image, default is qcow2.
1474
1475Arguments:
1476
1477- "device": device name to snapshot (json-string)
Benoît Canet0901f672014-01-23 21:31:38 +01001478- "node-name": graph node name to snapshot (json-string)
Jes Sorensend967b2f2011-07-11 20:01:09 +02001479- "snapshot-file": name of new image file (json-string)
Benoît Canet0901f672014-01-23 21:31:38 +01001480- "snapshot-node-name": graph node name of the new snapshot (json-string)
Paolo Bonzini6cc2a412012-03-06 18:55:59 +01001481- "mode": whether and how QEMU should create the snapshot file
1482 (NewImageMode, optional, default "absolute-paths")
Jes Sorensend967b2f2011-07-11 20:01:09 +02001483- "format": format of new image (json-string, optional)
1484
1485Example:
1486
Luiz Capitulino7f3850c2011-10-10 17:30:08 -03001487-> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
1488 "snapshot-file":
1489 "/some/place/my-image",
1490 "format": "qcow2" } }
Jes Sorensend967b2f2011-07-11 20:01:09 +02001491<- { "return": {} }
1492
1493EQMP
1494
1495 {
Alberto Garcia43de7e22015-10-26 14:27:16 +02001496 .name = "blockdev-snapshot",
1497 .args_type = "node:s,overlay:s",
1498 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot,
1499 },
1500
1501SQMP
1502blockdev-snapshot
1503-----------------
1504Since 2.5
1505
1506Create a snapshot, by installing 'node' as the backing image of
1507'overlay'. Additionally, if 'node' is associated with a block
1508device, the block device changes to using 'overlay' as its new active
1509image.
1510
1511Arguments:
1512
1513- "node": device that will have a snapshot created (json-string)
1514- "overlay": device that will have 'node' as its backing image (json-string)
1515
1516Example:
1517
1518-> { "execute": "blockdev-add",
1519 "arguments": { "options": { "driver": "qcow2",
1520 "node-name": "node1534",
1521 "file": { "driver": "file",
1522 "filename": "hd1.qcow2" },
1523 "backing": "" } } }
1524
1525<- { "return": {} }
1526
1527-> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0",
1528 "overlay": "node1534" } }
1529<- { "return": {} }
1530
1531EQMP
1532
1533 {
Wenchao Xiaf323bc92013-09-11 14:04:35 +08001534 .name = "blockdev-snapshot-internal-sync",
1535 .args_type = "device:B,name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001536 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot_internal_sync,
Wenchao Xiaf323bc92013-09-11 14:04:35 +08001537 },
1538
1539SQMP
1540blockdev-snapshot-internal-sync
1541-------------------------------
1542
1543Synchronously take an internal snapshot of a block device when the format of
1544image used supports it. If the name is an empty string, or a snapshot with
1545name already exists, the operation will fail.
1546
1547Arguments:
1548
1549- "device": device name to snapshot (json-string)
1550- "name": name of the new snapshot (json-string)
1551
1552Example:
1553
1554-> { "execute": "blockdev-snapshot-internal-sync",
1555 "arguments": { "device": "ide-hd0",
1556 "name": "snapshot0" }
1557 }
1558<- { "return": {} }
1559
1560EQMP
1561
1562 {
Wenchao Xia44e3e052013-09-11 14:04:36 +08001563 .name = "blockdev-snapshot-delete-internal-sync",
1564 .args_type = "device:B,id:s?,name:s?",
1565 .mhandler.cmd_new =
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001566 qmp_marshal_blockdev_snapshot_delete_internal_sync,
Wenchao Xia44e3e052013-09-11 14:04:36 +08001567 },
1568
1569SQMP
1570blockdev-snapshot-delete-internal-sync
1571--------------------------------------
1572
1573Synchronously delete an internal snapshot of a block device when the format of
1574image used supports it. The snapshot is identified by name or id or both. One
1575of name or id is required. If the snapshot is not found, the operation will
1576fail.
1577
1578Arguments:
1579
1580- "device": device name (json-string)
1581- "id": ID of the snapshot (json-string, optional)
1582- "name": name of the snapshot (json-string, optional)
1583
1584Example:
1585
1586-> { "execute": "blockdev-snapshot-delete-internal-sync",
1587 "arguments": { "device": "ide-hd0",
1588 "name": "snapshot0" }
1589 }
1590<- { "return": {
1591 "id": "1",
1592 "name": "snapshot0",
1593 "vm-state-size": 0,
1594 "date-sec": 1000012,
1595 "date-nsec": 10,
1596 "vm-clock-sec": 100,
1597 "vm-clock-nsec": 20
1598 }
1599 }
1600
1601EQMP
1602
1603 {
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001604 .name = "drive-mirror",
Paolo Bonzinib952b552012-10-18 16:49:28 +02001605 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
Benoît Canet09158f02014-06-27 18:25:25 +02001606 "node-name:s?,replaces:s?,"
Paolo Bonzinieee13df2013-01-21 17:09:46 +01001607 "on-source-error:s?,on-target-error:s?,"
Fam Zheng0fc9f8e2015-06-08 13:56:08 +08001608 "unmap:b?,"
Paolo Bonzini08e4ed62013-01-22 09:03:13 +01001609 "granularity:i?,buf-size:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001610 .mhandler.cmd_new = qmp_marshal_drive_mirror,
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001611 },
1612
1613SQMP
1614drive-mirror
1615------------
1616
1617Start mirroring a block device's writes to a new destination. target
1618specifies the target of the new image. If the file exists, or if it is
1619a device, it will be used as the new destination for writes. If it does not
1620exist, a new file will be created. format specifies the format of the
1621mirror image, default is to probe if mode='existing', else the format
1622of the source.
1623
1624Arguments:
1625
1626- "device": device name to operate on (json-string)
1627- "target": name of new image file (json-string)
1628- "format": format of new image (json-string, optional)
Benoît Canet4c828dc2014-06-16 12:00:55 +02001629- "node-name": the name of the new block driver state in the node graph
1630 (json-string, optional)
Benoît Canet09158f02014-06-27 18:25:25 +02001631- "replaces": the block driver node name to replace when finished
1632 (json-string, optional)
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001633- "mode": how an image file should be created into the target
1634 file/device (NewImageMode, optional, default 'absolute-paths')
1635- "speed": maximum speed of the streaming job, in bytes per second
1636 (json-int)
Paolo Bonzinieee13df2013-01-21 17:09:46 +01001637- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
Fam Zhengdf925622015-12-24 12:45:05 +08001638- "buf-size": maximum amount of data in flight from source to target, in bytes
Paolo Bonzini08e4ed62013-01-22 09:03:13 +01001639 (json-int, default 10M)
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001640- "sync": what parts of the disk image should be copied to the destination;
1641 possibilities include "full" for all the disk, "top" for only the sectors
1642 allocated in the topmost image, or "none" to only replicate new I/O
1643 (MirrorSyncMode).
Paolo Bonzinib952b552012-10-18 16:49:28 +02001644- "on-source-error": the action to take on an error on the source
1645 (BlockdevOnError, default 'report')
1646- "on-target-error": the action to take on an error on the target
1647 (BlockdevOnError, default 'report')
Fam Zheng0fc9f8e2015-06-08 13:56:08 +08001648- "unmap": whether the target sectors should be discarded where source has only
1649 zeroes. (json-bool, optional, default true)
Paolo Bonzinib952b552012-10-18 16:49:28 +02001650
Paolo Bonzinieee13df2013-01-21 17:09:46 +01001651The default value of the granularity is the image cluster size clamped
1652between 4096 and 65536, if the image format defines one. If the format
1653does not define a cluster size, the default value of the granularity
1654is 65536.
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001655
1656
1657Example:
1658
1659-> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
1660 "target": "/some/place/my-image",
1661 "sync": "full",
1662 "format": "qcow2" } }
1663<- { "return": {} }
1664
1665EQMP
1666
1667 {
Fam Zhengdf925622015-12-24 12:45:05 +08001668 .name = "blockdev-mirror",
1669 .args_type = "sync:s,device:B,target:B,replaces:s?,speed:i?,"
1670 "on-source-error:s?,on-target-error:s?,"
1671 "granularity:i?,buf-size:i?",
1672 .mhandler.cmd_new = qmp_marshal_blockdev_mirror,
1673 },
1674
1675SQMP
1676blockdev-mirror
1677------------
1678
1679Start mirroring a block device's writes to another block device. target
1680specifies the target of mirror operation.
1681
1682Arguments:
1683
1684- "device": device name to operate on (json-string)
1685- "target": device name to mirror to (json-string)
1686- "replaces": the block driver node name to replace when finished
1687 (json-string, optional)
1688- "speed": maximum speed of the streaming job, in bytes per second
1689 (json-int)
1690- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1691- "buf_size": maximum amount of data in flight from source to target, in bytes
1692 (json-int, default 10M)
1693- "sync": what parts of the disk image should be copied to the destination;
1694 possibilities include "full" for all the disk, "top" for only the sectors
1695 allocated in the topmost image, or "none" to only replicate new I/O
1696 (MirrorSyncMode).
1697- "on-source-error": the action to take on an error on the source
1698 (BlockdevOnError, default 'report')
1699- "on-target-error": the action to take on an error on the target
1700 (BlockdevOnError, default 'report')
1701
1702The default value of the granularity is the image cluster size clamped
1703between 4096 and 65536, if the image format defines one. If the format
1704does not define a cluster size, the default value of the granularity
1705is 65536.
1706
1707Example:
1708
1709-> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
1710 "target": "target0",
1711 "sync": "full" } }
1712<- { "return": {} }
1713
1714EQMP
1715 {
Jeff Codyfa40e652014-07-01 09:52:16 +02001716 .name = "change-backing-file",
1717 .args_type = "device:s,image-node-name:s,backing-file:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001718 .mhandler.cmd_new = qmp_marshal_change_backing_file,
Jeff Codyfa40e652014-07-01 09:52:16 +02001719 },
1720
1721SQMP
1722change-backing-file
1723-------------------
1724Since: 2.1
1725
1726Change the backing file in the image file metadata. This does not cause
1727QEMU to reopen the image file to reparse the backing filename (it may,
1728however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1729if needed). The new backing file string is written into the image file
1730metadata, and the QEMU internal strings are updated.
1731
1732Arguments:
1733
1734- "image-node-name": The name of the block driver state node of the
1735 image to modify. The "device" is argument is used to
1736 verify "image-node-name" is in the chain described by
1737 "device".
1738 (json-string, optional)
1739
1740- "device": The name of the device.
1741 (json-string)
1742
1743- "backing-file": The string to write as the backing file. This string is
1744 not validated, so care should be taken when specifying
1745 the string or the image chain may not be able to be
1746 reopened again.
1747 (json-string)
1748
1749Returns: Nothing on success
1750 If "device" does not exist or cannot be determined, DeviceNotFound
1751
1752EQMP
1753
1754 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001755 .name = "balloon",
1756 .args_type = "value:M",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001757 .mhandler.cmd_new = qmp_marshal_balloon,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001758 },
1759
1760SQMP
1761balloon
1762-------
1763
1764Request VM to change its memory allocation (in bytes).
1765
1766Arguments:
1767
1768- "value": New memory allocation (json-int)
1769
1770Example:
1771
1772-> { "execute": "balloon", "arguments": { "value": 536870912 } }
1773<- { "return": {} }
1774
1775EQMP
1776
1777 {
1778 .name = "set_link",
1779 .args_type = "name:s,up:b",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001780 .mhandler.cmd_new = qmp_marshal_set_link,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001781 },
1782
1783SQMP
1784set_link
1785--------
1786
1787Change the link status of a network adapter.
1788
1789Arguments:
1790
1791- "name": network device name (json-string)
1792- "up": status is up (json-bool)
1793
1794Example:
1795
1796-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1797<- { "return": {} }
1798
1799EQMP
1800
1801 {
1802 .name = "getfd",
1803 .args_type = "fdname:s",
1804 .params = "getfd name",
1805 .help = "receive a file descriptor via SCM rights and assign it a name",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001806 .mhandler.cmd_new = qmp_marshal_getfd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001807 },
1808
1809SQMP
1810getfd
1811-----
1812
1813Receive a file descriptor via SCM rights and assign it a name.
1814
1815Arguments:
1816
1817- "fdname": file descriptor name (json-string)
1818
1819Example:
1820
1821-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1822<- { "return": {} }
1823
Corey Bryant208c9d12012-06-22 14:36:09 -04001824Notes:
1825
1826(1) If the name specified by the "fdname" argument already exists,
1827 the file descriptor assigned to it will be closed and replaced
1828 by the received file descriptor.
1829(2) The 'closefd' command can be used to explicitly close the file
1830 descriptor when it is no longer needed.
1831
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001832EQMP
1833
1834 {
1835 .name = "closefd",
1836 .args_type = "fdname:s",
1837 .params = "closefd name",
1838 .help = "close a file descriptor previously passed via SCM rights",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001839 .mhandler.cmd_new = qmp_marshal_closefd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001840 },
1841
1842SQMP
1843closefd
1844-------
1845
1846Close a file descriptor previously passed via SCM rights.
1847
1848Arguments:
1849
1850- "fdname": file descriptor name (json-string)
1851
1852Example:
1853
1854-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1855<- { "return": {} }
1856
1857EQMP
1858
Corey Bryantba1c0482012-08-14 16:43:43 -04001859 {
1860 .name = "add-fd",
1861 .args_type = "fdset-id:i?,opaque:s?",
1862 .params = "add-fd fdset-id opaque",
1863 .help = "Add a file descriptor, that was passed via SCM rights, to an fd set",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001864 .mhandler.cmd_new = qmp_marshal_add_fd,
Corey Bryantba1c0482012-08-14 16:43:43 -04001865 },
1866
1867SQMP
1868add-fd
1869-------
1870
1871Add a file descriptor, that was passed via SCM rights, to an fd set.
1872
1873Arguments:
1874
1875- "fdset-id": The ID of the fd set to add the file descriptor to.
1876 (json-int, optional)
1877- "opaque": A free-form string that can be used to describe the fd.
1878 (json-string, optional)
1879
1880Return a json-object with the following information:
1881
1882- "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1883- "fd": The file descriptor that was received via SCM rights and added to the
1884 fd set. (json-int)
1885
1886Example:
1887
1888-> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1889<- { "return": { "fdset-id": 1, "fd": 3 } }
1890
1891Notes:
1892
1893(1) The list of fd sets is shared by all monitor connections.
1894(2) If "fdset-id" is not specified, a new fd set will be created.
1895
1896EQMP
1897
1898 {
1899 .name = "remove-fd",
1900 .args_type = "fdset-id:i,fd:i?",
1901 .params = "remove-fd fdset-id fd",
1902 .help = "Remove a file descriptor from an fd set",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001903 .mhandler.cmd_new = qmp_marshal_remove_fd,
Corey Bryantba1c0482012-08-14 16:43:43 -04001904 },
1905
1906SQMP
1907remove-fd
1908---------
1909
1910Remove a file descriptor from an fd set.
1911
1912Arguments:
1913
1914- "fdset-id": The ID of the fd set that the file descriptor belongs to.
1915 (json-int)
1916- "fd": The file descriptor that is to be removed. (json-int, optional)
1917
1918Example:
1919
1920-> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1921<- { "return": {} }
1922
1923Notes:
1924
1925(1) The list of fd sets is shared by all monitor connections.
1926(2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1927 removed.
1928
1929EQMP
1930
1931 {
1932 .name = "query-fdsets",
1933 .args_type = "",
1934 .help = "Return information describing all fd sets",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001935 .mhandler.cmd_new = qmp_marshal_query_fdsets,
Corey Bryantba1c0482012-08-14 16:43:43 -04001936 },
1937
1938SQMP
1939query-fdsets
1940-------------
1941
1942Return information describing all fd sets.
1943
1944Arguments: None
1945
1946Example:
1947
1948-> { "execute": "query-fdsets" }
1949<- { "return": [
1950 {
1951 "fds": [
1952 {
1953 "fd": 30,
1954 "opaque": "rdonly:/path/to/file"
1955 },
1956 {
1957 "fd": 24,
1958 "opaque": "rdwr:/path/to/file"
1959 }
1960 ],
1961 "fdset-id": 1
1962 },
1963 {
1964 "fds": [
1965 {
1966 "fd": 28
1967 },
1968 {
1969 "fd": 29
1970 }
1971 ],
1972 "fdset-id": 0
1973 }
1974 ]
1975 }
1976
1977Note: The list of fd sets is shared by all monitor connections.
1978
1979EQMP
1980
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001981 {
1982 .name = "block_passwd",
Benoît Canet12d3ba82014-01-23 21:31:35 +01001983 .args_type = "device:s?,node-name:s?,password:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001984 .mhandler.cmd_new = qmp_marshal_block_passwd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001985 },
1986
1987SQMP
1988block_passwd
1989------------
1990
1991Set the password of encrypted block devices.
1992
1993Arguments:
1994
1995- "device": device name (json-string)
Benoît Canet12d3ba82014-01-23 21:31:35 +01001996- "node-name": name in the block driver state graph (json-string)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001997- "password": password (json-string)
1998
1999Example:
2000
2001-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
2002 "password": "12345" } }
2003<- { "return": {} }
2004
2005EQMP
2006
2007 {
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002008 .name = "block_set_io_throttle",
Alberto Garcia76f4afb2015-06-08 18:17:44 +02002009 .args_type = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l,bps_max:l?,bps_rd_max:l?,bps_wr_max:l?,iops_max:l?,iops_rd_max:l?,iops_wr_max:l?,iops_size:l?,group:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002010 .mhandler.cmd_new = qmp_marshal_block_set_io_throttle,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002011 },
2012
2013SQMP
2014block_set_io_throttle
2015------------
2016
2017Change I/O throttle limits for a block drive.
2018
2019Arguments:
2020
2021- "device": device name (json-string)
Eric Blake586b5462013-08-30 14:44:11 -06002022- "bps": total throughput limit in bytes per second (json-int)
2023- "bps_rd": read throughput limit in bytes per second (json-int)
2024- "bps_wr": write throughput limit in bytes per second (json-int)
2025- "iops": total I/O operations per second (json-int)
2026- "iops_rd": read I/O operations per second (json-int)
2027- "iops_wr": write I/O operations per second (json-int)
Benoît Canet3e9fab62013-09-02 14:14:40 +02002028- "bps_max": total max in bytes (json-int)
2029- "bps_rd_max": read max in bytes (json-int)
2030- "bps_wr_max": write max in bytes (json-int)
2031- "iops_max": total I/O operations max (json-int)
2032- "iops_rd_max": read I/O operations max (json-int)
2033- "iops_wr_max": write I/O operations max (json-int)
Benoît Canet2024c1d2013-09-02 14:14:41 +02002034- "iops_size": I/O size in bytes when limiting (json-int)
Alberto Garcia76f4afb2015-06-08 18:17:44 +02002035- "group": throttle group name (json-string)
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002036
2037Example:
2038
2039-> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
Eric Blake586b5462013-08-30 14:44:11 -06002040 "bps": 1000000,
2041 "bps_rd": 0,
2042 "bps_wr": 0,
2043 "iops": 0,
2044 "iops_rd": 0,
Benoît Canet3e9fab62013-09-02 14:14:40 +02002045 "iops_wr": 0,
2046 "bps_max": 8000000,
2047 "bps_rd_max": 0,
2048 "bps_wr_max": 0,
2049 "iops_max": 0,
2050 "iops_rd_max": 0,
Benoît Canet2024c1d2013-09-02 14:14:41 +02002051 "iops_wr_max": 0,
2052 "iops_size": 0 } }
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002053<- { "return": {} }
2054
2055EQMP
2056
2057 {
Gerd Hoffmann75721502010-10-07 12:22:54 +02002058 .name = "set_password",
2059 .args_type = "protocol:s,password:s,connected:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002060 .mhandler.cmd_new = qmp_marshal_set_password,
Gerd Hoffmann75721502010-10-07 12:22:54 +02002061 },
2062
2063SQMP
2064set_password
2065------------
2066
2067Set the password for vnc/spice protocols.
2068
2069Arguments:
2070
2071- "protocol": protocol name (json-string)
2072- "password": password (json-string)
Alberto Garcia3599d462015-02-26 16:35:07 +02002073- "connected": [ keep | disconnect | fail ] (json-string, optional)
Gerd Hoffmann75721502010-10-07 12:22:54 +02002074
2075Example:
2076
2077-> { "execute": "set_password", "arguments": { "protocol": "vnc",
2078 "password": "secret" } }
2079<- { "return": {} }
2080
2081EQMP
2082
2083 {
2084 .name = "expire_password",
2085 .args_type = "protocol:s,time:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002086 .mhandler.cmd_new = qmp_marshal_expire_password,
Gerd Hoffmann75721502010-10-07 12:22:54 +02002087 },
2088
2089SQMP
2090expire_password
2091---------------
2092
2093Set the password expire time for vnc/spice protocols.
2094
2095Arguments:
2096
2097- "protocol": protocol name (json-string)
2098- "time": [ now | never | +secs | secs ] (json-string)
2099
2100Example:
2101
2102-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
2103 "time": "+60" } }
2104<- { "return": {} }
2105
2106EQMP
2107
2108 {
Daniel P. Berrange13661082011-06-23 13:31:42 +01002109 .name = "add_client",
Daniel P. Berrangef1f5f402012-02-13 13:43:08 +00002110 .args_type = "protocol:s,fdname:s,skipauth:b?,tls:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002111 .mhandler.cmd_new = qmp_marshal_add_client,
Daniel P. Berrange13661082011-06-23 13:31:42 +01002112 },
2113
2114SQMP
2115add_client
2116----------
2117
2118Add a graphics client
2119
2120Arguments:
2121
2122- "protocol": protocol name (json-string)
2123- "fdname": file descriptor name (json-string)
Daniel P. Berrangef1f5f402012-02-13 13:43:08 +00002124- "skipauth": whether to skip authentication (json-bool, optional)
2125- "tls": whether to perform TLS (json-bool, optional)
Daniel P. Berrange13661082011-06-23 13:31:42 +01002126
2127Example:
2128
2129-> { "execute": "add_client", "arguments": { "protocol": "vnc",
2130 "fdname": "myclient" } }
2131<- { "return": {} }
2132
2133EQMP
2134 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002135 .name = "qmp_capabilities",
2136 .args_type = "",
2137 .params = "",
2138 .help = "enable QMP capabilities",
Markus Armbruster485febc2015-03-13 17:25:50 +01002139 .mhandler.cmd_new = qmp_capabilities,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002140 },
2141
2142SQMP
2143qmp_capabilities
2144----------------
2145
2146Enable QMP capabilities.
2147
2148Arguments: None.
2149
2150Example:
2151
2152-> { "execute": "qmp_capabilities" }
2153<- { "return": {} }
2154
2155Note: This command must be issued before issuing any other command.
2156
Luiz Capitulino0268d972010-10-22 10:08:02 -02002157EQMP
2158
2159 {
2160 .name = "human-monitor-command",
2161 .args_type = "command-line:s,cpu-index:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002162 .mhandler.cmd_new = qmp_marshal_human_monitor_command,
Luiz Capitulino0268d972010-10-22 10:08:02 -02002163 },
2164
2165SQMP
2166human-monitor-command
2167---------------------
2168
2169Execute a Human Monitor command.
2170
2171Arguments:
2172
2173- command-line: the command name and its arguments, just like the
2174 Human Monitor's shell (json-string)
2175- cpu-index: select the CPU number to be used by commands which access CPU
2176 data, like 'info registers'. The Monitor selects CPU 0 if this
2177 argument is not provided (json-int, optional)
2178
2179Example:
2180
2181-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
2182<- { "return": "kvm support: enabled\r\n" }
2183
2184Notes:
2185
2186(1) The Human Monitor is NOT an stable interface, this means that command
2187 names, arguments and responses can change or be removed at ANY time.
2188 Applications that rely on long term stability guarantees should NOT
2189 use this command
2190
2191(2) Limitations:
2192
2193 o This command is stateless, this means that commands that depend
2194 on state information (such as getfd) might not work
2195
2196 o Commands that prompt the user for data (eg. 'cont' when the block
2197 device is encrypted) don't currently work
2198
Luiz Capitulino82a56f02010-09-13 12:26:00 -030021993. Query Commands
2200=================
2201
2202HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
2203HXCOMM this! We will possibly move query commands definitions inside those
2204HXCOMM sections, just like regular commands.
2205
2206EQMP
2207
2208SQMP
2209query-version
2210-------------
2211
2212Show QEMU version.
2213
2214Return a json-object with the following information:
2215
2216- "qemu": A json-object containing three integer values:
2217 - "major": QEMU's major version (json-int)
2218 - "minor": QEMU's minor version (json-int)
2219 - "micro": QEMU's micro version (json-int)
2220- "package": package's version (json-string)
2221
2222Example:
2223
2224-> { "execute": "query-version" }
2225<- {
2226 "return":{
2227 "qemu":{
2228 "major":0,
2229 "minor":11,
2230 "micro":5
2231 },
2232 "package":""
2233 }
2234 }
2235
2236EQMP
2237
Luiz Capitulinob9c15f12011-08-26 17:38:13 -03002238 {
2239 .name = "query-version",
2240 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002241 .mhandler.cmd_new = qmp_marshal_query_version,
Luiz Capitulinob9c15f12011-08-26 17:38:13 -03002242 },
2243
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002244SQMP
2245query-commands
2246--------------
2247
2248List QMP available commands.
2249
2250Each command is represented by a json-object, the returned value is a json-array
2251of all commands.
2252
2253Each json-object contain:
2254
2255- "name": command's name (json-string)
2256
2257Example:
2258
2259-> { "execute": "query-commands" }
2260<- {
2261 "return":[
2262 {
2263 "name":"query-balloon"
2264 },
2265 {
2266 "name":"system_powerdown"
2267 }
2268 ]
2269 }
2270
2271Note: This example has been shortened as the real response is too long.
2272
2273EQMP
2274
Luiz Capitulinoaa9b79b2011-09-21 14:31:51 -03002275 {
2276 .name = "query-commands",
2277 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002278 .mhandler.cmd_new = qmp_marshal_query_commands,
Luiz Capitulinoaa9b79b2011-09-21 14:31:51 -03002279 },
2280
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002281SQMP
Daniel P. Berrange48608532012-05-21 17:59:51 +01002282query-events
2283--------------
2284
2285List QMP available events.
2286
2287Each event is represented by a json-object, the returned value is a json-array
2288of all events.
2289
2290Each json-object contains:
2291
2292- "name": event's name (json-string)
2293
2294Example:
2295
2296-> { "execute": "query-events" }
2297<- {
2298 "return":[
2299 {
2300 "name":"SHUTDOWN"
2301 },
2302 {
2303 "name":"RESET"
2304 }
2305 ]
2306 }
2307
2308Note: This example has been shortened as the real response is too long.
2309
2310EQMP
2311
2312 {
2313 .name = "query-events",
2314 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002315 .mhandler.cmd_new = qmp_marshal_query_events,
Daniel P. Berrange48608532012-05-21 17:59:51 +01002316 },
2317
2318SQMP
Markus Armbruster39a18152015-09-16 13:06:28 +02002319query-qmp-schema
2320----------------
2321
2322Return the QMP wire schema. The returned value is a json-array of
2323named schema entities. Entities are commands, events and various
2324types. See docs/qapi-code-gen.txt for information on their structure
2325and intended use.
2326
2327EQMP
2328
2329 {
2330 .name = "query-qmp-schema",
2331 .args_type = "",
2332 .mhandler.cmd_new = qmp_query_qmp_schema,
2333 },
2334
2335SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002336query-chardev
2337-------------
2338
2339Each device is represented by a json-object. The returned value is a json-array
2340of all devices.
2341
2342Each json-object contain the following:
2343
2344- "label": device's label (json-string)
2345- "filename": device's file (json-string)
Laszlo Ersek32a97ea2014-06-26 17:50:03 +02002346- "frontend-open": open/closed state of the frontend device attached to this
2347 backend (json-bool)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002348
2349Example:
2350
2351-> { "execute": "query-chardev" }
2352<- {
Laszlo Ersek32a97ea2014-06-26 17:50:03 +02002353 "return": [
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002354 {
Laszlo Ersek32a97ea2014-06-26 17:50:03 +02002355 "label": "charchannel0",
2356 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
2357 "frontend-open": false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002358 },
2359 {
Laszlo Ersek32a97ea2014-06-26 17:50:03 +02002360 "label": "charmonitor",
2361 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
2362 "frontend-open": true
2363 },
2364 {
2365 "label": "charserial0",
2366 "filename": "pty:/dev/pts/2",
2367 "frontend-open": true
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002368 }
2369 ]
2370 }
2371
2372EQMP
2373
Luiz Capitulinoc5a415a2011-09-14 16:05:49 -03002374 {
2375 .name = "query-chardev",
2376 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002377 .mhandler.cmd_new = qmp_marshal_query_chardev,
Luiz Capitulinoc5a415a2011-09-14 16:05:49 -03002378 },
2379
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002380SQMP
Martin Kletzander77d1c3c2014-02-01 12:52:42 +01002381query-chardev-backends
2382-------------
2383
2384List available character device backends.
2385
2386Each backend is represented by a json-object, the returned value is a json-array
2387of all backends.
2388
2389Each json-object contains:
2390
2391- "name": backend name (json-string)
2392
2393Example:
2394
2395-> { "execute": "query-chardev-backends" }
2396<- {
2397 "return":[
2398 {
2399 "name":"udp"
2400 },
2401 {
2402 "name":"tcp"
2403 },
2404 {
2405 "name":"unix"
2406 },
2407 {
2408 "name":"spiceport"
2409 }
2410 ]
2411 }
2412
2413EQMP
2414
2415 {
2416 .name = "query-chardev-backends",
2417 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002418 .mhandler.cmd_new = qmp_marshal_query_chardev_backends,
Martin Kletzander77d1c3c2014-02-01 12:52:42 +01002419 },
2420
2421SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002422query-block
2423-----------
2424
2425Show the block devices.
2426
2427Each block device information is stored in a json-object and the returned value
2428is a json-array of all devices.
2429
2430Each json-object contain the following:
2431
2432- "device": device name (json-string)
2433- "type": device type (json-string)
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002434 - deprecated, retained for backward compatibility
2435 - Possible values: "unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002436- "removable": true if the device is removable, false otherwise (json-bool)
2437- "locked": true if the device is locked, false otherwise (json-bool)
Michal Privoznik99f42802013-01-29 17:58:41 +01002438- "tray_open": only present if removable, true if the device has a tray,
Markus Armbrustere4def802011-09-06 18:58:53 +02002439 and it is open (json-bool)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002440- "inserted": only present if the device is inserted, it is a json-object
2441 containing the following:
2442 - "file": device file name (json-string)
2443 - "ro": true if read-only, false otherwise (json-bool)
2444 - "drv": driver format name (json-string)
Stefan Hajnoczi550830f2014-09-16 15:24:24 +01002445 - Possible values: "blkdebug", "bochs", "cloop", "dmg",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002446 "file", "file", "ftp", "ftps", "host_cdrom",
Markus Armbruster92a539d2015-03-17 17:02:20 +01002447 "host_device", "http", "https",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002448 "nbd", "parallels", "qcow", "qcow2", "raw",
2449 "tftp", "vdi", "vmdk", "vpc", "vvfat"
2450 - "backing_file": backing file name (json-string, optional)
Benoît Canet2e3e3312012-08-02 10:22:48 +02002451 - "backing_file_depth": number of files in the backing file chain (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002452 - "encrypted": true if encrypted, false otherwise (json-bool)
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002453 - "bps": limit total bytes per second (json-int)
2454 - "bps_rd": limit read bytes per second (json-int)
2455 - "bps_wr": limit write bytes per second (json-int)
2456 - "iops": limit total I/O operations per second (json-int)
2457 - "iops_rd": limit read operations per second (json-int)
2458 - "iops_wr": limit write operations per second (json-int)
Benoît Canet3e9fab62013-09-02 14:14:40 +02002459 - "bps_max": total max in bytes (json-int)
2460 - "bps_rd_max": read max in bytes (json-int)
2461 - "bps_wr_max": write max in bytes (json-int)
2462 - "iops_max": total I/O operations max (json-int)
2463 - "iops_rd_max": read I/O operations max (json-int)
2464 - "iops_wr_max": write I/O operations max (json-int)
Benoît Canet2024c1d2013-09-02 14:14:41 +02002465 - "iops_size": I/O size when limiting by iops (json-int)
Peter Lieven465bee12014-05-18 00:58:19 +02002466 - "detect_zeroes": detect and optimize zero writing (json-string)
2467 - Possible values: "off", "on", "unmap"
Francesco Romanie2462112015-01-12 14:11:13 +01002468 - "write_threshold": write offset threshold in bytes, a event will be
2469 emitted if crossed. Zero if disabled (json-int)
Wenchao Xia553a7e82013-06-06 12:27:59 +08002470 - "image": the detail of the image, it is a json-object containing
2471 the following:
2472 - "filename": image file name (json-string)
2473 - "format": image format (json-string)
2474 - "virtual-size": image capacity in bytes (json-int)
2475 - "dirty-flag": true if image is not cleanly closed, not present
2476 means clean (json-bool, optional)
2477 - "actual-size": actual size on disk in bytes of the image, not
2478 present when image does not support thin
2479 provision (json-int, optional)
2480 - "cluster-size": size of a cluster in bytes, not present if image
2481 format does not support it (json-int, optional)
2482 - "encrypted": true if the image is encrypted, not present means
2483 false or the image format does not support
2484 encryption (json-bool, optional)
2485 - "backing_file": backing file name, not present means no backing
2486 file is used or the image format does not
2487 support backing file chain
2488 (json-string, optional)
2489 - "full-backing-filename": full path of the backing file, not
2490 present if it equals backing_file or no
2491 backing file is used
2492 (json-string, optional)
2493 - "backing-filename-format": the format of the backing file, not
2494 present means unknown or no backing
2495 file (json-string, optional)
2496 - "snapshots": the internal snapshot info, it is an optional list
2497 of json-object containing the following:
2498 - "id": unique snapshot id (json-string)
2499 - "name": snapshot name (json-string)
2500 - "vm-state-size": size of the VM state in bytes (json-int)
2501 - "date-sec": UTC date of the snapshot in seconds (json-int)
2502 - "date-nsec": fractional part in nanoseconds to be used with
Eric Blake586b5462013-08-30 14:44:11 -06002503 date-sec (json-int)
Wenchao Xia553a7e82013-06-06 12:27:59 +08002504 - "vm-clock-sec": VM clock relative to boot in seconds
2505 (json-int)
2506 - "vm-clock-nsec": fractional part in nanoseconds to be used
2507 with vm-clock-sec (json-int)
2508 - "backing-image": the detail of the backing image, it is an
2509 optional json-object only present when a
2510 backing image present for this image
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002511
Luiz Capitulinof04ef602011-09-26 17:43:54 -03002512- "io-status": I/O operation status, only present if the device supports it
2513 and the VM is configured to stop on errors. It's always reset
2514 to "ok" when the "cont" command is issued (json_string, optional)
2515 - Possible values: "ok", "failed", "nospace"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002516
2517Example:
2518
2519-> { "execute": "query-block" }
2520<- {
2521 "return":[
2522 {
Luiz Capitulinof04ef602011-09-26 17:43:54 -03002523 "io-status": "ok",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002524 "device":"ide0-hd0",
2525 "locked":false,
2526 "removable":false,
2527 "inserted":{
2528 "ro":false,
2529 "drv":"qcow2",
2530 "encrypted":false,
Wenchao Xia553a7e82013-06-06 12:27:59 +08002531 "file":"disks/test.qcow2",
2532 "backing_file_depth":1,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002533 "bps":1000000,
2534 "bps_rd":0,
2535 "bps_wr":0,
2536 "iops":1000000,
2537 "iops_rd":0,
2538 "iops_wr":0,
Benoît Canet3e9fab62013-09-02 14:14:40 +02002539 "bps_max": 8000000,
2540 "bps_rd_max": 0,
2541 "bps_wr_max": 0,
2542 "iops_max": 0,
2543 "iops_rd_max": 0,
2544 "iops_wr_max": 0,
Benoît Canet2024c1d2013-09-02 14:14:41 +02002545 "iops_size": 0,
Peter Lieven465bee12014-05-18 00:58:19 +02002546 "detect_zeroes": "on",
Francesco Romanie2462112015-01-12 14:11:13 +01002547 "write_threshold": 0,
Wenchao Xia553a7e82013-06-06 12:27:59 +08002548 "image":{
2549 "filename":"disks/test.qcow2",
2550 "format":"qcow2",
2551 "virtual-size":2048000,
2552 "backing_file":"base.qcow2",
2553 "full-backing-filename":"disks/base.qcow2",
John Snow54034322015-04-28 15:20:41 -04002554 "backing-filename-format":"qcow2",
Wenchao Xia553a7e82013-06-06 12:27:59 +08002555 "snapshots":[
2556 {
2557 "id": "1",
2558 "name": "snapshot1",
2559 "vm-state-size": 0,
2560 "date-sec": 10000200,
2561 "date-nsec": 12,
2562 "vm-clock-sec": 206,
2563 "vm-clock-nsec": 30
2564 }
2565 ],
2566 "backing-image":{
2567 "filename":"disks/base.qcow2",
2568 "format":"qcow2",
2569 "virtual-size":2048000
2570 }
2571 }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002572 },
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002573 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002574 },
2575 {
Luiz Capitulinof04ef602011-09-26 17:43:54 -03002576 "io-status": "ok",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002577 "device":"ide1-cd0",
2578 "locked":false,
2579 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002580 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002581 },
2582 {
2583 "device":"floppy0",
2584 "locked":false,
2585 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002586 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002587 },
2588 {
2589 "device":"sd0",
2590 "locked":false,
2591 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002592 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002593 }
2594 ]
2595 }
2596
2597EQMP
2598
Luiz Capitulinob2023812011-09-21 17:16:47 -03002599 {
2600 .name = "query-block",
2601 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002602 .mhandler.cmd_new = qmp_marshal_query_block,
Luiz Capitulinob2023812011-09-21 17:16:47 -03002603 },
2604
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002605SQMP
2606query-blockstats
2607----------------
2608
2609Show block device statistics.
2610
2611Each device statistic information is stored in a json-object and the returned
2612value is a json-array of all devices.
2613
2614Each json-object contain the following:
2615
2616- "device": device name (json-string)
2617- "stats": A json-object with the statistics information, it contains:
2618 - "rd_bytes": bytes read (json-int)
2619 - "wr_bytes": bytes written (json-int)
2620 - "rd_operations": read operations (json-int)
2621 - "wr_operations": write operations (json-int)
Christoph Hellwige8045d62011-08-22 00:25:58 +02002622 - "flush_operations": cache flush operations (json-int)
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002623 - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
2624 - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
2625 - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
Max Reitz53d8f9d2015-10-19 17:53:20 +02002626 - "wr_highest_offset": The offset after the greatest byte written to the
2627 BlockDriverState since it has been opened (json-int)
Peter Lievenf4564d52015-02-02 14:52:18 +01002628 - "rd_merged": number of read requests that have been merged into
2629 another request (json-int)
2630 - "wr_merged": number of write requests that have been merged into
2631 another request (json-int)
Alberto Garciacb38fff2015-10-28 17:33:02 +02002632 - "idle_time_ns": time since the last I/O operation, in
2633 nanoseconds. If the field is absent it means
2634 that there haven't been any operations yet
2635 (json-int, optional)
Alberto Garcia7ee12da2015-10-28 17:33:03 +02002636 - "failed_rd_operations": number of failed read operations
2637 (json-int)
2638 - "failed_wr_operations": number of failed write operations
2639 (json-int)
2640 - "failed_flush_operations": number of failed flush operations
2641 (json-int)
2642 - "invalid_rd_operations": number of invalid read operations
2643 (json-int)
2644 - "invalid_wr_operations": number of invalid write operations
2645 (json-int)
2646 - "invalid_flush_operations": number of invalid flush operations
2647 (json-int)
Alberto Garcia362e9292015-10-28 17:33:04 +02002648 - "account_invalid": whether invalid operations are included in
2649 the last access statistics (json-bool)
2650 - "account_failed": whether failed operations are included in the
2651 latency and last access statistics
2652 (json-bool)
Alberto Garcia979e9b02015-10-28 17:33:05 +02002653 - "timed_stats": A json-array containing statistics collected in
2654 specific intervals, with the following members:
2655 - "interval_length": interval used for calculating the
2656 statistics, in seconds (json-int)
2657 - "min_rd_latency_ns": minimum latency of read operations in
2658 the defined interval, in nanoseconds
2659 (json-int)
2660 - "min_wr_latency_ns": minimum latency of write operations in
2661 the defined interval, in nanoseconds
2662 (json-int)
2663 - "min_flush_latency_ns": minimum latency of flush operations
2664 in the defined interval, in
2665 nanoseconds (json-int)
2666 - "max_rd_latency_ns": maximum latency of read operations in
2667 the defined interval, in nanoseconds
2668 (json-int)
2669 - "max_wr_latency_ns": maximum latency of write operations in
2670 the defined interval, in nanoseconds
2671 (json-int)
2672 - "max_flush_latency_ns": maximum latency of flush operations
2673 in the defined interval, in
2674 nanoseconds (json-int)
2675 - "avg_rd_latency_ns": average latency of read operations in
2676 the defined interval, in nanoseconds
2677 (json-int)
2678 - "avg_wr_latency_ns": average latency of write operations in
2679 the defined interval, in nanoseconds
2680 (json-int)
2681 - "avg_flush_latency_ns": average latency of flush operations
2682 in the defined interval, in
2683 nanoseconds (json-int)
Alberto Garcia96e4ded2015-10-28 17:33:06 +02002684 - "avg_rd_queue_depth": average number of pending read
2685 operations in the defined interval
2686 (json-number)
2687 - "avg_wr_queue_depth": average number of pending write
2688 operations in the defined interval
2689 (json-number).
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002690- "parent": Contains recursively the statistics of the underlying
2691 protocol (e.g. the host file for a qcow2 image). If there is
2692 no underlying protocol, this field is omitted
2693 (json-object, optional)
2694
2695Example:
2696
2697-> { "execute": "query-blockstats" }
2698<- {
2699 "return":[
2700 {
2701 "device":"ide0-hd0",
2702 "parent":{
2703 "stats":{
2704 "wr_highest_offset":3686448128,
2705 "wr_bytes":9786368,
2706 "wr_operations":751,
2707 "rd_bytes":122567168,
2708 "rd_operations":36772
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002709 "wr_total_times_ns":313253456
2710 "rd_total_times_ns":3465673657
2711 "flush_total_times_ns":49653
Christoph Hellwige8045d62011-08-22 00:25:58 +02002712 "flush_operations":61,
Peter Lievenf4564d52015-02-02 14:52:18 +01002713 "rd_merged":0,
Alberto Garciacb38fff2015-10-28 17:33:02 +02002714 "wr_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002715 "idle_time_ns":2953431879,
2716 "account_invalid":true,
2717 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002718 }
2719 },
2720 "stats":{
2721 "wr_highest_offset":2821110784,
2722 "wr_bytes":9786368,
2723 "wr_operations":692,
2724 "rd_bytes":122739200,
2725 "rd_operations":36604
Christoph Hellwige8045d62011-08-22 00:25:58 +02002726 "flush_operations":51,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002727 "wr_total_times_ns":313253456
2728 "rd_total_times_ns":3465673657
Peter Lievenf4564d52015-02-02 14:52:18 +01002729 "flush_total_times_ns":49653,
2730 "rd_merged":0,
Alberto Garciacb38fff2015-10-28 17:33:02 +02002731 "wr_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002732 "idle_time_ns":2953431879,
2733 "account_invalid":true,
2734 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002735 }
2736 },
2737 {
2738 "device":"ide1-cd0",
2739 "stats":{
2740 "wr_highest_offset":0,
2741 "wr_bytes":0,
2742 "wr_operations":0,
2743 "rd_bytes":0,
2744 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02002745 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002746 "wr_total_times_ns":0
2747 "rd_total_times_ns":0
Peter Lievenf4564d52015-02-02 14:52:18 +01002748 "flush_total_times_ns":0,
2749 "rd_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002750 "wr_merged":0,
2751 "account_invalid":false,
2752 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002753 }
2754 },
2755 {
2756 "device":"floppy0",
2757 "stats":{
2758 "wr_highest_offset":0,
2759 "wr_bytes":0,
2760 "wr_operations":0,
2761 "rd_bytes":0,
2762 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02002763 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002764 "wr_total_times_ns":0
2765 "rd_total_times_ns":0
Peter Lievenf4564d52015-02-02 14:52:18 +01002766 "flush_total_times_ns":0,
2767 "rd_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002768 "wr_merged":0,
2769 "account_invalid":false,
2770 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002771 }
2772 },
2773 {
2774 "device":"sd0",
2775 "stats":{
2776 "wr_highest_offset":0,
2777 "wr_bytes":0,
2778 "wr_operations":0,
2779 "rd_bytes":0,
2780 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02002781 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002782 "wr_total_times_ns":0
2783 "rd_total_times_ns":0
Peter Lievenf4564d52015-02-02 14:52:18 +01002784 "flush_total_times_ns":0,
2785 "rd_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002786 "wr_merged":0,
2787 "account_invalid":false,
2788 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002789 }
2790 }
2791 ]
2792 }
2793
2794EQMP
2795
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03002796 {
2797 .name = "query-blockstats",
Fam Zhengf71eaa72014-10-31 11:32:57 +08002798 .args_type = "query-nodes:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002799 .mhandler.cmd_new = qmp_marshal_query_blockstats,
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03002800 },
2801
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002802SQMP
2803query-cpus
2804----------
2805
2806Show CPU information.
2807
2808Return a json-array. Each CPU is represented by a json-object, which contains:
2809
2810- "CPU": CPU index (json-int)
2811- "current": true if this is the current CPU, false otherwise (json-bool)
2812- "halted": true if the cpu is halted, false otherwise (json-bool)
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002813- "qom_path": path to the CPU object in the QOM tree (json-str)
Eric Blake86f4b682015-11-18 01:52:59 -07002814- "arch": architecture of the cpu, which determines what additional
2815 keys will be present (json-str)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002816- Current program counter. The key's name depends on the architecture:
2817 "pc": i386/x86_64 (json-int)
2818 "nip": PPC (json-int)
2819 "pc" and "npc": sparc (json-int)
2820 "PC": mips (json-int)
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01002821- "thread_id": ID of the underlying host thread (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002822
2823Example:
2824
2825-> { "execute": "query-cpus" }
2826<- {
2827 "return":[
2828 {
2829 "CPU":0,
2830 "current":true,
2831 "halted":false,
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002832 "qom_path":"/machine/unattached/device[0]",
Eric Blake86f4b682015-11-18 01:52:59 -07002833 "arch":"x86",
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002834 "pc":3227107138,
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01002835 "thread_id":3134
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002836 },
2837 {
2838 "CPU":1,
2839 "current":false,
2840 "halted":true,
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002841 "qom_path":"/machine/unattached/device[2]",
Eric Blake86f4b682015-11-18 01:52:59 -07002842 "arch":"x86",
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002843 "pc":7108165,
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01002844 "thread_id":3135
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002845 }
2846 ]
2847 }
2848
2849EQMP
2850
Luiz Capitulinode0b36b2011-09-21 16:38:35 -03002851 {
2852 .name = "query-cpus",
2853 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002854 .mhandler.cmd_new = qmp_marshal_query_cpus,
Luiz Capitulinode0b36b2011-09-21 16:38:35 -03002855 },
2856
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002857SQMP
Stefan Hajnoczidc3dd0d2014-02-27 11:48:42 +01002858query-iothreads
2859---------------
2860
2861Returns a list of information about each iothread.
2862
2863Note this list excludes the QEMU main loop thread, which is not declared
2864using the -object iothread command-line option. It is always the main thread
2865of the process.
2866
2867Return a json-array. Each iothread is represented by a json-object, which contains:
2868
2869- "id": name of iothread (json-str)
2870- "thread-id": ID of the underlying host thread (json-int)
2871
2872Example:
2873
2874-> { "execute": "query-iothreads" }
2875<- {
2876 "return":[
2877 {
2878 "id":"iothread0",
2879 "thread-id":3134
2880 },
2881 {
2882 "id":"iothread1",
2883 "thread-id":3135
2884 }
2885 ]
2886 }
2887
2888EQMP
2889
2890 {
2891 .name = "query-iothreads",
2892 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002893 .mhandler.cmd_new = qmp_marshal_query_iothreads,
Stefan Hajnoczidc3dd0d2014-02-27 11:48:42 +01002894 },
2895
2896SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002897query-pci
2898---------
2899
2900PCI buses and devices information.
2901
2902The returned value is a json-array of all buses. Each bus is represented by
2903a json-object, which has a key with a json-array of all PCI devices attached
2904to it. Each device is represented by a json-object.
2905
2906The bus json-object contains the following:
2907
2908- "bus": bus number (json-int)
2909- "devices": a json-array of json-objects, each json-object represents a
2910 PCI device
2911
2912The PCI device json-object contains the following:
2913
2914- "bus": identical to the parent's bus number (json-int)
2915- "slot": slot number (json-int)
2916- "function": function number (json-int)
2917- "class_info": a json-object containing:
2918 - "desc": device class description (json-string, optional)
2919 - "class": device class number (json-int)
2920- "id": a json-object containing:
2921 - "device": device ID (json-int)
2922 - "vendor": vendor ID (json-int)
2923- "irq": device's IRQ if assigned (json-int, optional)
2924- "qdev_id": qdev id string (json-string)
2925- "pci_bridge": It's a json-object, only present if this device is a
2926 PCI bridge, contains:
2927 - "bus": bus number (json-int)
2928 - "secondary": secondary bus number (json-int)
2929 - "subordinate": subordinate bus number (json-int)
2930 - "io_range": I/O memory range information, a json-object with the
2931 following members:
2932 - "base": base address, in bytes (json-int)
2933 - "limit": limit address, in bytes (json-int)
2934 - "memory_range": memory range information, a json-object with the
2935 following members:
2936 - "base": base address, in bytes (json-int)
2937 - "limit": limit address, in bytes (json-int)
2938 - "prefetchable_range": Prefetchable memory range information, a
2939 json-object with the following members:
2940 - "base": base address, in bytes (json-int)
2941 - "limit": limit address, in bytes (json-int)
2942 - "devices": a json-array of PCI devices if there's any attached, each
2943 each element is represented by a json-object, which contains
2944 the same members of the 'PCI device json-object' described
2945 above (optional)
2946- "regions": a json-array of json-objects, each json-object represents a
2947 memory region of this device
2948
2949The memory range json-object contains the following:
2950
2951- "base": base memory address (json-int)
2952- "limit": limit value (json-int)
2953
2954The region json-object can be an I/O region or a memory region, an I/O region
2955json-object contains the following:
2956
2957- "type": "io" (json-string, fixed)
2958- "bar": BAR number (json-int)
2959- "address": memory address (json-int)
2960- "size": memory size (json-int)
2961
2962A memory region json-object contains the following:
2963
2964- "type": "memory" (json-string, fixed)
2965- "bar": BAR number (json-int)
2966- "address": memory address (json-int)
2967- "size": memory size (json-int)
2968- "mem_type_64": true or false (json-bool)
2969- "prefetch": true or false (json-bool)
2970
2971Example:
2972
2973-> { "execute": "query-pci" }
2974<- {
2975 "return":[
2976 {
2977 "bus":0,
2978 "devices":[
2979 {
2980 "bus":0,
2981 "qdev_id":"",
2982 "slot":0,
2983 "class_info":{
2984 "class":1536,
2985 "desc":"Host bridge"
2986 },
2987 "id":{
2988 "device":32902,
2989 "vendor":4663
2990 },
2991 "function":0,
2992 "regions":[
2993
2994 ]
2995 },
2996 {
2997 "bus":0,
2998 "qdev_id":"",
2999 "slot":1,
3000 "class_info":{
3001 "class":1537,
3002 "desc":"ISA bridge"
3003 },
3004 "id":{
3005 "device":32902,
3006 "vendor":28672
3007 },
3008 "function":0,
3009 "regions":[
3010
3011 ]
3012 },
3013 {
3014 "bus":0,
3015 "qdev_id":"",
3016 "slot":1,
3017 "class_info":{
3018 "class":257,
3019 "desc":"IDE controller"
3020 },
3021 "id":{
3022 "device":32902,
3023 "vendor":28688
3024 },
3025 "function":1,
3026 "regions":[
3027 {
3028 "bar":4,
3029 "size":16,
3030 "address":49152,
3031 "type":"io"
3032 }
3033 ]
3034 },
3035 {
3036 "bus":0,
3037 "qdev_id":"",
3038 "slot":2,
3039 "class_info":{
3040 "class":768,
3041 "desc":"VGA controller"
3042 },
3043 "id":{
3044 "device":4115,
3045 "vendor":184
3046 },
3047 "function":0,
3048 "regions":[
3049 {
3050 "prefetch":true,
3051 "mem_type_64":false,
3052 "bar":0,
3053 "size":33554432,
3054 "address":4026531840,
3055 "type":"memory"
3056 },
3057 {
3058 "prefetch":false,
3059 "mem_type_64":false,
3060 "bar":1,
3061 "size":4096,
3062 "address":4060086272,
3063 "type":"memory"
3064 },
3065 {
3066 "prefetch":false,
3067 "mem_type_64":false,
3068 "bar":6,
3069 "size":65536,
3070 "address":-1,
3071 "type":"memory"
3072 }
3073 ]
3074 },
3075 {
3076 "bus":0,
3077 "qdev_id":"",
3078 "irq":11,
3079 "slot":4,
3080 "class_info":{
3081 "class":1280,
3082 "desc":"RAM controller"
3083 },
3084 "id":{
3085 "device":6900,
3086 "vendor":4098
3087 },
3088 "function":0,
3089 "regions":[
3090 {
3091 "bar":0,
3092 "size":32,
3093 "address":49280,
3094 "type":"io"
3095 }
3096 ]
3097 }
3098 ]
3099 }
3100 ]
3101 }
3102
3103Note: This example has been shortened as the real response is too long.
3104
3105EQMP
3106
Luiz Capitulino79627472011-10-21 14:15:33 -02003107 {
3108 .name = "query-pci",
3109 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003110 .mhandler.cmd_new = qmp_marshal_query_pci,
Luiz Capitulino79627472011-10-21 14:15:33 -02003111 },
3112
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003113SQMP
3114query-kvm
3115---------
3116
3117Show KVM information.
3118
3119Return a json-object with the following information:
3120
3121- "enabled": true if KVM support is enabled, false otherwise (json-bool)
3122- "present": true if QEMU has KVM support, false otherwise (json-bool)
3123
3124Example:
3125
3126-> { "execute": "query-kvm" }
3127<- { "return": { "enabled": true, "present": true } }
3128
3129EQMP
3130
Luiz Capitulino292a2602011-09-12 15:10:53 -03003131 {
3132 .name = "query-kvm",
3133 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003134 .mhandler.cmd_new = qmp_marshal_query_kvm,
Luiz Capitulino292a2602011-09-12 15:10:53 -03003135 },
3136
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003137SQMP
3138query-status
3139------------
3140
3141Return a json-object with the following information:
3142
3143- "running": true if the VM is running, or false if it is paused (json-bool)
3144- "singlestep": true if the VM is in single step mode,
3145 false otherwise (json-bool)
Luiz Capitulino9e37b9d2011-08-29 16:02:57 -03003146- "status": one of the following values (json-string)
3147 "debug" - QEMU is running on a debugger
3148 "inmigrate" - guest is paused waiting for an incoming migration
3149 "internal-error" - An internal error that prevents further guest
3150 execution has occurred
3151 "io-error" - the last IOP has failed and the device is configured
3152 to pause on I/O errors
3153 "paused" - guest has been paused via the 'stop' command
3154 "postmigrate" - guest is paused following a successful 'migrate'
3155 "prelaunch" - QEMU was started with -S and guest has not started
3156 "finish-migrate" - guest is paused to finish the migration process
3157 "restore-vm" - guest is paused to restore VM state
3158 "running" - guest is actively running
3159 "save-vm" - guest is paused to save the VM state
3160 "shutdown" - guest is shut down (and -no-shutdown is in use)
3161 "watchdog" - the watchdog action is configured to pause and
3162 has been triggered
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003163
3164Example:
3165
3166-> { "execute": "query-status" }
Luiz Capitulino9e37b9d2011-08-29 16:02:57 -03003167<- { "return": { "running": true, "singlestep": false, "status": "running" } }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003168
3169EQMP
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -03003170
3171 {
3172 .name = "query-status",
3173 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003174 .mhandler.cmd_new = qmp_marshal_query_status,
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -03003175 },
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003176
3177SQMP
3178query-mice
3179----------
3180
3181Show VM mice information.
3182
3183Each mouse is represented by a json-object, the returned value is a json-array
3184of all mice.
3185
3186The mouse json-object contains the following:
3187
3188- "name": mouse's name (json-string)
3189- "index": mouse's index (json-int)
3190- "current": true if this mouse is receiving events, false otherwise (json-bool)
3191- "absolute": true if the mouse generates absolute input events (json-bool)
3192
3193Example:
3194
3195-> { "execute": "query-mice" }
3196<- {
3197 "return":[
3198 {
3199 "name":"QEMU Microsoft Mouse",
3200 "index":0,
3201 "current":false,
3202 "absolute":false
3203 },
3204 {
3205 "name":"QEMU PS/2 Mouse",
3206 "index":1,
3207 "current":true,
3208 "absolute":true
3209 }
3210 ]
3211 }
3212
3213EQMP
3214
Luiz Capitulinoe235cec2011-09-21 15:29:55 -03003215 {
3216 .name = "query-mice",
3217 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003218 .mhandler.cmd_new = qmp_marshal_query_mice,
Luiz Capitulinoe235cec2011-09-21 15:29:55 -03003219 },
3220
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003221SQMP
3222query-vnc
3223---------
3224
3225Show VNC server information.
3226
3227Return a json-object with server information. Connected clients are returned
3228as a json-array of json-objects.
3229
3230The main json-object contains the following:
3231
3232- "enabled": true or false (json-bool)
3233- "host": server's IP address (json-string)
3234- "family": address family (json-string)
3235 - Possible values: "ipv4", "ipv6", "unix", "unknown"
3236- "service": server's port number (json-string)
3237- "auth": authentication method (json-string)
3238 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
3239 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
3240 "vencrypt+plain", "vencrypt+tls+none",
3241 "vencrypt+tls+plain", "vencrypt+tls+sasl",
3242 "vencrypt+tls+vnc", "vencrypt+x509+none",
3243 "vencrypt+x509+plain", "vencrypt+x509+sasl",
3244 "vencrypt+x509+vnc", "vnc"
3245- "clients": a json-array of all connected clients
3246
3247Clients are described by a json-object, each one contain the following:
3248
3249- "host": client's IP address (json-string)
3250- "family": address family (json-string)
3251 - Possible values: "ipv4", "ipv6", "unix", "unknown"
3252- "service": client's port number (json-string)
3253- "x509_dname": TLS dname (json-string, optional)
3254- "sasl_username": SASL username (json-string, optional)
3255
3256Example:
3257
3258-> { "execute": "query-vnc" }
3259<- {
3260 "return":{
3261 "enabled":true,
3262 "host":"0.0.0.0",
3263 "service":"50402",
3264 "auth":"vnc",
3265 "family":"ipv4",
3266 "clients":[
3267 {
3268 "host":"127.0.0.1",
3269 "service":"50401",
3270 "family":"ipv4"
3271 }
3272 ]
3273 }
3274 }
3275
3276EQMP
3277
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02003278 {
3279 .name = "query-vnc",
3280 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003281 .mhandler.cmd_new = qmp_marshal_query_vnc,
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02003282 },
Gerd Hoffmanndf887682014-12-17 15:49:44 +01003283 {
3284 .name = "query-vnc-servers",
3285 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003286 .mhandler.cmd_new = qmp_marshal_query_vnc_servers,
Gerd Hoffmanndf887682014-12-17 15:49:44 +01003287 },
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02003288
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003289SQMP
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01003290query-spice
3291-----------
3292
3293Show SPICE server information.
3294
3295Return a json-object with server information. Connected clients are returned
3296as a json-array of json-objects.
3297
3298The main json-object contains the following:
3299
3300- "enabled": true or false (json-bool)
3301- "host": server's IP address (json-string)
3302- "port": server's port number (json-int, optional)
3303- "tls-port": server's port number (json-int, optional)
3304- "auth": authentication method (json-string)
3305 - Possible values: "none", "spice"
3306- "channels": a json-array of all active channels clients
3307
3308Channels are described by a json-object, each one contain the following:
3309
3310- "host": client's IP address (json-string)
3311- "family": address family (json-string)
3312 - Possible values: "ipv4", "ipv6", "unix", "unknown"
3313- "port": client's port number (json-string)
3314- "connection-id": spice connection id. All channels with the same id
3315 belong to the same spice session (json-int)
3316- "channel-type": channel type. "1" is the main control channel, filter for
3317 this one if you want track spice sessions only (json-int)
3318- "channel-id": channel id. Usually "0", might be different needed when
3319 multiple channels of the same type exist, such as multiple
3320 display channels in a multihead setup (json-int)
Alberto Garcia3599d462015-02-26 16:35:07 +02003321- "tls": whether the channel is encrypted (json-bool)
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01003322
3323Example:
3324
3325-> { "execute": "query-spice" }
3326<- {
3327 "return": {
3328 "enabled": true,
3329 "auth": "spice",
3330 "port": 5920,
3331 "tls-port": 5921,
3332 "host": "0.0.0.0",
3333 "channels": [
3334 {
3335 "port": "54924",
3336 "family": "ipv4",
3337 "channel-type": 1,
3338 "connection-id": 1804289383,
3339 "host": "127.0.0.1",
3340 "channel-id": 0,
3341 "tls": true
3342 },
3343 {
3344 "port": "36710",
3345 "family": "ipv4",
3346 "channel-type": 4,
3347 "connection-id": 1804289383,
3348 "host": "127.0.0.1",
3349 "channel-id": 0,
3350 "tls": false
3351 },
3352 [ ... more channels follow ... ]
3353 ]
3354 }
3355 }
3356
3357EQMP
3358
Luiz Capitulinod1f29642011-10-20 17:01:33 -02003359#if defined(CONFIG_SPICE)
3360 {
3361 .name = "query-spice",
3362 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003363 .mhandler.cmd_new = qmp_marshal_query_spice,
Luiz Capitulinod1f29642011-10-20 17:01:33 -02003364 },
3365#endif
3366
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01003367SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003368query-name
3369----------
3370
3371Show VM name.
3372
3373Return a json-object with the following information:
3374
3375- "name": VM's name (json-string, optional)
3376
3377Example:
3378
3379-> { "execute": "query-name" }
3380<- { "return": { "name": "qemu-name" } }
3381
3382EQMP
3383
Anthony Liguori48a32be2011-09-02 12:34:48 -05003384 {
3385 .name = "query-name",
3386 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003387 .mhandler.cmd_new = qmp_marshal_query_name,
Anthony Liguori48a32be2011-09-02 12:34:48 -05003388 },
3389
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003390SQMP
3391query-uuid
3392----------
3393
3394Show VM UUID.
3395
3396Return a json-object with the following information:
3397
3398- "UUID": Universally Unique Identifier (json-string)
3399
3400Example:
3401
3402-> { "execute": "query-uuid" }
3403<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
3404
3405EQMP
3406
Luiz Capitulinoefab7672011-09-13 17:16:25 -03003407 {
3408 .name = "query-uuid",
3409 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003410 .mhandler.cmd_new = qmp_marshal_query_uuid,
Luiz Capitulinoefab7672011-09-13 17:16:25 -03003411 },
3412
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003413SQMP
Amos Kong1f8f9872013-04-25 17:50:35 +08003414query-command-line-options
3415--------------------------
3416
3417Show command line option schema.
3418
3419Return a json-array of command line option schema for all options (or for
3420the given option), returning an error if the given option doesn't exist.
3421
3422Each array entry contains the following:
3423
3424- "option": option name (json-string)
3425- "parameters": a json-array describes all parameters of the option:
3426 - "name": parameter name (json-string)
3427 - "type": parameter type (one of 'string', 'boolean', 'number',
3428 or 'size')
3429 - "help": human readable description of the parameter
3430 (json-string, optional)
Chunyan Liue36af942014-06-05 17:20:43 +08003431 - "default": default value string for the parameter
3432 (json-string, optional)
Amos Kong1f8f9872013-04-25 17:50:35 +08003433
3434Example:
3435
3436-> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
3437<- { "return": [
3438 {
3439 "parameters": [
3440 {
3441 "name": "romfile",
3442 "type": "string"
3443 },
3444 {
3445 "name": "bootindex",
3446 "type": "number"
3447 }
3448 ],
3449 "option": "option-rom"
3450 }
3451 ]
3452 }
3453
3454EQMP
3455
3456 {
3457 .name = "query-command-line-options",
3458 .args_type = "option:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003459 .mhandler.cmd_new = qmp_marshal_query_command_line_options,
Amos Kong1f8f9872013-04-25 17:50:35 +08003460 },
3461
3462SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003463query-migrate
3464-------------
3465
3466Migration status.
3467
3468Return a json-object. If migration is active there will be another json-object
3469with RAM migration status and if block migration is active another one with
3470block migration status.
3471
3472The main json-object contains the following:
3473
3474- "status": migration status (json-string)
Peter Feiner3b695952014-05-16 10:40:47 -04003475 - Possible values: "setup", "active", "completed", "failed", "cancelled"
Juan Quintela7aa939a2012-08-18 13:17:10 +02003476- "total-time": total amount of ms since migration started. If
3477 migration has ended, it returns the total migration
Juan Quintela817c6042013-02-11 15:11:10 +01003478 time (json-int)
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003479- "setup-time" amount of setup time in milliseconds _before_ the
3480 iterations begin but _after_ the QMP command is issued.
3481 This is designed to provide an accounting of any activities
3482 (such as RDMA pinning) which may be expensive, but do not
3483 actually occur during the iterative migration rounds
3484 themselves. (json-int)
Juan Quintela9c5a9fc2012-08-13 09:35:16 +02003485- "downtime": only present when migration has finished correctly
3486 total amount in ms for downtime that happened (json-int)
Juan Quintela2c52ddf2012-08-13 09:53:12 +02003487- "expected-downtime": only present while migration is active
3488 total amount in ms for downtime that was calculated on
Juan Quintela817c6042013-02-11 15:11:10 +01003489 the last bitmap round (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003490- "ram": only present if "status" is "active", it is a json-object with the
Juan Quintela817c6042013-02-11 15:11:10 +01003491 following RAM information:
3492 - "transferred": amount transferred in bytes (json-int)
3493 - "remaining": amount remaining to transfer in bytes (json-int)
3494 - "total": total amount of memory in bytes (json-int)
3495 - "duplicate": number of pages filled entirely with the same
3496 byte (json-int)
3497 These are sent over the wire much more efficiently.
Peter Lievenf1c72792013-03-26 10:58:37 +01003498 - "skipped": number of skipped zero pages (json-int)
Stefan Weil805a2502013-04-28 11:49:57 +02003499 - "normal" : number of whole pages transferred. I.e. they
Juan Quintela817c6042013-02-11 15:11:10 +01003500 were not sent as duplicate or xbzrle pages (json-int)
3501 - "normal-bytes" : number of bytes transferred in whole
3502 pages. This is just normal pages times size of one page,
3503 but this way upper levels don't need to care about page
3504 size (json-int)
ChenLiang58570ed2014-04-04 17:57:55 +08003505 - "dirty-sync-count": times that dirty ram was synchronized (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003506- "disk": only present if "status" is "active" and it is a block migration,
Juan Quintela817c6042013-02-11 15:11:10 +01003507 it is a json-object with the following disk information:
3508 - "transferred": amount transferred in bytes (json-int)
3509 - "remaining": amount remaining to transfer in bytes json-int)
3510 - "total": total disk size in bytes (json-int)
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003511- "xbzrle-cache": only present if XBZRLE is active.
3512 It is a json-object with the following XBZRLE information:
Juan Quintela817c6042013-02-11 15:11:10 +01003513 - "cache-size": XBZRLE cache size in bytes
3514 - "bytes": number of bytes transferred for XBZRLE compressed pages
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003515 - "pages": number of XBZRLE compressed pages
Juan Quintela817c6042013-02-11 15:11:10 +01003516 - "cache-miss": number of XBRZRLE page cache misses
ChenLiang8bc39232014-04-04 17:57:56 +08003517 - "cache-miss-rate": rate of XBRZRLE page cache misses
Juan Quintela817c6042013-02-11 15:11:10 +01003518 - "overflow": number of times XBZRLE overflows. This means
3519 that the XBZRLE encoding was bigger than just sent the
3520 whole page, and then we sent the whole page instead (as as
3521 normal page).
3522
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003523Examples:
3524
35251. Before the first migration
3526
3527-> { "execute": "query-migrate" }
3528<- { "return": {} }
3529
35302. Migration is done and has succeeded
3531
3532-> { "execute": "query-migrate" }
Orit Wasserman004d4c12012-08-06 21:42:56 +03003533<- { "return": {
3534 "status": "completed",
3535 "ram":{
3536 "transferred":123,
3537 "remaining":123,
3538 "total":246,
3539 "total-time":12345,
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003540 "setup-time":12345,
Juan Quintela9c5a9fc2012-08-13 09:35:16 +02003541 "downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003542 "duplicate":123,
3543 "normal":123,
ChenLiang58570ed2014-04-04 17:57:55 +08003544 "normal-bytes":123456,
3545 "dirty-sync-count":15
Orit Wasserman004d4c12012-08-06 21:42:56 +03003546 }
3547 }
3548 }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003549
35503. Migration is done and has failed
3551
3552-> { "execute": "query-migrate" }
3553<- { "return": { "status": "failed" } }
3554
35554. Migration is being performed and is not a block migration:
3556
3557-> { "execute": "query-migrate" }
3558<- {
3559 "return":{
3560 "status":"active",
3561 "ram":{
3562 "transferred":123,
3563 "remaining":123,
Orit Wasserman62d4e3f2012-08-06 21:42:55 +03003564 "total":246,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003565 "total-time":12345,
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003566 "setup-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02003567 "expected-downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003568 "duplicate":123,
3569 "normal":123,
ChenLiang58570ed2014-04-04 17:57:55 +08003570 "normal-bytes":123456,
3571 "dirty-sync-count":15
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003572 }
3573 }
3574 }
3575
35765. Migration is being performed and is a block migration:
3577
3578-> { "execute": "query-migrate" }
3579<- {
3580 "return":{
3581 "status":"active",
3582 "ram":{
3583 "total":1057024,
3584 "remaining":1053304,
Orit Wasserman62d4e3f2012-08-06 21:42:55 +03003585 "transferred":3720,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003586 "total-time":12345,
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003587 "setup-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02003588 "expected-downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003589 "duplicate":123,
3590 "normal":123,
ChenLiang58570ed2014-04-04 17:57:55 +08003591 "normal-bytes":123456,
3592 "dirty-sync-count":15
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003593 },
3594 "disk":{
3595 "total":20971520,
3596 "remaining":20880384,
3597 "transferred":91136
3598 }
3599 }
3600 }
3601
Orit Wassermanf36d55a2012-08-06 21:42:57 +030036026. Migration is being performed and XBZRLE is active:
3603
3604-> { "execute": "query-migrate" }
3605<- {
3606 "return":{
3607 "status":"active",
3608 "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
3609 "ram":{
3610 "total":1057024,
3611 "remaining":1053304,
3612 "transferred":3720,
3613 "total-time":12345,
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003614 "setup-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02003615 "expected-downtime":12345,
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003616 "duplicate":10,
3617 "normal":3333,
ChenLiang58570ed2014-04-04 17:57:55 +08003618 "normal-bytes":3412992,
3619 "dirty-sync-count":15
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003620 },
3621 "xbzrle-cache":{
3622 "cache-size":67108864,
3623 "bytes":20971520,
3624 "pages":2444343,
3625 "cache-miss":2244,
ChenLiang8bc39232014-04-04 17:57:56 +08003626 "cache-miss-rate":0.123,
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003627 "overflow":34434
3628 }
3629 }
3630 }
3631
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003632EQMP
3633
Luiz Capitulino791e7c82011-09-13 17:37:16 -03003634 {
3635 .name = "query-migrate",
3636 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003637 .mhandler.cmd_new = qmp_marshal_query_migrate,
Luiz Capitulino791e7c82011-09-13 17:37:16 -03003638 },
3639
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003640SQMP
Orit Wasserman00458432012-08-06 21:42:48 +03003641migrate-set-capabilities
Juan Quintela817c6042013-02-11 15:11:10 +01003642------------------------
Orit Wasserman00458432012-08-06 21:42:48 +03003643
3644Enable/Disable migration capabilities
3645
Juan Quintela817c6042013-02-11 15:11:10 +01003646- "xbzrle": XBZRLE support
zhanghailiangd6d69732014-12-09 14:38:37 +08003647- "rdma-pin-all": pin all pages when using RDMA during migration
3648- "auto-converge": throttle down guest to help convergence of migration
3649- "zero-blocks": compress zero blocks during block migration
zhanghailiang164f59e2016-01-15 11:37:46 +08003650- "compress": use multiple compression threads to accelerate live migration
Juan Quintela72e72e12015-07-08 14:13:10 +02003651- "events": generate events for each migration state change
zhanghailiang164f59e2016-01-15 11:37:46 +08003652- "x-postcopy-ram": postcopy mode for live migration
Orit Wasserman00458432012-08-06 21:42:48 +03003653
3654Arguments:
3655
3656Example:
3657
3658-> { "execute": "migrate-set-capabilities" , "arguments":
3659 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
3660
3661EQMP
3662
3663 {
3664 .name = "migrate-set-capabilities",
Paolo Bonzini43d0a2c2015-04-15 13:30:04 +02003665 .args_type = "capabilities:q",
Orit Wasserman00458432012-08-06 21:42:48 +03003666 .params = "capability:s,state:b",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003667 .mhandler.cmd_new = qmp_marshal_migrate_set_capabilities,
Orit Wasserman00458432012-08-06 21:42:48 +03003668 },
3669SQMP
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003670query-migrate-capabilities
Juan Quintela817c6042013-02-11 15:11:10 +01003671--------------------------
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003672
3673Query current migration capabilities
3674
3675- "capabilities": migration capabilities state
3676 - "xbzrle" : XBZRLE state (json-bool)
zhanghailiangd6d69732014-12-09 14:38:37 +08003677 - "rdma-pin-all" : RDMA Pin Page state (json-bool)
3678 - "auto-converge" : Auto Converge state (json-bool)
3679 - "zero-blocks" : Zero Blocks state (json-bool)
zhanghailiang164f59e2016-01-15 11:37:46 +08003680 - "compress": Multiple compression threads state (json-bool)
3681 - "events": Migration state change event state (json-bool)
3682 - "x-postcopy-ram": postcopy ram state (json-bool)
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003683
3684Arguments:
3685
3686Example:
3687
3688-> { "execute": "query-migrate-capabilities" }
zhanghailiang164f59e2016-01-15 11:37:46 +08003689<- {"return": [
3690 {"state": false, "capability": "xbzrle"},
3691 {"state": false, "capability": "rdma-pin-all"},
3692 {"state": false, "capability": "auto-converge"},
3693 {"state": false, "capability": "zero-blocks"},
3694 {"state": false, "capability": "compress"},
3695 {"state": true, "capability": "events"},
3696 {"state": false, "capability": "x-postcopy-ram"}
3697 ]}
Orit Wassermandbca1b32013-01-31 09:12:17 +02003698
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003699EQMP
3700
3701 {
3702 .name = "query-migrate-capabilities",
3703 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003704 .mhandler.cmd_new = qmp_marshal_query_migrate_capabilities,
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003705 },
3706
3707SQMP
Liang Li85de8322015-03-23 16:32:28 +08003708migrate-set-parameters
3709----------------------
3710
3711Set migration parameters
3712
3713- "compress-level": set compression level during migration (json-int)
3714- "compress-threads": set compression thread count for migration (json-int)
3715- "decompress-threads": set decompression thread count for migration (json-int)
zhanghailiang9c994a92016-01-15 11:37:45 +08003716- "x-cpu-throttle-initial": set initial percentage of time guest cpus are
3717 throttled for auto-converge (json-int)
3718- "x-cpu-throttle-increment": set throttle increasing percentage for
3719 auto-converge (json-int)
Liang Li85de8322015-03-23 16:32:28 +08003720
3721Arguments:
3722
3723Example:
3724
3725-> { "execute": "migrate-set-parameters" , "arguments":
3726 { "compress-level": 1 } }
3727
3728EQMP
3729
3730 {
3731 .name = "migrate-set-parameters",
3732 .args_type =
zhanghailiang9c994a92016-01-15 11:37:45 +08003733 "compress-level:i?,compress-threads:i?,decompress-threads:i?,x-cpu-throttle-initial:i?,x-cpu-throttle-increment:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003734 .mhandler.cmd_new = qmp_marshal_migrate_set_parameters,
Liang Li85de8322015-03-23 16:32:28 +08003735 },
3736SQMP
3737query-migrate-parameters
3738------------------------
3739
3740Query current migration parameters
3741
3742- "parameters": migration parameters value
3743 - "compress-level" : compression level value (json-int)
3744 - "compress-threads" : compression thread count value (json-int)
3745 - "decompress-threads" : decompression thread count value (json-int)
zhanghailiang9c994a92016-01-15 11:37:45 +08003746 - "x-cpu-throttle-initial" : initial percentage of time guest cpus are
3747 throttled (json-int)
3748 - "x-cpu-throttle-increment" : throttle increasing percentage for
3749 auto-converge (json-int)
Liang Li85de8322015-03-23 16:32:28 +08003750
3751Arguments:
3752
3753Example:
3754
3755-> { "execute": "query-migrate-parameters" }
3756<- {
3757 "return": {
zhanghailiang9c994a92016-01-15 11:37:45 +08003758 "decompress-threads": 2,
3759 "x-cpu-throttle-increment": 10,
3760 "compress-threads": 8,
3761 "compress-level": 1,
3762 "x-cpu-throttle-initial": 20
Liang Li85de8322015-03-23 16:32:28 +08003763 }
3764 }
3765
3766EQMP
3767
3768 {
3769 .name = "query-migrate-parameters",
3770 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003771 .mhandler.cmd_new = qmp_marshal_query_migrate_parameters,
Liang Li85de8322015-03-23 16:32:28 +08003772 },
3773
3774SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003775query-balloon
3776-------------
3777
3778Show balloon information.
3779
3780Make an asynchronous request for balloon info. When the request completes a
3781json-object will be returned containing the following data:
3782
3783- "actual": current balloon value in bytes (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003784
3785Example:
3786
3787-> { "execute": "query-balloon" }
3788<- {
3789 "return":{
3790 "actual":1073741824,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003791 }
3792 }
3793
3794EQMP
3795
Luiz Capitulino96637bc2011-10-21 11:41:37 -02003796 {
3797 .name = "query-balloon",
3798 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003799 .mhandler.cmd_new = qmp_marshal_query_balloon,
Luiz Capitulino96637bc2011-10-21 11:41:37 -02003800 },
Anthony Liguorib4b12c62011-12-12 14:29:34 -06003801
3802 {
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00003803 .name = "query-block-jobs",
3804 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003805 .mhandler.cmd_new = qmp_marshal_query_block_jobs,
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00003806 },
3807
3808 {
Anthony Liguorib4b12c62011-12-12 14:29:34 -06003809 .name = "qom-list",
3810 .args_type = "path:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003811 .mhandler.cmd_new = qmp_marshal_qom_list,
Anthony Liguorib4b12c62011-12-12 14:29:34 -06003812 },
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06003813
3814 {
3815 .name = "qom-set",
Paolo Bonzinib9f89782012-03-22 12:51:11 +01003816 .args_type = "path:s,property:s,value:q",
Markus Armbruster6eb39372015-09-16 13:06:25 +02003817 .mhandler.cmd_new = qmp_marshal_qom_set,
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06003818 },
3819
3820 {
3821 .name = "qom-get",
3822 .args_type = "path:s,property:s",
Markus Armbruster6eb39372015-09-16 13:06:25 +02003823 .mhandler.cmd_new = qmp_marshal_qom_get,
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06003824 },
Luiz Capitulino270b2432011-12-08 11:45:55 -02003825
3826 {
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003827 .name = "nbd-server-start",
3828 .args_type = "addr:q",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003829 .mhandler.cmd_new = qmp_marshal_nbd_server_start,
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003830 },
3831 {
3832 .name = "nbd-server-add",
3833 .args_type = "device:B,writable:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003834 .mhandler.cmd_new = qmp_marshal_nbd_server_add,
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003835 },
3836 {
3837 .name = "nbd-server-stop",
3838 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003839 .mhandler.cmd_new = qmp_marshal_nbd_server_stop,
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003840 },
3841
3842 {
Luiz Capitulino270b2432011-12-08 11:45:55 -02003843 .name = "change-vnc-password",
3844 .args_type = "password:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003845 .mhandler.cmd_new = qmp_marshal_change_vnc_password,
Luiz Capitulino270b2432011-12-08 11:45:55 -02003846 },
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06003847 {
3848 .name = "qom-list-types",
3849 .args_type = "implements:s?,abstract:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003850 .mhandler.cmd_new = qmp_marshal_qom_list_types,
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06003851 },
Anthony Liguori1daa31b2012-08-10 11:04:09 -05003852
3853 {
3854 .name = "device-list-properties",
3855 .args_type = "typename:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003856 .mhandler.cmd_new = qmp_marshal_device_list_properties,
Anthony Liguori1daa31b2012-08-10 11:04:09 -05003857 },
3858
Anthony Liguori01d3c802012-08-10 11:04:11 -05003859 {
3860 .name = "query-machines",
3861 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003862 .mhandler.cmd_new = qmp_marshal_query_machines,
Anthony Liguori01d3c802012-08-10 11:04:11 -05003863 },
3864
Anthony Liguorie4e31c62012-08-10 11:04:13 -05003865 {
3866 .name = "query-cpu-definitions",
3867 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003868 .mhandler.cmd_new = qmp_marshal_query_cpu_definitions,
Anthony Liguorie4e31c62012-08-10 11:04:13 -05003869 },
3870
Daniel P. Berrange99afc912012-08-20 15:31:38 +01003871 {
3872 .name = "query-target",
3873 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003874 .mhandler.cmd_new = qmp_marshal_query_target,
Daniel P. Berrange99afc912012-08-20 15:31:38 +01003875 },
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003876
3877 {
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003878 .name = "query-tpm",
3879 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003880 .mhandler.cmd_new = qmp_marshal_query_tpm,
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003881 },
3882
Corey Bryant28c4fa32013-03-20 12:34:49 -04003883SQMP
3884query-tpm
3885---------
3886
3887Return information about the TPM device.
3888
3889Arguments: None
3890
3891Example:
3892
3893-> { "execute": "query-tpm" }
3894<- { "return":
3895 [
3896 { "model": "tpm-tis",
3897 "options":
3898 { "type": "passthrough",
3899 "data":
3900 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
3901 "path": "/dev/tpm0"
3902 }
3903 },
3904 "id": "tpm0"
3905 }
3906 ]
3907 }
3908
3909EQMP
3910
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003911 {
3912 .name = "query-tpm-models",
3913 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003914 .mhandler.cmd_new = qmp_marshal_query_tpm_models,
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003915 },
3916
Corey Bryant28c4fa32013-03-20 12:34:49 -04003917SQMP
3918query-tpm-models
3919----------------
3920
3921Return a list of supported TPM models.
3922
3923Arguments: None
3924
3925Example:
3926
3927-> { "execute": "query-tpm-models" }
3928<- { "return": [ "tpm-tis" ] }
3929
3930EQMP
3931
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003932 {
3933 .name = "query-tpm-types",
3934 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003935 .mhandler.cmd_new = qmp_marshal_query_tpm_types,
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003936 },
3937
Corey Bryant28c4fa32013-03-20 12:34:49 -04003938SQMP
3939query-tpm-types
3940---------------
3941
3942Return a list of supported TPM types.
3943
3944Arguments: None
3945
3946Example:
3947
3948-> { "execute": "query-tpm-types" }
3949<- { "return": [ "passthrough" ] }
3950
3951EQMP
3952
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003953 {
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003954 .name = "chardev-add",
3955 .args_type = "id:s,backend:q",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003956 .mhandler.cmd_new = qmp_marshal_chardev_add,
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003957 },
3958
3959SQMP
3960chardev-add
3961----------------
3962
3963Add a chardev.
3964
3965Arguments:
3966
3967- "id": the chardev's ID, must be unique (json-string)
3968- "backend": chardev backend type + parameters
3969
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01003970Examples:
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003971
3972-> { "execute" : "chardev-add",
3973 "arguments" : { "id" : "foo",
3974 "backend" : { "type" : "null", "data" : {} } } }
3975<- { "return": {} }
3976
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01003977-> { "execute" : "chardev-add",
3978 "arguments" : { "id" : "bar",
3979 "backend" : { "type" : "file",
3980 "data" : { "out" : "/tmp/bar.log" } } } }
3981<- { "return": {} }
3982
Gerd Hoffmann0a1a7fa2012-12-20 14:39:13 +01003983-> { "execute" : "chardev-add",
3984 "arguments" : { "id" : "baz",
3985 "backend" : { "type" : "pty", "data" : {} } } }
3986<- { "return": { "pty" : "/dev/pty/42" } }
3987
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003988EQMP
3989
3990 {
3991 .name = "chardev-remove",
3992 .args_type = "id:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003993 .mhandler.cmd_new = qmp_marshal_chardev_remove,
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003994 },
3995
3996
3997SQMP
3998chardev-remove
3999--------------
4000
4001Remove a chardev.
4002
4003Arguments:
4004
4005- "id": the chardev's ID, must exist and not be in use (json-string)
4006
4007Example:
4008
4009-> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
4010<- { "return": {} }
4011
4012EQMP
Amos Kongb1be4282013-06-14 15:45:52 +08004013 {
4014 .name = "query-rx-filter",
4015 .args_type = "name:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004016 .mhandler.cmd_new = qmp_marshal_query_rx_filter,
Amos Kongb1be4282013-06-14 15:45:52 +08004017 },
4018
4019SQMP
4020query-rx-filter
4021---------------
4022
4023Show rx-filter information.
4024
4025Returns a json-array of rx-filter information for all NICs (or for the
4026given NIC), returning an error if the given NIC doesn't exist, or
4027given NIC doesn't support rx-filter querying, or given net client
4028isn't a NIC.
4029
4030The query will clear the event notification flag of each NIC, then qemu
4031will start to emit event to QMP monitor.
4032
4033Each array entry contains the following:
4034
4035- "name": net client name (json-string)
4036- "promiscuous": promiscuous mode is enabled (json-bool)
4037- "multicast": multicast receive state (one of 'normal', 'none', 'all')
4038- "unicast": unicast receive state (one of 'normal', 'none', 'all')
Amos Kongf7bc8ef2014-03-26 08:19:43 +08004039- "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
Amos Kongb1be4282013-06-14 15:45:52 +08004040- "broadcast-allowed": allow to receive broadcast (json-bool)
4041- "multicast-overflow": multicast table is overflowed (json-bool)
4042- "unicast-overflow": unicast table is overflowed (json-bool)
4043- "main-mac": main macaddr string (json-string)
4044- "vlan-table": a json-array of active vlan id
4045- "unicast-table": a json-array of unicast macaddr string
4046- "multicast-table": a json-array of multicast macaddr string
4047
4048Example:
4049
4050-> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
4051<- { "return": [
4052 {
4053 "promiscuous": true,
4054 "name": "vnet0",
4055 "main-mac": "52:54:00:12:34:56",
4056 "unicast": "normal",
Amos Kongf7bc8ef2014-03-26 08:19:43 +08004057 "vlan": "normal",
Amos Kongb1be4282013-06-14 15:45:52 +08004058 "vlan-table": [
4059 4,
4060 0
4061 ],
4062 "unicast-table": [
4063 ],
4064 "multicast": "normal",
4065 "multicast-overflow": false,
4066 "unicast-overflow": false,
4067 "multicast-table": [
4068 "01:00:5e:00:00:01",
4069 "33:33:00:00:00:01",
4070 "33:33:ff:12:34:56"
4071 ],
4072 "broadcast-allowed": false
4073 }
4074 ]
4075 }
4076
4077EQMP
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004078
4079 {
4080 .name = "blockdev-add",
4081 .args_type = "options:q",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004082 .mhandler.cmd_new = qmp_marshal_blockdev_add,
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004083 },
4084
4085SQMP
4086blockdev-add
4087------------
4088
4089Add a block device.
4090
Markus Armbrusterda2cf4e2015-03-20 14:32:17 +01004091This command is still a work in progress. It doesn't support all
Alberto Garcia81b936a2015-11-02 16:51:55 +02004092block drivers among other things. Stay away from it unless you want
4093to help with its development.
Markus Armbrusterda2cf4e2015-03-20 14:32:17 +01004094
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004095Arguments:
4096
4097- "options": block driver options
4098
4099Example (1):
4100
4101-> { "execute": "blockdev-add",
4102 "arguments": { "options" : { "driver": "qcow2",
4103 "file": { "driver": "file",
4104 "filename": "test.qcow2" } } } }
4105<- { "return": {} }
4106
4107Example (2):
4108
4109-> { "execute": "blockdev-add",
4110 "arguments": {
4111 "options": {
4112 "driver": "qcow2",
4113 "id": "my_disk",
4114 "discard": "unmap",
4115 "cache": {
4116 "direct": true,
4117 "writeback": true
4118 },
4119 "file": {
4120 "driver": "file",
4121 "filename": "/tmp/test.qcow2"
4122 },
4123 "backing": {
4124 "driver": "raw",
4125 "file": {
4126 "driver": "file",
4127 "filename": "/dev/fdset/4"
4128 }
4129 }
4130 }
4131 }
4132 }
4133
4134<- { "return": {} }
4135
4136EQMP
Benoît Canetc13163f2014-01-23 21:31:34 +01004137
4138 {
Alberto Garcia81b936a2015-11-02 16:51:55 +02004139 .name = "x-blockdev-del",
4140 .args_type = "id:s?,node-name:s?",
4141 .mhandler.cmd_new = qmp_marshal_x_blockdev_del,
4142 },
4143
4144SQMP
4145x-blockdev-del
4146------------
4147Since 2.5
4148
4149Deletes a block device thas has been added using blockdev-add.
4150The selected device can be either a block backend or a graph node.
4151
4152In the former case the backend will be destroyed, along with its
4153inserted medium if there's any. The command will fail if the backend
4154or its medium are in use.
4155
4156In the latter case the node will be destroyed. The command will fail
4157if the node is attached to a block backend or is otherwise being
4158used.
4159
4160One of "id" or "node-name" must be specified, but not both.
4161
4162This command is still a work in progress and is considered
4163experimental. Stay away from it unless you want to help with its
4164development.
4165
4166Arguments:
4167
4168- "id": Name of the block backend device to delete (json-string, optional)
4169- "node-name": Name of the graph node to delete (json-string, optional)
4170
4171Example:
4172
4173-> { "execute": "blockdev-add",
4174 "arguments": {
4175 "options": {
4176 "driver": "qcow2",
4177 "id": "drive0",
4178 "file": {
4179 "driver": "file",
4180 "filename": "test.qcow2"
4181 }
4182 }
4183 }
4184 }
4185
4186<- { "return": {} }
4187
4188-> { "execute": "x-blockdev-del",
4189 "arguments": { "id": "drive0" }
4190 }
4191<- { "return": {} }
4192
4193EQMP
4194
4195 {
Max Reitz7d8a9f72015-10-26 21:39:08 +01004196 .name = "blockdev-open-tray",
4197 .args_type = "device:s,force:b?",
4198 .mhandler.cmd_new = qmp_marshal_blockdev_open_tray,
4199 },
4200
4201SQMP
4202blockdev-open-tray
4203------------------
4204
4205Opens a block device's tray. If there is a block driver state tree inserted as a
4206medium, it will become inaccessible to the guest (but it will remain associated
4207to the block device, so closing the tray will make it accessible again).
4208
4209If the tray was already open before, this will be a no-op.
4210
4211Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
4212which no such event will be generated, these include:
4213- if the guest has locked the tray, @force is false and the guest does not
4214 respond to the eject request
4215- if the BlockBackend denoted by @device does not have a guest device attached
4216 to it
4217- if the guest device does not have an actual tray and is empty, for instance
4218 for floppy disk drives
4219
4220Arguments:
4221
4222- "device": block device name (json-string)
4223- "force": if false (the default), an eject request will be sent to the guest if
4224 it has locked the tray (and the tray will not be opened immediately);
4225 if true, the tray will be opened regardless of whether it is locked
4226 (json-bool, optional)
4227
4228Example:
4229
4230-> { "execute": "blockdev-open-tray",
4231 "arguments": { "device": "ide1-cd0" } }
4232
4233<- { "timestamp": { "seconds": 1418751016,
4234 "microseconds": 716996 },
4235 "event": "DEVICE_TRAY_MOVED",
4236 "data": { "device": "ide1-cd0",
4237 "tray-open": true } }
4238
4239<- { "return": {} }
4240
4241EQMP
4242
4243 {
Max Reitzabaaf592015-10-26 21:39:09 +01004244 .name = "blockdev-close-tray",
4245 .args_type = "device:s",
4246 .mhandler.cmd_new = qmp_marshal_blockdev_close_tray,
4247 },
4248
4249SQMP
4250blockdev-close-tray
4251-------------------
4252
4253Closes a block device's tray. If there is a block driver state tree associated
4254with the block device (which is currently ejected), that tree will be loaded as
4255the medium.
4256
4257If the tray was already closed before, this will be a no-op.
4258
4259Arguments:
4260
4261- "device": block device name (json-string)
4262
4263Example:
4264
4265-> { "execute": "blockdev-close-tray",
4266 "arguments": { "device": "ide1-cd0" } }
4267
4268<- { "timestamp": { "seconds": 1418751345,
4269 "microseconds": 272147 },
4270 "event": "DEVICE_TRAY_MOVED",
4271 "data": { "device": "ide1-cd0",
4272 "tray-open": false } }
4273
4274<- { "return": {} }
4275
4276EQMP
4277
4278 {
Max Reitz6e0abc22015-12-11 16:23:05 +01004279 .name = "x-blockdev-remove-medium",
Max Reitz2814f672015-10-26 21:39:10 +01004280 .args_type = "device:s",
Max Reitz6e0abc22015-12-11 16:23:05 +01004281 .mhandler.cmd_new = qmp_marshal_x_blockdev_remove_medium,
Max Reitz2814f672015-10-26 21:39:10 +01004282 },
4283
4284SQMP
Max Reitz6e0abc22015-12-11 16:23:05 +01004285x-blockdev-remove-medium
4286------------------------
Max Reitz2814f672015-10-26 21:39:10 +01004287
4288Removes a medium (a block driver state tree) from a block device. That block
4289device's tray must currently be open (unless there is no attached guest device).
4290
4291If the tray is open and there is no medium inserted, this will be a no-op.
4292
Max Reitz6e0abc22015-12-11 16:23:05 +01004293This command is still a work in progress and is considered experimental.
4294Stay away from it unless you want to help with its development.
4295
Max Reitz2814f672015-10-26 21:39:10 +01004296Arguments:
4297
4298- "device": block device name (json-string)
4299
4300Example:
4301
Max Reitz6e0abc22015-12-11 16:23:05 +01004302-> { "execute": "x-blockdev-remove-medium",
Max Reitz2814f672015-10-26 21:39:10 +01004303 "arguments": { "device": "ide1-cd0" } }
4304
4305<- { "error": { "class": "GenericError",
4306 "desc": "Tray of device 'ide1-cd0' is not open" } }
4307
4308-> { "execute": "blockdev-open-tray",
4309 "arguments": { "device": "ide1-cd0" } }
4310
4311<- { "timestamp": { "seconds": 1418751627,
4312 "microseconds": 549958 },
4313 "event": "DEVICE_TRAY_MOVED",
4314 "data": { "device": "ide1-cd0",
4315 "tray-open": true } }
4316
4317<- { "return": {} }
4318
Max Reitz6e0abc22015-12-11 16:23:05 +01004319-> { "execute": "x-blockdev-remove-medium",
Max Reitz2814f672015-10-26 21:39:10 +01004320 "arguments": { "device": "ide1-cd0" } }
4321
4322<- { "return": {} }
4323
4324EQMP
4325
4326 {
Max Reitz6e0abc22015-12-11 16:23:05 +01004327 .name = "x-blockdev-insert-medium",
Max Reitzd1299882015-10-26 21:39:11 +01004328 .args_type = "device:s,node-name:s",
Max Reitz6e0abc22015-12-11 16:23:05 +01004329 .mhandler.cmd_new = qmp_marshal_x_blockdev_insert_medium,
Max Reitzd1299882015-10-26 21:39:11 +01004330 },
4331
4332SQMP
Max Reitz6e0abc22015-12-11 16:23:05 +01004333x-blockdev-insert-medium
4334------------------------
Max Reitzd1299882015-10-26 21:39:11 +01004335
4336Inserts a medium (a block driver state tree) into a block device. That block
4337device's tray must currently be open (unless there is no attached guest device)
4338and there must be no medium inserted already.
4339
Max Reitz6e0abc22015-12-11 16:23:05 +01004340This command is still a work in progress and is considered experimental.
4341Stay away from it unless you want to help with its development.
4342
Max Reitzd1299882015-10-26 21:39:11 +01004343Arguments:
4344
4345- "device": block device name (json-string)
4346- "node-name": root node of the BDS tree to insert into the block device
4347
4348Example:
4349
4350-> { "execute": "blockdev-add",
4351 "arguments": { "options": { "node-name": "node0",
4352 "driver": "raw",
4353 "file": { "driver": "file",
4354 "filename": "fedora.iso" } } } }
4355
4356<- { "return": {} }
4357
Max Reitz6e0abc22015-12-11 16:23:05 +01004358-> { "execute": "x-blockdev-insert-medium",
Max Reitzd1299882015-10-26 21:39:11 +01004359 "arguments": { "device": "ide1-cd0",
4360 "node-name": "node0" } }
4361
4362<- { "return": {} }
4363
4364EQMP
4365
4366 {
Benoît Canetc13163f2014-01-23 21:31:34 +01004367 .name = "query-named-block-nodes",
4368 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004369 .mhandler.cmd_new = qmp_marshal_query_named_block_nodes,
Benoît Canetc13163f2014-01-23 21:31:34 +01004370 },
4371
4372SQMP
4373@query-named-block-nodes
4374------------------------
4375
4376Return a list of BlockDeviceInfo for all the named block driver nodes
4377
4378Example:
4379
4380-> { "execute": "query-named-block-nodes" }
4381<- { "return": [ { "ro":false,
4382 "drv":"qcow2",
4383 "encrypted":false,
4384 "file":"disks/test.qcow2",
4385 "node-name": "my-node",
4386 "backing_file_depth":1,
4387 "bps":1000000,
4388 "bps_rd":0,
4389 "bps_wr":0,
4390 "iops":1000000,
4391 "iops_rd":0,
4392 "iops_wr":0,
4393 "bps_max": 8000000,
4394 "bps_rd_max": 0,
4395 "bps_wr_max": 0,
4396 "iops_max": 0,
4397 "iops_rd_max": 0,
4398 "iops_wr_max": 0,
4399 "iops_size": 0,
Francesco Romanie2462112015-01-12 14:11:13 +01004400 "write_threshold": 0,
Benoît Canetc13163f2014-01-23 21:31:34 +01004401 "image":{
4402 "filename":"disks/test.qcow2",
4403 "format":"qcow2",
4404 "virtual-size":2048000,
4405 "backing_file":"base.qcow2",
4406 "full-backing-filename":"disks/base.qcow2",
John Snow54034322015-04-28 15:20:41 -04004407 "backing-filename-format":"qcow2",
Benoît Canetc13163f2014-01-23 21:31:34 +01004408 "snapshots":[
4409 {
4410 "id": "1",
4411 "name": "snapshot1",
4412 "vm-state-size": 0,
4413 "date-sec": 10000200,
4414 "date-nsec": 12,
4415 "vm-clock-sec": 206,
4416 "vm-clock-nsec": 30
4417 }
4418 ],
4419 "backing-image":{
4420 "filename":"disks/base.qcow2",
4421 "format":"qcow2",
4422 "virtual-size":2048000
4423 }
Michael S. Tsirkinc0594512014-06-16 15:20:18 +03004424 } } ] }
Benoît Canetc13163f2014-01-23 21:31:34 +01004425
4426EQMP
Hu Tao76b5d852014-06-16 18:05:41 +08004427
4428 {
Max Reitz24fb4132015-11-06 16:27:06 +01004429 .name = "blockdev-change-medium",
Max Reitz39ff43d2015-11-11 04:49:44 +01004430 .args_type = "device:B,filename:F,format:s?,read-only-mode:s?",
Max Reitz24fb4132015-11-06 16:27:06 +01004431 .mhandler.cmd_new = qmp_marshal_blockdev_change_medium,
4432 },
4433
4434SQMP
4435blockdev-change-medium
4436----------------------
4437
4438Changes the medium inserted into a block device by ejecting the current medium
4439and loading a new image file which is inserted as the new medium.
4440
4441Arguments:
4442
4443- "device": device name (json-string)
4444- "filename": filename of the new image (json-string)
4445- "format": format of the new image (json-string, optional)
Max Reitz39ff43d2015-11-11 04:49:44 +01004446- "read-only-mode": new read-only mode (json-string, optional)
4447 - Possible values: "retain" (default), "read-only", "read-write"
Max Reitz24fb4132015-11-06 16:27:06 +01004448
4449Examples:
4450
44511. Change a removable medium
4452
4453-> { "execute": "blockdev-change-medium",
4454 "arguments": { "device": "ide1-cd0",
4455 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
4456 "format": "raw" } }
4457<- { "return": {} }
4458
Max Reitz39ff43d2015-11-11 04:49:44 +010044592. Load a read-only medium into a writable drive
4460
4461-> { "execute": "blockdev-change-medium",
4462 "arguments": { "device": "isa-fd0",
4463 "filename": "/srv/images/ro.img",
4464 "format": "raw",
4465 "read-only-mode": "retain" } }
4466
4467<- { "error":
4468 { "class": "GenericError",
4469 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
4470
4471-> { "execute": "blockdev-change-medium",
4472 "arguments": { "device": "isa-fd0",
4473 "filename": "/srv/images/ro.img",
4474 "format": "raw",
4475 "read-only-mode": "read-only" } }
4476
4477<- { "return": {} }
4478
Max Reitz24fb4132015-11-06 16:27:06 +01004479EQMP
4480
4481 {
Hu Tao76b5d852014-06-16 18:05:41 +08004482 .name = "query-memdev",
4483 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004484 .mhandler.cmd_new = qmp_marshal_query_memdev,
Hu Tao76b5d852014-06-16 18:05:41 +08004485 },
4486
4487SQMP
4488query-memdev
4489------------
4490
4491Show memory devices information.
4492
4493
4494Example (1):
4495
4496-> { "execute": "query-memdev" }
4497<- { "return": [
4498 {
4499 "size": 536870912,
4500 "merge": false,
4501 "dump": true,
4502 "prealloc": false,
4503 "host-nodes": [0, 1],
4504 "policy": "bind"
4505 },
4506 {
4507 "size": 536870912,
4508 "merge": false,
4509 "dump": true,
4510 "prealloc": true,
4511 "host-nodes": [2, 3],
4512 "policy": "preferred"
4513 }
4514 ]
4515 }
4516
4517EQMP
Igor Mammedov6f2e2732014-06-16 19:12:25 +02004518
4519 {
4520 .name = "query-memory-devices",
4521 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004522 .mhandler.cmd_new = qmp_marshal_query_memory_devices,
Igor Mammedov6f2e2732014-06-16 19:12:25 +02004523 },
4524
4525SQMP
4526@query-memory-devices
4527--------------------
4528
4529Return a list of memory devices.
4530
4531Example:
4532-> { "execute": "query-memory-devices" }
4533<- { "return": [ { "data":
4534 { "addr": 5368709120,
4535 "hotpluggable": true,
4536 "hotplugged": true,
4537 "id": "d1",
4538 "memdev": "/objects/memX",
4539 "node": 0,
4540 "size": 1073741824,
4541 "slot": 0},
4542 "type": "dimm"
4543 } ] }
4544EQMP
Igor Mammedov02419bc2014-06-16 19:12:28 +02004545
4546 {
4547 .name = "query-acpi-ospm-status",
4548 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004549 .mhandler.cmd_new = qmp_marshal_query_acpi_ospm_status,
Igor Mammedov02419bc2014-06-16 19:12:28 +02004550 },
4551
4552SQMP
4553@query-acpi-ospm-status
4554--------------------
4555
4556Return list of ACPIOSTInfo for devices that support status reporting
4557via ACPI _OST method.
4558
4559Example:
4560-> { "execute": "query-acpi-ospm-status" }
4561<- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
4562 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
4563 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
4564 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
4565 ]}
4566EQMP
Marcelo Tosattif2ae8ab2014-06-24 18:55:11 -03004567
4568#if defined TARGET_I386
4569 {
4570 .name = "rtc-reset-reinjection",
4571 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004572 .mhandler.cmd_new = qmp_marshal_rtc_reset_reinjection,
Marcelo Tosattif2ae8ab2014-06-24 18:55:11 -03004573 },
4574#endif
4575
4576SQMP
4577rtc-reset-reinjection
4578---------------------
4579
4580Reset the RTC interrupt reinjection backlog.
4581
4582Arguments: None.
4583
4584Example:
4585
4586-> { "execute": "rtc-reset-reinjection" }
4587<- { "return": {} }
Lluís Vilanova1dde0f42014-08-25 13:19:57 +02004588EQMP
Marcelo Tosattif2ae8ab2014-06-24 18:55:11 -03004589
Lluís Vilanova1dde0f42014-08-25 13:19:57 +02004590 {
4591 .name = "trace-event-get-state",
4592 .args_type = "name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004593 .mhandler.cmd_new = qmp_marshal_trace_event_get_state,
Lluís Vilanova1dde0f42014-08-25 13:19:57 +02004594 },
4595
4596SQMP
4597trace-event-get-state
4598---------------------
4599
4600Query the state of events.
4601
4602Example:
4603
4604-> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
4605<- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
4606EQMP
4607
4608 {
4609 .name = "trace-event-set-state",
4610 .args_type = "name:s,enable:b,ignore-unavailable:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004611 .mhandler.cmd_new = qmp_marshal_trace_event_set_state,
Lluís Vilanova1dde0f42014-08-25 13:19:57 +02004612 },
4613
4614SQMP
4615trace-event-set-state
4616---------------------
4617
4618Set the state of events.
4619
4620Example:
4621
4622-> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
4623<- { "return": {} }
Marcelo Tosattif2ae8ab2014-06-24 18:55:11 -03004624EQMP
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004625
4626 {
Gerd Hoffmanndf5b2ad2014-11-25 14:54:17 +01004627 .name = "x-input-send-event",
Amos Kong51fc4472014-11-07 12:41:25 +08004628 .args_type = "console:i?,events:q",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004629 .mhandler.cmd_new = qmp_marshal_x_input_send_event,
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004630 },
4631
4632SQMP
Gerd Hoffmanndf5b2ad2014-11-25 14:54:17 +01004633@x-input-send-event
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004634-----------------
4635
4636Send input event to guest.
4637
4638Arguments:
4639
Amos Kong51fc4472014-11-07 12:41:25 +08004640- "console": console index. (json-int, optional)
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004641- "events": list of input events.
4642
4643The consoles are visible in the qom tree, under
4644/backend/console[$index]. They have a device link and head property, so
4645it is possible to map which console belongs to which device and display.
4646
Gerd Hoffmanndf5b2ad2014-11-25 14:54:17 +01004647Note: this command is experimental, and not a stable API.
4648
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004649Example (1):
4650
4651Press left mouse button.
4652
Gerd Hoffmanndf5b2ad2014-11-25 14:54:17 +01004653-> { "execute": "x-input-send-event",
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004654 "arguments": { "console": 0,
4655 "events": [ { "type": "btn",
Amos Kongb5369dd2014-11-25 16:05:56 +08004656 "data" : { "down": true, "button": "Left" } } ] } }
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004657<- { "return": {} }
4658
Gerd Hoffmanndf5b2ad2014-11-25 14:54:17 +01004659-> { "execute": "x-input-send-event",
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004660 "arguments": { "console": 0,
4661 "events": [ { "type": "btn",
Amos Kongb5369dd2014-11-25 16:05:56 +08004662 "data" : { "down": false, "button": "Left" } } ] } }
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004663<- { "return": {} }
4664
4665Example (2):
4666
4667Press ctrl-alt-del.
4668
Gerd Hoffmanndf5b2ad2014-11-25 14:54:17 +01004669-> { "execute": "x-input-send-event",
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004670 "arguments": { "console": 0, "events": [
4671 { "type": "key", "data" : { "down": true,
4672 "key": {"type": "qcode", "data": "ctrl" } } },
4673 { "type": "key", "data" : { "down": true,
4674 "key": {"type": "qcode", "data": "alt" } } },
4675 { "type": "key", "data" : { "down": true,
4676 "key": {"type": "qcode", "data": "delete" } } } ] } }
4677<- { "return": {} }
4678
4679Example (3):
4680
4681Move mouse pointer to absolute coordinates (20000, 400).
4682
Gerd Hoffmanndf5b2ad2014-11-25 14:54:17 +01004683-> { "execute": "x-input-send-event" ,
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004684 "arguments": { "console": 0, "events": [
4685 { "type": "abs", "data" : { "axis": "X", "value" : 20000 } },
4686 { "type": "abs", "data" : { "axis": "Y", "value" : 400 } } ] } }
4687<- { "return": {} }
4688
4689EQMP
Francesco Romanie2462112015-01-12 14:11:13 +01004690
4691 {
4692 .name = "block-set-write-threshold",
4693 .args_type = "node-name:s,write-threshold:l",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004694 .mhandler.cmd_new = qmp_marshal_block_set_write_threshold,
Francesco Romanie2462112015-01-12 14:11:13 +01004695 },
4696
4697SQMP
4698block-set-write-threshold
4699------------
4700
4701Change the write threshold for a block drive. The threshold is an offset,
4702thus must be non-negative. Default is no write threshold.
4703Setting the threshold to zero disables it.
4704
4705Arguments:
4706
4707- "node-name": the node name in the block driver state graph (json-string)
4708- "write-threshold": the write threshold in bytes (json-int)
4709
4710Example:
4711
4712-> { "execute": "block-set-write-threshold",
4713 "arguments": { "node-name": "mydev",
4714 "write-threshold": 17179869184 } }
4715<- { "return": {} }
4716
4717EQMP
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004718
4719 {
4720 .name = "query-rocker",
4721 .args_type = "name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004722 .mhandler.cmd_new = qmp_marshal_query_rocker,
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004723 },
4724
4725SQMP
4726Show rocker switch
4727------------------
4728
4729Arguments:
4730
4731- "name": switch name
4732
4733Example:
4734
4735-> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
4736<- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
4737
4738EQMP
4739
4740 {
4741 .name = "query-rocker-ports",
4742 .args_type = "name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004743 .mhandler.cmd_new = qmp_marshal_query_rocker_ports,
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004744 },
4745
4746SQMP
4747Show rocker switch ports
4748------------------------
4749
4750Arguments:
4751
4752- "name": switch name
4753
4754Example:
4755
4756-> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
4757<- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
4758 "autoneg": "off", "link-up": true, "speed": 10000},
4759 {"duplex": "full", "enabled": true, "name": "sw1.2",
4760 "autoneg": "off", "link-up": true, "speed": 10000}
4761 ]}
4762
4763EQMP
4764
4765 {
4766 .name = "query-rocker-of-dpa-flows",
4767 .args_type = "name:s,tbl-id:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004768 .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_flows,
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004769 },
4770
4771SQMP
4772Show rocker switch OF-DPA flow tables
4773-------------------------------------
4774
4775Arguments:
4776
4777- "name": switch name
4778- "tbl-id": (optional) flow table ID
4779
4780Example:
4781
4782-> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
4783<- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
4784 "hits": 138,
4785 "cookie": 0,
4786 "action": {"goto-tbl": 10},
4787 "mask": {"in-pport": 4294901760}
4788 },
4789 {...more...},
4790 ]}
4791
4792EQMP
4793
4794 {
4795 .name = "query-rocker-of-dpa-groups",
4796 .args_type = "name:s,type:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004797 .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_groups,
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004798 },
4799
4800SQMP
4801Show rocker OF-DPA group tables
4802-------------------------------
4803
4804Arguments:
4805
4806- "name": switch name
4807- "type": (optional) group type
4808
4809Example:
4810
4811-> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
4812<- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
4813 "pop-vlan": 1, "id": 251723778},
4814 {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
4815 "pop-vlan": 1, "id": 251723776},
4816 {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
4817 "pop-vlan": 1, "id": 251658241},
4818 {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
4819 "pop-vlan": 1, "id": 251658240}
4820 ]}