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