Statistics
| Branch: | Revision:

root / QMP / README @ d29f3196

History | View | Annotate | Download (2.9 kB)

1
                          QEMU Monitor Protocol
2
                          =====================
3

    
4
Introduction
5
-------------
6

    
7
The QEMU Monitor Protocol (QMP) allows applications to communicate with
8
QEMU's Monitor.
9

    
10
QMP is JSON[1] based and currently has the following features:
11

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

    
16
For detailed information on QMP's usage, please, refer to the following files:
17

    
18
o qmp-spec.txt      QEMU Monitor Protocol current specification
19
o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
20
o qmp-events.txt    List of available asynchronous events
21

    
22
There are also two simple Python scripts available:
23

    
24
o qmp-shell  A shell
25
o vm-info    Show some information about the Virtual Machine
26

    
27
IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
28
section in the qmp-commands.txt file before making any serious use of QMP.
29

    
30

    
31
[1] http://www.json.org
32

    
33
Usage
34
-----
35

    
36
To enable QMP, you need a QEMU monitor instance in "control mode". There are
37
two ways of doing this.
38

    
39
The simplest one is using the '-qmp' command-line option. The following
40
example makes QMP available on localhost port 4444:
41

    
42
  $ qemu [...] -qmp tcp:localhost:4444,server
43

    
44
However, in order to have more complex combinations, like multiple monitors,
45
the '-mon' command-line option should be used along with the '-chardev' one.
46
For instance, the following example creates one user monitor on stdio and one
47
QMP monitor on localhost port 4444.
48

    
49
   $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
50
                -chardev socket,id=mon1,host=localhost,port=4444,server \
51
                -mon chardev=mon1,mode=control
52

    
53
Please, refer to QEMU's manpage for more information.
54

    
55
Simple Testing
56
--------------
57

    
58
To manually test QMP one can connect with telnet and issue commands by hand:
59

    
60
$ telnet localhost 4444
61
Trying 127.0.0.1...
62
Connected to localhost.
63
Escape character is '^]'.
64
{"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
65
{ "execute": "qmp_capabilities" }
66
{"return": {}}
67
{ "execute": "query-version" }
68
{"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
69

    
70
Development Process
71
-------------------
72

    
73
When changing QMP's interface (by adding new commands, events or modifying
74
existing ones) it's mandatory to update the relevant documentation, which is
75
one (or more) of the files listed in the 'Introduction' section*.
76

    
77
Also, it's strongly recommended to send the documentation patch first, before
78
doing any code change. This is so because:
79

    
80
  1. Avoids the code dictating the interface
81

    
82
  2. Review can improve your interface.  Letting that happen before
83
     you implement it can save you work.
84

    
85
* The qmp-commands.txt file is generated from the qemu-monitor.hx one, which
86
  is the file that should be edited.
87

    
88
Homepage
89
--------
90

    
91
http://www.linux-kvm.org/page/MonitorProtocol