Running an Instance

Topics

Before We Begin

Before running an instance, verify the requirements in the following table.

Verification Steps

1	Ensure you have a version 1.5.0 compatible Java Runtime installation, and that the `JAVA_HOME` environment variable has been correctly set. If not, see The Java Runtime Environment.
2	Ensure you have an active Amazon Web Services Account, and that you've signed up for both Amazon S3 and Amazon EC2. If not, see Setting up an Account.
3	Ensure that you have created a directory called `.ec2` in your home directory, that it contains your X.509 certificate and private key, and that they're named correctly. If not, see Signing up for Amazon EC2.
4	Ensure that the `EC2_HOME` environment variable has been correctly set. If not, see Telling the Tools Where They Live.
5	Ensure that the `EC2_CERT` and `EC2_PRIVATE_KEY` environment variables have been correctly set. If not, see Telling the Tools Who You Are.

Once these are correct, you are ready to launch your first instance.

Finding a Suitable AMI

To find a suitable AMI

Use the ec2-describe-images command.

PROMPT> ec2-describe-images -o self -o amazon | grep machine

IMAGE    ami-2c5fba45    ec2-public-images/demo-paid-AMI-v1.07.manifest.xml    amazon    available    public    A79EC0DB    i386    machine
IMAGE    ami-bd9d78d4    ec2-public-images/demo-paid-AMI.manifest.xml     amazon    available    public    A79EC0DB    i386    machine
IMAGE    ami-2f5fba46    ec2-public-images/developer-image-i386-v1.07.manifest.xml    amazon     available    public        i386    machine    
IMAGE    ami-26b6534f    ec2-public-images/developer-image.manifest.xml    amazon    available     public        i386    machine
IMAGE    ami-f51aff9c    ec2-public-images/fedora-8-i386-base-v1.06.manifest.xml    amazon    available    public        i386    machine    aki-a71cf9ce    ari-a51cf9cc
IMAGE    ami-2b5fba42    ec2-public-images/fedora-8-i386-base-v1.07.manifest.xml    amazon     available    public        i386    machine    aki-a71cf9ce    ari-a51cf9cc
IMAGE    ami-f21aff9b    ec2-public-images/fedora-8-x86_64-base-v1.06.manifest.xml    amazon     available    public        x86_64    machine    aki-b51cf9dcari-b31cf9da
IMAGE    ami-2a5fba43    ec2-public-images/fedora-8-x86_64-base-v1.07.manifest.xml    amazon    available    public        x86_64    machine    aki-b51cf9dcari-b31cf9da
IMAGE    ami-a21affcb    ec2-public-images/fedora-core-6-x86_64-base-v1.06.manifest.xml    amazon    available    public        x86_64    machine    aki-a53adfccari-a23adfcb
IMAGE    ami-2d5fba44    ec2-public-images/fedora-core-6-x86_64-base-v1.07.manifest.xml     amazon    available    public        x86_64    machine    aki-a53adfccari-a23adfcb 
IMAGE    ami-225fba4b    ec2-public-images/fedora-core4-apache-mysql-v1.07.manifest.xml    amazon    available    public        i386    machine    
IMAGE    ami-25b6534c    ec2-public-images/fedora-core4-apache-mysql.manifest.xml    amazon    available    public        i386    machine
IMAGE    ami-2e5fba47    ec2-public-images/fedora-core4-apache-v1.07.manifest.xml    amazon    available    public        i386    machine
IMAGE    ami-23b6534a    ec2-public-images/fedora-core4-apache.manifest.xml    amazon    available    public        i386    machine
IMAGE    ami-215fba48    ec2-public-images/fedora-core4-base-v1.07.manifest.xml    amazon    available    public        i386    machine
IMAGE    ami-20b65349    ec2-public-images/fedora-core4-base.manifest.xml    amazon    available    public        i386    machine
IMAGE    ami-205fba49    ec2-public-images/fedora-core4-i386-base-v1.07.manifest.xml    amazon    available    public        i386    machine    aki-9b00e5f2
IMAGE    ami-255fba4c    ec2-public-images/fedora-core4-mysql-v1.07.manifest.xml    amazon    available    public        i386    machine
IMAGE    ami-22b6534b    ec2-public-images/fedora-core4-mysql.manifest.xml    amazon    available    public        i386    machine
IMAGE    ami-36ff1a5f    ec2-public-images/fedora-core6-base-x86_64.manifest.xml    amazon    available    public        x86_64    machine
IMAGE    ami-235fba4a    ec2-public-images/getting-started-v1.07.manifest.xml    amazon    available    public        i386    machine
IMAGE    ami-2bb65342    ec2-public-images/getting-started.manifest.xml    amazon    available    public        i386    machine

The command lists your AMIs and Amazon's public AMIs. The output might not exactly match the preceding example.

Look for the line containing the public image identified by the ec2-public-images/getting-started.manifest.xml value in the third column and note the corresponding value in the second column. This is the AMI ID you need. In this example, it is ami-2bb65342.

Generating an SSH Keypair

You will be running an instance of a public AMI. Since it has no password you will need a public/private keypair to login to the instance. One half of this keypair will be embedded into your instance, allowing you to login securely without a password using the other half of the keypair. After learning to create your own images, you can choose other mechanisms to allow you to securely login to your new instances. Every keypair you generate requires a name. Be sure to choose a name that is easy to remember.

To generate a keypair using gsg-keypair

Enter the following information.

PROMPT>  ec2-add-keypair gsg-keypair

Amazon EC2 returns a keypair, similar to the keypair in the following example.

KEYPAIR gsg-keypair  1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f 
-----BEGIN RSA PRIVATE KEY-----
MIIEoQIBAAKCAQBuLFg5ujHrtm1jnutSuoO8Xe56LlT+HM8v/xkaa39EstM3/aFxTHgElQiJLChp
HungXQ29VTc8rc1bW0lkdi23OH5eqkMHGhvEwqa0HWASUMll4o3o/IX+0f2UcPoKCOVUR+jx71Sg
5AU52EQfanIn3ZQ8lFW7Edp5a3q4DhjGlUKToHVbicL5E+g45zfB95wIyywWZfeW/UUF3LpGZyq/
ebIUlq1qTbHkLbCC2r7RTn8vpQWp47BGVYGtGSBMpTRP5hnbzzuqj3itkiLHjU39S2sJCJ0TrJx5
i8BygR4s3mHKBj8l+ePQxG1kGbF6R4yg6sECmXn17MRQVXODNHZbAgMBAAECggEAY1tsiUsIwDl5
91CXirkYGuVfLyLflXenxfI50mDFms/mumTqloHO7tr0oriHDR5K7wMcY/YY5YkcXNo7mvUVD1pM
ZNUJs7rw9gZRTrf7LylaJ58kOcyajw8TsC4e4LPbFaHwS1d6K8rXh64o6WgW4SrsB6ICmr1kGQI7
3wcfgt5ecIu4TZf0OE9IHjn+2eRlsrjBdeORi7KiUNC/pAG23I6MdDOFEQRcCSigCj+4/mciFUSA
SWS4dMbrpb9FNSIcf9dcLxVM7/6KxgJNfZc9XWzUw77Jg8x92Zd0fVhHOux5IZC+UvSKWB4dyfcI
tE8C3p9bbU9VGyY5vLCAiIb4qQKBgQDLiO24GXrIkswF32YtBBMuVgLGCwU9h9HlO9mKAc2m8Cm1
jUE5IpzRjTedc9I2qiIMUTwtgnw42auSCzbUeYMURPtDqyQ7p6AjMujp9EPemcSVOK9vXYL0Ptco
xW9MC0dtV6iPkCN7gOqiZXPRKaFbWADp16p8UAIvS/a5XXk5jwKBgQCKkpHi2EISh1uRkhxljyWC
iDCiK6JBRsMvpLbc0v5dKwP5alo1fmdR5PJaV2qvZSj5CYNpMAy1/EDNTY5OSIJU+0KFmQbyhsbm
rdLNLDL4+TcnT7c62/aH01ohYaf/VCbRhtLlBfqGoQc7+sAc8vmKkesnF7CqCEKDyF/dhrxYdQKB
gC0iZzzNAapayz1+JcVTwwEid6j9JqNXbBc+Z2YwMi+T0Fv/P/hwkX/ypeOXnIUcw0Ih/YtGBVAC
DQbsz7LcY1HqXiHKYNWNvXgwwO+oiChjxvEkSdsTTIfnK4VSCvU9BxDbQHjdiNDJbL6oar92UN7V
rBYvChJZF7LvUH4YmVpHAoGAbZ2X7XvoeEO+uZ58/BGKOIGHByHBDiXtzMhdJr15HTYjxK7OgTZm
gK+8zp4L9IbvLGDMJO8vft32XPEWuvI8twCzFH+CsWLQADZMZKSsBasOZ/h1FwhdMgCMcY+Qlzd4
JZKjTSu3i7vhvx6RzdSedXEMNTZWN4qlIx3kR5aHcukCgYA9T+Zrvm1F0seQPbLknn7EqhXIjBaT
P8TTvW/6bdPi23ExzxZn7KOdrfclYRph1LHMpAONv/x2xALIf91UB+v5ohy1oDoasL0gij1houRe
2ERKKdwz0ZL9SWq6VTdhr/5G994CK72fy5WhyERbDjUIdHaK3M849JJuf8cSrvSb4g==
-----END RSA PRIVATE KEY-----

The private key returned must be saved to a local file so that you can use it later.

Create a file named id_rsa-gsg-keypair and paste the entire key generated in step 1, including the following lines.
```
"-----BEGIN RSA PRIVATE KEY-----" 
"-----END RSA PRIVATE KEY-----" 
```

Confirm that the file contents looks similar to the following and save the file. You can save the file in any directory, but if you do not put it in your current directory, you should specify the full path when using the ssh command.

If you're using OpenSSH (or any reasonably paranoid SSH client), you will probably need to set the permissions of this file so it is only readable by you. On Linux/Unix, enter the information in the following example.
```
$  chmod 600 id_rsa-gsg-keypair ; ls -l id_rsa-gsg-keypair  
```
You receive output similar to the following example.
```
-rw-------  1 fred flintstones 1701 Jun 19 17:57 id_rsa-gsg-keypair 
```

	Note
	If you are using PuTTY in Windows you will need to convert the private key to PuTTY's format. For more information on using PuTTy with Amazon EC2, see Appendix: PuTTY .

Running an Instance

To launch an instance of your AMI

Use the ec2-run-instances command.

PROMPT>  ec2-run-instances ami-235fba4a -k gsg-keypair
				Amazon EC2 returns output similar to the following example.
RESERVATION     r-7430c31d      924417782495    default
INSTANCE        i-ae0bf0c7      ami-2bb65342    pending gsg-keypair   0    m1.small    2008-03-21T16:19:25+0000        us-east-1a

Look for the instance ID in the second field and write it down. You will use it to manipulate this instance (including terminating it when you are finished).
It will take a few minutes for the instance to launch.

The following command displays the launch status of the instance.

PROMPT>  ec2-describe-instances i-ae0bf0c7 
RESERVATION     r-7430c31d      924417782495    default
INSTANCE        i-ae0bf0c7      ami-2bb65342    ec2-67-202-7-236.compute-1.amazonaws.com        ip-10-251-31-162.ec2.internal   running gsg-keypair     0               m1.small        2008-03-21T16:19:25+0000us-east-1a

	Important
	Once you launch an instance, you will be billed per hour for running time. If you leave this tutorial at any time, make sure you terminate any instances you have started as described in Terminating Your Instances.

When the instance state in the field just before the keypair name reads "running" the instance has started booting. There might be a short time before it is accessible over the network, however. The first DNS name is your instance's external DNS name, i.e. the one that can be used to contact it from the Internet. The second DNS name is your instance's local DNS name, and is only contactable by other instances within the Amazon EC2 network. Your instance's DNS names will be different to those shown in the preceding example and you should use yours instead. In the examples in the getting started guide we use the public DNS name.

Authorizing Network Access to Your Instances

To authorize access to your instance

Enter the ec2-authorize command.
```
PROMPT>  ec2-authorize default -p 22
PERMISSION     default  ALLOWS  tcp     22      22      FROM    CIDR   0.0.0.0/0
PROMPT>  ec2-authorize default -p 80
PERMISSION     default  ALLOWS  tcp     80      80      FROM    CIDR   0.0.0.0/0 
```
Since we didn't specify otherwise, your instance was launched in your default group. The first command authorizes network access to instances in your default group on the standard SSH port (22). Similarly, the second command opens up the standard HTTP port (80). For more details on controlling network security groups, see the Amazon EC2 Developer Guide.

Connecting to your Instance

To connect to your instance

Open a web browser and go to http://<hostname>/, where <hostname> is your instance's public hostname as returned by ec2-describe-instances (ec2-67-202-51-223.compute-1.amazonaws.com in the example).
A webpage welcoming you to your instance displays.
Note
If the website times out, your instance might not have finished starting up. Wait a couple of minutes and try again.

Whenever you launch a public AMI that you have not rebundled, run the ec2-get-console-output command and locate the SSH HOST KEY FINGERPRINTS section.

PROMPT>  ec2-get-console-output instance_id

...
ec2: -----BEGIN SSH HOST KEY FINGERPRINTS-----
ec2: 2048 bc:89:29:c6:45:4b:b3:e2:c1:41:81:22:cb:3c:77:54
/etc/ssh/ssh_host_key.pub
ec2: 2048 fc:8d:0c:eb:0e:a6:4a:6a:61:50:00:c4:d2:51:78:66
/etc/ssh/ssh_host_rsa_key.pub
ec2: 1024 b5:cd:88:6a:18:7f:83:9d:1f:3b:80:03:10:17:7b:f5
/etc/ssh/ssh_host_dsa_key.pub
ec2: -----END SSH HOST KEY FINGERPRINTS-----
...

Note the fingerprints. You will need to compare them in the next step.

Use the following command to login as root and exercise full control over this instance as you would any host.

PROMPT>  ssh -i id_rsa-gsg-keypair root@ec2-67-202-51-223.compute-1.amazonaws.com 
The authenticity of host 'ec2-67-202-51-223.compute-1.amazonaws.com (216.182.225.42)' can't be established.
RSA key fingerprint is fc:8d:0c:eb:0e:a6:4a:6a:61:50:00:c4:d2:51:78:66.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'ec2-67-202-51-223.compute-1.amazonaws.com' (RSA) to the list of known hosts.
Last login: Wed Jun 21 08:02:08 2006
root@ec2-67-202-51-223 #

If you are launching a public AMI, verify the fingerprint matches one of the fingerprints from the output of the ec2-get-console-output command. If it doesn't, someone might be attempting a "man-in-the-middle" attack.

	Note
	Your machine might have a different name for the preceding ssh command or even use different command line options. Consult the documentation for your machine or download one of the clients described in SSH Clients if you are unsure whether you have such a client installed. For more information about using PuTTY on Windows, see Appendix: PuTTY.

Next Steps

You've set up the tools and used them to run an instance based on a public AMI. You have learned enough to successfully use Amazon EC2 to run as many standard Linux instances as you want. You can run instances based on any of the public AMIs by following this process.

The next section builds on this success by having you connect to the running instance and customize it to create your own image. To save this for a later date, terminate any instances you started as described in Terminating Your Instances.

	Note
	If the website times out, your instance might not have finished starting up. Wait a couple of minutes and try again.