qemu.qmp.qmp_shell module

Low-level QEMU shell on top of QMP.

usage: qmp-shell [-h] [-H] [-N] [-v] [-p] 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

-N, --skip-negotiation

Skip negotiate (for qemu-ga)

-v, --verbose

Verbose (echo commands sent and received)

-p, --pretty

Pretty-print JSON

Start QEMU with:

# qemu […] -qmp unix:./qmp-sock,server

Run the shell:

$ qmp-shell ./qmp-sock

Commands have the following format:

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

For example:

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

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

example-command arg-name1={‘key’:’value’,’obj’={‘prop’:”value”}}

Both JSON and Python formatting should work, including both styles of string literal quotes. Both paradigms of literal values should work, including null/true/false for JSON and None/True/False for Python.

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)

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, which is useful for debugging and documentation generation.

class qemu.qmp.qmp_shell.FuzzyJSON

Bases: ast.NodeTransformer

This extension of ast.NodeTransformer filters literal “true/false/null” values in a Python AST and replaces them by proper “True/False/None” values that Python can properly evaluate.

classmethod visit_Name(node: ast.Name) → ast.AST

Transform Name nodes with certain values into Constant (keyword) nodes.

class qemu.qmp.qmp_shell.HMPShell(address: Union[Tuple[str, int], str], pretty: bool = False, verbose: bool = False)

Bases: qemu.qmp.qmp_shell.QMPShell

HMPShell provides a basic readline-based HMP shell, tunnelled via QMP.

Parameters

• address – Address of the QMP server.

• pretty – Pretty-print QMP messages.

• verbose – Echo outgoing QMP messages to console.

show_banner(msg: str = 'Welcome to the HMP shell!') → None

Print to stdio a greeting, and the QEMU version if available.

class qemu.qmp.qmp_shell.QMPCompleter

Bases: object

QMPCompleter provides a readline library tab-complete behavior.

append(value: str) → None

Append a new valid completion to the list of possibilities.

complete(text: str, state: int) → Optional[str]

readline.set_completer() callback implementation.

class qemu.qmp.qmp_shell.QMPShell(address: Union[Tuple[str, int], str], pretty: bool = False, verbose: bool = False)

Bases: qemu.qmp.QEMUMonitorProtocol

QMPShell provides a basic readline-based QMP shell.

Parameters

• address – Address of the QMP server.

• pretty – Pretty-print QMP messages.

• verbose – Echo outgoing QMP messages to console.

close() → None

Close the socket and socket file.

connect(negotiate: bool = True) → None

Connect to the QMP Monitor and perform capabilities negotiation.

@return QMP greeting dict, or None if negotiate is false @raise OSError on socket connection errors @raise QMPConnectError if the greeting is not received @raise QMPCapabilitiesError if fails to negotiate capabilities

property prompt: str

Return the current shell prompt, including a trailing space.

read_exec_command() → bool

Read and execute a command.

@return True if execution was ok, return False if disconnected.

repl() → Iterator[None]

Return an iterator that implements the REPL.

show_banner(msg: str = 'Welcome to the QMP low-level shell!') → None

Print to stdio a greeting, and the QEMU version if available.

exception qemu.qmp.qmp_shell.QMPShellError

Bases: qemu.qmp.QMPError

QMP Shell Base error class.

qemu.qmp.qmp_shell.die(msg: str) → NoReturn

Write an error to stderr, then exit with a return code of 1.

qemu.qmp.qmp_shell.main() → None

qmp-shell entry point: parse command line arguments and start the REPL.