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