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] 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