docs/qmp/README

   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 qmp-commands.txt  QMP supported commands (auto-generated at build-time)
  20 o qmp-events.txt    List of available asynchronous events
  21
  22 [1] http://www.json.org
  23
  24 Usage
  25 -----
  26
  27 You can use the -qmp option to enable QMP. For example, the following
  28 makes QMP available on localhost port 4444:
  29
  30 $ qemu [...] -qmp tcp:localhost:4444,server,nowait
  31
  32 However, for more flexibility and to make use of more options, the -mon
  33 command-line option should be used. For instance, the following example
  34 creates one HMP instance (human monitor) on stdio and one QMP instance
  35 on localhost port 4444:
  36
  37 $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
  38              -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
  39              -mon chardev=mon1,mode=control,pretty=on
  40
  41 Please, refer to QEMU's manpage for more information.
  42
  43 Simple Testing
  44 --------------
  45
  46 To manually test QMP one can connect with telnet and issue commands by hand:
  47
  48 $ telnet localhost 4444
  49 Trying 127.0.0.1...
  50 Connected to localhost.
  51 Escape character is '^]'.
  52 {
  53     "QMP": {
  54         "version": {
  55             "qemu": {
  56                 "micro": 50,
  57                 "minor": 6,
  58                 "major": 1
  59             },
  60             "package": ""
  61         },
  62         "capabilities": [
  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 the qapi-schema.json file for a complete command reference.
  83
  84 QMP wiki page
  85 -------------
  86
  87 http://wiki.qemu-project.org/QMP