greatly expanding the documentation (hopefully not too much). I think

bridge-utils is required for the bridging - and I've added what I
added to my /etc/network/interfaces file... hope that's right!

1 files changed, 83 insertions, 20 deletions

diff --git a/README b/README
index f9ee427..5a139a7 100644
--- a/README
+++ b/README
@@ -7,7 +7,9 @@ This is a small set of scripts to make it relatively easy to manage a
 stable of kvm instances in a fairly secure and isolated fashion.
 
 The basic model is to use runit to supervise each KVM instance, with a
-single, non-privileged user account for each instance.
+single, non-privileged user account for each instance. You can login
+via ssh as the non-privileged user and, via screen, access the 
+instance's console. 
 
 Dependencies:
 
@@ -15,38 +17,99 @@ Dependencies:
  uml-utilities : for tunctl for the tun/tap interface
  kvm : for the virtual machine emulator
  screen : for the detached, logged serial console
+ bridge-utils : for configuring a bridge device
 
 Recommendations:
 
  openssh-server : i've been using ssh to access the vm's serial console
 
-Before you begin, you may want to prepare your system by doing the following:
+INSTALLATION
 
-* Copy di-maker, kvm-manager, and kvm-creator into /usr/local/sbin
-* Copy screenrc.kvm-manager to /etc/
-* Make the directory /usr/local/share/ISOs
-* Create a serial console enabled debian installer.
-	* cd /usr/local/share/ISOs
-	* di-maker > d-i.iso
+ * Install dependencies:
 
-A typical workflow to start an installer is:
+   aptitude install runit uml-utilties kvm screen bridge-utils
 
-kvm-creator create $GUESTNAME $VG [$DISKSIZE [$RAM [$TAP [$MAC] ] ] ]
-# set up boot media for the host ("put the installer CD in the drive"):
-ln -s /usr/local/share/ISOs/d-i.iso /home/$GUESTNAME/vms/$GUESTNAME/cd.iso
-# by default, the account has the authorized_keys file from the root
-# user on the host. optionally, add additionall keys
-cat ~/.ssh/authorized_keys >> /home/$GUESTNAME/.ssh/authorized_keys
-# start up the host
-update-service --add /etc/sv/kvm/$GUESTNAME
+ * Copy programs into /usr/local/sbin:
+ 
+   cp {di-maker,kvm-manager,kvm-creator} /usr/local/sbin/
 
+ * Copy screen configuration file into /etc
+
+   cp screenrc.kvm-manager /etc/
+
+ * Configure your host network to use a bridge. If your network adaptor 
+   is eth0, you can use the following in /etc/network/interfaces
+
+  auto br0
+  iface br0 inet static
+    [Put your normal IP config for eth0 here...]
+    bridge_ports eth0
+
+INSTALLING DEBIAN ONTO YOUR VIRTUAL SERVER
+
+To create a KVM instance, run:
+
+  kvm-creator create $GUESTNAME $VG [$DISKSIZE [$RAM [$TAP [$MAC] ] ] ]
+
+You can replace "create" with "demo" to see the default values for non-
+specified options.
+
+The creator scripts creates a username and home directory, logical volume, and
+the required directory in /etc/sv/kvm/GUESTNAME from which the kvm-manager
+script is run. After creating your virtual server, you can modify the files in
+/etc/sv/kvm/GUESTNAME/env to change initial settings.
+
+You may also add ssh key's to /home/GUESTNAME/.ssh/authorized_keys to provide
+additional access to other users.
+
+At this point, your virtual server is created, however, it has no operating system
+and it has not been started.
+
+There are two options for installing debian onto the virtual server:
+
+ * netboot
+ * iso (like a CD install)
+
+To use netboot, make sure you have a working DHCP server running on your
+host server and offering addresses over your bridge interface.
+
+Then, indicate that the server should boot via the network with:
+
+  touch /home/$GUESTNAME/vms/$GUESTNAME/netboot
+
+Alternatively, you can make a debian boot ISO image:
+
+	* Make the directory /usr/local/share/ISOs
+	* Create a serial console enabled debian installer.
+		* cd /usr/local/share/ISOs
+		* di-maker > d-i.iso
+
+Indicate that the server should boot via the CDROM (the equivelant of putting
+the installer CD in the drive) with:
+
+  ln -s /usr/local/share/ISOs/d-i.iso /home/$GUESTNAME/vms/$GUESTNAME/cd.iso
+
+STARTING YOUR VIRTUAL SERVER
+
+  update-service --add /etc/sv/kvm/$GUESTNAME
+
+This process adds your virtual server to the runit service directory.
+
+If /home/$GUESTNAME/vms/$GUESTNAME/cd.iso exists, the server will behave as if you
+set the CDROM as the boot device in the bios.
+
+If /home/$GUESTNAME/vms/$GUESTNAME/netboot exists, the server will behave as if you
+set the network device as the boot device in the bios.
+
+After you have installed your server, be sure to delete these files if they exist or
+your server won't boot properly.
+
+ACCESSING YOUR VIRTUAL SERVER
 
 To access the guest's serial console, do:
 
    ssh -t $GUESTNAME@host.machine screen -x $GUESTNAME
 
-
-trouble getting a serial console-enabled debian
-installer ISO?  try using the di-maker script.
+HACKING
 
 All patches, fixes, suggestions welcome!