== Overview ==

These instructions outline the steps for creating Debian-based (e.g. Ubuntu) images on ExoGENI and then converting them for use on ProtoGENI.

== Create a file to store the new OS filesystem ==


 * Here we create a 1GB file

{{{
dd if=/dev/zero of=ubuntu_12.04_fs bs=4096 count=262144
262144+0 records in
262144+0 records out
1073741824 bytes (1.1 GB) copied, 1.62763 s, 660 MB/s
}}}

 * Create a loopback device and filesystem, then mount on /mnt/loop.

{{{
sudo losetup -f --show ubuntu_12.04_fs 
/dev/loop0
sudo mkfs.ext4 /dev/loop0
sudo mount /dev/loop0 /mnt/loop
}}}

 * We can now bootstrap our OS onto this loopback filesystem.

== Ubuntu Image Creation using debootstrap ==

 * Get debootstrap for Ubuntu 12.04 "precise"

{{{
mkdir ubuntu_bootstrap
cd ubuntu_bootstrap/
wget http://archive.ubuntu.com/ubuntu/pool/main/d/debootstrap/debootstrap_1.0.56_all.deb
ar -xf debootstrap_1.0.56_all.deb 
tar -xf data.tar.xz 
tar -xf control.tar.gz
}}} 

 * Get the Ubuntu keyring to we can verify packages that get installed by deboostrap.

{{{
wget http://archive.ubuntu.com/ubuntu/pool/main/u/ubuntu-keyring/ubuntu-keyring_2012.05.19.tar.gz
tar -xf ubuntu-keyring_2012.05.19.tar.gz 
}}}

 * Now we can run the deboostrap just downloaded and install a new OS onto the loopback fs we created earlier.

{{{
sudo DEBOOTSTRAP_DIR=/vm/ubuntu_bootstrap/usr/share/debootstrap usr/sbin/debootstrap --arch amd64 --keyring=ubuntu-keyring-2012.05.19/keyrings/ubuntu-archive-keyring.gpg precise /mnt/loop http://us.archive.ubuntu.com/ubuntu/
}}}

 * Once the boostrap completes, we have a base OS install in the ubuntu_12.04 directory.  We can now chroot and install additional packages.

{{{
sudo chroot /mnt/loop
apt-get update
apt-get install linux-image sudo python ...
}}}

 * To allow the ProtoGENI EC2 conversion tool to work, we need the following packages at a minimum.

{{{
apt-get install sudo ruby unzip rsync ssh
}}}

 * We can also set a root password using 'passwd' within the chroot.
 * To ensure that the file compresses well, we want to write zeros into all the free space on the filesystem.  While chrooted, run:

{{{
dd if=/dev/zero of=./zeros && rm -f ./zeros
}}}

 * To finish up, unmount and remove the loopback device.

{{{
umount /mnt/loop
losetup -d /dev/loop0
}}}
 
== Prepare the image for ExoGENI ==

 * By installing the linux-image (or linux-image-virtual) package, we have a kernel with which we can boot the OS as a VM.  The kernel can be found in /boot
 * Copy the kernel as well the the initrd image to a temporary directory.
 * We can test booting the new OS with qemu.

{{{
mkdir kernel
sudo cp /mnt/loop/boot/vmlinuz-3.2.0-23-generic kernel/
sudo cp /mnt/loop/boot/initrd.img-3.2.0-23-generic kernel/
sudo umount /mnt/loop

sudo qemu-system-x86_64 -kernel kernel/vmlinuz-3.2.0-23-generic -initrd kernel/initrd.img-3.2.0-23-generic -append "root=/dev/sda ro" ubuntu_12.04_fs
}}}


 * If the image boots, then we have a working OS!
 * Now we need to install the NEUCA tools that will allow the image to work on ExoGENI racks.
 * Follow the instructions found here: [https://geni-orca.renci.org/trac/wiki/NEuca-guest-configuration NEUCA Guest Configuration]
 * Get the latest NEUCA tools from SVN to be safe.

 * Create the image metadata file and place in a web directory as per these intructions: [https://geni-orca.renci.org/trac/wiki/virtual-machines ExoGENI/ORCA Virtual Machine Images]

== Converting a running ExoGENI image for use on ProtoGENI ==

TODO