Enabling Your Own Linux Kernels

To enable user-provided kernels, Amazon has published Amazon Kernel Images (AKIs) that use a system called PVGRUB. PVGRUB is a para-virtual “mini-OS” that runs a version of GNU GRUB, the standard Linux boot loader. PVGRUB selects the kernel to boot by reading /boot/grub/menu.lst from your image. It will load the kernel specified by your image and then shut down the “mini-OS,” so that it no longer consumes any resources. One of the advantages of this solution is that PVGRUB understands standard grub.conf or menu.lst commands, which allows it to work with most existing Linux distributions.

The following task list describes what you need to do to enable an AMI to use PVGRUB AKI to run a user-provided kernel.

	Note
	To update an existing AMI to use a user-provided kernel, re-launch the AMI and follow steps 1 through 6 specified in the preceding task list.

For procedures associated with the preceding task list, see Using the User-Provided Kernel.

PVGRUB contains a full-featured version of GRUB. In order for PVGRUB to boot, a GRUB menu.lst file must exist in the image. For most distributions, you have two options for the GRUB configuration:

default 0
timeout 3
fallback 1

title Vanilla EC2 Kernel 2.6.32.10
	root (hd0)
	kernel /boot/vmlinux-2.6.32.10-ACME_SYS_EC2 root=/dev/sda1
	initrd /boot/initrd-2.6.32.10-ACME_SYS_EC2

title Ubuntu EC2 2.6.32.302-EC
	root (hd0)
	kernel /boot/ubuntu-ec2 root=/dev/sda1
	initrd /boot/initrd-ec2 

We recommend that you use option two to control the kernel booting for two reasons. First, Amazon EC2 users don’t have interactive control over the boot process because there is no keyboard access. GRUB will proceed without user interaction. Second, and most important for Amazon EBS-backed images, you want to protect against distributions that auto-update the kernel breaking your image. By not relying on the auto-update mechanism and explicitly choosing which kernel you run, you reduce the risk of an incompatible kernel becoming the default kernel.

A fallback kernel does not have to be specified in your menu.lst, but we recommend that you have a fallback when you test new new kernels. GRUB can fall back to another kernel in the event that the new kernel fails. Having a fallback kernel allows the instance to boot even if the new kernel is not found.

There are two special things you should consider when you use a PVGRUB-enabled image to mount EBS volumes. First, for Amazon EBS volumes the first partition must be a boot partition. Second, if you plan to use a logical volume manager (LVM) with Amazon EBS volumes, you need a separate boot partition outside of the LVM. Then you can create logical volumes with the LVM. PVGRUB expects to find the menu.lst in /boot/grub. As a result, if the boot partition is mounted in at /boot, menu.lst will be found in /boot/boot/grub.

Several PVGRUB AKIs are available depending on the type and location of your instance. There are AKIs for 32-bit and 64-bit architecture types, with each having one AKI for partitioned images and another AKI for partitionless images. You must choose an AKI with "hd0" in the name if you want a raw or unpartitioned disk image (most images). Choose an AKI with "hd00" in the name if you want an image that has a partition table.

Most vendors, such as Fedora, Red Hat, Ubuntu, and Novell, use unpartitioned disk images. This means that they use the hd0 variants of PVGRUB; almost without exception most users will want to use the hd0 variants.

	Note
	You cannot use the 64-bit version of PVGRUB to start a 32-bit kernel.

The following AKI IDs should be used by users who are either registering new AMIs or who want to launch existing AMIs using PVGRUB. Each AKI type is available in all five Amazon EC2 Regions:

There are a number of Linux distributions that have compatible Amazon EC2 kernels. The following is a brief, non-comprehensive list of kernels that we have worked with the maintainers to test:

It is possible that your specific Linux kernel will not boot using the new PVGRUB method. If you find that to be the case, you should select a different kernel or use a non-PVGRUB AKI to boot your instance.

	Note
	Kernels that disable the pv-ops XSAVE hypercall are known to work on all instance types, whereas those that enable this hypercall will fail to launch in some cases. Similarly, non-pv-ops kernels that do not adhere to the Xen 3.0.2 interface might fail to launch in some cases.

Since PVGRUB is a para-virtual version of GRUB 0.97, it has all the limitations of GRUB. Most importantly, this means that it will not work properly for certain disk layouts or file system types. The following are the /boot file systems that PVGRUB can boot from:

	Note
	These are the /boot file systems that we have tested and verified. Others could boot from PVGRUB, but haven’t been tested.

The following procedure gives an example of how to enable a openSUSE AMI to use the PVGRUB AKI to run a user-provided kernel by rebundling from a running instance.

	Important
	The specific details of configuring your AMI to use PVGRUB will vary depending on your exact Linux environment. The following example is for openSUSE 11.2.

Amazon supports the use of PVGRUB to load a kernel of your choice for your AMI. However, we cannot provide support for your kernel itself or failures caused by the use of a kernel that does not meet the requirements of PVGRUB. To avoid the situation in which a kernel does not work consistently or at all, we recommend that you use a known good kernel, select a non-PVGRUB AKI, or seek support from your AMI vendor. Unfortunately, due to the wide and varied kernel landscape, it is impossible for Amazon to provide support for all kernel varieties.