Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-03-16' into staging
[qemu.git] / docs / qmp-intro.txt
1                           QEMU Machine Protocol
2                           =====================
3
4 Introduction
5 ------------
6
7 The QEMU Machine Protocol (QMP) allows applications to operate a
8 QEMU instance.
9
10 QMP is JSON[1] based and features the following:
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 Machine Protocol current specification
19 o qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at build-time)
20
21 [1] http://www.json.org
22
23 Usage
24 -----
25
26 You can use the -qmp option to enable QMP. For example, the following
27 makes QMP available on localhost port 4444:
28
29 $ qemu [...] -qmp tcp:localhost:4444,server,nowait
30
31 However, for more flexibility and to make use of more options, the -mon
32 command-line option should be used. For instance, the following example
33 creates one HMP instance (human monitor) on stdio and one QMP instance
34 on localhost port 4444:
35
36 $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
37              -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
38              -mon chardev=mon1,mode=control,pretty=on
39
40 Please, refer to QEMU's manpage for more information.
41
42 Simple Testing
43 --------------
44
45 To manually test QMP one can connect with telnet and issue commands by hand:
46
47 $ telnet localhost 4444
48 Trying 127.0.0.1...
49 Connected to localhost.
50 Escape character is '^]'.
51 {
52     "QMP": {
53         "version": {
54             "qemu": {
55                 "micro": 50, 
56                 "minor": 6, 
57                 "major": 1
58             }, 
59             "package": ""
60         }, 
61         "capabilities": [
62         ]
63     }
64 }
65
66 { "execute": "qmp_capabilities" }
67 {
68     "return": {
69     }
70 }
71
72 { "execute": "query-status" }
73 {
74     "return": {
75         "status": "prelaunch", 
76         "singlestep": false, 
77         "running": false
78     }
79 }
80
81 Please, refer to the qapi-schema.json file for a complete command reference.
82
83 QMP wiki page
84 -------------
85
86 http://wiki.qemu-project.org/QMP