blob: 4d382f4ffc944c0caee10180b7658009429f156b [file] [log] [blame]
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001HXCOMM QMP dispatch table and documentation
2HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
3HXCOMM 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 = "",
Luiz Capitulino7a7f3252011-09-15 14:20:28 -030066 .mhandler.cmd_new = qmp_marshal_input_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",
Luiz Capitulinoc245b6a2011-12-07 16:02:36 -020087 .mhandler.cmd_new = qmp_marshal_input_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?",
Luiz Capitulino333a96e2011-12-08 11:13:50 -0200113 .mhandler.cmd_new = qmp_marshal_input_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",
Luiz Capitulinoad39cf62012-05-24 13:48:23 -0300149 .mhandler.cmd_new = qmp_marshal_input_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 = "",
Luiz Capitulino5f158f22011-09-15 14:34:39 -0300172 .mhandler.cmd_new = qmp_marshal_input_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 = "",
Luiz Capitulinoe42e8182011-11-22 17:58:31 -0200193 .mhandler.cmd_new = qmp_marshal_input_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 = "",
214 .mhandler.cmd_new = qmp_marshal_input_system_wakeup,
215 },
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 = "",
Luiz Capitulino38d22652011-09-15 14:41:46 -0300235 .mhandler.cmd_new = qmp_marshal_input_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 = "",
Luiz Capitulino22e1bb92011-11-27 22:40:03 -0200256 .mhandler.cmd_new = qmp_marshal_input_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",
279 .user_print = monitor_user_noop,
280 .mhandler.cmd_new = do_device_add,
281 },
282
283SQMP
284device_add
285----------
286
287Add a device.
288
289Arguments:
290
291- "driver": the name of the new device's driver (json-string)
292- "bus": the device's parent bus (device tree path, json-string, optional)
293- "id": the device's ID, must be unique (json-string)
294- device properties
295
296Example:
297
298-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
299<- { "return": {} }
300
301Notes:
302
303(1) For detailed information about this command, please refer to the
304 'docs/qdev-device-use.txt' file.
305
306(2) It's possible to list device properties by running QEMU with the
307 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
308
309EQMP
310
311 {
312 .name = "device_del",
313 .args_type = "id:s",
Luiz Capitulinoa15fef22012-03-29 12:38:50 -0300314 .mhandler.cmd_new = qmp_marshal_input_device_del,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300315 },
316
317SQMP
318device_del
319----------
320
321Remove a device.
322
323Arguments:
324
325- "id": the device's ID (json-string)
326
327Example:
328
329-> { "execute": "device_del", "arguments": { "id": "net1" } }
330<- { "return": {} }
331
332EQMP
333
334 {
Amos Konge4c8f002012-08-31 10:56:26 +0800335 .name = "send-key",
336 .args_type = "keys:O,hold-time:i?",
337 .mhandler.cmd_new = qmp_marshal_input_send_key,
338 },
339
340SQMP
341send-key
342----------
343
344Send keys to VM.
345
346Arguments:
347
348keys array:
349 - "key": key sequence (a json-array of key enum values)
350
351- hold-time: time to delay key up events, milliseconds. Defaults to 100
352 (json-int, optional)
353
354Example:
355
356-> { "execute": "send-key",
357 "arguments": { 'keys': [ 'ctrl', 'alt', 'delete' ] } }
358<- { "return": {} }
359
360EQMP
361
362 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300363 .name = "cpu",
364 .args_type = "index:i",
Luiz Capitulino755f1962011-10-06 14:31:39 -0300365 .mhandler.cmd_new = qmp_marshal_input_cpu,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300366 },
367
368SQMP
369cpu
370---
371
372Set the default CPU.
373
374Arguments:
375
376- "index": the CPU's index (json-int)
377
378Example:
379
380-> { "execute": "cpu", "arguments": { "index": 0 } }
381<- { "return": {} }
382
383Note: CPUs' indexes are obtained with the 'query-cpus' command.
384
385EQMP
386
387 {
388 .name = "memsave",
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -0200389 .args_type = "val:l,size:i,filename:s,cpu:i?",
390 .mhandler.cmd_new = qmp_marshal_input_memsave,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300391 },
392
393SQMP
394memsave
395-------
396
397Save to disk virtual memory dump starting at 'val' of size 'size'.
398
399Arguments:
400
401- "val": the starting address (json-int)
402- "size": the memory size, in bytes (json-int)
403- "filename": file path (json-string)
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -0200404- "cpu": virtual CPU index (json-int, optional)
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300405
406Example:
407
408-> { "execute": "memsave",
409 "arguments": { "val": 10,
410 "size": 100,
411 "filename": "/tmp/virtual-mem-dump" } }
412<- { "return": {} }
413
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300414EQMP
415
416 {
417 .name = "pmemsave",
418 .args_type = "val:l,size:i,filename:s",
Luiz Capitulino6d3962b2011-11-22 17:26:46 -0200419 .mhandler.cmd_new = qmp_marshal_input_pmemsave,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300420 },
421
422SQMP
423pmemsave
424--------
425
426Save to disk physical memory dump starting at 'val' of size 'size'.
427
428Arguments:
429
430- "val": the starting address (json-int)
431- "size": the memory size, in bytes (json-int)
432- "filename": file path (json-string)
433
434Example:
435
436-> { "execute": "pmemsave",
437 "arguments": { "val": 10,
438 "size": 100,
439 "filename": "/tmp/physical-mem-dump" } }
440<- { "return": {} }
441
442EQMP
443
444 {
Lai Jiangshana4046662011-03-07 17:05:15 +0800445 .name = "inject-nmi",
446 .args_type = "",
Luiz Capitulinoab49ab52011-11-23 12:55:53 -0200447 .mhandler.cmd_new = qmp_marshal_input_inject_nmi,
Lai Jiangshana4046662011-03-07 17:05:15 +0800448 },
449
450SQMP
451inject-nmi
452----------
453
454Inject an NMI on guest's CPUs.
455
456Arguments: None.
457
458Example:
459
460-> { "execute": "inject-nmi" }
461<- { "return": {} }
462
Luiz Capitulinode253f12012-07-27 16:18:16 -0300463Note: inject-nmi fails when the guest doesn't support injecting.
464 Currently, only x86 guests do.
Lai Jiangshana4046662011-03-07 17:05:15 +0800465
466EQMP
467
468 {
Stefano Stabellinia7ae8352012-01-25 12:24:51 +0000469 .name = "xen-save-devices-state",
470 .args_type = "filename:F",
471 .mhandler.cmd_new = qmp_marshal_input_xen_save_devices_state,
472 },
473
474SQMP
475xen-save-devices-state
476-------
477
478Save the state of all devices to file. The RAM and the block devices
479of the VM are not saved by this command.
480
481Arguments:
482
483- "filename": the file to save the state of the devices to as binary
484data. See xen-save-devices-state.txt for a description of the binary
485format.
486
487Example:
488
489-> { "execute": "xen-save-devices-state",
490 "arguments": { "filename": "/tmp/save" } }
491<- { "return": {} }
492
493EQMP
494
495 {
Anthony PERARD39f42432012-10-03 13:48:19 +0000496 .name = "xen-set-global-dirty-log",
497 .args_type = "enable:b",
498 .mhandler.cmd_new = qmp_marshal_input_xen_set_global_dirty_log,
499 },
500
501SQMP
502xen-set-global-dirty-log
503-------
504
505Enable or disable the global dirty log mode.
506
507Arguments:
508
509- "enable": Enable it or disable it.
510
511Example:
512
513-> { "execute": "xen-set-global-dirty-log",
514 "arguments": { "enable": true } }
515<- { "return": {} }
516
517EQMP
518
519 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300520 .name = "migrate",
521 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
Luiz Capitulinoe1c37d02011-12-05 14:48:01 -0200522 .mhandler.cmd_new = qmp_marshal_input_migrate,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300523 },
524
525SQMP
526migrate
527-------
528
529Migrate to URI.
530
531Arguments:
532
533- "blk": block migration, full disk copy (json-bool, optional)
534- "inc": incremental disk copy (json-bool, optional)
535- "uri": Destination URI (json-string)
536
537Example:
538
539-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
540<- { "return": {} }
541
542Notes:
543
544(1) The 'query-migrate' command should be used to check migration's progress
545 and final result (this information is provided by the 'status' member)
546(2) All boolean arguments default to false
547(3) The user Monitor's "detach" argument is invalid in QMP and should not
548 be used
549
550EQMP
551
552 {
553 .name = "migrate_cancel",
554 .args_type = "",
Luiz Capitulino6cdedb02011-11-27 22:54:09 -0200555 .mhandler.cmd_new = qmp_marshal_input_migrate_cancel,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300556 },
557
558SQMP
559migrate_cancel
560--------------
561
562Cancel the current migration.
563
564Arguments: None.
565
566Example:
567
568-> { "execute": "migrate_cancel" }
569<- { "return": {} }
570
571EQMP
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300572{
573 .name = "migrate-set-cache-size",
574 .args_type = "value:o",
575 .mhandler.cmd_new = qmp_marshal_input_migrate_set_cache_size,
576 },
577
578SQMP
579migrate-set-cache-size
580---------------------
581
582Set cache size to be used by XBZRLE migration, the cache size will be rounded
583down to the nearest power of 2
584
585Arguments:
586
587- "value": cache size in bytes (json-int)
588
589Example:
590
591-> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
592<- { "return": {} }
593
594EQMP
595 {
596 .name = "query-migrate-cache-size",
597 .args_type = "",
598 .mhandler.cmd_new = qmp_marshal_input_query_migrate_cache_size,
599 },
600
601SQMP
602query-migrate-cache-size
603---------------------
604
605Show cache size to be used by XBZRLE migration
606
607returns a json-object with the following information:
608- "size" : json-int
609
610Example:
611
612-> { "execute": "query-migrate-cache-size" }
613<- { "return": 67108864 }
614
615EQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300616
617 {
618 .name = "migrate_set_speed",
Wen Congyang3a019b62010-11-25 09:06:05 +0800619 .args_type = "value:o",
Luiz Capitulino3dc85382011-11-28 11:59:37 -0200620 .mhandler.cmd_new = qmp_marshal_input_migrate_set_speed,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300621 },
622
623SQMP
624migrate_set_speed
625-----------------
626
627Set maximum speed for migrations.
628
629Arguments:
630
Luiz Capitulino5569fd72010-12-15 17:56:18 -0200631- "value": maximum speed, in bytes per second (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300632
633Example:
634
635-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
636<- { "return": {} }
637
638EQMP
639
640 {
641 .name = "migrate_set_downtime",
642 .args_type = "value:T",
Luiz Capitulino4f0a9932011-11-27 23:18:01 -0200643 .mhandler.cmd_new = qmp_marshal_input_migrate_set_downtime,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300644 },
645
646SQMP
647migrate_set_downtime
648--------------------
649
650Set maximum tolerated downtime (in seconds) for migrations.
651
652Arguments:
653
654- "value": maximum downtime (json-number)
655
656Example:
657
658-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
659<- { "return": {} }
660
661EQMP
662
663 {
Jes Sorensenff73edf2011-03-09 14:31:06 +0100664 .name = "client_migrate_info",
665 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
666 .params = "protocol hostname port tls-port cert-subject",
667 .help = "send migration info to spice/vnc client",
668 .user_print = monitor_user_noop,
Yonit Halperinedc5cb12011-10-17 10:03:18 +0200669 .mhandler.cmd_async = client_migrate_info,
670 .flags = MONITOR_CMD_ASYNC,
Jes Sorensenff73edf2011-03-09 14:31:06 +0100671 },
672
673SQMP
674client_migrate_info
675------------------
676
677Set the spice/vnc connection info for the migration target. The spice/vnc
678server will ask the spice/vnc client to automatically reconnect using the
679new parameters (if specified) once the vm migration finished successfully.
680
681Arguments:
682
683- "protocol": protocol: "spice" or "vnc" (json-string)
684- "hostname": migration target hostname (json-string)
685- "port": spice/vnc tcp port for plaintext channels (json-int, optional)
686- "tls-port": spice tcp port for tls-secured channels (json-int, optional)
687- "cert-subject": server certificate subject (json-string, optional)
688
689Example:
690
691-> { "execute": "client_migrate_info",
692 "arguments": { "protocol": "spice",
693 "hostname": "virt42.lab.kraxel.org",
694 "port": 1234 } }
695<- { "return": {} }
696
697EQMP
698
699 {
Wen Congyang783e9b42012-05-07 12:10:47 +0800700 .name = "dump-guest-memory",
701 .args_type = "paging:b,protocol:s,begin:i?,end:i?",
702 .params = "-p protocol [begin] [length]",
703 .help = "dump guest memory to file",
704 .user_print = monitor_user_noop,
705 .mhandler.cmd_new = qmp_marshal_input_dump_guest_memory,
706 },
707
708SQMP
709dump
710
711
712Dump guest memory to file. The file can be processed with crash or gdb.
713
714Arguments:
715
716- "paging": do paging to get guest's memory mapping (json-bool)
717- "protocol": destination file(started with "file:") or destination file
718 descriptor (started with "fd:") (json-string)
719- "begin": the starting physical address. It's optional, and should be specified
720 with length together (json-int)
721- "length": the memory size, in bytes. It's optional, and should be specified
722 with begin together (json-int)
723
724Example:
725
726-> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
727<- { "return": {} }
728
729Notes:
730
731(1) All boolean arguments default to false
732
733EQMP
734
735 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300736 .name = "netdev_add",
737 .args_type = "netdev:O",
Luiz Capitulino928059a2012-04-18 17:34:15 -0300738 .mhandler.cmd_new = qmp_netdev_add,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300739 },
740
741SQMP
742netdev_add
743----------
744
745Add host network device.
746
747Arguments:
748
749- "type": the device type, "tap", "user", ... (json-string)
750- "id": the device's ID, must be unique (json-string)
751- device options
752
753Example:
754
755-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
756<- { "return": {} }
757
758Note: The supported device options are the same ones supported by the '-net'
759 command-line argument, which are listed in the '-help' output or QEMU's
760 manual
761
762EQMP
763
764 {
765 .name = "netdev_del",
766 .args_type = "id:s",
Luiz Capitulino5f964152012-04-16 14:36:32 -0300767 .mhandler.cmd_new = qmp_marshal_input_netdev_del,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300768 },
769
770SQMP
771netdev_del
772----------
773
774Remove host network device.
775
776Arguments:
777
778- "id": the device's ID, must be unique (json-string)
779
780Example:
781
782-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
783<- { "return": {} }
784
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +0100785
786EQMP
787
788 {
789 .name = "block_resize",
790 .args_type = "device:B,size:o",
Luiz Capitulino5e7caac2011-11-25 14:57:10 -0200791 .mhandler.cmd_new = qmp_marshal_input_block_resize,
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +0100792 },
793
794SQMP
795block_resize
796------------
797
798Resize a block image while a guest is running.
799
800Arguments:
801
802- "device": the device's ID, must be unique (json-string)
803- "size": new size
804
805Example:
806
807-> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
808<- { "return": {} }
809
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300810EQMP
811
812 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +0100813 .name = "block-stream",
Paolo Bonzini1d809092012-09-28 17:22:59 +0200814 .args_type = "device:B,base:s?,speed:o?,on-error:s?",
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +0000815 .mhandler.cmd_new = qmp_marshal_input_block_stream,
816 },
817
818 {
Jeff Codyed61fc12012-09-27 13:29:16 -0400819 .name = "block-commit",
820 .args_type = "device:B,base:s?,top:s,speed:o?",
821 .mhandler.cmd_new = qmp_marshal_input_block_commit,
822 },
823
824 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +0100825 .name = "block-job-set-speed",
Stefan Hajnoczi882ec7c2012-04-25 16:51:02 +0100826 .args_type = "device:B,speed:o",
Stefan Hajnoczi2d47c6e2012-01-18 14:40:47 +0000827 .mhandler.cmd_new = qmp_marshal_input_block_job_set_speed,
828 },
829
830 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +0100831 .name = "block-job-cancel",
Paolo Bonzini6e37fb82012-09-28 17:22:51 +0200832 .args_type = "device:B,force:b?",
Stefan Hajnoczi370521a2012-01-18 14:40:48 +0000833 .mhandler.cmd_new = qmp_marshal_input_block_job_cancel,
834 },
Jeff Codyc1864022012-02-28 15:54:07 -0500835 {
Paolo Bonzini6e37fb82012-09-28 17:22:51 +0200836 .name = "block-job-pause",
837 .args_type = "device:B",
838 .mhandler.cmd_new = qmp_marshal_input_block_job_pause,
839 },
840 {
841 .name = "block-job-resume",
842 .args_type = "device:B",
843 .mhandler.cmd_new = qmp_marshal_input_block_job_resume,
844 },
845 {
Paolo Bonziniaeae8832012-10-18 16:49:21 +0200846 .name = "block-job-complete",
847 .args_type = "device:B",
848 .mhandler.cmd_new = qmp_marshal_input_block_job_complete,
849 },
850 {
Paolo Bonzini52e7c242012-03-06 18:55:57 +0100851 .name = "transaction",
Paolo Bonzinib9f89782012-03-22 12:51:11 +0100852 .args_type = "actions:q",
Paolo Bonzini52e7c242012-03-06 18:55:57 +0100853 .mhandler.cmd_new = qmp_marshal_input_transaction,
Jeff Codyc1864022012-02-28 15:54:07 -0500854 },
855
856SQMP
Paolo Bonzini52e7c242012-03-06 18:55:57 +0100857transaction
858-----------
Jeff Codyc1864022012-02-28 15:54:07 -0500859
Paolo Bonzini52e7c242012-03-06 18:55:57 +0100860Atomically operate on one or more block devices. The only supported
861operation for now is snapshotting. If there is any failure performing
862any of the operations, all snapshots for the group are abandoned, and
863the original disks pre-snapshot attempt are used.
Jeff Codyc1864022012-02-28 15:54:07 -0500864
Paolo Bonzini52e7c242012-03-06 18:55:57 +0100865A list of dictionaries is accepted, that contains the actions to be performed.
866For snapshots this is the device, the file to use for the new snapshot,
867and the format. The default format, if not specified, is qcow2.
Jeff Codyc1864022012-02-28 15:54:07 -0500868
Paolo Bonzinibc8b0942012-03-06 18:55:58 +0100869Each new snapshot defaults to being created by QEMU (wiping any
870contents if the file already exists), but it is also possible to reuse
871an externally-created file. In the latter case, you should ensure that
872the new image file has the same contents as the current one; QEMU cannot
873perform any meaningful check. Typically this is achieved by using the
874current image file as the backing file for the new image.
875
Jeff Codyc1864022012-02-28 15:54:07 -0500876Arguments:
877
Paolo Bonzini52e7c242012-03-06 18:55:57 +0100878actions array:
879 - "type": the operation to perform. The only supported
880 value is "blockdev-snapshot-sync". (json-string)
881 - "data": a dictionary. The contents depend on the value
882 of "type". When "type" is "blockdev-snapshot-sync":
883 - "device": device name to snapshot (json-string)
884 - "snapshot-file": name of new image file (json-string)
885 - "format": format of new image (json-string, optional)
Paolo Bonzinibc8b0942012-03-06 18:55:58 +0100886 - "mode": whether and how QEMU should create the snapshot file
887 (NewImageMode, optional, default "absolute-paths")
Jeff Codyc1864022012-02-28 15:54:07 -0500888
889Example:
890
Paolo Bonzini52e7c242012-03-06 18:55:57 +0100891-> { "execute": "transaction",
892 "arguments": { "actions": [
893 { 'type': 'blockdev-snapshot-sync', 'data' : { "device": "ide-hd0",
894 "snapshot-file": "/some/place/my-image",
895 "format": "qcow2" } },
896 { 'type': 'blockdev-snapshot-sync', 'data' : { "device": "ide-hd1",
897 "snapshot-file": "/some/place/my-image2",
Paolo Bonzinibc8b0942012-03-06 18:55:58 +0100898 "mode": "existing",
Paolo Bonzini52e7c242012-03-06 18:55:57 +0100899 "format": "qcow2" } } ] } }
Jeff Codyc1864022012-02-28 15:54:07 -0500900<- { "return": {} }
901
902EQMP
Stefan Hajnoczi370521a2012-01-18 14:40:48 +0000903
904 {
Jes Sorensend967b2f2011-07-11 20:01:09 +0200905 .name = "blockdev-snapshot-sync",
Paolo Bonzini31155b92012-04-12 14:00:58 +0200906 .args_type = "device:B,snapshot-file:s,format:s?,mode:s?",
Luiz Capitulino6106e242011-11-25 16:15:19 -0200907 .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_sync,
Jes Sorensend967b2f2011-07-11 20:01:09 +0200908 },
909
910SQMP
911blockdev-snapshot-sync
912----------------------
913
914Synchronous snapshot of a block device. snapshot-file specifies the
915target of the new image. If the file exists, or if it is a device, the
916snapshot will be created in the existing file/device. If does not
917exist, a new file will be created. format specifies the format of the
918snapshot image, default is qcow2.
919
920Arguments:
921
922- "device": device name to snapshot (json-string)
923- "snapshot-file": name of new image file (json-string)
Paolo Bonzini6cc2a412012-03-06 18:55:59 +0100924- "mode": whether and how QEMU should create the snapshot file
925 (NewImageMode, optional, default "absolute-paths")
Jes Sorensend967b2f2011-07-11 20:01:09 +0200926- "format": format of new image (json-string, optional)
927
928Example:
929
Luiz Capitulino7f3850c2011-10-10 17:30:08 -0300930-> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
931 "snapshot-file":
932 "/some/place/my-image",
933 "format": "qcow2" } }
Jes Sorensend967b2f2011-07-11 20:01:09 +0200934<- { "return": {} }
935
936EQMP
937
938 {
Paolo Bonzinid9b902d2012-10-18 16:49:24 +0200939 .name = "drive-mirror",
Paolo Bonzinib952b552012-10-18 16:49:28 +0200940 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
941 "on-source-error:s?,on-target-error:s?",
Paolo Bonzinid9b902d2012-10-18 16:49:24 +0200942 .mhandler.cmd_new = qmp_marshal_input_drive_mirror,
943 },
944
945SQMP
946drive-mirror
947------------
948
949Start mirroring a block device's writes to a new destination. target
950specifies the target of the new image. If the file exists, or if it is
951a device, it will be used as the new destination for writes. If it does not
952exist, a new file will be created. format specifies the format of the
953mirror image, default is to probe if mode='existing', else the format
954of the source.
955
956Arguments:
957
958- "device": device name to operate on (json-string)
959- "target": name of new image file (json-string)
960- "format": format of new image (json-string, optional)
961- "mode": how an image file should be created into the target
962 file/device (NewImageMode, optional, default 'absolute-paths')
963- "speed": maximum speed of the streaming job, in bytes per second
964 (json-int)
965- "sync": what parts of the disk image should be copied to the destination;
966 possibilities include "full" for all the disk, "top" for only the sectors
967 allocated in the topmost image, or "none" to only replicate new I/O
968 (MirrorSyncMode).
Paolo Bonzinib952b552012-10-18 16:49:28 +0200969- "on-source-error": the action to take on an error on the source
970 (BlockdevOnError, default 'report')
971- "on-target-error": the action to take on an error on the target
972 (BlockdevOnError, default 'report')
973
Paolo Bonzinid9b902d2012-10-18 16:49:24 +0200974
975
976Example:
977
978-> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
979 "target": "/some/place/my-image",
980 "sync": "full",
981 "format": "qcow2" } }
982<- { "return": {} }
983
984EQMP
985
986 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300987 .name = "balloon",
988 .args_type = "value:M",
Luiz Capitulinod72f3262011-11-25 14:38:09 -0200989 .mhandler.cmd_new = qmp_marshal_input_balloon,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300990 },
991
992SQMP
993balloon
994-------
995
996Request VM to change its memory allocation (in bytes).
997
998Arguments:
999
1000- "value": New memory allocation (json-int)
1001
1002Example:
1003
1004-> { "execute": "balloon", "arguments": { "value": 536870912 } }
1005<- { "return": {} }
1006
1007EQMP
1008
1009 {
1010 .name = "set_link",
1011 .args_type = "name:s,up:b",
Luiz Capitulino4b371562011-11-23 13:11:55 -02001012 .mhandler.cmd_new = qmp_marshal_input_set_link,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001013 },
1014
1015SQMP
1016set_link
1017--------
1018
1019Change the link status of a network adapter.
1020
1021Arguments:
1022
1023- "name": network device name (json-string)
1024- "up": status is up (json-bool)
1025
1026Example:
1027
1028-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1029<- { "return": {} }
1030
1031EQMP
1032
1033 {
1034 .name = "getfd",
1035 .args_type = "fdname:s",
1036 .params = "getfd name",
1037 .help = "receive a file descriptor via SCM rights and assign it a name",
Corey Bryant208c9d12012-06-22 14:36:09 -04001038 .mhandler.cmd_new = qmp_marshal_input_getfd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001039 },
1040
1041SQMP
1042getfd
1043-----
1044
1045Receive a file descriptor via SCM rights and assign it a name.
1046
1047Arguments:
1048
1049- "fdname": file descriptor name (json-string)
1050
1051Example:
1052
1053-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1054<- { "return": {} }
1055
Corey Bryant208c9d12012-06-22 14:36:09 -04001056Notes:
1057
1058(1) If the name specified by the "fdname" argument already exists,
1059 the file descriptor assigned to it will be closed and replaced
1060 by the received file descriptor.
1061(2) The 'closefd' command can be used to explicitly close the file
1062 descriptor when it is no longer needed.
1063
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001064EQMP
1065
1066 {
1067 .name = "closefd",
1068 .args_type = "fdname:s",
1069 .params = "closefd name",
1070 .help = "close a file descriptor previously passed via SCM rights",
Corey Bryant208c9d12012-06-22 14:36:09 -04001071 .mhandler.cmd_new = qmp_marshal_input_closefd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001072 },
1073
1074SQMP
1075closefd
1076-------
1077
1078Close a file descriptor previously passed via SCM rights.
1079
1080Arguments:
1081
1082- "fdname": file descriptor name (json-string)
1083
1084Example:
1085
1086-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1087<- { "return": {} }
1088
1089EQMP
1090
Corey Bryantba1c0482012-08-14 16:43:43 -04001091 {
1092 .name = "add-fd",
1093 .args_type = "fdset-id:i?,opaque:s?",
1094 .params = "add-fd fdset-id opaque",
1095 .help = "Add a file descriptor, that was passed via SCM rights, to an fd set",
1096 .mhandler.cmd_new = qmp_marshal_input_add_fd,
1097 },
1098
1099SQMP
1100add-fd
1101-------
1102
1103Add a file descriptor, that was passed via SCM rights, to an fd set.
1104
1105Arguments:
1106
1107- "fdset-id": The ID of the fd set to add the file descriptor to.
1108 (json-int, optional)
1109- "opaque": A free-form string that can be used to describe the fd.
1110 (json-string, optional)
1111
1112Return a json-object with the following information:
1113
1114- "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1115- "fd": The file descriptor that was received via SCM rights and added to the
1116 fd set. (json-int)
1117
1118Example:
1119
1120-> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1121<- { "return": { "fdset-id": 1, "fd": 3 } }
1122
1123Notes:
1124
1125(1) The list of fd sets is shared by all monitor connections.
1126(2) If "fdset-id" is not specified, a new fd set will be created.
1127
1128EQMP
1129
1130 {
1131 .name = "remove-fd",
1132 .args_type = "fdset-id:i,fd:i?",
1133 .params = "remove-fd fdset-id fd",
1134 .help = "Remove a file descriptor from an fd set",
1135 .mhandler.cmd_new = qmp_marshal_input_remove_fd,
1136 },
1137
1138SQMP
1139remove-fd
1140---------
1141
1142Remove a file descriptor from an fd set.
1143
1144Arguments:
1145
1146- "fdset-id": The ID of the fd set that the file descriptor belongs to.
1147 (json-int)
1148- "fd": The file descriptor that is to be removed. (json-int, optional)
1149
1150Example:
1151
1152-> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1153<- { "return": {} }
1154
1155Notes:
1156
1157(1) The list of fd sets is shared by all monitor connections.
1158(2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1159 removed.
1160
1161EQMP
1162
1163 {
1164 .name = "query-fdsets",
1165 .args_type = "",
1166 .help = "Return information describing all fd sets",
1167 .mhandler.cmd_new = qmp_marshal_input_query_fdsets,
1168 },
1169
1170SQMP
1171query-fdsets
1172-------------
1173
1174Return information describing all fd sets.
1175
1176Arguments: None
1177
1178Example:
1179
1180-> { "execute": "query-fdsets" }
1181<- { "return": [
1182 {
1183 "fds": [
1184 {
1185 "fd": 30,
1186 "opaque": "rdonly:/path/to/file"
1187 },
1188 {
1189 "fd": 24,
1190 "opaque": "rdwr:/path/to/file"
1191 }
1192 ],
1193 "fdset-id": 1
1194 },
1195 {
1196 "fds": [
1197 {
1198 "fd": 28
1199 },
1200 {
1201 "fd": 29
1202 }
1203 ],
1204 "fdset-id": 0
1205 }
1206 ]
1207 }
1208
1209Note: The list of fd sets is shared by all monitor connections.
1210
1211EQMP
1212
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001213 {
1214 .name = "block_passwd",
1215 .args_type = "device:B,password:s",
Luiz Capitulinoa4dea8a2011-11-23 13:28:21 -02001216 .mhandler.cmd_new = qmp_marshal_input_block_passwd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001217 },
1218
1219SQMP
1220block_passwd
1221------------
1222
1223Set the password of encrypted block devices.
1224
1225Arguments:
1226
1227- "device": device name (json-string)
1228- "password": password (json-string)
1229
1230Example:
1231
1232-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1233 "password": "12345" } }
1234<- { "return": {} }
1235
1236EQMP
1237
1238 {
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001239 .name = "block_set_io_throttle",
1240 .args_type = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
Luiz Capitulino80047da2011-12-14 16:49:14 -02001241 .mhandler.cmd_new = qmp_marshal_input_block_set_io_throttle,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001242 },
1243
1244SQMP
1245block_set_io_throttle
1246------------
1247
1248Change I/O throttle limits for a block drive.
1249
1250Arguments:
1251
1252- "device": device name (json-string)
1253- "bps": total throughput limit in bytes per second(json-int)
1254- "bps_rd": read throughput limit in bytes per second(json-int)
1255- "bps_wr": read throughput limit in bytes per second(json-int)
1256- "iops": total I/O operations per second(json-int)
1257- "iops_rd": read I/O operations per second(json-int)
1258- "iops_wr": write I/O operations per second(json-int)
1259
1260Example:
1261
1262-> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
1263 "bps": "1000000",
1264 "bps_rd": "0",
1265 "bps_wr": "0",
1266 "iops": "0",
1267 "iops_rd": "0",
1268 "iops_wr": "0" } }
1269<- { "return": {} }
1270
1271EQMP
1272
1273 {
Gerd Hoffmann75721502010-10-07 12:22:54 +02001274 .name = "set_password",
1275 .args_type = "protocol:s,password:s,connected:s?",
Luiz Capitulinofbf796f2011-12-07 11:17:51 -02001276 .mhandler.cmd_new = qmp_marshal_input_set_password,
Gerd Hoffmann75721502010-10-07 12:22:54 +02001277 },
1278
1279SQMP
1280set_password
1281------------
1282
1283Set the password for vnc/spice protocols.
1284
1285Arguments:
1286
1287- "protocol": protocol name (json-string)
1288- "password": password (json-string)
1289- "connected": [ keep | disconnect | fail ] (josn-string, optional)
1290
1291Example:
1292
1293-> { "execute": "set_password", "arguments": { "protocol": "vnc",
1294 "password": "secret" } }
1295<- { "return": {} }
1296
1297EQMP
1298
1299 {
1300 .name = "expire_password",
1301 .args_type = "protocol:s,time:s",
Luiz Capitulino9ad53722011-12-07 11:47:57 -02001302 .mhandler.cmd_new = qmp_marshal_input_expire_password,
Gerd Hoffmann75721502010-10-07 12:22:54 +02001303 },
1304
1305SQMP
1306expire_password
1307---------------
1308
1309Set the password expire time for vnc/spice protocols.
1310
1311Arguments:
1312
1313- "protocol": protocol name (json-string)
1314- "time": [ now | never | +secs | secs ] (json-string)
1315
1316Example:
1317
1318-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1319 "time": "+60" } }
1320<- { "return": {} }
1321
1322EQMP
1323
1324 {
Daniel P. Berrange13661082011-06-23 13:31:42 +01001325 .name = "add_client",
Daniel P. Berrangef1f5f402012-02-13 13:43:08 +00001326 .args_type = "protocol:s,fdname:s,skipauth:b?,tls:b?",
Luiz Capitulinob224e5e2012-09-13 16:52:20 -03001327 .mhandler.cmd_new = qmp_marshal_input_add_client,
Daniel P. Berrange13661082011-06-23 13:31:42 +01001328 },
1329
1330SQMP
1331add_client
1332----------
1333
1334Add a graphics client
1335
1336Arguments:
1337
1338- "protocol": protocol name (json-string)
1339- "fdname": file descriptor name (json-string)
Daniel P. Berrangef1f5f402012-02-13 13:43:08 +00001340- "skipauth": whether to skip authentication (json-bool, optional)
1341- "tls": whether to perform TLS (json-bool, optional)
Daniel P. Berrange13661082011-06-23 13:31:42 +01001342
1343Example:
1344
1345-> { "execute": "add_client", "arguments": { "protocol": "vnc",
1346 "fdname": "myclient" } }
1347<- { "return": {} }
1348
1349EQMP
1350 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001351 .name = "qmp_capabilities",
1352 .args_type = "",
1353 .params = "",
1354 .help = "enable QMP capabilities",
1355 .user_print = monitor_user_noop,
1356 .mhandler.cmd_new = do_qmp_capabilities,
1357 },
1358
1359SQMP
1360qmp_capabilities
1361----------------
1362
1363Enable QMP capabilities.
1364
1365Arguments: None.
1366
1367Example:
1368
1369-> { "execute": "qmp_capabilities" }
1370<- { "return": {} }
1371
1372Note: This command must be issued before issuing any other command.
1373
Luiz Capitulino0268d972010-10-22 10:08:02 -02001374EQMP
1375
1376 {
1377 .name = "human-monitor-command",
1378 .args_type = "command-line:s,cpu-index:i?",
Luiz Capitulinod51a67b2011-11-25 17:52:45 -02001379 .mhandler.cmd_new = qmp_marshal_input_human_monitor_command,
Luiz Capitulino0268d972010-10-22 10:08:02 -02001380 },
1381
1382SQMP
1383human-monitor-command
1384---------------------
1385
1386Execute a Human Monitor command.
1387
1388Arguments:
1389
1390- command-line: the command name and its arguments, just like the
1391 Human Monitor's shell (json-string)
1392- cpu-index: select the CPU number to be used by commands which access CPU
1393 data, like 'info registers'. The Monitor selects CPU 0 if this
1394 argument is not provided (json-int, optional)
1395
1396Example:
1397
1398-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1399<- { "return": "kvm support: enabled\r\n" }
1400
1401Notes:
1402
1403(1) The Human Monitor is NOT an stable interface, this means that command
1404 names, arguments and responses can change or be removed at ANY time.
1405 Applications that rely on long term stability guarantees should NOT
1406 use this command
1407
1408(2) Limitations:
1409
1410 o This command is stateless, this means that commands that depend
1411 on state information (such as getfd) might not work
1412
1413 o Commands that prompt the user for data (eg. 'cont' when the block
1414 device is encrypted) don't currently work
1415
Luiz Capitulino82a56f02010-09-13 12:26:00 -030014163. Query Commands
1417=================
1418
1419HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
1420HXCOMM this! We will possibly move query commands definitions inside those
1421HXCOMM sections, just like regular commands.
1422
1423EQMP
1424
1425SQMP
1426query-version
1427-------------
1428
1429Show QEMU version.
1430
1431Return a json-object with the following information:
1432
1433- "qemu": A json-object containing three integer values:
1434 - "major": QEMU's major version (json-int)
1435 - "minor": QEMU's minor version (json-int)
1436 - "micro": QEMU's micro version (json-int)
1437- "package": package's version (json-string)
1438
1439Example:
1440
1441-> { "execute": "query-version" }
1442<- {
1443 "return":{
1444 "qemu":{
1445 "major":0,
1446 "minor":11,
1447 "micro":5
1448 },
1449 "package":""
1450 }
1451 }
1452
1453EQMP
1454
Luiz Capitulinob9c15f12011-08-26 17:38:13 -03001455 {
1456 .name = "query-version",
1457 .args_type = "",
1458 .mhandler.cmd_new = qmp_marshal_input_query_version,
1459 },
1460
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001461SQMP
1462query-commands
1463--------------
1464
1465List QMP available commands.
1466
1467Each command is represented by a json-object, the returned value is a json-array
1468of all commands.
1469
1470Each json-object contain:
1471
1472- "name": command's name (json-string)
1473
1474Example:
1475
1476-> { "execute": "query-commands" }
1477<- {
1478 "return":[
1479 {
1480 "name":"query-balloon"
1481 },
1482 {
1483 "name":"system_powerdown"
1484 }
1485 ]
1486 }
1487
1488Note: This example has been shortened as the real response is too long.
1489
1490EQMP
1491
Luiz Capitulinoaa9b79b2011-09-21 14:31:51 -03001492 {
1493 .name = "query-commands",
1494 .args_type = "",
1495 .mhandler.cmd_new = qmp_marshal_input_query_commands,
1496 },
1497
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001498SQMP
Daniel P. Berrange48608532012-05-21 17:59:51 +01001499query-events
1500--------------
1501
1502List QMP available events.
1503
1504Each event is represented by a json-object, the returned value is a json-array
1505of all events.
1506
1507Each json-object contains:
1508
1509- "name": event's name (json-string)
1510
1511Example:
1512
1513-> { "execute": "query-events" }
1514<- {
1515 "return":[
1516 {
1517 "name":"SHUTDOWN"
1518 },
1519 {
1520 "name":"RESET"
1521 }
1522 ]
1523 }
1524
1525Note: This example has been shortened as the real response is too long.
1526
1527EQMP
1528
1529 {
1530 .name = "query-events",
1531 .args_type = "",
1532 .mhandler.cmd_new = qmp_marshal_input_query_events,
1533 },
1534
1535SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001536query-chardev
1537-------------
1538
1539Each device is represented by a json-object. The returned value is a json-array
1540of all devices.
1541
1542Each json-object contain the following:
1543
1544- "label": device's label (json-string)
1545- "filename": device's file (json-string)
1546
1547Example:
1548
1549-> { "execute": "query-chardev" }
1550<- {
1551 "return":[
1552 {
1553 "label":"monitor",
1554 "filename":"stdio"
1555 },
1556 {
1557 "label":"serial0",
1558 "filename":"vc"
1559 }
1560 ]
1561 }
1562
1563EQMP
1564
Luiz Capitulinoc5a415a2011-09-14 16:05:49 -03001565 {
1566 .name = "query-chardev",
1567 .args_type = "",
1568 .mhandler.cmd_new = qmp_marshal_input_query_chardev,
1569 },
1570
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001571SQMP
1572query-block
1573-----------
1574
1575Show the block devices.
1576
1577Each block device information is stored in a json-object and the returned value
1578is a json-array of all devices.
1579
1580Each json-object contain the following:
1581
1582- "device": device name (json-string)
1583- "type": device type (json-string)
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001584 - deprecated, retained for backward compatibility
1585 - Possible values: "unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001586- "removable": true if the device is removable, false otherwise (json-bool)
1587- "locked": true if the device is locked, false otherwise (json-bool)
Markus Armbrustere4def802011-09-06 18:58:53 +02001588- "tray-open": only present if removable, true if the device has a tray,
1589 and it is open (json-bool)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001590- "inserted": only present if the device is inserted, it is a json-object
1591 containing the following:
1592 - "file": device file name (json-string)
1593 - "ro": true if read-only, false otherwise (json-bool)
1594 - "drv": driver format name (json-string)
1595 - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1596 "file", "file", "ftp", "ftps", "host_cdrom",
1597 "host_device", "host_floppy", "http", "https",
1598 "nbd", "parallels", "qcow", "qcow2", "raw",
1599 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1600 - "backing_file": backing file name (json-string, optional)
Benoît Canet2e3e3312012-08-02 10:22:48 +02001601 - "backing_file_depth": number of files in the backing file chain (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001602 - "encrypted": true if encrypted, false otherwise (json-bool)
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001603 - "bps": limit total bytes per second (json-int)
1604 - "bps_rd": limit read bytes per second (json-int)
1605 - "bps_wr": limit write bytes per second (json-int)
1606 - "iops": limit total I/O operations per second (json-int)
1607 - "iops_rd": limit read operations per second (json-int)
1608 - "iops_wr": limit write operations per second (json-int)
1609
Luiz Capitulinof04ef602011-09-26 17:43:54 -03001610- "io-status": I/O operation status, only present if the device supports it
1611 and the VM is configured to stop on errors. It's always reset
1612 to "ok" when the "cont" command is issued (json_string, optional)
1613 - Possible values: "ok", "failed", "nospace"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001614
1615Example:
1616
1617-> { "execute": "query-block" }
1618<- {
1619 "return":[
1620 {
Luiz Capitulinof04ef602011-09-26 17:43:54 -03001621 "io-status": "ok",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001622 "device":"ide0-hd0",
1623 "locked":false,
1624 "removable":false,
1625 "inserted":{
1626 "ro":false,
1627 "drv":"qcow2",
1628 "encrypted":false,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001629 "file":"disks/test.img",
Benoît Canet2e3e3312012-08-02 10:22:48 +02001630 "backing_file_depth":0,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001631 "bps":1000000,
1632 "bps_rd":0,
1633 "bps_wr":0,
1634 "iops":1000000,
1635 "iops_rd":0,
1636 "iops_wr":0,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001637 },
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001638 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001639 },
1640 {
Luiz Capitulinof04ef602011-09-26 17:43:54 -03001641 "io-status": "ok",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001642 "device":"ide1-cd0",
1643 "locked":false,
1644 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001645 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001646 },
1647 {
1648 "device":"floppy0",
1649 "locked":false,
1650 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001651 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001652 },
1653 {
1654 "device":"sd0",
1655 "locked":false,
1656 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001657 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001658 }
1659 ]
1660 }
1661
1662EQMP
1663
Luiz Capitulinob2023812011-09-21 17:16:47 -03001664 {
1665 .name = "query-block",
1666 .args_type = "",
1667 .mhandler.cmd_new = qmp_marshal_input_query_block,
1668 },
1669
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001670SQMP
1671query-blockstats
1672----------------
1673
1674Show block device statistics.
1675
1676Each device statistic information is stored in a json-object and the returned
1677value is a json-array of all devices.
1678
1679Each json-object contain the following:
1680
1681- "device": device name (json-string)
1682- "stats": A json-object with the statistics information, it contains:
1683 - "rd_bytes": bytes read (json-int)
1684 - "wr_bytes": bytes written (json-int)
1685 - "rd_operations": read operations (json-int)
1686 - "wr_operations": write operations (json-int)
Christoph Hellwige8045d62011-08-22 00:25:58 +02001687 - "flush_operations": cache flush operations (json-int)
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001688 - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1689 - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1690 - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001691 - "wr_highest_offset": Highest offset of a sector written since the
1692 BlockDriverState has been opened (json-int)
1693- "parent": Contains recursively the statistics of the underlying
1694 protocol (e.g. the host file for a qcow2 image). If there is
1695 no underlying protocol, this field is omitted
1696 (json-object, optional)
1697
1698Example:
1699
1700-> { "execute": "query-blockstats" }
1701<- {
1702 "return":[
1703 {
1704 "device":"ide0-hd0",
1705 "parent":{
1706 "stats":{
1707 "wr_highest_offset":3686448128,
1708 "wr_bytes":9786368,
1709 "wr_operations":751,
1710 "rd_bytes":122567168,
1711 "rd_operations":36772
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001712 "wr_total_times_ns":313253456
1713 "rd_total_times_ns":3465673657
1714 "flush_total_times_ns":49653
Christoph Hellwige8045d62011-08-22 00:25:58 +02001715 "flush_operations":61,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001716 }
1717 },
1718 "stats":{
1719 "wr_highest_offset":2821110784,
1720 "wr_bytes":9786368,
1721 "wr_operations":692,
1722 "rd_bytes":122739200,
1723 "rd_operations":36604
Christoph Hellwige8045d62011-08-22 00:25:58 +02001724 "flush_operations":51,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001725 "wr_total_times_ns":313253456
1726 "rd_total_times_ns":3465673657
1727 "flush_total_times_ns":49653
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001728 }
1729 },
1730 {
1731 "device":"ide1-cd0",
1732 "stats":{
1733 "wr_highest_offset":0,
1734 "wr_bytes":0,
1735 "wr_operations":0,
1736 "rd_bytes":0,
1737 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02001738 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001739 "wr_total_times_ns":0
1740 "rd_total_times_ns":0
1741 "flush_total_times_ns":0
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001742 }
1743 },
1744 {
1745 "device":"floppy0",
1746 "stats":{
1747 "wr_highest_offset":0,
1748 "wr_bytes":0,
1749 "wr_operations":0,
1750 "rd_bytes":0,
1751 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02001752 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001753 "wr_total_times_ns":0
1754 "rd_total_times_ns":0
1755 "flush_total_times_ns":0
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001756 }
1757 },
1758 {
1759 "device":"sd0",
1760 "stats":{
1761 "wr_highest_offset":0,
1762 "wr_bytes":0,
1763 "wr_operations":0,
1764 "rd_bytes":0,
1765 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02001766 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001767 "wr_total_times_ns":0
1768 "rd_total_times_ns":0
1769 "flush_total_times_ns":0
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001770 }
1771 }
1772 ]
1773 }
1774
1775EQMP
1776
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03001777 {
1778 .name = "query-blockstats",
1779 .args_type = "",
1780 .mhandler.cmd_new = qmp_marshal_input_query_blockstats,
1781 },
1782
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001783SQMP
1784query-cpus
1785----------
1786
1787Show CPU information.
1788
1789Return a json-array. Each CPU is represented by a json-object, which contains:
1790
1791- "CPU": CPU index (json-int)
1792- "current": true if this is the current CPU, false otherwise (json-bool)
1793- "halted": true if the cpu is halted, false otherwise (json-bool)
1794- Current program counter. The key's name depends on the architecture:
1795 "pc": i386/x86_64 (json-int)
1796 "nip": PPC (json-int)
1797 "pc" and "npc": sparc (json-int)
1798 "PC": mips (json-int)
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01001799- "thread_id": ID of the underlying host thread (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001800
1801Example:
1802
1803-> { "execute": "query-cpus" }
1804<- {
1805 "return":[
1806 {
1807 "CPU":0,
1808 "current":true,
1809 "halted":false,
1810 "pc":3227107138
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01001811 "thread_id":3134
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001812 },
1813 {
1814 "CPU":1,
1815 "current":false,
1816 "halted":true,
1817 "pc":7108165
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01001818 "thread_id":3135
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001819 }
1820 ]
1821 }
1822
1823EQMP
1824
Luiz Capitulinode0b36b2011-09-21 16:38:35 -03001825 {
1826 .name = "query-cpus",
1827 .args_type = "",
1828 .mhandler.cmd_new = qmp_marshal_input_query_cpus,
1829 },
1830
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001831SQMP
1832query-pci
1833---------
1834
1835PCI buses and devices information.
1836
1837The returned value is a json-array of all buses. Each bus is represented by
1838a json-object, which has a key with a json-array of all PCI devices attached
1839to it. Each device is represented by a json-object.
1840
1841The bus json-object contains the following:
1842
1843- "bus": bus number (json-int)
1844- "devices": a json-array of json-objects, each json-object represents a
1845 PCI device
1846
1847The PCI device json-object contains the following:
1848
1849- "bus": identical to the parent's bus number (json-int)
1850- "slot": slot number (json-int)
1851- "function": function number (json-int)
1852- "class_info": a json-object containing:
1853 - "desc": device class description (json-string, optional)
1854 - "class": device class number (json-int)
1855- "id": a json-object containing:
1856 - "device": device ID (json-int)
1857 - "vendor": vendor ID (json-int)
1858- "irq": device's IRQ if assigned (json-int, optional)
1859- "qdev_id": qdev id string (json-string)
1860- "pci_bridge": It's a json-object, only present if this device is a
1861 PCI bridge, contains:
1862 - "bus": bus number (json-int)
1863 - "secondary": secondary bus number (json-int)
1864 - "subordinate": subordinate bus number (json-int)
1865 - "io_range": I/O memory range information, a json-object with the
1866 following members:
1867 - "base": base address, in bytes (json-int)
1868 - "limit": limit address, in bytes (json-int)
1869 - "memory_range": memory range information, a json-object with the
1870 following members:
1871 - "base": base address, in bytes (json-int)
1872 - "limit": limit address, in bytes (json-int)
1873 - "prefetchable_range": Prefetchable memory range information, a
1874 json-object with the following members:
1875 - "base": base address, in bytes (json-int)
1876 - "limit": limit address, in bytes (json-int)
1877 - "devices": a json-array of PCI devices if there's any attached, each
1878 each element is represented by a json-object, which contains
1879 the same members of the 'PCI device json-object' described
1880 above (optional)
1881- "regions": a json-array of json-objects, each json-object represents a
1882 memory region of this device
1883
1884The memory range json-object contains the following:
1885
1886- "base": base memory address (json-int)
1887- "limit": limit value (json-int)
1888
1889The region json-object can be an I/O region or a memory region, an I/O region
1890json-object contains the following:
1891
1892- "type": "io" (json-string, fixed)
1893- "bar": BAR number (json-int)
1894- "address": memory address (json-int)
1895- "size": memory size (json-int)
1896
1897A memory region json-object contains the following:
1898
1899- "type": "memory" (json-string, fixed)
1900- "bar": BAR number (json-int)
1901- "address": memory address (json-int)
1902- "size": memory size (json-int)
1903- "mem_type_64": true or false (json-bool)
1904- "prefetch": true or false (json-bool)
1905
1906Example:
1907
1908-> { "execute": "query-pci" }
1909<- {
1910 "return":[
1911 {
1912 "bus":0,
1913 "devices":[
1914 {
1915 "bus":0,
1916 "qdev_id":"",
1917 "slot":0,
1918 "class_info":{
1919 "class":1536,
1920 "desc":"Host bridge"
1921 },
1922 "id":{
1923 "device":32902,
1924 "vendor":4663
1925 },
1926 "function":0,
1927 "regions":[
1928
1929 ]
1930 },
1931 {
1932 "bus":0,
1933 "qdev_id":"",
1934 "slot":1,
1935 "class_info":{
1936 "class":1537,
1937 "desc":"ISA bridge"
1938 },
1939 "id":{
1940 "device":32902,
1941 "vendor":28672
1942 },
1943 "function":0,
1944 "regions":[
1945
1946 ]
1947 },
1948 {
1949 "bus":0,
1950 "qdev_id":"",
1951 "slot":1,
1952 "class_info":{
1953 "class":257,
1954 "desc":"IDE controller"
1955 },
1956 "id":{
1957 "device":32902,
1958 "vendor":28688
1959 },
1960 "function":1,
1961 "regions":[
1962 {
1963 "bar":4,
1964 "size":16,
1965 "address":49152,
1966 "type":"io"
1967 }
1968 ]
1969 },
1970 {
1971 "bus":0,
1972 "qdev_id":"",
1973 "slot":2,
1974 "class_info":{
1975 "class":768,
1976 "desc":"VGA controller"
1977 },
1978 "id":{
1979 "device":4115,
1980 "vendor":184
1981 },
1982 "function":0,
1983 "regions":[
1984 {
1985 "prefetch":true,
1986 "mem_type_64":false,
1987 "bar":0,
1988 "size":33554432,
1989 "address":4026531840,
1990 "type":"memory"
1991 },
1992 {
1993 "prefetch":false,
1994 "mem_type_64":false,
1995 "bar":1,
1996 "size":4096,
1997 "address":4060086272,
1998 "type":"memory"
1999 },
2000 {
2001 "prefetch":false,
2002 "mem_type_64":false,
2003 "bar":6,
2004 "size":65536,
2005 "address":-1,
2006 "type":"memory"
2007 }
2008 ]
2009 },
2010 {
2011 "bus":0,
2012 "qdev_id":"",
2013 "irq":11,
2014 "slot":4,
2015 "class_info":{
2016 "class":1280,
2017 "desc":"RAM controller"
2018 },
2019 "id":{
2020 "device":6900,
2021 "vendor":4098
2022 },
2023 "function":0,
2024 "regions":[
2025 {
2026 "bar":0,
2027 "size":32,
2028 "address":49280,
2029 "type":"io"
2030 }
2031 ]
2032 }
2033 ]
2034 }
2035 ]
2036 }
2037
2038Note: This example has been shortened as the real response is too long.
2039
2040EQMP
2041
Luiz Capitulino79627472011-10-21 14:15:33 -02002042 {
2043 .name = "query-pci",
2044 .args_type = "",
2045 .mhandler.cmd_new = qmp_marshal_input_query_pci,
2046 },
2047
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002048SQMP
2049query-kvm
2050---------
2051
2052Show KVM information.
2053
2054Return a json-object with the following information:
2055
2056- "enabled": true if KVM support is enabled, false otherwise (json-bool)
2057- "present": true if QEMU has KVM support, false otherwise (json-bool)
2058
2059Example:
2060
2061-> { "execute": "query-kvm" }
2062<- { "return": { "enabled": true, "present": true } }
2063
2064EQMP
2065
Luiz Capitulino292a2602011-09-12 15:10:53 -03002066 {
2067 .name = "query-kvm",
2068 .args_type = "",
2069 .mhandler.cmd_new = qmp_marshal_input_query_kvm,
2070 },
2071
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002072SQMP
2073query-status
2074------------
2075
2076Return a json-object with the following information:
2077
2078- "running": true if the VM is running, or false if it is paused (json-bool)
2079- "singlestep": true if the VM is in single step mode,
2080 false otherwise (json-bool)
Luiz Capitulino9e37b9d2011-08-29 16:02:57 -03002081- "status": one of the following values (json-string)
2082 "debug" - QEMU is running on a debugger
2083 "inmigrate" - guest is paused waiting for an incoming migration
2084 "internal-error" - An internal error that prevents further guest
2085 execution has occurred
2086 "io-error" - the last IOP has failed and the device is configured
2087 to pause on I/O errors
2088 "paused" - guest has been paused via the 'stop' command
2089 "postmigrate" - guest is paused following a successful 'migrate'
2090 "prelaunch" - QEMU was started with -S and guest has not started
2091 "finish-migrate" - guest is paused to finish the migration process
2092 "restore-vm" - guest is paused to restore VM state
2093 "running" - guest is actively running
2094 "save-vm" - guest is paused to save the VM state
2095 "shutdown" - guest is shut down (and -no-shutdown is in use)
2096 "watchdog" - the watchdog action is configured to pause and
2097 has been triggered
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002098
2099Example:
2100
2101-> { "execute": "query-status" }
Luiz Capitulino9e37b9d2011-08-29 16:02:57 -03002102<- { "return": { "running": true, "singlestep": false, "status": "running" } }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002103
2104EQMP
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -03002105
2106 {
2107 .name = "query-status",
2108 .args_type = "",
2109 .mhandler.cmd_new = qmp_marshal_input_query_status,
2110 },
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002111
2112SQMP
2113query-mice
2114----------
2115
2116Show VM mice information.
2117
2118Each mouse is represented by a json-object, the returned value is a json-array
2119of all mice.
2120
2121The mouse json-object contains the following:
2122
2123- "name": mouse's name (json-string)
2124- "index": mouse's index (json-int)
2125- "current": true if this mouse is receiving events, false otherwise (json-bool)
2126- "absolute": true if the mouse generates absolute input events (json-bool)
2127
2128Example:
2129
2130-> { "execute": "query-mice" }
2131<- {
2132 "return":[
2133 {
2134 "name":"QEMU Microsoft Mouse",
2135 "index":0,
2136 "current":false,
2137 "absolute":false
2138 },
2139 {
2140 "name":"QEMU PS/2 Mouse",
2141 "index":1,
2142 "current":true,
2143 "absolute":true
2144 }
2145 ]
2146 }
2147
2148EQMP
2149
Luiz Capitulinoe235cec2011-09-21 15:29:55 -03002150 {
2151 .name = "query-mice",
2152 .args_type = "",
2153 .mhandler.cmd_new = qmp_marshal_input_query_mice,
2154 },
2155
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002156SQMP
2157query-vnc
2158---------
2159
2160Show VNC server information.
2161
2162Return a json-object with server information. Connected clients are returned
2163as a json-array of json-objects.
2164
2165The main json-object contains the following:
2166
2167- "enabled": true or false (json-bool)
2168- "host": server's IP address (json-string)
2169- "family": address family (json-string)
2170 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2171- "service": server's port number (json-string)
2172- "auth": authentication method (json-string)
2173 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2174 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2175 "vencrypt+plain", "vencrypt+tls+none",
2176 "vencrypt+tls+plain", "vencrypt+tls+sasl",
2177 "vencrypt+tls+vnc", "vencrypt+x509+none",
2178 "vencrypt+x509+plain", "vencrypt+x509+sasl",
2179 "vencrypt+x509+vnc", "vnc"
2180- "clients": a json-array of all connected clients
2181
2182Clients are described by a json-object, each one contain the following:
2183
2184- "host": client's IP address (json-string)
2185- "family": address family (json-string)
2186 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2187- "service": client's port number (json-string)
2188- "x509_dname": TLS dname (json-string, optional)
2189- "sasl_username": SASL username (json-string, optional)
2190
2191Example:
2192
2193-> { "execute": "query-vnc" }
2194<- {
2195 "return":{
2196 "enabled":true,
2197 "host":"0.0.0.0",
2198 "service":"50402",
2199 "auth":"vnc",
2200 "family":"ipv4",
2201 "clients":[
2202 {
2203 "host":"127.0.0.1",
2204 "service":"50401",
2205 "family":"ipv4"
2206 }
2207 ]
2208 }
2209 }
2210
2211EQMP
2212
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02002213 {
2214 .name = "query-vnc",
2215 .args_type = "",
2216 .mhandler.cmd_new = qmp_marshal_input_query_vnc,
2217 },
2218
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002219SQMP
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01002220query-spice
2221-----------
2222
2223Show SPICE server information.
2224
2225Return a json-object with server information. Connected clients are returned
2226as a json-array of json-objects.
2227
2228The main json-object contains the following:
2229
2230- "enabled": true or false (json-bool)
2231- "host": server's IP address (json-string)
2232- "port": server's port number (json-int, optional)
2233- "tls-port": server's port number (json-int, optional)
2234- "auth": authentication method (json-string)
2235 - Possible values: "none", "spice"
2236- "channels": a json-array of all active channels clients
2237
2238Channels are described by a json-object, each one contain the following:
2239
2240- "host": client's IP address (json-string)
2241- "family": address family (json-string)
2242 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2243- "port": client's port number (json-string)
2244- "connection-id": spice connection id. All channels with the same id
2245 belong to the same spice session (json-int)
2246- "channel-type": channel type. "1" is the main control channel, filter for
2247 this one if you want track spice sessions only (json-int)
2248- "channel-id": channel id. Usually "0", might be different needed when
2249 multiple channels of the same type exist, such as multiple
2250 display channels in a multihead setup (json-int)
2251- "tls": whevener the channel is encrypted (json-bool)
2252
2253Example:
2254
2255-> { "execute": "query-spice" }
2256<- {
2257 "return": {
2258 "enabled": true,
2259 "auth": "spice",
2260 "port": 5920,
2261 "tls-port": 5921,
2262 "host": "0.0.0.0",
2263 "channels": [
2264 {
2265 "port": "54924",
2266 "family": "ipv4",
2267 "channel-type": 1,
2268 "connection-id": 1804289383,
2269 "host": "127.0.0.1",
2270 "channel-id": 0,
2271 "tls": true
2272 },
2273 {
2274 "port": "36710",
2275 "family": "ipv4",
2276 "channel-type": 4,
2277 "connection-id": 1804289383,
2278 "host": "127.0.0.1",
2279 "channel-id": 0,
2280 "tls": false
2281 },
2282 [ ... more channels follow ... ]
2283 ]
2284 }
2285 }
2286
2287EQMP
2288
Luiz Capitulinod1f29642011-10-20 17:01:33 -02002289#if defined(CONFIG_SPICE)
2290 {
2291 .name = "query-spice",
2292 .args_type = "",
2293 .mhandler.cmd_new = qmp_marshal_input_query_spice,
2294 },
2295#endif
2296
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01002297SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002298query-name
2299----------
2300
2301Show VM name.
2302
2303Return a json-object with the following information:
2304
2305- "name": VM's name (json-string, optional)
2306
2307Example:
2308
2309-> { "execute": "query-name" }
2310<- { "return": { "name": "qemu-name" } }
2311
2312EQMP
2313
Anthony Liguori48a32be2011-09-02 12:34:48 -05002314 {
2315 .name = "query-name",
2316 .args_type = "",
2317 .mhandler.cmd_new = qmp_marshal_input_query_name,
2318 },
2319
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002320SQMP
2321query-uuid
2322----------
2323
2324Show VM UUID.
2325
2326Return a json-object with the following information:
2327
2328- "UUID": Universally Unique Identifier (json-string)
2329
2330Example:
2331
2332-> { "execute": "query-uuid" }
2333<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2334
2335EQMP
2336
Luiz Capitulinoefab7672011-09-13 17:16:25 -03002337 {
2338 .name = "query-uuid",
2339 .args_type = "",
2340 .mhandler.cmd_new = qmp_marshal_input_query_uuid,
2341 },
2342
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002343SQMP
2344query-migrate
2345-------------
2346
2347Migration status.
2348
2349Return a json-object. If migration is active there will be another json-object
2350with RAM migration status and if block migration is active another one with
2351block migration status.
2352
2353The main json-object contains the following:
2354
2355- "status": migration status (json-string)
2356 - Possible values: "active", "completed", "failed", "cancelled"
Juan Quintela7aa939a2012-08-18 13:17:10 +02002357- "total-time": total amount of ms since migration started. If
2358 migration has ended, it returns the total migration
2359 time (json-int)
Juan Quintela9c5a9fc2012-08-13 09:35:16 +02002360- "downtime": only present when migration has finished correctly
2361 total amount in ms for downtime that happened (json-int)
Juan Quintela2c52ddf2012-08-13 09:53:12 +02002362- "expected-downtime": only present while migration is active
2363 total amount in ms for downtime that was calculated on
2364 the last bitmap round (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002365- "ram": only present if "status" is "active", it is a json-object with the
2366 following RAM information (in bytes):
2367 - "transferred": amount transferred (json-int)
2368 - "remaining": amount remaining (json-int)
2369 - "total": total (json-int)
Orit Wasserman004d4c12012-08-06 21:42:56 +03002370 - "duplicate": number of duplicated pages (json-int)
2371 - "normal" : number of normal pages transferred (json-int)
2372 - "normal-bytes" : number of normal bytes transferred (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002373- "disk": only present if "status" is "active" and it is a block migration,
2374 it is a json-object with the following disk information (in bytes):
2375 - "transferred": amount transferred (json-int)
2376 - "remaining": amount remaining (json-int)
2377 - "total": total (json-int)
Orit Wassermanf36d55a2012-08-06 21:42:57 +03002378- "xbzrle-cache": only present if XBZRLE is active.
2379 It is a json-object with the following XBZRLE information:
2380 - "cache-size": XBZRLE cache size
2381 - "bytes": total XBZRLE bytes transferred
2382 - "pages": number of XBZRLE compressed pages
2383 - "cache-miss": number of cache misses
2384 - "overflow": number of XBZRLE overflows
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002385Examples:
2386
23871. Before the first migration
2388
2389-> { "execute": "query-migrate" }
2390<- { "return": {} }
2391
23922. Migration is done and has succeeded
2393
2394-> { "execute": "query-migrate" }
Orit Wasserman004d4c12012-08-06 21:42:56 +03002395<- { "return": {
2396 "status": "completed",
2397 "ram":{
2398 "transferred":123,
2399 "remaining":123,
2400 "total":246,
2401 "total-time":12345,
Juan Quintela9c5a9fc2012-08-13 09:35:16 +02002402 "downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002403 "duplicate":123,
2404 "normal":123,
2405 "normal-bytes":123456
2406 }
2407 }
2408 }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002409
24103. Migration is done and has failed
2411
2412-> { "execute": "query-migrate" }
2413<- { "return": { "status": "failed" } }
2414
24154. Migration is being performed and is not a block migration:
2416
2417-> { "execute": "query-migrate" }
2418<- {
2419 "return":{
2420 "status":"active",
2421 "ram":{
2422 "transferred":123,
2423 "remaining":123,
Orit Wasserman62d4e3f2012-08-06 21:42:55 +03002424 "total":246,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002425 "total-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02002426 "expected-downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002427 "duplicate":123,
2428 "normal":123,
2429 "normal-bytes":123456
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002430 }
2431 }
2432 }
2433
24345. Migration is being performed and is a block migration:
2435
2436-> { "execute": "query-migrate" }
2437<- {
2438 "return":{
2439 "status":"active",
2440 "ram":{
2441 "total":1057024,
2442 "remaining":1053304,
Orit Wasserman62d4e3f2012-08-06 21:42:55 +03002443 "transferred":3720,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002444 "total-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02002445 "expected-downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002446 "duplicate":123,
2447 "normal":123,
2448 "normal-bytes":123456
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002449 },
2450 "disk":{
2451 "total":20971520,
2452 "remaining":20880384,
2453 "transferred":91136
2454 }
2455 }
2456 }
2457
Orit Wassermanf36d55a2012-08-06 21:42:57 +030024586. Migration is being performed and XBZRLE is active:
2459
2460-> { "execute": "query-migrate" }
2461<- {
2462 "return":{
2463 "status":"active",
2464 "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
2465 "ram":{
2466 "total":1057024,
2467 "remaining":1053304,
2468 "transferred":3720,
2469 "total-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02002470 "expected-downtime":12345,
Orit Wassermanf36d55a2012-08-06 21:42:57 +03002471 "duplicate":10,
2472 "normal":3333,
2473 "normal-bytes":3412992
2474 },
2475 "xbzrle-cache":{
2476 "cache-size":67108864,
2477 "bytes":20971520,
2478 "pages":2444343,
2479 "cache-miss":2244,
2480 "overflow":34434
2481 }
2482 }
2483 }
2484
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002485EQMP
2486
Luiz Capitulino791e7c82011-09-13 17:37:16 -03002487 {
2488 .name = "query-migrate",
2489 .args_type = "",
2490 .mhandler.cmd_new = qmp_marshal_input_query_migrate,
2491 },
2492
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002493SQMP
Orit Wasserman00458432012-08-06 21:42:48 +03002494migrate-set-capabilities
2495-------
2496
2497Enable/Disable migration capabilities
2498
2499- "xbzrle": xbzrle support
2500
2501Arguments:
2502
2503Example:
2504
2505-> { "execute": "migrate-set-capabilities" , "arguments":
2506 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
2507
2508EQMP
2509
2510 {
2511 .name = "migrate-set-capabilities",
2512 .args_type = "capabilities:O",
2513 .params = "capability:s,state:b",
2514 .mhandler.cmd_new = qmp_marshal_input_migrate_set_capabilities,
2515 },
2516SQMP
Orit Wassermanbbf6da32012-08-06 21:42:47 +03002517query-migrate-capabilities
2518-------
2519
2520Query current migration capabilities
2521
2522- "capabilities": migration capabilities state
2523 - "xbzrle" : XBZRLE state (json-bool)
2524
2525Arguments:
2526
2527Example:
2528
2529-> { "execute": "query-migrate-capabilities" }
2530<- { "return": {
2531 "capabilities" : [ { "capability" : "xbzrle", "state" : false } ]
2532 }
2533 }
2534EQMP
2535
2536 {
2537 .name = "query-migrate-capabilities",
2538 .args_type = "",
2539 .mhandler.cmd_new = qmp_marshal_input_query_migrate_capabilities,
2540 },
2541
2542SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002543query-balloon
2544-------------
2545
2546Show balloon information.
2547
2548Make an asynchronous request for balloon info. When the request completes a
2549json-object will be returned containing the following data:
2550
2551- "actual": current balloon value in bytes (json-int)
2552- "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2553- "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2554- "major_page_faults": Number of major faults (json-int, optional)
2555- "minor_page_faults": Number of minor faults (json-int, optional)
2556- "free_mem": Total amount of free and unused memory in
2557 bytes (json-int, optional)
2558- "total_mem": Total amount of available memory in bytes (json-int, optional)
2559
2560Example:
2561
2562-> { "execute": "query-balloon" }
2563<- {
2564 "return":{
2565 "actual":1073741824,
2566 "mem_swapped_in":0,
2567 "mem_swapped_out":0,
2568 "major_page_faults":142,
2569 "minor_page_faults":239245,
2570 "free_mem":1014185984,
2571 "total_mem":1044668416
2572 }
2573 }
2574
2575EQMP
2576
Luiz Capitulino96637bc2011-10-21 11:41:37 -02002577 {
2578 .name = "query-balloon",
2579 .args_type = "",
2580 .mhandler.cmd_new = qmp_marshal_input_query_balloon,
2581 },
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002582
2583 {
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00002584 .name = "query-block-jobs",
2585 .args_type = "",
2586 .mhandler.cmd_new = qmp_marshal_input_query_block_jobs,
2587 },
2588
2589 {
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002590 .name = "qom-list",
2591 .args_type = "path:s",
2592 .mhandler.cmd_new = qmp_marshal_input_qom_list,
2593 },
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002594
2595 {
2596 .name = "qom-set",
Paolo Bonzinib9f89782012-03-22 12:51:11 +01002597 .args_type = "path:s,property:s,value:q",
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002598 .mhandler.cmd_new = qmp_qom_set,
2599 },
2600
2601 {
2602 .name = "qom-get",
2603 .args_type = "path:s,property:s",
2604 .mhandler.cmd_new = qmp_qom_get,
2605 },
Luiz Capitulino270b2432011-12-08 11:45:55 -02002606
2607 {
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02002608 .name = "nbd-server-start",
2609 .args_type = "addr:q",
2610 .mhandler.cmd_new = qmp_marshal_input_nbd_server_start,
2611 },
2612 {
2613 .name = "nbd-server-add",
2614 .args_type = "device:B,writable:b?",
2615 .mhandler.cmd_new = qmp_marshal_input_nbd_server_add,
2616 },
2617 {
2618 .name = "nbd-server-stop",
2619 .args_type = "",
2620 .mhandler.cmd_new = qmp_marshal_input_nbd_server_stop,
2621 },
2622
2623 {
Luiz Capitulino270b2432011-12-08 11:45:55 -02002624 .name = "change-vnc-password",
2625 .args_type = "password:s",
2626 .mhandler.cmd_new = qmp_marshal_input_change_vnc_password,
2627 },
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06002628 {
2629 .name = "qom-list-types",
2630 .args_type = "implements:s?,abstract:b?",
2631 .mhandler.cmd_new = qmp_marshal_input_qom_list_types,
2632 },
Anthony Liguori1daa31b2012-08-10 11:04:09 -05002633
2634 {
2635 .name = "device-list-properties",
2636 .args_type = "typename:s",
2637 .mhandler.cmd_new = qmp_marshal_input_device_list_properties,
2638 },
2639
Anthony Liguori01d3c802012-08-10 11:04:11 -05002640 {
2641 .name = "query-machines",
2642 .args_type = "",
2643 .mhandler.cmd_new = qmp_marshal_input_query_machines,
2644 },
2645
Anthony Liguorie4e31c62012-08-10 11:04:13 -05002646 {
2647 .name = "query-cpu-definitions",
2648 .args_type = "",
2649 .mhandler.cmd_new = qmp_marshal_input_query_cpu_definitions,
2650 },
2651
Daniel P. Berrange99afc912012-08-20 15:31:38 +01002652 {
2653 .name = "query-target",
2654 .args_type = "",
2655 .mhandler.cmd_new = qmp_marshal_input_query_target,
2656 },
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01002657
2658 {
2659 .name = "chardev-add",
2660 .args_type = "id:s,backend:q",
2661 .mhandler.cmd_new = qmp_marshal_input_chardev_add,
2662 },
2663
2664SQMP
2665chardev-add
2666----------------
2667
2668Add a chardev.
2669
2670Arguments:
2671
2672- "id": the chardev's ID, must be unique (json-string)
2673- "backend": chardev backend type + parameters
2674
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01002675Examples:
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01002676
2677-> { "execute" : "chardev-add",
2678 "arguments" : { "id" : "foo",
2679 "backend" : { "type" : "null", "data" : {} } } }
2680<- { "return": {} }
2681
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01002682-> { "execute" : "chardev-add",
2683 "arguments" : { "id" : "bar",
2684 "backend" : { "type" : "file",
2685 "data" : { "out" : "/tmp/bar.log" } } } }
2686<- { "return": {} }
2687
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01002688EQMP
2689
2690 {
2691 .name = "chardev-remove",
2692 .args_type = "id:s",
2693 .mhandler.cmd_new = qmp_marshal_input_chardev_remove,
2694 },
2695
2696
2697SQMP
2698chardev-remove
2699--------------
2700
2701Remove a chardev.
2702
2703Arguments:
2704
2705- "id": the chardev's ID, must exist and not be in use (json-string)
2706
2707Example:
2708
2709-> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
2710<- { "return": {} }
2711
2712EQMP