Building a ubuntu lucid image (Deprecated)

AppScale now runs on Precise. This document is deprecated.

This document overviews the steps to create a raw image (root file system) for a virtualized Ubuntu Lucid x86_64 system (guestVM). We support to the greatest extent possible an image format that is Xen-compatible and that implements the Ubuntu Lucid distribution. This image format can be used to implement an AppScale image that can be deployed over Xen virtualization (v3+), a Eucalyptus private cloud, and the Amazon EC2 public cloud.

---

Image Creation

The following creates a raw image of an Ubuntu Lucid x86_64 root file system (using the ext3 format) of size 10GB in a file called root.img in a directory called /local/images/lucid/10GB. Change these file and directory as required. Make sure that you have sufficient disk space to hold the root file system.

Change the size of the image by modifying the bs and count values. We recommend an image of at least 10GB (the instructions below create an image 10GB in size). AppScale requires an image of at least 6GB for the code base. The second 4GB is for application data storage in the AppScale cloud. This step requires that the utilities dd, mkfs, tune2fs, and debootstrap be installed in your host system.

export IMAGEHOME="/local/images/lucid/10GB"
export FILENAME="root.img"
mkdir -p ${IMAGEHOME}
dd if=/dev/zero of=${IMAGEHOME}/${FILENAME} oflag=direct bs=1M count=10240
cd ${IMAGEHOME}
mkfs.ext3 ${FILENAME}

Then update the image with the Ubuntu Lucid distro:

tune2fs -c -1 ${FILENAME}
mkdir -p tmpdir
mount -o loop ${FILENAME} ./tmpdir
debootstrap --arch amd64 --include=linux-image-ec2,linux-image-server,grub,xterm,acpid,openssh-server,vim,cryptsetup  --components=main,universe,multiverse lucid ./tmpdir http://archive.ubuntu.com/ubuntu

Next, create an image for the swap space of your system. We recommend a swap image of 4GB, but you can change the values as appropriate for your system.

export IMAGEHOME="/local/images/lucid/10GB"
export SWAP_FILENAME="swap.img"
dd if=/dev/zero of=${IMAGEHOME}/${SWAP_FILENAME} oflag=direct bs=1M count=4096
mkswap ${SWAP_FILENAME}

Next, use the steps below to configure the root file system image so that

• You can login as root using the password appscale,
• The console works with the xm tools,
• apt is setup for the AppScale install,
• The networking is configured to use DHCP, and
• There is a hostname.
• Setup the ramdisk. The No such file warnings due to the commands that do this (update-initramfs) can be ignored
• Copy out the kernel and ramdisk files Change these values as appropriate (and with care). You should already have your root.img mounted at tmpdir in the working directory, if you followed the steps above.

vi tmpdir/etc/shadow
//find the root entry and change the * in the second field to be this string
//this will set the password to "appscale"
$1$fIY.Kph/$BMsE4tyUwpXEziJGp7f9B.

//Add this line prior to each "exit 0" line in /etc/rc.local
vi tmpdir/etc/rc.local
modprobe acpiphp

mkdir -p tmpdir/etc/initramfs-tools/conf.d/
touch tmpdir/etc/initramfs-tools/conf.d/splash
echo FRAMEBUFFER=y | sudo tee tmpdir/etc/initramfs-tools/conf.d/splash

cat > ./tmpdir/etc/apt/sources.list << EOF
deb http://archive.ubuntu.com/ubuntu lucid main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu lucid-updates main restricted universe
deb http://security.ubuntu.com/ubuntu lucid-security main restricted universe
EOF

cat > ./tmpdir/etc/network/interfaces << EOF
auto lo
iface lo inet loopback
auto eth0
iface eth0 inet dhcp
EOF

cat > ./tmpdir/etc/hosts << EOF
127.0.0.1   localhost localhost.localdomain
127.0.1.1   lucid lucid.localdomain
EOF

echo lucid > ./tmpdir/etc/hostname

cat > ./tmpdir/etc/fstab << EOF
/dev/xvda1       /             ext3     defaults               0 0
/dev/xvda3       swap          swap     defaults               0 0
proc            /proc         proc     defaults                0 0
devpts          /dev/pts      devpts   gid=5,mode=620          0 0
EOF

chroot tmpdir
export LANG=C
localedef -v -c -i en_US -f UTF-8 en_US.UTF-8
dpkg-reconfigure locales
dpkg-reconfigure initramfs-tools
update-initramfs -u -k all
exit

cp tmpdir/boot/vmlin* .
cp tmpdir/boot/initrd* .

umount tmpdir

---

Image Verification and Update

We assume here that you are using Xen. First verify that Xen in installed and working via: {{{sudo xm list}}}. This command must execute without error.

Next, create a xen.conf file with contents similar to the following:

kernel = '/local/images/lucid/10GB/vmlinuz-2.6.32-305-ec2'
ramdisk = '/local/images/lucid/10GB/initrd.img-2.6.32-305-ec2'
memory = 2048
vcpus = 2
dhcp    = 'dhcp'
vif = [ '' ]

name = "lucid"
root = '/dev/xvda1 ro'
disk = [ 'file:/local/images/lucid/10GB/root.img,xvda1,w', 'file:/local/images/lucid/10GB/swap.img,xvda3,w' ]

on_poweroff = 'destroy'
on_reboot   = 'destroy'
on_crash    = 'destroy'

Edit this file and change the following entries to match your environment.

• kernel and ramdisk entries: Change these values to the location and filenames that you copied just prior to the umount command in the previous step (${IMAGEHOME} directory).
• vif: change to your bridge if not xenbr0 (e.g. to xenbr1 if appropriate)
• name entry: Change to the hostname of the image
• disk: change the directory and file names of the root.img and swap.img file (in the ${IMAGEHOME} directory).
• optionally, change the memory (we recommend 2048+) and vcpus values and any other values that are required to execute over Xen in your system.

Next, start the image. You should be in the directory that contains your xen.conf file.

-c means jump into the console. If you leave it off, you can then type {{{xm list}}} to get the ID of the instance, then {{{xm console domainID}}} using that ID number (and hit enter), to achieve the same thing.

xm create -c -f xen.conf

Login to the instance once it comes up, as root using the password appscale. Change this password to something secure that you will remember using the passwd command. Use the resize utility to fix your terminal if necessary.

In addition, update the system (this step will fail if networking is not working in the instance). Also update the image with a few basic tools that we need:

apt-get update; apt-get -y upgrade; apt-get -y dist-upgrade; apt-get -y autoremove
resize
echo resize >> /root/.bashrc
ssh-keygen
cp /root/.ssh/id_rsa.pub /root/.ssh/authorized_keys
ifconfig

Note the IP address and ssh into the node from the node itself as root. Type exit to exit this login shell.

To shutdown the VM, use halt as sudo/root from within the instance. Alternatively, from outside the instance, in the host (exit the console of the guestVM via CTRL-]), you can shutdown the instance via xm the command

xm shutdown domainID

where ID is the instance ID you get from

xm list

You can troubleshoot any problems you encounter by looking at the Xen logs in /var/log/xen/ on the host system and via the Xen mailing lists.

When you shutdown the instance, mount and copy out the updated kernel and ramdisk for use in the deployment/image instantiation. Change IMAGEHOME to the appropriate directory.

export IMAGEHOME="/local/images/lucid/10GB"
export FILENAME="root.img"
cd ${IMAGEHOME}
mount -o loop $FILENAME ./tmpdir
cp tmpdir/boot/vmlin* .
cp tmpdir/boot/initrd* .

umount tmpdir

Update the kernel and ramdisk entries in your xen.conf file with the newly copied vmlinuz and initrd file names/versions.

---

Image Creation for KVM

Although we do not have the manpower to fully support other virtual image configuration, we do provide steps for creating an image on a Ubuntu Lucid x86_64 system for the Kernel Virtual Machine (KVM) that implements the Ubuntu Lucid x86_64 system that AppScale requires. For other OS distributions, the steps are likely similar and can be found on online at sites other than ours. We make a 16GB image with 4GB of swap in this example.

First, check that kvm and virsh are installed and working (commands such as kvm-ok''' or virsh list --all''' may tell you). We recommend you instantiate a KVM image that is known to work before proceeding.

Once you are sure that your KVM installation is configured correctly and working, then create 20GB (16GB for root + 4GB for swap) Ubuntu Lucid x86_64 image. We recommend using the interactive system virt-install (virtinst) which you may need to first install via your package manager.

export IMAGEHOME="/local/images/kvm/lucid/16GB"
export FILENAME="root.img"
mkdir -p ${IMAGEHOME}
cd ${IMAGEHOME}
virt-install -n precise -r 2048 -f ${IMAGEHOME}/${FILENAME} -s 20 --vcpus=2 --os-type linux --os-variant=virtio26 --network bridge=br0 --nographics --location='http://jp.archive.ubuntu.com/ubuntu/dists/precise/main/installer-amd64/' --extra-args='console=tty0 console=ttyS0,115200n8'

The -s option sets the disk size (total of all partitions and swap). Here we use 20GB (16GB for the root file system and the rest for swap). The -r option is the memory size (we recommend 2048+). Make sure that the bridge name is correct for your system.

Using the interactive system, select the default values unless specified otherwise here. Change the hostname value to lucid or some other appropriate name. This is the name that is used to refer to the image/instance and that is used for the file name of the config file that this process produces (lucid.xml).

When asked, choose the correct time zone.

When asked for the partitioning method, choose Manual, and

• Select the virtual disk (vda) and select yes to create a new, empty partition table.
• Select the FREE SPACE under virtual disk 1 and Create a New Partition
• Change the size to 16GB, select Primary, and the Beginning location.
• Change "Use as:" from ext4 to ext3 (by pressing enter and selecting).
• Select (hit enter on) the Bootable Flag so that it turns on.
• Then use the down arrow to select "Done setting up this partition".
• Next, press enter on the FREE SPACE entry (this is the remaining space) below the 16GB root (/) entry you just created and select Create a new partition.
• Leave the size as is (select Continue) and press enter on Logical partition.
• Change "Use as:" to swap area (by pressing enter and selecting). Then select "Done setting up this Partition".
• Once you are back to the Partition Disks screen, use the down-arrow to navigate to "Finish partitioning and write changes to disk", and "Yes" to continue on the final screen.

When asked, add a user called appscale and set its password. Choose "No Automatic Updates". When asked about the packages to install, select the Basic Ubuntu Server and the OpenSSH Server.

Upon completion the instance will reboot. Log in as appscale, sudo to the root user (sudo -s), and set the root password. Verify also at this point that you can ssh into the instance from outside using the IP Address (ifconfig eth0) of the instance.

Next, as root and from within the running instance, finish setting up the basic system:

apt-get update; apt-get -y upgrade; apt-get -y dist-upgrade; apt-get -y autoremove
apt-get -y --force-yes install linux-image-server vim xterm wget openssh-server
resize
echo resize >> /root/.bashrc
ssh-keygen
cp /root/.ssh/id_rsa.pub /root/.ssh/authorized_keys
ifconfig

Note the IP address and ssh into the node from the node itself as root. Type exit to exit this login shell. Remove the udev rules so that you can copy the VM to others:

rm -f /etc/udev/rules.d/70-persistent-net.rules

Halt the system when you are done and save off the configuration file for safe keeping:

cd ${IMAGEHOME}
cp /etc/libvirt/qemu/lucid.xml .

If you want to change some value in this file, be sure to undefine the NAME entry (hostname) via virsh undefine lucid (if NAME is set to lucid in the xml file). Then redefine the configuration after making changes to the file via virsh define lucid.xml (using the name of your xml file).

You can instantiate your image via virsh start lucid, replacing lucid with your hostname (NAME value). Attach to the console via virsh console lucid (press enter to get the prompt). Leave the console and return to the host machine by pressing CTRL-] in the instance.

---

Next Steps: Image Configuration

https://github.com/AppScale/appscale/wiki/Installing-AppScale-from-source-on-GitHub