1QMP-SHELL(1)             QEMU Monitor Protocol Library            QMP-SHELL(1)
2
3
4

NAME

6       qmp-shell - An interactive QEMU shell powered by QMP
7

SYNOPSIS

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

DESCRIPTION

12       qmp-shell  offers  a simple shell with a convenient shorthand syntax as
13       an alternative to typing JSON by hand. This syntax is not  standardized
14       and  is  not meant to be used as a scriptable interface. This shorthand
15       may change incompatibly in the future, and it is strongly encouraged to
16       use the QMP library to provide API-stable scripting when needed.
17
18       positional arguments:
19              qmp_server            < UNIX socket path | TCP address:port >
20
21       optional arguments:
22
23              -h, --help
24                     show this help message and exit
25
26              -H, --hmp
27                     Use HMP interface
28
29              -v, --verbose
30                     Verbose (echo commands sent and received)
31
32              -p, --pretty
33                     Pretty-print JSON
34
35              -l LOGFILE, --logfile LOGFILE
36                     Save log of all QMP messages to PATH
37
38              -N, --skip-negotiation
39                     Skip negotiate (for qemu-ga)
40
41   Usage
42       First, start QEMU with:
43
44          > qemu [...] -qmp unix:./qmp-sock,server=on[,wait=off]
45
46       Then run the shell, passing the address of the socket:
47
48          > qmp-shell ./qmp-sock
49
50   Syntax
51       Commands have the following format:
52
53          < command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]
54
55       For example, to add a network device:
56
57          (QEMU) device_add driver=e1000 id=net1
58          {'return': {}}
59          (QEMU)
60
61       key=value pairs support either Python or JSON object literal notations,
62       without spaces. Dictionaries/objects {} are supported,  as  are  arrays
63       []:
64
65          example-command arg-name1={'key':'value','obj'={'prop':"value"}}
66
67       Either  JSON  or Python formatting for compound values works, including
68       both styles of string literal quotes (either single or double  quotes).
69       Both    paradigms   of   literal   values   are   accepted,   including
70       null/true/false for JSON and None/True/False for Python.
71
72   Transactions
73       Transactions have the following multi-line format:
74
75          transaction(
76          action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
77          ...
78          action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
79          )
80
81       One line transactions are also supported:
82
83          transaction( action-name1 ... )
84
85       For example:
86
87          (QEMU) transaction(
88          TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
89          TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
90          TRANS> )
91          {"return": {}}
92          (QEMU)
93
94   Commands
95       Autocomplete of command names using <tab> is supported. Pressing  <tab>
96       at  a  blank  CLI prompt will show you a list of all available commands
97       that the connected QEMU instance supports.
98
99       For documentation on QMP commands and their arguments, please  see  in‐
100       terop/qemu-qmp-ref.
101
102   Events
103       qmp-shell  will  display events received from the server, but this ver‐
104       sion does not do so asynchronously. To check for new  events  from  the
105       server, press <enter> on a blank line:
106
107          (QEMU) ⏎
108          {'timestamp': {'seconds': 1660071944, 'microseconds': 184667},
109           'event': 'STOP'}
110
111   Display options
112       Use  the -v and -p options to activate the verbose and pretty-print op‐
113       tions, which will echo back the properly formatted  JSON-compliant  QMP
114       that  is  being  sent  to QEMU. This is useful for debugging to see the
115       wire-level QMP data being exchanged, and generating output for  use  in
116       writing documentation for QEMU.
117

AUTHOR

119       The QEMU Project authors
120

122       2009-2022, QEMU Project
123
124
125
126
1270.0.2                            Oct 25, 2022                     QMP-SHELL(1)
Impressum