MonitorProtocol

QEMU Monitor Protocol

The QEMU Monitor Protocol (QMP) is a JSON-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

• Lightweight, text-based, easy to parse data format
• Asynchronous messages support (ie. events)
• Capabilities Negotiation

However, QMP is still under heavy development and is considered an unstable protocol. Please, check the README file for more information.

General Status

A preview version of QMP is available in QEMU since version 0.12. It's already functional and contains a number of commands available, however early adopters will have to cope with protocol changes between QEMU releases.

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 Luiz Capitulino and Markus Armbruster, but all QMP-related discussions happen on the 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 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 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 README and 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 qemu-monitor.hx file and/or the function which implements the command.

qmp-shell script

This script is available under the 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 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 yajl-devel (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of 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

	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 Libvirt are marked with yellow. Handlers it is expected to use are marked khaki

Command handlers

Handler name	Status	Version	Comments
do_acl_add()
do_acl_policy()
do_acl_remove()
do_acl_reset()
do_acl_show()
do_balloon()	merged	0.12
do_block_set_passwd()	merged	0.12
do_boot_set()
do_change()	merged	0.12
do_closefd()	merged	0.12
do_commit()
do_cont()	merged	0.12
do_cpu_set()	merged	0.12.50
do_cpu_set_nr()			qemu-kvm only
do_delvm()
do_device_add()	merged	0.12.50
do_device_del()	merged	0.12.50
do_eject()	merged	0.12
do_gdbserver()
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()
do_loadvm()
do_log()
do_logfile()
do_memory_dump()
do_memory_save()	merged	0.12.50
do_migrate()	partial	0.12
do_migrate_cancel()	merged	0.12
do_migrate_set_downtime()	merged	0.12.50
do_migrate_set_speed()	merged	0.12.50
do_mouse_button()
do_mouse_move()
do_mouse_set()
do_netdev_add()	merged	0.12.50
do_netdev_del()	merged	0.12.50
do_pci_device_hot_remove()	partial	0.12	legacy, use device_del instead
do_physical_memory_dump()
do_physical_memory_save()	merged	0.12.50
do_print()
do_quit()	merged	0.12
do_savevm()
do_screen_dump()	merged	0.12.50
do_sendkey()
do_set_link()	merged	0.12.50
do_singlestep()
do_stop()	merged	0.12
do_stop_capture()
do_sum()
do_system_powerdown()	merged	0.12
do_system_reset()	merged	0.12
do_usb_add()			legacy, use device_add instead
do_usb_del()			legacy, use device_del instead
do_watchdog_action()
do_wav_capture()
drive_hot_add()			legacy, use blockdev_add, device_add instead
net_host_device_add()			consider do_netdev_add() instead
net_host_device_remove()			consider do_netdev_del() instead
net_slirp_hostfwd_add()
net_slirp_hostfwd_remove()
pci_device_hot_add()	partial	0.12	legacy, use device_add, blockdev_add instead
do_blockdev_add()			to be created
do_blockdev_del()			to be created
do_chardev_add()			to be created
do_chardev_del()			to be created

Info handlers

Handler name	Status	Version	Comments
bdrv_info()	merged	0.12
bdrv_info_stats()	merged	0.12
do_info_balloon()	merged	0.12
do_info_capture()
do_info_commands()	merged	0.12
do_info_cpu_stats()
do_info_cpus()	merged	0.12
do_info_history()
do_info_hpet()	merged	0.12
do_info_jit()
do_info_kvm()	merged	0.12
do_info_mice()	merged	0.12
do_info_migrate()	merged	0.12
do_info_name()	merged	0.12
do_info_network()			legacy, use do_info_netdev()
do_info_netdev()			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()			lacks parent info, libvirt wants it
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
do_pci_info()	merged	0.12.50	libvirt uses this, but only with pre-0.12.x QEMU
irq_info()
mem_info()
pcmcia_info()
pic_info()
qemu_chr_info()	merged	0.12
tlb_info()
usb_host_info()
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