Building EBS Boot and S3 Based AMIs for EC2 with Ubuntu vmbuilder


Here’s my current recipe for how to build an Ubuntu 9.10 Karmic AMI, either the new EBS boot or the standard S3 based, using the Ubuntu vmbuilder software. The Ubuntu vmbuilder utility replaces ec2ubuntu-build-ami for building EC2 images and it can build images for a number of other virtual machine formats as well.

There is a lot of room for simplification and scripting in the following instructions, but I figured I’d publish what is working now so others can take advantage of the research to date. Happy New Year!

Some sections are marked [For EBS boot AMI] or [For S3 based AMI] and should only be followed when you are building that type of AMI. The rest of the sections apply to either type. It is possible to follow all instructions to build both types of AMIs at the same time.

  1. Run an instance of Ubuntu 9.10 Karmic AMI, either 32-bit or 64-bit depending on which architecture AMI you wish to build. I prefer the c1.* instance types to speed up the builds, but you can get by cheaper with the m1.* instance types. Make a note of the resulting instance id:

    # 32-bit
    instanceid=$(ec2-run-instances     --key YOURKEYPAIR                --availability-zone us-east-1a   --instance-type c1.medium        ami-1515f67c |
      egrep ^INSTANCE | cut -f2)
    echo "instanceid=$instanceid"
    # 64-bit
    instanceid=$(ec2-run-instances     --key YOURKEYPAIR                --availability-zone us-east-1a   --instance-type c1.xlarge        ami-ab15f6c2 |
      egrep ^INSTANCE | cut -f2)
    echo "instanceid=$instanceid"

    Wait for the instance to move to the “running” state, then note the public hostname:

    while host=$(ec2-describe-instances "$instanceid" | 
      egrep ^INSTANCE | cut -f4) && test -z $host; do echo -n .; sleep 1; done
    echo host=$host
  2. Copy your X.509 certificate and private key to the instance. Use the correct locations for your credential files:

    rsync                              --rsh="ssh -i YOURKEYPAIR.pem"   --rsync-path="sudo rsync"        ~/.ec2/{cert,pk}-*.pem           ubuntu@$host:/mnt/
  3. Connect to the instance:

    ssh -i YOURKEYPAIR.pem ubuntu@$host
  4. Install the image building software. We install the python-vm-builder package from Karmic, but we’re going to be using the latest vmbuilder from the development branch in Launchpad because it has good bug fixes. We also use the EC2 API tools from the Ubuntu on EC2 ec2-tools PPA because they are more up to date than the ones in Karmic, letting us register EBS boot AMIs:

    export DEBIAN_FRONTEND=noninteractive
    echo "deb karmic main" |
      sudo tee /etc/apt/sources.list.d/ubuntu-on-ec2-ec2-tools.list &&
    sudo apt-key adv --keyserver --recv-keys 9EE6D873 &&
    sudo apt-get update &&
    sudo -E apt-get upgrade -y &&
    sudo -E apt-get install -y   python-vm-builder ec2-ami-tools ec2-api-tools bzr &&
    bzr branch lp:vmbuilder

    You can ignore the “Launchpad ID” warning from bzr.

  5. Fill in your AWS credentials:

    export AWS_USER_ID=...
    export AWS_ACCESS_KEY_ID=...
    export AWS_SECRET_ACCESS_KEY=...
    export EC2_CERT=$(echo /mnt/cert-*.pem)
    export EC2_PRIVATE_KEY=$(echo /mnt/pk-*.pem)

    Set up parameters and create files to be used by the build process. The bucket value is only required for S3 based AMIs:

    if [ $(uname -m) = 'x86_64' ]; then
      kernelopts="--ec2-kernel=aki-fd15f694 --ec2-ramdisk=ari-c515f6ac"
      ebsopts="--kernel=aki-fd15f694 --ramdisk=ari-c515f6ac"
      ebsopts="$ebsopts --block-device-mapping /dev/sdb=ephemeral0"
      kernelopts="--ec2-kernel=aki-5f15f636 --ec2-ramdisk=ari-0915f660"
      ebsopts="--kernel=aki-5f15f636 --ramdisk=ari-0915f660"
      ebsopts="$ebsopts --block-device-mapping /dev/sda2=ephemeral0"
    cat > part-i386.txt <<EOM
    root 10240 a1
    /mnt 1 a2
    swap 1024 a3
    cat > part-x86_64.txt <<EOM
    root 10240 a1
    /mnt 1 b
  6. Create a script to perform local customizations to the image before it is bundled. This is passed to vmbuilder below using the --execscript option:

    cat > setup-server <<'EOM'
    #!/bin/bash -ex
    # fix what I consider to be bugs in vmbuilder
    perl -pi -e "s%^*\n%%" $imagedir/etc/hosts
    rm -f $imagedir/etc/hostname
    # Use multiverse
    perl -pi -e 's%(universe)$%$1 multiverse%'   $imagedir/etc/ec2-init/templates/sources.list.tmpl
    # Add Alestic PPA for runurl package (handy in user-data scripts)
    echo "deb karmic main" |
      tee $imagedir/etc/apt/sources.list.d/alestic-ppa.list
    chroot $imagedir   apt-key adv --keyserver --recv-keys BE09C571
    # Add ubuntu-on-ec2/ec2-tools PPA for updated ec2-ami-tools
    echo "deb karmic main" |
      sudo tee $imagedir/etc/apt/sources.list.d/ubuntu-on-ec2-ec2-tools.list
    chroot $imagedir   sudo apt-key adv --keyserver --recv-keys 9EE6D873
    # Install packages
    chroot $imagedir apt-get update
    chroot $imagedir apt-get install -y runurl
    chroot $imagedir apt-get install -y ec2-ami-tools
    chmod 755 setup-server
  7. Build the image:

    now=$(date +%Y%m%d-%H%M)
    description="Ubuntu $release $codename $arch $tag $now"
    sudo vmbuilder/vmbuilder xen ubuntu         --suite=$codename                         --arch=$arch2                             --dest=$dest                              --tmp=/mnt                                --ec2                                     --ec2-version="$description"              --manifest=$prefix.manifest               --lock-user                               --part=part-$arch.txt                     $kernelopts                               $pkgopts                                  --execscript ./setup-server               --debug

    [For S3 based AMI] include the following options in the vmbuilder command above. This does not preclude you from also building an EBS boot AMI with the same image. Make a note of the resulting AMI id output by vmbuilder:

      --ec2-bundle                              --ec2-upload                              --ec2-register                            --ec2-bucket=$bucket                      --ec2-prefix=$prefix                      --ec2-user=$AWS_USER_ID                   --ec2-cert=$EC2_CERT                      --ec2-key=$EC2_PRIVATE_KEY                --ec2-access-key=$AWS_ACCESS_KEY_ID       --ec2-secret-key=$AWS_SECRET_ACCESS_KEY 
  8. [For EBS boot AMI] Copy the image files to a new EBS volume, snapshot it, and register the snapshot as an EBS boot AMI. Make a note of the resulting AMI id:

    size=15 # root disk in GB
    volumeid=$(ec2-create-volume --size $size --availability-zone us-east-1a |
      cut -f2)
    instanceid=$(wget -qO- http://instance-data/latest/meta-data/instance-id)
    ec2-attach-volume --device /dev/sdi --instance "$instanceid" "$volumeid"
    while [ ! -e /dev/sdi ]; do echo -n .; sleep 1; done
    sudo mkfs.ext3 -F /dev/sdi
    sudo mkdir $ebsimage
    sudo mount /dev/sdi $ebsimage
    sudo mkdir $imageroot
    sudo mount -oloop $dest/root.img $imageroot
    sudo tar -cSf - -C $imageroot . | sudo tar xvf - -C $ebsimage
    sudo umount $imageroot $ebsimage
    ec2-detach-volume "$volumeid"
    snapshotid=$(ec2-create-snapshot "$volumeid" | cut -f2)
    ec2-delete-volume "$volumeid"
    while ec2-describe-snapshots "$snapshotid" | grep -q pending
      do echo -n .; sleep 1; done
    ec2-register                     --architecture $arch           --name "$prefix"               --description "$description"   $ebsopts                       --snapshot "$snapshotid"
  9. Depending on what you want to keep from the above process, there are various things that you might want to clean up.

    If you no longer want to use an S3 based AMI:

    ec2-deregister $amiid
    ec2-delete-bundle                       --access-key $AWS_ACCESS_KEY_ID       --secret-key $AWS_SECRET_ACCESS_KEY   --bucket $bucket                      --prefix $prefix

    If you no longer want to use an EBS boot AMI:

    ec2-deregister $amiid
    ec2-delete-snapshot $snapshotid

    When you’re done with the original instance:

    ec2-terminate-instance $instanceid

In the above instructions I stray a bit from the defaults. For example, I add the runurl package from the Alestic PPA so that it is available for use in user-data scripts on first boot. I enable multiverse for easy access to more software, and I install ec2-ami-tools which works better for me than the current euca2ools.

I also set /mnt to the first ephemeral store on the instance even on EBS boot AMIs. This more closely matches the default on the S3 based AMIs, but means that /mnt will not be persistent across a stop/start of an EBS boot instance.

Explore and set options as you see fit for your applications. Go wild with the --execscript feature (similar to the ec2ubuntu-build-ami --script option) to customize your image.

The following vmbuilder options do not currently work with creating EC2 images: --mirror, --components, --ppa. I have submitted bug 502490 to track this.

As with much of my work here, I’m simply explaining how to use software that others have spent a lot of energy building. In this case a lot of thanks go to the Ubuntu server team for developing vmbuilder, the EC2 plugin, the ec2-init startup software, and the code which builds the official Ubuntu AMIs; especially Søren Hansen, Scott Moser, and Chuck Short. I also appreciate the folks who reviewed early copies of these instructions and provided feedback including Scott Moser, Art Zemon, Trifon Trifonov, Vaibhav Puranik, and Chris.

Community feedback, bug reports, and enhancements for these instructions are welcomed.


> instanceid=$(wget -qO- http://instance-data/latest/meta-data/instance-id)

Where did you find out about 'instance-data' ? is that something documented in an amazon API ? I'd never seen it before and its largely more rememberable than ''.

smoser: I saw others using /instance-data/ here and there and found it worked. I use it when an instance is up and I forget the string of numbers, or when I want to shorten a line in a tutorial. I avoid it when writing serious instance startup code as I don't want to add a dependency on some DNS server somewhere inside EC2.

I have a problem with installing mysql - the post install process fails...

I also have a similar problem with ec2-api-tools (i believe in the java install)

any suggestions?

+ chroot /mnt/vmbuilderXTRe9u/root apt-get install -y mysql-server-5.1
invoke-rc.d: initscript mysql, action "stop" failed.
invoke-rc.d: initscript mysql, action "start" failed.
dpkg: error processing mysql-server-5.1 (--configure):
subprocess installed post-installation script returned error exit status 1
Errors were encountered while processing:
E: Sub-process /usr/bin/dpkg returned an error code (1)

I also have a similar problem with ec2-api-tools (i believe in the java install)

any suggestions?

Thank you for sharing these great articles with us, Eric!

I deregistered my 2-month old ubuntu karmic koala at ec2 as I experienced it as really slow. Well, I did run it on a small 32-bit instance, but really, it feels like something is wrong. Would you recommend 8.04 for servers on EC2 or am I misunderstanding something fundamental?

Ole: If you need any kind of performance, stay away from m1.small. The c1.medium have about 5x the performance at 2x the price. As far as AMIs go I would recommend either Canonical's Karmic or Canonical's Hardy.

saltkev: When some packages (e.g., mysql-server) are installed, they automatically try to run their daemons which can cause problems in the chroot environment. Turn this off by wrapping the installs inside of:

cat <<EOF > $imagedir/usr/sbin/policy-rc.d
exit 101
chmod 755 $imagedir/usr/sbin/policy-rc.d
[...install stuff here...]

rm -f $imagedir/usr/sbin/policy-rc.d

Hi, Eric, thanks a lot for your helpful article and your great AMIs :).

I tried to run the script and made some changes for my needs. For instance, I add a variable named region to set a differrent region.

Here is the script. It worked fine on the eu-west-1 region when I made a 64bit image. 32bit is not tested yet.

eric: The first line of that script for saltkev should be

cat > $imagedir/usr/sbin/policy-rc.d <<EOF


Thanks for catching the HTML error. I've fixed it in my original comment.


Why did you use /dev/sda2=ephemeral0 on the 32-bit platform and /dev/sdb=ephemeral0 on the 64-bit platform?

-- Art Z.

Art: Those devices are the standards used by Amazon EC2 with S3-based AMIs. You can change them in the EBS boot AMIs, but I chose to be consistent with where folks are used to seeing them so that existing systems software would continue to work. Now that I think about it, I should have added ephemeral1-3 on the 64-bit for large/xlarge.

See also:

You need to do this

echo mysql-server mysql-server/root_password select <ROOT_PASSWORD> |
echo mysql-server mysql-server/root_password_again select <ROOT_PASSWORD> |
before you call
apt-get install mysql-server

Regarding which instance to use, I went and compared prices.

If the task is CPU-bound, then the c1.medium instance is the way to go. Even for single-threaded tasks, it's 20% cheaper than the m1.small.

Of course, spending a lot of time with the processor idle would shift things back toward the m1.small.

wpietri: According to my calculations on a compute-unit-equivalent scale, a c1.medium is 60% less expensive than an m1.small (2/5 the cost), and an m1.small is 150% more expensive than a c1.medium (2.5 times the cost). Percentage math is fun.

In any case, for serious purposes, m1.smalls are miserable and c1.mediums and above are great. We've been running an m2.2xlarge for a while and it really hums.

The above command works great if i run it manually
8 [For EBS boot AMI] Copy the image files to a new EBS volume, snapshot it, and register the

I have issues if i run the same script through ssh

Example: $ssh -i mykey.pem root@host /opt/jamcracker/./ us-east-1a i-db8da6b0 /dev/sdh 10 i386 imgname345 imgname345

File not found: ''
File not found: ''

what may be the issues ??

clouduser: There is insufficient information in your report to be able to make an easy diagnosis. I would suggest you post your complete code to a forum or group for assistance.

First, thanks for all your contributions! I have learned a ton from your articles as I navigate using EC2/AWS.

I ran into an issue when trying to build the image - I received this error:

vmbuilder: error: no such option: --tmp

I cannot find any reference to that option in the man pages, but nothing turns up in my searches about it being deprecated either. Is it a typo, or am I missing something?


Tim: I've stopped using raw vmbuilder and simply start with the EC2 image files created by Canonical following this method:

You can still get help with vmbuilder through the normal Ubuntu channels (ubuntu-cloud mailing list, #ubuntu-server on IRC, for reporting bugs, etc.).

Hmm, I saw that article and ran thru it successfully for practice, but this one allows you to make an EBS Boot AMI from an existing instance—which is what I need to do at the moment. I started with a standard Canonical AMI (Karmic 9.10) and configured it to my needs and now I want to snapshot it to an image.

I'll see what I can find on the vmbuilder error at

You've probably already figured out a solution, but I just ran up against the same issue while following this tutorial.

I found a workaround by installing an older version of vmbuilder. I just had to modify the line:

> bzr branch lp:vmbuilder
to read instead:
> bzr branch lp:vmbuilder/0.11 vmbuilder

Hope this helps someone. :)

samhiatt: Thanks. I don't think I've run vmbuilder since Canonical started publishing the images they create with vmbuilder. It's much easier to start with those and customize the resulting file system. Or, I just start a stock Ubuntu AMI and customize at run time.

Can you supply me with instructions how to create a persistent EBS instance that keeps its information across a stop/start of an EBS boot instance.

Thanks for sharing your instructions with us.

bach.henrik: Sure thing. Just start an instance of an EBS boot AMI.

I'm following your above instructions to create an Amazon EBS instance.

But, I have problems with the --ec2 option for enabling the EC2 pluging:

$ sudo vmbuilder/vmbuilder xen ubuntu --ec2 --help
Usage: vmbuilder hypervisor distro [options]

vmbuilder: error: no such option: --ec2

Any ideas is appreciated.


These instructions are quite old and vmbuilder has had a lot of development since then. I don't have a need to use vmbuilder any more, so I'd recommend asking your questions in another forum, perhaps the ubuntu-cloud or ubuntu-server mailing lists.

Leave a comment

Ubuntu AMIs

Ubuntu AMIs for EC2:

More Entries

When Are Your SSL Certificates Expiring on AWS?
If you uploaded SSL certificates to Amazon Web Services for ELB (Elastic Load Balancing) or CloudFront (CDN), then you will want to keep an eye on the expiration dates and…
Throw Away The Password To Your AWS Account
reduce the risk of losing control of your AWS account by not knowing the root account password As Amazon states, one of the best practices for using AWS is Don’t…
AWS Community Heroes Program
Amazon Web Services recently announced an AWS Community Heroes Program where they are starting to recognize publicly some of the many individuals around the world who contribute in so many…
EBS-SSD Boot AMIs For Ubuntu On Amazon EC2
With Amazon’s announcement that SSD is now available for EBS volumes, they have also declared this the recommended EBS volume type. The good folks at Canonical are now building Ubuntu…
EC2 create-image Does Not Fully "Stop" The Instance
The EC2 create-image API/command/console action is a convenient trigger to create an AMI from a running (or stopped) EBS boot instance. It takes a snapshot of the instance’s EBS volume(s)…
Finding the Region for an AWS Resource ID
use concurrent AWS command line requests to search the world for your instance, image, volume, snapshot, … Background Amazon EC2 and many other AWS services are divided up into various…
Changing The Default "ubuntu" Username On New EC2 Instances
configure your own ssh username in user-data The official Ubuntu AMIs create a default user with the username ubuntu which is used for the initial ssh access, i.e.: ssh ubuntu@<HOST>…
Default ssh Usernames For Connecting To EC2 Instances
Each AMI publisher on EC2 decides what user (or users) should have ssh access enabled by default and what ssh credentials should allow you to gain access as that user.…
New c3.* Instance Types on Amazon EC2 - Nice!
Worth switching. Amazon shared that the new c3.* instance types have been in high demand on EC2 since they were released. I finally had a minute to take a look…
Query EC2 Account Limits with AWS API
Here’s a useful tip mentioned in one of the sessions at AWS re:Invent this year. There is a little known API call that lets you query some of the EC2…
Using aws-cli --query Option To Simplify Output
My favorite session at AWS re:Invent was James Saryerwinnie’s clear, concise, and informative tour of the aws-cli (command line interface), which according to GitHub logs he is enhancing like crazy.…
Reset S3 Object Timestamp for Bucket Lifecycle Expiration
use aws-cli to extend expiration and restart the delete or archive countdown on objects in an S3 bucket Background S3 buckets allow you to specify lifecycle rules that tell AWS…
Installing aws-cli, the New AWS Command Line Tool
consistent control over more AWS services with aws-cli, a single, powerful command line tool from Amazon Readers of this tech blog know that I am a fan of the power…
Using An AWS CloudFormation Stack To Allow "-" Instead Of "+" In Gmail Email Addresses
Launch a CloudFormation template to set up a stack of AWS resources to fill a simple need: Supporting Gmail addresses with “-” instead of “+” separating the user name from…
New Options In ec2-expire-snapshots v0.11
The ec2-expire-snapshots program can be used to expire EBS snapshots in Amazon EC2 on a regular schedule that you define. It can be used as a companion to ec2-consistent-snapshot or…
Replacing a CloudFront Distribution to "Invalidate" All Objects
I was chatting with Kevin Boyd (aka Beryllium) on the ##aws Freenode IRC channel about the challenge of invalidating a large number of CloudFront objects (35,000) due to a problem…
Email Alerts for AWS Billing Alarms
using CloudWatch and SNS to send yourself email messages when AWS costs accrue past limits you define The Amazon documentation describes how to use the AWS console to monitor your…
Cost of Transitioning S3 Objects to Glacier
how I was surprised by a large AWS charge and how to calculate the break-even point Glacier Archival of S3 Objects Amazon recently introduced a fantastic new feature where S3…
Running Ubuntu on Amazon EC2 in Sydney, Australia
Amazon has announced a new AWS region in Sydney, Australia with the name ap-southeast-2. The official Ubuntu AMI lookup pages (1, 2) don’t seem to be showing the new location…
Save Money by Giving Away Unused Heavy Utilization Reserved Instances
You may be able to save on future EC2 expenses by selling an unused Reserved Instance for less than its true value or even $0.01, provided it is in the…
Installing AWS Command Line Tools from Amazon Downloads
This article describes how to install the old generation of AWS command line tools. For the most part, these have been replaced with the new AWS cli that is…
Convert Running EC2 Instance to EBS-Optimized Instance with Provisioned IOPS EBS Volumes
Amazon just announced two related features for getting super-fast, consistent performance with EBS volumes: (1) Provisioned IOPS EBS volumes, and (2) EBS-Optimized Instances. Starting new instances and EBS volumes with…
Which EC2 Availability Zone is Affected by an Outage?
Did you know that Amazon includes status messages about the health of availability zones in the output of the ec2-describe-availability-zones command, the associated API call, and the AWS console? Right…
Installing AWS Command Line Tools Using Ubuntu Packages
See also: Installing AWS Command Line Tools from Amazon Downloads Here are the steps for installing the AWS command line tools that are currently available as Ubuntu packages. These include:…
Ubuntu Developer Summit, May 2012 (Oakland)
I will be attending the Ubuntu Developer Summit (UDS) next week in Oakland, CA.  This event brings people from around the world together in one place every six months to…
Uploading Known ssh Host Key in EC2 user-data Script
The ssh protocol uses two different keys to keep you secure: The user ssh key is the one we normally think of. This authenticates us to the remote host, proving…
Seeding Torrents with Amazon S3 and s3cmd on Ubuntu
Amazon Web Services is such a huge, complex service with so many products and features that sometimes very simple but powerful features fall through the cracks when you’re reading the…
There are a number of CloudCamp events coming up in cities around the world. These are free events, organized around the various concepts, technologies, and services that fall under the…
Use the Same Architecture (64-bit) on All EC2 Instance Types
A few hours ago, Amazon AWS announced that all EC2 instance types can now run 64-bit AMIs. Though t1.micro, m1.small, and c1.medium will continue to also support 32-bit AMIs, it…
ec2-consistent-snapshot on GitHub and v0.43 Released
The source for ec2-conssitent-snapshot has historically been available here: ec2-consistent-snapshot on using Bazaar For your convenience, it is now also available here: ec2-consistent-snapshot on GitHub using Git You are…