hostinfod/hostinfo.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 hostinfo - allow controlled access to host information from virtual machines
   6
   7 =head1 SYNOPSIS
   8
   9  chkconfig hostinfo on
  10  service hostinfo start
  11
  12  chkconfig hostinfo off
  13  service hostinfo stop
  14
  15  chkconfig --list hostinfo
  16  service hostinfo status
  17
  18 =head1 DESCRIPTION
  19
  20 This manpage describes running, configuring and troubleshooting the
  21 hostinfo daemon and hostinfo service.  For other parts of the hostinfo
  22 system, see the other manpages listed under I<SEE ALSO> at the end of
  23 this document.
  24
  25 The hostinfo service provides controlled access to host information
  26 and statistics from virtual machines.
  27
  28 The system administrator (of the host) must:
  29
  30 =over 4
  31
  32 =item *
  33
  34 explicitly enable the hostinfo feature (see below),
  35
  36 =item *
  37
  38 select which virtual machines can see any data (see L<hostinfo-set(8)>),
  39
  40 =item *
  41
  42 select which data they wish to disclose to virtual machines
  43 (C<guests.conf> below), and
  44
  45 =item *
  46
  47 select the frequency that virtual machines can ask for data
  48 (C<guests.conf>).
  49
  50 =back
  51
  52 On the host side, information is collected and passed on by the
  53 hostinfo daemon (C<hostinfod>).  If this daemon is not running then no
  54 information at all can be disclosed to guests.
  55
  56 Inside the guests, the information is made available through an
  57 emulated serial port using a simple request-reply text-based protocol.
  58 No special software or drivers are required inside the guest.
  59
  60 =head2 ENABLE HOSTINFO FEATURE
  61
  62 Enabling the hostinfo feature just means making sure the service
  63 (ie. hostinfod) is running:
  64
  65  chkconfig hostinfo on
  66  service hostinfo start
  67
  68 The C<chkconfig> command ensures that the daemon is started
  69 after the host boots.
  70
  71 After the C<service> command, C<hostinfod> process should be running.
  72 If it is not, check the system logfiles (eg. C</var/log/messages> or
  73 C</var/log/syslog>) and see the I<TROUBLESHOOTING> section below.
  74
  75 =head2 DISABLE HOSTINFO FEATURE
  76
  77 To disable the hostinfo feature:
  78
  79  chkconfig hostinfo off
  80  service hostinfo stop
  81
  82 The C<chkconfig> command ensures the daemon will not start after the
  83 host boots.
  84
  85 =head2 CHECK STATUS OF HOSTINFO FEATURE
  86
  87 This command will tell you if the hostinfo daemon will be started on
  88 boot (and in which runlevels):
  89
  90  chkconfig --list hostinfo
  91
  92 The command will tell you if the daemon is currently running:
  93
  94  service hostinfo status
  95
  96 If the daemon is not running when you expect it to, check the system
  97 logfiles (eg. C</var/log/messages> or C</var/log/syslog>) and see the
  98 I<TROUBLESHOOTING> section below.
  99
 100 =head2 ENABLE HOSTINFO FOR EACH GUEST
 101
 102 In addition to enabling the hostinfo feature globally, the system
 103 administrator I<must also> enable it for each guest.
 104
 105 This can be done from L<virt-install(1)> or L<virt-manager(1)>.
 106
 107 You can also do it from the command line using the L<hostinfo-set(8)>
 108 and L<hostinfo-status(8)> commands.
 109
 110 See the relevant manpages for more information.
 111
 112 =head1 CONFIGURATION
 113
 114 All the configuration files described below can contain comments (any
 115 line that starts with a C<#> character).  Blank lines are ignored.
 116
 117 In the discussion below, C<BOOL> means a boolean (truth value) which
 118 can be one of:
 119
 120 =over 4
 121
 122 =item B<1>
 123
 124 =item B<y>
 125
 126 =item B<yes>
 127
 128 =item B<on>
 129
 130 =item B<enable>
 131
 132 =item B<enabled>
 133
 134 =item B<t>
 135
 136 =item B<true>
 137
 138 meaning true/on
 139
 140 =item B<0>
 141
 142 =item B<n>
 143
 144 =item B<no>
 145
 146 =item B<off>
 147
 148 =item B<disable>
 149
 150 =item B<disabled>
 151
 152 =item B<f>
 153
 154 =item B<false>
 155
 156 meaning false/off.
 157
 158 =back
 159
 160 =head2 GENERAL CONFIGURATION: /etc/hostinfo/hostinfo.conf
 161
 162 This file contains general configuration for the hostinfo daemon.
 163
 164 Changes to this file are not detected automatically.  After editing
 165 this file, you must restart the hostinfo service:
 166
 167  service hostinfo restart
 168
 169 The settings which can be changed in C<hostinfo.conf> are:
 170
 171 =over 4
 172
 173 =item B<guests /path/to/guests.conf>
 174
 175 This contains the I<full path> to the C<guests.conf> (per-guest
 176 configuration file - see below).
 177
 178 This setting is required, and the named C<guests.conf> file must
 179 exist.
 180
 181 =item B<sockets /sockets/dir>
 182
 183 This controls the path to the directory containing Unix domain
 184 sockets, which are used for guest to host communication.  Changing
 185 this setting is I<not> recommended, and doing so may cause guests to
 186 be unable to communicate with the daemon.
 187
 188 =item B<verbose BOOL>
 189
 190 If verbose is enabled, then lots of debug-type information is sent to
 191 the system log files.  This is useful for debugging configuration
 192 problems, but not so good for production systems.
 193
 194
 195
 196
 197
 198 =back
 199
 200 =head2 PER-GUEST CONFIGURATION: /etc/hostinfo/guests.conf
 201
 202 This file controls what information and statistics are disclosed to
 203 each guest (virtual machine), and also how often guests are permitted
 204 to request this information.  Thus this file is very important to
 205 controlling the security of the hostinfo system.
 206
 207 Edits to this file take effect as soon as the next request is received
 208 from any guest.  You do not need to restart the daemon.
 209
 210 However B<if this file contains any mistakes, then the daemon will
 211 exit> (ie. the default becomes no access).  The reason for the error
 212 will be sent to a system log file.  So after editing this file, you
 213 should check that hostinfo is available end-to-end (ie. from a guest),
 214 else follow the I<TROUBLESHOOTING> advice below.
 215
 216 C<guests.conf> contains a list of sections, with each section starting
 217 with C<[hypervisor-guestname]>.  The final section should be a
 218 catch-all wildcard that matches any guest and gives the default rules
 219 C<[*]>.  A typical example would be:
 220
 221  # Rule for specific qemu/KVM guest called 'guest1'.
 222  [qemu-guest1]
 223  interval       60
 224  physcpus       off
 225
 226  # Rule that covers all other qemu/KVM guests.
 227  [qemu-*]
 228  interval       60
 229
 230  # Catch-all default rule for guests.
 231  # This rule MUST be last in the file.
 232  [*]
 233  interval       1
 234  availcpus      on
 235  corespersocket on
 236  memory         on
 237  mhz            on
 238  model          on
 239  nodes          on
 240  physcpus       on
 241  ping           on
 242  socketspernode on
 243  threadspercore on
 244  #etc.
 245
 246 In the section header, C<[hypervisor-guestname]>, the C<guestname>
 247 part refers to the name of the guest as it is known to libvirt.  Use
 248 the command C<virsh list --all> to show this.  The C<hypervisor> part
 249 is the name of the libvirt driver, and is usually C<qemu> for qemu and
 250 KVM guests.  Libvirt also uses this convention when naming log files,
 251 so look in C</var/log/libvirt/*/*> if you are unsure of the fully
 252 qualified names of your guests.  As shown above, you can use
 253 wildcards.
 254
 255 I<Note:> just configuring a guest in C<guests.conf> I<does not> mean
 256 that the guest will have access to host status.  You also have to
 257 enable the hostinfo feature globally, I<and> enable it for that guest.
 258 See above for how that is done.
 259
 260 Within each section, you can configure the settings below.
 261
 262 =over 4
 263
 264 =item B<interval N>
 265
 266 =item B<interval any>
 267
 268 This sets the maximum rate that a guest may request I<each> piece of
 269 information.  The rate is expressed in seconds (which can be a
 270 decimal), meaning the guest can make a request at most every N
 271 seconds.
 272
 273 Note: A guest can request each of the M pieces of information
 274 available to it, every N seconds, which means in total there could up
 275 to M requests every N seconds per guest.
 276
 277 If a guest exceeds the rate at which it is allowed to make requests,
 278 then the daemon will after some number of violations stop talking to
 279 the guest.  The only way to restore service to the guest will be to
 280 reboot the guest or restart the daemon.
 281
 282 Setting this to C<any> means there is no limit.  Guests can flood the
 283 host with requests.
 284
 285 =item B<I<command> BOOL>
 286
 287 Enable or disable the command named I<command>.
 288
 289 The default for every command is disabled.  You have to enable
 290 each one that you want to allow.
 291
 292 =back
 293
 294 =head1 TROUBLESHOOTING
 295
 296 =over 4
 297
 298 =item 1.
 299
 300 Is the daemon running?
 301
 302 Use C<service hostinfo status> (on the host) to see if the daemon is
 303 running.
 304
 305 Also see if the C<hostinfod> process appears in the process list:
 306
 307  ps ax | grep hostinfod
 308
 309 If the daemon is not running and/or will not start up, look in the
 310 system log files for error messages.  Depending on how L<syslogd(8)>
 311 or L<rsyslogd(8)> are configured, these messages usually end up in
 312 C</var/log/messages> or C</var/log/syslog>.
 313
 314 =item 2.
 315
 316 Is hostinfo enabled for the guest?
 317
 318 Use L<hostinfo-status(8)> and/or L<hostinfo-set(8)> to see if the
 319 hostinfo feature is enabled for the guest and/or to enable it.
 320
 321 You can also look to see if the serial port has been exported
 322 to the guest by libvirt:
 323
 324  virsh dumpxml guestname
 325
 326 and look for the following fragment in the XML output (it may look
 327 slightly different from that shown):
 328
 329  <serial type='unix'>
 330    <source mode='bind' path='/var/lib/hostinfo/$driver-$name'/>
 331    <target port='1'/>
 332  </serial>
 333
 334 Note that the type will be C<'unix'> even for non-Unix guests.
 335
 336 =item 3.
 337
 338 Is the daemon configured to export information to the guest?
 339
 340 Also, is the guest trying to request information too quickly?
 341
 342 Look at the C<guests.conf> configuration file, using the
 343 guide above.
 344
 345 You can also enable verbose messages in the daemon, which will send a
 346 lot of information out to the system log files.  You will be able to
 347 trace each request as it comes in, and what the daemon decides to do
 348 with it.  To do this, set C<verbose 1> in C<hostinfo.conf>, and then
 349 restart the daemon.
 350
 351 =item 4.
 352
 353 Does the socket exist?
 354
 355 Look for the communications socket in C</var/lib/hostinfo/>
 356 directory.
 357
 358 A socket for the guest should exist.  The socket should be
 359 attached to the C<hostinfod> process at one end, and the
 360 C<qemu-*> process at the other.  Use this command to find out:
 361
 362  netstat -anp
 363
 364 If the socket doesn't exist or is not attached properly, this may
 365 indicate a bug in hostinfo or qemu.
 366
 367 =item 5.
 368
 369 Can the guest request something?
 370
 371 In the guest, disable any software which might try to make hostinfo
 372 requests, then use the L<hostinfo-test(8)> program and see if you can
 373 make requests.  See that manpage for more information.
 374
 375 =item 6.
 376
 377 Are serial ports enabled in the guest?
 378
 379 In the guest, make sure serial port drivers are enabled.
 380
 381 For Linux and Unix-like guests, look through the output of the
 382 L<dmesg(1)> program to see if it found any serial ports.
 383
 384 =item 7.
 385
 386 Is the guest using the correct serial port?
 387
 388 Use the L<hostinfo-test(8)> program in the guest to test this.
 389
 390 =item 8.
 391
 392 (Linux/Unix guests) Is getty attached to the serial port?
 393
 394 On some operating systems, system daemons will attach themselves to
 395 serial ports.  Under Linux you can use the lsof command to check:
 396
 397  /usr/sbin/lsof | grep ttyS
 398
 399 =item 9.
 400
 401 (Linux/Unix guests) Is serial device not in raw mode?
 402
 403 Client software should set the serial device to raw mode and
 404 disable echoing.  The usual way to do this is:
 405
 406  stty raw -echo < /dev/ttyS1
 407
 408 =item 10.
 409
 410 Check the permissions on the serial port.
 411
 412 For Linux and Unix-like guests, check you have permission to read and
 413 write the C</dev/ttyS?> serial device.
 414
 415 =back
 416
 417 Note that serial port settings like speed, parity etc. make no
 418 difference for these emulated serial ports, so that won't be a factor.
 419
 420 =head1 FILES
 421
 422 =over 4
 423
 424 =item /etc/hostinfo/hostinfo.conf
 425
 426 =item /etc/hostinfo/guests.conf
 427
 428 =item /var/lib/hostinfo/
 429
 430 =back
 431
 432 =head1 SEE ALSO
 433
 434 L<hostinfo-set(8)>,
 435 L<hostinfo-status(8)>,
 436 L<hostinfo-test(1)>,
 437 L<virt-install(1)>,
 438 L<virt-manager(1)>,
 439 L<hostinfo-protocol(5)>,
 440 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
 441 L<http://libvirt.org/>.
 442
 443 =head1 AUTHORS
 444
 445 Richard W.M. Jones (C<rjones at redhat dot com>)
 446
 447 =head1 COPYRIGHT
 448
 449 Copyright (C) 2009 Red Hat Inc.
 450 L<http://fedoraproject.org/wiki/Features/Hostinfo>
 451
 452 This program is free software; you can redistribute it and/or modify
 453 it under the terms of the GNU General Public License as published by
 454 the Free Software Foundation; either version 2 of the License, or
 455 (at your option) any later version.
 456
 457 This program is distributed in the hope that it will be useful,
 458 but WITHOUT ANY WARRANTY; without even the implied warranty of
 459 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 460 GNU General Public License for more details.
 461
 462 You should have received a copy of the GNU General Public License
 463 along with this program; if not, write to the Free Software
 464 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.