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 Number of available physical cores in the host.
195 Returns the number of physical cores in the host that are available to
196 the virtualization system (ie. have not been disabled). See also
197 I<PHYSCPUS> which would in almost every case return the same number.
199 =head2 CORESPERSOCKET
205 Number of cores per socket in the physical host.
214 Returns the number of physical cores per socket in the host.
222 Amount of memory in host, in kilobytes.
231 Returns the total memory in the host, in kilobytes.
239 Speed of host cores in MHz.
248 Returns the clockspeed of host cores in MHz.
256 The host CPU model, a string such as C<i686> or C<x86_64>.
265 Returns the host CPU model.
273 The number of NUMA nodes in the host.
282 Returns the number of NUMA nodes in the host. If this is 1
283 then host memory access is uniform.
291 The number of physical cores.
300 Returns the number of physical cores available on the host.
302 In some (highly unusual) situations, some cores might be
303 disabled. To get the number of cores available to do work,
306 Note that it is common for the guest not to see all of the
307 physical CPUs (virtual CPUs E<lt> physical CPUs).
315 echodata [string]: A string that is echoed back in the response. This
316 must be 1-16 characters in length, consisting I<only> of 7 bit ASCII
317 alpha-numeric characters ([0-9a-zA-Z]{1,16}).
321 Returns C<echodata> back to the caller.
330 This command is used to test the hostinfo connection.
332 The possible responses to this are:
338 The command succeeds and echos back the same C<echodata> string. This
339 indicates that the connection through to the host daemon is working.
343 The command succeeds but echos back different C<echodata>. Indicates
344 a synchronization error or some corruption on the serial port
345 channel (see I<SYNCHRONIZATION> below).
349 The command returns an error. The error will indicate the problem.
350 Note as with all the other requests, you are limited in the rate you
351 can ping the host, by a setting that the host system administrator
356 The command returns nothing / hangs / returns a corrupted message.
357 See I<LOSS OF SERVICE>, I<SYNCHRONIZATION> below, and
358 I<TROUBLESHOOTING> in the L<hostinfo(8)> manual page.
362 =head2 SOCKETSPERNODE
368 The number of sockets on each node.
377 Returns the number CPU sockets in each NUMA node.
379 =head2 THREADSPERCORE
385 The number of hyperthreads per core.
394 If hyperthreading is enabled on the host, this returns
395 the number of threads on each real core. The numbers
396 returned by C<AVAILCPUS> and C<PHYSCPUS> are multiplied
409 =head1 COMMON STATUS CODES
413 All 2xx codes indicate the command completed successfully.
419 This is the usual status code that is returned to indicate
420 successful completion of the command.
426 All 4xx codes indicate a client error - malformed or unknown
431 =item 400 Bad request
433 This indicates a malformed request. Causes include: No command,
434 incorrect number or type of arguments, not having a single space
435 between the command and each argument, not correctly quoting strings,
438 =item 401 Command disabled
440 The host system administrator has configured hostinfo to prevent this
441 guest from using this command or accessing the requested piece of
442 information. Contact the host system administrator and ask them to
443 adjust the configuration to allow this command, or see L<hostinfo(8)>.
445 =item 404 Command not found
447 No such command. New commands can be added in later revisions of this
448 protocol. If you try to use these commands with older hostinfo
449 services, you will receive this error.
451 =item 406 Too frequent
453 This indicates that the client is trying to access the requested
454 resource too often. The client should access the resource no more
455 frequently than is configured by the host system administrator.
456 (After too many of these errors, the hostinfo service will be
457 completely disabled: see I<LOSS OF SERVICE> below).
463 All 5xx codes indicate a server error. The command was well-formed
464 but the host was unable to fulfil this request.
468 =item 500 Internal server error
470 This indicates a problem on the host side - for example, it might be
471 that the hostinfo daemon cannot contact libvirt. For security
472 reasons, the cause of these failures is never revealed to the guest.
473 However it is logged on the host side, so the host system
474 administrator can determine the precise cause of the error. (See also
475 I<TROUBLESHOOTING> in L<hostinfo(8)> manpage).
483 Use L<hostinfo-test(1)> to test hostinfo from the guest. This script
484 should work on any guest that can run Perl.
486 =head2 LOSS OF SERVICE
488 The daemon on the host side that services hostinfo requests is written
489 defensively. In particular, it will refuse service (eventually just
490 ignoring the guest completely) if the guest behaves badly, which
491 includes: trying to flood the host with data, sending requests more
492 frequently than the host system administrator has configured.
494 In the case where the guest loses service (gets no response from
495 any commands), the only solution is to contact the host system
498 The host system administrator can restart the daemon and/or the guest,
499 which should restore service. The host system administrator can also
500 troubleshoot problems by following the I<TROUBLESHOOTING> section in
503 =head2 SYNCHRONIZATION
505 Serial ports don't have any inherent way to synchronize the data
508 If the client believes it has lost synchronization, it can
509 regain it through the following steps:
519 Wait 5 seconds, discarding anything that is read on the
520 serial port during this time.
524 Send a PING command and check that the correct response is
529 =head2 MULTIPLE CLIENTS
531 The serial port only supports reading a single command at a time. If
532 multiple clients try to connect to the serial port and send commands
533 at the same time, then the results will be unpredictable.
535 If you need to have multiple clients accessing hostinfo inside a
536 guest, then you must run some sort of service or daemon inside the
537 guest which multiplexes these requests onto the single serial port.
539 The protocol does not support "pipelining" requests (that is, issuing
540 more than one request at a time or overlapping requests and replies).
541 If multiple commands are sent at once, then the daemon may discard all
542 but the final command.
556 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
557 L<http://libvirt.org/>,
562 Richard W.M. Jones (C<rjones at redhat dot com>)
566 Copyright (C) 2009 Red Hat Inc.
567 L<http://fedoraproject.org/wiki/Features/Hostinfo>
569 This program is free software; you can redistribute it and/or modify
570 it under the terms of the GNU General Public License as published by
571 the Free Software Foundation; either version 2 of the License, or
572 (at your option) any later version.
574 This program is distributed in the hope that it will be useful,
575 but WITHOUT ANY WARRANTY; without even the implied warranty of
576 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
577 GNU General Public License for more details.
579 You should have received a copy of the GNU General Public License
580 along with this program; if not, write to the Free Software
581 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.