docs/interop/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] https://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=on,wait=off
  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=on,wait=off \
  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": 0,
  56                 "minor": 0,
  57                 "major": 3
  58             },
  59             "package": "v3.0.0"
  60         },
  61         "capabilities": [
  62             "oob"
  63         ]
  64     }
  65 }
  66
  67 { "execute": "qmp_capabilities" }
  68 {
  69     "return": {
  70     }
  71 }
  72
  73 { "execute": "query-status" }
  74 {
  75     "return": {
  76         "status": "prelaunch",
  77         "singlestep": false,
  78         "running": false
  79     }
  80 }
  81
  82 Please refer to docs/interop/qemu-qmp-ref.* for a complete command
  83 reference, generated from qapi/qapi-schema.json.
  84
  85 QMP wiki page
  86 -------------
  87
  88 https://wiki.qemu.org/QMP