Debian or Ubuntu

Preparing an existing installation for AoE

You can either work with an installation on

  1. a physical disk on a client machine or
  2. a chroot(8) environment operating on a loopback-mounted disk image

Install the aoetools package. For Ubuntu, you need to put the universe part of the distribution into /etc/apt/sources.list, for example:

 deb http://archive.ubuntu.com/ubuntu feisty main universe

Install a kernel image that includes the aoe driver, i.e. the stock linux-image-2.6.18-* images included with Debian 4.0 and the linux-image-2.6.20-* images included with Ubuntu “Feisty Fawn”.

Create two scripts shown below. These scripts have to be executable.

  • /etc/initramfs-tools/hooks/aoetools will copy the aoe kernel module and /sbin/aoe-discover to the initial ramdisk.
  • /etc/initramfs-tools/scripts/local-top/aoetools is copied to the ram disk and run at boot-time, just before the root filesystem is mounted. If the root device string looks like an AoE target, it brings up all recognized Ethernet interfaces and activates the AoE driver.

After you have made sure that /etc/initramfs-tools/initramfs.conf contains the line

 BUSYBOX=y

you can update the initial ramdisk:

 # update-initramfs -u -k all

Update your /etc/fstab (or create a new one) as shown in the example below. The Linux AoE driver puts all device files into /etc/etherd/. Entire virtual disks are assigned names eX.Y where (X Y) is a unique AoE shelf:slot number within the local network. Individual partitions on those disks are assigned names eX.YpZ

# file system      mount point   type    options                  dump pass
/dev/etherd/e0.0p1 /             ext3    defaults                 0    1
/dev/etherd/e0.0p2 none          swap    sw                       0    0
proc               /proc         proc    defaults                 0    0

Update /boot/grub/menu.lst (or create a new one) so that the root device is passed to the kernel (in this example via the parameter root=/dev/etherd/e0.0p1).

If the modifications were applied to a physical disk on the client machine, you can now transfer the contents of your physical disk to the SAN target.

If the image you wish to export to client systems was modified directly,, you can now make the contents of that image available via AoE.

Preparing a chroot installation for AoE

Generating a bootable system image under chroot is very quick and easy. The following instructions will help you prepare a base image for Ubuntu 7.10 Gutsy Gibbon. After your base image is prepared you will be able to reuse that image for full Ubuntu setups (regular, Xubuntu, Kubuntu). Optionally you can proceed from that base with your own custom configuration while still enjoying the stability and support of Ubuntu.

What you need for this guide: A running Ubuntu system. For the sake of commonality we will use an x86 version in this guide. The Ubuntu tools; schroot, debootstrap, and aoetools.

# sudo apt-get install schroot debootstrap aoetools

Since we are not imaging an existing system we will need an empty image file to which we can install. On the server that you use to host your AoE targets (your vblade server) we need to create a blank file. The system can be set up on a 4gb file for testing purposes, but for a functional, flexible system you will want 10gb or more.

# dd if=/dev/zero of=image.img bs=1 count=1 seek=10G

All that remains to be done on the server (assuming that you have already configured your dhcp server to boot your AoE clients, refer to other HowTos on this wiki) is to make the image available.

# sudo vbladed X X ethX image.img #Where X is equal to your desired parameters.

Now we are ready to access the image as a block device via AoE. Using the Ubuntu system prepared with schroot, debootstrap, and aoetools we need to partition and format the disk image. We will start by preparing the special device files for AoE target mounting.

# sudo aoe-mkdevs /dev/etherd

Now that the special device files exist we can discover AoE devices on the network.

# sudo aoe-discover

We can verify the presence of our target by using the command aoe-stat.

# aoe-stat

If all went well the output should look something like this: eX.X 10GB ethY up #Where X is equal to the values you specified with vblade, and Y is equal to the specs of your system. Now we can partition the disk image.

# sudo fdisk /dev/etherd/eX.X #Where X is equal to the values you specified with vblade.

Fdisk is a fairly straightforward application for partitioning block devices in a terminal. However, you may create your partitions using gparted or any partition utility you wish. While running an AoE system you may not want to create a swap file, as using swap will increase the amount of load your system places on the network during usage, and can slow things down dramatically. For the purposes of this guide we will assume you have just used the whole disk for one partition. Now we will need a filesystem for our image. We will use the Ext3 filesystem here.

# sudo mke2fs -j /dev/etherd/eX.Xp1

Now we have a block device image that is ready for action. In order to begin the bootstrap process the disk image must be mounted. Begin by creating a mount point for our target.

# sudo mkdir /mnt/chroot

The image file can now be mounted under the empty directory (mount point).

# sudo mount /dev/etherd/eX.Xp1 /mnt/chroot

To install the base system to your image we invoke debootstrap. This handy utility will prepare our image for Debian or Ubuntu. For this guide we will be using Ubuntu Gutsy Gibbon.

# sudo debootstrap --components=main,restricted,universe,multiverse gutsy /mnt/chroot

The base system should be installed under /mnt/chroot so we can now switch to it.

# sudo chroot /mnt/chroot

We will make sure that the setup is optimal by verifying that we have the latest versions at this point, and making certain that we have some crucial tools. Also we will need a linux kernel, a boot loader, and the aoetools. It is also a good idea to set our locale and time zone information at this point.

# locale-gen en_US.UTF-8 #Or your specific locale if you aren't in the US
# tzselect
# apt-get update
# apt-get install debconf devscripts nano wget gnupg
# apt-get update #In case gnupg has the sniffles
# apt-get upgrade #It is always better to be certain that you have the latest versions than guess
# apt-get install linux-generic grub aoetools

To make our image bootable, Grub must be setup within the MBR. In order for this to work, we must first create the AoE special devices in our chroot. Then we must discover AoE targets so that we may mount our image under the chroot using the mount point /aoeroot.

# aoe-mkdevs /dev/etherd
# aoe-discover
# mkdir /aoeroot
# mount /dev/etherd/eX.Xp1 /aoeroot #Where X is equal to the values you specified with vblade.

Grub will require a bit of preparation as well. First we will need to create the grub directory under /boot, then we will populate that directory with some grub essentials.

# mkdir /boot/grub
# cp -r /usr/lib/grub/i386/. /boot/grub

Grub will require a file called devices.map to be present under /boot/grub. Using the nano text editor we can create this simple file quickly.

# nano /boot/grub/devices.map

Add the line: (hd0) /dev/etherd/eX.X (Where X is equal to the values you specified with vblade.) Save the file (in nano ctrl+o) and exit (in nano ctrl+x). Now Grub is ready to install to the MBR

# grub-install /dev/etherd/eX.X #Where X is equal to the values you specified with vblade.

Note that this setup still requires the scripts provided on this page, the creation of /etc/fstab, and the creation of /boot/grub/menu.lst. Some users may have difficulty using Gnome unless they add iface lo inet loopback and auto lo to /etc/network/interfaces. Always make certain to run update-initramfs -c -k all -v after any changes to keep your system booting happily. When you are finished creating/customizing /etc/fstab, /boot/grub/menu.lst and /etc/network/interfaces you will have a basic bootable image suitable for reuse. Setting up a new client is as simple as: copy the image, use vblade to make the new image available, mount the image, edit the specifics (ie: /boot/grub/menu.lst, /etc/hosts, etc) then boot from your new client. Once you have booted this basic image, making it a full system is as simple as apt-get install ubuntu-desktop, ubuntu-server, xubuntu-desktop, kubuntu-desktop, or whichever you choose.

Troubleshooting

It is possible to get a shell in Debian's and Ubuntu's initial ramdisks at various stages by passing debug=<WHEN> to the kernel. For debugging issues related to a boot device not being found, debug=mount is probably most useful.

See initramfs-tools(8) for further details.

Things to look out for include:

  • Has the driver for the NIC been loaded?
  • Is the interface “up”?
  • Has the aoe kernel module ben loaded?
  • Does /dev/aoe/ exist, does it contain the necessary entries?

Scripts

/etc/initramfs-tools/hooks/aoetools

#!/bin/sh
 
set  -e
 
PREREQ=""
 
prereqs()
{
	echo "$PREREQ"
}
 
case $1 in
prereqs)
	prereqs
	exit 0
	;;
esac
 
. /usr/share/initramfs-tools/hook-functions
 
[ -x /sbin/aoe-discover ] && copy_exec /sbin/aoe-discover /sbin
manual_add_modules aoe

/etc/initramfs-tools/scripts/local-top/aoetools

#!/bin/sh
 
set -e
 
PREREQ="udev"
 
prereqs()
{
	echo "$PREREQ"
}
 
case $1 in
prereqs)
	prereqs
	exit 0
	;;
esac
 
case $ROOT in
/dev/etherd/e*)
	INTERFACES=`sed -ne '/eth.*:/{s/:.*$//;p;}' < /proc/net/dev`
	for i in $INTERFACES; do
		echo Bringing up interface $i for AoE
		ifconfig $i up
	done
	# Make sure udev has processed all events from adding the NIC
	# modules before loading aoe
	[ -x /sbin/udevsettle ] && /sbin/udevsettle --timeout=30
	modprobe aoe
	# Wait until aoe device files have been generated.
	[ -x /sbin/udevsettle ] && /sbin/udevsettle --timeout=30
	aoe-discover
	;;
esac