5 hostinfo - allow controlled access to host information from virtual machines
10 service hostinfo start
12 chkconfig hostinfo off
15 chkconfig --list hostinfo
16 service hostinfo status
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
25 The hostinfo service provides controlled access to host information
26 and statistics from virtual machines.
28 The system administrator (of the host) must:
34 explicitly enable the hostinfo feature,
38 select which virtual machines can see any data,
42 select which data they wish to disclose to virtual machines, and
46 select the frequency that virtual machines can ask for data.
50 On the host side, information is collected and passed on by the
51 hostinfo daemon (C<hostinfod>). If this daemon is not running then no
52 information at all can be disclosed to guests.
54 Inside the guests, the information is made available through an
55 emulated serial port using a simple request-reply text-based protocol.
56 No special software or drivers are required inside the guest.
58 =head2 ENABLE HOSTINFO FEATURE
60 Enabling the hostinfo feature just means making sure the service
61 (ie. hostinfod) is running:
64 service hostinfo start
66 The C<chkconfig> command ensures that the daemon is started
69 After the C<service> command, C<hostinfod> process should be running.
70 If it is not, check the system logfiles (eg. C</var/log/messages> or
71 C</var/log/syslog>) and see the I<TROUBLESHOOTING> section below.
73 =head2 DISABLE HOSTINFO FEATURE
75 To disable the hostinfo feature:
77 chkconfig hostinfo off
80 The C<chkconfig> command ensures the daemon will not start after the
83 =head2 CHECK STATUS OF HOSTINFO FEATURE
85 This command will tell you if the hostinfo daemon will be started on
86 boot (and in which runlevels):
88 chkconfig --list hostinfo
90 The command will tell you if the daemon is currently running:
92 service hostinfo status
94 If the daemon is not running when you expect it to, check the system
95 logfiles (eg. C</var/log/messages> or C</var/log/syslog>) and see the
96 I<TROUBLESHOOTING> section below.
98 =head2 ENABLE HOSTINFO FOR EACH GUEST
100 In addition to enabling the hostinfo feature globally, the system
101 administrator I<must also> enable it for each guest.
103 This can be done from L<virt-install(1)> or L<virt-manager(1)>.
105 You can also do it from the command line using the L<hostinfo-set(8)>
106 and L<hostinfo-status(8)> commands.
108 See the relevant manpages for more information.
112 All the configuration files described below can contain comments (any
113 line that starts with a C<#> character). Blank lines are ignored.
115 In the discussion below, C<BOOL> means a boolean (truth value) which
158 =head2 GENERAL CONFIGURATION: /etc/hostinfo/hostinfo.conf
160 This file contains general configuration for the hostinfo daemon.
162 Changes to this file are not detected automatically. After editing
163 this file, you must restart the hostinfo service:
165 service hostinfo restart
167 The settings which can be changed in C<hostinfo.conf> are:
171 =item B<guests /path/to/guests.conf>
173 This contains the I<full path> to the C<guests.conf> (per-guest
174 configuration file - see below).
176 This setting is required, and the named C<guests.conf> file must
179 =item B<sockets /sockets/dir>
181 This controls the path to the directory containing Unix domain
182 sockets, which are used for guest to host communication. Changing
183 this setting is I<not> recommended, and doing so may cause guests to
184 be unable to communicate with the daemon.
186 =item B<verbose BOOL>
188 If verbose is enabled, then lots of debug-type information is sent to
189 the system log files. This is useful for debugging configuration
190 problems, but not so good for production systems.
198 =head2 PER-GUEST CONFIGURATION: /etc/hostinfo/guests.conf
200 This file controls what information and statistics are disclosed to
201 each guest (virtual machine), and also how often guests are permitted
202 to request this information. Thus this file is very important to
203 controlling the security of the hostinfo system.
205 Edits to this file take effect as soon as the next request is received
206 from any guest. You do not need to restart the daemon.
208 B<However if this file contains any mistakes, then the daemon will
209 exit> (ie. the default becomes no access). The reason for the error
210 will be sent to a system log file. So after editing this file, you
211 should check that hostinfo is available end-to-end (ie. from a guest),
212 else follow the I<TROUBLESHOOTING> advice below.
214 C<guests.conf> contains a list of sections, with each section starting
215 with C<[hypervisor-guestname]>. The final section should be a
216 catch-all wildcard that matches any guest and gives the default rules
217 C<[*]>. A typical example would be:
219 # Rule for specific qemu/KVM guest called 'guest1'.
224 # Rule that covers all other qemu/KVM guests.
228 # Catch-all default rule for guests.
229 # This rule MUST be last in the file.
235 In the section header, C<[hypervisor-guestname]>, the C<guestname>
236 part refers to the name of the guest as it is known to libvirt. Use
237 the command C<virsh list --all> to show this. The C<hypervisor> part
238 is the name of the libvirt driver, and is usually C<qemu> for qemu and
239 KVM guests. Libvirt also uses this convention when naming log files,
240 so look in C</var/log/libvirt/*/*> if you are unsure of the fully
241 qualified names of your guests. As shown above, you can use
244 I<Note:> just configuring a guest in C<guests.conf> I<does not> mean
245 that the guest will have access to host status. You also have to
246 enable the hostinfo feature globally, I<and> enable it for that guest.
247 See above for how that is done.
249 Within each section, you can configure the settings below.
255 =item B<interval any>
257 This sets the maximum rate that a guest may request I<each> piece of
258 information. The rate is expressed in seconds (which can be a
259 decimal), meaning the guest can make a request at most every N
262 Note: A guest can request each of the M pieces of information
263 available to it, every N seconds, which means in total there could up
264 to M requests every N seconds per guest.
266 If a guest exceeds the rate at which it is allowed to make requests,
267 then the daemon sleeps before replying (just for that guest).
269 Setting this to C<any> means there is no limit. Guests can flood the
272 =item B<physcpus BOOL>
274 Enable or disable requesting the number of physical CPUs available in
285 =head1 TROUBLESHOOTING
291 Is the daemon running?
293 Use C<service hostinfo status> (on the host) to see if the daemon is
296 Also see if the C<hostinfod> process appears in the process list:
298 ps ax | grep hostinfod
300 If the daemon is not running and/or will not start up, look in the
301 system log files for error messages. Depending on how L<syslogd(8)>
302 or L<rsyslogd(8)> are configured, these messages usually end up in
303 C</var/log/messages> or C</var/log/syslog>.
307 Is hostinfo enabled for the guest?
309 Use L<hostinfo-status(8)> and/or L<hostinfo-set(8)> to see if the
310 hostinfo feature is enabled for the guest and/or to enable it.
312 You can also look to see if the serial port has been exported
313 to the guest by libvirt:
315 virsh dumpxml guestname
317 and look for the following fragment in the XML output (it may look
318 slightly different from that shown):
321 <source mode='bind' path='/var/lib/hostinfo/$driver-$name'/>
325 Note that the type will be C<'unix'> even for non-Unix guests.
329 Is the daemon configured to export information to the guest?
331 Also, is the guest trying to request information too quickly?
333 Look at the C<guests.conf> configuration file, using the
336 You can also enable verbose messages in the daemon, which will send a
337 lot of information out to the system log files. You will be able to
338 trace each request as it comes in, and what the daemon decides to do
339 with it. To do this, set C<verbose 1> in C<hostinfo.conf>, and then
344 Does the socket exist?
346 Look for the communications socket in C</var/lib/hostinfo/>
349 A socket for the guest should exist. The socket should be
350 attached to the C<hostinfod> process at one end, and the
351 C<qemu-*> process at the other. Use this command to find out:
355 If the socket doesn't exist or is not attached properly, this may
356 indicate a bug in hostinfo or qemu.
360 Can the guest request something?
362 In the guest, disable any software which might try to make hostinfo
363 requests, then use the L<hostinfo-test(8)> program and see if you can
364 make requests. See that manpage for more information.
368 Are serial ports enabled in the guest?
370 In the guest, make sure serial port drivers are enabled.
372 For Linux and Unix-like guests, look through the output of the
373 L<dmesg(1)> program to see if it found any serial ports.
377 Is the guest using the correct serial port?
379 Use the L<hostinfo-test(8)> program in the guest to test this.
387 =item /etc/hostinfo/hostinfo.conf
390 =item /etc/hostinfo/guests.conf
393 =item /var/lib/hostinfo/
402 L<hostinfo-status(8)>,
406 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
407 L<http://libvirt.org/>.
411 Richard W.M. Jones (C<rjones at redhat dot com>)
415 Copyright (C) 2009 Red Hat Inc.
416 L<http://fedoraproject.org/wiki/Features/Hostinfo>
418 This program is free software; you can redistribute it and/or modify
419 it under the terms of the GNU General Public License as published by
420 the Free Software Foundation; either version 2 of the License, or
421 (at your option) any later version.
423 This program is distributed in the hope that it will be useful,
424 but WITHOUT ANY WARRANTY; without even the implied warranty of
425 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
426 GNU General Public License for more details.
428 You should have received a copy of the GNU General Public License
429 along with this program; if not, write to the Free Software
430 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.