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  physcpus on
 235  #etc.
 236
 237 In the section header, C<[hypervisor-guestname]>, the C<guestname>
 238 part refers to the name of the guest as it is known to libvirt.  Use
 239 the command C<virsh list --all> to show this.  The C<hypervisor> part
 240 is the name of the libvirt driver, and is usually C<qemu> for qemu and
 241 KVM guests.  Libvirt also uses this convention when naming log files,
 242 so look in C</var/log/libvirt/*/*> if you are unsure of the fully
 243 qualified names of your guests.  As shown above, you can use
 244 wildcards.
 245
 246 I<Note:> just configuring a guest in C<guests.conf> I<does not> mean
 247 that the guest will have access to host status.  You also have to
 248 enable the hostinfo feature globally, I<and> enable it for that guest.
 249 See above for how that is done.
 250
 251 Within each section, you can configure the settings below.
 252
 253 =over 4
 254
 255 =item B<interval N>
 256
 257 =item B<interval any>
 258
 259 This sets the maximum rate that a guest may request I<each> piece of
 260 information.  The rate is expressed in seconds (which can be a
 261 decimal), meaning the guest can make a request at most every N
 262 seconds.
 263
 264 Note: A guest can request each of the M pieces of information
 265 available to it, every N seconds, which means in total there could up
 266 to M requests every N seconds per guest.
 267
 268 If a guest exceeds the rate at which it is allowed to make requests,
 269 then the daemon will after some number of violations stop talking to
 270 the guest.  The only way to restore service to the guest will be to
 271 reboot the guest or restart the daemon.
 272
 273 Setting this to C<any> means there is no limit.  Guests can flood the
 274 host with requests.
 275
 276 =item B<physcpus BOOL>
 277
 278 Enable or disable requesting the number of physical CPUs available in
 279 the host.
 280
 281
 282
 283
 284
 285
 286
 287 =back
 288
 289 =head1 TROUBLESHOOTING
 290
 291 =over 4
 292
 293 =item 1.
 294
 295 Is the daemon running?
 296
 297 Use C<service hostinfo status> (on the host) to see if the daemon is
 298 running.
 299
 300 Also see if the C<hostinfod> process appears in the process list:
 301
 302  ps ax | grep hostinfod
 303
 304 If the daemon is not running and/or will not start up, look in the
 305 system log files for error messages.  Depending on how L<syslogd(8)>
 306 or L<rsyslogd(8)> are configured, these messages usually end up in
 307 C</var/log/messages> or C</var/log/syslog>.
 308
 309 =item 2.
 310
 311 Is hostinfo enabled for the guest?
 312
 313 Use L<hostinfo-status(8)> and/or L<hostinfo-set(8)> to see if the
 314 hostinfo feature is enabled for the guest and/or to enable it.
 315
 316 You can also look to see if the serial port has been exported
 317 to the guest by libvirt:
 318
 319  virsh dumpxml guestname
 320
 321 and look for the following fragment in the XML output (it may look
 322 slightly different from that shown):
 323
 324  <serial type='unix'>
 325    <source mode='bind' path='/var/lib/hostinfo/$driver-$name'/>
 326    <target port='1'/>
 327  </serial>
 328
 329 Note that the type will be C<'unix'> even for non-Unix guests.
 330
 331 =item 3.
 332
 333 Is the daemon configured to export information to the guest?
 334
 335 Also, is the guest trying to request information too quickly?
 336
 337 Look at the C<guests.conf> configuration file, using the
 338 guide above.
 339
 340 You can also enable verbose messages in the daemon, which will send a
 341 lot of information out to the system log files.  You will be able to
 342 trace each request as it comes in, and what the daemon decides to do
 343 with it.  To do this, set C<verbose 1> in C<hostinfo.conf>, and then
 344 restart the daemon.
 345
 346 =item 4.
 347
 348 Does the socket exist?
 349
 350 Look for the communications socket in C</var/lib/hostinfo/>
 351 directory.
 352
 353 A socket for the guest should exist.  The socket should be
 354 attached to the C<hostinfod> process at one end, and the
 355 C<qemu-*> process at the other.  Use this command to find out:
 356
 357  netstat -anp
 358
 359 If the socket doesn't exist or is not attached properly, this may
 360 indicate a bug in hostinfo or qemu.
 361
 362 =item 5.
 363
 364 Can the guest request something?
 365
 366 In the guest, disable any software which might try to make hostinfo
 367 requests, then use the L<hostinfo-test(8)> program and see if you can
 368 make requests.  See that manpage for more information.
 369
 370 =item 6.
 371
 372 Are serial ports enabled in the guest?
 373
 374 In the guest, make sure serial port drivers are enabled.
 375
 376 For Linux and Unix-like guests, look through the output of the
 377 L<dmesg(1)> program to see if it found any serial ports.
 378
 379 =item 7.
 380
 381 Is the guest using the correct serial port?
 382
 383 Use the L<hostinfo-test(8)> program in the guest to test this.
 384
 385 =back
 386
 387 Note that serial port settings like speed, parity etc. make no
 388 difference for these emulated serial ports, so that won't be a factor.
 389
 390 =head1 FILES
 391
 392 =over 4
 393
 394 =item /etc/hostinfo/hostinfo.conf
 395
 396 =item /etc/hostinfo/guests.conf
 397
 398 =item /var/lib/hostinfo/
 399
 400 =back
 401
 402 =head1 SEE ALSO
 403
 404 L<hostinfo-set(8)>,
 405 L<hostinfo-status(8)>,
 406 L<hostinfo-test(1)>,
 407 L<virt-install(1)>,
 408 L<virt-manager(1)>,
 409 L<hostinfo-protocol(5)>,
 410 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
 411 L<http://libvirt.org/>.
 412
 413 =head1 AUTHORS
 414
 415 Richard W.M. Jones (C<rjones at redhat dot com>)
 416
 417 =head1 COPYRIGHT
 418
 419 Copyright (C) 2009 Red Hat Inc.
 420 L<http://fedoraproject.org/wiki/Features/Hostinfo>
 421
 422 This program is free software; you can redistribute it and/or modify
 423 it under the terms of the GNU General Public License as published by
 424 the Free Software Foundation; either version 2 of the License, or
 425 (at your option) any later version.
 426
 427 This program is distributed in the hope that it will be useful,
 428 but WITHOUT ANY WARRANTY; without even the implied warranty of
 429 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 430 GNU General Public License for more details.
 431
 432 You should have received a copy of the GNU General Public License
 433 along with this program; if not, write to the Free Software
 434 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.