]>
Commit | Line | Data |
---|---|---|
82a56f0d LC |
1 | QMP Supported Commands |
2 | ---------------------- | |
3 | ||
4 | This document describes all commands currently supported by QMP. | |
5 | ||
6 | Most of the time their usage is exactly the same as in the user Monitor, this | |
7 | means that any other document which also describe commands (the manpage, | |
8 | QEMU's manual, etc) can and should be consulted. | |
9 | ||
10 | QMP has two types of commands: regular and query commands. Regular commands | |
11 | usually change the Virtual Machine's state someway, while query commands just | |
12 | return information. The sections below are divided accordingly. | |
13 | ||
14 | It's important to observe that all communication examples are formatted in | |
15 | a reader-friendly way, so that they're easier to understand. However, in real | |
16 | protocol usage, they're emitted as a single line. | |
17 | ||
18 | Also, the following notation is used to denote data flow: | |
19 | ||
20 | -> data issued by the Client | |
21 | <- Server data response | |
22 | ||
77a6da26 | 23 | Please, refer to the QMP specification (docs/qmp-spec.txt) for detailed |
82a56f0d LC |
24 | information on the Server command and response formats. |
25 | ||
26 | NOTE: This document is temporary and will be replaced soon. | |
27 | ||
28 | 1. Stability Considerations | |
29 | =========================== | |
30 | ||
31 | The current QMP command set (described in this file) may be useful for a | |
32 | number of use cases, however it's limited and several commands have bad | |
33 | defined semantics, specially with regard to command completion. | |
34 | ||
35 | These problems are going to be solved incrementally in the next QEMU releases | |
36 | and we're going to establish a deprecation policy for badly defined commands. | |
37 | ||
38 | If you're planning to adopt QMP, please observe the following: | |
39 | ||
c20cdf8b | 40 | 1. The deprecation policy will take effect and be documented soon, please |
82a56f0d LC |
41 | check the documentation of each used command as soon as a new release of |
42 | QEMU is available | |
43 | ||
44 | 2. DO NOT rely on anything which is not explicit documented | |
45 | ||
46 | 3. Errors, in special, are not documented. Applications should NOT check | |
47 | for specific errors classes or data (it's strongly recommended to only | |
48 | check for the "error" key) | |
49 | ||
50 | 2. Regular Commands | |
51 | =================== | |
52 | ||
53 | Server's responses in the examples below are always a success response, please | |
54 | refer to the QMP specification for more details on error responses. | |
55 | ||
82a56f0d LC |
56 | quit |
57 | ---- | |
58 | ||
59 | Quit the emulator. | |
60 | ||
61 | Arguments: None. | |
62 | ||
63 | Example: | |
64 | ||
65 | -> { "execute": "quit" } | |
66 | <- { "return": {} } | |
67 | ||
82a56f0d LC |
68 | eject |
69 | ----- | |
70 | ||
71 | Eject a removable medium. | |
72 | ||
bdf05133 | 73 | Arguments: |
82a56f0d | 74 | |
fbe2d816 KW |
75 | - "force": force ejection (json-bool, optional) |
76 | - "device": block device name (deprecated, use @id instead) | |
77 | (json-string, optional) | |
78 | - "id": the name or QOM path of the guest device (json-string, optional) | |
82a56f0d LC |
79 | |
80 | Example: | |
81 | ||
fbe2d816 | 82 | -> { "execute": "eject", "arguments": { "id": "ide0-1-0" } } |
82a56f0d LC |
83 | <- { "return": {} } |
84 | ||
85 | Note: The "force" argument defaults to false. | |
86 | ||
82a56f0d LC |
87 | change |
88 | ------ | |
89 | ||
90 | Change a removable medium or VNC configuration. | |
91 | ||
92 | Arguments: | |
93 | ||
94 | - "device": device name (json-string) | |
95 | - "target": filename or item (json-string) | |
96 | - "arg": additional argument (json-string, optional) | |
97 | ||
98 | Examples: | |
99 | ||
100 | 1. Change a removable medium | |
101 | ||
102 | -> { "execute": "change", | |
103 | "arguments": { "device": "ide1-cd0", | |
104 | "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } } | |
105 | <- { "return": {} } | |
106 | ||
107 | 2. Change VNC password | |
108 | ||
109 | -> { "execute": "change", | |
110 | "arguments": { "device": "vnc", "target": "password", | |
111 | "arg": "foobar1" } } | |
112 | <- { "return": {} } | |
113 | ||
82a56f0d LC |
114 | screendump |
115 | ---------- | |
116 | ||
117 | Save screen into PPM image. | |
118 | ||
119 | Arguments: | |
120 | ||
121 | - "filename": file path (json-string) | |
122 | ||
123 | Example: | |
124 | ||
125 | -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } } | |
126 | <- { "return": {} } | |
127 | ||
82a56f0d LC |
128 | stop |
129 | ---- | |
130 | ||
131 | Stop the emulator. | |
132 | ||
133 | Arguments: None. | |
134 | ||
135 | Example: | |
136 | ||
137 | -> { "execute": "stop" } | |
138 | <- { "return": {} } | |
139 | ||
82a56f0d LC |
140 | cont |
141 | ---- | |
142 | ||
143 | Resume emulation. | |
144 | ||
145 | Arguments: None. | |
146 | ||
147 | Example: | |
148 | ||
149 | -> { "execute": "cont" } | |
150 | <- { "return": {} } | |
9b9df25a | 151 | |
9b9df25a GH |
152 | system_wakeup |
153 | ------------- | |
154 | ||
155 | Wakeup guest from suspend. | |
156 | ||
157 | Arguments: None. | |
158 | ||
159 | Example: | |
160 | ||
161 | -> { "execute": "system_wakeup" } | |
162 | <- { "return": {} } | |
82a56f0d | 163 | |
82a56f0d LC |
164 | system_reset |
165 | ------------ | |
166 | ||
167 | Reset the system. | |
168 | ||
169 | Arguments: None. | |
170 | ||
171 | Example: | |
172 | ||
173 | -> { "execute": "system_reset" } | |
174 | <- { "return": {} } | |
175 | ||
82a56f0d LC |
176 | system_powerdown |
177 | ---------------- | |
178 | ||
179 | Send system power down event. | |
180 | ||
181 | Arguments: None. | |
182 | ||
183 | Example: | |
184 | ||
185 | -> { "execute": "system_powerdown" } | |
186 | <- { "return": {} } | |
187 | ||
82a56f0d LC |
188 | device_add |
189 | ---------- | |
190 | ||
191 | Add a device. | |
192 | ||
193 | Arguments: | |
194 | ||
195 | - "driver": the name of the new device's driver (json-string) | |
196 | - "bus": the device's parent bus (device tree path, json-string, optional) | |
197 | - "id": the device's ID, must be unique (json-string) | |
198 | - device properties | |
199 | ||
200 | Example: | |
201 | ||
202 | -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } } | |
203 | <- { "return": {} } | |
204 | ||
205 | Notes: | |
206 | ||
207 | (1) For detailed information about this command, please refer to the | |
208 | 'docs/qdev-device-use.txt' file. | |
209 | ||
210 | (2) It's possible to list device properties by running QEMU with the | |
211 | "-device DEVICE,\?" command-line argument, where DEVICE is the device's name | |
212 | ||
82a56f0d LC |
213 | device_del |
214 | ---------- | |
215 | ||
216 | Remove a device. | |
217 | ||
218 | Arguments: | |
219 | ||
6287d827 | 220 | - "id": the device's ID or QOM path (json-string) |
82a56f0d LC |
221 | |
222 | Example: | |
223 | ||
224 | -> { "execute": "device_del", "arguments": { "id": "net1" } } | |
225 | <- { "return": {} } | |
226 | ||
6287d827 DB |
227 | Example: |
228 | ||
229 | -> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } } | |
230 | <- { "return": {} } | |
231 | ||
e4c8f004 AK |
232 | send-key |
233 | ---------- | |
234 | ||
235 | Send keys to VM. | |
236 | ||
237 | Arguments: | |
238 | ||
239 | keys array: | |
f9b1d9b2 AK |
240 | - "key": key sequence (a json-array of key union values, |
241 | union can be number or qcode enum) | |
e4c8f004 AK |
242 | |
243 | - hold-time: time to delay key up events, milliseconds. Defaults to 100 | |
244 | (json-int, optional) | |
245 | ||
246 | Example: | |
247 | ||
248 | -> { "execute": "send-key", | |
f9b1d9b2 AK |
249 | "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, |
250 | { "type": "qcode", "data": "alt" }, | |
251 | { "type": "qcode", "data": "delete" } ] } } | |
e4c8f004 AK |
252 | <- { "return": {} } |
253 | ||
82a56f0d LC |
254 | cpu |
255 | --- | |
256 | ||
257 | Set the default CPU. | |
258 | ||
259 | Arguments: | |
260 | ||
261 | - "index": the CPU's index (json-int) | |
262 | ||
263 | Example: | |
264 | ||
265 | -> { "execute": "cpu", "arguments": { "index": 0 } } | |
266 | <- { "return": {} } | |
267 | ||
268 | Note: CPUs' indexes are obtained with the 'query-cpus' command. | |
269 | ||
69ca3ea5 IM |
270 | cpu-add |
271 | ------- | |
272 | ||
273 | Adds virtual cpu | |
274 | ||
275 | Arguments: | |
276 | ||
277 | - "id": cpu id (json-int) | |
278 | ||
279 | Example: | |
280 | ||
281 | -> { "execute": "cpu-add", "arguments": { "id": 2 } } | |
282 | <- { "return": {} } | |
283 | ||
82a56f0d LC |
284 | memsave |
285 | ------- | |
286 | ||
287 | Save to disk virtual memory dump starting at 'val' of size 'size'. | |
288 | ||
289 | Arguments: | |
290 | ||
291 | - "val": the starting address (json-int) | |
292 | - "size": the memory size, in bytes (json-int) | |
293 | - "filename": file path (json-string) | |
0cfd6a9a | 294 | - "cpu": virtual CPU index (json-int, optional) |
82a56f0d LC |
295 | |
296 | Example: | |
297 | ||
298 | -> { "execute": "memsave", | |
299 | "arguments": { "val": 10, | |
300 | "size": 100, | |
301 | "filename": "/tmp/virtual-mem-dump" } } | |
302 | <- { "return": {} } | |
303 | ||
82a56f0d LC |
304 | pmemsave |
305 | -------- | |
306 | ||
307 | Save to disk physical memory dump starting at 'val' of size 'size'. | |
308 | ||
309 | Arguments: | |
310 | ||
311 | - "val": the starting address (json-int) | |
312 | - "size": the memory size, in bytes (json-int) | |
313 | - "filename": file path (json-string) | |
314 | ||
315 | Example: | |
316 | ||
317 | -> { "execute": "pmemsave", | |
318 | "arguments": { "val": 10, | |
319 | "size": 100, | |
320 | "filename": "/tmp/physical-mem-dump" } } | |
321 | <- { "return": {} } | |
322 | ||
a4046664 LJ |
323 | inject-nmi |
324 | ---------- | |
325 | ||
9cb805fd | 326 | Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64). |
a4046664 LJ |
327 | |
328 | Arguments: None. | |
329 | ||
330 | Example: | |
331 | ||
332 | -> { "execute": "inject-nmi" } | |
333 | <- { "return": {} } | |
334 | ||
de253f14 | 335 | Note: inject-nmi fails when the guest doesn't support injecting. |
a4046664 | 336 | |
3949e594 | 337 | ringbuf-write |
1f590cf9 LL |
338 | ------------- |
339 | ||
3949e594 | 340 | Write to a ring buffer character device. |
1f590cf9 LL |
341 | |
342 | Arguments: | |
343 | ||
3949e594 MA |
344 | - "device": ring buffer character device name (json-string) |
345 | - "data": data to write (json-string) | |
346 | - "format": data format (json-string, optional) | |
347 | - Possible values: "utf8" (default), "base64" | |
1f590cf9 LL |
348 | |
349 | Example: | |
350 | ||
3949e594 MA |
351 | -> { "execute": "ringbuf-write", |
352 | "arguments": { "device": "foo", | |
1f590cf9 LL |
353 | "data": "abcdefgh", |
354 | "format": "utf8" } } | |
355 | <- { "return": {} } | |
356 | ||
3949e594 | 357 | ringbuf-read |
49b6d722 LL |
358 | ------------- |
359 | ||
3949e594 | 360 | Read from a ring buffer character device. |
49b6d722 LL |
361 | |
362 | Arguments: | |
363 | ||
3949e594 MA |
364 | - "device": ring buffer character device name (json-string) |
365 | - "size": how many bytes to read at most (json-int) | |
366 | - Number of data bytes, not number of characters in encoded data | |
367 | - "format": data format (json-string, optional) | |
368 | - Possible values: "utf8" (default), "base64" | |
369 | - Naturally, format "utf8" works only when the ring buffer | |
370 | contains valid UTF-8 text. Invalid UTF-8 sequences get | |
371 | replaced. Bug: replacement doesn't work. Bug: can screw | |
372 | up on encountering NUL characters, after the ring buffer | |
373 | lost data, and when reading stops because the size limit | |
374 | is reached. | |
49b6d722 LL |
375 | |
376 | Example: | |
377 | ||
3949e594 MA |
378 | -> { "execute": "ringbuf-read", |
379 | "arguments": { "device": "foo", | |
49b6d722 LL |
380 | "size": 1000, |
381 | "format": "utf8" } } | |
3ab651fc | 382 | <- {"return": "abcdefgh"} |
49b6d722 | 383 | |
a7ae8355 SS |
384 | xen-save-devices-state |
385 | ------- | |
386 | ||
387 | Save the state of all devices to file. The RAM and the block devices | |
388 | of the VM are not saved by this command. | |
389 | ||
390 | Arguments: | |
391 | ||
392 | - "filename": the file to save the state of the devices to as binary | |
393 | data. See xen-save-devices-state.txt for a description of the binary | |
394 | format. | |
395 | ||
396 | Example: | |
397 | ||
398 | -> { "execute": "xen-save-devices-state", | |
399 | "arguments": { "filename": "/tmp/save" } } | |
400 | <- { "return": {} } | |
401 | ||
88c16567 WC |
402 | xen-load-devices-state |
403 | ---------------------- | |
404 | ||
405 | Load the state of all devices from file. The RAM and the block devices | |
406 | of the VM are not loaded by this command. | |
407 | ||
408 | Arguments: | |
409 | ||
410 | - "filename": the file to load the state of the devices from as binary | |
411 | data. See xen-save-devices-state.txt for a description of the binary | |
412 | format. | |
413 | ||
414 | Example: | |
415 | ||
416 | -> { "execute": "xen-load-devices-state", | |
417 | "arguments": { "filename": "/tmp/resume" } } | |
418 | <- { "return": {} } | |
419 | ||
39f42439 AP |
420 | xen-set-global-dirty-log |
421 | ------- | |
422 | ||
423 | Enable or disable the global dirty log mode. | |
424 | ||
425 | Arguments: | |
426 | ||
427 | - "enable": Enable it or disable it. | |
428 | ||
429 | Example: | |
430 | ||
431 | -> { "execute": "xen-set-global-dirty-log", | |
432 | "arguments": { "enable": true } } | |
433 | <- { "return": {} } | |
434 | ||
82a56f0d LC |
435 | migrate |
436 | ------- | |
437 | ||
438 | Migrate to URI. | |
439 | ||
440 | Arguments: | |
441 | ||
442 | - "blk": block migration, full disk copy (json-bool, optional) | |
443 | - "inc": incremental disk copy (json-bool, optional) | |
444 | - "uri": Destination URI (json-string) | |
445 | ||
446 | Example: | |
447 | ||
448 | -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } | |
449 | <- { "return": {} } | |
450 | ||
451 | Notes: | |
452 | ||
453 | (1) The 'query-migrate' command should be used to check migration's progress | |
454 | and final result (this information is provided by the 'status' member) | |
455 | (2) All boolean arguments default to false | |
456 | (3) The user Monitor's "detach" argument is invalid in QMP and should not | |
457 | be used | |
458 | ||
82a56f0d LC |
459 | migrate_cancel |
460 | -------------- | |
461 | ||
462 | Cancel the current migration. | |
463 | ||
464 | Arguments: None. | |
465 | ||
466 | Example: | |
467 | ||
468 | -> { "execute": "migrate_cancel" } | |
469 | <- { "return": {} } | |
470 | ||
bf1ae1f4 DDAG |
471 | migrate-incoming |
472 | ---------------- | |
473 | ||
474 | Continue an incoming migration | |
475 | ||
476 | Arguments: | |
477 | ||
478 | - "uri": Source/listening URI (json-string) | |
479 | ||
480 | Example: | |
481 | ||
482 | -> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } } | |
483 | <- { "return": {} } | |
484 | ||
485 | Notes: | |
486 | ||
487 | (1) QEMU must be started with -incoming defer to allow migrate-incoming to | |
488 | be used | |
4aab6282 | 489 | (2) The uri format is the same as for -incoming |
bf1ae1f4 | 490 | |
9e1ba4cc | 491 | migrate-set-cache-size |
817c6045 | 492 | ---------------------- |
9e1ba4cc OW |
493 | |
494 | Set cache size to be used by XBZRLE migration, the cache size will be rounded | |
495 | down to the nearest power of 2 | |
496 | ||
497 | Arguments: | |
498 | ||
499 | - "value": cache size in bytes (json-int) | |
500 | ||
501 | Example: | |
502 | ||
503 | -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } } | |
504 | <- { "return": {} } | |
505 | ||
4886a1bc DDAG |
506 | migrate-start-postcopy |
507 | ---------------------- | |
508 | ||
509 | Switch an in-progress migration to postcopy mode. Ignored after the end of | |
510 | migration (or once already in postcopy). | |
511 | ||
512 | Example: | |
513 | -> { "execute": "migrate-start-postcopy" } | |
514 | <- { "return": {} } | |
515 | ||
9e1ba4cc | 516 | query-migrate-cache-size |
817c6045 | 517 | ------------------------ |
9e1ba4cc OW |
518 | |
519 | Show cache size to be used by XBZRLE migration | |
520 | ||
521 | returns a json-object with the following information: | |
522 | - "size" : json-int | |
523 | ||
524 | Example: | |
525 | ||
526 | -> { "execute": "query-migrate-cache-size" } | |
527 | <- { "return": 67108864 } | |
528 | ||
ff73edf5 JS |
529 | migrate_set_speed |
530 | ----------------- | |
e866e239 | 531 | |
ff73edf5 | 532 | Set maximum speed for migrations. |
e866e239 GH |
533 | |
534 | Arguments: | |
535 | ||
ff73edf5 | 536 | - "value": maximum speed, in bytes per second (json-int) |
e866e239 GH |
537 | |
538 | Example: | |
539 | ||
ff73edf5 | 540 | -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } } |
e866e239 GH |
541 | <- { "return": {} } |
542 | ||
ff73edf5 JS |
543 | migrate_set_downtime |
544 | -------------------- | |
82a56f0d | 545 | |
ff73edf5 | 546 | Set maximum tolerated downtime (in seconds) for migrations. |
82a56f0d LC |
547 | |
548 | Arguments: | |
549 | ||
ff73edf5 | 550 | - "value": maximum downtime (json-number) |
82a56f0d LC |
551 | |
552 | Example: | |
553 | ||
ff73edf5 | 554 | -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } } |
82a56f0d LC |
555 | <- { "return": {} } |
556 | ||
ff73edf5 | 557 | client_migrate_info |
13cadefb | 558 | ------------------- |
82a56f0d | 559 | |
13cadefb MA |
560 | Set migration information for remote display. This makes the server |
561 | ask the client to automatically reconnect using the new parameters | |
562 | once migration finished successfully. Only implemented for SPICE. | |
82a56f0d LC |
563 | |
564 | Arguments: | |
565 | ||
13cadefb | 566 | - "protocol": must be "spice" (json-string) |
ff73edf5 | 567 | - "hostname": migration target hostname (json-string) |
13cadefb | 568 | - "port": spice tcp port for plaintext channels (json-int, optional) |
ff73edf5 JS |
569 | - "tls-port": spice tcp port for tls-secured channels (json-int, optional) |
570 | - "cert-subject": server certificate subject (json-string, optional) | |
82a56f0d LC |
571 | |
572 | Example: | |
573 | ||
ff73edf5 JS |
574 | -> { "execute": "client_migrate_info", |
575 | "arguments": { "protocol": "spice", | |
576 | "hostname": "virt42.lab.kraxel.org", | |
577 | "port": 1234 } } | |
82a56f0d LC |
578 | <- { "return": {} } |
579 | ||
783e9b48 WC |
580 | dump |
581 | ||
582 | ||
583 | Dump guest memory to file. The file can be processed with crash or gdb. | |
584 | ||
585 | Arguments: | |
586 | ||
587 | - "paging": do paging to get guest's memory mapping (json-bool) | |
588 | - "protocol": destination file(started with "file:") or destination file | |
589 | descriptor (started with "fd:") (json-string) | |
228de9cf | 590 | - "detach": if specified, command will return immediately, without waiting |
39ba2ea6 PX |
591 | for the dump to finish. The user can track progress using |
592 | "query-dump". (json-bool) | |
783e9b48 WC |
593 | - "begin": the starting physical address. It's optional, and should be specified |
594 | with length together (json-int) | |
595 | - "length": the memory size, in bytes. It's optional, and should be specified | |
596 | with begin together (json-int) | |
b53ccc30 QN |
597 | - "format": the format of guest memory dump. It's optional, and can be |
598 | elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will | |
599 | conflict with paging and filter, ie. begin and length (json-string) | |
783e9b48 WC |
600 | |
601 | Example: | |
602 | ||
603 | -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } } | |
604 | <- { "return": {} } | |
605 | ||
606 | Notes: | |
607 | ||
608 | (1) All boolean arguments default to false | |
609 | ||
7d6dc7f3 QN |
610 | query-dump-guest-memory-capability |
611 | ---------- | |
612 | ||
613 | Show available formats for 'dump-guest-memory' | |
614 | ||
615 | Example: | |
616 | ||
617 | -> { "execute": "query-dump-guest-memory-capability" } | |
618 | <- { "return": { "formats": | |
619 | ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } | |
620 | ||
39ba2ea6 PX |
621 | query-dump |
622 | ---------- | |
623 | ||
624 | Query background dump status. | |
625 | ||
626 | Arguments: None. | |
627 | ||
628 | Example: | |
629 | ||
630 | -> { "execute": "query-dump" } | |
631 | <- { "return": { "status": "active", "completed": 1024000, | |
632 | "total": 2048000 } } | |
633 | ||
7ee0c3e3 JH |
634 | dump-skeys |
635 | ---------- | |
636 | ||
637 | Save guest storage keys to file. | |
638 | ||
639 | Arguments: | |
640 | ||
641 | - "filename": file path (json-string) | |
642 | ||
643 | Example: | |
644 | ||
645 | -> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } } | |
646 | <- { "return": {} } | |
647 | ||
82a56f0d LC |
648 | netdev_add |
649 | ---------- | |
650 | ||
651 | Add host network device. | |
652 | ||
653 | Arguments: | |
654 | ||
655 | - "type": the device type, "tap", "user", ... (json-string) | |
656 | - "id": the device's ID, must be unique (json-string) | |
657 | - device options | |
658 | ||
659 | Example: | |
660 | ||
b8a98326 MA |
661 | -> { "execute": "netdev_add", |
662 | "arguments": { "type": "user", "id": "netdev1", | |
663 | "dnssearch": "example.org" } } | |
82a56f0d LC |
664 | <- { "return": {} } |
665 | ||
af347aa5 | 666 | Note: The supported device options are the same ones supported by the '-netdev' |
82a56f0d LC |
667 | command-line argument, which are listed in the '-help' output or QEMU's |
668 | manual | |
669 | ||
82a56f0d LC |
670 | netdev_del |
671 | ---------- | |
672 | ||
673 | Remove host network device. | |
674 | ||
675 | Arguments: | |
676 | ||
677 | - "id": the device's ID, must be unique (json-string) | |
678 | ||
679 | Example: | |
680 | ||
681 | -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } | |
682 | <- { "return": {} } | |
683 | ||
6d4a2b3a | 684 | |
cff8b2c6 PB |
685 | object-add |
686 | ---------- | |
687 | ||
688 | Create QOM object. | |
689 | ||
690 | Arguments: | |
691 | ||
692 | - "qom-type": the object's QOM type, i.e. the class name (json-string) | |
693 | - "id": the object's ID, must be unique (json-string) | |
694 | - "props": a dictionary of object property values (optional, json-dict) | |
695 | ||
696 | Example: | |
697 | ||
698 | -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1", | |
699 | "props": { "filename": "/dev/hwrng" } } } | |
700 | <- { "return": {} } | |
701 | ||
ab2d0531 PB |
702 | object-del |
703 | ---------- | |
704 | ||
705 | Remove QOM object. | |
706 | ||
707 | Arguments: | |
708 | ||
709 | - "id": the object's ID (json-string) | |
710 | ||
711 | Example: | |
712 | ||
713 | -> { "execute": "object-del", "arguments": { "id": "rng1" } } | |
714 | <- { "return": {} } | |
715 | ||
716 | ||
6d4a2b3a CH |
717 | block_resize |
718 | ------------ | |
719 | ||
720 | Resize a block image while a guest is running. | |
721 | ||
722 | Arguments: | |
723 | ||
724 | - "device": the device's ID, must be unique (json-string) | |
3b1dbd11 | 725 | - "node-name": the node name in the block driver state graph (json-string) |
6d4a2b3a CH |
726 | - "size": new size |
727 | ||
728 | Example: | |
729 | ||
730 | -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } } | |
731 | <- { "return": {} } | |
732 | ||
ec683d60 SH |
733 | block-stream |
734 | ------------ | |
735 | ||
736 | Copy data from a backing file into a block device. | |
737 | ||
738 | Arguments: | |
739 | ||
2323322e AG |
740 | - "job-id": Identifier for the newly-created block job. If omitted, |
741 | the device name will be used. (json-string, optional) | |
b6c1bae5 | 742 | - "device": The device name or node-name of a root node (json-string) |
ec683d60 SH |
743 | - "base": The file name of the backing image above which copying starts |
744 | (json-string, optional) | |
745 | - "backing-file": The backing file string to write into the active layer. This | |
746 | filename is not validated. | |
747 | ||
748 | If a pathname string is such that it cannot be resolved by | |
749 | QEMU, that means that subsequent QMP or HMP commands must use | |
750 | node-names for the image in question, as filename lookup | |
751 | methods will fail. | |
752 | ||
753 | If not specified, QEMU will automatically determine the | |
754 | backing file string to use, or error out if there is no | |
755 | obvious choice. Care should be taken when specifying the | |
756 | string, to specify a valid filename or protocol. | |
757 | (json-string, optional) (Since 2.1) | |
758 | - "speed": the maximum speed, in bytes per second (json-int, optional) | |
759 | - "on-error": the action to take on an error (default 'report'). 'stop' and | |
760 | 'enospc' can only be used if the block device supports io-status. | |
761 | (json-string, optional) (Since 2.1) | |
762 | ||
763 | Example: | |
764 | ||
765 | -> { "execute": "block-stream", "arguments": { "device": "virtio0", | |
766 | "base": "/tmp/master.qcow2" } } | |
767 | <- { "return": {} } | |
768 | ||
37222900 JC |
769 | block-commit |
770 | ------------ | |
771 | ||
772 | Live commit of data from overlay image nodes into backing nodes - i.e., writes | |
773 | data between 'top' and 'base' into 'base'. | |
774 | ||
775 | Arguments: | |
776 | ||
fd62c609 AG |
777 | - "job-id": Identifier for the newly-created block job. If omitted, |
778 | the device name will be used. (json-string, optional) | |
1d13b167 | 779 | - "device": The device name or node-name of a root node (json-string) |
37222900 JC |
780 | - "base": The file name of the backing image to write data into. |
781 | If not specified, this is the deepest backing image | |
782 | (json-string, optional) | |
783 | - "top": The file name of the backing image within the image chain, | |
7676e2c5 JC |
784 | which contains the topmost data to be committed down. If |
785 | not specified, this is the active layer. (json-string, optional) | |
37222900 | 786 | |
54e26900 JC |
787 | - backing-file: The backing file string to write into the overlay |
788 | image of 'top'. If 'top' is the active layer, | |
789 | specifying a backing file string is an error. This | |
790 | filename is not validated. | |
791 | ||
792 | If a pathname string is such that it cannot be | |
793 | resolved by QEMU, that means that subsequent QMP or | |
794 | HMP commands must use node-names for the image in | |
795 | question, as filename lookup methods will fail. | |
796 | ||
797 | If not specified, QEMU will automatically determine | |
798 | the backing file string to use, or error out if | |
799 | there is no obvious choice. Care should be taken | |
800 | when specifying the string, to specify a valid | |
801 | filename or protocol. | |
802 | (json-string, optional) (Since 2.1) | |
803 | ||
37222900 JC |
804 | If top == base, that is an error. |
805 | If top == active, the job will not be completed by itself, | |
806 | user needs to complete the job with the block-job-complete | |
807 | command after getting the ready event. (Since 2.0) | |
808 | ||
809 | If the base image is smaller than top, then the base image | |
810 | will be resized to be the same size as top. If top is | |
811 | smaller than the base image, the base will not be | |
812 | truncated. If you want the base image size to match the | |
813 | size of the smaller top, you can safely truncate it | |
814 | yourself once the commit operation successfully completes. | |
815 | (json-string) | |
816 | - "speed": the maximum speed, in bytes per second (json-int, optional) | |
817 | ||
818 | ||
819 | Example: | |
820 | ||
821 | -> { "execute": "block-commit", "arguments": { "device": "virtio0", | |
822 | "top": "/tmp/snap1.qcow2" } } | |
823 | <- { "return": {} } | |
824 | ||
99a9addf SH |
825 | drive-backup |
826 | ------------ | |
827 | ||
828 | Start a point-in-time copy of a block device to a new destination. The | |
829 | status of ongoing drive-backup operations can be checked with | |
830 | query-block-jobs where the BlockJobInfo.type field has the value 'backup'. | |
831 | The operation can be stopped before it has completed using the | |
832 | block-job-cancel command. | |
833 | ||
834 | Arguments: | |
835 | ||
70559d49 AG |
836 | - "job-id": Identifier for the newly-created block job. If omitted, |
837 | the device name will be used. (json-string, optional) | |
b7e4fa22 | 838 | - "device": the device name or node-name of a root node which should be copied. |
99a9addf SH |
839 | (json-string) |
840 | - "target": the target of the new image. If the file exists, or if it is a | |
841 | device, the existing file/device will be used as the new | |
842 | destination. If it does not exist, a new file will be created. | |
843 | (json-string) | |
844 | - "format": the format of the new destination, default is to probe if 'mode' is | |
845 | 'existing', else the format of the source | |
846 | (json-string, optional) | |
b53169ea SH |
847 | - "sync": what parts of the disk image should be copied to the destination; |
848 | possibilities include "full" for all the disk, "top" for only the sectors | |
4b80ab2b | 849 | allocated in the topmost image, "incremental" for only the dirty sectors in |
d58d8453 | 850 | the bitmap, or "none" to only replicate new I/O (MirrorSyncMode). |
4b80ab2b JS |
851 | - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync |
852 | is "incremental", must NOT be present otherwise. | |
99a9addf SH |
853 | - "mode": whether and how QEMU should create a new image |
854 | (NewImageMode, optional, default 'absolute-paths') | |
855 | - "speed": the maximum speed, in bytes per second (json-int, optional) | |
13b9414b PB |
856 | - "compress": true to compress data, if the target format supports it. |
857 | (json-bool, optional, default false) | |
99a9addf SH |
858 | - "on-source-error": the action to take on an error on the source, default |
859 | 'report'. 'stop' and 'enospc' can only be used | |
860 | if the block device supports io-status. | |
861 | (BlockdevOnError, optional) | |
862 | - "on-target-error": the action to take on an error on the target, default | |
863 | 'report' (no limitations, since this applies to | |
864 | a different block device than device). | |
865 | (BlockdevOnError, optional) | |
866 | ||
867 | Example: | |
868 | -> { "execute": "drive-backup", "arguments": { "device": "drive0", | |
fc5d3f84 | 869 | "sync": "full", |
99a9addf SH |
870 | "target": "backup.img" } } |
871 | <- { "return": {} } | |
c29c1dd3 | 872 | |
c29c1dd3 FZ |
873 | blockdev-backup |
874 | --------------- | |
875 | ||
876 | The device version of drive-backup: this command takes an existing named device | |
877 | as backup target. | |
878 | ||
879 | Arguments: | |
880 | ||
70559d49 AG |
881 | - "job-id": Identifier for the newly-created block job. If omitted, |
882 | the device name will be used. (json-string, optional) | |
cef34eeb | 883 | - "device": the device name or node-name of a root node which should be copied. |
c29c1dd3 FZ |
884 | (json-string) |
885 | - "target": the name of the backup target device. (json-string) | |
886 | - "sync": what parts of the disk image should be copied to the destination; | |
887 | possibilities include "full" for all the disk, "top" for only the | |
888 | sectors allocated in the topmost image, or "none" to only replicate | |
889 | new I/O (MirrorSyncMode). | |
890 | - "speed": the maximum speed, in bytes per second (json-int, optional) | |
3b7b1236 PB |
891 | - "compress": true to compress data, if the target format supports it. |
892 | (json-bool, optional, default false) | |
c29c1dd3 FZ |
893 | - "on-source-error": the action to take on an error on the source, default |
894 | 'report'. 'stop' and 'enospc' can only be used | |
895 | if the block device supports io-status. | |
896 | (BlockdevOnError, optional) | |
897 | - "on-target-error": the action to take on an error on the target, default | |
898 | 'report' (no limitations, since this applies to | |
899 | a different block device than device). | |
900 | (BlockdevOnError, optional) | |
901 | ||
902 | Example: | |
903 | -> { "execute": "blockdev-backup", "arguments": { "device": "src-id", | |
904 | "sync": "full", | |
905 | "target": "tgt-id" } } | |
906 | <- { "return": {} } | |
907 | ||
52e7c241 PB |
908 | transaction |
909 | ----------- | |
c186402c | 910 | |
a910523a KC |
911 | Atomically operate on one or more block devices. Operations that are |
912 | currently supported: | |
913 | ||
914 | - drive-backup | |
915 | - blockdev-backup | |
916 | - blockdev-snapshot-sync | |
917 | - blockdev-snapshot-internal-sync | |
918 | - abort | |
919 | - block-dirty-bitmap-add | |
920 | - block-dirty-bitmap-clear | |
921 | ||
922 | Refer to the qemu/qapi-schema.json file for minimum required QEMU | |
923 | versions for these operations. A list of dictionaries is accepted, | |
924 | that contains the actions to be performed. If there is any failure | |
925 | performing any of the operations, all operations for the group are | |
926 | abandoned. | |
c186402c | 927 | |
bbe86010 WX |
928 | For external snapshots, the dictionary contains the device, the file to use for |
929 | the new snapshot, and the format. The default format, if not specified, is | |
930 | qcow2. | |
c186402c | 931 | |
bc8b094f PB |
932 | Each new snapshot defaults to being created by QEMU (wiping any |
933 | contents if the file already exists), but it is also possible to reuse | |
934 | an externally-created file. In the latter case, you should ensure that | |
935 | the new image file has the same contents as the current one; QEMU cannot | |
936 | perform any meaningful check. Typically this is achieved by using the | |
937 | current image file as the backing file for the new image. | |
938 | ||
bbe86010 WX |
939 | On failure, the original disks pre-snapshot attempt will be used. |
940 | ||
941 | For internal snapshots, the dictionary contains the device and the snapshot's | |
942 | name. If an internal snapshot matching name already exists, the request will | |
943 | be rejected. Only some image formats support it, for example, qcow2, rbd, | |
944 | and sheepdog. | |
945 | ||
946 | On failure, qemu will try delete the newly created internal snapshot in the | |
947 | transaction. When an I/O error occurs during deletion, the user needs to fix | |
948 | it later with qemu-img or other command. | |
949 | ||
c186402c JC |
950 | Arguments: |
951 | ||
52e7c241 | 952 | actions array: |
a910523a KC |
953 | - "type": the operation to perform (json-string). Possible |
954 | values: "drive-backup", "blockdev-backup", | |
955 | "blockdev-snapshot-sync", | |
956 | "blockdev-snapshot-internal-sync", | |
957 | "abort", "block-dirty-bitmap-add", | |
958 | "block-dirty-bitmap-clear" | |
52e7c241 PB |
959 | - "data": a dictionary. The contents depend on the value |
960 | of "type". When "type" is "blockdev-snapshot-sync": | |
961 | - "device": device name to snapshot (json-string) | |
0901f67e | 962 | - "node-name": graph node name to snapshot (json-string) |
52e7c241 | 963 | - "snapshot-file": name of new image file (json-string) |
0901f67e | 964 | - "snapshot-node-name": graph node name of the new snapshot (json-string) |
52e7c241 | 965 | - "format": format of new image (json-string, optional) |
bc8b094f PB |
966 | - "mode": whether and how QEMU should create the snapshot file |
967 | (NewImageMode, optional, default "absolute-paths") | |
bbe86010 | 968 | When "type" is "blockdev-snapshot-internal-sync": |
75dfd402 KW |
969 | - "device": the device name or node-name of a root node to snapshot |
970 | (json-string) | |
bbe86010 | 971 | - "name": name of the new snapshot (json-string) |
c186402c JC |
972 | |
973 | Example: | |
974 | ||
52e7c241 PB |
975 | -> { "execute": "transaction", |
976 | "arguments": { "actions": [ | |
cd0c5389 | 977 | { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", |
52e7c241 PB |
978 | "snapshot-file": "/some/place/my-image", |
979 | "format": "qcow2" } }, | |
cd0c5389 | 980 | { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", |
0901f67e BC |
981 | "snapshot-file": "/some/place/my-image2", |
982 | "snapshot-node-name": "node3432", | |
983 | "mode": "existing", | |
984 | "format": "qcow2" } }, | |
cd0c5389 | 985 | { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", |
52e7c241 | 986 | "snapshot-file": "/some/place/my-image2", |
bc8b094f | 987 | "mode": "existing", |
bbe86010 | 988 | "format": "qcow2" } }, |
cd0c5389 | 989 | { "type": "blockdev-snapshot-internal-sync", "data" : { |
bbe86010 WX |
990 | "device": "ide-hd2", |
991 | "name": "snapshot0" } } ] } } | |
c186402c JC |
992 | <- { "return": {} } |
993 | ||
341ebc2f JS |
994 | block-dirty-bitmap-add |
995 | ---------------------- | |
996 | Since 2.4 | |
997 | ||
998 | Create a dirty bitmap with a name on the device, and start tracking the writes. | |
999 | ||
1000 | Arguments: | |
1001 | ||
1002 | - "node": device/node on which to create dirty bitmap (json-string) | |
1003 | - "name": name of the new dirty bitmap (json-string) | |
1004 | - "granularity": granularity to track writes with (int, optional) | |
1005 | ||
1006 | Example: | |
1007 | ||
1008 | -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0", | |
1009 | "name": "bitmap0" } } | |
1010 | <- { "return": {} } | |
1011 | ||
341ebc2f JS |
1012 | block-dirty-bitmap-remove |
1013 | ------------------------- | |
1014 | Since 2.4 | |
1015 | ||
1016 | Stop write tracking and remove the dirty bitmap that was created with | |
1017 | block-dirty-bitmap-add. | |
1018 | ||
1019 | Arguments: | |
1020 | ||
1021 | - "node": device/node on which to remove dirty bitmap (json-string) | |
1022 | - "name": name of the dirty bitmap to remove (json-string) | |
1023 | ||
1024 | Example: | |
1025 | ||
1026 | -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0", | |
1027 | "name": "bitmap0" } } | |
1028 | <- { "return": {} } | |
1029 | ||
e74e6b78 JS |
1030 | block-dirty-bitmap-clear |
1031 | ------------------------ | |
1032 | Since 2.4 | |
1033 | ||
1034 | Reset the dirty bitmap associated with a node so that an incremental backup | |
1035 | from this point in time forward will only backup clusters modified after this | |
1036 | clear operation. | |
1037 | ||
1038 | Arguments: | |
1039 | ||
1040 | - "node": device/node on which to remove dirty bitmap (json-string) | |
1041 | - "name": name of the dirty bitmap to remove (json-string) | |
1042 | ||
1043 | Example: | |
1044 | ||
1045 | -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0", | |
1046 | "name": "bitmap0" } } | |
1047 | <- { "return": {} } | |
1048 | ||
d967b2f1 JS |
1049 | blockdev-snapshot-sync |
1050 | ---------------------- | |
1051 | ||
1052 | Synchronous snapshot of a block device. snapshot-file specifies the | |
1053 | target of the new image. If the file exists, or if it is a device, the | |
1054 | snapshot will be created in the existing file/device. If does not | |
1055 | exist, a new file will be created. format specifies the format of the | |
1056 | snapshot image, default is qcow2. | |
1057 | ||
1058 | Arguments: | |
1059 | ||
1060 | - "device": device name to snapshot (json-string) | |
0901f67e | 1061 | - "node-name": graph node name to snapshot (json-string) |
d967b2f1 | 1062 | - "snapshot-file": name of new image file (json-string) |
0901f67e | 1063 | - "snapshot-node-name": graph node name of the new snapshot (json-string) |
6cc2a415 PB |
1064 | - "mode": whether and how QEMU should create the snapshot file |
1065 | (NewImageMode, optional, default "absolute-paths") | |
d967b2f1 JS |
1066 | - "format": format of new image (json-string, optional) |
1067 | ||
1068 | Example: | |
1069 | ||
7f3850c2 LC |
1070 | -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0", |
1071 | "snapshot-file": | |
1072 | "/some/place/my-image", | |
1073 | "format": "qcow2" } } | |
d967b2f1 JS |
1074 | <- { "return": {} } |
1075 | ||
43de7e2d AG |
1076 | blockdev-snapshot |
1077 | ----------------- | |
1078 | Since 2.5 | |
1079 | ||
1080 | Create a snapshot, by installing 'node' as the backing image of | |
1081 | 'overlay'. Additionally, if 'node' is associated with a block | |
1082 | device, the block device changes to using 'overlay' as its new active | |
1083 | image. | |
1084 | ||
1085 | Arguments: | |
1086 | ||
1087 | - "node": device that will have a snapshot created (json-string) | |
1088 | - "overlay": device that will have 'node' as its backing image (json-string) | |
1089 | ||
1090 | Example: | |
1091 | ||
1092 | -> { "execute": "blockdev-add", | |
0153d2f5 KW |
1093 | "arguments": { "driver": "qcow2", |
1094 | "node-name": "node1534", | |
1095 | "file": { "driver": "file", | |
1096 | "filename": "hd1.qcow2" }, | |
1097 | "backing": "" } } | |
43de7e2d AG |
1098 | |
1099 | <- { "return": {} } | |
1100 | ||
1101 | -> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0", | |
1102 | "overlay": "node1534" } } | |
1103 | <- { "return": {} } | |
1104 | ||
f323bc9e WX |
1105 | blockdev-snapshot-internal-sync |
1106 | ------------------------------- | |
1107 | ||
1108 | Synchronously take an internal snapshot of a block device when the format of | |
1109 | image used supports it. If the name is an empty string, or a snapshot with | |
1110 | name already exists, the operation will fail. | |
1111 | ||
1112 | Arguments: | |
1113 | ||
75dfd402 KW |
1114 | - "device": the device name or node-name of a root node to snapshot |
1115 | (json-string) | |
f323bc9e WX |
1116 | - "name": name of the new snapshot (json-string) |
1117 | ||
1118 | Example: | |
1119 | ||
1120 | -> { "execute": "blockdev-snapshot-internal-sync", | |
1121 | "arguments": { "device": "ide-hd0", | |
1122 | "name": "snapshot0" } | |
1123 | } | |
1124 | <- { "return": {} } | |
1125 | ||
44e3e053 WX |
1126 | blockdev-snapshot-delete-internal-sync |
1127 | -------------------------------------- | |
1128 | ||
1129 | Synchronously delete an internal snapshot of a block device when the format of | |
1130 | image used supports it. The snapshot is identified by name or id or both. One | |
1131 | of name or id is required. If the snapshot is not found, the operation will | |
1132 | fail. | |
1133 | ||
1134 | Arguments: | |
1135 | ||
2dfb4c03 | 1136 | - "device": the device name or node-name of a root node (json-string) |
44e3e053 WX |
1137 | - "id": ID of the snapshot (json-string, optional) |
1138 | - "name": name of the snapshot (json-string, optional) | |
1139 | ||
1140 | Example: | |
1141 | ||
1142 | -> { "execute": "blockdev-snapshot-delete-internal-sync", | |
1143 | "arguments": { "device": "ide-hd0", | |
1144 | "name": "snapshot0" } | |
1145 | } | |
1146 | <- { "return": { | |
1147 | "id": "1", | |
1148 | "name": "snapshot0", | |
1149 | "vm-state-size": 0, | |
1150 | "date-sec": 1000012, | |
1151 | "date-nsec": 10, | |
1152 | "vm-clock-sec": 100, | |
1153 | "vm-clock-nsec": 20 | |
1154 | } | |
1155 | } | |
1156 | ||
d9b902db PB |
1157 | drive-mirror |
1158 | ------------ | |
1159 | ||
1160 | Start mirroring a block device's writes to a new destination. target | |
1161 | specifies the target of the new image. If the file exists, or if it is | |
1162 | a device, it will be used as the new destination for writes. If it does not | |
1163 | exist, a new file will be created. format specifies the format of the | |
1164 | mirror image, default is to probe if mode='existing', else the format | |
1165 | of the source. | |
1166 | ||
1167 | Arguments: | |
1168 | ||
71aa9867 AG |
1169 | - "job-id": Identifier for the newly-created block job. If omitted, |
1170 | the device name will be used. (json-string, optional) | |
0524e93a KW |
1171 | - "device": the device name or node-name of a root node whose writes should be |
1172 | mirrored. (json-string) | |
d9b902db PB |
1173 | - "target": name of new image file (json-string) |
1174 | - "format": format of new image (json-string, optional) | |
4c828dc6 BC |
1175 | - "node-name": the name of the new block driver state in the node graph |
1176 | (json-string, optional) | |
09158f00 BC |
1177 | - "replaces": the block driver node name to replace when finished |
1178 | (json-string, optional) | |
d9b902db PB |
1179 | - "mode": how an image file should be created into the target |
1180 | file/device (NewImageMode, optional, default 'absolute-paths') | |
1181 | - "speed": maximum speed of the streaming job, in bytes per second | |
1182 | (json-int) | |
eee13dfe | 1183 | - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional) |
df92562e | 1184 | - "buf-size": maximum amount of data in flight from source to target, in bytes |
08e4ed6c | 1185 | (json-int, default 10M) |
d9b902db PB |
1186 | - "sync": what parts of the disk image should be copied to the destination; |
1187 | possibilities include "full" for all the disk, "top" for only the sectors | |
1188 | allocated in the topmost image, or "none" to only replicate new I/O | |
1189 | (MirrorSyncMode). | |
b952b558 PB |
1190 | - "on-source-error": the action to take on an error on the source |
1191 | (BlockdevOnError, default 'report') | |
1192 | - "on-target-error": the action to take on an error on the target | |
1193 | (BlockdevOnError, default 'report') | |
0fc9f8ea FZ |
1194 | - "unmap": whether the target sectors should be discarded where source has only |
1195 | zeroes. (json-bool, optional, default true) | |
b952b558 | 1196 | |
eee13dfe PB |
1197 | The default value of the granularity is the image cluster size clamped |
1198 | between 4096 and 65536, if the image format defines one. If the format | |
1199 | does not define a cluster size, the default value of the granularity | |
1200 | is 65536. | |
d9b902db PB |
1201 | |
1202 | ||
1203 | Example: | |
1204 | ||
1205 | -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0", | |
1206 | "target": "/some/place/my-image", | |
1207 | "sync": "full", | |
1208 | "format": "qcow2" } } | |
1209 | <- { "return": {} } | |
1210 | ||
df92562e FZ |
1211 | blockdev-mirror |
1212 | ------------ | |
1213 | ||
1214 | Start mirroring a block device's writes to another block device. target | |
1215 | specifies the target of mirror operation. | |
1216 | ||
1217 | Arguments: | |
1218 | ||
71aa9867 AG |
1219 | - "job-id": Identifier for the newly-created block job. If omitted, |
1220 | the device name will be used. (json-string, optional) | |
07eec652 KW |
1221 | - "device": The device name or node-name of a root node whose writes should be |
1222 | mirrored (json-string) | |
df92562e FZ |
1223 | - "target": device name to mirror to (json-string) |
1224 | - "replaces": the block driver node name to replace when finished | |
1225 | (json-string, optional) | |
1226 | - "speed": maximum speed of the streaming job, in bytes per second | |
1227 | (json-int) | |
1228 | - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional) | |
1229 | - "buf_size": maximum amount of data in flight from source to target, in bytes | |
1230 | (json-int, default 10M) | |
1231 | - "sync": what parts of the disk image should be copied to the destination; | |
1232 | possibilities include "full" for all the disk, "top" for only the sectors | |
1233 | allocated in the topmost image, or "none" to only replicate new I/O | |
1234 | (MirrorSyncMode). | |
1235 | - "on-source-error": the action to take on an error on the source | |
1236 | (BlockdevOnError, default 'report') | |
1237 | - "on-target-error": the action to take on an error on the target | |
1238 | (BlockdevOnError, default 'report') | |
1239 | ||
1240 | The default value of the granularity is the image cluster size clamped | |
1241 | between 4096 and 65536, if the image format defines one. If the format | |
1242 | does not define a cluster size, the default value of the granularity | |
1243 | is 65536. | |
1244 | ||
1245 | Example: | |
1246 | ||
1247 | -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0", | |
1248 | "target": "target0", | |
1249 | "sync": "full" } } | |
1250 | <- { "return": {} } | |
1251 | ||
fa40e656 JC |
1252 | change-backing-file |
1253 | ------------------- | |
1254 | Since: 2.1 | |
1255 | ||
1256 | Change the backing file in the image file metadata. This does not cause | |
1257 | QEMU to reopen the image file to reparse the backing filename (it may, | |
1258 | however, perform a reopen to change permissions from r/o -> r/w -> r/o, | |
1259 | if needed). The new backing file string is written into the image file | |
1260 | metadata, and the QEMU internal strings are updated. | |
1261 | ||
1262 | Arguments: | |
1263 | ||
1264 | - "image-node-name": The name of the block driver state node of the | |
1265 | image to modify. The "device" is argument is used to | |
1266 | verify "image-node-name" is in the chain described by | |
1267 | "device". | |
1268 | (json-string, optional) | |
1269 | ||
7b5dca3f KW |
1270 | - "device": The device name or node-name of the root node that owns |
1271 | image-node-name. | |
fa40e656 JC |
1272 | (json-string) |
1273 | ||
1274 | - "backing-file": The string to write as the backing file. This string is | |
1275 | not validated, so care should be taken when specifying | |
1276 | the string or the image chain may not be able to be | |
1277 | reopened again. | |
1278 | (json-string) | |
1279 | ||
1280 | Returns: Nothing on success | |
1281 | If "device" does not exist or cannot be determined, DeviceNotFound | |
1282 | ||
82a56f0d LC |
1283 | balloon |
1284 | ------- | |
1285 | ||
1286 | Request VM to change its memory allocation (in bytes). | |
1287 | ||
1288 | Arguments: | |
1289 | ||
1290 | - "value": New memory allocation (json-int) | |
1291 | ||
1292 | Example: | |
1293 | ||
1294 | -> { "execute": "balloon", "arguments": { "value": 536870912 } } | |
1295 | <- { "return": {} } | |
1296 | ||
82a56f0d LC |
1297 | set_link |
1298 | -------- | |
1299 | ||
1300 | Change the link status of a network adapter. | |
1301 | ||
1302 | Arguments: | |
1303 | ||
1304 | - "name": network device name (json-string) | |
1305 | - "up": status is up (json-bool) | |
1306 | ||
1307 | Example: | |
1308 | ||
1309 | -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } } | |
1310 | <- { "return": {} } | |
1311 | ||
82a56f0d LC |
1312 | getfd |
1313 | ----- | |
1314 | ||
1315 | Receive a file descriptor via SCM rights and assign it a name. | |
1316 | ||
1317 | Arguments: | |
1318 | ||
1319 | - "fdname": file descriptor name (json-string) | |
1320 | ||
1321 | Example: | |
1322 | ||
1323 | -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } | |
1324 | <- { "return": {} } | |
1325 | ||
208c9d1b CB |
1326 | Notes: |
1327 | ||
1328 | (1) If the name specified by the "fdname" argument already exists, | |
1329 | the file descriptor assigned to it will be closed and replaced | |
1330 | by the received file descriptor. | |
1331 | (2) The 'closefd' command can be used to explicitly close the file | |
1332 | descriptor when it is no longer needed. | |
1333 | ||
82a56f0d LC |
1334 | closefd |
1335 | ------- | |
1336 | ||
1337 | Close a file descriptor previously passed via SCM rights. | |
1338 | ||
1339 | Arguments: | |
1340 | ||
1341 | - "fdname": file descriptor name (json-string) | |
1342 | ||
1343 | Example: | |
1344 | ||
1345 | -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } | |
1346 | <- { "return": {} } | |
1347 | ||
ba1c048a CB |
1348 | add-fd |
1349 | ------- | |
1350 | ||
1351 | Add a file descriptor, that was passed via SCM rights, to an fd set. | |
1352 | ||
1353 | Arguments: | |
1354 | ||
1355 | - "fdset-id": The ID of the fd set to add the file descriptor to. | |
1356 | (json-int, optional) | |
1357 | - "opaque": A free-form string that can be used to describe the fd. | |
1358 | (json-string, optional) | |
1359 | ||
1360 | Return a json-object with the following information: | |
1361 | ||
1362 | - "fdset-id": The ID of the fd set that the fd was added to. (json-int) | |
1363 | - "fd": The file descriptor that was received via SCM rights and added to the | |
1364 | fd set. (json-int) | |
1365 | ||
1366 | Example: | |
1367 | ||
1368 | -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } | |
1369 | <- { "return": { "fdset-id": 1, "fd": 3 } } | |
1370 | ||
1371 | Notes: | |
1372 | ||
1373 | (1) The list of fd sets is shared by all monitor connections. | |
1374 | (2) If "fdset-id" is not specified, a new fd set will be created. | |
1375 | ||
ba1c048a CB |
1376 | remove-fd |
1377 | --------- | |
1378 | ||
1379 | Remove a file descriptor from an fd set. | |
1380 | ||
1381 | Arguments: | |
1382 | ||
1383 | - "fdset-id": The ID of the fd set that the file descriptor belongs to. | |
1384 | (json-int) | |
1385 | - "fd": The file descriptor that is to be removed. (json-int, optional) | |
1386 | ||
1387 | Example: | |
1388 | ||
1389 | -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } | |
1390 | <- { "return": {} } | |
1391 | ||
1392 | Notes: | |
1393 | ||
1394 | (1) The list of fd sets is shared by all monitor connections. | |
1395 | (2) If "fd" is not specified, all file descriptors in "fdset-id" will be | |
1396 | removed. | |
1397 | ||
ba1c048a CB |
1398 | query-fdsets |
1399 | ------------- | |
1400 | ||
1401 | Return information describing all fd sets. | |
1402 | ||
1403 | Arguments: None | |
1404 | ||
1405 | Example: | |
1406 | ||
1407 | -> { "execute": "query-fdsets" } | |
1408 | <- { "return": [ | |
1409 | { | |
1410 | "fds": [ | |
1411 | { | |
1412 | "fd": 30, | |
1413 | "opaque": "rdonly:/path/to/file" | |
1414 | }, | |
1415 | { | |
1416 | "fd": 24, | |
1417 | "opaque": "rdwr:/path/to/file" | |
1418 | } | |
1419 | ], | |
1420 | "fdset-id": 1 | |
1421 | }, | |
1422 | { | |
1423 | "fds": [ | |
1424 | { | |
1425 | "fd": 28 | |
1426 | }, | |
1427 | { | |
1428 | "fd": 29 | |
1429 | } | |
1430 | ], | |
1431 | "fdset-id": 0 | |
1432 | } | |
1433 | ] | |
1434 | } | |
1435 | ||
1436 | Note: The list of fd sets is shared by all monitor connections. | |
1437 | ||
82a56f0d LC |
1438 | block_passwd |
1439 | ------------ | |
1440 | ||
1441 | Set the password of encrypted block devices. | |
1442 | ||
1443 | Arguments: | |
1444 | ||
1445 | - "device": device name (json-string) | |
12d3ba82 | 1446 | - "node-name": name in the block driver state graph (json-string) |
82a56f0d LC |
1447 | - "password": password (json-string) |
1448 | ||
1449 | Example: | |
1450 | ||
1451 | -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0", | |
1452 | "password": "12345" } } | |
1453 | <- { "return": {} } | |
1454 | ||
727f005e ZYW |
1455 | block_set_io_throttle |
1456 | ------------ | |
1457 | ||
1458 | Change I/O throttle limits for a block drive. | |
1459 | ||
1460 | Arguments: | |
1461 | ||
7a9877a0 KW |
1462 | - "device": block device name (deprecated, use @id instead) |
1463 | (json-string, optional) | |
1464 | - "id": the name or QOM path of the guest device (json-string, optional) | |
586b5466 EB |
1465 | - "bps": total throughput limit in bytes per second (json-int) |
1466 | - "bps_rd": read throughput limit in bytes per second (json-int) | |
1467 | - "bps_wr": write throughput limit in bytes per second (json-int) | |
1468 | - "iops": total I/O operations per second (json-int) | |
1469 | - "iops_rd": read I/O operations per second (json-int) | |
1470 | - "iops_wr": write I/O operations per second (json-int) | |
dce13204 AG |
1471 | - "bps_max": total throughput limit during bursts, in bytes (json-int, optional) |
1472 | - "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional) | |
1473 | - "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional) | |
1474 | - "iops_max": total I/O operations per second during bursts (json-int, optional) | |
1475 | - "iops_rd_max": read I/O operations per second during bursts (json-int, optional) | |
1476 | - "iops_wr_max": write I/O operations per second during bursts (json-int, optional) | |
1477 | - "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional) | |
1478 | - "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional) | |
1479 | - "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional) | |
1480 | - "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional) | |
1481 | - "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional) | |
1482 | - "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional) | |
1483 | - "iops_size": I/O size in bytes when limiting (json-int, optional) | |
1484 | - "group": throttle group name (json-string, optional) | |
727f005e ZYW |
1485 | |
1486 | Example: | |
1487 | ||
7a9877a0 | 1488 | -> { "execute": "block_set_io_throttle", "arguments": { "id": "ide0-1-0", |
586b5466 EB |
1489 | "bps": 1000000, |
1490 | "bps_rd": 0, | |
1491 | "bps_wr": 0, | |
1492 | "iops": 0, | |
1493 | "iops_rd": 0, | |
3e9fab69 BC |
1494 | "iops_wr": 0, |
1495 | "bps_max": 8000000, | |
1496 | "bps_rd_max": 0, | |
1497 | "bps_wr_max": 0, | |
1498 | "iops_max": 0, | |
1499 | "iops_rd_max": 0, | |
2024c1df | 1500 | "iops_wr_max": 0, |
dce13204 | 1501 | "bps_max_length": 60, |
2024c1df | 1502 | "iops_size": 0 } } |
727f005e ZYW |
1503 | <- { "return": {} } |
1504 | ||
7572150c GH |
1505 | set_password |
1506 | ------------ | |
1507 | ||
1508 | Set the password for vnc/spice protocols. | |
1509 | ||
1510 | Arguments: | |
1511 | ||
1512 | - "protocol": protocol name (json-string) | |
1513 | - "password": password (json-string) | |
3599d46b | 1514 | - "connected": [ keep | disconnect | fail ] (json-string, optional) |
7572150c GH |
1515 | |
1516 | Example: | |
1517 | ||
1518 | -> { "execute": "set_password", "arguments": { "protocol": "vnc", | |
1519 | "password": "secret" } } | |
1520 | <- { "return": {} } | |
1521 | ||
7572150c GH |
1522 | expire_password |
1523 | --------------- | |
1524 | ||
1525 | Set the password expire time for vnc/spice protocols. | |
1526 | ||
1527 | Arguments: | |
1528 | ||
1529 | - "protocol": protocol name (json-string) | |
1530 | - "time": [ now | never | +secs | secs ] (json-string) | |
1531 | ||
1532 | Example: | |
1533 | ||
1534 | -> { "execute": "expire_password", "arguments": { "protocol": "vnc", | |
1535 | "time": "+60" } } | |
1536 | <- { "return": {} } | |
1537 | ||
13661089 DB |
1538 | add_client |
1539 | ---------- | |
1540 | ||
1541 | Add a graphics client | |
1542 | ||
1543 | Arguments: | |
1544 | ||
1545 | - "protocol": protocol name (json-string) | |
1546 | - "fdname": file descriptor name (json-string) | |
f1f5f407 DB |
1547 | - "skipauth": whether to skip authentication (json-bool, optional) |
1548 | - "tls": whether to perform TLS (json-bool, optional) | |
13661089 DB |
1549 | |
1550 | Example: | |
1551 | ||
1552 | -> { "execute": "add_client", "arguments": { "protocol": "vnc", | |
1553 | "fdname": "myclient" } } | |
1554 | <- { "return": {} } | |
1555 | ||
82a56f0d LC |
1556 | qmp_capabilities |
1557 | ---------------- | |
1558 | ||
1559 | Enable QMP capabilities. | |
1560 | ||
1561 | Arguments: None. | |
1562 | ||
1563 | Example: | |
1564 | ||
1565 | -> { "execute": "qmp_capabilities" } | |
1566 | <- { "return": {} } | |
1567 | ||
1568 | Note: This command must be issued before issuing any other command. | |
1569 | ||
0268d97c LC |
1570 | human-monitor-command |
1571 | --------------------- | |
1572 | ||
1573 | Execute a Human Monitor command. | |
1574 | ||
bdf05133 | 1575 | Arguments: |
0268d97c LC |
1576 | |
1577 | - command-line: the command name and its arguments, just like the | |
1578 | Human Monitor's shell (json-string) | |
1579 | - cpu-index: select the CPU number to be used by commands which access CPU | |
1580 | data, like 'info registers'. The Monitor selects CPU 0 if this | |
1581 | argument is not provided (json-int, optional) | |
1582 | ||
1583 | Example: | |
1584 | ||
1585 | -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } } | |
1586 | <- { "return": "kvm support: enabled\r\n" } | |
1587 | ||
1588 | Notes: | |
1589 | ||
1590 | (1) The Human Monitor is NOT an stable interface, this means that command | |
1591 | names, arguments and responses can change or be removed at ANY time. | |
1592 | Applications that rely on long term stability guarantees should NOT | |
1593 | use this command | |
1594 | ||
1595 | (2) Limitations: | |
1596 | ||
1597 | o This command is stateless, this means that commands that depend | |
1598 | on state information (such as getfd) might not work | |
1599 | ||
1600 | o Commands that prompt the user for data (eg. 'cont' when the block | |
1601 | device is encrypted) don't currently work | |
1602 | ||
82a56f0d LC |
1603 | 3. Query Commands |
1604 | ================= | |
1605 | ||
82a56f0d | 1606 | |
82a56f0d LC |
1607 | query-version |
1608 | ------------- | |
1609 | ||
1610 | Show QEMU version. | |
1611 | ||
1612 | Return a json-object with the following information: | |
1613 | ||
1614 | - "qemu": A json-object containing three integer values: | |
1615 | - "major": QEMU's major version (json-int) | |
1616 | - "minor": QEMU's minor version (json-int) | |
1617 | - "micro": QEMU's micro version (json-int) | |
1618 | - "package": package's version (json-string) | |
1619 | ||
1620 | Example: | |
1621 | ||
1622 | -> { "execute": "query-version" } | |
1623 | <- { | |
1624 | "return":{ | |
1625 | "qemu":{ | |
1626 | "major":0, | |
1627 | "minor":11, | |
1628 | "micro":5 | |
1629 | }, | |
1630 | "package":"" | |
1631 | } | |
1632 | } | |
1633 | ||
82a56f0d LC |
1634 | query-commands |
1635 | -------------- | |
1636 | ||
1637 | List QMP available commands. | |
1638 | ||
1639 | Each command is represented by a json-object, the returned value is a json-array | |
1640 | of all commands. | |
1641 | ||
1642 | Each json-object contain: | |
1643 | ||
1644 | - "name": command's name (json-string) | |
1645 | ||
1646 | Example: | |
1647 | ||
1648 | -> { "execute": "query-commands" } | |
1649 | <- { | |
1650 | "return":[ | |
1651 | { | |
1652 | "name":"query-balloon" | |
1653 | }, | |
1654 | { | |
1655 | "name":"system_powerdown" | |
1656 | } | |
1657 | ] | |
1658 | } | |
1659 | ||
1660 | Note: This example has been shortened as the real response is too long. | |
1661 | ||
4860853d DB |
1662 | query-events |
1663 | -------------- | |
1664 | ||
1665 | List QMP available events. | |
1666 | ||
1667 | Each event is represented by a json-object, the returned value is a json-array | |
1668 | of all events. | |
1669 | ||
1670 | Each json-object contains: | |
1671 | ||
1672 | - "name": event's name (json-string) | |
1673 | ||
1674 | Example: | |
1675 | ||
1676 | -> { "execute": "query-events" } | |
1677 | <- { | |
1678 | "return":[ | |
1679 | { | |
1680 | "name":"SHUTDOWN" | |
1681 | }, | |
1682 | { | |
1683 | "name":"RESET" | |
1684 | } | |
1685 | ] | |
1686 | } | |
1687 | ||
1688 | Note: This example has been shortened as the real response is too long. | |
1689 | ||
39a18158 MA |
1690 | query-qmp-schema |
1691 | ---------------- | |
1692 | ||
1693 | Return the QMP wire schema. The returned value is a json-array of | |
1694 | named schema entities. Entities are commands, events and various | |
1695 | types. See docs/qapi-code-gen.txt for information on their structure | |
1696 | and intended use. | |
1697 | ||
82a56f0d LC |
1698 | query-chardev |
1699 | ------------- | |
1700 | ||
1701 | Each device is represented by a json-object. The returned value is a json-array | |
1702 | of all devices. | |
1703 | ||
1704 | Each json-object contain the following: | |
1705 | ||
1706 | - "label": device's label (json-string) | |
1707 | - "filename": device's file (json-string) | |
32a97ea1 LE |
1708 | - "frontend-open": open/closed state of the frontend device attached to this |
1709 | backend (json-bool) | |
82a56f0d LC |
1710 | |
1711 | Example: | |
1712 | ||
1713 | -> { "execute": "query-chardev" } | |
1714 | <- { | |
32a97ea1 LE |
1715 | "return": [ |
1716 | { | |
1717 | "label": "charchannel0", | |
1718 | "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server", | |
1719 | "frontend-open": false | |
1720 | }, | |
82a56f0d | 1721 | { |
32a97ea1 LE |
1722 | "label": "charmonitor", |
1723 | "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server", | |
1724 | "frontend-open": true | |
82a56f0d LC |
1725 | }, |
1726 | { | |
32a97ea1 LE |
1727 | "label": "charserial0", |
1728 | "filename": "pty:/dev/pts/2", | |
1729 | "frontend-open": true | |
82a56f0d LC |
1730 | } |
1731 | ] | |
1732 | } | |
1733 | ||
77d1c3c6 MK |
1734 | query-chardev-backends |
1735 | ------------- | |
1736 | ||
1737 | List available character device backends. | |
1738 | ||
1739 | Each backend is represented by a json-object, the returned value is a json-array | |
1740 | of all backends. | |
1741 | ||
1742 | Each json-object contains: | |
1743 | ||
1744 | - "name": backend name (json-string) | |
1745 | ||
1746 | Example: | |
1747 | ||
1748 | -> { "execute": "query-chardev-backends" } | |
1749 | <- { | |
1750 | "return":[ | |
1751 | { | |
1752 | "name":"udp" | |
1753 | }, | |
1754 | { | |
1755 | "name":"tcp" | |
1756 | }, | |
1757 | { | |
1758 | "name":"unix" | |
1759 | }, | |
1760 | { | |
1761 | "name":"spiceport" | |
1762 | } | |
1763 | ] | |
1764 | } | |
1765 | ||
82a56f0d LC |
1766 | query-block |
1767 | ----------- | |
1768 | ||
1769 | Show the block devices. | |
1770 | ||
1771 | Each block device information is stored in a json-object and the returned value | |
1772 | is a json-array of all devices. | |
1773 | ||
1774 | Each json-object contain the following: | |
1775 | ||
1776 | - "device": device name (json-string) | |
1777 | - "type": device type (json-string) | |
d8aeeb31 MA |
1778 | - deprecated, retained for backward compatibility |
1779 | - Possible values: "unknown" | |
82a56f0d LC |
1780 | - "removable": true if the device is removable, false otherwise (json-bool) |
1781 | - "locked": true if the device is locked, false otherwise (json-bool) | |
99f42808 | 1782 | - "tray_open": only present if removable, true if the device has a tray, |
e4def80b | 1783 | and it is open (json-bool) |
82a56f0d LC |
1784 | - "inserted": only present if the device is inserted, it is a json-object |
1785 | containing the following: | |
1786 | - "file": device file name (json-string) | |
1787 | - "ro": true if read-only, false otherwise (json-bool) | |
1788 | - "drv": driver format name (json-string) | |
550830f9 | 1789 | - Possible values: "blkdebug", "bochs", "cloop", "dmg", |
82a56f0d | 1790 | "file", "file", "ftp", "ftps", "host_cdrom", |
92a539d2 | 1791 | "host_device", "http", "https", |
82a56f0d LC |
1792 | "nbd", "parallels", "qcow", "qcow2", "raw", |
1793 | "tftp", "vdi", "vmdk", "vpc", "vvfat" | |
1794 | - "backing_file": backing file name (json-string, optional) | |
2e3e3317 | 1795 | - "backing_file_depth": number of files in the backing file chain (json-int) |
82a56f0d | 1796 | - "encrypted": true if encrypted, false otherwise (json-bool) |
727f005e ZYW |
1797 | - "bps": limit total bytes per second (json-int) |
1798 | - "bps_rd": limit read bytes per second (json-int) | |
1799 | - "bps_wr": limit write bytes per second (json-int) | |
1800 | - "iops": limit total I/O operations per second (json-int) | |
1801 | - "iops_rd": limit read operations per second (json-int) | |
1802 | - "iops_wr": limit write operations per second (json-int) | |
3e9fab69 BC |
1803 | - "bps_max": total max in bytes (json-int) |
1804 | - "bps_rd_max": read max in bytes (json-int) | |
1805 | - "bps_wr_max": write max in bytes (json-int) | |
1806 | - "iops_max": total I/O operations max (json-int) | |
1807 | - "iops_rd_max": read I/O operations max (json-int) | |
1808 | - "iops_wr_max": write I/O operations max (json-int) | |
2024c1df | 1809 | - "iops_size": I/O size when limiting by iops (json-int) |
465bee1d PL |
1810 | - "detect_zeroes": detect and optimize zero writing (json-string) |
1811 | - Possible values: "off", "on", "unmap" | |
e2462113 FR |
1812 | - "write_threshold": write offset threshold in bytes, a event will be |
1813 | emitted if crossed. Zero if disabled (json-int) | |
553a7e87 WX |
1814 | - "image": the detail of the image, it is a json-object containing |
1815 | the following: | |
1816 | - "filename": image file name (json-string) | |
1817 | - "format": image format (json-string) | |
1818 | - "virtual-size": image capacity in bytes (json-int) | |
1819 | - "dirty-flag": true if image is not cleanly closed, not present | |
1820 | means clean (json-bool, optional) | |
1821 | - "actual-size": actual size on disk in bytes of the image, not | |
1822 | present when image does not support thin | |
1823 | provision (json-int, optional) | |
1824 | - "cluster-size": size of a cluster in bytes, not present if image | |
1825 | format does not support it (json-int, optional) | |
1826 | - "encrypted": true if the image is encrypted, not present means | |
1827 | false or the image format does not support | |
1828 | encryption (json-bool, optional) | |
1829 | - "backing_file": backing file name, not present means no backing | |
1830 | file is used or the image format does not | |
1831 | support backing file chain | |
1832 | (json-string, optional) | |
1833 | - "full-backing-filename": full path of the backing file, not | |
1834 | present if it equals backing_file or no | |
1835 | backing file is used | |
1836 | (json-string, optional) | |
1837 | - "backing-filename-format": the format of the backing file, not | |
1838 | present means unknown or no backing | |
1839 | file (json-string, optional) | |
1840 | - "snapshots": the internal snapshot info, it is an optional list | |
1841 | of json-object containing the following: | |
1842 | - "id": unique snapshot id (json-string) | |
1843 | - "name": snapshot name (json-string) | |
1844 | - "vm-state-size": size of the VM state in bytes (json-int) | |
1845 | - "date-sec": UTC date of the snapshot in seconds (json-int) | |
1846 | - "date-nsec": fractional part in nanoseconds to be used with | |
586b5466 | 1847 | date-sec (json-int) |
553a7e87 WX |
1848 | - "vm-clock-sec": VM clock relative to boot in seconds |
1849 | (json-int) | |
1850 | - "vm-clock-nsec": fractional part in nanoseconds to be used | |
1851 | with vm-clock-sec (json-int) | |
1852 | - "backing-image": the detail of the backing image, it is an | |
1853 | optional json-object only present when a | |
1854 | backing image present for this image | |
727f005e | 1855 | |
f04ef601 LC |
1856 | - "io-status": I/O operation status, only present if the device supports it |
1857 | and the VM is configured to stop on errors. It's always reset | |
1858 | to "ok" when the "cont" command is issued (json_string, optional) | |
1859 | - Possible values: "ok", "failed", "nospace" | |
82a56f0d LC |
1860 | |
1861 | Example: | |
1862 | ||
1863 | -> { "execute": "query-block" } | |
1864 | <- { | |
1865 | "return":[ | |
1866 | { | |
f04ef601 | 1867 | "io-status": "ok", |
82a56f0d LC |
1868 | "device":"ide0-hd0", |
1869 | "locked":false, | |
1870 | "removable":false, | |
1871 | "inserted":{ | |
1872 | "ro":false, | |
1873 | "drv":"qcow2", | |
1874 | "encrypted":false, | |
553a7e87 WX |
1875 | "file":"disks/test.qcow2", |
1876 | "backing_file_depth":1, | |
727f005e ZYW |
1877 | "bps":1000000, |
1878 | "bps_rd":0, | |
1879 | "bps_wr":0, | |
1880 | "iops":1000000, | |
1881 | "iops_rd":0, | |
1882 | "iops_wr":0, | |
3e9fab69 BC |
1883 | "bps_max": 8000000, |
1884 | "bps_rd_max": 0, | |
1885 | "bps_wr_max": 0, | |
1886 | "iops_max": 0, | |
1887 | "iops_rd_max": 0, | |
1888 | "iops_wr_max": 0, | |
2024c1df | 1889 | "iops_size": 0, |
465bee1d | 1890 | "detect_zeroes": "on", |
e2462113 | 1891 | "write_threshold": 0, |
553a7e87 WX |
1892 | "image":{ |
1893 | "filename":"disks/test.qcow2", | |
1894 | "format":"qcow2", | |
1895 | "virtual-size":2048000, | |
1896 | "backing_file":"base.qcow2", | |
1897 | "full-backing-filename":"disks/base.qcow2", | |
5403432f | 1898 | "backing-filename-format":"qcow2", |
553a7e87 WX |
1899 | "snapshots":[ |
1900 | { | |
1901 | "id": "1", | |
1902 | "name": "snapshot1", | |
1903 | "vm-state-size": 0, | |
1904 | "date-sec": 10000200, | |
1905 | "date-nsec": 12, | |
1906 | "vm-clock-sec": 206, | |
1907 | "vm-clock-nsec": 30 | |
1908 | } | |
1909 | ], | |
1910 | "backing-image":{ | |
1911 | "filename":"disks/base.qcow2", | |
1912 | "format":"qcow2", | |
1913 | "virtual-size":2048000 | |
1914 | } | |
1915 | } | |
82a56f0d | 1916 | }, |
d8aeeb31 | 1917 | "type":"unknown" |
82a56f0d LC |
1918 | }, |
1919 | { | |
f04ef601 | 1920 | "io-status": "ok", |
82a56f0d LC |
1921 | "device":"ide1-cd0", |
1922 | "locked":false, | |
1923 | "removable":true, | |
d8aeeb31 | 1924 | "type":"unknown" |
82a56f0d LC |
1925 | }, |
1926 | { | |
1927 | "device":"floppy0", | |
1928 | "locked":false, | |
1929 | "removable":true, | |
d8aeeb31 | 1930 | "type":"unknown" |
82a56f0d LC |
1931 | }, |
1932 | { | |
1933 | "device":"sd0", | |
1934 | "locked":false, | |
1935 | "removable":true, | |
d8aeeb31 | 1936 | "type":"unknown" |
82a56f0d LC |
1937 | } |
1938 | ] | |
1939 | } | |
1940 | ||
82a56f0d LC |
1941 | query-blockstats |
1942 | ---------------- | |
1943 | ||
1944 | Show block device statistics. | |
1945 | ||
1946 | Each device statistic information is stored in a json-object and the returned | |
1947 | value is a json-array of all devices. | |
1948 | ||
1949 | Each json-object contain the following: | |
1950 | ||
1951 | - "device": device name (json-string) | |
1952 | - "stats": A json-object with the statistics information, it contains: | |
1953 | - "rd_bytes": bytes read (json-int) | |
1954 | - "wr_bytes": bytes written (json-int) | |
1955 | - "rd_operations": read operations (json-int) | |
1956 | - "wr_operations": write operations (json-int) | |
e8045d67 | 1957 | - "flush_operations": cache flush operations (json-int) |
c488c7f6 CH |
1958 | - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int) |
1959 | - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int) | |
1960 | - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int) | |
53d8f9d8 HR |
1961 | - "wr_highest_offset": The offset after the greatest byte written to the |
1962 | BlockDriverState since it has been opened (json-int) | |
f4564d53 PL |
1963 | - "rd_merged": number of read requests that have been merged into |
1964 | another request (json-int) | |
1965 | - "wr_merged": number of write requests that have been merged into | |
1966 | another request (json-int) | |
cb38fffb AG |
1967 | - "idle_time_ns": time since the last I/O operation, in |
1968 | nanoseconds. If the field is absent it means | |
1969 | that there haven't been any operations yet | |
1970 | (json-int, optional) | |
7ee12daf AG |
1971 | - "failed_rd_operations": number of failed read operations |
1972 | (json-int) | |
1973 | - "failed_wr_operations": number of failed write operations | |
1974 | (json-int) | |
1975 | - "failed_flush_operations": number of failed flush operations | |
1976 | (json-int) | |
1977 | - "invalid_rd_operations": number of invalid read operations | |
1978 | (json-int) | |
1979 | - "invalid_wr_operations": number of invalid write operations | |
1980 | (json-int) | |
1981 | - "invalid_flush_operations": number of invalid flush operations | |
1982 | (json-int) | |
362e9299 AG |
1983 | - "account_invalid": whether invalid operations are included in |
1984 | the last access statistics (json-bool) | |
1985 | - "account_failed": whether failed operations are included in the | |
1986 | latency and last access statistics | |
1987 | (json-bool) | |
979e9b03 AG |
1988 | - "timed_stats": A json-array containing statistics collected in |
1989 | specific intervals, with the following members: | |
1990 | - "interval_length": interval used for calculating the | |
1991 | statistics, in seconds (json-int) | |
1992 | - "min_rd_latency_ns": minimum latency of read operations in | |
1993 | the defined interval, in nanoseconds | |
1994 | (json-int) | |
1995 | - "min_wr_latency_ns": minimum latency of write operations in | |
1996 | the defined interval, in nanoseconds | |
1997 | (json-int) | |
1998 | - "min_flush_latency_ns": minimum latency of flush operations | |
1999 | in the defined interval, in | |
2000 | nanoseconds (json-int) | |
2001 | - "max_rd_latency_ns": maximum latency of read operations in | |
2002 | the defined interval, in nanoseconds | |
2003 | (json-int) | |
2004 | - "max_wr_latency_ns": maximum latency of write operations in | |
2005 | the defined interval, in nanoseconds | |
2006 | (json-int) | |
2007 | - "max_flush_latency_ns": maximum latency of flush operations | |
2008 | in the defined interval, in | |
2009 | nanoseconds (json-int) | |
2010 | - "avg_rd_latency_ns": average latency of read operations in | |
2011 | the defined interval, in nanoseconds | |
2012 | (json-int) | |
2013 | - "avg_wr_latency_ns": average latency of write operations in | |
2014 | the defined interval, in nanoseconds | |
2015 | (json-int) | |
2016 | - "avg_flush_latency_ns": average latency of flush operations | |
2017 | in the defined interval, in | |
2018 | nanoseconds (json-int) | |
96e4deda AG |
2019 | - "avg_rd_queue_depth": average number of pending read |
2020 | operations in the defined interval | |
2021 | (json-number) | |
2022 | - "avg_wr_queue_depth": average number of pending write | |
2023 | operations in the defined interval | |
2024 | (json-number). | |
82a56f0d LC |
2025 | - "parent": Contains recursively the statistics of the underlying |
2026 | protocol (e.g. the host file for a qcow2 image). If there is | |
2027 | no underlying protocol, this field is omitted | |
2028 | (json-object, optional) | |
2029 | ||
2030 | Example: | |
2031 | ||
2032 | -> { "execute": "query-blockstats" } | |
2033 | <- { | |
2034 | "return":[ | |
2035 | { | |
2036 | "device":"ide0-hd0", | |
2037 | "parent":{ | |
2038 | "stats":{ | |
2039 | "wr_highest_offset":3686448128, | |
2040 | "wr_bytes":9786368, | |
2041 | "wr_operations":751, | |
2042 | "rd_bytes":122567168, | |
2043 | "rd_operations":36772 | |
c488c7f6 CH |
2044 | "wr_total_times_ns":313253456 |
2045 | "rd_total_times_ns":3465673657 | |
2046 | "flush_total_times_ns":49653 | |
e8045d67 | 2047 | "flush_operations":61, |
f4564d53 | 2048 | "rd_merged":0, |
cb38fffb | 2049 | "wr_merged":0, |
362e9299 AG |
2050 | "idle_time_ns":2953431879, |
2051 | "account_invalid":true, | |
2052 | "account_failed":false | |
82a56f0d LC |
2053 | } |
2054 | }, | |
2055 | "stats":{ | |
2056 | "wr_highest_offset":2821110784, | |
2057 | "wr_bytes":9786368, | |
2058 | "wr_operations":692, | |
2059 | "rd_bytes":122739200, | |
2060 | "rd_operations":36604 | |
e8045d67 | 2061 | "flush_operations":51, |
c488c7f6 CH |
2062 | "wr_total_times_ns":313253456 |
2063 | "rd_total_times_ns":3465673657 | |
f4564d53 PL |
2064 | "flush_total_times_ns":49653, |
2065 | "rd_merged":0, | |
cb38fffb | 2066 | "wr_merged":0, |
362e9299 AG |
2067 | "idle_time_ns":2953431879, |
2068 | "account_invalid":true, | |
2069 | "account_failed":false | |
82a56f0d LC |
2070 | } |
2071 | }, | |
2072 | { | |
2073 | "device":"ide1-cd0", | |
2074 | "stats":{ | |
2075 | "wr_highest_offset":0, | |
2076 | "wr_bytes":0, | |
2077 | "wr_operations":0, | |
2078 | "rd_bytes":0, | |
2079 | "rd_operations":0 | |
e8045d67 | 2080 | "flush_operations":0, |
c488c7f6 CH |
2081 | "wr_total_times_ns":0 |
2082 | "rd_total_times_ns":0 | |
f4564d53 PL |
2083 | "flush_total_times_ns":0, |
2084 | "rd_merged":0, | |
362e9299 AG |
2085 | "wr_merged":0, |
2086 | "account_invalid":false, | |
2087 | "account_failed":false | |
82a56f0d LC |
2088 | } |
2089 | }, | |
2090 | { | |
2091 | "device":"floppy0", | |
2092 | "stats":{ | |
2093 | "wr_highest_offset":0, | |
2094 | "wr_bytes":0, | |
2095 | "wr_operations":0, | |
2096 | "rd_bytes":0, | |
2097 | "rd_operations":0 | |
e8045d67 | 2098 | "flush_operations":0, |
c488c7f6 CH |
2099 | "wr_total_times_ns":0 |
2100 | "rd_total_times_ns":0 | |
f4564d53 PL |
2101 | "flush_total_times_ns":0, |
2102 | "rd_merged":0, | |
362e9299 AG |
2103 | "wr_merged":0, |
2104 | "account_invalid":false, | |
2105 | "account_failed":false | |
82a56f0d LC |
2106 | } |
2107 | }, | |
2108 | { | |
2109 | "device":"sd0", | |
2110 | "stats":{ | |
2111 | "wr_highest_offset":0, | |
2112 | "wr_bytes":0, | |
2113 | "wr_operations":0, | |
2114 | "rd_bytes":0, | |
2115 | "rd_operations":0 | |
e8045d67 | 2116 | "flush_operations":0, |
c488c7f6 CH |
2117 | "wr_total_times_ns":0 |
2118 | "rd_total_times_ns":0 | |
f4564d53 PL |
2119 | "flush_total_times_ns":0, |
2120 | "rd_merged":0, | |
362e9299 AG |
2121 | "wr_merged":0, |
2122 | "account_invalid":false, | |
2123 | "account_failed":false | |
82a56f0d LC |
2124 | } |
2125 | } | |
2126 | ] | |
2127 | } | |
2128 | ||
82a56f0d LC |
2129 | query-cpus |
2130 | ---------- | |
2131 | ||
2132 | Show CPU information. | |
2133 | ||
2134 | Return a json-array. Each CPU is represented by a json-object, which contains: | |
2135 | ||
2136 | - "CPU": CPU index (json-int) | |
2137 | - "current": true if this is the current CPU, false otherwise (json-bool) | |
2138 | - "halted": true if the cpu is halted, false otherwise (json-bool) | |
58f88d4b | 2139 | - "qom_path": path to the CPU object in the QOM tree (json-str) |
86f4b687 EB |
2140 | - "arch": architecture of the cpu, which determines what additional |
2141 | keys will be present (json-str) | |
82a56f0d LC |
2142 | - Current program counter. The key's name depends on the architecture: |
2143 | "pc": i386/x86_64 (json-int) | |
2144 | "nip": PPC (json-int) | |
2145 | "pc" and "npc": sparc (json-int) | |
2146 | "PC": mips (json-int) | |
dc7a09cf | 2147 | - "thread_id": ID of the underlying host thread (json-int) |
82a56f0d LC |
2148 | |
2149 | Example: | |
2150 | ||
2151 | -> { "execute": "query-cpus" } | |
2152 | <- { | |
2153 | "return":[ | |
2154 | { | |
2155 | "CPU":0, | |
2156 | "current":true, | |
2157 | "halted":false, | |
58f88d4b | 2158 | "qom_path":"/machine/unattached/device[0]", |
86f4b687 | 2159 | "arch":"x86", |
58f88d4b | 2160 | "pc":3227107138, |
dc7a09cf | 2161 | "thread_id":3134 |
82a56f0d LC |
2162 | }, |
2163 | { | |
2164 | "CPU":1, | |
2165 | "current":false, | |
2166 | "halted":true, | |
58f88d4b | 2167 | "qom_path":"/machine/unattached/device[2]", |
86f4b687 | 2168 | "arch":"x86", |
58f88d4b | 2169 | "pc":7108165, |
dc7a09cf | 2170 | "thread_id":3135 |
82a56f0d LC |
2171 | } |
2172 | ] | |
2173 | } | |
2174 | ||
dc3dd0d2 SH |
2175 | query-iothreads |
2176 | --------------- | |
2177 | ||
2178 | Returns a list of information about each iothread. | |
2179 | ||
2180 | Note this list excludes the QEMU main loop thread, which is not declared | |
2181 | using the -object iothread command-line option. It is always the main thread | |
2182 | of the process. | |
2183 | ||
2184 | Return a json-array. Each iothread is represented by a json-object, which contains: | |
2185 | ||
2186 | - "id": name of iothread (json-str) | |
2187 | - "thread-id": ID of the underlying host thread (json-int) | |
2188 | ||
2189 | Example: | |
2190 | ||
2191 | -> { "execute": "query-iothreads" } | |
2192 | <- { | |
2193 | "return":[ | |
2194 | { | |
2195 | "id":"iothread0", | |
2196 | "thread-id":3134 | |
2197 | }, | |
2198 | { | |
2199 | "id":"iothread1", | |
2200 | "thread-id":3135 | |
2201 | } | |
2202 | ] | |
2203 | } | |
2204 | ||
82a56f0d LC |
2205 | query-pci |
2206 | --------- | |
2207 | ||
2208 | PCI buses and devices information. | |
2209 | ||
2210 | The returned value is a json-array of all buses. Each bus is represented by | |
2211 | a json-object, which has a key with a json-array of all PCI devices attached | |
2212 | to it. Each device is represented by a json-object. | |
2213 | ||
2214 | The bus json-object contains the following: | |
2215 | ||
2216 | - "bus": bus number (json-int) | |
2217 | - "devices": a json-array of json-objects, each json-object represents a | |
2218 | PCI device | |
2219 | ||
2220 | The PCI device json-object contains the following: | |
2221 | ||
2222 | - "bus": identical to the parent's bus number (json-int) | |
2223 | - "slot": slot number (json-int) | |
2224 | - "function": function number (json-int) | |
2225 | - "class_info": a json-object containing: | |
2226 | - "desc": device class description (json-string, optional) | |
2227 | - "class": device class number (json-int) | |
2228 | - "id": a json-object containing: | |
2229 | - "device": device ID (json-int) | |
2230 | - "vendor": vendor ID (json-int) | |
2231 | - "irq": device's IRQ if assigned (json-int, optional) | |
2232 | - "qdev_id": qdev id string (json-string) | |
2233 | - "pci_bridge": It's a json-object, only present if this device is a | |
2234 | PCI bridge, contains: | |
2235 | - "bus": bus number (json-int) | |
2236 | - "secondary": secondary bus number (json-int) | |
2237 | - "subordinate": subordinate bus number (json-int) | |
2238 | - "io_range": I/O memory range information, a json-object with the | |
2239 | following members: | |
2240 | - "base": base address, in bytes (json-int) | |
2241 | - "limit": limit address, in bytes (json-int) | |
2242 | - "memory_range": memory range information, a json-object with the | |
2243 | following members: | |
2244 | - "base": base address, in bytes (json-int) | |
2245 | - "limit": limit address, in bytes (json-int) | |
2246 | - "prefetchable_range": Prefetchable memory range information, a | |
2247 | json-object with the following members: | |
2248 | - "base": base address, in bytes (json-int) | |
2249 | - "limit": limit address, in bytes (json-int) | |
2250 | - "devices": a json-array of PCI devices if there's any attached, each | |
2251 | each element is represented by a json-object, which contains | |
2252 | the same members of the 'PCI device json-object' described | |
2253 | above (optional) | |
2254 | - "regions": a json-array of json-objects, each json-object represents a | |
2255 | memory region of this device | |
2256 | ||
2257 | The memory range json-object contains the following: | |
2258 | ||
2259 | - "base": base memory address (json-int) | |
2260 | - "limit": limit value (json-int) | |
2261 | ||
2262 | The region json-object can be an I/O region or a memory region, an I/O region | |
2263 | json-object contains the following: | |
2264 | ||
2265 | - "type": "io" (json-string, fixed) | |
2266 | - "bar": BAR number (json-int) | |
2267 | - "address": memory address (json-int) | |
2268 | - "size": memory size (json-int) | |
2269 | ||
2270 | A memory region json-object contains the following: | |
2271 | ||
2272 | - "type": "memory" (json-string, fixed) | |
2273 | - "bar": BAR number (json-int) | |
2274 | - "address": memory address (json-int) | |
2275 | - "size": memory size (json-int) | |
2276 | - "mem_type_64": true or false (json-bool) | |
2277 | - "prefetch": true or false (json-bool) | |
2278 | ||
2279 | Example: | |
2280 | ||
2281 | -> { "execute": "query-pci" } | |
2282 | <- { | |
2283 | "return":[ | |
2284 | { | |
2285 | "bus":0, | |
2286 | "devices":[ | |
2287 | { | |
2288 | "bus":0, | |
2289 | "qdev_id":"", | |
2290 | "slot":0, | |
2291 | "class_info":{ | |
2292 | "class":1536, | |
2293 | "desc":"Host bridge" | |
2294 | }, | |
2295 | "id":{ | |
2296 | "device":32902, | |
2297 | "vendor":4663 | |
2298 | }, | |
2299 | "function":0, | |
2300 | "regions":[ | |
bdf05133 | 2301 | |
82a56f0d LC |
2302 | ] |
2303 | }, | |
2304 | { | |
2305 | "bus":0, | |
2306 | "qdev_id":"", | |
2307 | "slot":1, | |
2308 | "class_info":{ | |
2309 | "class":1537, | |
2310 | "desc":"ISA bridge" | |
2311 | }, | |
2312 | "id":{ | |
2313 | "device":32902, | |
2314 | "vendor":28672 | |
2315 | }, | |
2316 | "function":0, | |
2317 | "regions":[ | |
bdf05133 | 2318 | |
82a56f0d LC |
2319 | ] |
2320 | }, | |
2321 | { | |
2322 | "bus":0, | |
2323 | "qdev_id":"", | |
2324 | "slot":1, | |
2325 | "class_info":{ | |
2326 | "class":257, | |
2327 | "desc":"IDE controller" | |
2328 | }, | |
2329 | "id":{ | |
2330 | "device":32902, | |
2331 | "vendor":28688 | |
2332 | }, | |
2333 | "function":1, | |
2334 | "regions":[ | |
2335 | { | |
2336 | "bar":4, | |
2337 | "size":16, | |
2338 | "address":49152, | |
2339 | "type":"io" | |
2340 | } | |
2341 | ] | |
2342 | }, | |
2343 | { | |
2344 | "bus":0, | |
2345 | "qdev_id":"", | |
2346 | "slot":2, | |
2347 | "class_info":{ | |
2348 | "class":768, | |
2349 | "desc":"VGA controller" | |
2350 | }, | |
2351 | "id":{ | |
2352 | "device":4115, | |
2353 | "vendor":184 | |
2354 | }, | |
2355 | "function":0, | |
2356 | "regions":[ | |
2357 | { | |
2358 | "prefetch":true, | |
2359 | "mem_type_64":false, | |
2360 | "bar":0, | |
2361 | "size":33554432, | |
2362 | "address":4026531840, | |
2363 | "type":"memory" | |
2364 | }, | |
2365 | { | |
2366 | "prefetch":false, | |
2367 | "mem_type_64":false, | |
2368 | "bar":1, | |
2369 | "size":4096, | |
2370 | "address":4060086272, | |
2371 | "type":"memory" | |
2372 | }, | |
2373 | { | |
2374 | "prefetch":false, | |
2375 | "mem_type_64":false, | |
2376 | "bar":6, | |
2377 | "size":65536, | |
2378 | "address":-1, | |
2379 | "type":"memory" | |
2380 | } | |
2381 | ] | |
2382 | }, | |
2383 | { | |
2384 | "bus":0, | |
2385 | "qdev_id":"", | |
2386 | "irq":11, | |
2387 | "slot":4, | |
2388 | "class_info":{ | |
2389 | "class":1280, | |
2390 | "desc":"RAM controller" | |
2391 | }, | |
2392 | "id":{ | |
2393 | "device":6900, | |
2394 | "vendor":4098 | |
2395 | }, | |
2396 | "function":0, | |
2397 | "regions":[ | |
2398 | { | |
2399 | "bar":0, | |
2400 | "size":32, | |
2401 | "address":49280, | |
2402 | "type":"io" | |
2403 | } | |
2404 | ] | |
2405 | } | |
2406 | ] | |
2407 | } | |
2408 | ] | |
2409 | } | |
2410 | ||
2411 | Note: This example has been shortened as the real response is too long. | |
2412 | ||
82a56f0d LC |
2413 | query-kvm |
2414 | --------- | |
2415 | ||
2416 | Show KVM information. | |
2417 | ||
2418 | Return a json-object with the following information: | |
2419 | ||
2420 | - "enabled": true if KVM support is enabled, false otherwise (json-bool) | |
2421 | - "present": true if QEMU has KVM support, false otherwise (json-bool) | |
2422 | ||
2423 | Example: | |
2424 | ||
2425 | -> { "execute": "query-kvm" } | |
2426 | <- { "return": { "enabled": true, "present": true } } | |
2427 | ||
82a56f0d LC |
2428 | query-status |
2429 | ------------ | |
2430 | ||
2431 | Return a json-object with the following information: | |
2432 | ||
2433 | - "running": true if the VM is running, or false if it is paused (json-bool) | |
2434 | - "singlestep": true if the VM is in single step mode, | |
2435 | false otherwise (json-bool) | |
9e37b9dc LC |
2436 | - "status": one of the following values (json-string) |
2437 | "debug" - QEMU is running on a debugger | |
2438 | "inmigrate" - guest is paused waiting for an incoming migration | |
2439 | "internal-error" - An internal error that prevents further guest | |
2440 | execution has occurred | |
2441 | "io-error" - the last IOP has failed and the device is configured | |
2442 | to pause on I/O errors | |
2443 | "paused" - guest has been paused via the 'stop' command | |
2444 | "postmigrate" - guest is paused following a successful 'migrate' | |
2445 | "prelaunch" - QEMU was started with -S and guest has not started | |
2446 | "finish-migrate" - guest is paused to finish the migration process | |
2447 | "restore-vm" - guest is paused to restore VM state | |
2448 | "running" - guest is actively running | |
2449 | "save-vm" - guest is paused to save the VM state | |
2450 | "shutdown" - guest is shut down (and -no-shutdown is in use) | |
2451 | "watchdog" - the watchdog action is configured to pause and | |
2452 | has been triggered | |
82a56f0d LC |
2453 | |
2454 | Example: | |
2455 | ||
2456 | -> { "execute": "query-status" } | |
9e37b9dc | 2457 | <- { "return": { "running": true, "singlestep": false, "status": "running" } } |
82a56f0d | 2458 | |
82a56f0d LC |
2459 | query-mice |
2460 | ---------- | |
2461 | ||
2462 | Show VM mice information. | |
2463 | ||
2464 | Each mouse is represented by a json-object, the returned value is a json-array | |
2465 | of all mice. | |
2466 | ||
2467 | The mouse json-object contains the following: | |
2468 | ||
2469 | - "name": mouse's name (json-string) | |
2470 | - "index": mouse's index (json-int) | |
2471 | - "current": true if this mouse is receiving events, false otherwise (json-bool) | |
2472 | - "absolute": true if the mouse generates absolute input events (json-bool) | |
2473 | ||
2474 | Example: | |
2475 | ||
2476 | -> { "execute": "query-mice" } | |
2477 | <- { | |
2478 | "return":[ | |
2479 | { | |
2480 | "name":"QEMU Microsoft Mouse", | |
2481 | "index":0, | |
2482 | "current":false, | |
2483 | "absolute":false | |
2484 | }, | |
2485 | { | |
2486 | "name":"QEMU PS/2 Mouse", | |
2487 | "index":1, | |
2488 | "current":true, | |
2489 | "absolute":true | |
2490 | } | |
2491 | ] | |
2492 | } | |
2493 | ||
82a56f0d LC |
2494 | query-vnc |
2495 | --------- | |
2496 | ||
2497 | Show VNC server information. | |
2498 | ||
2499 | Return a json-object with server information. Connected clients are returned | |
2500 | as a json-array of json-objects. | |
2501 | ||
2502 | The main json-object contains the following: | |
2503 | ||
2504 | - "enabled": true or false (json-bool) | |
2505 | - "host": server's IP address (json-string) | |
2506 | - "family": address family (json-string) | |
2507 | - Possible values: "ipv4", "ipv6", "unix", "unknown" | |
2508 | - "service": server's port number (json-string) | |
2509 | - "auth": authentication method (json-string) | |
2510 | - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight", | |
2511 | "tls", "ultra", "unknown", "vencrypt", "vencrypt", | |
2512 | "vencrypt+plain", "vencrypt+tls+none", | |
2513 | "vencrypt+tls+plain", "vencrypt+tls+sasl", | |
2514 | "vencrypt+tls+vnc", "vencrypt+x509+none", | |
2515 | "vencrypt+x509+plain", "vencrypt+x509+sasl", | |
2516 | "vencrypt+x509+vnc", "vnc" | |
2517 | - "clients": a json-array of all connected clients | |
2518 | ||
2519 | Clients are described by a json-object, each one contain the following: | |
2520 | ||
2521 | - "host": client's IP address (json-string) | |
2522 | - "family": address family (json-string) | |
2523 | - Possible values: "ipv4", "ipv6", "unix", "unknown" | |
2524 | - "service": client's port number (json-string) | |
2525 | - "x509_dname": TLS dname (json-string, optional) | |
2526 | - "sasl_username": SASL username (json-string, optional) | |
2527 | ||
2528 | Example: | |
2529 | ||
2530 | -> { "execute": "query-vnc" } | |
2531 | <- { | |
2532 | "return":{ | |
2533 | "enabled":true, | |
2534 | "host":"0.0.0.0", | |
2535 | "service":"50402", | |
2536 | "auth":"vnc", | |
2537 | "family":"ipv4", | |
2538 | "clients":[ | |
2539 | { | |
2540 | "host":"127.0.0.1", | |
2541 | "service":"50401", | |
2542 | "family":"ipv4" | |
2543 | } | |
2544 | ] | |
2545 | } | |
2546 | } | |
2547 | ||
cb42a870 GH |
2548 | query-spice |
2549 | ----------- | |
2550 | ||
2551 | Show SPICE server information. | |
2552 | ||
2553 | Return a json-object with server information. Connected clients are returned | |
2554 | as a json-array of json-objects. | |
2555 | ||
2556 | The main json-object contains the following: | |
2557 | ||
2558 | - "enabled": true or false (json-bool) | |
2559 | - "host": server's IP address (json-string) | |
2560 | - "port": server's port number (json-int, optional) | |
2561 | - "tls-port": server's port number (json-int, optional) | |
2562 | - "auth": authentication method (json-string) | |
2563 | - Possible values: "none", "spice" | |
2564 | - "channels": a json-array of all active channels clients | |
2565 | ||
2566 | Channels are described by a json-object, each one contain the following: | |
2567 | ||
2568 | - "host": client's IP address (json-string) | |
2569 | - "family": address family (json-string) | |
2570 | - Possible values: "ipv4", "ipv6", "unix", "unknown" | |
2571 | - "port": client's port number (json-string) | |
2572 | - "connection-id": spice connection id. All channels with the same id | |
2573 | belong to the same spice session (json-int) | |
2574 | - "channel-type": channel type. "1" is the main control channel, filter for | |
2575 | this one if you want track spice sessions only (json-int) | |
2576 | - "channel-id": channel id. Usually "0", might be different needed when | |
2577 | multiple channels of the same type exist, such as multiple | |
2578 | display channels in a multihead setup (json-int) | |
3599d46b | 2579 | - "tls": whether the channel is encrypted (json-bool) |
cb42a870 GH |
2580 | |
2581 | Example: | |
2582 | ||
2583 | -> { "execute": "query-spice" } | |
2584 | <- { | |
2585 | "return": { | |
2586 | "enabled": true, | |
2587 | "auth": "spice", | |
2588 | "port": 5920, | |
2589 | "tls-port": 5921, | |
2590 | "host": "0.0.0.0", | |
2591 | "channels": [ | |
2592 | { | |
2593 | "port": "54924", | |
2594 | "family": "ipv4", | |
2595 | "channel-type": 1, | |
2596 | "connection-id": 1804289383, | |
2597 | "host": "127.0.0.1", | |
2598 | "channel-id": 0, | |
2599 | "tls": true | |
2600 | }, | |
2601 | { | |
2602 | "port": "36710", | |
2603 | "family": "ipv4", | |
2604 | "channel-type": 4, | |
2605 | "connection-id": 1804289383, | |
2606 | "host": "127.0.0.1", | |
2607 | "channel-id": 0, | |
2608 | "tls": false | |
2609 | }, | |
2610 | [ ... more channels follow ... ] | |
2611 | ] | |
2612 | } | |
2613 | } | |
2614 | ||
82a56f0d LC |
2615 | query-name |
2616 | ---------- | |
2617 | ||
2618 | Show VM name. | |
2619 | ||
2620 | Return a json-object with the following information: | |
2621 | ||
2622 | - "name": VM's name (json-string, optional) | |
2623 | ||
2624 | Example: | |
2625 | ||
2626 | -> { "execute": "query-name" } | |
2627 | <- { "return": { "name": "qemu-name" } } | |
2628 | ||
82a56f0d LC |
2629 | query-uuid |
2630 | ---------- | |
2631 | ||
2632 | Show VM UUID. | |
2633 | ||
2634 | Return a json-object with the following information: | |
2635 | ||
2636 | - "UUID": Universally Unique Identifier (json-string) | |
2637 | ||
2638 | Example: | |
2639 | ||
2640 | -> { "execute": "query-uuid" } | |
2641 | <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } | |
2642 | ||
1f8f987d AK |
2643 | query-command-line-options |
2644 | -------------------------- | |
2645 | ||
2646 | Show command line option schema. | |
2647 | ||
2648 | Return a json-array of command line option schema for all options (or for | |
2649 | the given option), returning an error if the given option doesn't exist. | |
2650 | ||
2651 | Each array entry contains the following: | |
2652 | ||
2653 | - "option": option name (json-string) | |
2654 | - "parameters": a json-array describes all parameters of the option: | |
2655 | - "name": parameter name (json-string) | |
2656 | - "type": parameter type (one of 'string', 'boolean', 'number', | |
2657 | or 'size') | |
2658 | - "help": human readable description of the parameter | |
2659 | (json-string, optional) | |
e36af94f CL |
2660 | - "default": default value string for the parameter |
2661 | (json-string, optional) | |
1f8f987d AK |
2662 | |
2663 | Example: | |
2664 | ||
2665 | -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } } | |
2666 | <- { "return": [ | |
2667 | { | |
2668 | "parameters": [ | |
2669 | { | |
2670 | "name": "romfile", | |
2671 | "type": "string" | |
2672 | }, | |
2673 | { | |
2674 | "name": "bootindex", | |
2675 | "type": "number" | |
2676 | } | |
2677 | ], | |
2678 | "option": "option-rom" | |
2679 | } | |
2680 | ] | |
2681 | } | |
2682 | ||
82a56f0d LC |
2683 | query-migrate |
2684 | ------------- | |
2685 | ||
2686 | Migration status. | |
2687 | ||
2688 | Return a json-object. If migration is active there will be another json-object | |
2689 | with RAM migration status and if block migration is active another one with | |
2690 | block migration status. | |
2691 | ||
2692 | The main json-object contains the following: | |
2693 | ||
2694 | - "status": migration status (json-string) | |
3b695950 | 2695 | - Possible values: "setup", "active", "completed", "failed", "cancelled" |
7aa939af JQ |
2696 | - "total-time": total amount of ms since migration started. If |
2697 | migration has ended, it returns the total migration | |
817c6045 | 2698 | time (json-int) |
8f3067bd MH |
2699 | - "setup-time" amount of setup time in milliseconds _before_ the |
2700 | iterations begin but _after_ the QMP command is issued. | |
2701 | This is designed to provide an accounting of any activities | |
bdf05133 MAL |
2702 | (such as RDMA pinning) which may be expensive, but do not |
2703 | actually occur during the iterative migration rounds | |
8f3067bd | 2704 | themselves. (json-int) |
9c5a9fcf JQ |
2705 | - "downtime": only present when migration has finished correctly |
2706 | total amount in ms for downtime that happened (json-int) | |
2c52ddf1 JQ |
2707 | - "expected-downtime": only present while migration is active |
2708 | total amount in ms for downtime that was calculated on | |
817c6045 | 2709 | the last bitmap round (json-int) |
82a56f0d | 2710 | - "ram": only present if "status" is "active", it is a json-object with the |
817c6045 JQ |
2711 | following RAM information: |
2712 | - "transferred": amount transferred in bytes (json-int) | |
2713 | - "remaining": amount remaining to transfer in bytes (json-int) | |
2714 | - "total": total amount of memory in bytes (json-int) | |
2715 | - "duplicate": number of pages filled entirely with the same | |
2716 | byte (json-int) | |
2717 | These are sent over the wire much more efficiently. | |
f1c72795 | 2718 | - "skipped": number of skipped zero pages (json-int) |
805a2505 | 2719 | - "normal" : number of whole pages transferred. I.e. they |
817c6045 JQ |
2720 | were not sent as duplicate or xbzrle pages (json-int) |
2721 | - "normal-bytes" : number of bytes transferred in whole | |
2722 | pages. This is just normal pages times size of one page, | |
2723 | but this way upper levels don't need to care about page | |
2724 | size (json-int) | |
58570ed8 | 2725 | - "dirty-sync-count": times that dirty ram was synchronized (json-int) |
82a56f0d | 2726 | - "disk": only present if "status" is "active" and it is a block migration, |
817c6045 JQ |
2727 | it is a json-object with the following disk information: |
2728 | - "transferred": amount transferred in bytes (json-int) | |
2729 | - "remaining": amount remaining to transfer in bytes json-int) | |
2730 | - "total": total disk size in bytes (json-int) | |
f36d55af OW |
2731 | - "xbzrle-cache": only present if XBZRLE is active. |
2732 | It is a json-object with the following XBZRLE information: | |
817c6045 JQ |
2733 | - "cache-size": XBZRLE cache size in bytes |
2734 | - "bytes": number of bytes transferred for XBZRLE compressed pages | |
f36d55af | 2735 | - "pages": number of XBZRLE compressed pages |
817c6045 | 2736 | - "cache-miss": number of XBRZRLE page cache misses |
8bc39233 | 2737 | - "cache-miss-rate": rate of XBRZRLE page cache misses |
817c6045 JQ |
2738 | - "overflow": number of times XBZRLE overflows. This means |
2739 | that the XBZRLE encoding was bigger than just sent the | |
2740 | whole page, and then we sent the whole page instead (as as | |
2741 | normal page). | |
2742 | ||
82a56f0d LC |
2743 | Examples: |
2744 | ||
2745 | 1. Before the first migration | |
2746 | ||
2747 | -> { "execute": "query-migrate" } | |
2748 | <- { "return": {} } | |
2749 | ||
2750 | 2. Migration is done and has succeeded | |
2751 | ||
2752 | -> { "execute": "query-migrate" } | |
004d4c10 OW |
2753 | <- { "return": { |
2754 | "status": "completed", | |
2755 | "ram":{ | |
2756 | "transferred":123, | |
2757 | "remaining":123, | |
2758 | "total":246, | |
2759 | "total-time":12345, | |
8f3067bd | 2760 | "setup-time":12345, |
9c5a9fcf | 2761 | "downtime":12345, |
004d4c10 OW |
2762 | "duplicate":123, |
2763 | "normal":123, | |
58570ed8 C |
2764 | "normal-bytes":123456, |
2765 | "dirty-sync-count":15 | |
004d4c10 OW |
2766 | } |
2767 | } | |
2768 | } | |
82a56f0d LC |
2769 | |
2770 | 3. Migration is done and has failed | |
2771 | ||
2772 | -> { "execute": "query-migrate" } | |
2773 | <- { "return": { "status": "failed" } } | |
2774 | ||
2775 | 4. Migration is being performed and is not a block migration: | |
2776 | ||
2777 | -> { "execute": "query-migrate" } | |
2778 | <- { | |
2779 | "return":{ | |
2780 | "status":"active", | |
2781 | "ram":{ | |
2782 | "transferred":123, | |
2783 | "remaining":123, | |
62d4e3fe | 2784 | "total":246, |
004d4c10 | 2785 | "total-time":12345, |
8f3067bd | 2786 | "setup-time":12345, |
2c52ddf1 | 2787 | "expected-downtime":12345, |
004d4c10 OW |
2788 | "duplicate":123, |
2789 | "normal":123, | |
58570ed8 C |
2790 | "normal-bytes":123456, |
2791 | "dirty-sync-count":15 | |
82a56f0d LC |
2792 | } |
2793 | } | |
2794 | } | |
2795 | ||
2796 | 5. Migration is being performed and is a block migration: | |
2797 | ||
2798 | -> { "execute": "query-migrate" } | |
2799 | <- { | |
2800 | "return":{ | |
2801 | "status":"active", | |
2802 | "ram":{ | |
2803 | "total":1057024, | |
2804 | "remaining":1053304, | |
62d4e3fe | 2805 | "transferred":3720, |
004d4c10 | 2806 | "total-time":12345, |
8f3067bd | 2807 | "setup-time":12345, |
2c52ddf1 | 2808 | "expected-downtime":12345, |
004d4c10 OW |
2809 | "duplicate":123, |
2810 | "normal":123, | |
58570ed8 C |
2811 | "normal-bytes":123456, |
2812 | "dirty-sync-count":15 | |
82a56f0d LC |
2813 | }, |
2814 | "disk":{ | |
2815 | "total":20971520, | |
2816 | "remaining":20880384, | |
2817 | "transferred":91136 | |
2818 | } | |
2819 | } | |
2820 | } | |
2821 | ||
f36d55af OW |
2822 | 6. Migration is being performed and XBZRLE is active: |
2823 | ||
2824 | -> { "execute": "query-migrate" } | |
2825 | <- { | |
2826 | "return":{ | |
2827 | "status":"active", | |
2828 | "capabilities" : [ { "capability": "xbzrle", "state" : true } ], | |
2829 | "ram":{ | |
2830 | "total":1057024, | |
2831 | "remaining":1053304, | |
2832 | "transferred":3720, | |
2833 | "total-time":12345, | |
8f3067bd | 2834 | "setup-time":12345, |
2c52ddf1 | 2835 | "expected-downtime":12345, |
f36d55af OW |
2836 | "duplicate":10, |
2837 | "normal":3333, | |
58570ed8 C |
2838 | "normal-bytes":3412992, |
2839 | "dirty-sync-count":15 | |
f36d55af OW |
2840 | }, |
2841 | "xbzrle-cache":{ | |
2842 | "cache-size":67108864, | |
2843 | "bytes":20971520, | |
2844 | "pages":2444343, | |
2845 | "cache-miss":2244, | |
8bc39233 | 2846 | "cache-miss-rate":0.123, |
f36d55af OW |
2847 | "overflow":34434 |
2848 | } | |
2849 | } | |
2850 | } | |
2851 | ||
00458433 | 2852 | migrate-set-capabilities |
817c6045 | 2853 | ------------------------ |
00458433 OW |
2854 | |
2855 | Enable/Disable migration capabilities | |
2856 | ||
817c6045 | 2857 | - "xbzrle": XBZRLE support |
d6d69731 HZ |
2858 | - "rdma-pin-all": pin all pages when using RDMA during migration |
2859 | - "auto-converge": throttle down guest to help convergence of migration | |
2860 | - "zero-blocks": compress zero blocks during block migration | |
164f59e8 | 2861 | - "compress": use multiple compression threads to accelerate live migration |
72e72e1a | 2862 | - "events": generate events for each migration state change |
32c3db5b | 2863 | - "postcopy-ram": postcopy mode for live migration |
00458433 OW |
2864 | |
2865 | Arguments: | |
2866 | ||
2867 | Example: | |
2868 | ||
2869 | -> { "execute": "migrate-set-capabilities" , "arguments": | |
2870 | { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } | |
2871 | ||
bbf6da32 | 2872 | query-migrate-capabilities |
817c6045 | 2873 | -------------------------- |
bbf6da32 OW |
2874 | |
2875 | Query current migration capabilities | |
2876 | ||
2877 | - "capabilities": migration capabilities state | |
2878 | - "xbzrle" : XBZRLE state (json-bool) | |
d6d69731 HZ |
2879 | - "rdma-pin-all" : RDMA Pin Page state (json-bool) |
2880 | - "auto-converge" : Auto Converge state (json-bool) | |
2881 | - "zero-blocks" : Zero Blocks state (json-bool) | |
164f59e8 HZ |
2882 | - "compress": Multiple compression threads state (json-bool) |
2883 | - "events": Migration state change event state (json-bool) | |
32c3db5b | 2884 | - "postcopy-ram": postcopy ram state (json-bool) |
bbf6da32 OW |
2885 | |
2886 | Arguments: | |
2887 | ||
2888 | Example: | |
2889 | ||
2890 | -> { "execute": "query-migrate-capabilities" } | |
164f59e8 HZ |
2891 | <- {"return": [ |
2892 | {"state": false, "capability": "xbzrle"}, | |
2893 | {"state": false, "capability": "rdma-pin-all"}, | |
2894 | {"state": false, "capability": "auto-converge"}, | |
2895 | {"state": false, "capability": "zero-blocks"}, | |
2896 | {"state": false, "capability": "compress"}, | |
2897 | {"state": true, "capability": "events"}, | |
32c3db5b | 2898 | {"state": false, "capability": "postcopy-ram"} |
164f59e8 | 2899 | ]} |
dbca1b37 | 2900 | |
85de8323 LL |
2901 | migrate-set-parameters |
2902 | ---------------------- | |
2903 | ||
2904 | Set migration parameters | |
2905 | ||
2906 | - "compress-level": set compression level during migration (json-int) | |
2907 | - "compress-threads": set compression thread count for migration (json-int) | |
2908 | - "decompress-threads": set decompression thread count for migration (json-int) | |
d85a31d1 JH |
2909 | - "cpu-throttle-initial": set initial percentage of time guest cpus are |
2910 | throttled for auto-converge (json-int) | |
2911 | - "cpu-throttle-increment": set throttle increasing percentage for | |
2912 | auto-converge (json-int) | |
2ff30257 AA |
2913 | - "max-bandwidth": set maximum speed for migrations (in bytes/sec) (json-int) |
2914 | - "downtime-limit": set maximum tolerated downtime (in milliseconds) for | |
2915 | migrations (json-int) | |
85de8323 LL |
2916 | Arguments: |
2917 | ||
2918 | Example: | |
2919 | ||
2920 | -> { "execute": "migrate-set-parameters" , "arguments": | |
2921 | { "compress-level": 1 } } | |
2922 | ||
85de8323 LL |
2923 | query-migrate-parameters |
2924 | ------------------------ | |
2925 | ||
2926 | Query current migration parameters | |
2927 | ||
2928 | - "parameters": migration parameters value | |
2929 | - "compress-level" : compression level value (json-int) | |
2930 | - "compress-threads" : compression thread count value (json-int) | |
2931 | - "decompress-threads" : decompression thread count value (json-int) | |
d85a31d1 JH |
2932 | - "cpu-throttle-initial" : initial percentage of time guest cpus are |
2933 | throttled (json-int) | |
2934 | - "cpu-throttle-increment" : throttle increasing percentage for | |
2935 | auto-converge (json-int) | |
2ff30257 AA |
2936 | - "max-bandwidth" : maximium migration speed in bytes per second |
2937 | (json-int) | |
2938 | - "downtime-limit" : maximum tolerated downtime of migration in | |
2939 | milliseconds (json-int) | |
85de8323 LL |
2940 | Arguments: |
2941 | ||
2942 | Example: | |
2943 | ||
2944 | -> { "execute": "query-migrate-parameters" } | |
2945 | <- { | |
2946 | "return": { | |
9c994a97 | 2947 | "decompress-threads": 2, |
d85a31d1 | 2948 | "cpu-throttle-increment": 10, |
9c994a97 HZ |
2949 | "compress-threads": 8, |
2950 | "compress-level": 1, | |
2ff30257 AA |
2951 | "cpu-throttle-initial": 20, |
2952 | "max-bandwidth": 33554432, | |
2953 | "downtime-limit": 300 | |
85de8323 LL |
2954 | } |
2955 | } | |
2956 | ||
82a56f0d LC |
2957 | query-balloon |
2958 | ------------- | |
2959 | ||
2960 | Show balloon information. | |
2961 | ||
2962 | Make an asynchronous request for balloon info. When the request completes a | |
2963 | json-object will be returned containing the following data: | |
2964 | ||
2965 | - "actual": current balloon value in bytes (json-int) | |
82a56f0d LC |
2966 | |
2967 | Example: | |
2968 | ||
2969 | -> { "execute": "query-balloon" } | |
2970 | <- { | |
2971 | "return":{ | |
2972 | "actual":1073741824, | |
82a56f0d LC |
2973 | } |
2974 | } | |
2975 | ||
28c4fa32 CB |
2976 | query-tpm |
2977 | --------- | |
2978 | ||
2979 | Return information about the TPM device. | |
2980 | ||
2981 | Arguments: None | |
2982 | ||
2983 | Example: | |
2984 | ||
2985 | -> { "execute": "query-tpm" } | |
2986 | <- { "return": | |
2987 | [ | |
2988 | { "model": "tpm-tis", | |
2989 | "options": | |
2990 | { "type": "passthrough", | |
2991 | "data": | |
2992 | { "cancel-path": "/sys/class/misc/tpm0/device/cancel", | |
2993 | "path": "/dev/tpm0" | |
2994 | } | |
2995 | }, | |
2996 | "id": "tpm0" | |
2997 | } | |
2998 | ] | |
2999 | } | |
3000 | ||
28c4fa32 CB |
3001 | query-tpm-models |
3002 | ---------------- | |
3003 | ||
3004 | Return a list of supported TPM models. | |
3005 | ||
3006 | Arguments: None | |
3007 | ||
3008 | Example: | |
3009 | ||
3010 | -> { "execute": "query-tpm-models" } | |
3011 | <- { "return": [ "tpm-tis" ] } | |
3012 | ||
28c4fa32 CB |
3013 | query-tpm-types |
3014 | --------------- | |
3015 | ||
3016 | Return a list of supported TPM types. | |
3017 | ||
3018 | Arguments: None | |
3019 | ||
3020 | Example: | |
3021 | ||
3022 | -> { "execute": "query-tpm-types" } | |
3023 | <- { "return": [ "passthrough" ] } | |
3024 | ||
f1a1a356 GH |
3025 | chardev-add |
3026 | ---------------- | |
3027 | ||
3028 | Add a chardev. | |
3029 | ||
3030 | Arguments: | |
3031 | ||
3032 | - "id": the chardev's ID, must be unique (json-string) | |
3033 | - "backend": chardev backend type + parameters | |
3034 | ||
ffbdbe59 | 3035 | Examples: |
f1a1a356 GH |
3036 | |
3037 | -> { "execute" : "chardev-add", | |
3038 | "arguments" : { "id" : "foo", | |
3039 | "backend" : { "type" : "null", "data" : {} } } } | |
3040 | <- { "return": {} } | |
3041 | ||
ffbdbe59 GH |
3042 | -> { "execute" : "chardev-add", |
3043 | "arguments" : { "id" : "bar", | |
3044 | "backend" : { "type" : "file", | |
3045 | "data" : { "out" : "/tmp/bar.log" } } } } | |
3046 | <- { "return": {} } | |
3047 | ||
0a1a7fab GH |
3048 | -> { "execute" : "chardev-add", |
3049 | "arguments" : { "id" : "baz", | |
3050 | "backend" : { "type" : "pty", "data" : {} } } } | |
3051 | <- { "return": { "pty" : "/dev/pty/42" } } | |
3052 | ||
f1a1a356 GH |
3053 | chardev-remove |
3054 | -------------- | |
3055 | ||
3056 | Remove a chardev. | |
3057 | ||
3058 | Arguments: | |
3059 | ||
3060 | - "id": the chardev's ID, must exist and not be in use (json-string) | |
3061 | ||
3062 | Example: | |
3063 | ||
3064 | -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } | |
3065 | <- { "return": {} } | |
3066 | ||
b1be4280 AK |
3067 | query-rx-filter |
3068 | --------------- | |
3069 | ||
3070 | Show rx-filter information. | |
3071 | ||
3072 | Returns a json-array of rx-filter information for all NICs (or for the | |
3073 | given NIC), returning an error if the given NIC doesn't exist, or | |
3074 | given NIC doesn't support rx-filter querying, or given net client | |
3075 | isn't a NIC. | |
3076 | ||
3077 | The query will clear the event notification flag of each NIC, then qemu | |
3078 | will start to emit event to QMP monitor. | |
3079 | ||
3080 | Each array entry contains the following: | |
3081 | ||
3082 | - "name": net client name (json-string) | |
3083 | - "promiscuous": promiscuous mode is enabled (json-bool) | |
3084 | - "multicast": multicast receive state (one of 'normal', 'none', 'all') | |
3085 | - "unicast": unicast receive state (one of 'normal', 'none', 'all') | |
f7bc8ef8 | 3086 | - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0) |
b1be4280 AK |
3087 | - "broadcast-allowed": allow to receive broadcast (json-bool) |
3088 | - "multicast-overflow": multicast table is overflowed (json-bool) | |
3089 | - "unicast-overflow": unicast table is overflowed (json-bool) | |
3090 | - "main-mac": main macaddr string (json-string) | |
3091 | - "vlan-table": a json-array of active vlan id | |
3092 | - "unicast-table": a json-array of unicast macaddr string | |
3093 | - "multicast-table": a json-array of multicast macaddr string | |
3094 | ||
3095 | Example: | |
3096 | ||
3097 | -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } | |
3098 | <- { "return": [ | |
3099 | { | |
3100 | "promiscuous": true, | |
3101 | "name": "vnet0", | |
3102 | "main-mac": "52:54:00:12:34:56", | |
3103 | "unicast": "normal", | |
f7bc8ef8 | 3104 | "vlan": "normal", |
b1be4280 AK |
3105 | "vlan-table": [ |
3106 | 4, | |
3107 | 0 | |
3108 | ], | |
3109 | "unicast-table": [ | |
3110 | ], | |
3111 | "multicast": "normal", | |
3112 | "multicast-overflow": false, | |
3113 | "unicast-overflow": false, | |
3114 | "multicast-table": [ | |
3115 | "01:00:5e:00:00:01", | |
3116 | "33:33:00:00:00:01", | |
3117 | "33:33:ff:12:34:56" | |
3118 | ], | |
3119 | "broadcast-allowed": false | |
3120 | } | |
3121 | ] | |
3122 | } | |
3123 | ||
d26c9a15 KW |
3124 | blockdev-add |
3125 | ------------ | |
3126 | ||
3127 | Add a block device. | |
3128 | ||
da2cf4e8 | 3129 | This command is still a work in progress. It doesn't support all |
81b936ae AG |
3130 | block drivers among other things. Stay away from it unless you want |
3131 | to help with its development. | |
da2cf4e8 | 3132 | |
0153d2f5 | 3133 | For the arguments, see the QAPI schema documentation of BlockdevOptions. |
d26c9a15 KW |
3134 | |
3135 | Example (1): | |
3136 | ||
3137 | -> { "execute": "blockdev-add", | |
0153d2f5 KW |
3138 | "arguments": { "driver": "qcow2", |
3139 | "file": { "driver": "file", | |
3140 | "filename": "test.qcow2" } } } | |
d26c9a15 KW |
3141 | <- { "return": {} } |
3142 | ||
3143 | Example (2): | |
3144 | ||
3145 | -> { "execute": "blockdev-add", | |
3146 | "arguments": { | |
0153d2f5 KW |
3147 | "driver": "qcow2", |
3148 | "node-name": "my_disk", | |
3149 | "discard": "unmap", | |
3150 | "cache": { | |
3151 | "direct": true, | |
3152 | "writeback": true | |
3153 | }, | |
3154 | "file": { | |
3155 | "driver": "file", | |
3156 | "filename": "/tmp/test.qcow2" | |
3157 | }, | |
3158 | "backing": { | |
3159 | "driver": "raw", | |
3160 | "file": { | |
3161 | "driver": "file", | |
3162 | "filename": "/dev/fdset/4" | |
3163 | } | |
d26c9a15 KW |
3164 | } |
3165 | } | |
3166 | } | |
3167 | ||
3168 | <- { "return": {} } | |
3169 | ||
81b936ae AG |
3170 | x-blockdev-del |
3171 | ------------ | |
3172 | Since 2.5 | |
3173 | ||
9ec8873e KW |
3174 | Deletes a block device that has been added using blockdev-add. |
3175 | The command will fail if the node is attached to a device or is | |
3176 | otherwise being used. | |
81b936ae AG |
3177 | |
3178 | This command is still a work in progress and is considered | |
3179 | experimental. Stay away from it unless you want to help with its | |
3180 | development. | |
3181 | ||
3182 | Arguments: | |
3183 | ||
9ec8873e | 3184 | - "node-name": Name of the graph node to delete (json-string) |
81b936ae AG |
3185 | |
3186 | Example: | |
3187 | ||
3188 | -> { "execute": "blockdev-add", | |
3189 | "arguments": { | |
0153d2f5 KW |
3190 | "driver": "qcow2", |
3191 | "node-name": "node0", | |
3192 | "file": { | |
3193 | "driver": "file", | |
3194 | "filename": "test.qcow2" | |
81b936ae AG |
3195 | } |
3196 | } | |
3197 | } | |
3198 | ||
3199 | <- { "return": {} } | |
3200 | ||
3201 | -> { "execute": "x-blockdev-del", | |
9ec8873e | 3202 | "arguments": { "node-name": "node0" } |
81b936ae AG |
3203 | } |
3204 | <- { "return": {} } | |
3205 | ||
7d8a9f71 HR |
3206 | blockdev-open-tray |
3207 | ------------------ | |
3208 | ||
3209 | Opens a block device's tray. If there is a block driver state tree inserted as a | |
3210 | medium, it will become inaccessible to the guest (but it will remain associated | |
3211 | to the block device, so closing the tray will make it accessible again). | |
3212 | ||
3213 | If the tray was already open before, this will be a no-op. | |
3214 | ||
3215 | Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in | |
3216 | which no such event will be generated, these include: | |
3217 | - if the guest has locked the tray, @force is false and the guest does not | |
3218 | respond to the eject request | |
3219 | - if the BlockBackend denoted by @device does not have a guest device attached | |
3220 | to it | |
3221 | - if the guest device does not have an actual tray and is empty, for instance | |
3222 | for floppy disk drives | |
3223 | ||
3224 | Arguments: | |
3225 | ||
b33945cf KW |
3226 | - "device": block device name (deprecated, use @id instead) |
3227 | (json-string, optional) | |
3228 | - "id": the name or QOM path of the guest device (json-string, optional) | |
7d8a9f71 HR |
3229 | - "force": if false (the default), an eject request will be sent to the guest if |
3230 | it has locked the tray (and the tray will not be opened immediately); | |
3231 | if true, the tray will be opened regardless of whether it is locked | |
3232 | (json-bool, optional) | |
3233 | ||
3234 | Example: | |
3235 | ||
3236 | -> { "execute": "blockdev-open-tray", | |
b33945cf | 3237 | "arguments": { "id": "ide0-1-0" } } |
7d8a9f71 HR |
3238 | |
3239 | <- { "timestamp": { "seconds": 1418751016, | |
3240 | "microseconds": 716996 }, | |
3241 | "event": "DEVICE_TRAY_MOVED", | |
3242 | "data": { "device": "ide1-cd0", | |
2d76e724 | 3243 | "id": "ide0-1-0", |
7d8a9f71 HR |
3244 | "tray-open": true } } |
3245 | ||
3246 | <- { "return": {} } | |
3247 | ||
abaaf59d HR |
3248 | blockdev-close-tray |
3249 | ------------------- | |
3250 | ||
3251 | Closes a block device's tray. If there is a block driver state tree associated | |
3252 | with the block device (which is currently ejected), that tree will be loaded as | |
3253 | the medium. | |
3254 | ||
3255 | If the tray was already closed before, this will be a no-op. | |
3256 | ||
3257 | Arguments: | |
3258 | ||
b33945cf KW |
3259 | - "device": block device name (deprecated, use @id instead) |
3260 | (json-string, optional) | |
3261 | - "id": the name or QOM path of the guest device (json-string, optional) | |
abaaf59d HR |
3262 | |
3263 | Example: | |
3264 | ||
3265 | -> { "execute": "blockdev-close-tray", | |
b33945cf | 3266 | "arguments": { "id": "ide0-1-0" } } |
abaaf59d HR |
3267 | |
3268 | <- { "timestamp": { "seconds": 1418751345, | |
3269 | "microseconds": 272147 }, | |
3270 | "event": "DEVICE_TRAY_MOVED", | |
3271 | "data": { "device": "ide1-cd0", | |
2d76e724 | 3272 | "id": "ide0-1-0", |
abaaf59d HR |
3273 | "tray-open": false } } |
3274 | ||
3275 | <- { "return": {} } | |
3276 | ||
6e0abc25 HR |
3277 | x-blockdev-remove-medium |
3278 | ------------------------ | |
2814f672 HR |
3279 | |
3280 | Removes a medium (a block driver state tree) from a block device. That block | |
3281 | device's tray must currently be open (unless there is no attached guest device). | |
3282 | ||
3283 | If the tray is open and there is no medium inserted, this will be a no-op. | |
3284 | ||
6e0abc25 HR |
3285 | This command is still a work in progress and is considered experimental. |
3286 | Stay away from it unless you want to help with its development. | |
3287 | ||
2814f672 HR |
3288 | Arguments: |
3289 | ||
00949bab KW |
3290 | - "device": block device name (deprecated, use @id instead) |
3291 | (json-string, optional) | |
3292 | - "id": the name or QOM path of the guest device (json-string, optional) | |
2814f672 HR |
3293 | |
3294 | Example: | |
3295 | ||
6e0abc25 | 3296 | -> { "execute": "x-blockdev-remove-medium", |
00949bab | 3297 | "arguments": { "id": "ide0-1-0" } } |
2814f672 HR |
3298 | |
3299 | <- { "error": { "class": "GenericError", | |
00949bab | 3300 | "desc": "Tray of device 'ide0-1-0' is not open" } } |
2814f672 HR |
3301 | |
3302 | -> { "execute": "blockdev-open-tray", | |
00949bab | 3303 | "arguments": { "id": "ide0-1-0" } } |
2814f672 HR |
3304 | |
3305 | <- { "timestamp": { "seconds": 1418751627, | |
3306 | "microseconds": 549958 }, | |
3307 | "event": "DEVICE_TRAY_MOVED", | |
3308 | "data": { "device": "ide1-cd0", | |
2d76e724 | 3309 | "id": "ide0-1-0", |
2814f672 HR |
3310 | "tray-open": true } } |
3311 | ||
3312 | <- { "return": {} } | |
3313 | ||
6e0abc25 | 3314 | -> { "execute": "x-blockdev-remove-medium", |
00949bab | 3315 | "arguments": { "device": "ide0-1-0" } } |
2814f672 HR |
3316 | |
3317 | <- { "return": {} } | |
3318 | ||
6e0abc25 HR |
3319 | x-blockdev-insert-medium |
3320 | ------------------------ | |
d1299882 HR |
3321 | |
3322 | Inserts a medium (a block driver state tree) into a block device. That block | |
3323 | device's tray must currently be open (unless there is no attached guest device) | |
3324 | and there must be no medium inserted already. | |
3325 | ||
6e0abc25 HR |
3326 | This command is still a work in progress and is considered experimental. |
3327 | Stay away from it unless you want to help with its development. | |
3328 | ||
d1299882 HR |
3329 | Arguments: |
3330 | ||
716df217 KW |
3331 | - "device": block device name (deprecated, use @id instead) |
3332 | (json-string, optional) | |
3333 | - "id": the name or QOM path of the guest device (json-string, optional) | |
d1299882 HR |
3334 | - "node-name": root node of the BDS tree to insert into the block device |
3335 | ||
3336 | Example: | |
3337 | ||
3338 | -> { "execute": "blockdev-add", | |
0153d2f5 KW |
3339 | "arguments": { { "node-name": "node0", |
3340 | "driver": "raw", | |
3341 | "file": { "driver": "file", | |
3342 | "filename": "fedora.iso" } } } | |
d1299882 HR |
3343 | |
3344 | <- { "return": {} } | |
3345 | ||
6e0abc25 | 3346 | -> { "execute": "x-blockdev-insert-medium", |
716df217 | 3347 | "arguments": { "id": "ide0-1-0", |
d1299882 HR |
3348 | "node-name": "node0" } } |
3349 | ||
3350 | <- { "return": {} } | |
3351 | ||
7f821597 WC |
3352 | x-blockdev-change |
3353 | ----------------- | |
3354 | ||
3355 | Dynamically reconfigure the block driver state graph. It can be used | |
3356 | to add, remove, insert or replace a graph node. Currently only the | |
3357 | Quorum driver implements this feature to add or remove its child. This | |
3358 | is useful to fix a broken quorum child. | |
3359 | ||
3360 | If @node is specified, it will be inserted under @parent. @child | |
3361 | may not be specified in this case. If both @parent and @child are | |
3362 | specified but @node is not, @child will be detached from @parent. | |
3363 | ||
3364 | Arguments: | |
3365 | - "parent": the id or name of the parent node (json-string) | |
3366 | - "child": the name of a child under the given parent node (json-string, optional) | |
3367 | - "node": the name of the node that will be added (json-string, optional) | |
3368 | ||
3369 | Note: this command is experimental, and not a stable API. It doesn't | |
3370 | support all kinds of operations, all kinds of children, nor all block | |
3371 | drivers. | |
3372 | ||
3373 | Warning: The data in a new quorum child MUST be consistent with that of | |
3374 | the rest of the array. | |
3375 | ||
3376 | Example: | |
3377 | ||
3378 | Add a new node to a quorum | |
3379 | -> { "execute": "blockdev-add", | |
0153d2f5 KW |
3380 | "arguments": { "driver": "raw", |
3381 | "node-name": "new_node", | |
3382 | "file": { "driver": "file", | |
3383 | "filename": "test.raw" } } } | |
7f821597 WC |
3384 | <- { "return": {} } |
3385 | -> { "execute": "x-blockdev-change", | |
3386 | "arguments": { "parent": "disk1", | |
3387 | "node": "new_node" } } | |
3388 | <- { "return": {} } | |
3389 | ||
3390 | Delete a quorum's node | |
3391 | -> { "execute": "x-blockdev-change", | |
3392 | "arguments": { "parent": "disk1", | |
3393 | "child": "children.1" } } | |
3394 | <- { "return": {} } | |
3395 | ||
bdf05133 MAL |
3396 | query-named-block-nodes |
3397 | ----------------------- | |
c13163fb BC |
3398 | |
3399 | Return a list of BlockDeviceInfo for all the named block driver nodes | |
3400 | ||
3401 | Example: | |
3402 | ||
3403 | -> { "execute": "query-named-block-nodes" } | |
3404 | <- { "return": [ { "ro":false, | |
3405 | "drv":"qcow2", | |
3406 | "encrypted":false, | |
3407 | "file":"disks/test.qcow2", | |
3408 | "node-name": "my-node", | |
3409 | "backing_file_depth":1, | |
3410 | "bps":1000000, | |
3411 | "bps_rd":0, | |
3412 | "bps_wr":0, | |
3413 | "iops":1000000, | |
3414 | "iops_rd":0, | |
3415 | "iops_wr":0, | |
3416 | "bps_max": 8000000, | |
3417 | "bps_rd_max": 0, | |
3418 | "bps_wr_max": 0, | |
3419 | "iops_max": 0, | |
3420 | "iops_rd_max": 0, | |
3421 | "iops_wr_max": 0, | |
3422 | "iops_size": 0, | |
e2462113 | 3423 | "write_threshold": 0, |
c13163fb BC |
3424 | "image":{ |
3425 | "filename":"disks/test.qcow2", | |
3426 | "format":"qcow2", | |
3427 | "virtual-size":2048000, | |
3428 | "backing_file":"base.qcow2", | |
3429 | "full-backing-filename":"disks/base.qcow2", | |
5403432f | 3430 | "backing-filename-format":"qcow2", |
c13163fb BC |
3431 | "snapshots":[ |
3432 | { | |
3433 | "id": "1", | |
3434 | "name": "snapshot1", | |
3435 | "vm-state-size": 0, | |
3436 | "date-sec": 10000200, | |
3437 | "date-nsec": 12, | |
3438 | "vm-clock-sec": 206, | |
3439 | "vm-clock-nsec": 30 | |
3440 | } | |
3441 | ], | |
3442 | "backing-image":{ | |
3443 | "filename":"disks/base.qcow2", | |
3444 | "format":"qcow2", | |
3445 | "virtual-size":2048000 | |
3446 | } | |
c059451c | 3447 | } } ] } |
c13163fb | 3448 | |
24fb4133 HR |
3449 | blockdev-change-medium |
3450 | ---------------------- | |
3451 | ||
3452 | Changes the medium inserted into a block device by ejecting the current medium | |
3453 | and loading a new image file which is inserted as the new medium. | |
3454 | ||
3455 | Arguments: | |
3456 | ||
70e2cb3b KW |
3457 | - "device": block device name (deprecated, use @id instead) |
3458 | (json-string, optional) | |
3459 | - "id": the name or QOM path of the guest device (json-string, optional) | |
24fb4133 HR |
3460 | - "filename": filename of the new image (json-string) |
3461 | - "format": format of the new image (json-string, optional) | |
39ff43d9 HR |
3462 | - "read-only-mode": new read-only mode (json-string, optional) |
3463 | - Possible values: "retain" (default), "read-only", "read-write" | |
24fb4133 HR |
3464 | |
3465 | Examples: | |
3466 | ||
3467 | 1. Change a removable medium | |
3468 | ||
3469 | -> { "execute": "blockdev-change-medium", | |
70e2cb3b | 3470 | "arguments": { "id": "ide0-1-0", |
24fb4133 HR |
3471 | "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", |
3472 | "format": "raw" } } | |
3473 | <- { "return": {} } | |
3474 | ||
39ff43d9 HR |
3475 | 2. Load a read-only medium into a writable drive |
3476 | ||
3477 | -> { "execute": "blockdev-change-medium", | |
70e2cb3b | 3478 | "arguments": { "id": "floppyA", |
39ff43d9 HR |
3479 | "filename": "/srv/images/ro.img", |
3480 | "format": "raw", | |
3481 | "read-only-mode": "retain" } } | |
3482 | ||
3483 | <- { "error": | |
3484 | { "class": "GenericError", | |
3485 | "desc": "Could not open '/srv/images/ro.img': Permission denied" } } | |
3486 | ||
3487 | -> { "execute": "blockdev-change-medium", | |
70e2cb3b | 3488 | "arguments": { "id": "floppyA", |
39ff43d9 HR |
3489 | "filename": "/srv/images/ro.img", |
3490 | "format": "raw", | |
3491 | "read-only-mode": "read-only" } } | |
3492 | ||
3493 | <- { "return": {} } | |
3494 | ||
76b5d850 HT |
3495 | query-memdev |
3496 | ------------ | |
3497 | ||
3498 | Show memory devices information. | |
3499 | ||
3500 | ||
3501 | Example (1): | |
3502 | ||
3503 | -> { "execute": "query-memdev" } | |
3504 | <- { "return": [ | |
3505 | { | |
3506 | "size": 536870912, | |
3507 | "merge": false, | |
3508 | "dump": true, | |
3509 | "prealloc": false, | |
3510 | "host-nodes": [0, 1], | |
3511 | "policy": "bind" | |
3512 | }, | |
3513 | { | |
3514 | "size": 536870912, | |
3515 | "merge": false, | |
3516 | "dump": true, | |
3517 | "prealloc": true, | |
3518 | "host-nodes": [2, 3], | |
3519 | "policy": "preferred" | |
3520 | } | |
3521 | ] | |
3522 | } | |
3523 | ||
bdf05133 | 3524 | query-memory-devices |
6f2e2730 IM |
3525 | -------------------- |
3526 | ||
3527 | Return a list of memory devices. | |
3528 | ||
3529 | Example: | |
3530 | -> { "execute": "query-memory-devices" } | |
3531 | <- { "return": [ { "data": | |
3532 | { "addr": 5368709120, | |
3533 | "hotpluggable": true, | |
3534 | "hotplugged": true, | |
3535 | "id": "d1", | |
3536 | "memdev": "/objects/memX", | |
3537 | "node": 0, | |
3538 | "size": 1073741824, | |
3539 | "slot": 0}, | |
3540 | "type": "dimm" | |
3541 | } ] } | |
bdf05133 | 3542 | |
bdf05133 MAL |
3543 | query-acpi-ospm-status |
3544 | ---------------------- | |
02419bcb IM |
3545 | |
3546 | Return list of ACPIOSTInfo for devices that support status reporting | |
3547 | via ACPI _OST method. | |
3548 | ||
3549 | Example: | |
3550 | -> { "execute": "query-acpi-ospm-status" } | |
3551 | <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, | |
3552 | { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, | |
3553 | { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, | |
3554 | { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} | |
3555 | ]} | |
bdf05133 | 3556 | |
f2ae8abf MT |
3557 | rtc-reset-reinjection |
3558 | --------------------- | |
3559 | ||
3560 | Reset the RTC interrupt reinjection backlog. | |
3561 | ||
3562 | Arguments: None. | |
3563 | ||
3564 | Example: | |
3565 | ||
3566 | -> { "execute": "rtc-reset-reinjection" } | |
3567 | <- { "return": {} } | |
bdf05133 | 3568 | |
1dde0f48 LV |
3569 | trace-event-get-state |
3570 | --------------------- | |
3571 | ||
3572 | Query the state of events. | |
3573 | ||
77e2b172 LV |
3574 | Arguments: |
3575 | ||
3576 | - "name": Event name pattern (json-string). | |
3577 | - "vcpu": The vCPU to query, any vCPU by default (json-int, optional). | |
3578 | ||
3579 | An event is returned if: | |
3580 | - its name matches the "name" pattern, and | |
3581 | - if "vcpu" is given, the event has the "vcpu" property. | |
3582 | ||
3583 | Therefore, if "vcpu" is given, the operation will only match per-vCPU events, | |
3584 | returning their state on the specified vCPU. Special case: if "name" is an exact | |
3585 | match, "vcpu" is given and the event does not have the "vcpu" property, an error | |
3586 | is returned. | |
3587 | ||
1dde0f48 LV |
3588 | Example: |
3589 | ||
3590 | -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } } | |
3591 | <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] } | |
bdf05133 | 3592 | |
1dde0f48 LV |
3593 | trace-event-set-state |
3594 | --------------------- | |
3595 | ||
3596 | Set the state of events. | |
3597 | ||
77e2b172 LV |
3598 | Arguments: |
3599 | ||
3600 | - "name": Event name pattern (json-string). | |
3601 | - "enable": Whether to enable or disable the event (json-bool). | |
3602 | - "ignore-unavailable": Whether to ignore errors for events that cannot be | |
3603 | changed (json-bool, optional). | |
3604 | - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional). | |
3605 | ||
3606 | An event's state is modified if: | |
3607 | - its name matches the "name" pattern, and | |
3608 | - if "vcpu" is given, the event has the "vcpu" property. | |
3609 | ||
3610 | Therefore, if "vcpu" is given, the operation will only match per-vCPU events, | |
3611 | setting their state on the specified vCPU. Special case: if "name" is an exact | |
3612 | match, "vcpu" is given and the event does not have the "vcpu" property, an error | |
3613 | is returned. | |
3614 | ||
1dde0f48 LV |
3615 | Example: |
3616 | ||
3617 | -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } } | |
3618 | <- { "return": {} } | |
bdf05133 | 3619 | |
bdf05133 MAL |
3620 | input-send-event |
3621 | ---------------- | |
50c6617f MT |
3622 | |
3623 | Send input event to guest. | |
3624 | ||
3625 | Arguments: | |
3626 | ||
b98d26e3 GH |
3627 | - "device": display device (json-string, optional) |
3628 | - "head": display head (json-int, optional) | |
3629 | - "events": list of input events | |
50c6617f MT |
3630 | |
3631 | The consoles are visible in the qom tree, under | |
3632 | /backend/console[$index]. They have a device link and head property, so | |
3633 | it is possible to map which console belongs to which device and display. | |
3634 | ||
3635 | Example (1): | |
3636 | ||
3637 | Press left mouse button. | |
3638 | ||
6575ccdd | 3639 | -> { "execute": "input-send-event", |
b98d26e3 | 3640 | "arguments": { "device": "video0", |
50c6617f | 3641 | "events": [ { "type": "btn", |
f22d0af0 | 3642 | "data" : { "down": true, "button": "left" } } ] } } |
50c6617f MT |
3643 | <- { "return": {} } |
3644 | ||
6575ccdd | 3645 | -> { "execute": "input-send-event", |
b98d26e3 | 3646 | "arguments": { "device": "video0", |
50c6617f | 3647 | "events": [ { "type": "btn", |
f22d0af0 | 3648 | "data" : { "down": false, "button": "left" } } ] } } |
50c6617f MT |
3649 | <- { "return": {} } |
3650 | ||
3651 | Example (2): | |
3652 | ||
3653 | Press ctrl-alt-del. | |
3654 | ||
6575ccdd | 3655 | -> { "execute": "input-send-event", |
b98d26e3 | 3656 | "arguments": { "events": [ |
50c6617f MT |
3657 | { "type": "key", "data" : { "down": true, |
3658 | "key": {"type": "qcode", "data": "ctrl" } } }, | |
3659 | { "type": "key", "data" : { "down": true, | |
3660 | "key": {"type": "qcode", "data": "alt" } } }, | |
3661 | { "type": "key", "data" : { "down": true, | |
3662 | "key": {"type": "qcode", "data": "delete" } } } ] } } | |
3663 | <- { "return": {} } | |
3664 | ||
3665 | Example (3): | |
3666 | ||
3667 | Move mouse pointer to absolute coordinates (20000, 400). | |
3668 | ||
6575ccdd | 3669 | -> { "execute": "input-send-event" , |
b98d26e3 | 3670 | "arguments": { "events": [ |
01df5143 GH |
3671 | { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, |
3672 | { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } | |
50c6617f MT |
3673 | <- { "return": {} } |
3674 | ||
e2462113 FR |
3675 | block-set-write-threshold |
3676 | ------------ | |
3677 | ||
3678 | Change the write threshold for a block drive. The threshold is an offset, | |
3679 | thus must be non-negative. Default is no write threshold. | |
3680 | Setting the threshold to zero disables it. | |
3681 | ||
3682 | Arguments: | |
3683 | ||
3684 | - "node-name": the node name in the block driver state graph (json-string) | |
3685 | - "write-threshold": the write threshold in bytes (json-int) | |
3686 | ||
3687 | Example: | |
3688 | ||
3689 | -> { "execute": "block-set-write-threshold", | |
3690 | "arguments": { "node-name": "mydev", | |
3691 | "write-threshold": 17179869184 } } | |
3692 | <- { "return": {} } | |
3693 | ||
fafa4d50 SF |
3694 | Show rocker switch |
3695 | ------------------ | |
3696 | ||
3697 | Arguments: | |
3698 | ||
3699 | - "name": switch name | |
3700 | ||
3701 | Example: | |
3702 | ||
3703 | -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } | |
3704 | <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} | |
3705 | ||
fafa4d50 SF |
3706 | Show rocker switch ports |
3707 | ------------------------ | |
3708 | ||
3709 | Arguments: | |
3710 | ||
3711 | - "name": switch name | |
3712 | ||
3713 | Example: | |
3714 | ||
3715 | -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } | |
3716 | <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", | |
3717 | "autoneg": "off", "link-up": true, "speed": 10000}, | |
3718 | {"duplex": "full", "enabled": true, "name": "sw1.2", | |
3719 | "autoneg": "off", "link-up": true, "speed": 10000} | |
3720 | ]} | |
3721 | ||
fafa4d50 SF |
3722 | Show rocker switch OF-DPA flow tables |
3723 | ------------------------------------- | |
3724 | ||
3725 | Arguments: | |
3726 | ||
3727 | - "name": switch name | |
3728 | - "tbl-id": (optional) flow table ID | |
3729 | ||
3730 | Example: | |
3731 | ||
3732 | -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } } | |
3733 | <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0}, | |
3734 | "hits": 138, | |
3735 | "cookie": 0, | |
3736 | "action": {"goto-tbl": 10}, | |
3737 | "mask": {"in-pport": 4294901760} | |
3738 | }, | |
3739 | {...more...}, | |
3740 | ]} | |
3741 | ||
fafa4d50 SF |
3742 | Show rocker OF-DPA group tables |
3743 | ------------------------------- | |
3744 | ||
3745 | Arguments: | |
3746 | ||
3747 | - "name": switch name | |
3748 | - "type": (optional) group type | |
3749 | ||
3750 | Example: | |
3751 | ||
3752 | -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } } | |
3753 | <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841, | |
3754 | "pop-vlan": 1, "id": 251723778}, | |
3755 | {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841, | |
3756 | "pop-vlan": 1, "id": 251723776}, | |
3757 | {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840, | |
3758 | "pop-vlan": 1, "id": 251658241}, | |
3759 | {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840, | |
3760 | "pop-vlan": 1, "id": 251658240} | |
3761 | ]} | |
ae50a770 | 3762 | |
ae50a770 PX |
3763 | query-gic-capabilities |
3764 | --------------- | |
3765 | ||
3766 | Return a list of GICCapability objects, describing supported GIC | |
3767 | (Generic Interrupt Controller) versions. | |
3768 | ||
3769 | Arguments: None | |
3770 | ||
3771 | Example: | |
3772 | ||
3773 | -> { "execute": "query-gic-capabilities" } | |
3774 | <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, | |
3775 | { "version": 3, "emulated": false, "kernel": true } ] } | |
3776 | ||
d4633541 IM |
3777 | Show existing/possible CPUs |
3778 | --------------------------- | |
3779 | ||
3780 | Arguments: None. | |
3781 | ||
3782 | Example for pseries machine type started with | |
3783 | -smp 2,cores=2,maxcpus=4 -cpu POWER8: | |
3784 | ||
3785 | -> { "execute": "query-hotpluggable-cpus" } | |
3786 | <- {"return": [ | |
13f5e800 | 3787 | { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core", |
d4633541 | 3788 | "vcpus-count": 1 }, |
13f5e800 | 3789 | { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", |
d4633541 IM |
3790 | "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} |
3791 | ]}' | |
4d952914 IM |
3792 | |
3793 | Example for pc machine type started with | |
3794 | -smp 1,maxcpus=2: | |
3795 | -> { "execute": "query-hotpluggable-cpus" } | |
3796 | <- {"return": [ | |
3797 | { | |
3798 | "type": "qemu64-x86_64-cpu", "vcpus-count": 1, | |
3799 | "props": {"core-id": 0, "socket-id": 1, "thread-id": 0} | |
3800 | }, | |
3801 | { | |
3802 | "qom-path": "/machine/unattached/device[0]", | |
3803 | "type": "qemu64-x86_64-cpu", "vcpus-count": 1, | |
3804 | "props": {"core-id": 0, "socket-id": 0, "thread-id": 0} | |
3805 | } | |
3806 | ]} |