Before we start, good luck and godspeed, this will be a long haul.
Installing and configuring the aws toolsFirst, download the tools. These can be found on http://timkay.com/aws/. Using these requires you to have the CURL libraries installed (use your packet manager to install, e.g.
sudo apt-get install curlif you're on a Debian based linux like Ubuntu).
Get the tools like explained on the page linked to above. Installation is optional. Just make sure you're in the folder in which you downloaded the "aws" file when using the tools and don't forget to
chmod u+x aws if you prefer not installing the tools. I won't be using an installed version in this tutorial so if you do install, replace all instances of
aws (this will make bash look for aws in your path instead of your current directory).
Don't forget to create a file in your home directory called .awssecret containing your access key id and secret access key id. This file looks like
with the first line containing your api key and the second your api secret.
General noticeOne very important thing to note, is that there isn't exactly "one" Amazon EC2. There are several, the one you should choose depends on your location. These are the so-called endpoints I've talked about before. If you're in the US, you can just use the ./aws without doing something extra and you'll be using the (default) US endpoint. If you're in Europe, you probably want to use the European endpoint. Doing this in Tim Kay's aws tools is done by giving the extra parameter
--region=euafter every command. That's right, every single one.
If you're like me and forget to do this every other command, you can execute the command
exactly once. This will write the option to a file that's used as a set of default options for every aws parameters. This way you don't have to add the
echo "--region=eu" >> ~/.awsrc
--regionparameter to the end of every line and endpoints shouldn't bother you too much.
Creating a new SSH keyDon't confuse this key (the SSH key) with the API key you entered in the ~/.awssecret file. The key in the ~/.awssecret is the key you need when talking to the Amazon API, the key you'll generate here is the key you'll need to talk to your instances.
Instead of giving you a password to connect to your EC2 instance, Amazon allows (well, forces) you to use a more secure RSA key to setup an ssh connection to your instance(s).
Generating this key is easy. Execute the command
To generate a key named "default" (when talking about this key to Amazon, you'll refer to it as "default" or whatever you named the key) and place your private key in a file called "defaultawskey.key" in your current directory. This is a normal run-of-the-mill SSH key. SSH won't accept your key if you give it like this, by default the key file is probably readable by everyone (a security problem which annoys ssh). You can fix the problem by only allowing yourself (so by not allowing other users on your local machine access to this key file) access to the file with
./aws add-keypair default > defaultawskey.key
chmod 600 defaultawskey.key
Allowing SSH access to your server by configuring a groupIf you want your server to do anything, you'll probably need it to execute commands. When starting a new instance, you'll specify a security group. This group will tell the server's firewall what ports to open.
Practically, you want to open a communication channel on TCP port 22 (SSH traffic). You can do this by either modifying an existing security group (one called "default" is created for you by default). Suppose we want to create a new group called "sshonly" and only allow ssh traffic in this group.
Making a new group called sshonly is done with the command
The text in the -d argument is obligatory and contains a short description of your group.
./aws addgrp sshonly -d "Only ssh traffic"
By default, this group is empty (it does not contain any rules). You can confirm this by executing
The output is too wide to display here, but you'll notice nothing is written in the righmost few columns on the "sshonly" row. This is because there are no rules for this group.
Once this new group is created, a new rule can be added to it. This is done with the authorize command.
This authorizes tcp access on port 22 for a security group called "sshonly". The parameter 0.0.0.0/0 is important since this notes that all IP addresses are allowed to ssh to the instance. If you'd like extra security, you can probably enter your own ip address or address range here. Confirm the port was opened succesfully by once again executing
./aws authorize sshonly -P tcp -p 22 -s 0.0.0.0/0
Note the new table containing the columns
A good sign indeed.
ipProtocol | fromPort | toPort | groups tcp | 22 | 22 | item= userId=x cidrIp=0.0.0.0/0
Finding an AMIAn AMI, or Amazon Machine Instance, identifies an image you can use to base your instance on. You can request all possible AMI's by executing the command
This command writes all available ami's to a file called amis.txt in the current directory. Executing this command can and will take a while (it's a very big list). You're best of grepping through it. When you find an image you like (a simple i386 image with a recent ubuntu version on will probably do fine), take note of the string in the first column (ami-xxxxxxxx), you'll be needing this. The one I chose was ami-d80a3fac (an Ubuntu 10.10 server image).
./aws describe-images > amis.txt
Starting a new instanceActually starting a new instance is done by executing
This will start a new instance with ami "ami-d80a3fac", security group "sshonly" and the key named "default" (remember, this was the one for which we stored our private key in the file defaultawskey.key). After pressing enter, the new instance will be in status "Pending". This means Amazon is getting the machine ready for usage. Wait about a minute and run the command
./aws run-instances ami-d80a3fac -g sshonly -k default
Keep running the describe-instances command until a DNS address appears and the state is "running" (not "pending"). Your new instance can be reached on the address given in the describe-instances output, e.g. "ec2-79-125-77-241.eu-west-1.compute.amazonaws.com" and the instance is named "i-44e3d333".
ives ~/aws $ ./aws describe-instances --simple i-44e3d333 running ec2-79-125-77-241.eu-west-1.compute.amazonaws.com
Executing commands on your instanceWe're finally here! We now have SSH access to our running instance. Give the command
with "defaultawskey.key" being the file to which your RSA key was written in the section "Creating a new SSH key" and "ec2-79-125-77-241.eu-west-1.compute.amazonaws.com" being the address your instance can be reached on, given by the describe-instances output.
ssh -i defaultawskey.key email@example.com
Doing this should give you something like
Enter "yes", press return and with some luck you can enjoy your brand new instance.
RSA key fingerprint is 58:ff:ff:42:f1:8e:46:86:71:ef:a6:66:d5:43:4a:d4. Are you sure you want to continue connecting (yes/no)?
If you get the error
Login as the user called "ubuntu" instead of "root", like this:
Please login as the ubuntu user rather than root user.
And everything should be fine. If you got to this point, congratulations, I know it wasn't easy! Anyhow, read on and don't forget to terminate your instances! They're not free.
ssh -i defaultawskey.key firstname.lastname@example.org
will tell you what instances you have running at the moment (on your current endpoint, so make sure you didn't start any servers on the USA endpoint and are looking at the EU instance listing -- they won't show up).
./aws describe-instances --simple
The column on the left contains the instance number. Pass this number to
./aws terminate-instance like this:
with "i-44e3d333" being the instance number "describe-instances" gave you. After entering this command, the describe instances listing will look like this:
./aws terminate-instances i-44e3d333
The instance will keep its "terminated" status for a few hours and will then disappear.
ives ~/aws $ ./aws describe-instances --simple i-44e3d333 terminated