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 BLOCK_IO_ERROR
  34 --------------
  35
  36 Emitted when a disk I/O error occurs.
  37
  38 Data:
  39
  40 - "device": device name. This is always present for compatibility
  41             reasons, but it can be empty ("") if the image does not
  42             have a device name associated. (json-string)
  43 - "node-name": node name. Note that errors may be reported for the root node
  44                that is directly attached to a guest device rather than for the
  45                node where the error occurred. (json-string)
  46 - "operation": I/O operation (json-string, "read" or "write")
  47 - "action": action that has been taken, it's one of the following (json-string):
  48     "ignore": error has been ignored
  49     "report": error has been reported to the device
  50     "stop": the VM is going to stop because of the error
  51
  52 Example:
  53
  54 { "event": "BLOCK_IO_ERROR",
  55     "data": { "device": "ide0-hd1",
  56               "node-name": "#block212",
  57               "operation": "write",
  58               "action": "stop" },
  59     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
  60
  61 Note: If action is "stop", a STOP event will eventually follow the
  62 BLOCK_IO_ERROR event.
  63
  64 BLOCK_JOB_CANCELLED
  65 -------------------
  66
  67 Emitted when a block job has been cancelled.
  68
  69 Data:
  70
  71 - "type":     Job type (json-string; "stream" for image streaming
  72                                      "commit" for block commit)
  73 - "device":   Job identifier. Originally the device name but other
  74               values are allowed since QEMU 2.7 (json-string)
  75 - "len":      Maximum progress value (json-int)
  76 - "offset":   Current progress value (json-int)
  77               On success this is equal to len.
  78               On failure this is less than len.
  79 - "speed":    Rate limit, bytes per second (json-int)
  80
  81 Example:
  82
  83 { "event": "BLOCK_JOB_CANCELLED",
  84      "data": { "type": "stream", "device": "virtio-disk0",
  85                "len": 10737418240, "offset": 134217728,
  86                "speed": 0 },
  87      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
  88
  89 BLOCK_JOB_COMPLETED
  90 -------------------
  91
  92 Emitted when a block job has completed.
  93
  94 Data:
  95
  96 - "type":     Job type (json-string; "stream" for image streaming
  97                                      "commit" for block commit)
  98 - "device":   Job identifier. Originally the device name but other
  99               values are allowed since QEMU 2.7 (json-string)
 100 - "len":      Maximum progress value (json-int)
 101 - "offset":   Current progress value (json-int)
 102               On success this is equal to len.
 103               On failure this is less than len.
 104 - "speed":    Rate limit, bytes per second (json-int)
 105 - "error":    Error message (json-string, optional)
 106               Only present on failure.  This field contains a human-readable
 107               error message.  There are no semantics other than that streaming
 108               has failed and clients should not try to interpret the error
 109               string.
 110
 111 Example:
 112
 113 { "event": "BLOCK_JOB_COMPLETED",
 114      "data": { "type": "stream", "device": "virtio-disk0",
 115                "len": 10737418240, "offset": 10737418240,
 116                "speed": 0 },
 117      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
 118
 119 BLOCK_JOB_ERROR
 120 ---------------
 121
 122 Emitted when a block job encounters an error.
 123
 124 Data:
 125
 126 - "device": Job identifier. Originally the device name but other
 127             values are allowed since QEMU 2.7 (json-string)
 128 - "operation": I/O operation (json-string, "read" or "write")
 129 - "action": action that has been taken, it's one of the following (json-string):
 130     "ignore": error has been ignored, the job may fail later
 131     "report": error will be reported and the job canceled
 132     "stop": error caused job to be paused
 133
 134 Example:
 135
 136 { "event": "BLOCK_JOB_ERROR",
 137     "data": { "device": "ide0-hd1",
 138               "operation": "write",
 139               "action": "stop" },
 140     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 141
 142 BLOCK_JOB_READY
 143 ---------------
 144
 145 Emitted when a block job is ready to complete.
 146
 147 Data:
 148
 149 - "type":     Job type (json-string; "stream" for image streaming
 150                                      "commit" for block commit)
 151 - "device":   Job identifier. Originally the device name but other
 152               values are allowed since QEMU 2.7 (json-string)
 153 - "len":      Maximum progress value (json-int)
 154 - "offset":   Current progress value (json-int)
 155               On success this is equal to len.
 156               On failure this is less than len.
 157 - "speed":    Rate limit, bytes per second (json-int)
 158
 159 Example:
 160
 161 { "event": "BLOCK_JOB_READY",
 162     "data": { "device": "drive0", "type": "mirror", "speed": 0,
 163               "len": 2097152, "offset": 2097152 }
 164     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 165
 166 Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
 167 event.
 168
 169 DEVICE_DELETED
 170 --------------
 171
 172 Emitted whenever the device removal completion is acknowledged
 173 by the guest.
 174 At this point, it's safe to reuse the specified device ID.
 175 Device removal can be initiated by the guest or by HMP/QMP commands.
 176
 177 Data:
 178
 179 - "device": device name (json-string, optional)
 180 - "path": device path (json-string)
 181
 182 { "event": "DEVICE_DELETED",
 183   "data": { "device": "virtio-net-pci-0",
 184             "path": "/machine/peripheral/virtio-net-pci-0" },
 185   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 186
 187 DEVICE_TRAY_MOVED
 188 -----------------
 189
 190 It's emitted whenever the tray of a removable device is moved by the guest
 191 or by HMP/QMP commands.
 192
 193 Data:
 194
 195 - "device": Block device name. This is always present for compatibility
 196             reasons, but it can be empty ("") if the image does not have a
 197             device name associated. (json-string)
 198 - "id": The name or QOM path of the guest device (json-string)
 199 - "tray-open": true if the tray has been opened or false if it has been closed
 200                (json-bool)
 201
 202 { "event": "DEVICE_TRAY_MOVED",
 203   "data": { "device": "ide1-cd0",
 204             "id": "/machine/unattached/device[22]",
 205             "tray-open": true
 206   },
 207   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 208
 209 DUMP_COMPLETED
 210 --------------
 211
 212 Emitted when the guest has finished one memory dump.
 213
 214 Data:
 215
 216 - "result": DumpQueryResult type described in qapi-schema.json
 217 - "error": Error message when dump failed. This is only a
 218   human-readable string provided when dump failed. It should not be
 219   parsed in any way (json-string, optional)
 220
 221 Example:
 222
 223 { "event": "DUMP_COMPLETED",
 224   "data": {"result": {"total": 1090650112, "status": "completed",
 225                       "completed": 1090650112} } }
 226
 227 GUEST_PANICKED
 228 --------------
 229
 230 Emitted when guest OS panic is detected.
 231
 232 Data:
 233
 234 - "action": Action that has been taken (json-string, currently always "pause").
 235
 236 Example:
 237
 238 { "event": "GUEST_PANICKED",
 239      "data": { "action": "pause" } }
 240
 241 MEM_UNPLUG_ERROR
 242 --------------------
 243 Emitted when memory hot unplug error occurs.
 244
 245 Data:
 246
 247 - "device": device name (json-string)
 248 - "msg": Informative message (e.g., reason for the error) (json-string)
 249
 250 Example:
 251
 252 { "event": "MEM_UNPLUG_ERROR"
 253   "data": { "device": "dimm1",
 254             "msg": "acpi: device unplug for unsupported device"
 255   },
 256   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 257
 258 NIC_RX_FILTER_CHANGED
 259 ---------------------
 260
 261 The event is emitted once until the query command is executed,
 262 the first event will always be emitted.
 263
 264 Data:
 265
 266 - "name": net client name (json-string)
 267 - "path": device path (json-string)
 268
 269 { "event": "NIC_RX_FILTER_CHANGED",
 270   "data": { "name": "vnet0",
 271             "path": "/machine/peripheral/vnet0/virtio-backend" },
 272   "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
 273 }
 274
 275 POWERDOWN
 276 ---------
 277
 278 Emitted when the Virtual Machine is powered down through the power
 279 control system, such as via ACPI.
 280
 281 Data: None.
 282
 283 Example:
 284
 285 { "event": "POWERDOWN",
 286     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
 287
 288 QUORUM_FAILURE
 289 --------------
 290
 291 Emitted by the Quorum block driver if it fails to establish a quorum.
 292
 293 Data:
 294
 295 - "reference":     device name if defined else node name.
 296 - "sector-num":    Number of the first sector of the failed read operation.
 297 - "sectors-count": Failed read operation sector count.
 298
 299 Example:
 300
 301 { "event": "QUORUM_FAILURE",
 302      "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
 303      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
 304
 305 Note: this event is rate-limited.
 306
 307 QUORUM_REPORT_BAD
 308 -----------------
 309
 310 Emitted to report a corruption of a Quorum file.
 311
 312 Data:
 313
 314 - "type":          Quorum operation type
 315 - "error":         Error message (json-string, optional)
 316                    Only present on failure.  This field contains a human-readable
 317                    error message.  There are no semantics other than that the
 318                    block layer reported an error and clients should not try to
 319                    interpret the error string.
 320 - "node-name":     The graph node name of the block driver state.
 321 - "sector-num":    Number of the first sector of the failed read operation.
 322 - "sectors-count": Failed read operation sector count.
 323
 324 Example:
 325
 326 Read operation:
 327 { "event": "QUORUM_REPORT_BAD",
 328      "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
 329                "type": "read" },
 330      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
 331
 332 Flush operation:
 333 { "event": "QUORUM_REPORT_BAD",
 334      "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
 335                "type": "flush", "error": "Broken pipe" },
 336      "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
 337
 338 Note: this event is rate-limited.
 339
 340 RESET
 341 -----
 342
 343 Emitted when the Virtual Machine is reset.
 344
 345 Data: None.
 346
 347 Example:
 348
 349 { "event": "RESET",
 350     "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
 351
 352 RESUME
 353 ------
 354
 355 Emitted when the Virtual Machine resumes execution.
 356
 357 Data: None.
 358
 359 Example:
 360
 361 { "event": "RESUME",
 362     "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
 363
 364 RTC_CHANGE
 365 ----------
 366
 367 Emitted when the guest changes the RTC time.
 368
 369 Data:
 370
 371 - "offset": Offset between base RTC clock (as specified by -rtc base), and
 372 new RTC clock value (json-number)
 373
 374 Example:
 375
 376 { "event": "RTC_CHANGE",
 377     "data": { "offset": 78 },
 378     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
 379
 380 Note: this event is rate-limited.
 381
 382 SHUTDOWN
 383 --------
 384
 385 Emitted when the Virtual Machine has shut down, indicating that qemu
 386 is about to exit.
 387
 388 Data: None.
 389
 390 Example:
 391
 392 { "event": "SHUTDOWN",
 393     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
 394
 395 Note: If the command-line option "-no-shutdown" has been specified, a STOP
 396 event will eventually follow the SHUTDOWN event.
 397
 398 SPICE_CONNECTED
 399 ---------------
 400
 401 Emitted when a SPICE client connects.
 402
 403 Data:
 404
 405 - "server": Server information (json-object)
 406   - "host": IP address (json-string)
 407   - "port": port number (json-string)
 408   - "family": address family (json-string, "ipv4" or "ipv6")
 409 - "client": Client information (json-object)
 410   - "host": IP address (json-string)
 411   - "port": port number (json-string)
 412   - "family": address family (json-string, "ipv4" or "ipv6")
 413
 414 Example:
 415
 416 { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
 417   "event": "SPICE_CONNECTED",
 418   "data": {
 419     "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
 420     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
 421 }}
 422
 423 SPICE_DISCONNECTED
 424 ------------------
 425
 426 Emitted when a SPICE client disconnects.
 427
 428 Data:
 429
 430 - "server": Server information (json-object)
 431   - "host": IP address (json-string)
 432   - "port": port number (json-string)
 433   - "family": address family (json-string, "ipv4" or "ipv6")
 434 - "client": Client information (json-object)
 435   - "host": IP address (json-string)
 436   - "port": port number (json-string)
 437   - "family": address family (json-string, "ipv4" or "ipv6")
 438
 439 Example:
 440
 441 { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
 442   "event": "SPICE_DISCONNECTED",
 443   "data": {
 444     "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
 445     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
 446 }}
 447
 448 SPICE_INITIALIZED
 449 -----------------
 450
 451 Emitted after initial handshake and authentication takes place (if any)
 452 and the SPICE channel is up and running
 453
 454 Data:
 455
 456 - "server": Server information (json-object)
 457   - "host": IP address (json-string)
 458   - "port": port number (json-string)
 459   - "family": address family (json-string, "ipv4" or "ipv6")
 460   - "auth": authentication method (json-string, optional)
 461 - "client": Client information (json-object)
 462   - "host": IP address (json-string)
 463   - "port": port number (json-string)
 464   - "family": address family (json-string, "ipv4" or "ipv6")
 465   - "connection-id": spice connection id.  All channels with the same id
 466                      belong to the same spice session (json-int)
 467   - "channel-type": channel type.  "1" is the main control channel, filter for
 468                     this one if you want track spice sessions only (json-int)
 469   - "channel-id": channel id.  Usually "0", might be different needed when
 470                   multiple channels of the same type exist, such as multiple
 471                   display channels in a multihead setup (json-int)
 472   - "tls": whevener the channel is encrypted (json-bool)
 473
 474 Example:
 475
 476 { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
 477   "event": "SPICE_INITIALIZED",
 478   "data": {"server": {"auth": "spice", "port": "5921",
 479                       "family": "ipv4", "host": "127.0.0.1"},
 480            "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
 481                       "connection-id": 1804289383, "host": "127.0.0.1",
 482                       "channel-id": 0, "tls": true}
 483 }}
 484
 485 SPICE_MIGRATE_COMPLETED
 486 -----------------------
 487
 488 Emitted when SPICE migration has completed
 489
 490 Data: None.
 491
 492 Example:
 493
 494 { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
 495   "event": "SPICE_MIGRATE_COMPLETED" }
 496
 497 MIGRATION
 498 ---------
 499
 500 Emitted when a migration event happens
 501
 502 Data: None.
 503
 504  - "status": migration status
 505      See MigrationStatus in ~/qapi-schema.json for possible values
 506
 507 Example:
 508
 509 {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
 510  "event": "MIGRATION", "data": {"status": "completed"}}
 511
 512 MIGRATION_PASS
 513 --------------
 514
 515 Emitted from the source side of a migration at the start of each pass
 516 (when it syncs the dirty bitmap)
 517
 518 Data: None.
 519
 520   - "pass": An incrementing count (starting at 1 on the first pass)
 521
 522 Example:
 523 {"timestamp": {"seconds": 1449669631, "microseconds": 239225},
 524  "event": "MIGRATION_PASS", "data": {"pass": 2}}
 525
 526 STOP
 527 ----
 528
 529 Emitted when the Virtual Machine is stopped.
 530
 531 Data: None.
 532
 533 Example:
 534
 535 { "event": "STOP",
 536     "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
 537
 538 SUSPEND
 539 -------
 540
 541 Emitted when guest enters S3 state.
 542
 543 Data: None.
 544
 545 Example:
 546
 547 { "event": "SUSPEND",
 548      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
 549
 550 SUSPEND_DISK
 551 ------------
 552
 553 Emitted when the guest makes a request to enter S4 state.
 554
 555 Data: None.
 556
 557 Example:
 558
 559 { "event": "SUSPEND_DISK",
 560      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
 561
 562 Note: QEMU shuts down when entering S4 state.
 563
 564 VNC_CONNECTED
 565 -------------
 566
 567 Emitted when a VNC client establishes a connection.
 568
 569 Data:
 570
 571 - "server": Server information (json-object)
 572   - "host": IP address (json-string)
 573   - "service": port number (json-string)
 574   - "family": address family (json-string, "ipv4" or "ipv6")
 575   - "auth": authentication method (json-string, optional)
 576 - "client": Client information (json-object)
 577   - "host": IP address (json-string)
 578   - "service": port number (json-string)
 579   - "family": address family (json-string, "ipv4" or "ipv6")
 580
 581 Example:
 582
 583 { "event": "VNC_CONNECTED",
 584     "data": {
 585         "server": { "auth": "sasl", "family": "ipv4",
 586                     "service": "5901", "host": "0.0.0.0" },
 587         "client": { "family": "ipv4", "service": "58425",
 588                     "host": "127.0.0.1" } },
 589     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
 590
 591
 592 Note: This event is emitted before any authentication takes place, thus
 593 the authentication ID is not provided.
 594
 595 VNC_DISCONNECTED
 596 ----------------
 597
 598 Emitted when the connection is closed.
 599
 600 Data:
 601
 602 - "server": Server information (json-object)
 603   - "host": IP address (json-string)
 604   - "service": port number (json-string)
 605   - "family": address family (json-string, "ipv4" or "ipv6")
 606   - "auth": authentication method (json-string, optional)
 607 - "client": Client information (json-object)
 608   - "host": IP address (json-string)
 609   - "service": port number (json-string)
 610   - "family": address family (json-string, "ipv4" or "ipv6")
 611   - "x509_dname": TLS dname (json-string, optional)
 612   - "sasl_username": SASL username (json-string, optional)
 613
 614 Example:
 615
 616 { "event": "VNC_DISCONNECTED",
 617     "data": {
 618         "server": { "auth": "sasl", "family": "ipv4",
 619                     "service": "5901", "host": "0.0.0.0" },
 620         "client": { "family": "ipv4", "service": "58425",
 621                     "host": "127.0.0.1", "sasl_username": "luiz" } },
 622     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
 623
 624 VNC_INITIALIZED
 625 ---------------
 626
 627 Emitted after authentication takes place (if any) and the VNC session is
 628 made active.
 629
 630 Data:
 631
 632 - "server": Server information (json-object)
 633   - "host": IP address (json-string)
 634   - "service": port number (json-string)
 635   - "family": address family (json-string, "ipv4" or "ipv6")
 636   - "auth": authentication method (json-string, optional)
 637 - "client": Client information (json-object)
 638   - "host": IP address (json-string)
 639   - "service": port number (json-string)
 640   - "family": address family (json-string, "ipv4" or "ipv6")
 641   - "x509_dname": TLS dname (json-string, optional)
 642   - "sasl_username": SASL username (json-string, optional)
 643
 644 Example:
 645
 646 { "event": "VNC_INITIALIZED",
 647     "data": {
 648         "server": { "auth": "sasl", "family": "ipv4",
 649                     "service": "5901", "host": "0.0.0.0"},
 650         "client": { "family": "ipv4", "service": "46089",
 651                     "host": "127.0.0.1", "sasl_username": "luiz" } },
 652         "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
 653
 654 VSERPORT_CHANGE
 655 ---------------
 656
 657 Emitted when the guest opens or closes a virtio-serial port.
 658
 659 Data:
 660
 661 - "id": device identifier of the virtio-serial port (json-string)
 662 - "open": true if the guest has opened the virtio-serial port (json-bool)
 663
 664 Example:
 665
 666 { "event": "VSERPORT_CHANGE",
 667     "data": { "id": "channel0", "open": true },
 668     "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
 669
 670 Note: this event is rate-limited separately for each "id".
 671
 672 WAKEUP
 673 ------
 674
 675 Emitted when the guest has woken up from S3 and is running.
 676
 677 Data: None.
 678
 679 Example:
 680
 681 { "event": "WAKEUP",
 682      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
 683
 684 WATCHDOG
 685 --------
 686
 687 Emitted when the watchdog device's timer is expired.
 688
 689 Data:
 690
 691 - "action": Action that has been taken, it's one of the following (json-string):
 692             "reset", "shutdown", "poweroff", "pause", "debug", or "none"
 693
 694 Example:
 695
 696 { "event": "WATCHDOG",
 697      "data": { "action": "reset" },
 698      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
 699
 700 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
 701 followed respectively by the RESET, SHUTDOWN, or STOP events.
 702
 703 Note: this event is rate-limited.