root / qapi-schema-guest.json @ d7582078
History | View | Annotate | Download (13.4 kB)
1 | e3d4d252 | Michael Roth | # *-*- Mode: Python -*-* |
---|---|---|---|
2 | e3d4d252 | Michael Roth | |
3 | e3d4d252 | Michael Roth | ## |
4 | 3cf0bed8 | Michael Roth | #
|
5 | 3cf0bed8 | Michael Roth | # Echo back a unique integer value, and prepend to response a |
6 | 3cf0bed8 | Michael Roth | # leading sentinel byte (0xFF) the client can check scan for. |
7 | 3cf0bed8 | Michael Roth | #
|
8 | 3cf0bed8 | Michael Roth | # This is used by clients talking to the guest agent over the |
9 | 3cf0bed8 | Michael Roth | # wire to ensure the stream is in sync and doesn't contain stale |
10 | 3cf0bed8 | Michael Roth | # data from previous client. It must be issued upon initial |
11 | 3cf0bed8 | Michael Roth | # connection, and after any client-side timeouts (including |
12 | 3cf0bed8 | Michael Roth | # timeouts on receiving a response to this command). |
13 | 3cf0bed8 | Michael Roth | #
|
14 | 3cf0bed8 | Michael Roth | # After issuing this request, all guest agent responses should be |
15 | 3cf0bed8 | Michael Roth | # ignored until the response containing the unique integer value |
16 | 3cf0bed8 | Michael Roth | # the client passed in is returned. Receival of the 0xFF sentinel |
17 | 3cf0bed8 | Michael Roth | # byte must be handled as an indication that the client's |
18 | 3cf0bed8 | Michael Roth | # lexer/tokenizer/parser state should be flushed/reset in |
19 | 3cf0bed8 | Michael Roth | # preparation for reliably receiving the subsequent response. As |
20 | 3cf0bed8 | Michael Roth | # an optimization, clients may opt to ignore all data until a |
21 | a31f0531 | Jim Meyering | # sentinel value is receiving to avoid unnecessary processing of |
22 | 3cf0bed8 | Michael Roth | # stale data. |
23 | 3cf0bed8 | Michael Roth | #
|
24 | 3cf0bed8 | Michael Roth | # Similarly, clients should also precede this *request* |
25 | 3cf0bed8 | Michael Roth | # with a 0xFF byte to make sure the guest agent flushes any |
26 | 3cf0bed8 | Michael Roth | # partially read JSON data from a previous client connection. |
27 | 3cf0bed8 | Michael Roth | #
|
28 | 3cf0bed8 | Michael Roth | # @id: randomly generated 64-bit integer |
29 | 3cf0bed8 | Michael Roth | #
|
30 | 3cf0bed8 | Michael Roth | # Returns: The unique integer id passed in by the client |
31 | 3cf0bed8 | Michael Roth | #
|
32 | 3cf0bed8 | Michael Roth | # Since: 1.1 |
33 | 3cf0bed8 | Michael Roth | # ## |
34 | 3cf0bed8 | Michael Roth | { 'command': 'guest-sync-delimited' |
35 | 3cf0bed8 | Michael Roth | 'data': { 'id': 'int' }, |
36 | 3cf0bed8 | Michael Roth | 'returns': 'int' } |
37 | 3cf0bed8 | Michael Roth | |
38 | 3cf0bed8 | Michael Roth | ## |
39 | e3d4d252 | Michael Roth | # @guest-sync: |
40 | e3d4d252 | Michael Roth | #
|
41 | e3d4d252 | Michael Roth | # Echo back a unique integer value |
42 | e3d4d252 | Michael Roth | #
|
43 | e3d4d252 | Michael Roth | # This is used by clients talking to the guest agent over the |
44 | e3d4d252 | Michael Roth | # wire to ensure the stream is in sync and doesn't contain stale |
45 | e3d4d252 | Michael Roth | # data from previous client. All guest agent responses should be |
46 | e3d4d252 | Michael Roth | # ignored until the provided unique integer value is returned, |
47 | e3d4d252 | Michael Roth | # and it is up to the client to handle stale whole or |
48 | e3d4d252 | Michael Roth | # partially-delivered JSON text in such a way that this response |
49 | e3d4d252 | Michael Roth | # can be obtained. |
50 | e3d4d252 | Michael Roth | #
|
51 | 3cf0bed8 | Michael Roth | # In cases where a partial stale response was previously |
52 | 3cf0bed8 | Michael Roth | # received by the client, this cannot always be done reliably. |
53 | 3cf0bed8 | Michael Roth | # One particular scenario being if qemu-ga responses are fed |
54 | 3cf0bed8 | Michael Roth | # character-by-character into a JSON parser. In these situations, |
55 | 3cf0bed8 | Michael Roth | # using guest-sync-delimited may be optimal. |
56 | 3cf0bed8 | Michael Roth | #
|
57 | 3cf0bed8 | Michael Roth | # For clients that fetch responses line by line and convert them |
58 | 3cf0bed8 | Michael Roth | # to JSON objects, guest-sync should be sufficient, but note that |
59 | 3cf0bed8 | Michael Roth | # in cases where the channel is dirty some attempts at parsing the |
60 | 3cf0bed8 | Michael Roth | # response may result in a parser error. |
61 | 3cf0bed8 | Michael Roth | #
|
62 | e7d81004 | Stefan Weil | # Such clients should also precede this command |
63 | 3cf0bed8 | Michael Roth | # with a 0xFF byte to make sure the guest agent flushes any |
64 | e3d4d252 | Michael Roth | # partially read JSON data from a previous session. |
65 | e3d4d252 | Michael Roth | #
|
66 | e3d4d252 | Michael Roth | # @id: randomly generated 64-bit integer |
67 | e3d4d252 | Michael Roth | #
|
68 | e3d4d252 | Michael Roth | # Returns: The unique integer id passed in by the client |
69 | e3d4d252 | Michael Roth | #
|
70 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
71 | e3d4d252 | Michael Roth | ## |
72 | e3d4d252 | Michael Roth | { 'command': 'guest-sync' |
73 | e3d4d252 | Michael Roth | 'data': { 'id': 'int' }, |
74 | e3d4d252 | Michael Roth | 'returns': 'int' } |
75 | e3d4d252 | Michael Roth | |
76 | e3d4d252 | Michael Roth | ## |
77 | e3d4d252 | Michael Roth | # @guest-ping: |
78 | e3d4d252 | Michael Roth | #
|
79 | e3d4d252 | Michael Roth | # Ping the guest agent, a non-error return implies success |
80 | e3d4d252 | Michael Roth | #
|
81 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
82 | e3d4d252 | Michael Roth | ## |
83 | e3d4d252 | Michael Roth | { 'command': 'guest-ping' } |
84 | e3d4d252 | Michael Roth | |
85 | e3d4d252 | Michael Roth | ## |
86 | 54383726 | Michael Roth | # @GuestAgentCommandInfo: |
87 | e3d4d252 | Michael Roth | #
|
88 | 54383726 | Michael Roth | # Information about guest agent commands. |
89 | e3d4d252 | Michael Roth | #
|
90 | 54383726 | Michael Roth | # @name: name of the command |
91 | 54383726 | Michael Roth | #
|
92 | 54383726 | Michael Roth | # @enabled: whether command is currently enabled by guest admin |
93 | 54383726 | Michael Roth | #
|
94 | 54383726 | Michael Roth | # Since 1.1.0 |
95 | e3d4d252 | Michael Roth | ## |
96 | bf95c0d5 | Michael Roth | { 'type': 'GuestAgentCommandInfo', |
97 | bf95c0d5 | Michael Roth | 'data': { 'name': 'str', 'enabled': 'bool' } } |
98 | 54383726 | Michael Roth | |
99 | 54383726 | Michael Roth | ## |
100 | 54383726 | Michael Roth | # @GuestAgentInfo |
101 | 54383726 | Michael Roth | #
|
102 | 54383726 | Michael Roth | # Information about guest agent. |
103 | 54383726 | Michael Roth | #
|
104 | 54383726 | Michael Roth | # @version: guest agent version |
105 | 54383726 | Michael Roth | #
|
106 | 54383726 | Michael Roth | # @supported_commands: Information about guest agent commands |
107 | 54383726 | Michael Roth | #
|
108 | 54383726 | Michael Roth | # Since 0.15.0 |
109 | 54383726 | Michael Roth | ## |
110 | bf95c0d5 | Michael Roth | { 'type': 'GuestAgentInfo', |
111 | bf95c0d5 | Michael Roth | 'data': { 'version': 'str', |
112 | bf95c0d5 | Michael Roth | 'supported_commands': ['GuestAgentCommandInfo'] } } |
113 | 54383726 | Michael Roth | ## |
114 | 54383726 | Michael Roth | # @guest-info: |
115 | 54383726 | Michael Roth | #
|
116 | 54383726 | Michael Roth | # Get some information about the guest agent. |
117 | 54383726 | Michael Roth | #
|
118 | 54383726 | Michael Roth | # Returns: @GuestAgentInfo |
119 | 54383726 | Michael Roth | #
|
120 | 54383726 | Michael Roth | # Since: 0.15.0 |
121 | 54383726 | Michael Roth | ## |
122 | e3d4d252 | Michael Roth | { 'command': 'guest-info', |
123 | e3d4d252 | Michael Roth | 'returns': 'GuestAgentInfo' } |
124 | e3d4d252 | Michael Roth | |
125 | e3d4d252 | Michael Roth | ## |
126 | e3d4d252 | Michael Roth | # @guest-shutdown: |
127 | e3d4d252 | Michael Roth | #
|
128 | e3d4d252 | Michael Roth | # Initiate guest-activated shutdown. Note: this is an asynchronous |
129 | 3674838c | Luiz Capitulino | # shutdown request, with no guarantee of successful shutdown. |
130 | e3d4d252 | Michael Roth | #
|
131 | e3d4d252 | Michael Roth | # @mode: #optional "halt", "powerdown" (default), or "reboot" |
132 | e3d4d252 | Michael Roth | #
|
133 | 89268172 | Luiz Capitulino | # This command does NOT return a response on success. Success condition |
134 | 89268172 | Luiz Capitulino | # is indicated by the VM exiting with a zero exit status or, when |
135 | 89268172 | Luiz Capitulino | # running with --no-shutdown, by issuing the query-status QMP command |
136 | 89268172 | Luiz Capitulino | # to confirm the VM status is "shutdown". |
137 | e3d4d252 | Michael Roth | #
|
138 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
139 | e3d4d252 | Michael Roth | ## |
140 | 89268172 | Luiz Capitulino | { 'command': 'guest-shutdown', 'data': { '*mode': 'str' }, |
141 | 89268172 | Luiz Capitulino | 'success-response': 'no' } |
142 | e3d4d252 | Michael Roth | |
143 | e3d4d252 | Michael Roth | ## |
144 | e3d4d252 | Michael Roth | # @guest-file-open: |
145 | e3d4d252 | Michael Roth | #
|
146 | e3d4d252 | Michael Roth | # Open a file in the guest and retrieve a file handle for it |
147 | e3d4d252 | Michael Roth | #
|
148 | e3d4d252 | Michael Roth | # @filepath: Full path to the file in the guest to open. |
149 | e3d4d252 | Michael Roth | #
|
150 | e3d4d252 | Michael Roth | # @mode: #optional open mode, as per fopen(), "r" is the default. |
151 | e3d4d252 | Michael Roth | #
|
152 | e3d4d252 | Michael Roth | # Returns: Guest file handle on success. |
153 | e3d4d252 | Michael Roth | #
|
154 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
155 | e3d4d252 | Michael Roth | ## |
156 | e3d4d252 | Michael Roth | { 'command': 'guest-file-open', |
157 | e3d4d252 | Michael Roth | 'data': { 'path': 'str', '*mode': 'str' }, |
158 | e3d4d252 | Michael Roth | 'returns': 'int' } |
159 | e3d4d252 | Michael Roth | |
160 | e3d4d252 | Michael Roth | ## |
161 | e3d4d252 | Michael Roth | # @guest-file-close: |
162 | e3d4d252 | Michael Roth | #
|
163 | e3d4d252 | Michael Roth | # Close an open file in the guest |
164 | e3d4d252 | Michael Roth | #
|
165 | e3d4d252 | Michael Roth | # @handle: filehandle returned by guest-file-open |
166 | e3d4d252 | Michael Roth | #
|
167 | e3d4d252 | Michael Roth | # Returns: Nothing on success. |
168 | e3d4d252 | Michael Roth | #
|
169 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
170 | e3d4d252 | Michael Roth | ## |
171 | e3d4d252 | Michael Roth | { 'command': 'guest-file-close', |
172 | e3d4d252 | Michael Roth | 'data': { 'handle': 'int' } } |
173 | e3d4d252 | Michael Roth | |
174 | e3d4d252 | Michael Roth | ## |
175 | 54383726 | Michael Roth | # @GuestFileRead |
176 | 54383726 | Michael Roth | #
|
177 | 54383726 | Michael Roth | # Result of guest agent file-read operation |
178 | 54383726 | Michael Roth | #
|
179 | 54383726 | Michael Roth | # @count: number of bytes read (note: count is *before* |
180 | 54383726 | Michael Roth | # base64-encoding is applied) |
181 | 54383726 | Michael Roth | #
|
182 | 54383726 | Michael Roth | # @buf-b64: base64-encoded bytes read |
183 | 54383726 | Michael Roth | #
|
184 | 54383726 | Michael Roth | # @eof: whether EOF was encountered during read operation. |
185 | 54383726 | Michael Roth | #
|
186 | 54383726 | Michael Roth | # Since: 0.15.0 |
187 | 54383726 | Michael Roth | ## |
188 | 54383726 | Michael Roth | { 'type': 'GuestFileRead', |
189 | 54383726 | Michael Roth | 'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } } |
190 | 54383726 | Michael Roth | |
191 | 54383726 | Michael Roth | ## |
192 | e3d4d252 | Michael Roth | # @guest-file-read: |
193 | e3d4d252 | Michael Roth | #
|
194 | e3d4d252 | Michael Roth | # Read from an open file in the guest. Data will be base64-encoded |
195 | e3d4d252 | Michael Roth | #
|
196 | e3d4d252 | Michael Roth | # @handle: filehandle returned by guest-file-open |
197 | e3d4d252 | Michael Roth | #
|
198 | e3d4d252 | Michael Roth | # @count: #optional maximum number of bytes to read (default is 4KB) |
199 | e3d4d252 | Michael Roth | #
|
200 | 54383726 | Michael Roth | # Returns: @GuestFileRead on success. |
201 | e3d4d252 | Michael Roth | #
|
202 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
203 | e3d4d252 | Michael Roth | ## |
204 | e3d4d252 | Michael Roth | { 'command': 'guest-file-read', |
205 | e3d4d252 | Michael Roth | 'data': { 'handle': 'int', '*count': 'int' }, |
206 | e3d4d252 | Michael Roth | 'returns': 'GuestFileRead' } |
207 | e3d4d252 | Michael Roth | |
208 | e3d4d252 | Michael Roth | ## |
209 | 54383726 | Michael Roth | # @GuestFileWrite |
210 | 54383726 | Michael Roth | #
|
211 | 54383726 | Michael Roth | # Result of guest agent file-write operation |
212 | 54383726 | Michael Roth | #
|
213 | 54383726 | Michael Roth | # @count: number of bytes written (note: count is actual bytes |
214 | 54383726 | Michael Roth | # written, after base64-decoding of provided buffer) |
215 | 54383726 | Michael Roth | #
|
216 | 54383726 | Michael Roth | # @eof: whether EOF was encountered during write operation. |
217 | 54383726 | Michael Roth | #
|
218 | 54383726 | Michael Roth | # Since: 0.15.0 |
219 | 54383726 | Michael Roth | ## |
220 | 54383726 | Michael Roth | { 'type': 'GuestFileWrite', |
221 | 54383726 | Michael Roth | 'data': { 'count': 'int', 'eof': 'bool' } } |
222 | 54383726 | Michael Roth | |
223 | 54383726 | Michael Roth | ## |
224 | e3d4d252 | Michael Roth | # @guest-file-write: |
225 | e3d4d252 | Michael Roth | #
|
226 | e3d4d252 | Michael Roth | # Write to an open file in the guest. |
227 | e3d4d252 | Michael Roth | #
|
228 | e3d4d252 | Michael Roth | # @handle: filehandle returned by guest-file-open |
229 | e3d4d252 | Michael Roth | #
|
230 | e3d4d252 | Michael Roth | # @buf-b64: base64-encoded string representing data to be written |
231 | e3d4d252 | Michael Roth | #
|
232 | e3d4d252 | Michael Roth | # @count: #optional bytes to write (actual bytes, after base64-decode), |
233 | e3d4d252 | Michael Roth | # default is all content in buf-b64 buffer after base64 decoding |
234 | e3d4d252 | Michael Roth | #
|
235 | 54383726 | Michael Roth | # Returns: @GuestFileWrite on success. |
236 | e3d4d252 | Michael Roth | #
|
237 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
238 | e3d4d252 | Michael Roth | ## |
239 | e3d4d252 | Michael Roth | { 'command': 'guest-file-write', |
240 | e3d4d252 | Michael Roth | 'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' }, |
241 | e3d4d252 | Michael Roth | 'returns': 'GuestFileWrite' } |
242 | e3d4d252 | Michael Roth | |
243 | 54383726 | Michael Roth | |
244 | 54383726 | Michael Roth | ## |
245 | 54383726 | Michael Roth | # @GuestFileSeek |
246 | 54383726 | Michael Roth | #
|
247 | 54383726 | Michael Roth | # Result of guest agent file-seek operation |
248 | 54383726 | Michael Roth | #
|
249 | 54383726 | Michael Roth | # @position: current file position |
250 | 54383726 | Michael Roth | #
|
251 | 54383726 | Michael Roth | # @eof: whether EOF was encountered during file seek |
252 | 54383726 | Michael Roth | #
|
253 | 54383726 | Michael Roth | # Since: 0.15.0 |
254 | 54383726 | Michael Roth | ## |
255 | 54383726 | Michael Roth | { 'type': 'GuestFileSeek', |
256 | 54383726 | Michael Roth | 'data': { 'position': 'int', 'eof': 'bool' } } |
257 | 54383726 | Michael Roth | |
258 | e3d4d252 | Michael Roth | ## |
259 | e3d4d252 | Michael Roth | # @guest-file-seek: |
260 | e3d4d252 | Michael Roth | #
|
261 | e3d4d252 | Michael Roth | # Seek to a position in the file, as with fseek(), and return the |
262 | e3d4d252 | Michael Roth | # current file position afterward. Also encapsulates ftell()'s |
263 | e3d4d252 | Michael Roth | # functionality, just Set offset=0, whence=SEEK_CUR. |
264 | e3d4d252 | Michael Roth | #
|
265 | e3d4d252 | Michael Roth | # @handle: filehandle returned by guest-file-open |
266 | e3d4d252 | Michael Roth | #
|
267 | e3d4d252 | Michael Roth | # @offset: bytes to skip over in the file stream |
268 | e3d4d252 | Michael Roth | #
|
269 | e3d4d252 | Michael Roth | # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek() |
270 | e3d4d252 | Michael Roth | #
|
271 | 54383726 | Michael Roth | # Returns: @GuestFileSeek on success. |
272 | e3d4d252 | Michael Roth | #
|
273 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
274 | e3d4d252 | Michael Roth | ## |
275 | e3d4d252 | Michael Roth | { 'command': 'guest-file-seek', |
276 | e3d4d252 | Michael Roth | 'data': { 'handle': 'int', 'offset': 'int', 'whence': 'int' }, |
277 | e3d4d252 | Michael Roth | 'returns': 'GuestFileSeek' } |
278 | e3d4d252 | Michael Roth | |
279 | e3d4d252 | Michael Roth | ## |
280 | e3d4d252 | Michael Roth | # @guest-file-flush: |
281 | e3d4d252 | Michael Roth | #
|
282 | e3d4d252 | Michael Roth | # Write file changes bufferred in userspace to disk/kernel buffers |
283 | e3d4d252 | Michael Roth | #
|
284 | e3d4d252 | Michael Roth | # @handle: filehandle returned by guest-file-open |
285 | e3d4d252 | Michael Roth | #
|
286 | e3d4d252 | Michael Roth | # Returns: Nothing on success. |
287 | e3d4d252 | Michael Roth | #
|
288 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
289 | e3d4d252 | Michael Roth | ## |
290 | e3d4d252 | Michael Roth | { 'command': 'guest-file-flush', |
291 | e3d4d252 | Michael Roth | 'data': { 'handle': 'int' } } |
292 | e3d4d252 | Michael Roth | |
293 | e3d4d252 | Michael Roth | ## |
294 | 54383726 | Michael Roth | # @GuestFsFreezeStatus |
295 | e3d4d252 | Michael Roth | #
|
296 | 54383726 | Michael Roth | # An enumation of filesystem freeze states |
297 | e3d4d252 | Michael Roth | #
|
298 | 54383726 | Michael Roth | # @thawed: filesystems thawed/unfrozen |
299 | 54383726 | Michael Roth | #
|
300 | 54383726 | Michael Roth | # @frozen: all non-network guest filesystems frozen |
301 | 54383726 | Michael Roth | #
|
302 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
303 | e3d4d252 | Michael Roth | ## |
304 | e3d4d252 | Michael Roth | { 'enum': 'GuestFsfreezeStatus', |
305 | 9e8aded4 | Michael Roth | 'data': [ 'thawed', 'frozen' ] } |
306 | 54383726 | Michael Roth | |
307 | 54383726 | Michael Roth | ## |
308 | 54383726 | Michael Roth | # @guest-fsfreeze-status: |
309 | 54383726 | Michael Roth | #
|
310 | 54383726 | Michael Roth | # Get guest fsfreeze state. error state indicates |
311 | 54383726 | Michael Roth | #
|
312 | 54383726 | Michael Roth | # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below) |
313 | 54383726 | Michael Roth | #
|
314 | 9e8aded4 | Michael Roth | # Note: This may fail to properly report the current state as a result of |
315 | f789aa7b | Michael Roth | # some other guest processes having issued an fs freeze/thaw. |
316 | 9e8aded4 | Michael Roth | #
|
317 | 54383726 | Michael Roth | # Since: 0.15.0 |
318 | 54383726 | Michael Roth | ## |
319 | e3d4d252 | Michael Roth | { 'command': 'guest-fsfreeze-status', |
320 | e3d4d252 | Michael Roth | 'returns': 'GuestFsfreezeStatus' } |
321 | e3d4d252 | Michael Roth | |
322 | e3d4d252 | Michael Roth | ## |
323 | e3d4d252 | Michael Roth | # @guest-fsfreeze-freeze: |
324 | e3d4d252 | Michael Roth | #
|
325 | 9e8aded4 | Michael Roth | # Sync and freeze all freezable, local guest filesystems |
326 | e3d4d252 | Michael Roth | #
|
327 | 9e8aded4 | Michael Roth | # Returns: Number of file systems currently frozen. On error, all filesystems |
328 | 9e8aded4 | Michael Roth | # will be thawed. |
329 | e3d4d252 | Michael Roth | #
|
330 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
331 | e3d4d252 | Michael Roth | ## |
332 | e3d4d252 | Michael Roth | { 'command': 'guest-fsfreeze-freeze', |
333 | e3d4d252 | Michael Roth | 'returns': 'int' } |
334 | e3d4d252 | Michael Roth | |
335 | e3d4d252 | Michael Roth | ## |
336 | e3d4d252 | Michael Roth | # @guest-fsfreeze-thaw: |
337 | e3d4d252 | Michael Roth | #
|
338 | 9e8aded4 | Michael Roth | # Unfreeze all frozen guest filesystems |
339 | 9e8aded4 | Michael Roth | #
|
340 | 9e8aded4 | Michael Roth | # Returns: Number of file systems thawed by this call |
341 | e3d4d252 | Michael Roth | #
|
342 | 9e8aded4 | Michael Roth | # Note: if return value does not match the previous call to |
343 | 9e8aded4 | Michael Roth | # guest-fsfreeze-freeze, this likely means some freezable |
344 | 9e8aded4 | Michael Roth | # filesystems were unfrozen before this call, and that the |
345 | 9e8aded4 | Michael Roth | # filesystem state may have changed before issuing this |
346 | 9e8aded4 | Michael Roth | # command. |
347 | e3d4d252 | Michael Roth | #
|
348 | e3d4d252 | Michael Roth | # Since: 0.15.0 |
349 | e3d4d252 | Michael Roth | ## |
350 | e3d4d252 | Michael Roth | { 'command': 'guest-fsfreeze-thaw', |
351 | e3d4d252 | Michael Roth | 'returns': 'int' } |
352 | 11d0f125 | Luiz Capitulino | |
353 | 11d0f125 | Luiz Capitulino | ## |
354 | eab5fd59 | Paolo Bonzini | # @guest-fstrim: |
355 | eab5fd59 | Paolo Bonzini | #
|
356 | eab5fd59 | Paolo Bonzini | # Discard (or "trim") blocks which are not in use by the filesystem. |
357 | eab5fd59 | Paolo Bonzini | #
|
358 | eab5fd59 | Paolo Bonzini | # @minimum: |
359 | eab5fd59 | Paolo Bonzini | # Minimum contiguous free range to discard, in bytes. Free ranges |
360 | eab5fd59 | Paolo Bonzini | # smaller than this may be ignored (this is a hint and the guest |
361 | eab5fd59 | Paolo Bonzini | # may not respect it). By increasing this value, the fstrim |
362 | eab5fd59 | Paolo Bonzini | # operation will complete more quickly for filesystems with badly |
363 | eab5fd59 | Paolo Bonzini | # fragmented free space, although not all blocks will be discarded. |
364 | eab5fd59 | Paolo Bonzini | # The default value is zero, meaning "discard every free block". |
365 | eab5fd59 | Paolo Bonzini | #
|
366 | eab5fd59 | Paolo Bonzini | # Returns: Nothing. |
367 | eab5fd59 | Paolo Bonzini | #
|
368 | eab5fd59 | Paolo Bonzini | # Since: 1.2 |
369 | eab5fd59 | Paolo Bonzini | ## |
370 | eab5fd59 | Paolo Bonzini | { 'command': 'guest-fstrim', |
371 | eab5fd59 | Paolo Bonzini | 'data': { '*minimum': 'int' } } |
372 | eab5fd59 | Paolo Bonzini | |
373 | eab5fd59 | Paolo Bonzini | ## |
374 | 11d0f125 | Luiz Capitulino | # @guest-suspend-disk |
375 | 11d0f125 | Luiz Capitulino | #
|
376 | 11d0f125 | Luiz Capitulino | # Suspend guest to disk. |
377 | 11d0f125 | Luiz Capitulino | #
|
378 | 11d0f125 | Luiz Capitulino | # This command tries to execute the scripts provided by the pm-utils package. |
379 | 11d0f125 | Luiz Capitulino | # If it's not available, the suspend operation will be performed by manually |
380 | 11d0f125 | Luiz Capitulino | # writing to a sysfs file. |
381 | 11d0f125 | Luiz Capitulino | #
|
382 | 11d0f125 | Luiz Capitulino | # For the best results it's strongly recommended to have the pm-utils |
383 | 11d0f125 | Luiz Capitulino | # package installed in the guest. |
384 | 11d0f125 | Luiz Capitulino | #
|
385 | c6fcc10a | Luiz Capitulino | # This command does NOT return a response on success. There is a high chance |
386 | c6fcc10a | Luiz Capitulino | # the command succeeded if the VM exits with a zero exit status or, when |
387 | c6fcc10a | Luiz Capitulino | # running with --no-shutdown, by issuing the query-status QMP command to |
388 | c6fcc10a | Luiz Capitulino | # to confirm the VM status is "shutdown". However, the VM could also exit |
389 | c6fcc10a | Luiz Capitulino | # (or set its status to "shutdown") due to other reasons. |
390 | c6fcc10a | Luiz Capitulino | #
|
391 | c6fcc10a | Luiz Capitulino | # The following errors may be returned: |
392 | 11d0f125 | Luiz Capitulino | # If suspend to disk is not supported, Unsupported |
393 | 11d0f125 | Luiz Capitulino | #
|
394 | c6fcc10a | Luiz Capitulino | # Notes: It's strongly recommended to issue the guest-sync command before |
395 | c6fcc10a | Luiz Capitulino | # sending commands when the guest resumes |
396 | 11d0f125 | Luiz Capitulino | #
|
397 | 11d0f125 | Luiz Capitulino | # Since: 1.1 |
398 | 11d0f125 | Luiz Capitulino | ## |
399 | c6fcc10a | Luiz Capitulino | { 'command': 'guest-suspend-disk', 'success-response': 'no' } |
400 | fbf42210 | Luiz Capitulino | |
401 | fbf42210 | Luiz Capitulino | ## |
402 | fbf42210 | Luiz Capitulino | # @guest-suspend-ram |
403 | fbf42210 | Luiz Capitulino | #
|
404 | fbf42210 | Luiz Capitulino | # Suspend guest to ram. |
405 | fbf42210 | Luiz Capitulino | #
|
406 | fbf42210 | Luiz Capitulino | # This command tries to execute the scripts provided by the pm-utils package. |
407 | fbf42210 | Luiz Capitulino | # If it's not available, the suspend operation will be performed by manually |
408 | fbf42210 | Luiz Capitulino | # writing to a sysfs file. |
409 | fbf42210 | Luiz Capitulino | #
|
410 | fbf42210 | Luiz Capitulino | # For the best results it's strongly recommended to have the pm-utils |
411 | fbf42210 | Luiz Capitulino | # package installed in the guest. |
412 | fbf42210 | Luiz Capitulino | #
|
413 | fbf42210 | Luiz Capitulino | # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup' |
414 | fbf42210 | Luiz Capitulino | # command. Thus, it's *required* to query QEMU for the presence of the |
415 | fbf42210 | Luiz Capitulino | # 'system_wakeup' command before issuing guest-suspend-ram. |
416 | fbf42210 | Luiz Capitulino | #
|
417 | 432d29db | Luiz Capitulino | # This command does NOT return a response on success. There are two options |
418 | 432d29db | Luiz Capitulino | # to check for success: |
419 | 432d29db | Luiz Capitulino | # 1. Wait for the SUSPEND QMP event from QEMU |
420 | 432d29db | Luiz Capitulino | # 2. Issue the query-status QMP command to confirm the VM status is |
421 | 432d29db | Luiz Capitulino | # "suspended" |
422 | 432d29db | Luiz Capitulino | #
|
423 | 432d29db | Luiz Capitulino | # The following errors may be returned: |
424 | fbf42210 | Luiz Capitulino | # If suspend to ram is not supported, Unsupported |
425 | fbf42210 | Luiz Capitulino | #
|
426 | 432d29db | Luiz Capitulino | # Notes: It's strongly recommended to issue the guest-sync command before |
427 | 432d29db | Luiz Capitulino | # sending commands when the guest resumes |
428 | fbf42210 | Luiz Capitulino | #
|
429 | fbf42210 | Luiz Capitulino | # Since: 1.1 |
430 | fbf42210 | Luiz Capitulino | ## |
431 | 432d29db | Luiz Capitulino | { 'command': 'guest-suspend-ram', 'success-response': 'no' } |
432 | 95f4f404 | Luiz Capitulino | |
433 | 95f4f404 | Luiz Capitulino | ## |
434 | 95f4f404 | Luiz Capitulino | # @guest-suspend-hybrid |
435 | 95f4f404 | Luiz Capitulino | #
|
436 | 95f4f404 | Luiz Capitulino | # Save guest state to disk and suspend to ram. |
437 | 95f4f404 | Luiz Capitulino | #
|
438 | 95f4f404 | Luiz Capitulino | # This command requires the pm-utils package to be installed in the guest. |
439 | 95f4f404 | Luiz Capitulino | #
|
440 | 95f4f404 | Luiz Capitulino | # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup' |
441 | 95f4f404 | Luiz Capitulino | # command. Thus, it's *required* to query QEMU for the presence of the |
442 | 95f4f404 | Luiz Capitulino | # 'system_wakeup' command before issuing guest-suspend-hybrid. |
443 | 95f4f404 | Luiz Capitulino | #
|
444 | d9fcd2a1 | Luiz Capitulino | # This command does NOT return a response on success. There are two options |
445 | d9fcd2a1 | Luiz Capitulino | # to check for success: |
446 | d9fcd2a1 | Luiz Capitulino | # 1. Wait for the SUSPEND QMP event from QEMU |
447 | d9fcd2a1 | Luiz Capitulino | # 2. Issue the query-status QMP command to confirm the VM status is |
448 | d9fcd2a1 | Luiz Capitulino | # "suspended" |
449 | d9fcd2a1 | Luiz Capitulino | #
|
450 | d9fcd2a1 | Luiz Capitulino | # The following errors may be returned: |
451 | 95f4f404 | Luiz Capitulino | # If hybrid suspend is not supported, Unsupported |
452 | 95f4f404 | Luiz Capitulino | #
|
453 | d9fcd2a1 | Luiz Capitulino | # Notes: It's strongly recommended to issue the guest-sync command before |
454 | d9fcd2a1 | Luiz Capitulino | # sending commands when the guest resumes |
455 | 95f4f404 | Luiz Capitulino | #
|
456 | 95f4f404 | Luiz Capitulino | # Since: 1.1 |
457 | 95f4f404 | Luiz Capitulino | ## |
458 | d9fcd2a1 | Luiz Capitulino | { 'command': 'guest-suspend-hybrid', 'success-response': 'no' } |
459 | 3424fc9f | Michal Privoznik | |
460 | 3424fc9f | Michal Privoznik | ## |
461 | 3424fc9f | Michal Privoznik | # @GuestIpAddressType: |
462 | 3424fc9f | Michal Privoznik | #
|
463 | 3424fc9f | Michal Privoznik | # An enumeration of supported IP address types |
464 | 3424fc9f | Michal Privoznik | #
|
465 | 3424fc9f | Michal Privoznik | # @ipv4: IP version 4 |
466 | 3424fc9f | Michal Privoznik | #
|
467 | 3424fc9f | Michal Privoznik | # @ipv6: IP version 6 |
468 | 3424fc9f | Michal Privoznik | #
|
469 | 3424fc9f | Michal Privoznik | # Since: 1.1 |
470 | 3424fc9f | Michal Privoznik | ## |
471 | 3424fc9f | Michal Privoznik | { 'enum': 'GuestIpAddressType', |
472 | 3424fc9f | Michal Privoznik | 'data': [ 'ipv4', 'ipv6' ] } |
473 | 3424fc9f | Michal Privoznik | |
474 | 3424fc9f | Michal Privoznik | ## |
475 | 3424fc9f | Michal Privoznik | # @GuestIpAddress: |
476 | 3424fc9f | Michal Privoznik | #
|
477 | 3424fc9f | Michal Privoznik | # @ip-address: IP address |
478 | 3424fc9f | Michal Privoznik | #
|
479 | 3424fc9f | Michal Privoznik | # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6) |
480 | 3424fc9f | Michal Privoznik | #
|
481 | 3424fc9f | Michal Privoznik | # @prefix: Network prefix length of @ip-address |
482 | 3424fc9f | Michal Privoznik | #
|
483 | 3424fc9f | Michal Privoznik | # Since: 1.1 |
484 | 3424fc9f | Michal Privoznik | ## |
485 | 3424fc9f | Michal Privoznik | { 'type': 'GuestIpAddress', |
486 | 3424fc9f | Michal Privoznik | 'data': {'ip-address': 'str', |
487 | 3424fc9f | Michal Privoznik | 'ip-address-type': 'GuestIpAddressType', |
488 | 3424fc9f | Michal Privoznik | 'prefix': 'int'} } |
489 | 3424fc9f | Michal Privoznik | |
490 | 3424fc9f | Michal Privoznik | ## |
491 | 3424fc9f | Michal Privoznik | # @GuestNetworkInterface: |
492 | 3424fc9f | Michal Privoznik | #
|
493 | 3424fc9f | Michal Privoznik | # @name: The name of interface for which info are being delivered |
494 | 3424fc9f | Michal Privoznik | #
|
495 | 3424fc9f | Michal Privoznik | # @hardware-address: Hardware address of @name |
496 | 3424fc9f | Michal Privoznik | #
|
497 | 3424fc9f | Michal Privoznik | # @ip-addresses: List of addresses assigned to @name |
498 | 3424fc9f | Michal Privoznik | #
|
499 | 3424fc9f | Michal Privoznik | # Since: 1.1 |
500 | 3424fc9f | Michal Privoznik | ## |
501 | 3424fc9f | Michal Privoznik | { 'type': 'GuestNetworkInterface', |
502 | 3424fc9f | Michal Privoznik | 'data': {'name': 'str', |
503 | 3424fc9f | Michal Privoznik | '*hardware-address': 'str', |
504 | 3424fc9f | Michal Privoznik | '*ip-addresses': ['GuestIpAddress'] } } |
505 | 3424fc9f | Michal Privoznik | |
506 | 3424fc9f | Michal Privoznik | ## |
507 | 3424fc9f | Michal Privoznik | # @guest-network-get-interfaces: |
508 | 3424fc9f | Michal Privoznik | #
|
509 | 3424fc9f | Michal Privoznik | # Get list of guest IP addresses, MAC addresses |
510 | 3424fc9f | Michal Privoznik | # and netmasks. |
511 | 3424fc9f | Michal Privoznik | #
|
512 | 3424fc9f | Michal Privoznik | # Returns: List of GuestNetworkInfo on success. |
513 | 3424fc9f | Michal Privoznik | #
|
514 | 3424fc9f | Michal Privoznik | # Since: 1.1 |
515 | 3424fc9f | Michal Privoznik | ## |
516 | 3424fc9f | Michal Privoznik | { 'command': 'guest-network-get-interfaces', |
517 | 3424fc9f | Michal Privoznik | 'returns': ['GuestNetworkInterface'] } |