]> git.proxmox.com Git - qemu.git/blame - qmp-commands.hx
projects / qemu.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
USB: add usb network redirection support
[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
45 1. The deprecation policy will take efect and be documented soon, please
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
82a56f0d
LC		 694EQMP
695
696 {
697 .name = "balloon",
698 .args_type = "value:M",
699 .params = "target",
700 .help = "request VM to change its memory allocation (in MB)",
701 .user_print = monitor_user_noop,
702 .mhandler.cmd_async = do_balloon,
703 .flags = MONITOR_CMD_ASYNC,
704 },
705
706SQMP
707balloon
708-------
709
710Request VM to change its memory allocation (in bytes).
711
712Arguments:
713
714- "value": New memory allocation (json-int)
715
716Example:
717
718-> { "execute": "balloon", "arguments": { "value": 536870912 } }
719<- { "return": {} }
720
721EQMP
722
723 {
724 .name = "set_link",
725 .args_type = "name:s,up:b",
726 .params = "name on|off",
727 .help = "change the link status of a network adapter",
728 .user_print = monitor_user_noop,
729 .mhandler.cmd_new = do_set_link,
730 },
731
732SQMP
733set_link
734--------
735
736Change the link status of a network adapter.
737
738Arguments:
739
740- "name": network device name (json-string)
741- "up": status is up (json-bool)
742
743Example:
744
745-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
746<- { "return": {} }
747
748EQMP
749
750 {
751 .name = "getfd",
752 .args_type = "fdname:s",
753 .params = "getfd name",
754 .help = "receive a file descriptor via SCM rights and assign it a name",
755 .user_print = monitor_user_noop,
756 .mhandler.cmd_new = do_getfd,
757 },
758
759SQMP
760getfd
761-----
762
763Receive a file descriptor via SCM rights and assign it a name.
764
765Arguments:
766
767- "fdname": file descriptor name (json-string)
768
769Example:
770
771-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
772<- { "return": {} }
773
774EQMP
775
776 {
777 .name = "closefd",
778 .args_type = "fdname:s",
779 .params = "closefd name",
780 .help = "close a file descriptor previously passed via SCM rights",
781 .user_print = monitor_user_noop,
782 .mhandler.cmd_new = do_closefd,
783 },
784
785SQMP
786closefd
787-------
788
789Close a file descriptor previously passed via SCM rights.
790
791Arguments:
792
793- "fdname": file descriptor name (json-string)
794
795Example:
796
797-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
798<- { "return": {} }
799
800EQMP
801
802 {
803 .name = "block_passwd",
804 .args_type = "device:B,password:s",
805 .params = "block_passwd device password",
806 .help = "set the password of encrypted block devices",
807 .user_print = monitor_user_noop,
808 .mhandler.cmd_new = do_block_set_passwd,
809 },
810
811SQMP
812block_passwd
813------------
814
815Set the password of encrypted block devices.
816
817Arguments:
818
819- "device": device name (json-string)
820- "password": password (json-string)
821
822Example:
823
824-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
825 "password": "12345" } }
826<- { "return": {} }
827
7572150c
GH		 828EQMP
829
830 {
831 .name = "set_password",
832 .args_type = "protocol:s,password:s,connected:s?",
833 .params = "protocol password action-if-connected",
834 .help = "set spice/vnc password",
835 .user_print = monitor_user_noop,
836 .mhandler.cmd_new = set_password,
837 },
838
839SQMP
840set_password
841------------
842
843Set the password for vnc/spice protocols.
844
845Arguments:
846
847- "protocol": protocol name (json-string)
848- "password": password (json-string)
849- "connected": [ keep | disconnect | fail ] (josn-string, optional)
850
851Example:
852
853-> { "execute": "set_password", "arguments": { "protocol": "vnc",
854 "password": "secret" } }
855<- { "return": {} }
856
857EQMP
858
859 {
860 .name = "expire_password",
861 .args_type = "protocol:s,time:s",
862 .params = "protocol time",
863 .help = "set spice/vnc password expire-time",
864 .user_print = monitor_user_noop,
865 .mhandler.cmd_new = expire_password,
866 },
867
868SQMP
869expire_password
870---------------
871
872Set the password expire time for vnc/spice protocols.
873
874Arguments:
875
876- "protocol": protocol name (json-string)
877- "time": [ now | never | +secs | secs ] (json-string)
878
879Example:
880
881-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
882 "time": "+60" } }
883<- { "return": {} }
884
82a56f0d
LC		 885EQMP
886
887 {
888 .name = "qmp_capabilities",
889 .args_type = "",
890 .params = "",
891 .help = "enable QMP capabilities",
892 .user_print = monitor_user_noop,
893 .mhandler.cmd_new = do_qmp_capabilities,
894 },
895
896SQMP
897qmp_capabilities
898----------------
899
900Enable QMP capabilities.
901
902Arguments: None.
903
904Example:
905
906-> { "execute": "qmp_capabilities" }
907<- { "return": {} }
908
909Note: This command must be issued before issuing any other command.
910
0268d97c
LC		 911EQMP
912
913 {
914 .name = "human-monitor-command",
915 .args_type = "command-line:s,cpu-index:i?",
916 .params = "",
917 .help = "",
918 .user_print = monitor_user_noop,
919 .mhandler.cmd_new = do_hmp_passthrough,
920 },
921
922SQMP
923human-monitor-command
924---------------------
925
926Execute a Human Monitor command.
927
928Arguments:
929
930- command-line: the command name and its arguments, just like the
931 Human Monitor's shell (json-string)
932- cpu-index: select the CPU number to be used by commands which access CPU
933 data, like 'info registers'. The Monitor selects CPU 0 if this
934 argument is not provided (json-int, optional)
935
936Example:
937
938-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
939<- { "return": "kvm support: enabled\r\n" }
940
941Notes:
942
943(1) The Human Monitor is NOT an stable interface, this means that command
944 names, arguments and responses can change or be removed at ANY time.
945 Applications that rely on long term stability guarantees should NOT
946 use this command
947
948(2) Limitations:
949
950 o This command is stateless, this means that commands that depend
951 on state information (such as getfd) might not work
952
953 o Commands that prompt the user for data (eg. 'cont' when the block
954 device is encrypted) don't currently work
955
82a56f0d
LC		 9563. Query Commands
957=================
958
959HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
960HXCOMM this! We will possibly move query commands definitions inside those
961HXCOMM sections, just like regular commands.
962
963EQMP
964
965SQMP
966query-version
967-------------
968
969Show QEMU version.
970
971Return a json-object with the following information:
972
973- "qemu": A json-object containing three integer values:
974 - "major": QEMU's major version (json-int)
975 - "minor": QEMU's minor version (json-int)
976 - "micro": QEMU's micro version (json-int)
977- "package": package's version (json-string)
978
979Example:
980
981-> { "execute": "query-version" }
982<- {
983 "return":{
984 "qemu":{
985 "major":0,
986 "minor":11,
987 "micro":5
988 },
989 "package":""
990 }
991 }
992
993EQMP
994
995SQMP
996query-commands
997--------------
998
999List QMP available commands.
1000
1001Each command is represented by a json-object, the returned value is a json-array
1002of all commands.
1003
1004Each json-object contain:
1005
1006- "name": command's name (json-string)
1007
1008Example:
1009
1010-> { "execute": "query-commands" }
1011<- {
1012 "return":[
1013 {
1014 "name":"query-balloon"
1015 },
1016 {
1017 "name":"system_powerdown"
1018 }
1019 ]
1020 }
1021
1022Note: This example has been shortened as the real response is too long.
1023
1024EQMP
1025
1026SQMP
1027query-chardev
1028-------------
1029
1030Each device is represented by a json-object. The returned value is a json-array
1031of all devices.
1032
1033Each json-object contain the following:
1034
1035- "label": device's label (json-string)
1036- "filename": device's file (json-string)
1037
1038Example:
1039
1040-> { "execute": "query-chardev" }
1041<- {
1042 "return":[
1043 {
1044 "label":"monitor",
1045 "filename":"stdio"
1046 },
1047 {
1048 "label":"serial0",
1049 "filename":"vc"
1050 }
1051 ]
1052 }
1053
1054EQMP
1055
1056SQMP
1057query-block
1058-----------
1059
1060Show the block devices.
1061
1062Each block device information is stored in a json-object and the returned value
1063is a json-array of all devices.
1064
1065Each json-object contain the following:
1066
1067- "device": device name (json-string)
1068- "type": device type (json-string)
d8aeeb31
MA		 1069 - deprecated, retained for backward compatibility
1070 - Possible values: "unknown"
82a56f0d
LC		 1071- "removable": true if the device is removable, false otherwise (json-bool)
1072- "locked": true if the device is locked, false otherwise (json-bool)
1073- "inserted": only present if the device is inserted, it is a json-object
1074 containing the following:
1075 - "file": device file name (json-string)
1076 - "ro": true if read-only, false otherwise (json-bool)
1077 - "drv": driver format name (json-string)
1078 - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1079 "file", "file", "ftp", "ftps", "host_cdrom",
1080 "host_device", "host_floppy", "http", "https",
1081 "nbd", "parallels", "qcow", "qcow2", "raw",
1082 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1083 - "backing_file": backing file name (json-string, optional)
1084 - "encrypted": true if encrypted, false otherwise (json-bool)
1085
1086Example:
1087
1088-> { "execute": "query-block" }
1089<- {
1090 "return":[
1091 {
1092 "device":"ide0-hd0",
1093 "locked":false,
1094 "removable":false,
1095 "inserted":{
1096 "ro":false,
1097 "drv":"qcow2",
1098 "encrypted":false,
1099 "file":"disks/test.img"
1100 },
d8aeeb31 1101 "type":"unknown"
82a56f0d
LC		 1102 },
1103 {
1104 "device":"ide1-cd0",
1105 "locked":false,
1106 "removable":true,
d8aeeb31 1107 "type":"unknown"
82a56f0d
LC		 1108 },
1109 {
1110 "device":"floppy0",
1111 "locked":false,
1112 "removable":true,
d8aeeb31 1113 "type":"unknown"
82a56f0d
LC		 1114 },
1115 {
1116 "device":"sd0",
1117 "locked":false,
1118 "removable":true,
d8aeeb31 1119 "type":"unknown"
82a56f0d
LC		 1120 }
1121 ]
1122 }
1123
1124EQMP
1125
1126SQMP
1127query-blockstats
1128----------------
1129
1130Show block device statistics.
1131
1132Each device statistic information is stored in a json-object and the returned
1133value is a json-array of all devices.
1134
1135Each json-object contain the following:
1136
1137- "device": device name (json-string)
1138- "stats": A json-object with the statistics information, it contains:
1139 - "rd_bytes": bytes read (json-int)
1140 - "wr_bytes": bytes written (json-int)
1141 - "rd_operations": read operations (json-int)
1142 - "wr_operations": write operations (json-int)
1143 - "wr_highest_offset": Highest offset of a sector written since the
1144 BlockDriverState has been opened (json-int)
1145- "parent": Contains recursively the statistics of the underlying
1146 protocol (e.g. the host file for a qcow2 image). If there is
1147 no underlying protocol, this field is omitted
1148 (json-object, optional)
1149
1150Example:
1151
1152-> { "execute": "query-blockstats" }
1153<- {
1154 "return":[
1155 {
1156 "device":"ide0-hd0",
1157 "parent":{
1158 "stats":{
1159 "wr_highest_offset":3686448128,
1160 "wr_bytes":9786368,
1161 "wr_operations":751,
1162 "rd_bytes":122567168,
1163 "rd_operations":36772
1164 }
1165 },
1166 "stats":{
1167 "wr_highest_offset":2821110784,
1168 "wr_bytes":9786368,
1169 "wr_operations":692,
1170 "rd_bytes":122739200,
1171 "rd_operations":36604
1172 }
1173 },
1174 {
1175 "device":"ide1-cd0",
1176 "stats":{
1177 "wr_highest_offset":0,
1178 "wr_bytes":0,
1179 "wr_operations":0,
1180 "rd_bytes":0,
1181 "rd_operations":0
1182 }
1183 },
1184 {
1185 "device":"floppy0",
1186 "stats":{
1187 "wr_highest_offset":0,
1188 "wr_bytes":0,
1189 "wr_operations":0,
1190 "rd_bytes":0,
1191 "rd_operations":0
1192 }
1193 },
1194 {
1195 "device":"sd0",
1196 "stats":{
1197 "wr_highest_offset":0,
1198 "wr_bytes":0,
1199 "wr_operations":0,
1200 "rd_bytes":0,
1201 "rd_operations":0
1202 }
1203 }
1204 ]
1205 }
1206
1207EQMP
1208
1209SQMP
1210query-cpus
1211----------
1212
1213Show CPU information.
1214
1215Return a json-array. Each CPU is represented by a json-object, which contains:
1216
1217- "CPU": CPU index (json-int)
1218- "current": true if this is the current CPU, false otherwise (json-bool)
1219- "halted": true if the cpu is halted, false otherwise (json-bool)
1220- Current program counter. The key's name depends on the architecture:
1221 "pc": i386/x86_64 (json-int)
1222 "nip": PPC (json-int)
1223 "pc" and "npc": sparc (json-int)
1224 "PC": mips (json-int)
dc7a09cf 1225- "thread_id": ID of the underlying host thread (json-int)
82a56f0d
LC		 1226
1227Example:
1228
1229-> { "execute": "query-cpus" }
1230<- {
1231 "return":[
1232 {
1233 "CPU":0,
1234 "current":true,
1235 "halted":false,
1236 "pc":3227107138
dc7a09cf 1237 "thread_id":3134
82a56f0d
LC		 1238 },
1239 {
1240 "CPU":1,
1241 "current":false,
1242 "halted":true,
1243 "pc":7108165
dc7a09cf 1244 "thread_id":3135
82a56f0d
LC		 1245 }
1246 ]
1247 }
1248
1249EQMP
1250
1251SQMP
1252query-pci
1253---------
1254
1255PCI buses and devices information.
1256
1257The returned value is a json-array of all buses. Each bus is represented by
1258a json-object, which has a key with a json-array of all PCI devices attached
1259to it. Each device is represented by a json-object.
1260
1261The bus json-object contains the following:
1262
1263- "bus": bus number (json-int)
1264- "devices": a json-array of json-objects, each json-object represents a
1265 PCI device
1266
1267The PCI device json-object contains the following:
1268
1269- "bus": identical to the parent's bus number (json-int)
1270- "slot": slot number (json-int)
1271- "function": function number (json-int)
1272- "class_info": a json-object containing:
1273 - "desc": device class description (json-string, optional)
1274 - "class": device class number (json-int)
1275- "id": a json-object containing:
1276 - "device": device ID (json-int)
1277 - "vendor": vendor ID (json-int)
1278- "irq": device's IRQ if assigned (json-int, optional)
1279- "qdev_id": qdev id string (json-string)
1280- "pci_bridge": It's a json-object, only present if this device is a
1281 PCI bridge, contains:
1282 - "bus": bus number (json-int)
1283 - "secondary": secondary bus number (json-int)
1284 - "subordinate": subordinate bus number (json-int)
1285 - "io_range": I/O memory range information, a json-object with the
1286 following members:
1287 - "base": base address, in bytes (json-int)
1288 - "limit": limit address, in bytes (json-int)
1289 - "memory_range": memory range information, a json-object with the
1290 following members:
1291 - "base": base address, in bytes (json-int)
1292 - "limit": limit address, in bytes (json-int)
1293 - "prefetchable_range": Prefetchable memory range information, a
1294 json-object with the following members:
1295 - "base": base address, in bytes (json-int)
1296 - "limit": limit address, in bytes (json-int)
1297 - "devices": a json-array of PCI devices if there's any attached, each
1298 each element is represented by a json-object, which contains
1299 the same members of the 'PCI device json-object' described
1300 above (optional)
1301- "regions": a json-array of json-objects, each json-object represents a
1302 memory region of this device
1303
1304The memory range json-object contains the following:
1305
1306- "base": base memory address (json-int)
1307- "limit": limit value (json-int)
1308
1309The region json-object can be an I/O region or a memory region, an I/O region
1310json-object contains the following:
1311
1312- "type": "io" (json-string, fixed)
1313- "bar": BAR number (json-int)
1314- "address": memory address (json-int)
1315- "size": memory size (json-int)
1316
1317A memory region json-object contains the following:
1318
1319- "type": "memory" (json-string, fixed)
1320- "bar": BAR number (json-int)
1321- "address": memory address (json-int)
1322- "size": memory size (json-int)
1323- "mem_type_64": true or false (json-bool)
1324- "prefetch": true or false (json-bool)
1325
1326Example:
1327
1328-> { "execute": "query-pci" }
1329<- {
1330 "return":[
1331 {
1332 "bus":0,
1333 "devices":[
1334 {
1335 "bus":0,
1336 "qdev_id":"",
1337 "slot":0,
1338 "class_info":{
1339 "class":1536,
1340 "desc":"Host bridge"
1341 },
1342 "id":{
1343 "device":32902,
1344 "vendor":4663
1345 },
1346 "function":0,
1347 "regions":[
1348
1349 ]
1350 },
1351 {
1352 "bus":0,
1353 "qdev_id":"",
1354 "slot":1,
1355 "class_info":{
1356 "class":1537,
1357 "desc":"ISA bridge"
1358 },
1359 "id":{
1360 "device":32902,
1361 "vendor":28672
1362 },
1363 "function":0,
1364 "regions":[
1365
1366 ]
1367 },
1368 {
1369 "bus":0,
1370 "qdev_id":"",
1371 "slot":1,
1372 "class_info":{
1373 "class":257,
1374 "desc":"IDE controller"
1375 },
1376 "id":{
1377 "device":32902,
1378 "vendor":28688
1379 },
1380 "function":1,
1381 "regions":[
1382 {
1383 "bar":4,
1384 "size":16,
1385 "address":49152,
1386 "type":"io"
1387 }
1388 ]
1389 },
1390 {
1391 "bus":0,
1392 "qdev_id":"",
1393 "slot":2,
1394 "class_info":{
1395 "class":768,
1396 "desc":"VGA controller"
1397 },
1398 "id":{
1399 "device":4115,
1400 "vendor":184
1401 },
1402 "function":0,
1403 "regions":[
1404 {
1405 "prefetch":true,
1406 "mem_type_64":false,
1407 "bar":0,
1408 "size":33554432,
1409 "address":4026531840,
1410 "type":"memory"
1411 },
1412 {
1413 "prefetch":false,
1414 "mem_type_64":false,
1415 "bar":1,
1416 "size":4096,
1417 "address":4060086272,
1418 "type":"memory"
1419 },
1420 {
1421 "prefetch":false,
1422 "mem_type_64":false,
1423 "bar":6,
1424 "size":65536,
1425 "address":-1,
1426 "type":"memory"
1427 }
1428 ]
1429 },
1430 {
1431 "bus":0,
1432 "qdev_id":"",
1433 "irq":11,
1434 "slot":4,
1435 "class_info":{
1436 "class":1280,
1437 "desc":"RAM controller"
1438 },
1439 "id":{
1440 "device":6900,
1441 "vendor":4098
1442 },
1443 "function":0,
1444 "regions":[
1445 {
1446 "bar":0,
1447 "size":32,
1448 "address":49280,
1449 "type":"io"
1450 }
1451 ]
1452 }
1453 ]
1454 }
1455 ]
1456 }
1457
1458Note: This example has been shortened as the real response is too long.
1459
1460EQMP
1461
1462SQMP
1463query-kvm
1464---------
1465
1466Show KVM information.
1467
1468Return a json-object with the following information:
1469
1470- "enabled": true if KVM support is enabled, false otherwise (json-bool)
1471- "present": true if QEMU has KVM support, false otherwise (json-bool)
1472
1473Example:
1474
1475-> { "execute": "query-kvm" }
1476<- { "return": { "enabled": true, "present": true } }
1477
1478EQMP
1479
1480SQMP
1481query-status
1482------------
1483
1484Return a json-object with the following information:
1485
1486- "running": true if the VM is running, or false if it is paused (json-bool)
1487- "singlestep": true if the VM is in single step mode,
1488 false otherwise (json-bool)
1489
1490Example:
1491
1492-> { "execute": "query-status" }
1493<- { "return": { "running": true, "singlestep": false } }
1494
1495EQMP
1496
1497SQMP
1498query-mice
1499----------
1500
1501Show VM mice information.
1502
1503Each mouse is represented by a json-object, the returned value is a json-array
1504of all mice.
1505
1506The mouse json-object contains the following:
1507
1508- "name": mouse's name (json-string)
1509- "index": mouse's index (json-int)
1510- "current": true if this mouse is receiving events, false otherwise (json-bool)
1511- "absolute": true if the mouse generates absolute input events (json-bool)
1512
1513Example:
1514
1515-> { "execute": "query-mice" }
1516<- {
1517 "return":[
1518 {
1519 "name":"QEMU Microsoft Mouse",
1520 "index":0,
1521 "current":false,
1522 "absolute":false
1523 },
1524 {
1525 "name":"QEMU PS/2 Mouse",
1526 "index":1,
1527 "current":true,
1528 "absolute":true
1529 }
1530 ]
1531 }
1532
1533EQMP
1534
1535SQMP
1536query-vnc
1537---------
1538
1539Show VNC server information.
1540
1541Return a json-object with server information. Connected clients are returned
1542as a json-array of json-objects.
1543
1544The main json-object contains the following:
1545
1546- "enabled": true or false (json-bool)
1547- "host": server's IP address (json-string)
1548- "family": address family (json-string)
1549 - Possible values: "ipv4", "ipv6", "unix", "unknown"
1550- "service": server's port number (json-string)
1551- "auth": authentication method (json-string)
1552 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
1553 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
1554 "vencrypt+plain", "vencrypt+tls+none",
1555 "vencrypt+tls+plain", "vencrypt+tls+sasl",
1556 "vencrypt+tls+vnc", "vencrypt+x509+none",
1557 "vencrypt+x509+plain", "vencrypt+x509+sasl",
1558 "vencrypt+x509+vnc", "vnc"
1559- "clients": a json-array of all connected clients
1560
1561Clients are described by a json-object, each one contain the following:
1562
1563- "host": client's IP address (json-string)
1564- "family": address family (json-string)
1565 - Possible values: "ipv4", "ipv6", "unix", "unknown"
1566- "service": client's port number (json-string)
1567- "x509_dname": TLS dname (json-string, optional)
1568- "sasl_username": SASL username (json-string, optional)
1569
1570Example:
1571
1572-> { "execute": "query-vnc" }
1573<- {
1574 "return":{
1575 "enabled":true,
1576 "host":"0.0.0.0",
1577 "service":"50402",
1578 "auth":"vnc",
1579 "family":"ipv4",
1580 "clients":[
1581 {
1582 "host":"127.0.0.1",
1583 "service":"50401",
1584 "family":"ipv4"
1585 }
1586 ]
1587 }
1588 }
1589
1590EQMP
1591
cb42a870
GH		 1592SQMP
1593query-spice
1594-----------
1595
1596Show SPICE server information.
1597
1598Return a json-object with server information. Connected clients are returned
1599as a json-array of json-objects.
1600
1601The main json-object contains the following:
1602
1603- "enabled": true or false (json-bool)
1604- "host": server's IP address (json-string)
1605- "port": server's port number (json-int, optional)
1606- "tls-port": server's port number (json-int, optional)
1607- "auth": authentication method (json-string)
1608 - Possible values: "none", "spice"
1609- "channels": a json-array of all active channels clients
1610
1611Channels are described by a json-object, each one contain the following:
1612
1613- "host": client's IP address (json-string)
1614- "family": address family (json-string)
1615 - Possible values: "ipv4", "ipv6", "unix", "unknown"
1616- "port": client's port number (json-string)
1617- "connection-id": spice connection id. All channels with the same id
1618 belong to the same spice session (json-int)
1619- "channel-type": channel type. "1" is the main control channel, filter for
1620 this one if you want track spice sessions only (json-int)
1621- "channel-id": channel id. Usually "0", might be different needed when
1622 multiple channels of the same type exist, such as multiple
1623 display channels in a multihead setup (json-int)
1624- "tls": whevener the channel is encrypted (json-bool)
1625
1626Example:
1627
1628-> { "execute": "query-spice" }
1629<- {
1630 "return": {
1631 "enabled": true,
1632 "auth": "spice",
1633 "port": 5920,
1634 "tls-port": 5921,
1635 "host": "0.0.0.0",
1636 "channels": [
1637 {
1638 "port": "54924",
1639 "family": "ipv4",
1640 "channel-type": 1,
1641 "connection-id": 1804289383,
1642 "host": "127.0.0.1",
1643 "channel-id": 0,
1644 "tls": true
1645 },
1646 {
1647 "port": "36710",
1648 "family": "ipv4",
1649 "channel-type": 4,
1650 "connection-id": 1804289383,
1651 "host": "127.0.0.1",
1652 "channel-id": 0,
1653 "tls": false
1654 },
1655 [ ... more channels follow ... ]
1656 ]
1657 }
1658 }
1659
1660EQMP
1661
82a56f0d
LC		 1662SQMP
1663query-name
1664----------
1665
1666Show VM name.
1667
1668Return a json-object with the following information:
1669
1670- "name": VM's name (json-string, optional)
1671
1672Example:
1673
1674-> { "execute": "query-name" }
1675<- { "return": { "name": "qemu-name" } }
1676
1677EQMP
1678
1679SQMP
1680query-uuid
1681----------
1682
1683Show VM UUID.
1684
1685Return a json-object with the following information:
1686
1687- "UUID": Universally Unique Identifier (json-string)
1688
1689Example:
1690
1691-> { "execute": "query-uuid" }
1692<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
1693
1694EQMP
1695
1696SQMP
1697query-migrate
1698-------------
1699
1700Migration status.
1701
1702Return a json-object. If migration is active there will be another json-object
1703with RAM migration status and if block migration is active another one with
1704block migration status.
1705
1706The main json-object contains the following:
1707
1708- "status": migration status (json-string)
1709 - Possible values: "active", "completed", "failed", "cancelled"
1710- "ram": only present if "status" is "active", it is a json-object with the
1711 following RAM information (in bytes):
1712 - "transferred": amount transferred (json-int)
1713 - "remaining": amount remaining (json-int)
1714 - "total": total (json-int)
1715- "disk": only present if "status" is "active" and it is a block migration,
1716 it is a json-object with the following disk information (in bytes):
1717 - "transferred": amount transferred (json-int)
1718 - "remaining": amount remaining (json-int)
1719 - "total": total (json-int)
1720
1721Examples:
1722
17231. Before the first migration
1724
1725-> { "execute": "query-migrate" }
1726<- { "return": {} }
1727
17282. Migration is done and has succeeded
1729
1730-> { "execute": "query-migrate" }
1731<- { "return": { "status": "completed" } }
1732
17333. Migration is done and has failed
1734
1735-> { "execute": "query-migrate" }
1736<- { "return": { "status": "failed" } }
1737
17384. Migration is being performed and is not a block migration:
1739
1740-> { "execute": "query-migrate" }
1741<- {
1742 "return":{
1743 "status":"active",
1744 "ram":{
1745 "transferred":123,
1746 "remaining":123,
1747 "total":246
1748 }
1749 }
1750 }
1751
17525. Migration is being performed and is a block migration:
1753
1754-> { "execute": "query-migrate" }
1755<- {
1756 "return":{
1757 "status":"active",
1758 "ram":{
1759 "total":1057024,
1760 "remaining":1053304,
1761 "transferred":3720
1762 },
1763 "disk":{
1764 "total":20971520,
1765 "remaining":20880384,
1766 "transferred":91136
1767 }
1768 }
1769 }
1770
1771EQMP
1772
1773SQMP
1774query-balloon
1775-------------
1776
1777Show balloon information.
1778
1779Make an asynchronous request for balloon info. When the request completes a
1780json-object will be returned containing the following data:
1781
1782- "actual": current balloon value in bytes (json-int)
1783- "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
1784- "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
1785- "major_page_faults": Number of major faults (json-int, optional)
1786- "minor_page_faults": Number of minor faults (json-int, optional)
1787- "free_mem": Total amount of free and unused memory in
1788 bytes (json-int, optional)
1789- "total_mem": Total amount of available memory in bytes (json-int, optional)
1790
1791Example:
1792
1793-> { "execute": "query-balloon" }
1794<- {
1795 "return":{
1796 "actual":1073741824,
1797 "mem_swapped_in":0,
1798 "mem_swapped_out":0,
1799 "major_page_faults":142,
1800 "minor_page_faults":239245,
1801 "free_mem":1014185984,
1802 "total_mem":1044668416
1803 }
1804 }
1805
1806EQMP
1807
Qemu copy for testing