--- /dev/null
+=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.
git.annexia.org / virt-hostinfo.git / blobdiff