docs/qmp-events.txt

   1                    QEMU Machine Protocol Events
   2                    ============================
   3
   4 ACPI_DEVICE_OST
   5 ---------------
   6
   7 Emitted when guest executes ACPI _OST method.
   8
   9  - data: ACPIOSTInfo type as described in qapi-schema.json
  10
  11 { "event": "ACPI_DEVICE_OST",
  12      "data": { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0 } }
  13
  14 BALLOON_CHANGE
  15 --------------
  16
  17 Emitted when the guest changes the actual BALLOON level. This
  18 value is equivalent to the 'actual' field return by the
  19 'query-balloon' command
  20
  21 Data:
  22
  23 - "actual": actual level of the guest memory balloon in bytes (json-number)
  24
  25 Example:
  26
  27 { "event": "BALLOON_CHANGE",
  28     "data": { "actual": 944766976 },
  29     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
  30
  31 Note: this event is rate-limited.
  32
  33 DEVICE_DELETED
  34 --------------
  35
  36 Emitted whenever the device removal completion is acknowledged
  37 by the guest.
  38 At this point, it's safe to reuse the specified device ID.
  39 Device removal can be initiated by the guest or by HMP/QMP commands.
  40
  41 Data:
  42
  43 - "device": device name (json-string, optional)
  44 - "path": device path (json-string)
  45
  46 { "event": "DEVICE_DELETED",
  47   "data": { "device": "virtio-net-pci-0",
  48             "path": "/machine/peripheral/virtio-net-pci-0" },
  49   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
  50
  51 DEVICE_TRAY_MOVED
  52 -----------------
  53
  54 It's emitted whenever the tray of a removable device is moved by the guest
  55 or by HMP/QMP commands.
  56
  57 Data:
  58
  59 - "device": Block device name. This is always present for compatibility
  60             reasons, but it can be empty ("") if the image does not have a
  61             device name associated. (json-string)
  62 - "id": The name or QOM path of the guest device (json-string)
  63 - "tray-open": true if the tray has been opened or false if it has been closed
  64                (json-bool)
  65
  66 { "event": "DEVICE_TRAY_MOVED",
  67   "data": { "device": "ide1-cd0",
  68             "id": "/machine/unattached/device[22]",
  69             "tray-open": true
  70   },
  71   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
  72
  73 DUMP_COMPLETED
  74 --------------
  75
  76 Emitted when the guest has finished one memory dump.
  77
  78 Data:
  79
  80 - "result": DumpQueryResult type described in qapi-schema.json
  81 - "error": Error message when dump failed. This is only a
  82   human-readable string provided when dump failed. It should not be
  83   parsed in any way (json-string, optional)
  84
  85 Example:
  86
  87 { "event": "DUMP_COMPLETED",
  88   "data": {"result": {"total": 1090650112, "status": "completed",
  89                       "completed": 1090650112} } }
  90
  91 GUEST_PANICKED
  92 --------------
  93
  94 Emitted when guest OS panic is detected.
  95
  96 Data:
  97
  98 - "action": Action that has been taken (json-string, currently always "pause").
  99
 100 Example:
 101
 102 { "event": "GUEST_PANICKED",
 103      "data": { "action": "pause" } }
 104
 105 MEM_UNPLUG_ERROR
 106 --------------------
 107 Emitted when memory hot unplug error occurs.
 108
 109 Data:
 110
 111 - "device": device name (json-string)
 112 - "msg": Informative message (e.g., reason for the error) (json-string)
 113
 114 Example:
 115
 116 { "event": "MEM_UNPLUG_ERROR"
 117   "data": { "device": "dimm1",
 118             "msg": "acpi: device unplug for unsupported device"
 119   },
 120   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 121
 122 NIC_RX_FILTER_CHANGED
 123 ---------------------
 124
 125 The event is emitted once until the query command is executed,
 126 the first event will always be emitted.
 127
 128 Data:
 129
 130 - "name": net client name (json-string)
 131 - "path": device path (json-string)
 132
 133 { "event": "NIC_RX_FILTER_CHANGED",
 134   "data": { "name": "vnet0",
 135             "path": "/machine/peripheral/vnet0/virtio-backend" },
 136   "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
 137 }
 138
 139 POWERDOWN
 140 ---------
 141
 142 Emitted when the Virtual Machine is powered down through the power
 143 control system, such as via ACPI.
 144
 145 Data: None.
 146
 147 Example:
 148
 149 { "event": "POWERDOWN",
 150     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
 151
 152 QUORUM_FAILURE
 153 --------------
 154
 155 Emitted by the Quorum block driver if it fails to establish a quorum.
 156
 157 Data:
 158
 159 - "reference":     device name if defined else node name.
 160 - "sector-num":    Number of the first sector of the failed read operation.
 161 - "sectors-count": Failed read operation sector count.
 162
 163 Example:
 164
 165 { "event": "QUORUM_FAILURE",
 166      "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
 167      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
 168
 169 Note: this event is rate-limited.
 170
 171 QUORUM_REPORT_BAD
 172 -----------------
 173
 174 Emitted to report a corruption of a Quorum file.
 175
 176 Data:
 177
 178 - "type":          Quorum operation type
 179 - "error":         Error message (json-string, optional)
 180                    Only present on failure.  This field contains a human-readable
 181                    error message.  There are no semantics other than that the
 182                    block layer reported an error and clients should not try to
 183                    interpret the error string.
 184 - "node-name":     The graph node name of the block driver state.
 185 - "sector-num":    Number of the first sector of the failed read operation.
 186 - "sectors-count": Failed read operation sector count.
 187
 188 Example:
 189
 190 Read operation:
 191 { "event": "QUORUM_REPORT_BAD",
 192      "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
 193                "type": "read" },
 194      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
 195
 196 Flush operation:
 197 { "event": "QUORUM_REPORT_BAD",
 198      "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
 199                "type": "flush", "error": "Broken pipe" },
 200      "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
 201
 202 Note: this event is rate-limited.
 203
 204 RESET
 205 -----
 206
 207 Emitted when the Virtual Machine is reset.
 208
 209 Data: None.
 210
 211 Example:
 212
 213 { "event": "RESET",
 214     "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
 215
 216 RESUME
 217 ------
 218
 219 Emitted when the Virtual Machine resumes execution.
 220
 221 Data: None.
 222
 223 Example:
 224
 225 { "event": "RESUME",
 226     "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
 227
 228 RTC_CHANGE
 229 ----------
 230
 231 Emitted when the guest changes the RTC time.
 232
 233 Data:
 234
 235 - "offset": Offset between base RTC clock (as specified by -rtc base), and
 236 new RTC clock value (json-number)
 237
 238 Example:
 239
 240 { "event": "RTC_CHANGE",
 241     "data": { "offset": 78 },
 242     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
 243
 244 Note: this event is rate-limited.
 245
 246 SHUTDOWN
 247 --------
 248
 249 Emitted when the Virtual Machine has shut down, indicating that qemu
 250 is about to exit.
 251
 252 Data: None.
 253
 254 Example:
 255
 256 { "event": "SHUTDOWN",
 257     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
 258
 259 Note: If the command-line option "-no-shutdown" has been specified, a STOP
 260 event will eventually follow the SHUTDOWN event.
 261
 262 SPICE_CONNECTED
 263 ---------------
 264
 265 Emitted when a SPICE client connects.
 266
 267 Data:
 268
 269 - "server": Server information (json-object)
 270   - "host": IP address (json-string)
 271   - "port": port number (json-string)
 272   - "family": address family (json-string, "ipv4" or "ipv6")
 273 - "client": Client information (json-object)
 274   - "host": IP address (json-string)
 275   - "port": port number (json-string)
 276   - "family": address family (json-string, "ipv4" or "ipv6")
 277
 278 Example:
 279
 280 { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
 281   "event": "SPICE_CONNECTED",
 282   "data": {
 283     "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
 284     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
 285 }}
 286
 287 SPICE_DISCONNECTED
 288 ------------------
 289
 290 Emitted when a SPICE client disconnects.
 291
 292 Data:
 293
 294 - "server": Server information (json-object)
 295   - "host": IP address (json-string)
 296   - "port": port number (json-string)
 297   - "family": address family (json-string, "ipv4" or "ipv6")
 298 - "client": Client information (json-object)
 299   - "host": IP address (json-string)
 300   - "port": port number (json-string)
 301   - "family": address family (json-string, "ipv4" or "ipv6")
 302
 303 Example:
 304
 305 { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
 306   "event": "SPICE_DISCONNECTED",
 307   "data": {
 308     "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
 309     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
 310 }}
 311
 312 SPICE_INITIALIZED
 313 -----------------
 314
 315 Emitted after initial handshake and authentication takes place (if any)
 316 and the SPICE channel is up and running
 317
 318 Data:
 319
 320 - "server": Server information (json-object)
 321   - "host": IP address (json-string)
 322   - "port": port number (json-string)
 323   - "family": address family (json-string, "ipv4" or "ipv6")
 324   - "auth": authentication method (json-string, optional)
 325 - "client": Client information (json-object)
 326   - "host": IP address (json-string)
 327   - "port": port number (json-string)
 328   - "family": address family (json-string, "ipv4" or "ipv6")
 329   - "connection-id": spice connection id.  All channels with the same id
 330                      belong to the same spice session (json-int)
 331   - "channel-type": channel type.  "1" is the main control channel, filter for
 332                     this one if you want track spice sessions only (json-int)
 333   - "channel-id": channel id.  Usually "0", might be different needed when
 334                   multiple channels of the same type exist, such as multiple
 335                   display channels in a multihead setup (json-int)
 336   - "tls": whevener the channel is encrypted (json-bool)
 337
 338 Example:
 339
 340 { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
 341   "event": "SPICE_INITIALIZED",
 342   "data": {"server": {"auth": "spice", "port": "5921",
 343                       "family": "ipv4", "host": "127.0.0.1"},
 344            "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
 345                       "connection-id": 1804289383, "host": "127.0.0.1",
 346                       "channel-id": 0, "tls": true}
 347 }}
 348
 349 SPICE_MIGRATE_COMPLETED
 350 -----------------------
 351
 352 Emitted when SPICE migration has completed
 353
 354 Data: None.
 355
 356 Example:
 357
 358 { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
 359   "event": "SPICE_MIGRATE_COMPLETED" }
 360
 361 MIGRATION
 362 ---------
 363
 364 Emitted when a migration event happens
 365
 366 Data: None.
 367
 368  - "status": migration status
 369      See MigrationStatus in ~/qapi-schema.json for possible values
 370
 371 Example:
 372
 373 {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
 374  "event": "MIGRATION", "data": {"status": "completed"}}
 375
 376 MIGRATION_PASS
 377 --------------
 378
 379 Emitted from the source side of a migration at the start of each pass
 380 (when it syncs the dirty bitmap)
 381
 382 Data: None.
 383
 384   - "pass": An incrementing count (starting at 1 on the first pass)
 385
 386 Example:
 387 {"timestamp": {"seconds": 1449669631, "microseconds": 239225},
 388  "event": "MIGRATION_PASS", "data": {"pass": 2}}
 389
 390 STOP
 391 ----
 392
 393 Emitted when the Virtual Machine is stopped.
 394
 395 Data: None.
 396
 397 Example:
 398
 399 { "event": "STOP",
 400     "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
 401
 402 SUSPEND
 403 -------
 404
 405 Emitted when guest enters S3 state.
 406
 407 Data: None.
 408
 409 Example:
 410
 411 { "event": "SUSPEND",
 412      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
 413
 414 SUSPEND_DISK
 415 ------------
 416
 417 Emitted when the guest makes a request to enter S4 state.
 418
 419 Data: None.
 420
 421 Example:
 422
 423 { "event": "SUSPEND_DISK",
 424      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
 425
 426 Note: QEMU shuts down when entering S4 state.
 427
 428 VNC_CONNECTED
 429 -------------
 430
 431 Emitted when a VNC client establishes a connection.
 432
 433 Data:
 434
 435 - "server": Server information (json-object)
 436   - "host": IP address (json-string)
 437   - "service": port number (json-string)
 438   - "family": address family (json-string, "ipv4" or "ipv6")
 439   - "auth": authentication method (json-string, optional)
 440 - "client": Client information (json-object)
 441   - "host": IP address (json-string)
 442   - "service": port number (json-string)
 443   - "family": address family (json-string, "ipv4" or "ipv6")
 444
 445 Example:
 446
 447 { "event": "VNC_CONNECTED",
 448     "data": {
 449         "server": { "auth": "sasl", "family": "ipv4",
 450                     "service": "5901", "host": "0.0.0.0" },
 451         "client": { "family": "ipv4", "service": "58425",
 452                     "host": "127.0.0.1" } },
 453     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
 454
 455
 456 Note: This event is emitted before any authentication takes place, thus
 457 the authentication ID is not provided.
 458
 459 VNC_DISCONNECTED
 460 ----------------
 461
 462 Emitted when the connection is closed.
 463
 464 Data:
 465
 466 - "server": Server information (json-object)
 467   - "host": IP address (json-string)
 468   - "service": port number (json-string)
 469   - "family": address family (json-string, "ipv4" or "ipv6")
 470   - "auth": authentication method (json-string, optional)
 471 - "client": Client information (json-object)
 472   - "host": IP address (json-string)
 473   - "service": port number (json-string)
 474   - "family": address family (json-string, "ipv4" or "ipv6")
 475   - "x509_dname": TLS dname (json-string, optional)
 476   - "sasl_username": SASL username (json-string, optional)
 477
 478 Example:
 479
 480 { "event": "VNC_DISCONNECTED",
 481     "data": {
 482         "server": { "auth": "sasl", "family": "ipv4",
 483                     "service": "5901", "host": "0.0.0.0" },
 484         "client": { "family": "ipv4", "service": "58425",
 485                     "host": "127.0.0.1", "sasl_username": "luiz" } },
 486     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
 487
 488 VNC_INITIALIZED
 489 ---------------
 490
 491 Emitted after authentication takes place (if any) and the VNC session is
 492 made active.
 493
 494 Data:
 495
 496 - "server": Server information (json-object)
 497   - "host": IP address (json-string)
 498   - "service": port number (json-string)
 499   - "family": address family (json-string, "ipv4" or "ipv6")
 500   - "auth": authentication method (json-string, optional)
 501 - "client": Client information (json-object)
 502   - "host": IP address (json-string)
 503   - "service": port number (json-string)
 504   - "family": address family (json-string, "ipv4" or "ipv6")
 505   - "x509_dname": TLS dname (json-string, optional)
 506   - "sasl_username": SASL username (json-string, optional)
 507
 508 Example:
 509
 510 { "event": "VNC_INITIALIZED",
 511     "data": {
 512         "server": { "auth": "sasl", "family": "ipv4",
 513                     "service": "5901", "host": "0.0.0.0"},
 514         "client": { "family": "ipv4", "service": "46089",
 515                     "host": "127.0.0.1", "sasl_username": "luiz" } },
 516         "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
 517
 518 VSERPORT_CHANGE
 519 ---------------
 520
 521 Emitted when the guest opens or closes a virtio-serial port.
 522
 523 Data:
 524
 525 - "id": device identifier of the virtio-serial port (json-string)
 526 - "open": true if the guest has opened the virtio-serial port (json-bool)
 527
 528 Example:
 529
 530 { "event": "VSERPORT_CHANGE",
 531     "data": { "id": "channel0", "open": true },
 532     "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
 533
 534 Note: this event is rate-limited separately for each "id".
 535
 536 WAKEUP
 537 ------
 538
 539 Emitted when the guest has woken up from S3 and is running.
 540
 541 Data: None.
 542
 543 Example:
 544
 545 { "event": "WAKEUP",
 546      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
 547
 548 WATCHDOG
 549 --------
 550
 551 Emitted when the watchdog device's timer is expired.
 552
 553 Data:
 554
 555 - "action": Action that has been taken, it's one of the following (json-string):
 556             "reset", "shutdown", "poweroff", "pause", "debug", or "none"
 557
 558 Example:
 559
 560 { "event": "WATCHDOG",
 561      "data": { "action": "reset" },
 562      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
 563
 564 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
 565 followed respectively by the RESET, SHUTDOWN, or STOP events.
 566
 567 Note: this event is rate-limited.