Enabling Your Own Linux Kernels

To enable user-provided kernels, Amazon has published Amazon Kernel Images (AKIs) that use a system called PV-GRUB. PV-GRUB is a paravirtual “mini-OS” that runs a version of GNU GRUB, the standard Linux boot loader. PV-GRUB 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 PV-GRUB 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 PV-GRUB 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.

In order for PV-GRUB 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 EC2 instances, you want to protect against distributions that auto-update the default kernel and break 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 PV-GRUB-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. PV-GRUB 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 PV-GRUB 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 PV-GRUB; almost without exception most users will want to use the hd0 variants.

	Note
	You cannot use the 64-bit version of PV-GRUB to start a 32-bit kernel or vice versa.

	Note
	You must not specify an Amazon ramdisk image (ARI) when using a PV-GRUB AKI.

The following AKI IDs should be used by users who are either registering new AMIs or who want to launch existing AMIs using PV-GRUB. Each AKI type is available in all 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 PV-GRUB method. If you find that to be the case, you should select a different kernel or use a non-PV-GRUB 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 PV-GRUB is a paravirtual 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 PV-GRUB can boot from:

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

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

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

Amazon supports the use of PV-GRUB 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 PV-GRUB. 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-PV-GRUB 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.