--- /dev/null
+=encoding utf8
+
+=head1 NAME
+
+hostinfo-protocol - hostinfo client commands and protocol
+
+=head1 SYNOPSIS
+
+ >>> PING "hello"
+ <<< 1.0 200 hello
+
+=head1 DESCRIPTION
+
+This manpage documents the hostinfo protocol. For other aspects of
+the hostinfo system, please see the associated manpages listed in the
+I<SEE ALSO> section below.
+
+Hostinfo is a protocol that virtual machines (guests) can use to
+access limited information about the physical host that they are
+running on. For example, the virtual machine sees only virtual CPUs,
+but using the hostinfo protocol you can query the number of physical
+CPUs on the real machine.
+
+Accessing hostinfo does not require any special libraries or software.
+The hostinfo service is made available on a (virtual) serial port
+attached to the guest. Programs send text commands to this serial
+port and read the replies. The format of these commands and replies
+are what this manpage documents.
+
+=head2 ENABLING HOSTINFO FOR A GUEST
+
+Before hostinfo can be used from a guest, it must be enabled by the
+host's system administrator. This is outside the scope of this
+manpage - see L<hostinfo(8)>.
+
+=head1 PROTOCOL
+
+=head2 SERIAL PORT
+
+The specifics of how you access serial ports under your operating
+system are not covered in this manpage, but on Linux you would open a
+special device like C</dev/ttyS1> and on DOS/Windows it would be
+something like C<COM2:>.
+
+Hostinfo is I<usually> exported to the guest through the second serial
+port (C</dev/ttyS1> on Linux, C<COM2:> on DOS/Windows). However the
+system administrator can change this, and might do so particularly if
+the serial ports are used for something else. Contact the host system
+administrator or run the L<hostinfo-status(8)> command on the host.
+
+Software written to use the hostinfo protocol should be configurable
+to use any serial port, I<or> it can try to determine the serial port
+dynamically (although this may be risky/undesirable depending on what
+the other serial ports are used for).
+
+=head2 REQUESTS AND REPLIES
+
+The basic protocol consists of sending a text-based command (the
+request), and then reading the reply.
+
+A typical request/reply cycle looks like:
+
+ >>> PING "hello"
+ <<< 1.0 200 hello
+
+In this case the request was the literal string C<"PING \"hello\"\r\n">
+(note: followed by carriage return [CR] and line feed [LF]).
+
+The reply was C<"1.0 200 hello\r\n">.
+
+The E<gt>E<gt>E<gt> and E<lt>E<lt>E<lt> symbols are not part of
+the protocol. They indicate messages sent to the host and
+received from the host respectively.
+
+The request is a command followed by some number of arguments,
+followed by CRLF. Commands available are described below.
+
+The reply consists of:
+
+=over 4
+
+=item 1.0
+
+The protocol version number, always C<1.x> in the current
+iteration of the protocol.
+
+=item E<lt>spaceE<gt> 200
+
+The 3 digit status code (compatible with HTTP
+status codes, see RFC 2616).
+
+=item E<lt>spaceE<gt> hello
+
+A space followed by the (optional) short response, B<or>:
+
+=item multi-line response
+
+Some commands (but not PING) can return a multi-line response.
+
+=back
+
+A few commands return a multi-line response:
+
+ >>> CAPABILITIES
+ <<< 1.0 200
+ <<< Content-Type: text/xml
+ <<< Content-Length: 123
+ <<<
+ <<< <capabilities>
+ <<< <host>
+ <<< <cpu>
+ <<< <arch>i686</arch>
+ (etc.)
+
+The multi-line response consists of headers and blank line and a body,
+and is a compatible subset of HTTP (RFC 2616).
+
+To tell the difference between a short, single-line response
+and a multi-line response:
+
+For the short response, the 3 digit HTTP status code will be followed
+by a space character (even if the short response itself is empty).
+For example C<"1.0 200 hello\r\n"> or C<"1.0 200 \r\n">.
+
+For the multi-line response, the 3 digit HTTP status code will be
+followed by the CR LF immediately. For example C<"1.0 200\r\n">.
+
+When a command returns an error, the request / response looks like
+this:
+
+ >>> NOSUCHCOMMAND
+ <<< 1.0 404 Command not found
+
+As in HTTP, C<4xx> and C<5xx> status codes indicate classes of
+error. Following the error code is an explanatory string.
+
+Errors never have a multi-line response.
+
+=head2 FREQUENCY OF REQUESTS
+
+The guest will usually be limited in the frequency of requests it is
+permitted to make. This limit is set by the host system administrator
+(see L<hostinfo(8)>). If the guest exceeds this frequency too often,
+then the result will be that the host stops answering requests. See
+I<LOSS OF SERVICE> below.
+
+=head1 COMMANDS
+
+Requests consist of a command followed by zero or more arguments.
+Arguments are separated from the command and from each other by a
+single space. After the command and arguments, send CRLF.
+
+Commands are written in this manpage all in uppercase. However they
+are not case sensitive, and you can send them in lowercase or mixed
+case.
+
+The request is always a single line, always consists only of 7 bit
+printable ASCII (apart from the final CRLF), and must be less or equal
+to 4096 characters in length (that includes the final CRLF).
+
+Arguments that are strings I<must> be quoted (using double-quotes).
+Special characters inside the strings are escaped using backslashes.
+The rules are precisely the same as for C literal strings, so
+for example C<"\t"> is a string containing a single tab character.
+
+Arguments that are integers appear as integer literals.
+
+Other argument types that are allowed are: booleans (I<true> or
+I<false>).
+
+Note that integers, booleans must never be quoted.
+
+=head2 PING
+
+ PING echodata
+
+=head3 Arguments
+
+echodata [string]: A string that is echoed back in the response. This
+must be 1-16 characters in length, consisting I<only> of 7 bit ASCII
+alpha-numeric characters ([0-9a-zA-Z]{1,16}).
+
+=head3 Returns
+
+Returns C<echodata> back to the caller.
+
+=head3 Description
+
+This command is used to test the hostinfo connection.
+
+The possible responses to this are:
+
+=over 4
+
+=item *
+
+The command succeeds and echos back the same C<echodata> string.
+This indicates that everything is working.
+
+=item *
+
+The command succeeds but echos back different C<echodata>. Indicates
+a synchronization error or some corruption on the serial port
+channel (see I<SYNCHRONIZATION> below).
+
+=item *
+
+The command returns an error. The error will indicate the problem.
+Note as with all the other requests, you are limited in the rate you
+can ping the host, by a setting that the host system administrator
+controls.
+
+=item *
+
+The command returns nothing / hangs / returns a corrupted message.
+See I<LOSS OF SERVICE>, I<SYNCHRONIZATION> below, and
+I<TROUBLESHOOTING> in the L<hostinfo(8)> manual page.
+
+=back
+
+
+
+
+
+
+
+
+
+
+
+=head1 COMMON STATUS CODES
+
+=head2 2xx
+
+All 2xx codes indicate the command completed successfully.
+
+=over 4
+
+=item 200
+
+This is the usual status code that is returned to indicate
+successful completion of the command.
+
+=back
+
+=head2 4xx
+
+All 4xx codes indicate a client error - malformed or unknown
+command etc.
+
+=over 4
+
+=item 400 Bad request
+
+This indicates a malformed request. Causes include: No command,
+incorrect number or type of arguments, not having a single space
+between the command and each argument, not correctly quoting strings,
+invalid integers.
+
+=item 401 Command disabled
+
+The host system administrator has configured hostinfo to prevent this
+guest from using this command or accessing the requested piece of
+information. Contact the host system administrator and ask them to
+adjust the configuration to allow this command, or see L<hostinfo(8)>.
+
+=item 404 Command not found
+
+No such command. New commands can be added in later revisions of this
+protocol. If you try to use these commands with older hostinfo
+services, you will receive this error.
+
+=item 406 Too frequent
+
+This indicates that the client is trying to access the requested
+resource too often. The client should access the resource no more
+frequently than is configured by the host system administrator.
+(After too many of these errors, the hostinfo service will be
+completely disabled: see I<LOSS OF SERVICE> below).
+
+=back
+
+=head2 5xx
+
+All 5xx codes indicate a server error. The command was well-formed
+but the host was unable to fulfil this request.
+
+=over 4
+
+=item 500 Internal server error
+
+This indicates a problem on the host side - for example, it might be
+that the hostinfo daemon cannot contact libvirt. For security
+reasons, the cause of these failures is never revealed to the guest.
+However it is logged on the host side, so the host system
+administrator can determine the precise cause of the error. (See also
+I<TROUBLESHOOTING> in L<hostinfo(8)> manpage).
+
+=back
+
+=head1 OTHER ISSUES
+
+=head2 TESTING
+
+Use L<hostinfo-test(1)> to test hostinfo from the guest. This script
+should work on any guest that can run Perl.
+
+=head2 LOSS OF SERVICE
+
+The daemon on the host side that services hostinfo requests is written
+defensively. In particular, it will refuse service (eventually just
+ignoring the guest completely) if the guest behaves badly, which
+includes: trying to flood the host with data, sending requests more
+frequently than the host system administrator has configured.
+
+In the case where the guest loses service (gets no response from
+any commands), the only solution is to contact the host system
+administrator.
+
+The host system administrator can restart the daemon and/or the guest,
+which should restore service. The host system administrator can also
+troubleshoot problems by following the I<TROUBLESHOOTING> section in
+L<hostinfo(8)>.
+
+=head2 SYNCHRONIZATION
+
+Serial ports don't have any inherent way to synchronize the data
+stream.
+
+If the client believes it has lost synchronization, it can
+regain it through the following steps:
+
+=over 4
+
+=item 1.
+
+Send CR LF twice.
+
+=item 2.
+
+Wait 5 seconds, discarding anything that is read on the
+serial port during this time.
+
+=item 3.
+
+Send a PING command and check that the correct response is
+received.
+
+=back
+
+=head2 MULTIPLE CLIENTS
+
+The serial port only supports reading a single command at a time. If
+multiple clients try to connect to the serial port and send commands
+at the same time, then the results will be unpredictable.
+
+If you need to have multiple clients accessing hostinfo inside a
+guest, then you must run some sort of service or daemon inside the
+guest which multiplexes these requests onto the single serial port.
+
+The protocol does not support "pipelining" requests (that is, issuing
+more than one request at a time or overlapping requests and replies).
+If multiple commands are sent at once, then the daemon may discard all
+but the final command.
+
+=head1 FILES
+
+=over 4
+
+=item /dev/ttyS1
+
+=back
+
+=head1 SEE ALSO
+
+L<hostinfo(8)>,
+L<hostinfo-test(1)>,
+L<http://fedoraproject.org/wiki/Features/Hostinfo>,
+L<http://libvirt.org/>,
+L<RFC 2616>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009 Red Hat Inc.
+L<http://fedoraproject.org/wiki/Features/Hostinfo>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
git.annexia.org / virt-hostinfo.git / blobdiff