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 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
  58 following command:
  59
  60  stty raw -echo < /dev/ttyS1
  61
  62 although it can also be done using terminal ioctls (see L<ioctl(2)>
  63 and L<ioctl_list(2)>).
  64
  65 =head2 REQUESTS AND REPLIES
  66
  67 The basic protocol consists of sending a text-based command (the
  68 request), and then reading the reply.
  69
  70 A typical request/reply cycle looks like:
  71
  72  <<< PING "hello"
  73  >>> 1.0 200 hello
  74
  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]).
  77
  78 The reply was C<"1.0 200 hello\r\n">.
  79
  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.
  83
  84 The request is a command followed by some number of arguments,
  85 followed by CRLF.  Commands available are described below.
  86
  87 The reply consists of:
  88
  89 =over 4
  90
  91 =item 1.0
  92
  93 The protocol version number, always C<1.x> in the current
  94 iteration of the protocol.
  95
  96 =item E<lt>spaceE<gt> 200
  97
  98 The 3 digit status code (compatible with HTTP
  99 status codes, see RFC 2616).
 100
 101 =item E<lt>spaceE<gt> hello
 102
 103 A space followed by the (optional) short response, B<or>:
 104
 105 =item multi-line response
 106
 107 Some commands (but not PING) can return a multi-line response.
 108
 109 =back
 110
 111 A few commands return a multi-line response:
 112
 113  <<< CAPABILITIES
 114  >>> 1.0 200
 115  >>> Content-Type: text/xml
 116  >>> Content-Length: 123
 117  >>>
 118  >>> <capabilities>
 119  >>>   <host>
 120  >>>     <cpu>
 121  >>>       <arch>i686</arch>
 122  (etc.)
 123
 124 The multi-line response consists of headers and blank line and a body,
 125 and is a compatible subset of HTTP (RFC 2616).
 126
 127 To tell the difference between a short, single-line response
 128 and a multi-line response:
 129
 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">.
 133
 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">.
 136
 137 When a command returns an error, the request / response looks like
 138 this:
 139
 140  <<< NOSUCHCOMMAND
 141  >>> 1.0 404 Command not found
 142
 143 As in HTTP, C<4xx> and C<5xx> status codes indicate classes of
 144 error.  Following the error code is an explanatory string.
 145
 146 Errors never have a multi-line response.
 147
 148 =head2 FREQUENCY OF REQUESTS
 149
 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.
 155
 156 =head1 COMMANDS
 157
 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.
 161
 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
 164 case.
 165
 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
 169 final CRLF).
 170
 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.
 175
 176 Strings may not contain C<\0> characters in the middle, nor can they
 177 be NULL.
 178
 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.
 182
 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.
 186
 187 Boolean arguments should be sent as I<true> or I<false>.
 188
 189 =head2 AVAILCPUS
 190
 191  AVAILCPUS
 192
 193 =head3 Returns
 194
 195 Number of available physical cores in the host.
 196
 197 =head3 Example
 198
 199  <<< AVAILCPUS
 200  >>> 1.0 200 4
 201
 202 =head3 Description
 203
 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.
 207
 208 =head2 CORESPERSOCKET
 209
 210  CORESPERSOCKET
 211
 212 =head3 Returns
 213
 214 Number of cores per socket in the physical host.
 215
 216 =head3 Example
 217
 218  <<< CORESPERSOCKET
 219  >>> 1.0 200 2
 220
 221 =head3 Description
 222
 223 Returns the number of physical cores per socket in the host.
 224
 225 =head2 MEMORY
 226
 227  MEMORY
 228
 229 =head3 Returns
 230
 231 Amount of memory in host, in kilobytes.
 232
 233 =head3 Example
 234
 235  <<< MEMORY
 236  >>> 1.0 200 2097022
 237
 238 =head3 Description
 239
 240 Returns the total memory in the host, in kilobytes.
 241
 242 =head2 MHZ
 243
 244  MHZ
 245
 246 =head3 Returns
 247
 248 Speed of host cores in MHz.
 249
 250 =head3 Example
 251
 252  <<< MHZ
 253  >>> 1.0 200 2047
 254
 255 =head3 Description
 256
 257 Returns the clockspeed of host cores in MHz.
 258
 259 =head2 MODEL
 260
 261  MODEL
 262
 263 =head3 Returns
 264
 265 The host CPU model, a string such as C<i686> or C<x86_64>.
 266
 267 =head3 Example
 268
 269  <<< MODEL
 270  >>> 1.0 200 x86_64
 271
 272 =head3 Description
 273
 274 Returns the host CPU model.
 275
 276 =head2 NODES
 277
 278  NODES
 279
 280 =head3 Returns
 281
 282 The number of NUMA nodes in the host.
 283
 284 =head3 Example
 285
 286  <<< NODES
 287  >>> 1.0 200 1
 288
 289 =head3 Description
 290
 291 Returns the number of NUMA nodes in the host.  If this is 1
 292 then host memory access is uniform.
 293
 294 =head2 PHYSCPUS
 295
 296  PHYSCPUS
 297
 298 =head3 Returns
 299
 300 The number of physical cores.
 301
 302 =head3 Example
 303
 304  <<< PHYSCPUS
 305  >>> 1.0 200 4
 306
 307 =head3 Description
 308
 309 Returns the number of physical cores available on the host.
 310
 311 In some (highly unusual) situations, some cores might be
 312 disabled.  To get the number of cores available to do work,
 313 use C<AVAILCPUS>.
 314
 315 Note that it is common for the guest not to see all of the
 316 physical CPUs (virtual CPUs E<lt> physical CPUs).
 317
 318 =head2 PING
 319
 320  PING echodata
 321
 322 =head3 Arguments
 323
 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}).
 327
 328 =head3 Returns
 329
 330 Returns C<echodata> back to the caller.
 331
 332 =head3 Example
 333
 334  <<< PING "hello"
 335  >>> 1.0 200 hello
 336
 337 =head3 Description
 338
 339 This command is used to test the hostinfo connection.
 340
 341 The possible responses to this are:
 342
 343 =over 4
 344
 345 =item *
 346
 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.
 349
 350 =item *
 351
 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).
 355
 356 =item *
 357
 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
 361 controls.
 362
 363 =item *
 364
 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.
 368
 369 =back
 370
 371 =head2 SOCKETSPERNODE
 372
 373  SOCKETSPERNODE
 374
 375 =head3 Returns
 376
 377 The number of sockets on each node.
 378
 379 =head3 Example
 380
 381  <<< SOCKETSPERNODE
 382  >>> 1.0 200 2
 383
 384 =head3 Description
 385
 386 Returns the number CPU sockets in each NUMA node.
 387
 388 =head2 THREADSPERCORE
 389
 390  THREADSPERCORE
 391
 392 =head3 Returns
 393
 394 The number of hyperthreads per core.
 395
 396 =head3 Example
 397
 398  <<< THREADSPERCORE
 399  >>> 1.0 200 1
 400
 401 =head3 Description
 402
 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
 406 accordingly.
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418 =head1 COMMON STATUS CODES
 419
 420 =head2 2xx
 421
 422 All 2xx codes indicate the command completed successfully.
 423
 424 =over 4
 425
 426 =item 200
 427
 428 This is the usual status code that is returned to indicate
 429 successful completion of the command.
 430
 431 =back
 432
 433 =head2 4xx
 434
 435 All 4xx codes indicate a client error - malformed or unknown
 436 command etc.
 437
 438 =over 4
 439
 440 =item 400 Bad request
 441
 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,
 445 invalid integers.
 446
 447 =item 401 Command disabled
 448
 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)>.
 453
 454 =item 404 Command not found
 455
 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.
 459
 460 =item 406 Too frequent
 461
 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).
 467
 468 =back
 469
 470 =head2 5xx
 471
 472 All 5xx codes indicate a server error.  The command was well-formed
 473 but the host was unable to fulfil this request.
 474
 475 =over 4
 476
 477 =item 500 Internal server error
 478
 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).
 485
 486 =back
 487
 488 =head1 OTHER ISSUES
 489
 490 =head2 TESTING
 491
 492 Use L<hostinfo-test(1)> to test hostinfo from the guest.  This script
 493 should work on any guest that can run Perl.
 494
 495 You can also send commands directly to the daemon on the host
 496 (just for testing purposes) using the I<nc> program:
 497
 498  # nc -CUl /var/lib/hostinfo/test-test
 499
 500 =head2 LOSS OF SERVICE
 501
 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.
 507
 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
 510 administrator.
 511
 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
 515 L<hostinfo(8)>.
 516
 517 =head2 SYNCHRONIZATION
 518
 519 Serial ports don't have any inherent way to synchronize the data
 520 stream.
 521
 522 If the client believes it has lost synchronization, it can
 523 regain it through the following steps:
 524
 525 =over 4
 526
 527 =item 1.
 528
 529 Send CR LF twice.
 530
 531 =item 2.
 532
 533 Wait 5 seconds, discarding anything that is read on the
 534 serial port during this time.
 535
 536 =item 3.
 537
 538 Send a PING command and check that the correct response is
 539 received.
 540
 541 =back
 542
 543 =head2 MULTIPLE CLIENTS
 544
 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.
 548
 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.
 552
 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.
 557
 558 =head1 FILES
 559
 560 =over 4
 561
 562 =item /dev/ttyS1
 563
 564 =back
 565
 566 =head1 SEE ALSO
 567
 568 L<hostinfo(8)>,
 569 L<hostinfo-test(1)>,
 570 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
 571 L<http://libvirt.org/>,
 572 L<RFC 2616>.
 573
 574 =head1 AUTHORS
 575
 576 Richard W.M. Jones (C<rjones at redhat dot com>)
 577
 578 =head1 COPYRIGHT
 579
 580 Copyright (C) 2009 Red Hat Inc.
 581 L<http://fedoraproject.org/wiki/Features/Hostinfo>
 582
 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.
 587
 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.
 592
 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.