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 On Linux/Unix guests, you will need to disable echo and set the serial
57 port to raw mode. The easiest way to do this is to execute the
60 stty raw -echo < /dev/ttyS1
62 although it can also be done using terminal ioctls (see L<ioctl(2)>
63 and L<ioctl_list(2)>).
65 =head2 REQUESTS AND REPLIES
67 The basic protocol consists of sending a text-based command (the
68 request), and then reading the reply.
70 A typical request/reply cycle looks like:
75 In this case the request was the literal string C<"PING \"hello\"\r\n">
76 (note: followed by carriage return [CR] and line feed [LF]).
78 The reply was C<"1.0 200 hello\r\n">.
80 The E<lt>E<lt>E<lt> and E<gt>E<gt>E<gt> symbols are not part of
81 the protocol. They indicate messages sent to the host and
82 received from the host respectively.
84 The request is a command followed by some number of arguments,
85 followed by CRLF. Commands available are described below.
87 The reply consists of:
93 The protocol version number, always C<1.x> in the current
94 iteration of the protocol.
96 =item E<lt>spaceE<gt> 200
98 The 3 digit status code (compatible with HTTP
99 status codes, see RFC 2616).
101 =item E<lt>spaceE<gt> hello
103 A space followed by the (optional) short response, B<or>:
105 =item multi-line response
107 Some commands (but not PING) can return a multi-line response.
111 A few commands return a multi-line response:
115 >>> Content-Type: text/xml
116 >>> Content-Length: 123
121 >>> <arch>i686</arch>
124 The multi-line response consists of headers and blank line and a body,
125 and is a compatible subset of HTTP (RFC 2616).
127 To tell the difference between a short, single-line response
128 and a multi-line response:
130 For the short response, the 3 digit HTTP status code will be followed
131 by a space character (even if the short response itself is empty).
132 For example C<"1.0 200 hello\r\n"> or C<"1.0 200 \r\n">.
134 For the multi-line response, the 3 digit HTTP status code will be
135 followed by the CR LF immediately. For example C<"1.0 200\r\n">.
137 When a command returns an error, the request / response looks like
141 >>> 1.0 404 Command not found
143 As in HTTP, C<4xx> and C<5xx> status codes indicate classes of
144 error. Following the error code is an explanatory string.
146 Errors never have a multi-line response.
148 =head2 FREQUENCY OF REQUESTS
150 The guest will usually be limited in the frequency of requests it is
151 permitted to make. This limit is set by the host system administrator
152 (see L<hostinfo(8)>). If the guest exceeds this frequency too often,
153 then the result will be that the host stops answering requests. See
154 I<LOSS OF SERVICE> below.
158 Requests consist of a command followed by zero or more arguments.
159 Arguments are separated from the command and from each other by a
160 single space. After the command and arguments, send CRLF.
162 Commands are written in this manpage all in uppercase. However they
163 are not case sensitive, and you can send them in lowercase or mixed
166 The request is always a single line, always consists only of 7 bit
167 printable ASCII bytes in the range 32-126 (apart from the final CRLF),
168 and must be less or equal to 4096 bytes in length (that includes the
171 Arguments that are strings I<must> be quoted (using double-quotes).
172 Special characters inside the strings are escaped using backslashes.
173 The rules are precisely the same as for C literal strings, so for
174 example C<"\t"> is a string containing a single tab character.
176 Strings may not contain C<\0> characters in the middle, nor can they
179 Unless specified otherwise, the charset for strings is I<UTF-8>, but
180 any bytes outside the range 32-126 must be sent as escape sequences,
181 eg. C<"\xC2\xA3"> would encode the pound (currency) sign.
183 Arguments that are integers appear as integer literals, with optional
184 minus sign (C<->) before. As with C, use a I<0> to indicate octal and
185 I<0x> to indicate hexadecimal literals.
187 Boolean arguments should be sent as I<true> or I<false>.
195 Number of available physical cores in the host.
204 Returns the number of physical cores in the host that are available to
205 the virtualization system (ie. have not been disabled). See also
206 I<PHYSCPUS> which would in almost every case return the same number.
208 =head2 CORESPERSOCKET
214 Number of cores per socket in the physical host.
223 Returns the number of physical cores per socket in the host.
231 Amount of memory in host, in kilobytes.
240 Returns the total memory in the host, in kilobytes.
248 Speed of host cores in MHz.
257 Returns the clockspeed of host cores in MHz.
265 The host CPU model, a string such as C<i686> or C<x86_64>.
274 Returns the host CPU model.
282 The number of NUMA nodes in the host.
291 Returns the number of NUMA nodes in the host. If this is 1
292 then host memory access is uniform.
300 The number of physical cores.
309 Returns the number of physical cores available on the host.
311 In some (highly unusual) situations, some cores might be
312 disabled. To get the number of cores available to do work,
315 Note that it is common for the guest not to see all of the
316 physical CPUs (virtual CPUs E<lt> physical CPUs).
324 echodata [string]: A string that is echoed back in the response. This
325 must be 1-16 characters in length, consisting I<only> of 7 bit ASCII
326 alpha-numeric characters ([0-9a-zA-Z]{1,16}).
330 Returns C<echodata> back to the caller.
339 This command is used to test the hostinfo connection.
341 The possible responses to this are:
347 The command succeeds and echos back the same C<echodata> string. This
348 indicates that the connection through to the host daemon is working.
352 The command succeeds but echos back different C<echodata>. Indicates
353 a synchronization error or some corruption on the serial port
354 channel (see I<SYNCHRONIZATION> below).
358 The command returns an error. The error will indicate the problem.
359 Note as with all the other requests, you are limited in the rate you
360 can ping the host, by a setting that the host system administrator
365 The command returns nothing / hangs / returns a corrupted message.
366 See I<LOSS OF SERVICE>, I<SYNCHRONIZATION> below, and
367 I<TROUBLESHOOTING> in the L<hostinfo(8)> manual page.
371 =head2 SOCKETSPERNODE
377 The number of sockets on each node.
386 Returns the number CPU sockets in each NUMA node.
388 =head2 THREADSPERCORE
394 The number of hyperthreads per core.
403 If hyperthreading is enabled on the host, this returns
404 the number of threads on each real core. The numbers
405 returned by C<AVAILCPUS> and C<PHYSCPUS> are multiplied
418 =head1 COMMON STATUS CODES
422 All 2xx codes indicate the command completed successfully.
428 This is the usual status code that is returned to indicate
429 successful completion of the command.
435 All 4xx codes indicate a client error - malformed or unknown
440 =item 400 Bad request
442 This indicates a malformed request. Causes include: No command,
443 incorrect number or type of arguments, not having a single space
444 between the command and each argument, not correctly quoting strings,
447 =item 401 Command disabled
449 The host system administrator has configured hostinfo to prevent this
450 guest from using this command or accessing the requested piece of
451 information. Contact the host system administrator and ask them to
452 adjust the configuration to allow this command, or see L<hostinfo(8)>.
454 =item 404 Command not found
456 No such command. New commands can be added in later revisions of this
457 protocol. If you try to use these commands with older hostinfo
458 services, you will receive this error.
460 =item 406 Too frequent
462 This indicates that the client is trying to access the requested
463 resource too often. The client should access the resource no more
464 frequently than is configured by the host system administrator.
465 (After too many of these errors, the hostinfo service will be
466 completely disabled: see I<LOSS OF SERVICE> below).
472 All 5xx codes indicate a server error. The command was well-formed
473 but the host was unable to fulfil this request.
477 =item 500 Internal server error
479 This indicates a problem on the host side - for example, it might be
480 that the hostinfo daemon cannot contact libvirt. For security
481 reasons, the cause of these failures is never revealed to the guest.
482 However it is logged on the host side, so the host system
483 administrator can determine the precise cause of the error. (See also
484 I<TROUBLESHOOTING> in L<hostinfo(8)> manpage).
492 Use L<hostinfo-test(1)> to test hostinfo from the guest. This script
493 should work on any guest that can run Perl.
495 You can also send commands directly to the daemon on the host
496 (just for testing purposes) using the I<nc> program:
498 # nc -CUl /var/lib/hostinfo/test-test
500 =head2 LOSS OF SERVICE
502 The daemon on the host side that services hostinfo requests is written
503 defensively. In particular, it will refuse service (eventually just
504 ignoring the guest completely) if the guest behaves badly, which
505 includes: trying to flood the host with data, sending requests more
506 frequently than the host system administrator has configured.
508 In the case where the guest loses service (gets no response from
509 any commands), the only solution is to contact the host system
512 The host system administrator can restart the daemon and/or the guest,
513 which should restore service. The host system administrator can also
514 troubleshoot problems by following the I<TROUBLESHOOTING> section in
517 =head2 SYNCHRONIZATION
519 Serial ports don't have any inherent way to synchronize the data
522 If the client believes it has lost synchronization, it can
523 regain it through the following steps:
533 Wait 5 seconds, discarding anything that is read on the
534 serial port during this time.
538 Send a PING command and check that the correct response is
543 =head2 MULTIPLE CLIENTS
545 The serial port only supports reading a single command at a time. If
546 multiple clients try to connect to the serial port and send commands
547 at the same time, then the results will be unpredictable.
549 If you need to have multiple clients accessing hostinfo inside a
550 guest, then you must run some sort of service or daemon inside the
551 guest which multiplexes these requests onto the single serial port.
553 The protocol does not support "pipelining" requests (that is, issuing
554 more than one request at a time or overlapping requests and replies).
555 If multiple commands are sent at once, then the daemon may discard all
556 but the final command.
570 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
571 L<http://libvirt.org/>,
576 Richard W.M. Jones (C<rjones at redhat dot com>)
580 Copyright (C) 2009 Red Hat Inc.
581 L<http://fedoraproject.org/wiki/Features/Hostinfo>
583 This program is free software; you can redistribute it and/or modify
584 it under the terms of the GNU General Public License as published by
585 the Free Software Foundation; either version 2 of the License, or
586 (at your option) any later version.
588 This program is distributed in the hope that it will be useful,
589 but WITHOUT ANY WARRANTY; without even the implied warranty of
590 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
591 GNU General Public License for more details.
593 You should have received a copy of the GNU General Public License
594 along with this program; if not, write to the Free Software
595 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.