qmp-shell - Man Page

An interactive QEMU shell powered by QMP

Synopsis

qmp-shell [-h] [-H] [-v] [-p] [-l LOGFILE] [-N] qmp_server

Description

qmp-shell offers a simple shell with a convenient shorthand syntax as an alternative to typing JSON by hand. This syntax is not standardized and is not meant to be used as a scriptable interface. This shorthand may change incompatibly in the future, and it is strongly encouraged to use the QMP library to provide API-stable scripting when needed.

positional arguments:

qmp_server            < UNIX socket path | TCP address:port >

optional arguments:
-h, --help

show this help message and exit

-H, --hmp

Use HMP interface

-v, --verbose

Verbose (echo commands sent and received)

-p, --pretty

Pretty-print JSON

-l LOGFILE--logfile LOGFILE

Save log of all QMP messages to PATH

-N, --skip-negotiation

Skip negotiate (for qemu-ga)

Usage

First, start QEMU with:

> qemu [...] -qmp unix:./qmp-sock,server=on[,wait=off]

Then run the shell, passing the address of the socket:

> qmp-shell ./qmp-sock

Syntax

Commands have the following format:

< command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]

For example, to add a network device:

(QEMU) device_add driver=e1000 id=net1
{'return': {}}
(QEMU)

key=value pairs support either Python or JSON object literal notations, without spaces. Dictionaries/objects {} are supported, as are arrays []:

example-command arg-name1={'key':'value','obj'={'prop':"value"}}

Either JSON or Python formatting for compound values works, including both styles of string literal quotes (either single or double quotes). Both paradigms of literal values are accepted, including null/true/false for JSON and None/True/False for Python.

Transactions

Transactions have the following multi-line format:

transaction(
action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
...
action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
)

One line transactions are also supported:

transaction( action-name1 ... )

For example:

(QEMU) transaction(
TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
TRANS> )
{"return": {}}
(QEMU)

Commands

Autocomplete of command names using <tab> is supported. Pressing <tab> at a blank CLI prompt will show you a list of all available commands that the connected QEMU instance supports.

For documentation on QMP commands and their arguments, please see interop/qemu-qmp-ref.

Events

qmp-shell will display events received from the server, but this version does not do so asynchronously. To check for new events from the server, press <enter> on a blank line:

(QEMU) ⏎
{'timestamp': {'seconds': 1660071944, 'microseconds': 184667},
 'event': 'STOP'}

Display options

Use the -v and -p options to activate the verbose and pretty-print options, which will echo back the properly formatted JSON-compliant QMP that is being sent to QEMU. This is useful for debugging to see the wire-level QMP data being exchanged, and generating output for use in writing documentation for QEMU.

Author

The QEMU Project authors

Referenced By

qmp-shell-wrap(1).

Oct 25, 2022 0.0.2 QEMU Monitor Protocol Library