QMP-SHELL(1)

NAME
qmp-shell - 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 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

Copyright
2009-2022, QEMU Project