Date Category Blog

After releasing the fbsdzfs-ec2imager last week, I posted it on Reddit and got one follow-up suggestion: to include a mini-guide for generically setting up access right to an AWS account. Having an account and access keys to run things there is a prerequisite to running the packer builder, so it seems sensible to flesh this out a bit more. Along with updating the README, today I’ll discuss this a little further and lay out some of the other design plans I’m aiming at.

Table of Contents

  1. Setting Up an AWS Account

    • Creating an IAM User
    • Generation and using Access Keys
      • Key Rotation Script
    • Confirming access for Packer
  2. Staging a VPC and Subnet (in progress)

    • Initial Security Groups

Setting Up An AWS Account

Since the signup procedure for an AWS account is so straightforward, I’m not going to go into this in depth. In short: have an email address, create an Amazon account (or use your existing one), and create an AWS account. All you'll need during the signup process is - a credit card for billing (Amazon will authorize a charge of 1.00 USD to prove the card) - a phone number during the signup process (An automated call will be made to this number to prove your identity)

What we’ll focus on here instead is what happens after you’ve created your account. If the first thing you wonder is what do I do now?, then this is what you do now.

Creating an IAM User

The root user for an AWS account should normally be reserved for billing issues. To interact with your setup, use instead an IAM account with semi-restricted permissions to avoid anyone else acquiring your information and abusing it to rack up charges. AWS Support has been known to be accommodating for issues surrounding identity or service theft, but best practice can prevent you from needing to rely on Amazon's good will.

To start off on the right foot with IAM, make your life easier. The console login for IAM users is different than the login for the account root user, so having a URL to access the console directly helps. First log into the AWS Console's IAM Page as the root user. Before you create a new IAM user for running packer jobs, first take a moment to "customize" the Console login url, at the top of the IAM Dashboard. I'm using, for example, for ease of access (since "queerbsd" was, surprisingly already taken).

Second, you'll want to add a Multi-Factor Authentication (MFA) device to your root account. Although this isn't strictly necessary, it is extremely bad practice to not include MFA. I can recommend Google Authenticator as a virtual MFA device, as it is an easy, free, and safe way to help lock down your root user's access.

Third, create a new user using the dialog provided. This will take you through creating a new account, and creating a group with permissions set for the new user.

IAM User Creation: Step One

For the first part of the dialog, pick a name. The literal login name you use is easiest as $USER will be picked up from your shell, but I've picked leeron for demonstrating how to modify this when running the packer scripts. At least be sure to check both these boxes:

  • [√] Programmatic Access
  • [√] AWS Management Console Access

Since this is your own user, feel free to generate and set a Custom password for the new IAM user account. Take note though that the user account will need the IAMUserChangePassword policy attached to their user, or to the group you'll create for them– unless you want to always delegate updating access rights from the root account.

IAM User Creation: Step Two

The second part of the dialog takes you through creating a group for the new user. I've used "QBSDEc2ImageBuilder" as a group name, then attached the following managed policies which are needed for building and testing an FbsdZFS image.

  • AWSMarketplaceFullAccess
  • AmazonEC2FullAccess
  • AmazonVPCReadOnlyAccess
  • IAMUserChangePassword

Just a note on user permissions: AWS permissions are hugely complex. For a good example of more fine-grained permission possibilities, take a closer look at the IAMUserChangePermission (i.e., "show policy"). For now we'll stick to Managed Policies for ease of use.

IAM User Creation: Steps Three & Four

Step three is only a quick review of the user you're about to generate. If anything looks incorrect, you can stop and change it here before proceeding with the "Create User" button.

Step four shows you the access credentials for the new user. This is the only time these credentials are available, so we'll pause here and take you through the local side of configuring your new user's access rights.

If you close the browser window or forget to copy the user permissions, you'll need to navigate in the IAM Dashboard to Users >> >> Security Credentials, and update both the user's Console password, revoke the old Access Key, and generate a new one.

Configuring Your AWS CLI User

NOTE: This portion presumes you're already using a reasonably unix- or linux-like OS.

Install AWS CLI Tools

The first thing to do is install the AWS CLI, if you haven't already. This tool uses a python library called "boto3" and provides a set of scripts based on this library to connect to the AWS API and run actions. You have two options at this point:

  • Use your local package manager to install either awscli or py27-awscli. Naming conventions may vary.
  • If you have Python's virtualenv installed, set up a virtualenv and run the awscli from there. For instance, after running git-clone on the the fbsdzfs-ec2imager, you could easily just do this:
    virtualenv fbsdzfs-ec2imager
    cd ./fbsdzfs-ec2imager
    source bin/activate
    pip install awscli

Configure AWS CLI With Access Keys

Whichever way you choose to run this, next just configure the access keys using the aws configure utility. If you run this with no parameters, you'll create a default profile for connecting. Here I'll set up a specific profile for "leeron" with dummy credentials.

    $ aws --profile leeron configure 
    AWS Access Key ID [None]: AKIAJXMVPCF22XP4S6UQ
    AWS Secret Access Key [None]: 1XoGNY/krd3IQkJYr8hrQDmJ93nYB8yPBE9VUihW
    Default region name [None]: us-east-1
    Default output format [None]: json

I can test leeron's access now, by running something like

    env AWS_PROFILE=leeron aws ec2 describe-instances

Confirming Access for Packer

Some "gotchas" before you run the builder:

  • AWS checks your local clock when you make calls to the API. If your computer's clock is more than a minute behind, all calls will return an unspecified authorization error.

  • The Free Tier for new users of AWS allows t2.micro instances for building images at no cost. The initial release of fbsdzfs-ec2imager used t2.large instances for the build to help speed the data-dependent process of downloading the source files and base packages. The latest version has been updated to avoid inflicting fees on users, but check the "instance_type" value to confirm that this is in fact using a t2.nano or t2.micro instance, or you will be charged (a very minor fee) for the hour that the packer builder image was started in.

  • At this point you should already be able to run the fbsdzfs-ec2imager packer script, using the default VPC settings that AWS sets up for you when you create an account. A prequisite is subscribing to the FreeBSD instance you'll need to launch in order to run the build. This is self-explanatory when the packer build runs, as it will spit out an error like this:

    ==> amazon-ebssurrogate: Error launching source instance: OptInRequired: In order to use this AWS Marketplace product you need to accept terms and subscribe. To do so please visit

To avoid the error, "subscribe" to the Marketplace AMI you intend to build from (these are split into different products, one for each major FreeBSD release version)

Staging a VPC and Subnet

Technically there's no need to do any of the following; you should be perfectly capable of running fbsdzfs-ec2imager with the account you just created and Everything Should Just Work™ (trademark pending). Everything will be run in the default VPC for your region, pre-generated by Amazon. The following steps are here for anyone who wants to skip the defaults and make a "segregated" VPC.

  • More developed instructions TBD.