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 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
 160 final CRLF).
 161
 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.
 166
 167 Strings may not contain C<\0> characters in the middle, nor can they
 168 be NULL.
 169
 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.
 173
 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.
 177
 178 Boolean arguments should be sent as I<true> or I<false>.
 179
 180 =head2 AVAILCPUS
 181
 182  AVAILCPUS
 183
 184 =head3 Returns
 185
 186 Number of available physical cores in the host.
 187
 188 =head3 Example
 189
 190  >>> AVAILCPUS
 191  <<< 1.0 200 4
 192
 193 =head3 Description
 194
 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.
 198
 199 =head2 CORESPERSOCKET
 200
 201  CORESPERSOCKET
 202
 203 =head3 Returns
 204
 205 Number of cores per socket in the physical host.
 206
 207 =head3 Example
 208
 209  >>> CORESPERSOCKET
 210  <<< 1.0 200 2
 211
 212 =head3 Description
 213
 214 Returns the number of physical cores per socket in the host.
 215
 216 =head2 MEMORY
 217
 218  MEMORY
 219
 220 =head3 Returns
 221
 222 Amount of memory in host, in kilobytes.
 223
 224 =head3 Example
 225
 226  >>> MEMORY
 227  <<< 1.0 200 2097022
 228
 229 =head3 Description
 230
 231 Returns the total memory in the host, in kilobytes.
 232
 233 =head2 MHZ
 234
 235  MHZ
 236
 237 =head3 Returns
 238
 239 Speed of host cores in MHz.
 240
 241 =head3 Example
 242
 243  >>> MHZ
 244  <<< 1.0 200 2047
 245
 246 =head3 Description
 247
 248 Returns the clockspeed of host cores in MHz.
 249
 250 =head2 MODEL
 251
 252  MODEL
 253
 254 =head3 Returns
 255
 256 The host CPU model, a string such as C<i686> or C<x86_64>.
 257
 258 =head3 Example
 259
 260  >>> MODEL
 261  <<< 1.0 200 x86_64
 262
 263 =head3 Description
 264
 265 Returns the host CPU model.
 266
 267 =head2 NODES
 268
 269  NODES
 270
 271 =head3 Returns
 272
 273 The number of NUMA nodes in the host.
 274
 275 =head3 Example
 276
 277  >>> NODES
 278  <<< 1.0 200 1
 279
 280 =head3 Description
 281
 282 Returns the number of NUMA nodes in the host.  If this is 1
 283 then host memory access is uniform.
 284
 285 =head2 PHYSCPUS
 286
 287  PHYSCPUS
 288
 289 =head3 Returns
 290
 291 The number of physical cores.
 292
 293 =head3 Example
 294
 295  >>> PHYSCPUS
 296  <<< 1.0 200 4
 297
 298 =head3 Description
 299
 300 Returns the number of physical cores available on the host.
 301
 302 In some (highly unusual) situations, some cores might be
 303 disabled.  To get the number of cores available to do work,
 304 use C<AVAILCPUS>.
 305
 306 Note that it is common for the guest not to see all of the
 307 physical CPUs (virtual CPUs E<lt> physical CPUs).
 308
 309 =head2 PING
 310
 311  PING echodata
 312
 313 =head3 Arguments
 314
 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}).
 318
 319 =head3 Returns
 320
 321 Returns C<echodata> back to the caller.
 322
 323 =head3 Example
 324
 325  >>> PING "hello"
 326  <<< 1.0 200 hello
 327
 328 =head3 Description
 329
 330 This command is used to test the hostinfo connection.
 331
 332 The possible responses to this are:
 333
 334 =over 4
 335
 336 =item *
 337
 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.
 340
 341 =item *
 342
 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).
 346
 347 =item *
 348
 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
 352 controls.
 353
 354 =item *
 355
 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.
 359
 360 =back
 361
 362 =head2 SOCKETSPERNODE
 363
 364  SOCKETSPERNODE
 365
 366 =head3 Returns
 367
 368 The number of sockets on each node.
 369
 370 =head3 Example
 371
 372  >>> SOCKETSPERNODE
 373  <<< 1.0 200 2
 374
 375 =head3 Description
 376
 377 Returns the number CPU sockets in each NUMA node.
 378
 379 =head2 THREADSPERCORE
 380
 381  THREADSPERCORE
 382
 383 =head3 Returns
 384
 385 The number of hyperthreads per core.
 386
 387 =head3 Example
 388
 389  >>> THREADSPERCORE
 390  <<< 1.0 200 1
 391
 392 =head3 Description
 393
 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
 397 accordingly.
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409 =head1 COMMON STATUS CODES
 410
 411 =head2 2xx
 412
 413 All 2xx codes indicate the command completed successfully.
 414
 415 =over 4
 416
 417 =item 200
 418
 419 This is the usual status code that is returned to indicate
 420 successful completion of the command.
 421
 422 =back
 423
 424 =head2 4xx
 425
 426 All 4xx codes indicate a client error - malformed or unknown
 427 command etc.
 428
 429 =over 4
 430
 431 =item 400 Bad request
 432
 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,
 436 invalid integers.
 437
 438 =item 401 Command disabled
 439
 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)>.
 444
 445 =item 404 Command not found
 446
 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.
 450
 451 =item 406 Too frequent
 452
 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).
 458
 459 =back
 460
 461 =head2 5xx
 462
 463 All 5xx codes indicate a server error.  The command was well-formed
 464 but the host was unable to fulfil this request.
 465
 466 =over 4
 467
 468 =item 500 Internal server error
 469
 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).
 476
 477 =back
 478
 479 =head1 OTHER ISSUES
 480
 481 =head2 TESTING
 482
 483 Use L<hostinfo-test(1)> to test hostinfo from the guest.  This script
 484 should work on any guest that can run Perl.
 485
 486 =head2 LOSS OF SERVICE
 487
 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.
 493
 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
 496 administrator.
 497
 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
 501 L<hostinfo(8)>.
 502
 503 =head2 SYNCHRONIZATION
 504
 505 Serial ports don't have any inherent way to synchronize the data
 506 stream.
 507
 508 If the client believes it has lost synchronization, it can
 509 regain it through the following steps:
 510
 511 =over 4
 512
 513 =item 1.
 514
 515 Send CR LF twice.
 516
 517 =item 2.
 518
 519 Wait 5 seconds, discarding anything that is read on the
 520 serial port during this time.
 521
 522 =item 3.
 523
 524 Send a PING command and check that the correct response is
 525 received.
 526
 527 =back
 528
 529 =head2 MULTIPLE CLIENTS
 530
 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.
 534
 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.
 538
 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.
 543
 544 =head1 FILES
 545
 546 =over 4
 547
 548 =item /dev/ttyS1
 549
 550 =back
 551
 552 =head1 SEE ALSO
 553
 554 L<hostinfo(8)>,
 555 L<hostinfo-test(1)>,
 556 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
 557 L<http://libvirt.org/>,
 558 L<RFC 2616>.
 559
 560 =head1 AUTHORS
 561
 562 Richard W.M. Jones (C<rjones at redhat dot com>)
 563
 564 =head1 COPYRIGHT
 565
 566 Copyright (C) 2009 Red Hat Inc.
 567 L<http://fedoraproject.org/wiki/Features/Hostinfo>
 568
 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.
 573
 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.
 578
 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.