qmp-shell
qmp-shell - An interactive QEMU shell powered by QMP
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.
usage: qmp-shell [-h] [-H] [-v] [-p] [-l LOGFILE] [-N] qmp_server
- 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
QEMU QMP Reference Manual
.
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.