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 (apart from the final CRLF), and must be less or equal
 159 to 4096 characters in length (that includes the final CRLF).
 160
 161 Arguments that are strings I<must> be quoted (using double-quotes).
 162 Special characters inside the strings are escaped using backslashes.
 163 The rules are precisely the same as for C literal strings, so
 164 for example C<"\t"> is a string containing a single tab character.
 165
 166 Arguments that are integers appear as integer literals.
 167
 168 Other argument types that are allowed are: booleans (I<true> or
 169 I<false>).
 170
 171 Note that integers, booleans must never be quoted.
 172
 173 =head2 PING
 174
 175  PING echodata
 176
 177 =head3 Arguments
 178
 179 echodata [string]: A string that is echoed back in the response.  This
 180 must be 1-16 characters in length, consisting I<only> of 7 bit ASCII
 181 alpha-numeric characters ([0-9a-zA-Z]{1,16}).
 182
 183 =head3 Returns
 184
 185 Returns C<echodata> back to the caller.
 186
 187 =head3 Description
 188
 189 This command is used to test the hostinfo connection.
 190
 191 The possible responses to this are:
 192
 193 =over 4
 194
 195 =item *
 196
 197 The command succeeds and echos back the same C<echodata> string.
 198 This indicates that everything is working.
 199
 200 =item *
 201
 202 The command succeeds but echos back different C<echodata>.  Indicates
 203 a synchronization error or some corruption on the serial port
 204 channel (see I<SYNCHRONIZATION> below).
 205
 206 =item *
 207
 208 The command returns an error.  The error will indicate the problem.
 209 Note as with all the other requests, you are limited in the rate you
 210 can ping the host, by a setting that the host system administrator
 211 controls.
 212
 213 =item *
 214
 215 The command returns nothing / hangs / returns a corrupted message.
 216 See I<LOSS OF SERVICE>, I<SYNCHRONIZATION> below, and
 217 I<TROUBLESHOOTING> in the L<hostinfo(8)> manual page.
 218
 219 =back
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231 =head1 COMMON STATUS CODES
 232
 233 =head2 2xx
 234
 235 All 2xx codes indicate the command completed successfully.
 236
 237 =over 4
 238
 239 =item 200
 240
 241 This is the usual status code that is returned to indicate
 242 successful completion of the command.
 243
 244 =back
 245
 246 =head2 4xx
 247
 248 All 4xx codes indicate a client error - malformed or unknown
 249 command etc.
 250
 251 =over 4
 252
 253 =item 400 Bad request
 254
 255 This indicates a malformed request.  Causes include: No command,
 256 incorrect number or type of arguments, not having a single space
 257 between the command and each argument, not correctly quoting strings,
 258 invalid integers.
 259
 260 =item 401 Command disabled
 261
 262 The host system administrator has configured hostinfo to prevent this
 263 guest from using this command or accessing the requested piece of
 264 information.  Contact the host system administrator and ask them to
 265 adjust the configuration to allow this command, or see L<hostinfo(8)>.
 266
 267 =item 404 Command not found
 268
 269 No such command.  New commands can be added in later revisions of this
 270 protocol.  If you try to use these commands with older hostinfo
 271 services, you will receive this error.
 272
 273 =item 406 Too frequent
 274
 275 This indicates that the client is trying to access the requested
 276 resource too often.  The client should access the resource no more
 277 frequently than is configured by the host system administrator.
 278 (After too many of these errors, the hostinfo service will be
 279 completely disabled: see I<LOSS OF SERVICE> below).
 280
 281 =back
 282
 283 =head2 5xx
 284
 285 All 5xx codes indicate a server error.  The command was well-formed
 286 but the host was unable to fulfil this request.
 287
 288 =over 4
 289
 290 =item 500 Internal server error
 291
 292 This indicates a problem on the host side - for example, it might be
 293 that the hostinfo daemon cannot contact libvirt.  For security
 294 reasons, the cause of these failures is never revealed to the guest.
 295 However it is logged on the host side, so the host system
 296 administrator can determine the precise cause of the error.  (See also
 297 I<TROUBLESHOOTING> in L<hostinfo(8)> manpage).
 298
 299 =back
 300
 301 =head1 OTHER ISSUES
 302
 303 =head2 TESTING
 304
 305 Use L<hostinfo-test(1)> to test hostinfo from the guest.  This script
 306 should work on any guest that can run Perl.
 307
 308 =head2 LOSS OF SERVICE
 309
 310 The daemon on the host side that services hostinfo requests is written
 311 defensively.  In particular, it will refuse service (eventually just
 312 ignoring the guest completely) if the guest behaves badly, which
 313 includes: trying to flood the host with data, sending requests more
 314 frequently than the host system administrator has configured.
 315
 316 In the case where the guest loses service (gets no response from
 317 any commands), the only solution is to contact the host system
 318 administrator.
 319
 320 The host system administrator can restart the daemon and/or the guest,
 321 which should restore service.  The host system administrator can also
 322 troubleshoot problems by following the I<TROUBLESHOOTING> section in
 323 L<hostinfo(8)>.
 324
 325 =head2 SYNCHRONIZATION
 326
 327 Serial ports don't have any inherent way to synchronize the data
 328 stream.
 329
 330 If the client believes it has lost synchronization, it can
 331 regain it through the following steps:
 332
 333 =over 4
 334
 335 =item 1.
 336
 337 Send CR LF twice.
 338
 339 =item 2.
 340
 341 Wait 5 seconds, discarding anything that is read on the
 342 serial port during this time.
 343
 344 =item 3.
 345
 346 Send a PING command and check that the correct response is
 347 received.
 348
 349 =back
 350
 351 =head2 MULTIPLE CLIENTS
 352
 353 The serial port only supports reading a single command at a time.  If
 354 multiple clients try to connect to the serial port and send commands
 355 at the same time, then the results will be unpredictable.
 356
 357 If you need to have multiple clients accessing hostinfo inside a
 358 guest, then you must run some sort of service or daemon inside the
 359 guest which multiplexes these requests onto the single serial port.
 360
 361 The protocol does not support "pipelining" requests (that is, issuing
 362 more than one request at a time or overlapping requests and replies).
 363 If multiple commands are sent at once, then the daemon may discard all
 364 but the final command.
 365
 366 =head1 FILES
 367
 368 =over 4
 369
 370 =item /dev/ttyS1
 371
 372 =back
 373
 374 =head1 SEE ALSO
 375
 376 L<hostinfo(8)>,
 377 L<hostinfo-test(1)>,
 378 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
 379 L<http://libvirt.org/>,
 380 L<RFC 2616>.
 381
 382 =head1 AUTHORS
 383
 384 Richard W.M. Jones (C<rjones at redhat dot com>)
 385
 386 =head1 COPYRIGHT
 387
 388 Copyright (C) 2009 Red Hat Inc.
 389 L<http://fedoraproject.org/wiki/Features/Hostinfo>
 390
 391 This program is free software; you can redistribute it and/or modify
 392 it under the terms of the GNU General Public License as published by
 393 the Free Software Foundation; either version 2 of the License, or
 394 (at your option) any later version.
 395
 396 This program is distributed in the hope that it will be useful,
 397 but WITHOUT ANY WARRANTY; without even the implied warranty of
 398 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 399 GNU General Public License for more details.
 400
 401 You should have received a copy of the GNU General Public License
 402 along with this program; if not, write to the Free Software
 403 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.