Start of hostinfo daemon / play with APR.

[virt-hostinfo.git] / README

diff --git a/README b/README
index e69de29..cd91204 100644 (file)
--- a/README
+++ b/README
@@ -0,0 +1,73 @@
+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
+----------------------------------------------------------------------
+
+- APR (Apache Portable Runtime) 1.3
+
+
+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 hostinfod(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.