Improve OVF documentation and provide functional demo.

1 files changed, 77 insertions, 5 deletions

diff --git a/doc/ovf/README b/doc/ovf/README
index f674ea7c..d5cfb443 100644
--- a/doc/ovf/README
+++ b/doc/ovf/README
@@ -1,11 +1,83 @@
-- environment.xml
+This directory contains documentation and a demo of the OVF
+functionality that is present in cloud-init.
+
+The example/ directory contains the following files:
+  example/ovf-env.xml
   This is an example ovf environment file
   to make an iso that qualifies for the ISO transport, do:
     mkdir my-iso
     cp environment.xml my-iso/ovf-env.xml
     genisoimage -o transport.iso -r my-iso
   Then, boot with that ISO attached as a CDrom
-- ProductSection.xml
-  TODO: document what the ProductSection can look like
-- maverick-server.ovf
-  Example generated by virtualbox "export" of a simple VM
+- example/ubuntu-server.ovf
+  Example generated by virtualbox "export" of a simple VM.
+  It contains a functional ProductSection also.  Given answers
+  to each of the Properties there, a suitable OVF environment file
+  (ovf-env.xml) could be created.
+
+== Demo ==
+In order to easily demonstrate this functionality, simple demo is
+contained here.  To boot a local virtual machine in either kvm or virtual
+box, follow the steps below.
+
+- download a suitable Ubuntu image
+  Visit http://cloud-images.ubuntu.com/releases and download a disk image
+  of Natty, Oneiric or a newer release.
+
+  $ burl="http://cloud-images.ubuntu.com/releases/"
+  $ disk="ubuntu-11.10-server-cloudimg-i386-disk1"
+  $ wget "$burl/11.10/release/$disk.img" -O "$disk.img"
+
+- If you're going to use virtual box, you will need to convert the image
+  from qcow2 format into a virtual-box friendly VHD format.  
+  $ qemu-img convert -O vdi "$disk.img" "ubuntu.vdi"
+
+- If you're using kvm, you should create a qcow delta image to store
+  the changes so you keep the original pristine.
+  $ qemu-img create -f qcow2 -b "$disk.img" "ubuntu.qcow2"
+
+  Optionally, you could decompress the image, which will make it boot faster
+  but will take up more local disk space.
+  $ qemu-img convert -O qcow2 "$disk.img" "$disk.qcow2"
+  $ qemu-img create -O qcow2 -b "$disk.qcow2" ubuntu.qcow2
+
+- Create an ISO file that will provide user-data to the image.
+  This will put the contents of 'user-data' into an ovf-env.xml file
+  and create an ISO file that can then be attached at boot to provide
+  the user data to cloud-init.
+
+  $ ./make-iso ovf-env.xml.tmpl user-data --output ovftransport.iso
+
+- Boot your virtual machine
+  The cloud-images boot with kernel and boot progress to ttyS0.
+  You can change that at the grub prompt if you'd like by editing the
+  kernel entry.  Otherwise, to see progress you'll need to switch
+  to the serial console.  In kvm graphic mode, you do that by clicking
+  in the window and then pressing pressing 'ctrl-alt-3'.  For information
+  on how to do that in virtualbox or kvm curses, see the relevant
+  documentation.
+
+  KVM:
+   $ kvm -drive file=ubuntu.qcow2,if=virtio -cdrom ovftransport.iso \
+        -m 256 -net nic -net user,hostfwd=tcp::2222-:22
+
+  VirtualBox:
+   - Launch the GUI and create a new vm with $disk.vdi and ovftransport.iso
+     attached.
+   - If you use 'NAT' networking, then forward a port (2222) to the
+     guests' port 22 to be able to ssh.
+
+  Upon successful boot you will be able to log in as the 'ubuntu' user
+  with the password 'passw0rd' (which was set in the 'user-data' file).
+  
+  You will also be able to ssh to the instance with the provided:
+  $ chmod 600 ovfdemo.pem
+  $ ssh -i ovfdemo.pem -p 2222 ubuntu@localhost
+
+- Notes:
+  * The 'instance-id' that is set in the ovf-env.xml image needs to
+    be unique.  If you want to run the first-boot code of cloud-init
+    again you will either have to remove /var/lib/cloud ('rm -Rf' is fine)
+    or create a new cdrom with a different instance-id.  To do the
+    ladder, simply add the '--instance-id=' flag to the 'make-iso'
+    command above and start your vm with the new ISO attached.