Rich0's Gentoo Blog

Gentoo EC2 Tutorial / Bootstrapping

with 4 comments

I want to accomplish a few things with this post.

First, I’d like to give more attention to the work recently done by edowd on Bootstrapping Gentoo in EC2.

Second, I’d like to introduce a few enhancements I’ve made on these (some being merged upstream already).

Third, I’d like to turn this into a bit of a tutorial into getting started with EC2 as well since these scripts make it brain-dead simple.

I’ve previously written on building a Gentoo EC2 image from scratch, but those instructions do not work on EBS instances without adjustment, and they’re fairly manual. Edowd extended this work by porting to EBS and writing scripts to build a gentoo install from a stage3 on EC2. I’ve further extended this by adding a rudimentary plugin framework so that this can be used to bootstrap servers for various purposes – I’ve been inspired by some of the things I’ve seen done with Chef and while that tool doesn’t fit perfectly with the Gentoo design this is a step in that direction.

What follows is a step-by-step howto that assumes you’re reading this on Gentoo and little else, and ends up with you at a shell on your own server on EC2. Those familiar with EC2 can safely skim over the early parts until you get to the git clone step.

  1. To get started, go to, and go through the steps of creating an account if you don’t already have one. You’ll need to specify payment details/etc. If you buy stuff from amazon just use your existing account (if you want), and there isn’t much more than enabling AWS.
  2. Log into, and from the top right corner drop-down under either your name or My Account/Console choose “Security Credentials”.
  3. Browse down to access credentials, click on the X.509 certificate tab, generate a certificate, and then download both the certificate and private key files. The web services require these to do just about anything on AWS.
  4. On your gentoo system run as root emerge ec2-ami-tools ec2-api-tools. This installs the tools needed to script actions on EC2.
  5. Export into your environment (likely via .bashrc) EC2_CERT and EC2_PRIVATE_KEY. These should contain the paths to the files you created in the previous step. Congratulations – any of the ac2-api-tools should now work.
  6. We’re now going to checkout the scripts to build your server. Go to an empty directory and run git clone git:// -b rich0-changes.
  7. chdir to the repository directory if necessary, and within it run ./ This creates security zones and ssh keys automatically for you, and at the end outputs command lines that will build a 32 or 64 bit server. The default security zone will accept inbound connections to anywhere, but unless you’re worried about an ssh zero-day that really isn’t a big deal.
  8. Run either command line that was generated by the setup script. The parameters tell the script what region to build the server in, what security zone to use, what ssh public key to use, and where to find the private key file for that public key (it created it for you in the current directory).
  9. Go grab a cup of coffee – here is what is happening:
    1. A spot request is created for a half decent server to be used to build your gentoo image. This is done to save money – amazon can kill your bootstrap server if they need it, and you’ll get the prevailing spot rate. You can tweak the price you’re willing to pay in the script – lower prices mean more waiting. Right now I set it pretty high for testing purposes.
    2. The script waits for an instance to be created and boot. The build server right now uses an amazon image – not Gentoo-based. That could be easily tweaked – you don’t need anything in particular to bootstrap gentoo as long as it can extract a stage3 tarball.
    3. A few build scripts are scp’ed to the server and run. The server formats an EBS partition for gentoo and mounts it.
    4. A stage3 and portage snapshot are downloaded and extracted. Portage config files (world, make.conf, etc) are populated. A script is created inside the EBS volume, and executed via chroot.
    5. That script basically does the typical handbook install (emerge sync, update world (which has all the essentials in it like dhcpcd and so on), build a kernel, configure rc files, etc.
    6. The bootstrap server terminates, leaving behind the EBS volume containing the new gentoo image. A snapshot is created of this image and registered as an AMI.
    7. A micro instance of the AMI is launched to test it. After successful testing it is terminated.
  10. After the script is finished check the output to see that the server worked. If you want it outputs a command line to make the server public – otherwise only you can see/run it.
  11. To run your server go to, sign in if necessary, browse to the EC2 dashboard. Click on AMIs on the left side, select your new gentoo AMI, and launch it (micro instances are cheap for testing purposes). Go to instances on the left side and hit refresh until your instance is running. Click on it and look down in the details for the public DNS entry.
  12. To connect to your instance run ssh -i <path to pem file in your bootstrap directory> ec2-user@<public DNS name of your server>. You can sudo to root (no password).

That’s it – you have a server in the cloud. When you’re done be sure to clean up to avoid excessive charges (a few cents an hour can add up). Check the instances section and TERMINATE (not stop) any instances that are there. You will be billed by the month for storage so de-register AMIs you don’t need and go to the snapshot section and delete their corresponding snapshots.

Now, all that is useful, but you probably want to tailor your instance. You can of course do that interactively, but if you want to script it check out the plugins in the plugin directory. Just add a path to a plugin file at the end of the command line to build the instance and it will tailor your image accordingly. I plan to clean up the scripts a bit more to move anything discretionary into the plugins (you don’t NEED fcron or atop on a server).

The plugins/desktop plugin is a work in progress, but I think it should work now (takes the better part of a day to build). It only works 32-bit right now due to the profile line. However, if you run it you should be able to connect with x2goclient and have a KDE virtual desktop. A word of warning – a micro instance is a bit underpowered for this.

And on a side note, if somebody could close bugs 427722 and 423855 that would eliminate two hacks in my plugin. The stable NX doesn’t work with x2go (I don’t know if it works for anything else), and the stable gst-plugins-xvideo is missing a dependency. The latter bug will bite anybody who tries to install a clean stage3 and emerge kde-meta.

All of this is very much a work in progress. Patches or pull requests are welcome, and edowd is maintaining a nice set of up-to-date gentoo images for public use based on his scripts.

Note: Recently I modified this script to add my dev overlay. I’m mainly doing this to deal with build failures. However, in the interest of full disclosure I want to make sure all are aware.

Written by rich0

September 24, 2012 at 10:20 am

Posted in foss, gentoo, linux

4 Responses

Subscribe to comments with RSS.

  1. FYI – if you grabbed these scripts earlier today the desktop plugin has some missing dependencies (another bug filed). Just do a git pull for what I think are fixes. A full clean test takes about a day so I won’t know for sure until tomorrow.

    These minimal builds are also great for testing dependencies.

    Also of note – it is REALLY easy to miss dependencies. I missed the font dependency because in my last round of testing I emerged xterm to see if I could launch something simpler than startkde, and that pulled in some fonts. Actually, that has me thinking since that probably didn’t pull in font-cursor-misc and that does seem to be necessary.

    These are RDEPENDs too so even my mailing list proposal of making the sandbox really strict wouldn’t catch those. Only thing to be done there is to run every process in its own sandbox limiting reads to strict RDEPENDs, and that would be quite a project (albeit a very interesting one).


    September 24, 2012 at 11:57 pm

  2. Your scripts are wonderful, but…

    They need some serious sanity-checking added. The emerge that contained the kernel sources failed when:

    [blocks B ] sys-apps/module-init-tools (“sys-apps/module-init-tools” is blocking sys-apps/kmod-12-r1)
    [blocks B ] sys-apps/kmod (“sys-apps/kmod” is blocking sys-apps/module-init-tools-3.16-r2)

    The script kept marching merrily along, even though the emerge and the kernel build failed. The micro-instance test even PASSED, despite the ssh command timing out.

    Once I worked around the package block, everything went smooth as glass.

    mark casagrande

    January 27, 2013 at 1:05 am

    • Yup, more often than not these scripts fail when things change. This tends to happen when the stage3s get old. The micro test passing was a bit of a surprise, though. Are you actually using the latest version with my changes?

      If the emerge exited abnormally the script should basically hang forever waiting for the instance to shut down as I modified it to stay up so that I could manually ssh in and intervene (making it much easier to debug the problem than having it destroy the instance and then crossing my fingers that any changes will fix the issue that might have happened two hours into a build).


      January 27, 2013 at 7:05 am

  3. […] EC2 Marketplace and while we would have gotten technical props for building our own Gentoo AMI (as this post describes) but we really couldn’t justify the extra time. So we resorted to a prebuilt Gentoo AMI from […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: