[virt-hostinfo.git] / hostinfod / hostinfo.pod

=encoding utf8

=head1 NAME

hostinfo - allow controlled access to host information from virtual machines

=head1 SYNOPSIS

 chkconfig hostinfo on
 service hostinfo start

 chkconfig hostinfo off
 service hostinfo stop

 chkconfig --list hostinfo
 service hostinfo status

=head1 DESCRIPTION

This manpage describes running, configuring and troubleshooting the
hostinfo daemon and hostinfo service.  For other parts of the hostinfo
system, see the other manpages listed under I<SEE ALSO> at the end of
this document.

The hostinfo service provides controlled access to host information
and statistics from virtual machines.

The system administrator (of the host) must:

=over 4

=item *

explicitly enable the hostinfo feature,

=item *

select which virtual machines can see any data,

=item *

select which data they wish to disclose to virtual machines, and

=item *

select the frequency that virtual machines can ask for data.

=back

On the host side, information is collected and passed on by the
hostinfo daemon (C<hostinfod>).  If this daemon is not running then no
information at all can be disclosed to guests.

Inside the guests, the information is made available through an
emulated serial port using a simple request-reply text-based protocol.
No special software or drivers are required inside the guest.

=head2 ENABLE HOSTINFO FEATURE

Enabling the hostinfo feature just means making sure the service
(ie. hostinfod) is running:

 chkconfig hostinfo on
 service hostinfo start

The C<chkconfig> command ensures that the daemon is started
after the host boots.

After the C<service> command, C<hostinfod> process should be running.
If it is not, check the system logfiles (eg. C</var/log/messages> or
C</var/log/syslog>) and see the I<TROUBLESHOOTING> section below.

=head2 DISABLE HOSTINFO FEATURE

To disable the hostinfo feature:

 chkconfig hostinfo off
 service hostinfo stop

The C<chkconfig> command ensures the daemon will not start after the
host boots.

=head2 CHECK STATUS OF HOSTINFO FEATURE

This command will tell you if the hostinfo daemon will be started on
boot (and in which runlevels):

 chkconfig --list hostinfo

The command will tell you if the daemon is currently running:

 service hostinfo status

If the daemon is not running when you expect it to, check the system
logfiles (eg. C</var/log/messages> or C</var/log/syslog>) and see the
I<TROUBLESHOOTING> section below.

=head2 ENABLE HOSTINFO FOR EACH GUEST

In addition to enabling the hostinfo feature globally, the system
administrator I<must also> enable it for each guest.

This can be done from L<virt-install(1)> or L<virt-manager(1)>.

You can also do it from the command line using the L<hostinfo-set(8)>
and L<hostinfo-status(8)> commands.

See the relevant manpages for more information.

=head1 CONFIGURATION

All the configuration files described below can contain comments (any
line that starts with a C<#> character).  Blank lines are ignored.

In the discussion below, C<BOOL> means a boolean (truth value) which
can be one of:

=over 4

=item B<1>

=item B<y>

=item B<yes>

=item B<on>

=item B<enable>

=item B<enabled>

=item B<t>

=item B<true>

meaning true/on

=item B<0>

=item B<n>

=item B<no>

=item B<off>

=item B<disable>

=item B<disabled>

=item B<f>

=item B<false>

meaning false/off.

=back

=head2 GENERAL CONFIGURATION: /etc/hostinfo/hostinfo.conf

This file contains general configuration for the hostinfo daemon.

Changes to this file are not detected automatically.  After editing
this file, you must restart the hostinfo service:

 service hostinfo restart

The settings which can be changed in C<hostinfo.conf> are:

=over 4

=item B<guests /path/to/guests.conf>

This contains the I<full path> to the C<guests.conf> (per-guest
configuration file - see below).

This setting is required, and the named C<guests.conf> file must
exist.

=item B<sockets /sockets/dir>

This controls the path to the directory containing Unix domain
sockets, which are used for guest to host communication.  Changing
this setting is I<not> recommended, and doing so may cause guests to
be unable to communicate with the daemon.

=item B<verbose BOOL>

If verbose is enabled, then lots of debug-type information is sent to
the system log files.  This is useful for debugging configuration
problems, but not so good for production systems.





=back

=head2 PER-GUEST CONFIGURATION: /etc/hostinfo/guests.conf

This file controls what information and statistics are disclosed to
each guest (virtual machine), and also how often guests are permitted
to request this information.  Thus this file is very important to
controlling the security of the hostinfo system.

Edits to this file take effect as soon as the next request is received
from any guest.  You do not need to restart the daemon.

B<However if this file contains any mistakes, then the daemon will
exit> (ie. the default becomes no access).  The reason for the error
will be sent to a system log file.  So after editing this file, you
should check that hostinfo is available end-to-end (ie. from a guest),
else follow the I<TROUBLESHOOTING> advice below.

C<guests.conf> contains a list of sections, with each section starting
with C<[hypervisor-guestname]>.  The final section should be a
catch-all wildcard that matches any guest and gives the default rules
C<[*]>.  A typical example would be:

 # Rule for specific qemu/KVM guest called 'guest1'.
 [qemu-guest1]
 interval 60
 physcpus off
 
 # Rule that covers all other qemu/KVM guests.
 [qemu-*]
 interval 60
 
 # Catch-all default rule for guests.
 # This rule MUST be last in the file.
 [*]
 interval 1
 physcpus on
 #etc.

In the section header, C<[hypervisor-guestname]>, the C<guestname>
part refers to the name of the guest as it is known to libvirt.  Use
the command C<virsh list --all> to show this.  The C<hypervisor> part
is the name of the libvirt driver, and is usually C<qemu> for qemu and
KVM guests.  Libvirt also uses this convention when naming log files,
so look in C</var/log/libvirt/*/*> if you are unsure of the fully
qualified names of your guests.  As shown above, you can use
wildcards.

I<Note:> just configuring a guest in C<guests.conf> I<does not> mean
that the guest will have access to host status.  You also have to
enable the hostinfo feature globally, I<and> enable it for that guest.
See above for how that is done.

Within each section, you can configure the settings below.

=over 4

=item B<interval N>

=item B<interval any>

This sets the maximum rate that a guest may request I<each> piece of
information.  The rate is expressed in seconds (which can be a
decimal), meaning the guest can make a request at most every N
seconds.

Note: A guest can request each of the M pieces of information
available to it, every N seconds, which means in total there could up
to M requests every N seconds per guest.

If a guest exceeds the rate at which it is allowed to make requests,
then the daemon sleeps before replying (just for that guest).

Setting this to C<any> means there is no limit.  Guests can flood the
host with requests.

=item B<physcpus BOOL>

Enable or disable requesting the number of physical CPUs available in
the host.







=back

=head1 TROUBLESHOOTING

=over 4

=item 1.

Is the daemon running?

Use C<service hostinfo status> (on the host) to see if the daemon is
running.

Also see if the C<hostinfod> process appears in the process list:

 ps ax | grep hostinfod

If the daemon is not running and/or will not start up, look in the
system log files for error messages.  Depending on how L<syslogd(8)>
or L<rsyslogd(8)> are configured, these messages usually end up in
C</var/log/messages> or C</var/log/syslog>.

=item 2.

Is hostinfo enabled for the guest?

Use L<hostinfo-status(8)> and/or L<hostinfo-set(8)> to see if the
hostinfo feature is enabled for the guest and/or to enable it.

You can also look to see if the serial port has been exported
to the guest by libvirt:

 virsh dumpxml guestname

and look for the following fragment in the XML output (it may look
slightly different from that shown):

 <serial type='unix'>
   <source mode='bind' path='/var/lib/hostinfo/$driver-$name'/>
   <target port='1'/>
 </serial>

Note that the type will be C<'unix'> even for non-Unix guests.

=item 3.

Is the daemon configured to export information to the guest?

Also, is the guest trying to request information too quickly?

Look at the C<guests.conf> configuration file, using the
guide above.

You can also enable verbose messages in the daemon, which will send a
lot of information out to the system log files.  You will be able to
trace each request as it comes in, and what the daemon decides to do
with it.  To do this, set C<verbose 1> in C<hostinfo.conf>, and then
restart the daemon.

=item 4.

Does the socket exist?

Look for the communications socket in C</var/lib/hostinfo/>
directory.

A socket for the guest should exist.  The socket should be
attached to the C<hostinfod> process at one end, and the
C<qemu-*> process at the other.  Use this command to find out:

 netstat -anp

If the socket doesn't exist or is not attached properly, this may
indicate a bug in hostinfo or qemu.

=item 5.

Can the guest request something?

In the guest, disable any software which might try to make hostinfo
requests, then use the L<hostinfo-test(8)> program and see if you can
make requests.  See that manpage for more information.

=item 6.

Are serial ports enabled in the guest?

In the guest, make sure serial port drivers are enabled.

For Linux and Unix-like guests, look through the output of the
L<dmesg(1)> program to see if it found any serial ports.

=item 7.

Is the guest using the correct serial port?

Use the L<hostinfo-test(8)> program in the guest to test this.

=back

=head1 FILES

=over 4

=item /etc/hostinfo/hostinfo.conf


=item /etc/hostinfo/guests.conf


=item /var/lib/hostinfo/



=back

=head1 SEE ALSO

L<hostinfo-set(8)>,
L<hostinfo-status(8)>,
L<hostinfo-test(8)>,
L<virt-install(1)>,
L<virt-manager(1)>,
L<http://fedoraproject.org/wiki/Features/Hostinfo>,
L<http://libvirt.org/>.

=head1 AUTHORS

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 COPYRIGHT

Copyright (C) 2009 Red Hat Inc.
L<http://fedoraproject.org/wiki/Features/Hostinfo>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.