Version 8 (modified by, 9 years ago) (diff)



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

  • Note: The following assumes you would like to bootstrap a new filesystem and OS in your local development environment. Alternatives include:
  1. Download an existing image tarball, extract the filesystem, make changes, and repackage the image as needed. You can start from "Making changes to the image" section below.
  2. Use the ExoGENI playpen to boot existing images and make live changes with the option of saving the modified image. See for more information.

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 
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/
ar -xf debootstrap_1.0.59_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.
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
  • Once the bootstrap completes, we have a base OS install in the ubuntu_12.04 directory. We can now chroot and install additional packages.

Making changes to the image

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.
  • Remove apt list.
rm -rf  /var/lib/apt/lists/*
  • Remove the apt-cache to remove installation packages.
sudo apt-get clean
  • 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: NEUCA Guest Configuration
  • Get the latest NEUCA tools from SVN to be safe.

Converting a running ExoGENI image for use on ProtoGENI/InstaGENI

  • Note: a converted image with only the Neuca tools installed and enabled will boot on PG/IG but with limited capabilities. The caveats include:
    1. No user account creation.
    2. No user ssh keys installed. --> The accounts and keys that existed on the running EG image will persist and allow you to login to the node.
    3. Data plan interfaces will exist but configuration (e.g., IPs) will not be assigned.

To resolve the above issues, the Emulab client tools must be installed on the EG image before the conversion process. The tools may be installed on the running EG VM right before the conversion step or they may be included on the saved EG image filesystem. The instructions for this install process can be found:

==> Installing Emulab Client Tools (for EG images)

  • To complete the conversion process, you need an account on a given site's Emulab instance. For instance, at Utah, information can be found at
  • Create a sliver with an EG node you would like to convert. Make sure the running image has the minimum dependencies as described above.
  • Once logged in, follow these steps:
  1. Under "My Emulab" -> "Profile" tab -> "Edit SSH Keys", find your SSH key in the list. Copy that key to the EG node you would like to convert to /home/USER/.ssh/authorized_keys The Emulab conversion script will use this key and only this key when contacting your EG node.
  2. Under "List ImageIDs", click the option for "Import an Amazon EC2 Instance Image"
  3. Fill in the form.
    1. Note: the "EC2 User@Node Info:" field. This should be of the form 'USER@IP', where IP is the public address of your running EG node.
    2. Select "Shared" so the image is viewable by any of your Emulab subgroups.
  4. Watch the displayed progress as the conversion takes place. If the process fails with tar errors, you are most likely out of disk space (over quota) on
  5. Once the process is complete, the image file will be accessible via in /proj/PROJ/images, or wherever you asked the form to save your image.
  6. To use your image within GENI, the image must be made global. Find your newly created image under "List ImageIDs" and toggle the "Global" option. Now, the metadata should be viewable when you click the "https://" link in the image info table.
  7. Use this URL as an option in Flack or a request RSpec to load the image on ProtoGENI PC and VM resources.