Merge branch 'master' of git+ssh://g-rjones@et.redhat.com/git/virt-hostinfo
[virt-hostinfo.git] / hostinfod / hostinfo-protocol.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 hostinfo-protocol - hostinfo client commands and protocol
6
7 =head1 SYNOPSIS
8
9  >>> PING "hello"
10  <<< 1.0 200 hello
11
12 =head1 DESCRIPTION
13
14 This manpage documents the hostinfo protocol.  For other aspects of
15 the hostinfo system, please see the associated manpages listed in the
16 I<SEE ALSO> section below.
17
18 Hostinfo is a protocol that virtual machines (guests) can use to
19 access limited information about the physical host that they are
20 running on.  For example, the virtual machine sees only virtual CPUs,
21 but using the hostinfo protocol you can query the number of physical
22 CPUs on the real machine.
23
24 Accessing hostinfo does not require any special libraries or software.
25 The hostinfo service is made available on a (virtual) serial port
26 attached to the guest.  Programs send text commands to this serial
27 port and read the replies.  The format of these commands and replies
28 are what this manpage documents.
29
30 =head2 ENABLING HOSTINFO FOR A GUEST
31
32 Before hostinfo can be used from a guest, it must be enabled by the
33 host's system administrator.  This is outside the scope of this
34 manpage - see L<hostinfo(8)>.
35
36 =head1 PROTOCOL
37
38 =head2 SERIAL PORT
39
40 The specifics of how you access serial ports under your operating
41 system are not covered in this manpage, but on Linux you would open a
42 special device like C</dev/ttyS1> and on DOS/Windows it would be
43 something like C<COM2:>.
44
45 Hostinfo is I<usually> exported to the guest through the second serial
46 port (C</dev/ttyS1> on Linux, C<COM2:> on DOS/Windows).  However the
47 system administrator can change this, and might do so particularly if
48 the serial ports are used for something else.  Contact the host system
49 administrator or run the L<hostinfo-status(8)> command on the host.
50
51 Software written to use the hostinfo protocol should be configurable
52 to use any serial port, I<or> it can try to determine the serial port
53 dynamically (although this may be risky/undesirable depending on what
54 the other serial ports are used for).
55
56 =head2 REQUESTS AND REPLIES
57
58 The basic protocol consists of sending a text-based command (the
59 request), and then reading the reply.
60
61 A typical request/reply cycle looks like:
62
63  >>> PING "hello"
64  <<< 1.0 200 hello
65
66 In this case the request was the literal string C<"PING \"hello\"\r\n">
67 (note: followed by carriage return [CR] and line feed [LF]).
68
69 The reply was C<"1.0 200 hello\r\n">.
70
71 The E<gt>E<gt>E<gt> and E<lt>E<lt>E<lt> symbols are not part of
72 the protocol.  They indicate messages sent to the host and
73 received from the host respectively.
74
75 The request is a command followed by some number of arguments,
76 followed by CRLF.  Commands available are described below.
77
78 The reply consists of:
79
80 =over 4
81
82 =item 1.0
83
84 The protocol version number, always C<1.x> in the current
85 iteration of the protocol.
86
87 =item E<lt>spaceE<gt> 200
88
89 The 3 digit status code (compatible with HTTP
90 status codes, see RFC 2616).
91
92 =item E<lt>spaceE<gt> hello
93
94 A space followed by the (optional) short response, B<or>:
95
96 =item multi-line response
97
98 Some commands (but not PING) can return a multi-line response.
99
100 =back
101
102 A few commands return a multi-line response:
103
104  >>> CAPABILITIES
105  <<< 1.0 200
106  <<< Content-Type: text/xml
107  <<< Content-Length: 123
108  <<<
109  <<< <capabilities>
110  <<<   <host>
111  <<<     <cpu>
112  <<<       <arch>i686</arch>
113  (etc.)
114
115 The multi-line response consists of headers and blank line and a body,
116 and is a compatible subset of HTTP (RFC 2616).
117
118 To tell the difference between a short, single-line response
119 and a multi-line response:
120
121 For the short response, the 3 digit HTTP status code will be followed
122 by a space character (even if the short response itself is empty).
123 For example C<"1.0 200 hello\r\n"> or C<"1.0 200 \r\n">.
124
125 For the multi-line response, the 3 digit HTTP status code will be
126 followed by the CR LF immediately.  For example C<"1.0 200\r\n">.
127
128 When a command returns an error, the request / response looks like
129 this:
130
131  >>> NOSUCHCOMMAND
132  <<< 1.0 404 Command not found
133
134 As in HTTP, C<4xx> and C<5xx> status codes indicate classes of
135 error.  Following the error code is an explanatory string.
136
137 Errors never have a multi-line response.
138
139 =head2 FREQUENCY OF REQUESTS
140
141 The guest will usually be limited in the frequency of requests it is
142 permitted to make.  This limit is set by the host system administrator
143 (see L<hostinfo(8)>).  If the guest exceeds this frequency too often,
144 then the result will be that the host stops answering requests.  See
145 I<LOSS OF SERVICE> below.
146
147 =head1 COMMANDS
148
149 Requests consist of a command followed by zero or more arguments.
150 Arguments are separated from the command and from each other by a
151 single space.  After the command and arguments, send CRLF.
152
153 Commands are written in this manpage all in uppercase.  However they
154 are not case sensitive, and you can send them in lowercase or mixed
155 case.
156
157 The request is always a single line, always consists only of 7 bit
158 printable ASCII bytes in the range 32-126 (apart from the final CRLF),
159 and must be less or equal to 4096 bytes in length (that includes the
160 final CRLF).
161
162 Arguments that are strings I<must> be quoted (using double-quotes).
163 Special characters inside the strings are escaped using backslashes.
164 The rules are precisely the same as for C literal strings, so for
165 example C<"\t"> is a string containing a single tab character.
166
167 Strings may not contain C<\0> characters in the middle, nor can they
168 be NULL.
169
170 Unless specified otherwise, the charset for strings is I<UTF-8>, but
171 any bytes outside the range 32-126 must be sent as escape sequences,
172 eg. C<"\xC2\xA3"> would encode the pound (currency) sign.
173
174 Arguments that are integers appear as integer literals, with optional
175 minus sign (C<->) before.  As with C, use a I<0> to indicate octal and
176 I<0x> to indicate hexadecimal literals.
177
178 Boolean arguments should be sent as I<true> or I<false>.
179
180 =head2 PING
181
182  PING echodata
183
184 =head3 Arguments
185
186 echodata [string]: A string that is echoed back in the response.  This
187 must be 1-16 characters in length, consisting I<only> of 7 bit ASCII
188 alpha-numeric characters ([0-9a-zA-Z]{1,16}).
189
190 =head3 Returns
191
192 Returns C<echodata> back to the caller.
193
194 =head3 Example
195
196  >>> PING "hello"
197  <<< 1.0 200 hello
198
199 =head3 Description
200
201 This command is used to test the hostinfo connection.
202
203 The possible responses to this are:
204
205 =over 4
206
207 =item *
208
209 The command succeeds and echos back the same C<echodata> string.  This
210 indicates that the connection through to the host daemon is working.
211
212 =item *
213
214 The command succeeds but echos back different C<echodata>.  Indicates
215 a synchronization error or some corruption on the serial port
216 channel (see I<SYNCHRONIZATION> below).
217
218 =item *
219
220 The command returns an error.  The error will indicate the problem.
221 Note as with all the other requests, you are limited in the rate you
222 can ping the host, by a setting that the host system administrator
223 controls.
224
225 =item *
226
227 The command returns nothing / hangs / returns a corrupted message.
228 See I<LOSS OF SERVICE>, I<SYNCHRONIZATION> below, and
229 I<TROUBLESHOOTING> in the L<hostinfo(8)> manual page.
230
231 =back
232
233
234
235
236
237
238
239
240
241
242
243 =head1 COMMON STATUS CODES
244
245 =head2 2xx
246
247 All 2xx codes indicate the command completed successfully.
248
249 =over 4
250
251 =item 200
252
253 This is the usual status code that is returned to indicate
254 successful completion of the command.
255
256 =back
257
258 =head2 4xx
259
260 All 4xx codes indicate a client error - malformed or unknown
261 command etc.
262
263 =over 4
264
265 =item 400 Bad request
266
267 This indicates a malformed request.  Causes include: No command,
268 incorrect number or type of arguments, not having a single space
269 between the command and each argument, not correctly quoting strings,
270 invalid integers.
271
272 =item 401 Command disabled
273
274 The host system administrator has configured hostinfo to prevent this
275 guest from using this command or accessing the requested piece of
276 information.  Contact the host system administrator and ask them to
277 adjust the configuration to allow this command, or see L<hostinfo(8)>.
278
279 =item 404 Command not found
280
281 No such command.  New commands can be added in later revisions of this
282 protocol.  If you try to use these commands with older hostinfo
283 services, you will receive this error.
284
285 =item 406 Too frequent
286
287 This indicates that the client is trying to access the requested
288 resource too often.  The client should access the resource no more
289 frequently than is configured by the host system administrator.
290 (After too many of these errors, the hostinfo service will be
291 completely disabled: see I<LOSS OF SERVICE> below).
292
293 =back
294
295 =head2 5xx
296
297 All 5xx codes indicate a server error.  The command was well-formed
298 but the host was unable to fulfil this request.
299
300 =over 4
301
302 =item 500 Internal server error
303
304 This indicates a problem on the host side - for example, it might be
305 that the hostinfo daemon cannot contact libvirt.  For security
306 reasons, the cause of these failures is never revealed to the guest.
307 However it is logged on the host side, so the host system
308 administrator can determine the precise cause of the error.  (See also
309 I<TROUBLESHOOTING> in L<hostinfo(8)> manpage).
310
311 =back
312
313 =head1 OTHER ISSUES
314
315 =head2 TESTING
316
317 Use L<hostinfo-test(1)> to test hostinfo from the guest.  This script
318 should work on any guest that can run Perl.
319
320 =head2 LOSS OF SERVICE
321
322 The daemon on the host side that services hostinfo requests is written
323 defensively.  In particular, it will refuse service (eventually just
324 ignoring the guest completely) if the guest behaves badly, which
325 includes: trying to flood the host with data, sending requests more
326 frequently than the host system administrator has configured.
327
328 In the case where the guest loses service (gets no response from
329 any commands), the only solution is to contact the host system
330 administrator.
331
332 The host system administrator can restart the daemon and/or the guest,
333 which should restore service.  The host system administrator can also
334 troubleshoot problems by following the I<TROUBLESHOOTING> section in
335 L<hostinfo(8)>.
336
337 =head2 SYNCHRONIZATION
338
339 Serial ports don't have any inherent way to synchronize the data
340 stream.
341
342 If the client believes it has lost synchronization, it can
343 regain it through the following steps:
344
345 =over 4
346
347 =item 1.
348
349 Send CR LF twice.
350
351 =item 2.
352
353 Wait 5 seconds, discarding anything that is read on the
354 serial port during this time.
355
356 =item 3.
357
358 Send a PING command and check that the correct response is
359 received.
360
361 =back
362
363 =head2 MULTIPLE CLIENTS
364
365 The serial port only supports reading a single command at a time.  If
366 multiple clients try to connect to the serial port and send commands
367 at the same time, then the results will be unpredictable.
368
369 If you need to have multiple clients accessing hostinfo inside a
370 guest, then you must run some sort of service or daemon inside the
371 guest which multiplexes these requests onto the single serial port.
372
373 The protocol does not support "pipelining" requests (that is, issuing
374 more than one request at a time or overlapping requests and replies).
375 If multiple commands are sent at once, then the daemon may discard all
376 but the final command.
377
378 =head1 FILES
379
380 =over 4
381
382 =item /dev/ttyS1
383
384 =back
385
386 =head1 SEE ALSO
387
388 L<hostinfo(8)>,
389 L<hostinfo-test(1)>,
390 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
391 L<http://libvirt.org/>,
392 L<RFC 2616>.
393
394 =head1 AUTHORS
395
396 Richard W.M. Jones (C<rjones at redhat dot com>)
397
398 =head1 COPYRIGHT
399
400 Copyright (C) 2009 Red Hat Inc.
401 L<http://fedoraproject.org/wiki/Features/Hostinfo>
402
403 This program is free software; you can redistribute it and/or modify
404 it under the terms of the GNU General Public License as published by
405 the Free Software Foundation; either version 2 of the License, or
406 (at your option) any later version.
407
408 This program is distributed in the hope that it will be useful,
409 but WITHOUT ANY WARRANTY; without even the implied warranty of
410 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
411 GNU General Public License for more details.
412
413 You should have received a copy of the GNU General Public License
414 along with this program; if not, write to the Free Software
415 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.