]>
Commit | Line | Data |
---|---|---|
26d5a1cd LC |
1 | QEMU Monitor Protocol |
2 | ===================== | |
3 | ||
4 | Introduction | |
5 | ------------- | |
6 | ||
052f1b9b LC |
7 | The QEMU Monitor Protocol (QMP) allows applications to communicate with |
8 | QEMU's Monitor. | |
26d5a1cd | 9 | |
d29f3196 | 10 | QMP is JSON[1] based and currently has the following features: |
052f1b9b LC |
11 | |
12 | - Lightweight, text-based, easy to parse data format | |
d29f3196 LC |
13 | - Asynchronous messages support (ie. events) |
14 | - Capabilities Negotiation | |
26d5a1cd | 15 | |
d29f3196 | 16 | For detailed information on QMP's usage, please, refer to the following files: |
26d5a1cd | 17 | |
b40292e7 | 18 | o qmp-spec.txt QEMU Monitor Protocol current specification |
d29f3196 | 19 | o qmp-commands.txt QMP supported commands (auto-generated at build-time) |
b40292e7 | 20 | o qmp-events.txt List of available asynchronous events |
26d5a1cd LC |
21 | |
22 | There are also two simple Python scripts available: | |
23 | ||
d29f3196 LC |
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 | ||
26d5a1cd LC |
30 | |
31 | [1] http://www.json.org | |
32 | ||
33 | Usage | |
34 | ----- | |
35 | ||
d29f3196 LC |
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: | |
26d5a1cd | 41 | |
d29f3196 | 42 | $ qemu [...] -qmp tcp:localhost:4444,server |
26d5a1cd | 43 | |
d29f3196 LC |
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. | |
26d5a1cd | 48 | |
d29f3196 LC |
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 | |
26d5a1cd | 52 | |
d29f3196 | 53 | Please, refer to QEMU's manpage for more information. |
052f1b9b LC |
54 | |
55 | Simple Testing | |
56 | -------------- | |
57 | ||
d29f3196 | 58 | To manually test QMP one can connect with telnet and issue commands by hand: |
26d5a1cd LC |
59 | |
60 | $ telnet localhost 4444 | |
052f1b9b | 61 | Trying 127.0.0.1... |
26d5a1cd LC |
62 | Connected to localhost. |
63 | Escape character is '^]'. | |
d29f3196 | 64 | {"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}} |
ca9567e2 LC |
65 | { "execute": "qmp_capabilities" } |
66 | {"return": {}} | |
26d5a1cd | 67 | { "execute": "query-version" } |
d29f3196 LC |
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 | ||
82a56f0d | 85 | * The qmp-commands.txt file is generated from the qmp-commands.hx one, which |
d29f3196 | 86 | is the file that should be edited. |
26d5a1cd | 87 | |
d29f3196 LC |
88 | Homepage |
89 | -------- | |
26d5a1cd LC |
90 | |
91 | http://www.linux-kvm.org/page/MonitorProtocol |