MonitorProtocol: Difference between revisions

From KVM
(Update libvirt's use of commands)
No edit summary
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= QEMU Monitor Protocol =
= PAGE MOVED!! =


The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.
This page has moved to: http://wiki.qemu.org/QMP
 
QMP's main features are:
 
* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stable API (starting with QEMU version 0.13)
 
The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the  [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.
 
== General Status ==
 
A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.
 
For more information about converted handlers, please check [[#Conversion Status]].
 
== Examples ==
 
In the following examples, 'C' stands for 'Client' and 'S' stands for 'Server'.
 
=== Server Greeting ===
 
S: { "QMP": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }
 
=== Query version ===
 
C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }
 
=== Eject a device ===
 
C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}
 
== Development ==
 
Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], but all QMP-related discussions happen on the [http://lists.nongnu.org/mailman/listinfo/qemu-devel qemu-devel] mailing list.
 
Next features, hot fixes and other patches are stored in the QMP unstable repository:
 
http://repo.or.cz/w/qemu/qmp-unstable.git
 
'''NOTE''': all branches in this repository are constantly ''rebased'' (master inclusive).
 
== TODO ==
 
=== High Priority ===
 
* do_device_add()/do_device_del() conversions (markus)
* do_netdev_add()/do_netdev_del() conversions (markus)
* do_blockdev_add()/do_blockdev_del() conversions (markus)
* Events Grouping (luiz)
* Make qmp-shell work again (luiz)
 
* Self-description & High-level protocol documentation
* High-level internal documentation
* Better QObjects and QMP debug support
 
=== Normal Priority ===
 
* Convert all remaining commands to the QObject API
* Improve internal API, currently it's too [http://lists.gnu.org/archive/html/qemu-devel/2009-12/msg02537.html low-level]
* Array-based Monitor's command table
* Libqmp
 
== Testing ==
 
Unfortunately, there is no automated tool to test QMP correctness yet. Probably, the right thing to do is to integrate with [http://www.linux-kvm.org/page/KVM-Autotest kvm-autotest] but we still have to think how this should be done.
 
Meanwhile, QMP testing is a low-level procedure which requires knowledge about the protocol and its implementation, so the first thing to do is to read the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] and [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt spec] files.
 
This section describes three ways of testing QMP:
 
* By hand (difficult, only worth it if you're chasing a specific bug)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)
 
=== By hand ===
 
1. Start QMP on a TCP socket, so that telnet can be used
 
# qemu [...] -qmp tcp:localhost:4444,server
 
2. Now, run telnet
 
$ telnet localhost 4444
 
3. You should see the following prompt
 
{"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
 
4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''
 
{ "execute": "query-commands" }
 
'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".
 
'''NOTE (2):''' QMP doesn't have user documentation yet, this means that, to find out which arguments a command accepts or what's its output, you will have to either check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/qemu-monitor.hx qemu-monitor.hx] file and/or the function which implements the command.
 
=== qmp-shell script ===
 
This script is available under the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP QMP] directory in QEMU's source-tree. It automates a bit the testing work, as it can construct commands.
 
1. Start QMP on a unix socket, like:
 
# qemu [...] -qmp unix:./qmp-sock,server
 
2. Run the script
 
# qmp-shell ./qmp-sock
 
3. You should get the following prompt
 
(QEMU)
 
4. Now you can run commands. For example, let's change the VNC password:
 
(QEMU) change device=vnc target=password arg='1234'
 
'''NOTE''': To find out what arguments a command accepts, you have to either check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/qemu-monitor.hx qemu-monitor.hx] file and/or the function which implements the command.
 
=== Libvirt ===
 
Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.
 
1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')
 
2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary libvirt master branch] run the following:
 
./autogen.sh --system --enable-compile-warnings=error
 
'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.
 
'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library
 
3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:
 
#if 0
    if (version >= 13000)
        flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif
 
Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU
 
4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install
 
5. As root simply stop the current daemon & start the one you built
 
/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd
 
6. As root you can use the newly built virsh too
 
cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>
 
== Conversion Status ==
 
'''UPDATED''': 2009-12-16
 
{| border="1"
|
|Command
|Info
|-
|Handlers
|62
|36
|-
|Converted
|19
|15
|-
|Percentage
|30%
|41%
|-
|}
 
The following tables have a per-function status. There is one table for ''command'' handlers and another one for ''info'' handlers.
 
Status can be:
 
* merged: already merged upstream
* partial: merged, but error handling is incomplete
 
'''NOTE:''' Handlers used by [http://libvirt.org Libvirt] are marked with <span style="background-color:yellow">yellow</span>.  Handlers it is expected to use are marked <span style="background-color:khaki">khaki</span>
 
==== Command handlers ====
 
{| border="1"
|'''Handler name'''
|'''Status'''
|'''Version'''
|'''Comments'''
|-
|do_acl_add()
|
|
|
|-
|do_acl_policy()
|
|
|
|-
|do_acl_remove()
|
|
|
|-
|do_acl_reset()
|
|
|
|-
|do_acl_show()
|
|
|
|- style="background-color:yellow;"
|do_balloon()
|merged
|0.12
|
|-
|do_block_set_passwd()
|merged
|0.12
|
|-
|do_boot_set()
|
|
|
|- style="background-color:yellow;"
|do_change()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_closefd()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_commit()
|
|
|
|- style="background-color:yellow;"
|do_cont()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_cpu_set()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_device_del()
|
|
|
|- style="background-color:yellow;"
|do_eject()
|merged
|0.12
|
|-
|do_gdbserver()
|
|
|
|- style="background-color:yellow;"
|do_getfd()
|merged
|0.12
|
|-
|do_help_cmd()
|
|
|
|-
|do_info()
|merged
|0.12
|as 'query-' commands
|-
|do_inject_mce()
|
|
|
|-
|do_inject_nmi()
|
|
|
|-
|do_ioport_read()
|
|
|
|-
|do_ioport_write()
|
|
|
|- style="background-color:yellow;"
|do_loadvm()
|
|
|
|-
|do_log()
|
|
|
|-
|do_logfile()
|
|
|
|-
|do_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_memory_save()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate()
|partial
|0.12
|
|- style="background-color:yellow;"
|do_migrate_cancel()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_migrate_set_downtime()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|- style="background-color:khaki;"
|do_mouse_button()
|
|
|
|- style="background-color:khaki;"
|do_mouse_move()
|
|
|
|- style="background-color:khaki;"
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|do_print()
|
|
|
|-
|do_quit()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_savevm()
|
|
|
|- style="background-color:khaki;"
|do_screen_dump()
|
|
|
|- style="background-color:khaki;"
|do_sendkey()
|
|
|
|- style="background-color:khaki;"
|do_set_link()
|
|
|
|-
|do_singlestep()
|
|
|
|- style="background-color:yellow;"
|do_stop()
|merged
|0.12
|
|-
|do_stop_capture()
|
|
|
|-
|do_sum()
|
|
|
|- style="background-color:yellow;"
|do_system_powerdown()
|merged
|0.12
|
|-
|do_system_reset()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_usb_add()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}
 
==== Info handlers ====
 
{| border="1"
|'''Handler name'''
|'''Status'''
|'''Version'''
|'''Comments'''
|- style="background-color:yellow;"
|bdrv_info()
|merged
|0.12
|
|- style="background-color:yellow;"
|bdrv_info_stats()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_info_balloon()
|merged
|0.12
|
|-
|do_info_capture()
|
|
|
|- style="background-color:yellow;"
|do_info_cpus()
|merged
|0.12
|
|-
|do_info_cpu_stats()
|
|
|
|-
|do_info_history()
|
|
|
|-
|do_info_hpet()
|merged
|0.12
|
|-
|do_info_jit()
|
|
|
|-
|do_info_kvm()
|merged
|0.12
|
|-
|do_info_mice()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_info_migrate()
|merged
|0.12
|
|-
|do_info_name()
|merged
|0.12
|
|-
|do_info_network()
| [http://wiki.qemu.org/Google_Summer_of_Code_2010/QMP Being worked on in SoC]
|
|
|-
|do_info_numa()
|
|
|
|-
|do_info_profile()
|
|
|
|-
|do_info_qdm()
|
|
|
|-
|do_info_qtree()
|
|
|
|-
|do_info_registers()
|
|
|
|-
|do_info_roms()
|
|
|
|-
|do_info_snapshots()
|
|
|
|-
|do_info_status()
|merged
|0.12
|
|-
|do_info_usernet()
|
|
|
|-
|do_info_uuid()
|merged
|0.12
|
|-
|do_info_version()
|merged
|0.12
|
|-
|do_info_vnc()
|merged
|0.12
|
|-
|irq_info()
|
|
|
|-
|mem_info()
|
|
|
|- style="background-color:yellow;"
|pci_info()
|
|
|
|-
|pcmcia_info()
|
|
|
|-
|pic_info()
|
|
|
|-
|qemu_chr_info()
|merged
|0.12
|
|-
|tlb_info()
|
|
|
|-
|usb_host_info()
|
|
|
|- style="background-color:yellow;"
|usb_info()
|
|
|
|-
|}
 
== History ==
 
This was the fourth proposal for a Monitor protocol, past discussions can be found in the following links:
 
* http://www.mail-archive.com/qemu-devel@nongnu.org/msg14593.html
* http://lists.gnu.org/archive/html/qemu-devel/2009-01/msg00655.html
* http://lists.gnu.org/archive/html/qemu-devel/2009-06/msg01584.html

Latest revision as of 08:51, 9 September 2010

PAGE MOVED!!

This page has moved to: http://wiki.qemu.org/QMP

Retrieved from "https://linux-kvm.org/index.php?title=MonitorProtocol&oldid=3232"