5 hostinfo-protocol - hostinfo client commands and protocol
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.
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.
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.
30 =head2 ENABLING HOSTINFO FOR A GUEST
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)>.
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:>.
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.
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).
56 =head2 REQUESTS AND REPLIES
58 The basic protocol consists of sending a text-based command (the
59 request), and then reading the reply.
61 A typical request/reply cycle looks like:
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]).
69 The reply was C<"1.0 200 hello\r\n">.
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.
75 The request is a command followed by some number of arguments,
76 followed by CRLF. Commands available are described below.
78 The reply consists of:
84 The protocol version number, always C<1.x> in the current
85 iteration of the protocol.
87 =item E<lt>spaceE<gt> 200
89 The 3 digit status code (compatible with HTTP
90 status codes, see RFC 2616).
92 =item E<lt>spaceE<gt> hello
94 A space followed by the (optional) short response, B<or>:
96 =item multi-line response
98 Some commands (but not PING) can return a multi-line response.
102 A few commands return a multi-line response:
106 <<< Content-Type: text/xml
107 <<< Content-Length: 123
112 <<< <arch>i686</arch>
115 The multi-line response consists of headers and blank line and a body,
116 and is a compatible subset of HTTP (RFC 2616).
118 To tell the difference between a short, single-line response
119 and a multi-line response:
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">.
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">.
128 When a command returns an error, the request / response looks like
132 <<< 1.0 404 Command not found
134 As in HTTP, C<4xx> and C<5xx> status codes indicate classes of
135 error. Following the error code is an explanatory string.
137 Errors never have a multi-line response.
139 =head2 FREQUENCY OF REQUESTS
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.
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.
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
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
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.
167 Strings may not contain C<\0> characters in the middle, nor can they
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.
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.
178 Boolean arguments should be sent as I<true> or I<false>.
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}).
192 Returns C<echodata> back to the caller.
201 This command is used to test the hostinfo connection.
203 The possible responses to this are:
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.
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).
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
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.
243 =head1 COMMON STATUS CODES
247 All 2xx codes indicate the command completed successfully.
253 This is the usual status code that is returned to indicate
254 successful completion of the command.
260 All 4xx codes indicate a client error - malformed or unknown
265 =item 400 Bad request
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,
272 =item 401 Command disabled
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)>.
279 =item 404 Command not found
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.
285 =item 406 Too frequent
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).
297 All 5xx codes indicate a server error. The command was well-formed
298 but the host was unable to fulfil this request.
302 =item 500 Internal server error
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).
317 Use L<hostinfo-test(1)> to test hostinfo from the guest. This script
318 should work on any guest that can run Perl.
320 =head2 LOSS OF SERVICE
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.
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
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
337 =head2 SYNCHRONIZATION
339 Serial ports don't have any inherent way to synchronize the data
342 If the client believes it has lost synchronization, it can
343 regain it through the following steps:
353 Wait 5 seconds, discarding anything that is read on the
354 serial port during this time.
358 Send a PING command and check that the correct response is
363 =head2 MULTIPLE CLIENTS
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.
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.
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.
390 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
391 L<http://libvirt.org/>,
396 Richard W.M. Jones (C<rjones at redhat dot com>)
400 Copyright (C) 2009 Red Hat Inc.
401 L<http://fedoraproject.org/wiki/Features/Hostinfo>
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.
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.
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.