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 (see below),
38 select which virtual machines can see any data (see L<hostinfo-set(8)>),
42 select which data they wish to disclose to virtual machines
43 (C<guests.conf> below), and
47 select the frequency that virtual machines can ask for data
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.
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.
60 =head2 ENABLE HOSTINFO FEATURE
62 Enabling the hostinfo feature just means making sure the service
63 (ie. hostinfod) is running:
66 service hostinfo start
68 The C<chkconfig> command ensures that the daemon is started
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.
75 =head2 DISABLE HOSTINFO FEATURE
77 To disable the hostinfo feature:
79 chkconfig hostinfo off
82 The C<chkconfig> command ensures the daemon will not start after the
85 =head2 CHECK STATUS OF HOSTINFO FEATURE
87 This command will tell you if the hostinfo daemon will be started on
88 boot (and in which runlevels):
90 chkconfig --list hostinfo
92 The command will tell you if the daemon is currently running:
94 service hostinfo status
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.
100 =head2 ENABLE HOSTINFO FOR EACH GUEST
102 In addition to enabling the hostinfo feature globally, the system
103 administrator I<must also> enable it for each guest.
105 This can be done from L<virt-install(1)> or L<virt-manager(1)>.
107 You can also do it from the command line using the L<hostinfo-set(8)>
108 and L<hostinfo-status(8)> commands.
110 See the relevant manpages for more information.
114 All the configuration files described below can contain comments (any
115 line that starts with a C<#> character). Blank lines are ignored.
117 In the discussion below, C<BOOL> means a boolean (truth value) which
160 =head2 GENERAL CONFIGURATION: /etc/hostinfo/hostinfo.conf
162 This file contains general configuration for the hostinfo daemon.
164 Changes to this file are not detected automatically. After editing
165 this file, you must restart the hostinfo service:
167 service hostinfo restart
169 The settings which can be changed in C<hostinfo.conf> are:
173 =item B<guests /path/to/guests.conf>
175 This contains the I<full path> to the C<guests.conf> (per-guest
176 configuration file - see below).
178 This setting is required, and the named C<guests.conf> file must
181 =item B<sockets /sockets/dir>
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.
188 =item B<verbose BOOL>
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.
200 =head2 PER-GUEST CONFIGURATION: /etc/hostinfo/guests.conf
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.
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.
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.
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:
221 # Rule for specific qemu/KVM guest called 'guest1'.
226 # Rule that covers all other qemu/KVM guests.
230 # Catch-all default rule for guests.
231 # This rule MUST be last in the file.
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
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.
251 Within each section, you can configure the settings below.
257 =item B<interval any>
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
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.
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.
273 Setting this to C<any> means there is no limit. Guests can flood the
276 =item B<physcpus BOOL>
278 Enable or disable requesting the number of physical CPUs available in
289 =head1 TROUBLESHOOTING
295 Is the daemon running?
297 Use C<service hostinfo status> (on the host) to see if the daemon is
300 Also see if the C<hostinfod> process appears in the process list:
302 ps ax | grep hostinfod
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>.
311 Is hostinfo enabled for the guest?
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.
316 You can also look to see if the serial port has been exported
317 to the guest by libvirt:
319 virsh dumpxml guestname
321 and look for the following fragment in the XML output (it may look
322 slightly different from that shown):
325 <source mode='bind' path='/var/lib/hostinfo/$driver-$name'/>
329 Note that the type will be C<'unix'> even for non-Unix guests.
333 Is the daemon configured to export information to the guest?
335 Also, is the guest trying to request information too quickly?
337 Look at the C<guests.conf> configuration file, using the
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
348 Does the socket exist?
350 Look for the communications socket in C</var/lib/hostinfo/>
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:
359 If the socket doesn't exist or is not attached properly, this may
360 indicate a bug in hostinfo or qemu.
364 Can the guest request something?
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.
372 Are serial ports enabled in the guest?
374 In the guest, make sure serial port drivers are enabled.
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.
381 Is the guest using the correct serial port?
383 Use the L<hostinfo-test(8)> program in the guest to test this.
391 =item /etc/hostinfo/hostinfo.conf
393 =item /etc/hostinfo/guests.conf
395 =item /var/lib/hostinfo/
402 L<hostinfo-status(8)>,
406 L<hostinfo-protocol(5)>,
407 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
408 L<http://libvirt.org/>.
412 Richard W.M. Jones (C<rjones at redhat dot com>)
416 Copyright (C) 2009 Red Hat Inc.
417 L<http://fedoraproject.org/wiki/Features/Hostinfo>
419 This program is free software; you can redistribute it and/or modify
420 it under the terms of the GNU General Public License as published by
421 the Free Software Foundation; either version 2 of the License, or
422 (at your option) any later version.
424 This program is distributed in the hope that it will be useful,
425 but WITHOUT ANY WARRANTY; without even the implied warranty of
426 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
427 GNU General Public License for more details.
429 You should have received a copy of the GNU General Public License
430 along with this program; if not, write to the Free Software
431 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.