blob: 273b4a67ba172522389b30b695a053ce132f9a23 [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?,"
Paolo Bonzinieee13df2013-01-21 17:09:46 +0100941 "on-source-error:s?,on-target-error:s?,"
Paolo Bonzini08e4ed62013-01-22 09:03:13 +0100942 "granularity:i?,buf-size:i?",
Paolo Bonzinid9b902d2012-10-18 16:49:24 +0200943 .mhandler.cmd_new = qmp_marshal_input_drive_mirror,
944 },
945
946SQMP
947drive-mirror
948------------
949
950Start mirroring a block device's writes to a new destination. target
951specifies the target of the new image. If the file exists, or if it is
952a device, it will be used as the new destination for writes. If it does not
953exist, a new file will be created. format specifies the format of the
954mirror image, default is to probe if mode='existing', else the format
955of the source.
956
957Arguments:
958
959- "device": device name to operate on (json-string)
960- "target": name of new image file (json-string)
961- "format": format of new image (json-string, optional)
962- "mode": how an image file should be created into the target
963 file/device (NewImageMode, optional, default 'absolute-paths')
964- "speed": maximum speed of the streaming job, in bytes per second
965 (json-int)
Paolo Bonzinieee13df2013-01-21 17:09:46 +0100966- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
Paolo Bonzini08e4ed62013-01-22 09:03:13 +0100967- "buf_size": maximum amount of data in flight from source to target, in bytes
968 (json-int, default 10M)
Paolo Bonzinid9b902d2012-10-18 16:49:24 +0200969- "sync": what parts of the disk image should be copied to the destination;
970 possibilities include "full" for all the disk, "top" for only the sectors
971 allocated in the topmost image, or "none" to only replicate new I/O
972 (MirrorSyncMode).
Paolo Bonzinib952b552012-10-18 16:49:28 +0200973- "on-source-error": the action to take on an error on the source
974 (BlockdevOnError, default 'report')
975- "on-target-error": the action to take on an error on the target
976 (BlockdevOnError, default 'report')
977
Paolo Bonzinieee13df2013-01-21 17:09:46 +0100978The default value of the granularity is the image cluster size clamped
979between 4096 and 65536, if the image format defines one. If the format
980does not define a cluster size, the default value of the granularity
981is 65536.
Paolo Bonzinid9b902d2012-10-18 16:49:24 +0200982
983
984Example:
985
986-> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
987 "target": "/some/place/my-image",
988 "sync": "full",
989 "format": "qcow2" } }
990<- { "return": {} }
991
992EQMP
993
994 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300995 .name = "balloon",
996 .args_type = "value:M",
Luiz Capitulinod72f3262011-11-25 14:38:09 -0200997 .mhandler.cmd_new = qmp_marshal_input_balloon,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300998 },
999
1000SQMP
1001balloon
1002-------
1003
1004Request VM to change its memory allocation (in bytes).
1005
1006Arguments:
1007
1008- "value": New memory allocation (json-int)
1009
1010Example:
1011
1012-> { "execute": "balloon", "arguments": { "value": 536870912 } }
1013<- { "return": {} }
1014
1015EQMP
1016
1017 {
1018 .name = "set_link",
1019 .args_type = "name:s,up:b",
Luiz Capitulino4b371562011-11-23 13:11:55 -02001020 .mhandler.cmd_new = qmp_marshal_input_set_link,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001021 },
1022
1023SQMP
1024set_link
1025--------
1026
1027Change the link status of a network adapter.
1028
1029Arguments:
1030
1031- "name": network device name (json-string)
1032- "up": status is up (json-bool)
1033
1034Example:
1035
1036-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1037<- { "return": {} }
1038
1039EQMP
1040
1041 {
1042 .name = "getfd",
1043 .args_type = "fdname:s",
1044 .params = "getfd name",
1045 .help = "receive a file descriptor via SCM rights and assign it a name",
Corey Bryant208c9d12012-06-22 14:36:09 -04001046 .mhandler.cmd_new = qmp_marshal_input_getfd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001047 },
1048
1049SQMP
1050getfd
1051-----
1052
1053Receive a file descriptor via SCM rights and assign it a name.
1054
1055Arguments:
1056
1057- "fdname": file descriptor name (json-string)
1058
1059Example:
1060
1061-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1062<- { "return": {} }
1063
Corey Bryant208c9d12012-06-22 14:36:09 -04001064Notes:
1065
1066(1) If the name specified by the "fdname" argument already exists,
1067 the file descriptor assigned to it will be closed and replaced
1068 by the received file descriptor.
1069(2) The 'closefd' command can be used to explicitly close the file
1070 descriptor when it is no longer needed.
1071
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001072EQMP
1073
1074 {
1075 .name = "closefd",
1076 .args_type = "fdname:s",
1077 .params = "closefd name",
1078 .help = "close a file descriptor previously passed via SCM rights",
Corey Bryant208c9d12012-06-22 14:36:09 -04001079 .mhandler.cmd_new = qmp_marshal_input_closefd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001080 },
1081
1082SQMP
1083closefd
1084-------
1085
1086Close a file descriptor previously passed via SCM rights.
1087
1088Arguments:
1089
1090- "fdname": file descriptor name (json-string)
1091
1092Example:
1093
1094-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1095<- { "return": {} }
1096
1097EQMP
1098
Corey Bryantba1c0482012-08-14 16:43:43 -04001099 {
1100 .name = "add-fd",
1101 .args_type = "fdset-id:i?,opaque:s?",
1102 .params = "add-fd fdset-id opaque",
1103 .help = "Add a file descriptor, that was passed via SCM rights, to an fd set",
1104 .mhandler.cmd_new = qmp_marshal_input_add_fd,
1105 },
1106
1107SQMP
1108add-fd
1109-------
1110
1111Add a file descriptor, that was passed via SCM rights, to an fd set.
1112
1113Arguments:
1114
1115- "fdset-id": The ID of the fd set to add the file descriptor to.
1116 (json-int, optional)
1117- "opaque": A free-form string that can be used to describe the fd.
1118 (json-string, optional)
1119
1120Return a json-object with the following information:
1121
1122- "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1123- "fd": The file descriptor that was received via SCM rights and added to the
1124 fd set. (json-int)
1125
1126Example:
1127
1128-> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1129<- { "return": { "fdset-id": 1, "fd": 3 } }
1130
1131Notes:
1132
1133(1) The list of fd sets is shared by all monitor connections.
1134(2) If "fdset-id" is not specified, a new fd set will be created.
1135
1136EQMP
1137
1138 {
1139 .name = "remove-fd",
1140 .args_type = "fdset-id:i,fd:i?",
1141 .params = "remove-fd fdset-id fd",
1142 .help = "Remove a file descriptor from an fd set",
1143 .mhandler.cmd_new = qmp_marshal_input_remove_fd,
1144 },
1145
1146SQMP
1147remove-fd
1148---------
1149
1150Remove a file descriptor from an fd set.
1151
1152Arguments:
1153
1154- "fdset-id": The ID of the fd set that the file descriptor belongs to.
1155 (json-int)
1156- "fd": The file descriptor that is to be removed. (json-int, optional)
1157
1158Example:
1159
1160-> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1161<- { "return": {} }
1162
1163Notes:
1164
1165(1) The list of fd sets is shared by all monitor connections.
1166(2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1167 removed.
1168
1169EQMP
1170
1171 {
1172 .name = "query-fdsets",
1173 .args_type = "",
1174 .help = "Return information describing all fd sets",
1175 .mhandler.cmd_new = qmp_marshal_input_query_fdsets,
1176 },
1177
1178SQMP
1179query-fdsets
1180-------------
1181
1182Return information describing all fd sets.
1183
1184Arguments: None
1185
1186Example:
1187
1188-> { "execute": "query-fdsets" }
1189<- { "return": [
1190 {
1191 "fds": [
1192 {
1193 "fd": 30,
1194 "opaque": "rdonly:/path/to/file"
1195 },
1196 {
1197 "fd": 24,
1198 "opaque": "rdwr:/path/to/file"
1199 }
1200 ],
1201 "fdset-id": 1
1202 },
1203 {
1204 "fds": [
1205 {
1206 "fd": 28
1207 },
1208 {
1209 "fd": 29
1210 }
1211 ],
1212 "fdset-id": 0
1213 }
1214 ]
1215 }
1216
1217Note: The list of fd sets is shared by all monitor connections.
1218
1219EQMP
1220
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001221 {
1222 .name = "block_passwd",
1223 .args_type = "device:B,password:s",
Luiz Capitulinoa4dea8a2011-11-23 13:28:21 -02001224 .mhandler.cmd_new = qmp_marshal_input_block_passwd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001225 },
1226
1227SQMP
1228block_passwd
1229------------
1230
1231Set the password of encrypted block devices.
1232
1233Arguments:
1234
1235- "device": device name (json-string)
1236- "password": password (json-string)
1237
1238Example:
1239
1240-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1241 "password": "12345" } }
1242<- { "return": {} }
1243
1244EQMP
1245
1246 {
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001247 .name = "block_set_io_throttle",
1248 .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 -02001249 .mhandler.cmd_new = qmp_marshal_input_block_set_io_throttle,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001250 },
1251
1252SQMP
1253block_set_io_throttle
1254------------
1255
1256Change I/O throttle limits for a block drive.
1257
1258Arguments:
1259
1260- "device": device name (json-string)
1261- "bps": total throughput limit in bytes per second(json-int)
1262- "bps_rd": read throughput limit in bytes per second(json-int)
1263- "bps_wr": read throughput limit in bytes per second(json-int)
1264- "iops": total I/O operations per second(json-int)
1265- "iops_rd": read I/O operations per second(json-int)
1266- "iops_wr": write I/O operations per second(json-int)
1267
1268Example:
1269
1270-> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
1271 "bps": "1000000",
1272 "bps_rd": "0",
1273 "bps_wr": "0",
1274 "iops": "0",
1275 "iops_rd": "0",
1276 "iops_wr": "0" } }
1277<- { "return": {} }
1278
1279EQMP
1280
1281 {
Gerd Hoffmann75721502010-10-07 12:22:54 +02001282 .name = "set_password",
1283 .args_type = "protocol:s,password:s,connected:s?",
Luiz Capitulinofbf796f2011-12-07 11:17:51 -02001284 .mhandler.cmd_new = qmp_marshal_input_set_password,
Gerd Hoffmann75721502010-10-07 12:22:54 +02001285 },
1286
1287SQMP
1288set_password
1289------------
1290
1291Set the password for vnc/spice protocols.
1292
1293Arguments:
1294
1295- "protocol": protocol name (json-string)
1296- "password": password (json-string)
1297- "connected": [ keep | disconnect | fail ] (josn-string, optional)
1298
1299Example:
1300
1301-> { "execute": "set_password", "arguments": { "protocol": "vnc",
1302 "password": "secret" } }
1303<- { "return": {} }
1304
1305EQMP
1306
1307 {
1308 .name = "expire_password",
1309 .args_type = "protocol:s,time:s",
Luiz Capitulino9ad53722011-12-07 11:47:57 -02001310 .mhandler.cmd_new = qmp_marshal_input_expire_password,
Gerd Hoffmann75721502010-10-07 12:22:54 +02001311 },
1312
1313SQMP
1314expire_password
1315---------------
1316
1317Set the password expire time for vnc/spice protocols.
1318
1319Arguments:
1320
1321- "protocol": protocol name (json-string)
1322- "time": [ now | never | +secs | secs ] (json-string)
1323
1324Example:
1325
1326-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1327 "time": "+60" } }
1328<- { "return": {} }
1329
1330EQMP
1331
1332 {
Daniel P. Berrange13661082011-06-23 13:31:42 +01001333 .name = "add_client",
Daniel P. Berrangef1f5f402012-02-13 13:43:08 +00001334 .args_type = "protocol:s,fdname:s,skipauth:b?,tls:b?",
Luiz Capitulinob224e5e2012-09-13 16:52:20 -03001335 .mhandler.cmd_new = qmp_marshal_input_add_client,
Daniel P. Berrange13661082011-06-23 13:31:42 +01001336 },
1337
1338SQMP
1339add_client
1340----------
1341
1342Add a graphics client
1343
1344Arguments:
1345
1346- "protocol": protocol name (json-string)
1347- "fdname": file descriptor name (json-string)
Daniel P. Berrangef1f5f402012-02-13 13:43:08 +00001348- "skipauth": whether to skip authentication (json-bool, optional)
1349- "tls": whether to perform TLS (json-bool, optional)
Daniel P. Berrange13661082011-06-23 13:31:42 +01001350
1351Example:
1352
1353-> { "execute": "add_client", "arguments": { "protocol": "vnc",
1354 "fdname": "myclient" } }
1355<- { "return": {} }
1356
1357EQMP
1358 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001359 .name = "qmp_capabilities",
1360 .args_type = "",
1361 .params = "",
1362 .help = "enable QMP capabilities",
1363 .user_print = monitor_user_noop,
1364 .mhandler.cmd_new = do_qmp_capabilities,
1365 },
1366
1367SQMP
1368qmp_capabilities
1369----------------
1370
1371Enable QMP capabilities.
1372
1373Arguments: None.
1374
1375Example:
1376
1377-> { "execute": "qmp_capabilities" }
1378<- { "return": {} }
1379
1380Note: This command must be issued before issuing any other command.
1381
Luiz Capitulino0268d972010-10-22 10:08:02 -02001382EQMP
1383
1384 {
1385 .name = "human-monitor-command",
1386 .args_type = "command-line:s,cpu-index:i?",
Luiz Capitulinod51a67b2011-11-25 17:52:45 -02001387 .mhandler.cmd_new = qmp_marshal_input_human_monitor_command,
Luiz Capitulino0268d972010-10-22 10:08:02 -02001388 },
1389
1390SQMP
1391human-monitor-command
1392---------------------
1393
1394Execute a Human Monitor command.
1395
1396Arguments:
1397
1398- command-line: the command name and its arguments, just like the
1399 Human Monitor's shell (json-string)
1400- cpu-index: select the CPU number to be used by commands which access CPU
1401 data, like 'info registers'. The Monitor selects CPU 0 if this
1402 argument is not provided (json-int, optional)
1403
1404Example:
1405
1406-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1407<- { "return": "kvm support: enabled\r\n" }
1408
1409Notes:
1410
1411(1) The Human Monitor is NOT an stable interface, this means that command
1412 names, arguments and responses can change or be removed at ANY time.
1413 Applications that rely on long term stability guarantees should NOT
1414 use this command
1415
1416(2) Limitations:
1417
1418 o This command is stateless, this means that commands that depend
1419 on state information (such as getfd) might not work
1420
1421 o Commands that prompt the user for data (eg. 'cont' when the block
1422 device is encrypted) don't currently work
1423
Luiz Capitulino82a56f02010-09-13 12:26:00 -030014243. Query Commands
1425=================
1426
1427HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
1428HXCOMM this! We will possibly move query commands definitions inside those
1429HXCOMM sections, just like regular commands.
1430
1431EQMP
1432
1433SQMP
1434query-version
1435-------------
1436
1437Show QEMU version.
1438
1439Return a json-object with the following information:
1440
1441- "qemu": A json-object containing three integer values:
1442 - "major": QEMU's major version (json-int)
1443 - "minor": QEMU's minor version (json-int)
1444 - "micro": QEMU's micro version (json-int)
1445- "package": package's version (json-string)
1446
1447Example:
1448
1449-> { "execute": "query-version" }
1450<- {
1451 "return":{
1452 "qemu":{
1453 "major":0,
1454 "minor":11,
1455 "micro":5
1456 },
1457 "package":""
1458 }
1459 }
1460
1461EQMP
1462
Luiz Capitulinob9c15f12011-08-26 17:38:13 -03001463 {
1464 .name = "query-version",
1465 .args_type = "",
1466 .mhandler.cmd_new = qmp_marshal_input_query_version,
1467 },
1468
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001469SQMP
1470query-commands
1471--------------
1472
1473List QMP available commands.
1474
1475Each command is represented by a json-object, the returned value is a json-array
1476of all commands.
1477
1478Each json-object contain:
1479
1480- "name": command's name (json-string)
1481
1482Example:
1483
1484-> { "execute": "query-commands" }
1485<- {
1486 "return":[
1487 {
1488 "name":"query-balloon"
1489 },
1490 {
1491 "name":"system_powerdown"
1492 }
1493 ]
1494 }
1495
1496Note: This example has been shortened as the real response is too long.
1497
1498EQMP
1499
Luiz Capitulinoaa9b79b2011-09-21 14:31:51 -03001500 {
1501 .name = "query-commands",
1502 .args_type = "",
1503 .mhandler.cmd_new = qmp_marshal_input_query_commands,
1504 },
1505
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001506SQMP
Daniel P. Berrange48608532012-05-21 17:59:51 +01001507query-events
1508--------------
1509
1510List QMP available events.
1511
1512Each event is represented by a json-object, the returned value is a json-array
1513of all events.
1514
1515Each json-object contains:
1516
1517- "name": event's name (json-string)
1518
1519Example:
1520
1521-> { "execute": "query-events" }
1522<- {
1523 "return":[
1524 {
1525 "name":"SHUTDOWN"
1526 },
1527 {
1528 "name":"RESET"
1529 }
1530 ]
1531 }
1532
1533Note: This example has been shortened as the real response is too long.
1534
1535EQMP
1536
1537 {
1538 .name = "query-events",
1539 .args_type = "",
1540 .mhandler.cmd_new = qmp_marshal_input_query_events,
1541 },
1542
1543SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001544query-chardev
1545-------------
1546
1547Each device is represented by a json-object. The returned value is a json-array
1548of all devices.
1549
1550Each json-object contain the following:
1551
1552- "label": device's label (json-string)
1553- "filename": device's file (json-string)
1554
1555Example:
1556
1557-> { "execute": "query-chardev" }
1558<- {
1559 "return":[
1560 {
1561 "label":"monitor",
1562 "filename":"stdio"
1563 },
1564 {
1565 "label":"serial0",
1566 "filename":"vc"
1567 }
1568 ]
1569 }
1570
1571EQMP
1572
Luiz Capitulinoc5a415a2011-09-14 16:05:49 -03001573 {
1574 .name = "query-chardev",
1575 .args_type = "",
1576 .mhandler.cmd_new = qmp_marshal_input_query_chardev,
1577 },
1578
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001579SQMP
1580query-block
1581-----------
1582
1583Show the block devices.
1584
1585Each block device information is stored in a json-object and the returned value
1586is a json-array of all devices.
1587
1588Each json-object contain the following:
1589
1590- "device": device name (json-string)
1591- "type": device type (json-string)
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001592 - deprecated, retained for backward compatibility
1593 - Possible values: "unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001594- "removable": true if the device is removable, false otherwise (json-bool)
1595- "locked": true if the device is locked, false otherwise (json-bool)
Markus Armbrustere4def802011-09-06 18:58:53 +02001596- "tray-open": only present if removable, true if the device has a tray,
1597 and it is open (json-bool)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001598- "inserted": only present if the device is inserted, it is a json-object
1599 containing the following:
1600 - "file": device file name (json-string)
1601 - "ro": true if read-only, false otherwise (json-bool)
1602 - "drv": driver format name (json-string)
1603 - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1604 "file", "file", "ftp", "ftps", "host_cdrom",
1605 "host_device", "host_floppy", "http", "https",
1606 "nbd", "parallels", "qcow", "qcow2", "raw",
1607 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1608 - "backing_file": backing file name (json-string, optional)
Benoît Canet2e3e3312012-08-02 10:22:48 +02001609 - "backing_file_depth": number of files in the backing file chain (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001610 - "encrypted": true if encrypted, false otherwise (json-bool)
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001611 - "bps": limit total bytes per second (json-int)
1612 - "bps_rd": limit read bytes per second (json-int)
1613 - "bps_wr": limit write bytes per second (json-int)
1614 - "iops": limit total I/O operations per second (json-int)
1615 - "iops_rd": limit read operations per second (json-int)
1616 - "iops_wr": limit write operations per second (json-int)
1617
Luiz Capitulinof04ef602011-09-26 17:43:54 -03001618- "io-status": I/O operation status, only present if the device supports it
1619 and the VM is configured to stop on errors. It's always reset
1620 to "ok" when the "cont" command is issued (json_string, optional)
1621 - Possible values: "ok", "failed", "nospace"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001622
1623Example:
1624
1625-> { "execute": "query-block" }
1626<- {
1627 "return":[
1628 {
Luiz Capitulinof04ef602011-09-26 17:43:54 -03001629 "io-status": "ok",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001630 "device":"ide0-hd0",
1631 "locked":false,
1632 "removable":false,
1633 "inserted":{
1634 "ro":false,
1635 "drv":"qcow2",
1636 "encrypted":false,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001637 "file":"disks/test.img",
Benoît Canet2e3e3312012-08-02 10:22:48 +02001638 "backing_file_depth":0,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08001639 "bps":1000000,
1640 "bps_rd":0,
1641 "bps_wr":0,
1642 "iops":1000000,
1643 "iops_rd":0,
1644 "iops_wr":0,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001645 },
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001646 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001647 },
1648 {
Luiz Capitulinof04ef602011-09-26 17:43:54 -03001649 "io-status": "ok",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001650 "device":"ide1-cd0",
1651 "locked":false,
1652 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001653 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001654 },
1655 {
1656 "device":"floppy0",
1657 "locked":false,
1658 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001659 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001660 },
1661 {
1662 "device":"sd0",
1663 "locked":false,
1664 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02001665 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001666 }
1667 ]
1668 }
1669
1670EQMP
1671
Luiz Capitulinob2023812011-09-21 17:16:47 -03001672 {
1673 .name = "query-block",
1674 .args_type = "",
1675 .mhandler.cmd_new = qmp_marshal_input_query_block,
1676 },
1677
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001678SQMP
1679query-blockstats
1680----------------
1681
1682Show block device statistics.
1683
1684Each device statistic information is stored in a json-object and the returned
1685value is a json-array of all devices.
1686
1687Each json-object contain the following:
1688
1689- "device": device name (json-string)
1690- "stats": A json-object with the statistics information, it contains:
1691 - "rd_bytes": bytes read (json-int)
1692 - "wr_bytes": bytes written (json-int)
1693 - "rd_operations": read operations (json-int)
1694 - "wr_operations": write operations (json-int)
Christoph Hellwige8045d62011-08-22 00:25:58 +02001695 - "flush_operations": cache flush operations (json-int)
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001696 - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1697 - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1698 - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001699 - "wr_highest_offset": Highest offset of a sector written since the
1700 BlockDriverState has been opened (json-int)
1701- "parent": Contains recursively the statistics of the underlying
1702 protocol (e.g. the host file for a qcow2 image). If there is
1703 no underlying protocol, this field is omitted
1704 (json-object, optional)
1705
1706Example:
1707
1708-> { "execute": "query-blockstats" }
1709<- {
1710 "return":[
1711 {
1712 "device":"ide0-hd0",
1713 "parent":{
1714 "stats":{
1715 "wr_highest_offset":3686448128,
1716 "wr_bytes":9786368,
1717 "wr_operations":751,
1718 "rd_bytes":122567168,
1719 "rd_operations":36772
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001720 "wr_total_times_ns":313253456
1721 "rd_total_times_ns":3465673657
1722 "flush_total_times_ns":49653
Christoph Hellwige8045d62011-08-22 00:25:58 +02001723 "flush_operations":61,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001724 }
1725 },
1726 "stats":{
1727 "wr_highest_offset":2821110784,
1728 "wr_bytes":9786368,
1729 "wr_operations":692,
1730 "rd_bytes":122739200,
1731 "rd_operations":36604
Christoph Hellwige8045d62011-08-22 00:25:58 +02001732 "flush_operations":51,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001733 "wr_total_times_ns":313253456
1734 "rd_total_times_ns":3465673657
1735 "flush_total_times_ns":49653
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001736 }
1737 },
1738 {
1739 "device":"ide1-cd0",
1740 "stats":{
1741 "wr_highest_offset":0,
1742 "wr_bytes":0,
1743 "wr_operations":0,
1744 "rd_bytes":0,
1745 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02001746 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001747 "wr_total_times_ns":0
1748 "rd_total_times_ns":0
1749 "flush_total_times_ns":0
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001750 }
1751 },
1752 {
1753 "device":"floppy0",
1754 "stats":{
1755 "wr_highest_offset":0,
1756 "wr_bytes":0,
1757 "wr_operations":0,
1758 "rd_bytes":0,
1759 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02001760 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001761 "wr_total_times_ns":0
1762 "rd_total_times_ns":0
1763 "flush_total_times_ns":0
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001764 }
1765 },
1766 {
1767 "device":"sd0",
1768 "stats":{
1769 "wr_highest_offset":0,
1770 "wr_bytes":0,
1771 "wr_operations":0,
1772 "rd_bytes":0,
1773 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02001774 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02001775 "wr_total_times_ns":0
1776 "rd_total_times_ns":0
1777 "flush_total_times_ns":0
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001778 }
1779 }
1780 ]
1781 }
1782
1783EQMP
1784
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03001785 {
1786 .name = "query-blockstats",
1787 .args_type = "",
1788 .mhandler.cmd_new = qmp_marshal_input_query_blockstats,
1789 },
1790
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001791SQMP
1792query-cpus
1793----------
1794
1795Show CPU information.
1796
1797Return a json-array. Each CPU is represented by a json-object, which contains:
1798
1799- "CPU": CPU index (json-int)
1800- "current": true if this is the current CPU, false otherwise (json-bool)
1801- "halted": true if the cpu is halted, false otherwise (json-bool)
1802- Current program counter. The key's name depends on the architecture:
1803 "pc": i386/x86_64 (json-int)
1804 "nip": PPC (json-int)
1805 "pc" and "npc": sparc (json-int)
1806 "PC": mips (json-int)
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01001807- "thread_id": ID of the underlying host thread (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001808
1809Example:
1810
1811-> { "execute": "query-cpus" }
1812<- {
1813 "return":[
1814 {
1815 "CPU":0,
1816 "current":true,
1817 "halted":false,
1818 "pc":3227107138
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01001819 "thread_id":3134
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001820 },
1821 {
1822 "CPU":1,
1823 "current":false,
1824 "halted":true,
1825 "pc":7108165
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01001826 "thread_id":3135
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001827 }
1828 ]
1829 }
1830
1831EQMP
1832
Luiz Capitulinode0b36b2011-09-21 16:38:35 -03001833 {
1834 .name = "query-cpus",
1835 .args_type = "",
1836 .mhandler.cmd_new = qmp_marshal_input_query_cpus,
1837 },
1838
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001839SQMP
1840query-pci
1841---------
1842
1843PCI buses and devices information.
1844
1845The returned value is a json-array of all buses. Each bus is represented by
1846a json-object, which has a key with a json-array of all PCI devices attached
1847to it. Each device is represented by a json-object.
1848
1849The bus json-object contains the following:
1850
1851- "bus": bus number (json-int)
1852- "devices": a json-array of json-objects, each json-object represents a
1853 PCI device
1854
1855The PCI device json-object contains the following:
1856
1857- "bus": identical to the parent's bus number (json-int)
1858- "slot": slot number (json-int)
1859- "function": function number (json-int)
1860- "class_info": a json-object containing:
1861 - "desc": device class description (json-string, optional)
1862 - "class": device class number (json-int)
1863- "id": a json-object containing:
1864 - "device": device ID (json-int)
1865 - "vendor": vendor ID (json-int)
1866- "irq": device's IRQ if assigned (json-int, optional)
1867- "qdev_id": qdev id string (json-string)
1868- "pci_bridge": It's a json-object, only present if this device is a
1869 PCI bridge, contains:
1870 - "bus": bus number (json-int)
1871 - "secondary": secondary bus number (json-int)
1872 - "subordinate": subordinate bus number (json-int)
1873 - "io_range": I/O memory range information, a json-object with the
1874 following members:
1875 - "base": base address, in bytes (json-int)
1876 - "limit": limit address, in bytes (json-int)
1877 - "memory_range": memory range information, a json-object with the
1878 following members:
1879 - "base": base address, in bytes (json-int)
1880 - "limit": limit address, in bytes (json-int)
1881 - "prefetchable_range": Prefetchable memory range information, a
1882 json-object with the following members:
1883 - "base": base address, in bytes (json-int)
1884 - "limit": limit address, in bytes (json-int)
1885 - "devices": a json-array of PCI devices if there's any attached, each
1886 each element is represented by a json-object, which contains
1887 the same members of the 'PCI device json-object' described
1888 above (optional)
1889- "regions": a json-array of json-objects, each json-object represents a
1890 memory region of this device
1891
1892The memory range json-object contains the following:
1893
1894- "base": base memory address (json-int)
1895- "limit": limit value (json-int)
1896
1897The region json-object can be an I/O region or a memory region, an I/O region
1898json-object contains the following:
1899
1900- "type": "io" (json-string, fixed)
1901- "bar": BAR number (json-int)
1902- "address": memory address (json-int)
1903- "size": memory size (json-int)
1904
1905A memory region json-object contains the following:
1906
1907- "type": "memory" (json-string, fixed)
1908- "bar": BAR number (json-int)
1909- "address": memory address (json-int)
1910- "size": memory size (json-int)
1911- "mem_type_64": true or false (json-bool)
1912- "prefetch": true or false (json-bool)
1913
1914Example:
1915
1916-> { "execute": "query-pci" }
1917<- {
1918 "return":[
1919 {
1920 "bus":0,
1921 "devices":[
1922 {
1923 "bus":0,
1924 "qdev_id":"",
1925 "slot":0,
1926 "class_info":{
1927 "class":1536,
1928 "desc":"Host bridge"
1929 },
1930 "id":{
1931 "device":32902,
1932 "vendor":4663
1933 },
1934 "function":0,
1935 "regions":[
1936
1937 ]
1938 },
1939 {
1940 "bus":0,
1941 "qdev_id":"",
1942 "slot":1,
1943 "class_info":{
1944 "class":1537,
1945 "desc":"ISA bridge"
1946 },
1947 "id":{
1948 "device":32902,
1949 "vendor":28672
1950 },
1951 "function":0,
1952 "regions":[
1953
1954 ]
1955 },
1956 {
1957 "bus":0,
1958 "qdev_id":"",
1959 "slot":1,
1960 "class_info":{
1961 "class":257,
1962 "desc":"IDE controller"
1963 },
1964 "id":{
1965 "device":32902,
1966 "vendor":28688
1967 },
1968 "function":1,
1969 "regions":[
1970 {
1971 "bar":4,
1972 "size":16,
1973 "address":49152,
1974 "type":"io"
1975 }
1976 ]
1977 },
1978 {
1979 "bus":0,
1980 "qdev_id":"",
1981 "slot":2,
1982 "class_info":{
1983 "class":768,
1984 "desc":"VGA controller"
1985 },
1986 "id":{
1987 "device":4115,
1988 "vendor":184
1989 },
1990 "function":0,
1991 "regions":[
1992 {
1993 "prefetch":true,
1994 "mem_type_64":false,
1995 "bar":0,
1996 "size":33554432,
1997 "address":4026531840,
1998 "type":"memory"
1999 },
2000 {
2001 "prefetch":false,
2002 "mem_type_64":false,
2003 "bar":1,
2004 "size":4096,
2005 "address":4060086272,
2006 "type":"memory"
2007 },
2008 {
2009 "prefetch":false,
2010 "mem_type_64":false,
2011 "bar":6,
2012 "size":65536,
2013 "address":-1,
2014 "type":"memory"
2015 }
2016 ]
2017 },
2018 {
2019 "bus":0,
2020 "qdev_id":"",
2021 "irq":11,
2022 "slot":4,
2023 "class_info":{
2024 "class":1280,
2025 "desc":"RAM controller"
2026 },
2027 "id":{
2028 "device":6900,
2029 "vendor":4098
2030 },
2031 "function":0,
2032 "regions":[
2033 {
2034 "bar":0,
2035 "size":32,
2036 "address":49280,
2037 "type":"io"
2038 }
2039 ]
2040 }
2041 ]
2042 }
2043 ]
2044 }
2045
2046Note: This example has been shortened as the real response is too long.
2047
2048EQMP
2049
Luiz Capitulino79627472011-10-21 14:15:33 -02002050 {
2051 .name = "query-pci",
2052 .args_type = "",
2053 .mhandler.cmd_new = qmp_marshal_input_query_pci,
2054 },
2055
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002056SQMP
2057query-kvm
2058---------
2059
2060Show KVM information.
2061
2062Return a json-object with the following information:
2063
2064- "enabled": true if KVM support is enabled, false otherwise (json-bool)
2065- "present": true if QEMU has KVM support, false otherwise (json-bool)
2066
2067Example:
2068
2069-> { "execute": "query-kvm" }
2070<- { "return": { "enabled": true, "present": true } }
2071
2072EQMP
2073
Luiz Capitulino292a2602011-09-12 15:10:53 -03002074 {
2075 .name = "query-kvm",
2076 .args_type = "",
2077 .mhandler.cmd_new = qmp_marshal_input_query_kvm,
2078 },
2079
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002080SQMP
2081query-status
2082------------
2083
2084Return a json-object with the following information:
2085
2086- "running": true if the VM is running, or false if it is paused (json-bool)
2087- "singlestep": true if the VM is in single step mode,
2088 false otherwise (json-bool)
Luiz Capitulino9e37b9d2011-08-29 16:02:57 -03002089- "status": one of the following values (json-string)
2090 "debug" - QEMU is running on a debugger
2091 "inmigrate" - guest is paused waiting for an incoming migration
2092 "internal-error" - An internal error that prevents further guest
2093 execution has occurred
2094 "io-error" - the last IOP has failed and the device is configured
2095 to pause on I/O errors
2096 "paused" - guest has been paused via the 'stop' command
2097 "postmigrate" - guest is paused following a successful 'migrate'
2098 "prelaunch" - QEMU was started with -S and guest has not started
2099 "finish-migrate" - guest is paused to finish the migration process
2100 "restore-vm" - guest is paused to restore VM state
2101 "running" - guest is actively running
2102 "save-vm" - guest is paused to save the VM state
2103 "shutdown" - guest is shut down (and -no-shutdown is in use)
2104 "watchdog" - the watchdog action is configured to pause and
2105 has been triggered
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002106
2107Example:
2108
2109-> { "execute": "query-status" }
Luiz Capitulino9e37b9d2011-08-29 16:02:57 -03002110<- { "return": { "running": true, "singlestep": false, "status": "running" } }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002111
2112EQMP
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -03002113
2114 {
2115 .name = "query-status",
2116 .args_type = "",
2117 .mhandler.cmd_new = qmp_marshal_input_query_status,
2118 },
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002119
2120SQMP
2121query-mice
2122----------
2123
2124Show VM mice information.
2125
2126Each mouse is represented by a json-object, the returned value is a json-array
2127of all mice.
2128
2129The mouse json-object contains the following:
2130
2131- "name": mouse's name (json-string)
2132- "index": mouse's index (json-int)
2133- "current": true if this mouse is receiving events, false otherwise (json-bool)
2134- "absolute": true if the mouse generates absolute input events (json-bool)
2135
2136Example:
2137
2138-> { "execute": "query-mice" }
2139<- {
2140 "return":[
2141 {
2142 "name":"QEMU Microsoft Mouse",
2143 "index":0,
2144 "current":false,
2145 "absolute":false
2146 },
2147 {
2148 "name":"QEMU PS/2 Mouse",
2149 "index":1,
2150 "current":true,
2151 "absolute":true
2152 }
2153 ]
2154 }
2155
2156EQMP
2157
Luiz Capitulinoe235cec2011-09-21 15:29:55 -03002158 {
2159 .name = "query-mice",
2160 .args_type = "",
2161 .mhandler.cmd_new = qmp_marshal_input_query_mice,
2162 },
2163
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002164SQMP
2165query-vnc
2166---------
2167
2168Show VNC server information.
2169
2170Return a json-object with server information. Connected clients are returned
2171as a json-array of json-objects.
2172
2173The main json-object contains the following:
2174
2175- "enabled": true or false (json-bool)
2176- "host": server's IP address (json-string)
2177- "family": address family (json-string)
2178 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2179- "service": server's port number (json-string)
2180- "auth": authentication method (json-string)
2181 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2182 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2183 "vencrypt+plain", "vencrypt+tls+none",
2184 "vencrypt+tls+plain", "vencrypt+tls+sasl",
2185 "vencrypt+tls+vnc", "vencrypt+x509+none",
2186 "vencrypt+x509+plain", "vencrypt+x509+sasl",
2187 "vencrypt+x509+vnc", "vnc"
2188- "clients": a json-array of all connected clients
2189
2190Clients are described by a json-object, each one contain the following:
2191
2192- "host": client's IP address (json-string)
2193- "family": address family (json-string)
2194 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2195- "service": client's port number (json-string)
2196- "x509_dname": TLS dname (json-string, optional)
2197- "sasl_username": SASL username (json-string, optional)
2198
2199Example:
2200
2201-> { "execute": "query-vnc" }
2202<- {
2203 "return":{
2204 "enabled":true,
2205 "host":"0.0.0.0",
2206 "service":"50402",
2207 "auth":"vnc",
2208 "family":"ipv4",
2209 "clients":[
2210 {
2211 "host":"127.0.0.1",
2212 "service":"50401",
2213 "family":"ipv4"
2214 }
2215 ]
2216 }
2217 }
2218
2219EQMP
2220
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02002221 {
2222 .name = "query-vnc",
2223 .args_type = "",
2224 .mhandler.cmd_new = qmp_marshal_input_query_vnc,
2225 },
2226
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002227SQMP
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01002228query-spice
2229-----------
2230
2231Show SPICE server information.
2232
2233Return a json-object with server information. Connected clients are returned
2234as a json-array of json-objects.
2235
2236The main json-object contains the following:
2237
2238- "enabled": true or false (json-bool)
2239- "host": server's IP address (json-string)
2240- "port": server's port number (json-int, optional)
2241- "tls-port": server's port number (json-int, optional)
2242- "auth": authentication method (json-string)
2243 - Possible values: "none", "spice"
2244- "channels": a json-array of all active channels clients
2245
2246Channels are described by a json-object, each one contain the following:
2247
2248- "host": client's IP address (json-string)
2249- "family": address family (json-string)
2250 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2251- "port": client's port number (json-string)
2252- "connection-id": spice connection id. All channels with the same id
2253 belong to the same spice session (json-int)
2254- "channel-type": channel type. "1" is the main control channel, filter for
2255 this one if you want track spice sessions only (json-int)
2256- "channel-id": channel id. Usually "0", might be different needed when
2257 multiple channels of the same type exist, such as multiple
2258 display channels in a multihead setup (json-int)
2259- "tls": whevener the channel is encrypted (json-bool)
2260
2261Example:
2262
2263-> { "execute": "query-spice" }
2264<- {
2265 "return": {
2266 "enabled": true,
2267 "auth": "spice",
2268 "port": 5920,
2269 "tls-port": 5921,
2270 "host": "0.0.0.0",
2271 "channels": [
2272 {
2273 "port": "54924",
2274 "family": "ipv4",
2275 "channel-type": 1,
2276 "connection-id": 1804289383,
2277 "host": "127.0.0.1",
2278 "channel-id": 0,
2279 "tls": true
2280 },
2281 {
2282 "port": "36710",
2283 "family": "ipv4",
2284 "channel-type": 4,
2285 "connection-id": 1804289383,
2286 "host": "127.0.0.1",
2287 "channel-id": 0,
2288 "tls": false
2289 },
2290 [ ... more channels follow ... ]
2291 ]
2292 }
2293 }
2294
2295EQMP
2296
Luiz Capitulinod1f29642011-10-20 17:01:33 -02002297#if defined(CONFIG_SPICE)
2298 {
2299 .name = "query-spice",
2300 .args_type = "",
2301 .mhandler.cmd_new = qmp_marshal_input_query_spice,
2302 },
2303#endif
2304
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01002305SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002306query-name
2307----------
2308
2309Show VM name.
2310
2311Return a json-object with the following information:
2312
2313- "name": VM's name (json-string, optional)
2314
2315Example:
2316
2317-> { "execute": "query-name" }
2318<- { "return": { "name": "qemu-name" } }
2319
2320EQMP
2321
Anthony Liguori48a32be2011-09-02 12:34:48 -05002322 {
2323 .name = "query-name",
2324 .args_type = "",
2325 .mhandler.cmd_new = qmp_marshal_input_query_name,
2326 },
2327
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002328SQMP
2329query-uuid
2330----------
2331
2332Show VM UUID.
2333
2334Return a json-object with the following information:
2335
2336- "UUID": Universally Unique Identifier (json-string)
2337
2338Example:
2339
2340-> { "execute": "query-uuid" }
2341<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2342
2343EQMP
2344
Luiz Capitulinoefab7672011-09-13 17:16:25 -03002345 {
2346 .name = "query-uuid",
2347 .args_type = "",
2348 .mhandler.cmd_new = qmp_marshal_input_query_uuid,
2349 },
2350
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002351SQMP
2352query-migrate
2353-------------
2354
2355Migration status.
2356
2357Return a json-object. If migration is active there will be another json-object
2358with RAM migration status and if block migration is active another one with
2359block migration status.
2360
2361The main json-object contains the following:
2362
2363- "status": migration status (json-string)
2364 - Possible values: "active", "completed", "failed", "cancelled"
Juan Quintela7aa939a2012-08-18 13:17:10 +02002365- "total-time": total amount of ms since migration started. If
2366 migration has ended, it returns the total migration
2367 time (json-int)
Juan Quintela9c5a9fc2012-08-13 09:35:16 +02002368- "downtime": only present when migration has finished correctly
2369 total amount in ms for downtime that happened (json-int)
Juan Quintela2c52ddf2012-08-13 09:53:12 +02002370- "expected-downtime": only present while migration is active
2371 total amount in ms for downtime that was calculated on
2372 the last bitmap round (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002373- "ram": only present if "status" is "active", it is a json-object with the
2374 following RAM information (in bytes):
2375 - "transferred": amount transferred (json-int)
2376 - "remaining": amount remaining (json-int)
2377 - "total": total (json-int)
Orit Wasserman004d4c12012-08-06 21:42:56 +03002378 - "duplicate": number of duplicated pages (json-int)
2379 - "normal" : number of normal pages transferred (json-int)
2380 - "normal-bytes" : number of normal bytes transferred (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002381- "disk": only present if "status" is "active" and it is a block migration,
2382 it is a json-object with the following disk information (in bytes):
2383 - "transferred": amount transferred (json-int)
2384 - "remaining": amount remaining (json-int)
2385 - "total": total (json-int)
Orit Wassermanf36d55a2012-08-06 21:42:57 +03002386- "xbzrle-cache": only present if XBZRLE is active.
2387 It is a json-object with the following XBZRLE information:
2388 - "cache-size": XBZRLE cache size
2389 - "bytes": total XBZRLE bytes transferred
2390 - "pages": number of XBZRLE compressed pages
2391 - "cache-miss": number of cache misses
2392 - "overflow": number of XBZRLE overflows
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002393Examples:
2394
23951. Before the first migration
2396
2397-> { "execute": "query-migrate" }
2398<- { "return": {} }
2399
24002. Migration is done and has succeeded
2401
2402-> { "execute": "query-migrate" }
Orit Wasserman004d4c12012-08-06 21:42:56 +03002403<- { "return": {
2404 "status": "completed",
2405 "ram":{
2406 "transferred":123,
2407 "remaining":123,
2408 "total":246,
2409 "total-time":12345,
Juan Quintela9c5a9fc2012-08-13 09:35:16 +02002410 "downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002411 "duplicate":123,
2412 "normal":123,
2413 "normal-bytes":123456
2414 }
2415 }
2416 }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002417
24183. Migration is done and has failed
2419
2420-> { "execute": "query-migrate" }
2421<- { "return": { "status": "failed" } }
2422
24234. Migration is being performed and is not a block migration:
2424
2425-> { "execute": "query-migrate" }
2426<- {
2427 "return":{
2428 "status":"active",
2429 "ram":{
2430 "transferred":123,
2431 "remaining":123,
Orit Wasserman62d4e3f2012-08-06 21:42:55 +03002432 "total":246,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002433 "total-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02002434 "expected-downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002435 "duplicate":123,
2436 "normal":123,
2437 "normal-bytes":123456
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002438 }
2439 }
2440 }
2441
24425. Migration is being performed and is a block migration:
2443
2444-> { "execute": "query-migrate" }
2445<- {
2446 "return":{
2447 "status":"active",
2448 "ram":{
2449 "total":1057024,
2450 "remaining":1053304,
Orit Wasserman62d4e3f2012-08-06 21:42:55 +03002451 "transferred":3720,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002452 "total-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02002453 "expected-downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03002454 "duplicate":123,
2455 "normal":123,
2456 "normal-bytes":123456
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002457 },
2458 "disk":{
2459 "total":20971520,
2460 "remaining":20880384,
2461 "transferred":91136
2462 }
2463 }
2464 }
2465
Orit Wassermanf36d55a2012-08-06 21:42:57 +030024666. Migration is being performed and XBZRLE is active:
2467
2468-> { "execute": "query-migrate" }
2469<- {
2470 "return":{
2471 "status":"active",
2472 "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
2473 "ram":{
2474 "total":1057024,
2475 "remaining":1053304,
2476 "transferred":3720,
2477 "total-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02002478 "expected-downtime":12345,
Orit Wassermanf36d55a2012-08-06 21:42:57 +03002479 "duplicate":10,
2480 "normal":3333,
2481 "normal-bytes":3412992
2482 },
2483 "xbzrle-cache":{
2484 "cache-size":67108864,
2485 "bytes":20971520,
2486 "pages":2444343,
2487 "cache-miss":2244,
2488 "overflow":34434
2489 }
2490 }
2491 }
2492
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002493EQMP
2494
Luiz Capitulino791e7c82011-09-13 17:37:16 -03002495 {
2496 .name = "query-migrate",
2497 .args_type = "",
2498 .mhandler.cmd_new = qmp_marshal_input_query_migrate,
2499 },
2500
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002501SQMP
Orit Wasserman00458432012-08-06 21:42:48 +03002502migrate-set-capabilities
2503-------
2504
2505Enable/Disable migration capabilities
2506
2507- "xbzrle": xbzrle support
2508
2509Arguments:
2510
2511Example:
2512
2513-> { "execute": "migrate-set-capabilities" , "arguments":
2514 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
2515
2516EQMP
2517
2518 {
2519 .name = "migrate-set-capabilities",
2520 .args_type = "capabilities:O",
2521 .params = "capability:s,state:b",
2522 .mhandler.cmd_new = qmp_marshal_input_migrate_set_capabilities,
2523 },
2524SQMP
Orit Wassermanbbf6da32012-08-06 21:42:47 +03002525query-migrate-capabilities
2526-------
2527
2528Query current migration capabilities
2529
2530- "capabilities": migration capabilities state
2531 - "xbzrle" : XBZRLE state (json-bool)
2532
2533Arguments:
2534
2535Example:
2536
2537-> { "execute": "query-migrate-capabilities" }
2538<- { "return": {
2539 "capabilities" : [ { "capability" : "xbzrle", "state" : false } ]
2540 }
2541 }
2542EQMP
2543
2544 {
2545 .name = "query-migrate-capabilities",
2546 .args_type = "",
2547 .mhandler.cmd_new = qmp_marshal_input_query_migrate_capabilities,
2548 },
2549
2550SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002551query-balloon
2552-------------
2553
2554Show balloon information.
2555
2556Make an asynchronous request for balloon info. When the request completes a
2557json-object will be returned containing the following data:
2558
2559- "actual": current balloon value in bytes (json-int)
2560- "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2561- "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2562- "major_page_faults": Number of major faults (json-int, optional)
2563- "minor_page_faults": Number of minor faults (json-int, optional)
2564- "free_mem": Total amount of free and unused memory in
2565 bytes (json-int, optional)
2566- "total_mem": Total amount of available memory in bytes (json-int, optional)
2567
2568Example:
2569
2570-> { "execute": "query-balloon" }
2571<- {
2572 "return":{
2573 "actual":1073741824,
2574 "mem_swapped_in":0,
2575 "mem_swapped_out":0,
2576 "major_page_faults":142,
2577 "minor_page_faults":239245,
2578 "free_mem":1014185984,
2579 "total_mem":1044668416
2580 }
2581 }
2582
2583EQMP
2584
Luiz Capitulino96637bc2011-10-21 11:41:37 -02002585 {
2586 .name = "query-balloon",
2587 .args_type = "",
2588 .mhandler.cmd_new = qmp_marshal_input_query_balloon,
2589 },
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002590
2591 {
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00002592 .name = "query-block-jobs",
2593 .args_type = "",
2594 .mhandler.cmd_new = qmp_marshal_input_query_block_jobs,
2595 },
2596
2597 {
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002598 .name = "qom-list",
2599 .args_type = "path:s",
2600 .mhandler.cmd_new = qmp_marshal_input_qom_list,
2601 },
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002602
2603 {
2604 .name = "qom-set",
Paolo Bonzinib9f89782012-03-22 12:51:11 +01002605 .args_type = "path:s,property:s,value:q",
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002606 .mhandler.cmd_new = qmp_qom_set,
2607 },
2608
2609 {
2610 .name = "qom-get",
2611 .args_type = "path:s,property:s",
2612 .mhandler.cmd_new = qmp_qom_get,
2613 },
Luiz Capitulino270b2432011-12-08 11:45:55 -02002614
2615 {
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02002616 .name = "nbd-server-start",
2617 .args_type = "addr:q",
2618 .mhandler.cmd_new = qmp_marshal_input_nbd_server_start,
2619 },
2620 {
2621 .name = "nbd-server-add",
2622 .args_type = "device:B,writable:b?",
2623 .mhandler.cmd_new = qmp_marshal_input_nbd_server_add,
2624 },
2625 {
2626 .name = "nbd-server-stop",
2627 .args_type = "",
2628 .mhandler.cmd_new = qmp_marshal_input_nbd_server_stop,
2629 },
2630
2631 {
Luiz Capitulino270b2432011-12-08 11:45:55 -02002632 .name = "change-vnc-password",
2633 .args_type = "password:s",
2634 .mhandler.cmd_new = qmp_marshal_input_change_vnc_password,
2635 },
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06002636 {
2637 .name = "qom-list-types",
2638 .args_type = "implements:s?,abstract:b?",
2639 .mhandler.cmd_new = qmp_marshal_input_qom_list_types,
2640 },
Anthony Liguori1daa31b2012-08-10 11:04:09 -05002641
2642 {
2643 .name = "device-list-properties",
2644 .args_type = "typename:s",
2645 .mhandler.cmd_new = qmp_marshal_input_device_list_properties,
2646 },
2647
Anthony Liguori01d3c802012-08-10 11:04:11 -05002648 {
2649 .name = "query-machines",
2650 .args_type = "",
2651 .mhandler.cmd_new = qmp_marshal_input_query_machines,
2652 },
2653
Anthony Liguorie4e31c62012-08-10 11:04:13 -05002654 {
2655 .name = "query-cpu-definitions",
2656 .args_type = "",
2657 .mhandler.cmd_new = qmp_marshal_input_query_cpu_definitions,
2658 },
2659
Daniel P. Berrange99afc912012-08-20 15:31:38 +01002660 {
2661 .name = "query-target",
2662 .args_type = "",
2663 .mhandler.cmd_new = qmp_marshal_input_query_target,
2664 },
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01002665
2666 {
2667 .name = "chardev-add",
2668 .args_type = "id:s,backend:q",
2669 .mhandler.cmd_new = qmp_marshal_input_chardev_add,
2670 },
2671
2672SQMP
2673chardev-add
2674----------------
2675
2676Add a chardev.
2677
2678Arguments:
2679
2680- "id": the chardev's ID, must be unique (json-string)
2681- "backend": chardev backend type + parameters
2682
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01002683Examples:
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01002684
2685-> { "execute" : "chardev-add",
2686 "arguments" : { "id" : "foo",
2687 "backend" : { "type" : "null", "data" : {} } } }
2688<- { "return": {} }
2689
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01002690-> { "execute" : "chardev-add",
2691 "arguments" : { "id" : "bar",
2692 "backend" : { "type" : "file",
2693 "data" : { "out" : "/tmp/bar.log" } } } }
2694<- { "return": {} }
2695
Gerd Hoffmann0a1a7fa2012-12-20 14:39:13 +01002696-> { "execute" : "chardev-add",
2697 "arguments" : { "id" : "baz",
2698 "backend" : { "type" : "pty", "data" : {} } } }
2699<- { "return": { "pty" : "/dev/pty/42" } }
2700
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01002701EQMP
2702
2703 {
2704 .name = "chardev-remove",
2705 .args_type = "id:s",
2706 .mhandler.cmd_new = qmp_marshal_input_chardev_remove,
2707 },
2708
2709
2710SQMP
2711chardev-remove
2712--------------
2713
2714Remove a chardev.
2715
2716Arguments:
2717
2718- "id": the chardev's ID, must exist and not be in use (json-string)
2719
2720Example:
2721
2722-> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
2723<- { "return": {} }
2724
2725EQMP