]> Git Repo - qemu.git/blame - qmp-commands.hx
projects / qemu.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
guest agent: remove uneeded dependencies
[qemu.git] / qmp-commands.hx
CommitLineData
82a56f0d
LC		 1HXCOMM 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
c20cdf8b 45 1. The deprecation policy will take effect and be documented soon, please
82a56f0d
LC		 46 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 = "",
66 .params = "",
67 .help = "quit the emulator",
68 .user_print = monitor_user_noop,
69 .mhandler.cmd_new = do_quit,
70 },
71
72SQMP
73quit
74----
75
76Quit the emulator.
77
78Arguments: None.
79
80Example:
81
82-> { "execute": "quit" }
83<- { "return": {} }
84
85EQMP
86
87 {
88 .name = "eject",
89 .args_type = "force:-f,device:B",
90 .params = "[-f] device",
91 .help = "eject a removable medium (use -f to force it)",
92 .user_print = monitor_user_noop,
93 .mhandler.cmd_new = do_eject,
94 },
95
96SQMP
97eject
98-----
99
100Eject a removable medium.
101
102Arguments:
103
104- force: force ejection (json-bool, optional)
105- device: device name (json-string)
106
107Example:
108
109-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
110<- { "return": {} }
111
112Note: The "force" argument defaults to false.
113
114EQMP
115
116 {
117 .name = "change",
118 .args_type = "device:B,target:F,arg:s?",
119 .params = "device filename [format]",
120 .help = "change a removable medium, optional format",
121 .user_print = monitor_user_noop,
122 .mhandler.cmd_new = do_change,
123 },
124
125SQMP
126change
127------
128
129Change a removable medium or VNC configuration.
130
131Arguments:
132
133- "device": device name (json-string)
134- "target": filename or item (json-string)
135- "arg": additional argument (json-string, optional)
136
137Examples:
138
1391. Change a removable medium
140
141-> { "execute": "change",
142 "arguments": { "device": "ide1-cd0",
143 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
144<- { "return": {} }
145
1462. Change VNC password
147
148-> { "execute": "change",
149 "arguments": { "device": "vnc", "target": "password",
150 "arg": "foobar1" } }
151<- { "return": {} }
152
153EQMP
154
155 {
156 .name = "screendump",
157 .args_type = "filename:F",
158 .params = "filename",
159 .help = "save screen into PPM image 'filename'",
160 .user_print = monitor_user_noop,
161 .mhandler.cmd_new = do_screen_dump,
162 },
163
164SQMP
165screendump
166----------
167
168Save screen into PPM image.
169
170Arguments:
171
172- "filename": file path (json-string)
173
174Example:
175
176-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
177<- { "return": {} }
178
179EQMP
180
181 {
182 .name = "stop",
183 .args_type = "",
184 .params = "",
185 .help = "stop emulation",
186 .user_print = monitor_user_noop,
187 .mhandler.cmd_new = do_stop,
188 },
189
190SQMP
191stop
192----
193
194Stop the emulator.
195
196Arguments: None.
197
198Example:
199
200-> { "execute": "stop" }
201<- { "return": {} }
202
203EQMP
204
205 {
206 .name = "cont",
207 .args_type = "",
208 .params = "",
209 .help = "resume emulation",
210 .user_print = monitor_user_noop,
211 .mhandler.cmd_new = do_cont,
212 },
213
214SQMP
215cont
216----
217
218Resume emulation.
219
220Arguments: None.
221
222Example:
223
224-> { "execute": "cont" }
225<- { "return": {} }
226
227EQMP
228
229 {
230 .name = "system_reset",
231 .args_type = "",
232 .params = "",
233 .help = "reset the system",
234 .user_print = monitor_user_noop,
235 .mhandler.cmd_new = do_system_reset,
236 },
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 = "",
256 .params = "",
257 .help = "send system power down event",
258 .user_print = monitor_user_noop,
259 .mhandler.cmd_new = do_system_powerdown,
260 },
261
262SQMP
263system_powerdown
264----------------
265
266Send system power down event.
267
268Arguments: None.
269
270Example:
271
272-> { "execute": "system_powerdown" }
273<- { "return": {} }
274
275EQMP
276
277 {
278 .name = "device_add",
279 .args_type = "device:O",
280 .params = "driver[,prop=value][,...]",
281 .help = "add device, like -device on the command line",
282 .user_print = monitor_user_noop,
283 .mhandler.cmd_new = do_device_add,
284 },
285
286SQMP
287device_add
288----------
289
290Add a device.
291
292Arguments:
293
294- "driver": the name of the new device's driver (json-string)
295- "bus": the device's parent bus (device tree path, json-string, optional)
296- "id": the device's ID, must be unique (json-string)
297- device properties
298
299Example:
300
301-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
302<- { "return": {} }
303
304Notes:
305
306(1) For detailed information about this command, please refer to the
307 'docs/qdev-device-use.txt' file.
308
309(2) It's possible to list device properties by running QEMU with the
310 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
311
312EQMP
313
314 {
315 .name = "device_del",
316 .args_type = "id:s",
317 .params = "device",
318 .help = "remove device",
319 .user_print = monitor_user_noop,
320 .mhandler.cmd_new = do_device_del,
321 },
322
323SQMP
324device_del
325----------
326
327Remove a device.
328
329Arguments:
330
331- "id": the device's ID (json-string)
332
333Example:
334
335-> { "execute": "device_del", "arguments": { "id": "net1" } }
336<- { "return": {} }
337
338EQMP
339
340 {
341 .name = "cpu",
342 .args_type = "index:i",
343 .params = "index",
344 .help = "set the default CPU",
345 .user_print = monitor_user_noop,
346 .mhandler.cmd_new = do_cpu_set,
347 },
348
349SQMP
350cpu
351---
352
353Set the default CPU.
354
355Arguments:
356
357- "index": the CPU's index (json-int)
358
359Example:
360
361-> { "execute": "cpu", "arguments": { "index": 0 } }
362<- { "return": {} }
363
364Note: CPUs' indexes are obtained with the 'query-cpus' command.
365
366EQMP
367
368 {
369 .name = "memsave",
370 .args_type = "val:l,size:i,filename:s",
371 .params = "addr size file",
372 .help = "save to disk virtual memory dump starting at 'addr' of size 'size'",
373 .user_print = monitor_user_noop,
374 .mhandler.cmd_new = do_memory_save,
375 },
376
377SQMP
378memsave
379-------
380
381Save to disk virtual memory dump starting at 'val' of size 'size'.
382
383Arguments:
384
385- "val": the starting address (json-int)
386- "size": the memory size, in bytes (json-int)
387- "filename": file path (json-string)
388
389Example:
390
391-> { "execute": "memsave",
392 "arguments": { "val": 10,
393 "size": 100,
394 "filename": "/tmp/virtual-mem-dump" } }
395<- { "return": {} }
396
397Note: Depends on the current CPU.
398
399EQMP
400
401 {
402 .name = "pmemsave",
403 .args_type = "val:l,size:i,filename:s",
404 .params = "addr size file",
405 .help = "save to disk physical memory dump starting at 'addr' of size 'size'",
406 .user_print = monitor_user_noop,
407 .mhandler.cmd_new = do_physical_memory_save,
408 },
409
410SQMP
411pmemsave
412--------
413
414Save to disk physical memory dump starting at 'val' of size 'size'.
415
416Arguments:
417
418- "val": the starting address (json-int)
419- "size": the memory size, in bytes (json-int)
420- "filename": file path (json-string)
421
422Example:
423
424-> { "execute": "pmemsave",
425 "arguments": { "val": 10,
426 "size": 100,
427 "filename": "/tmp/physical-mem-dump" } }
428<- { "return": {} }
429
a4046664
LJ		 430EQMP
431
432 {
433 .name = "inject-nmi",
434 .args_type = "",
435 .params = "",
436 .help = "",
437 .user_print = monitor_user_noop,
e9b4b432 438 .mhandler.cmd_new = do_inject_nmi,
a4046664
LJ		 439 },
440
441SQMP
442inject-nmi
443----------
444
445Inject an NMI on guest's CPUs.
446
447Arguments: None.
448
449Example:
450
451-> { "execute": "inject-nmi" }
452<- { "return": {} }
453
454Note: inject-nmi is only supported for x86 guest currently, it will
455 returns "Unsupported" error for non-x86 guest.
456
82a56f0d
LC		 457EQMP
458
459 {
460 .name = "migrate",
461 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
462 .params = "[-d] [-b] [-i] uri",
463 .help = "migrate to URI (using -d to not wait for completion)"
464 "\n\t\t\t -b for migration without shared storage with"
465 " full copy of disk\n\t\t\t -i for migration without "
466 "shared storage with incremental copy of disk "
467 "(base image shared between src and destination)",
468 .user_print = monitor_user_noop,
469 .mhandler.cmd_new = do_migrate,
470 },
471
472SQMP
473migrate
474-------
475
476Migrate to URI.
477
478Arguments:
479
480- "blk": block migration, full disk copy (json-bool, optional)
481- "inc": incremental disk copy (json-bool, optional)
482- "uri": Destination URI (json-string)
483
484Example:
485
486-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
487<- { "return": {} }
488
489Notes:
490
491(1) The 'query-migrate' command should be used to check migration's progress
492 and final result (this information is provided by the 'status' member)
493(2) All boolean arguments default to false
494(3) The user Monitor's "detach" argument is invalid in QMP and should not
495 be used
496
497EQMP
498
499 {
500 .name = "migrate_cancel",
501 .args_type = "",
502 .params = "",
503 .help = "cancel the current VM migration",
504 .user_print = monitor_user_noop,
505 .mhandler.cmd_new = do_migrate_cancel,
506 },
507
508SQMP
509migrate_cancel
510--------------
511
512Cancel the current migration.
513
514Arguments: None.
515
516Example:
517
518-> { "execute": "migrate_cancel" }
519<- { "return": {} }
520
521EQMP
522
523 {
524 .name = "migrate_set_speed",
3a019b6e 525 .args_type = "value:o",
82a56f0d
LC		 526 .params = "value",
527 .help = "set maximum speed (in bytes) for migrations",
528 .user_print = monitor_user_noop,
529 .mhandler.cmd_new = do_migrate_set_speed,
530 },
531
e866e239 532SQMP
ff73edf5
JS		 533migrate_set_speed
534-----------------
e866e239 535
ff73edf5 536Set maximum speed for migrations.
e866e239
GH		 537
538Arguments:
539
ff73edf5 540- "value": maximum speed, in bytes per second (json-int)
e866e239
GH		 541
542Example:
543
ff73edf5 544-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
e866e239
GH		 545<- { "return": {} }
546
547EQMP
548
549 {
ff73edf5
JS		 550 .name = "migrate_set_downtime",
551 .args_type = "value:T",
552 .params = "value",
553 .help = "set maximum tolerated downtime (in seconds) for migrations",
e866e239 554 .user_print = monitor_user_noop,
ff73edf5 555 .mhandler.cmd_new = do_migrate_set_downtime,
e866e239
GH		 556 },
557
82a56f0d 558SQMP
ff73edf5
JS		 559migrate_set_downtime
560--------------------
82a56f0d 561
ff73edf5 562Set maximum tolerated downtime (in seconds) for migrations.
82a56f0d
LC		 563
564Arguments:
565
ff73edf5 566- "value": maximum downtime (json-number)
82a56f0d
LC		 567
568Example:
569
ff73edf5 570-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
82a56f0d
LC		 571<- { "return": {} }
572
573EQMP
574
575 {
ff73edf5
JS		 576 .name = "client_migrate_info",
577 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
578 .params = "protocol hostname port tls-port cert-subject",
579 .help = "send migration info to spice/vnc client",
82a56f0d 580 .user_print = monitor_user_noop,
ff73edf5 581 .mhandler.cmd_new = client_migrate_info,
82a56f0d
LC		 582 },
583
584SQMP
ff73edf5
JS		 585client_migrate_info
586------------------
82a56f0d 587
ff73edf5
JS		 588Set the spice/vnc connection info for the migration target. The spice/vnc
589server will ask the spice/vnc client to automatically reconnect using the
590new parameters (if specified) once the vm migration finished successfully.
82a56f0d
LC		 591
592Arguments:
593
ff73edf5
JS		 594- "protocol": protocol: "spice" or "vnc" (json-string)
595- "hostname": migration target hostname (json-string)
596- "port": spice/vnc tcp port for plaintext channels (json-int, optional)
597- "tls-port": spice tcp port for tls-secured channels (json-int, optional)
598- "cert-subject": server certificate subject (json-string, optional)
82a56f0d
LC		 599
600Example:
601
ff73edf5
JS		 602-> { "execute": "client_migrate_info",
603 "arguments": { "protocol": "spice",
604 "hostname": "virt42.lab.kraxel.org",
605 "port": 1234 } }
82a56f0d
LC		 606<- { "return": {} }
607
608EQMP
609
610 {
611 .name = "netdev_add",
612 .args_type = "netdev:O",
613 .params = "[user|tap|socket],id=str[,prop=value][,...]",
614 .help = "add host network device",
615 .user_print = monitor_user_noop,
616 .mhandler.cmd_new = do_netdev_add,
617 },
618
619SQMP
620netdev_add
621----------
622
623Add host network device.
624
625Arguments:
626
627- "type": the device type, "tap", "user", ... (json-string)
628- "id": the device's ID, must be unique (json-string)
629- device options
630
631Example:
632
633-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
634<- { "return": {} }
635
636Note: The supported device options are the same ones supported by the '-net'
637 command-line argument, which are listed in the '-help' output or QEMU's
638 manual
639
640EQMP
641
642 {
643 .name = "netdev_del",
644 .args_type = "id:s",
645 .params = "id",
646 .help = "remove host network device",
647 .user_print = monitor_user_noop,
648 .mhandler.cmd_new = do_netdev_del,
649 },
650
651SQMP
652netdev_del
653----------
654
655Remove host network device.
656
657Arguments:
658
659- "id": the device's ID, must be unique (json-string)
660
661Example:
662
663-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
664<- { "return": {} }
665
6d4a2b3a
CH		 666
667EQMP
668
669 {
670 .name = "block_resize",
671 .args_type = "device:B,size:o",
672 .params = "device size",
673 .help = "resize a block image",
674 .user_print = monitor_user_noop,
675 .mhandler.cmd_new = do_block_resize,
676 },
677
678SQMP
679block_resize
680------------
681
682Resize a block image while a guest is running.
683
684Arguments:
685
686- "device": the device's ID, must be unique (json-string)
687- "size": new size
688
689Example:
690
691-> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
692<- { "return": {} }
693
d967b2f1
JS		 694EQMP
695
696 {
697 .name = "blockdev-snapshot-sync",
698 .args_type = "device:B,snapshot-file:s?,format:s?",
699 .params = "device [new-image-file] [format]",
700 .user_print = monitor_user_noop,
701 .mhandler.cmd_new = do_snapshot_blkdev,
702 },
703
704SQMP
705blockdev-snapshot-sync
706----------------------
707
708Synchronous snapshot of a block device. snapshot-file specifies the
709target of the new image. If the file exists, or if it is a device, the
710snapshot will be created in the existing file/device. If does not
711exist, a new file will be created. format specifies the format of the
712snapshot image, default is qcow2.
713
714Arguments:
715
716- "device": device name to snapshot (json-string)
717- "snapshot-file": name of new image file (json-string)
718- "format": format of new image (json-string, optional)
719
720Example:
721
722-> { "execute": "blockdev-snapshot", "arguments": { "device": "ide-hd0",
723 "snapshot-file":
724 "/some/place/my-image",
725 "format": "qcow2" } }
726<- { "return": {} }
727
82a56f0d
LC		 728EQMP
729
730 {
731 .name = "balloon",
732 .args_type = "value:M",
733 .params = "target",
734 .help = "request VM to change its memory allocation (in MB)",
735 .user_print = monitor_user_noop,
736 .mhandler.cmd_async = do_balloon,
737 .flags = MONITOR_CMD_ASYNC,
738 },
739
740SQMP
741balloon
742-------
743
744Request VM to change its memory allocation (in bytes).
745
746Arguments:
747
748- "value": New memory allocation (json-int)
749
750Example:
751
752-> { "execute": "balloon", "arguments": { "value": 536870912 } }
753<- { "return": {} }
754
755EQMP
756
757 {
758 .name = "set_link",
759 .args_type = "name:s,up:b",
760 .params = "name on|off",
761 .help = "change the link status of a network adapter",
762 .user_print = monitor_user_noop,
763 .mhandler.cmd_new = do_set_link,
764 },
765
766SQMP
767set_link
768--------
769
770Change the link status of a network adapter.
771
772Arguments:
773
774- "name": network device name (json-string)
775- "up": status is up (json-bool)
776
777Example:
778
779-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
780<- { "return": {} }
781
782EQMP
783
784 {
785 .name = "getfd",
786 .args_type = "fdname:s",
787 .params = "getfd name",
788 .help = "receive a file descriptor via SCM rights and assign it a name",
789 .user_print = monitor_user_noop,
790 .mhandler.cmd_new = do_getfd,
791 },
792
793SQMP
794getfd
795-----
796
797Receive a file descriptor via SCM rights and assign it a name.
798
799Arguments:
800
801- "fdname": file descriptor name (json-string)
802
803Example:
804
805-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
806<- { "return": {} }
807
808EQMP
809
810 {
811 .name = "closefd",
812 .args_type = "fdname:s",
813 .params = "closefd name",
814 .help = "close a file descriptor previously passed via SCM rights",
815 .user_print = monitor_user_noop,
816 .mhandler.cmd_new = do_closefd,
817 },
818
819SQMP
820closefd
821-------
822
823Close a file descriptor previously passed via SCM rights.
824
825Arguments:
826
827- "fdname": file descriptor name (json-string)
828
829Example:
830
831-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
832<- { "return": {} }
833
834EQMP
835
836 {
837 .name = "block_passwd",
838 .args_type = "device:B,password:s",
839 .params = "block_passwd device password",
840 .help = "set the password of encrypted block devices",
841 .user_print = monitor_user_noop,
842 .mhandler.cmd_new = do_block_set_passwd,
843 },
844
845SQMP
846block_passwd
847------------
848
849Set the password of encrypted block devices.
850
851Arguments:
852
853- "device": device name (json-string)
854- "password": password (json-string)
855
856Example:
857
858-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
859 "password": "12345" } }
860<- { "return": {} }
861
7572150c
GH		 862EQMP
863
864 {
865 .name = "set_password",
866 .args_type = "protocol:s,password:s,connected:s?",
867 .params = "protocol password action-if-connected",
868 .help = "set spice/vnc password",
869 .user_print = monitor_user_noop,
870 .mhandler.cmd_new = set_password,
871 },
872
873SQMP
874set_password
875------------
876
877Set the password for vnc/spice protocols.
878
879Arguments:
880
881- "protocol": protocol name (json-string)
882- "password": password (json-string)
883- "connected": [ keep | disconnect | fail ] (josn-string, optional)
884
885Example:
886
887-> { "execute": "set_password", "arguments": { "protocol": "vnc",
888 "password": "secret" } }
889<- { "return": {} }
890
891EQMP
892
893 {
894 .name = "expire_password",
895 .args_type = "protocol:s,time:s",
896 .params = "protocol time",
897 .help = "set spice/vnc password expire-time",
898 .user_print = monitor_user_noop,
899 .mhandler.cmd_new = expire_password,
900 },
901
902SQMP
903expire_password
904---------------
905
906Set the password expire time for vnc/spice protocols.
907
908Arguments:
909
910- "protocol": protocol name (json-string)
911- "time": [ now | never | +secs | secs ] (json-string)
912
913Example:
914
915-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
916 "time": "+60" } }
917<- { "return": {} }
918
82a56f0d
LC		 919EQMP
920
13661089
DB		 921 {
922 .name = "add_client",
923 .args_type = "protocol:s,fdname:s,skipauth:b?",
924 .params = "protocol fdname skipauth",
925 .help = "add a graphics client",
926 .user_print = monitor_user_noop,
927 .mhandler.cmd_new = add_graphics_client,
928 },
929
930SQMP
931add_client
932----------
933
934Add a graphics client
935
936Arguments:
937
938- "protocol": protocol name (json-string)
939- "fdname": file descriptor name (json-string)
940
941Example:
942
943-> { "execute": "add_client", "arguments": { "protocol": "vnc",
944 "fdname": "myclient" } }
945<- { "return": {} }
946
947EQMP
82a56f0d
LC		 948 {
949 .name = "qmp_capabilities",
950 .args_type = "",
951 .params = "",
952 .help = "enable QMP capabilities",
953 .user_print = monitor_user_noop,
954 .mhandler.cmd_new = do_qmp_capabilities,
955 },
956
957SQMP
958qmp_capabilities
959----------------
960
961Enable QMP capabilities.
962
963Arguments: None.
964
965Example:
966
967-> { "execute": "qmp_capabilities" }
968<- { "return": {} }
969
970Note: This command must be issued before issuing any other command.
971
0268d97c
LC		 972EQMP
973
974 {
975 .name = "human-monitor-command",
976 .args_type = "command-line:s,cpu-index:i?",
977 .params = "",
978 .help = "",
979 .user_print = monitor_user_noop,
980 .mhandler.cmd_new = do_hmp_passthrough,
981 },
982
983SQMP
984human-monitor-command
985---------------------
986
987Execute a Human Monitor command.
988
989Arguments:
990
991- command-line: the command name and its arguments, just like the
992 Human Monitor's shell (json-string)
993- cpu-index: select the CPU number to be used by commands which access CPU
994 data, like 'info registers'. The Monitor selects CPU 0 if this
995 argument is not provided (json-int, optional)
996
997Example:
998
999-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1000<- { "return": "kvm support: enabled\r\n" }
1001
1002Notes:
1003
1004(1) The Human Monitor is NOT an stable interface, this means that command
1005 names, arguments and responses can change or be removed at ANY time.
1006 Applications that rely on long term stability guarantees should NOT
1007 use this command
1008
1009(2) Limitations:
1010
1011 o This command is stateless, this means that commands that depend
1012 on state information (such as getfd) might not work
1013
1014 o Commands that prompt the user for data (eg. 'cont' when the block
1015 device is encrypted) don't currently work
1016
82a56f0d
LC		 10173. Query Commands
1018=================
1019
1020HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
1021HXCOMM this! We will possibly move query commands definitions inside those
1022HXCOMM sections, just like regular commands.
1023
1024EQMP
1025
1026SQMP
1027query-version
1028-------------
1029
1030Show QEMU version.
1031
1032Return a json-object with the following information:
1033
1034- "qemu": A json-object containing three integer values:
1035 - "major": QEMU's major version (json-int)
1036 - "minor": QEMU's minor version (json-int)
1037 - "micro": QEMU's micro version (json-int)
1038- "package": package's version (json-string)
1039
1040Example:
1041
1042-> { "execute": "query-version" }
1043<- {
1044 "return":{
1045 "qemu":{
1046 "major":0,
1047 "minor":11,
1048 "micro":5
1049 },
1050 "package":""
1051 }
1052 }
1053
1054EQMP
1055
1056SQMP
1057query-commands
1058--------------
1059
1060List QMP available commands.
1061
1062Each command is represented by a json-object, the returned value is a json-array
1063of all commands.
1064
1065Each json-object contain:
1066
1067- "name": command's name (json-string)
1068
1069Example:
1070
1071-> { "execute": "query-commands" }
1072<- {
1073 "return":[
1074 {
1075 "name":"query-balloon"
1076 },
1077 {
1078 "name":"system_powerdown"
1079 }
1080 ]
1081 }
1082
1083Note: This example has been shortened as the real response is too long.
1084
1085EQMP
1086
1087SQMP
1088query-chardev
1089-------------
1090
1091Each device is represented by a json-object. The returned value is a json-array
1092of all devices.
1093
1094Each json-object contain the following:
1095
1096- "label": device's label (json-string)
1097- "filename": device's file (json-string)
1098
1099Example:
1100
1101-> { "execute": "query-chardev" }
1102<- {
1103 "return":[
1104 {
1105 "label":"monitor",
1106 "filename":"stdio"
1107 },
1108 {
1109 "label":"serial0",
1110 "filename":"vc"
1111 }
1112 ]
1113 }
1114
1115EQMP
1116
1117SQMP
1118query-block
1119-----------
1120
1121Show the block devices.
1122
1123Each block device information is stored in a json-object and the returned value
1124is a json-array of all devices.
1125
1126Each json-object contain the following:
1127
1128- "device": device name (json-string)
1129- "type": device type (json-string)
d8aeeb31
MA		 1130 - deprecated, retained for backward compatibility
1131 - Possible values: "unknown"
82a56f0d
LC		 1132- "removable": true if the device is removable, false otherwise (json-bool)
1133- "locked": true if the device is locked, false otherwise (json-bool)
1134- "inserted": only present if the device is inserted, it is a json-object
1135 containing the following:
1136 - "file": device file name (json-string)
1137 - "ro": true if read-only, false otherwise (json-bool)
1138 - "drv": driver format name (json-string)
1139 - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1140 "file", "file", "ftp", "ftps", "host_cdrom",
1141 "host_device", "host_floppy", "http", "https",
1142 "nbd", "parallels", "qcow", "qcow2", "raw",
1143 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1144 - "backing_file": backing file name (json-string, optional)
1145 - "encrypted": true if encrypted, false otherwise (json-bool)
1146
1147Example:
1148
1149-> { "execute": "query-block" }
1150<- {
1151 "return":[
1152 {
1153 "device":"ide0-hd0",
1154 "locked":false,
1155 "removable":false,
1156 "inserted":{
1157 "ro":false,
1158 "drv":"qcow2",
1159 "encrypted":false,
1160 "file":"disks/test.img"
1161 },
d8aeeb31 1162 "type":"unknown"
82a56f0d
LC		 1163 },
1164 {
1165 "device":"ide1-cd0",
1166 "locked":false,
1167 "removable":true,
d8aeeb31 1168 "type":"unknown"
82a56f0d
LC		 1169 },
1170 {
1171 "device":"floppy0",
1172 "locked":false,
1173 "removable":true,
d8aeeb31 1174 "type":"unknown"
82a56f0d
LC		 1175 },
1176 {
1177 "device":"sd0",
1178 "locked":false,
1179 "removable":true,
d8aeeb31 1180 "type":"unknown"
82a56f0d
LC		 1181 }
1182 ]
1183 }
1184
1185EQMP
1186
1187SQMP
1188query-blockstats
1189----------------
1190
1191Show block device statistics.
1192
1193Each device statistic information is stored in a json-object and the returned
1194value is a json-array of all devices.
1195
1196Each json-object contain the following:
1197
1198- "device": device name (json-string)
1199- "stats": A json-object with the statistics information, it contains:
1200 - "rd_bytes": bytes read (json-int)
1201 - "wr_bytes": bytes written (json-int)
1202 - "rd_operations": read operations (json-int)
1203 - "wr_operations": write operations (json-int)
1204 - "wr_highest_offset": Highest offset of a sector written since the
1205 BlockDriverState has been opened (json-int)
1206- "parent": Contains recursively the statistics of the underlying
1207 protocol (e.g. the host file for a qcow2 image). If there is
1208 no underlying protocol, this field is omitted
1209 (json-object, optional)
1210
1211Example:
1212
1213-> { "execute": "query-blockstats" }
1214<- {
1215 "return":[
1216 {
1217 "device":"ide0-hd0",
1218 "parent":{
1219 "stats":{
1220 "wr_highest_offset":3686448128,
1221 "wr_bytes":9786368,
1222 "wr_operations":751,
1223 "rd_bytes":122567168,
1224 "rd_operations":36772
1225 }
1226 },
1227 "stats":{
1228 "wr_highest_offset":2821110784,
1229 "wr_bytes":9786368,
1230 "wr_operations":692,
1231 "rd_bytes":122739200,
1232 "rd_operations":36604
1233 }
1234 },
1235 {
1236 "device":"ide1-cd0",
1237 "stats":{
1238 "wr_highest_offset":0,
1239 "wr_bytes":0,
1240 "wr_operations":0,
1241 "rd_bytes":0,
1242 "rd_operations":0
1243 }
1244 },
1245 {
1246 "device":"floppy0",
1247 "stats":{
1248 "wr_highest_offset":0,
1249 "wr_bytes":0,
1250 "wr_operations":0,
1251 "rd_bytes":0,
1252 "rd_operations":0
1253 }
1254 },
1255 {
1256 "device":"sd0",
1257 "stats":{
1258 "wr_highest_offset":0,
1259 "wr_bytes":0,
1260 "wr_operations":0,
1261 "rd_bytes":0,
1262 "rd_operations":0
1263 }
1264 }
1265 ]
1266 }
1267
1268EQMP
1269
1270SQMP
1271query-cpus
1272----------
1273
1274Show CPU information.
1275
1276Return a json-array. Each CPU is represented by a json-object, which contains:
1277
1278- "CPU": CPU index (json-int)
1279- "current": true if this is the current CPU, false otherwise (json-bool)
1280- "halted": true if the cpu is halted, false otherwise (json-bool)
1281- Current program counter. The key's name depends on the architecture:
1282 "pc": i386/x86_64 (json-int)
1283 "nip": PPC (json-int)
1284 "pc" and "npc": sparc (json-int)
1285 "PC": mips (json-int)
dc7a09cf 1286- "thread_id": ID of the underlying host thread (json-int)
82a56f0d
LC		 1287
1288Example:
1289
1290-> { "execute": "query-cpus" }
1291<- {
1292 "return":[
1293 {
1294 "CPU":0,
1295 "current":true,
1296 "halted":false,
1297 "pc":3227107138
dc7a09cf 1298 "thread_id":3134
82a56f0d
LC		 1299 },
1300 {
1301 "CPU":1,
1302 "current":false,
1303 "halted":true,
1304 "pc":7108165
dc7a09cf 1305 "thread_id":3135
82a56f0d
LC		 1306 }
1307 ]
1308 }
1309
1310EQMP
1311
1312SQMP
1313query-pci
1314---------
1315
1316PCI buses and devices information.
1317
1318The returned value is a json-array of all buses. Each bus is represented by
1319a json-object, which has a key with a json-array of all PCI devices attached
1320to it. Each device is represented by a json-object.
1321
1322The bus json-object contains the following:
1323
1324- "bus": bus number (json-int)
1325- "devices": a json-array of json-objects, each json-object represents a
1326 PCI device
1327
1328The PCI device json-object contains the following:
1329
1330- "bus": identical to the parent's bus number (json-int)
1331- "slot": slot number (json-int)
1332- "function": function number (json-int)
1333- "class_info": a json-object containing:
1334 - "desc": device class description (json-string, optional)
1335 - "class": device class number (json-int)
1336- "id": a json-object containing:
1337 - "device": device ID (json-int)
1338 - "vendor": vendor ID (json-int)
1339- "irq": device's IRQ if assigned (json-int, optional)
1340- "qdev_id": qdev id string (json-string)
1341- "pci_bridge": It's a json-object, only present if this device is a
1342 PCI bridge, contains:
1343 - "bus": bus number (json-int)
1344 - "secondary": secondary bus number (json-int)
1345 - "subordinate": subordinate bus number (json-int)
1346 - "io_range": I/O memory range information, a json-object with the
1347 following members:
1348 - "base": base address, in bytes (json-int)
1349 - "limit": limit address, in bytes (json-int)
1350 - "memory_range": memory range information, a json-object with the
1351 following members:
1352 - "base": base address, in bytes (json-int)
1353 - "limit": limit address, in bytes (json-int)
1354 - "prefetchable_range": Prefetchable memory range information, a
1355 json-object with the following members:
1356 - "base": base address, in bytes (json-int)
1357 - "limit": limit address, in bytes (json-int)
1358 - "devices": a json-array of PCI devices if there's any attached, each
1359 each element is represented by a json-object, which contains
1360 the same members of the 'PCI device json-object' described
1361 above (optional)
1362- "regions": a json-array of json-objects, each json-object represents a
1363 memory region of this device
1364
1365The memory range json-object contains the following:
1366
1367- "base": base memory address (json-int)
1368- "limit": limit value (json-int)
1369
1370The region json-object can be an I/O region or a memory region, an I/O region
1371json-object contains the following:
1372
1373- "type": "io" (json-string, fixed)
1374- "bar": BAR number (json-int)
1375- "address": memory address (json-int)
1376- "size": memory size (json-int)
1377
1378A memory region json-object contains the following:
1379
1380- "type": "memory" (json-string, fixed)
1381- "bar": BAR number (json-int)
1382- "address": memory address (json-int)
1383- "size": memory size (json-int)
1384- "mem_type_64": true or false (json-bool)
1385- "prefetch": true or false (json-bool)
1386
1387Example:
1388
1389-> { "execute": "query-pci" }
1390<- {
1391 "return":[
1392 {
1393 "bus":0,
1394 "devices":[
1395 {
1396 "bus":0,
1397 "qdev_id":"",
1398 "slot":0,
1399 "class_info":{
1400 "class":1536,
1401 "desc":"Host bridge"
1402 },
1403 "id":{
1404 "device":32902,
1405 "vendor":4663
1406 },
1407 "function":0,
1408 "regions":[
1409
1410 ]
1411 },
1412 {
1413 "bus":0,
1414 "qdev_id":"",
1415 "slot":1,
1416 "class_info":{
1417 "class":1537,
1418 "desc":"ISA bridge"
1419 },
1420 "id":{
1421 "device":32902,
1422 "vendor":28672
1423 },
1424 "function":0,
1425 "regions":[
1426
1427 ]
1428 },
1429 {
1430 "bus":0,
1431 "qdev_id":"",
1432 "slot":1,
1433 "class_info":{
1434 "class":257,
1435 "desc":"IDE controller"
1436 },
1437 "id":{
1438 "device":32902,
1439 "vendor":28688
1440 },
1441 "function":1,
1442 "regions":[
1443 {
1444 "bar":4,
1445 "size":16,
1446 "address":49152,
1447 "type":"io"
1448 }
1449 ]
1450 },
1451 {
1452 "bus":0,
1453 "qdev_id":"",
1454 "slot":2,
1455 "class_info":{
1456 "class":768,
1457 "desc":"VGA controller"
1458 },
1459 "id":{
1460 "device":4115,
1461 "vendor":184
1462 },
1463 "function":0,
1464 "regions":[
1465 {
1466 "prefetch":true,
1467 "mem_type_64":false,
1468 "bar":0,
1469 "size":33554432,
1470 "address":4026531840,
1471 "type":"memory"
1472 },
1473 {
1474 "prefetch":false,
1475 "mem_type_64":false,
1476 "bar":1,
1477 "size":4096,
1478 "address":4060086272,
1479 "type":"memory"
1480 },
1481 {
1482 "prefetch":false,
1483 "mem_type_64":false,
1484 "bar":6,
1485 "size":65536,
1486 "address":-1,
1487 "type":"memory"
1488 }
1489 ]
1490 },
1491 {
1492 "bus":0,
1493 "qdev_id":"",
1494 "irq":11,
1495 "slot":4,
1496 "class_info":{
1497 "class":1280,
1498 "desc":"RAM controller"
1499 },
1500 "id":{
1501 "device":6900,
1502 "vendor":4098
1503 },
1504 "function":0,
1505 "regions":[
1506 {
1507 "bar":0,
1508 "size":32,
1509 "address":49280,
1510 "type":"io"
1511 }
1512 ]
1513 }
1514 ]
1515 }
1516 ]
1517 }
1518
1519Note: This example has been shortened as the real response is too long.
1520
1521EQMP
1522
1523SQMP
1524query-kvm
1525---------
1526
1527Show KVM information.
1528
1529Return a json-object with the following information:
1530
1531- "enabled": true if KVM support is enabled, false otherwise (json-bool)
1532- "present": true if QEMU has KVM support, false otherwise (json-bool)
1533
1534Example:
1535
1536-> { "execute": "query-kvm" }
1537<- { "return": { "enabled": true, "present": true } }
1538
1539EQMP
1540
1541SQMP
1542query-status
1543------------
1544
1545Return a json-object with the following information:
1546
1547- "running": true if the VM is running, or false if it is paused (json-bool)
1548- "singlestep": true if the VM is in single step mode,
1549 false otherwise (json-bool)
1550
1551Example:
1552
1553-> { "execute": "query-status" }
1554<- { "return": { "running": true, "singlestep": false } }
1555
1556EQMP
1557
1558SQMP
1559query-mice
1560----------
1561
1562Show VM mice information.
1563
1564Each mouse is represented by a json-object, the returned value is a json-array
1565of all mice.
1566
1567The mouse json-object contains the following:
1568
1569- "name": mouse's name (json-string)
1570- "index": mouse's index (json-int)
1571- "current": true if this mouse is receiving events, false otherwise (json-bool)
1572- "absolute": true if the mouse generates absolute input events (json-bool)
1573
1574Example:
1575
1576-> { "execute": "query-mice" }
1577<- {
1578 "return":[
1579 {
1580 "name":"QEMU Microsoft Mouse",
1581 "index":0,
1582 "current":false,
1583 "absolute":false
1584 },
1585 {
1586 "name":"QEMU PS/2 Mouse",
1587 "index":1,
1588 "current":true,
1589 "absolute":true
1590 }
1591 ]
1592 }
1593
1594EQMP
1595
1596SQMP
1597query-vnc
1598---------
1599
1600Show VNC server information.
1601
1602Return a json-object with server information. Connected clients are returned
1603as a json-array of json-objects.
1604
1605The main json-object contains the following:
1606
1607- "enabled": true or false (json-bool)
1608- "host": server's IP address (json-string)
1609- "family": address family (json-string)
1610 - Possible values: "ipv4", "ipv6", "unix", "unknown"
1611- "service": server's port number (json-string)
1612- "auth": authentication method (json-string)
1613 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
1614 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
1615 "vencrypt+plain", "vencrypt+tls+none",
1616 "vencrypt+tls+plain", "vencrypt+tls+sasl",
1617 "vencrypt+tls+vnc", "vencrypt+x509+none",
1618 "vencrypt+x509+plain", "vencrypt+x509+sasl",
1619 "vencrypt+x509+vnc", "vnc"
1620- "clients": a json-array of all connected clients
1621
1622Clients are described by a json-object, each one contain the following:
1623
1624- "host": client's IP address (json-string)
1625- "family": address family (json-string)
1626 - Possible values: "ipv4", "ipv6", "unix", "unknown"
1627- "service": client's port number (json-string)
1628- "x509_dname": TLS dname (json-string, optional)
1629- "sasl_username": SASL username (json-string, optional)
1630
1631Example:
1632
1633-> { "execute": "query-vnc" }
1634<- {
1635 "return":{
1636 "enabled":true,
1637 "host":"0.0.0.0",
1638 "service":"50402",
1639 "auth":"vnc",
1640 "family":"ipv4",
1641 "clients":[
1642 {
1643 "host":"127.0.0.1",
1644 "service":"50401",
1645 "family":"ipv4"
1646 }
1647 ]
1648 }
1649 }
1650
1651EQMP
1652
cb42a870
GH		 1653SQMP
1654query-spice
1655-----------
1656
1657Show SPICE server information.
1658
1659Return a json-object with server information. Connected clients are returned
1660as a json-array of json-objects.
1661
1662The main json-object contains the following:
1663
1664- "enabled": true or false (json-bool)
1665- "host": server's IP address (json-string)
1666- "port": server's port number (json-int, optional)
1667- "tls-port": server's port number (json-int, optional)
1668- "auth": authentication method (json-string)
1669 - Possible values: "none", "spice"
1670- "channels": a json-array of all active channels clients
1671
1672Channels are described by a json-object, each one contain the following:
1673
1674- "host": client's IP address (json-string)
1675- "family": address family (json-string)
1676 - Possible values: "ipv4", "ipv6", "unix", "unknown"
1677- "port": client's port number (json-string)
1678- "connection-id": spice connection id. All channels with the same id
1679 belong to the same spice session (json-int)
1680- "channel-type": channel type. "1" is the main control channel, filter for
1681 this one if you want track spice sessions only (json-int)
1682- "channel-id": channel id. Usually "0", might be different needed when
1683 multiple channels of the same type exist, such as multiple
1684 display channels in a multihead setup (json-int)
1685- "tls": whevener the channel is encrypted (json-bool)
1686
1687Example:
1688
1689-> { "execute": "query-spice" }
1690<- {
1691 "return": {
1692 "enabled": true,
1693 "auth": "spice",
1694 "port": 5920,
1695 "tls-port": 5921,
1696 "host": "0.0.0.0",
1697 "channels": [
1698 {
1699 "port": "54924",
1700 "family": "ipv4",
1701 "channel-type": 1,
1702 "connection-id": 1804289383,
1703 "host": "127.0.0.1",
1704 "channel-id": 0,
1705 "tls": true
1706 },
1707 {
1708 "port": "36710",
1709 "family": "ipv4",
1710 "channel-type": 4,
1711 "connection-id": 1804289383,
1712 "host": "127.0.0.1",
1713 "channel-id": 0,
1714 "tls": false
1715 },
1716 [ ... more channels follow ... ]
1717 ]
1718 }
1719 }
1720
1721EQMP
1722
82a56f0d
LC		 1723SQMP
1724query-name
1725----------
1726
1727Show VM name.
1728
1729Return a json-object with the following information:
1730
1731- "name": VM's name (json-string, optional)
1732
1733Example:
1734
1735-> { "execute": "query-name" }
1736<- { "return": { "name": "qemu-name" } }
1737
1738EQMP
1739
1740SQMP
1741query-uuid
1742----------
1743
1744Show VM UUID.
1745
1746Return a json-object with the following information:
1747
1748- "UUID": Universally Unique Identifier (json-string)
1749
1750Example:
1751
1752-> { "execute": "query-uuid" }
1753<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
1754
1755EQMP
1756
1757SQMP
1758query-migrate
1759-------------
1760
1761Migration status.
1762
1763Return a json-object. If migration is active there will be another json-object
1764with RAM migration status and if block migration is active another one with
1765block migration status.
1766
1767The main json-object contains the following:
1768
1769- "status": migration status (json-string)
1770 - Possible values: "active", "completed", "failed", "cancelled"
1771- "ram": only present if "status" is "active", it is a json-object with the
1772 following RAM information (in bytes):
1773 - "transferred": amount transferred (json-int)
1774 - "remaining": amount remaining (json-int)
1775 - "total": total (json-int)
1776- "disk": only present if "status" is "active" and it is a block migration,
1777 it is a json-object with the following disk information (in bytes):
1778 - "transferred": amount transferred (json-int)
1779 - "remaining": amount remaining (json-int)
1780 - "total": total (json-int)
1781
1782Examples:
1783
17841. Before the first migration
1785
1786-> { "execute": "query-migrate" }
1787<- { "return": {} }
1788
17892. Migration is done and has succeeded
1790
1791-> { "execute": "query-migrate" }
1792<- { "return": { "status": "completed" } }
1793
17943. Migration is done and has failed
1795
1796-> { "execute": "query-migrate" }
1797<- { "return": { "status": "failed" } }
1798
17994. Migration is being performed and is not a block migration:
1800
1801-> { "execute": "query-migrate" }
1802<- {
1803 "return":{
1804 "status":"active",
1805 "ram":{
1806 "transferred":123,
1807 "remaining":123,
1808 "total":246
1809 }
1810 }
1811 }
1812
18135. Migration is being performed and is a block migration:
1814
1815-> { "execute": "query-migrate" }
1816<- {
1817 "return":{
1818 "status":"active",
1819 "ram":{
1820 "total":1057024,
1821 "remaining":1053304,
1822 "transferred":3720
1823 },
1824 "disk":{
1825 "total":20971520,
1826 "remaining":20880384,
1827 "transferred":91136
1828 }
1829 }
1830 }
1831
1832EQMP
1833
1834SQMP
1835query-balloon
1836-------------
1837
1838Show balloon information.
1839
1840Make an asynchronous request for balloon info. When the request completes a
1841json-object will be returned containing the following data:
1842
1843- "actual": current balloon value in bytes (json-int)
1844- "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
1845- "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
1846- "major_page_faults": Number of major faults (json-int, optional)
1847- "minor_page_faults": Number of minor faults (json-int, optional)
1848- "free_mem": Total amount of free and unused memory in
1849 bytes (json-int, optional)
1850- "total_mem": Total amount of available memory in bytes (json-int, optional)
1851
1852Example:
1853
1854-> { "execute": "query-balloon" }
1855<- {
1856 "return":{
1857 "actual":1073741824,
1858 "mem_swapped_in":0,
1859 "mem_swapped_out":0,
1860 "major_page_faults":142,
1861 "minor_page_faults":239245,
1862 "free_mem":1014185984,
1863 "total_mem":1044668416
1864 }
1865 }
1866
1867EQMP
1868
Empty description
This page took 0.366283 seconds and 4 git commands to generate.