virt-hostinfo
Copyright (C) 2009 Red Hat Inc.
----------------------------------------------------------------------

This is a project designed to allow controlled access to host
information from virtual machines.  It is proposed as a new feature
for Fedora 12, and you can read more about it on this web page:

http://fedoraproject.org/wiki/Features/Hostinfo


Requirements
----------------------------------------------------------------------

- C compiler

- APR (Apache Portable Runtime) 1.3

- Perl

- pod2man and other perldoc tools
  * these are usually supplied with Perl

- libvirt

- Perl module Sys::Virt



Build
----------------------------------------------------------------------

On the host:

  ./configure
  make
  sudo make install

There is nothing to build or install in the guest.


Host configuration
----------------------------------------------------------------------

You can edit the text configuration files under /etc/hostinfod by
hand.  Please read the hostinfo(8) manual page.

For graphical configuration, use virt-manager.

To create new guests with access to host information, use
virt-install.


Accessing host information from guests
----------------------------------------------------------------------

No special software is required inside the guest.  Simply connect to
the serial port[1] (eg. /dev/ttyS1 or COM2) using your favorite serial
terminal software and send commands.

The protocol is a simple, line-based, text protocol.  No special
libraries are needed to use it from programs or by hand.  The commands
that you can send are documented in the hostinfod(8) manual page.

If you get no response on the serial port at all, check on the host
side that the guest is allowed access (see /etc/hostinfod/).  Also
check that the serial port has been set up in libvirt:

  virsh dumpxml DOMAIN

(should show a <serial/> clause)

Also check that hostinfod (the daemon) is running on the host.

Note that serial port settings like speed, parity etc. make no
difference for these emulated serial ports, so that won't be a factor.

If you get an answer from the hostinfo daemon, but it indicates a
permissions error, check on the host side that the guest is allowed to
access the particular resource (see /etc/hostinfod/).

[1] _Which_ serial port can vary - you need to either try them one by
one or ask the host administrator to tell you.  We try to stay on the
second serial port (ttyS1 or COM2) but there are some configurations
where we get bumped up or down to other serial ports.