blob: 5f8a18d4d887da7e4d29638bf76e6da1740b82f1 [file] [log] [blame]
Michael Rothe3d4d252011-07-19 15:41:55 -05001# *-*- Mode: Python -*-*
2
3##
4# @guest-sync:
5#
6# Echo back a unique integer value
7#
8# This is used by clients talking to the guest agent over the
9# wire to ensure the stream is in sync and doesn't contain stale
10# data from previous client. All guest agent responses should be
11# ignored until the provided unique integer value is returned,
12# and it is up to the client to handle stale whole or
13# partially-delivered JSON text in such a way that this response
14# can be obtained.
15#
Stefan Weile7d81002011-12-10 00:19:46 +010016# Such clients should also precede this command
Michael Rothe3d4d252011-07-19 15:41:55 -050017# with a 0xFF byte to make such the guest agent flushes any
18# partially read JSON data from a previous session.
19#
20# @id: randomly generated 64-bit integer
21#
22# Returns: The unique integer id passed in by the client
23#
24# Since: 0.15.0
25##
26{ 'command': 'guest-sync'
27 'data': { 'id': 'int' },
28 'returns': 'int' }
29
30##
31# @guest-ping:
32#
33# Ping the guest agent, a non-error return implies success
34#
35# Since: 0.15.0
36##
37{ 'command': 'guest-ping' }
38
39##
40# @guest-info:
41#
42# Get some information about the guest agent.
43#
44# Since: 0.15.0
45##
Michael Rothbf95c0d2011-12-06 22:03:43 -060046{ 'type': 'GuestAgentCommandInfo',
47 'data': { 'name': 'str', 'enabled': 'bool' } }
48{ 'type': 'GuestAgentInfo',
49 'data': { 'version': 'str',
50 'supported_commands': ['GuestAgentCommandInfo'] } }
Michael Rothe3d4d252011-07-19 15:41:55 -050051{ 'command': 'guest-info',
52 'returns': 'GuestAgentInfo' }
53
54##
55# @guest-shutdown:
56#
57# Initiate guest-activated shutdown. Note: this is an asynchronous
58# shutdown request, with no guaruntee of successful shutdown. Errors
59# will be logged to guest's syslog.
60#
61# @mode: #optional "halt", "powerdown" (default), or "reboot"
62#
63# Returns: Nothing on success
64#
65# Since: 0.15.0
66##
67{ 'command': 'guest-shutdown', 'data': { '*mode': 'str' } }
68
69##
70# @guest-file-open:
71#
72# Open a file in the guest and retrieve a file handle for it
73#
74# @filepath: Full path to the file in the guest to open.
75#
76# @mode: #optional open mode, as per fopen(), "r" is the default.
77#
78# Returns: Guest file handle on success.
79#
80# Since: 0.15.0
81##
82{ 'command': 'guest-file-open',
83 'data': { 'path': 'str', '*mode': 'str' },
84 'returns': 'int' }
85
86##
87# @guest-file-close:
88#
89# Close an open file in the guest
90#
91# @handle: filehandle returned by guest-file-open
92#
93# Returns: Nothing on success.
94#
95# Since: 0.15.0
96##
97{ 'command': 'guest-file-close',
98 'data': { 'handle': 'int' } }
99
100##
101# @guest-file-read:
102#
103# Read from an open file in the guest. Data will be base64-encoded
104#
105# @handle: filehandle returned by guest-file-open
106#
107# @count: #optional maximum number of bytes to read (default is 4KB)
108#
109# Returns: GuestFileRead on success. Note: count is number of bytes read
110# *before* base64 encoding bytes read.
111#
112# Since: 0.15.0
113##
114{ 'type': 'GuestFileRead',
115 'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
116
117{ 'command': 'guest-file-read',
118 'data': { 'handle': 'int', '*count': 'int' },
119 'returns': 'GuestFileRead' }
120
121##
122# @guest-file-write:
123#
124# Write to an open file in the guest.
125#
126# @handle: filehandle returned by guest-file-open
127#
128# @buf-b64: base64-encoded string representing data to be written
129#
130# @count: #optional bytes to write (actual bytes, after base64-decode),
131# default is all content in buf-b64 buffer after base64 decoding
132#
133# Returns: GuestFileWrite on success. Note: count is the number of bytes
134# base64-decoded bytes written
135#
136# Since: 0.15.0
137##
138{ 'type': 'GuestFileWrite',
139 'data': { 'count': 'int', 'eof': 'bool' } }
140{ 'command': 'guest-file-write',
141 'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
142 'returns': 'GuestFileWrite' }
143
144##
145# @guest-file-seek:
146#
147# Seek to a position in the file, as with fseek(), and return the
148# current file position afterward. Also encapsulates ftell()'s
149# functionality, just Set offset=0, whence=SEEK_CUR.
150#
151# @handle: filehandle returned by guest-file-open
152#
153# @offset: bytes to skip over in the file stream
154#
155# @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
156#
157# Returns: GuestFileSeek on success.
158#
159# Since: 0.15.0
160##
161{ 'type': 'GuestFileSeek',
162 'data': { 'position': 'int', 'eof': 'bool' } }
163
164{ 'command': 'guest-file-seek',
165 'data': { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
166 'returns': 'GuestFileSeek' }
167
168##
169# @guest-file-flush:
170#
171# Write file changes bufferred in userspace to disk/kernel buffers
172#
173# @handle: filehandle returned by guest-file-open
174#
175# Returns: Nothing on success.
176#
177# Since: 0.15.0
178##
179{ 'command': 'guest-file-flush',
180 'data': { 'handle': 'int' } }
181
182##
183# @guest-fsfreeze-status:
184#
185# Get guest fsfreeze state. error state indicates failure to thaw 1 or more
186# previously frozen filesystems, or failure to open a previously cached
187# filesytem (filesystem unmounted/directory changes, etc).
188#
189# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
190#
191# Since: 0.15.0
192##
193{ 'enum': 'GuestFsfreezeStatus',
194 'data': [ 'thawed', 'frozen', 'error' ] }
195{ 'command': 'guest-fsfreeze-status',
196 'returns': 'GuestFsfreezeStatus' }
197
198##
199# @guest-fsfreeze-freeze:
200#
201# Sync and freeze all non-network guest filesystems
202#
203# Returns: Number of file systems frozen on success
204#
205# Since: 0.15.0
206##
207{ 'command': 'guest-fsfreeze-freeze',
208 'returns': 'int' }
209
210##
211# @guest-fsfreeze-thaw:
212#
213# Unfreeze frozen guest fileystems
214#
215# Returns: Number of file systems thawed
216# If error, -1 (unknown error) or -errno
217#
218# Since: 0.15.0
219##
220{ 'command': 'guest-fsfreeze-thaw',
221 'returns': 'int' }