Amazon Elastic Compute

Cloud
Developer Guide
API Version 2008-02-01
 Amazon Elastic Compute Cloud Developer Guide

Amazon Elastic Compute Cloud: Developer Guide

Copyright © 2008 Amazon Web Services LLC or its affiliates. All rights reserved.
 Amazon Elastic Compute Cloud Developer Guide

Table of Contents
What's New ...................................................................................................................................... 1
Welcome .......................................................................................................................................... 2
Introduction to Amazon Elastic Compute Cloud .............................................................................5
Creating and Preparing AMIs .......................................................................................................... 6
Creating an AMI ........................................................................................................... 6
Starting with an Existing AMI ............................................................................ 6
Creating an AMI through a Loopback File ....................................................... 12
Bundling an AMI ........................................................................................................ 18
Sharing AMIs ..............................................................................................................21
Shared AMI Guidelines .....................................................................................21
Sharing AMIs .................................................................................................... 25
Making an AMI Public ......................................................................................25
Sharing an AMI with Specific Users .................................................................26
Publishing Shared AMIs ................................................................................... 27
Creating Paid AMIs .................................................................................................... 28
Paid and Supported AMIs ................................................................................. 29
Summary of How Paid AMIs Work ..................................................................29
Summary of How Supported AMIs Work ........................................................ 30
Product Registration ..........................................................................................31
Associating a Product Code with an AMI .........................................................32
Sharing Your Paid AMI with Select Users or the Public ..................................33
Confirming an Instance Is Running an AMI Associated with a Product Code .33
Getting the Product Code from Within an Instance .......................................... 34
Launching and Using Instances ..................................................................................................... 35
Instance Usage ............................................................................................................ 35
Instance Types ............................................................................................................ 36
Instance Metadata ....................................................................................................... 37
Instance Storage .......................................................................................................... 43
Availability Zones .......................................................................................................45
Using Shared AMIs .................................................................................................... 47
Paying for AMIs ......................................................................................................... 48
Get Console Output and Reboot Instances ................................................................. 51
Instance Addressing and Network Security ................................................................................... 53
Instance Addressing .................................................................................................... 53
Elastic IP Addresses .......................................................................................... 55
Network Security ........................................................................................................ 57
Concepts ............................................................................................................ 57
Examples ........................................................................................................... 57
Using the APIs ............................................................................................................................... 61
Using the SOAP API .................................................................................................. 61
Using the Query API ...................................................................................................64
API Reference ................................................................................................................................ 68
API Conventions .........................................................................................................68
API Versioning ........................................................................................................... 69
API Error Codes ..........................................................................................................70
Common Data Types .................................................................................................. 73
AvailabilityZoneItemType ................................................................................ 73
BlockDeviceMappingItemType ........................................................................ 73
DescribeImagesResponseItemType .................................................................. 74
DescribeKeyPairsResponseItemType ............................................................... 75
EmptyElementType ...........................................................................................75
GroupSetType ................................................................................................... 76
InstanceStateType ............................................................................................. 76
 Amazon Elastic Compute Cloud Developer Guide

IpPermissionType ..............................................................................................77
LaunchPermissionItemType ..............................................................................78
LaunchPermissionOperationType .....................................................................78
PlacementRequestType ..................................................................................... 79
PlacementResponseType ...................................................................................79
ProductCodeItemType ...................................................................................... 79
ProductInstanceResponseItemType .................................................................. 80
ReservationInfoType .........................................................................................80
RunningInstancesItemType ...............................................................................81
SecurityGroupItemType ....................................................................................82
TerminateInstancesResponseInfoType ............................................................. 83
UserDataType ....................................................................................................83
UserIdGroupPairType ....................................................................................... 84
Amazon EC2 SOAP API ............................................................................................ 84
List of Operations by Function ..........................................................................85
AllocateAddress ................................................................................................ 86
AssociateAddress .............................................................................................. 86
AuthorizeSecurityGroupIngress ........................................................................87
ConfirmProductInstance ....................................................................................89
CreateKeyPair ................................................................................................... 90
CreateSecurityGroup .........................................................................................91
DeleteKeyPair ................................................................................................... 92
DeleteSecurityGroup .........................................................................................93
DeregisterImage ................................................................................................ 94
DescribeAddresses ............................................................................................ 95
DescribeAvailabilityZones ................................................................................96
DescribeImageAttribute .................................................................................... 97
DescribeImages ............................................................................................... 100
DescribeInstances ............................................................................................102
DescribeKeyPairs ............................................................................................ 103
DescribeSecurityGroups ..................................................................................104
DisassociateAddress ........................................................................................106
GetConsoleOutput ...........................................................................................107
ModifyImageAttribute .................................................................................... 108
RebootInstances .............................................................................................. 109
RegisterImage ..................................................................................................110
ReleaseAddress ............................................................................................... 111
ResetImageAttribute ........................................................................................112
RevokeSecurityGroupIngress ..........................................................................113
RunInstances ................................................................................................... 115
TerminateInstances ..........................................................................................119
Amazon EC2 Query API .......................................................................................... 120
Common Query Parameters ............................................................................ 120
List of Operations by Function ........................................................................121
AllocateAddress .............................................................................................. 122
AssociateAddress ............................................................................................ 123
AuthorizeSecurityGroupIngress ......................................................................124
ConfirmProductInstance ..................................................................................126
CreateKeyPair ................................................................................................. 127
CreateSecurityGroup .......................................................................................129
DeleteKeyPair ................................................................................................. 130
DeleteSecurityGroup .......................................................................................130
DeregisterImage .............................................................................................. 132
DescribeAddresses .......................................................................................... 132
DescribeAvailabilityZones ..............................................................................133
DescribeImageAttribute .................................................................................. 135
DescribeImages ............................................................................................... 137
DescribeInstances ............................................................................................139
 Amazon Elastic Compute Cloud Developer Guide

DescribeKeyPairs ............................................................................................ 140

DescribeSecurityGroups ..................................................................................141
DisassociateAddress ........................................................................................143
GetConsoleOutput ...........................................................................................144
ModifyImageAttribute .................................................................................... 145
RebootInstances .............................................................................................. 147
ReleaseAddress ............................................................................................... 148
RegisterImage ..................................................................................................149
ResetImageAttribute ........................................................................................150
RevokeSecurityGroupIngress ..........................................................................151
RunInstances ................................................................................................... 153
TerminateInstances ..........................................................................................157
Command Line Tools Reference ................................................................................................. 159
AMI Tools .................................................................................................................160
ec2-bundle-image ............................................................................................ 160
ec2-bundle-vol .................................................................................................163
ec2-delete-bundle ............................................................................................ 166
ec2-download-bundle ...................................................................................... 168
ec2-unbundle ................................................................................................... 169
ec2-upload-bundle ...........................................................................................171
API Tools .................................................................................................................. 173
List of Operations by Function ........................................................................173
ec2-add-group ..................................................................................................174
ec2-add-keypair ...............................................................................................175
ec2-allocate-address ........................................................................................ 176
ec2-associate-address ...................................................................................... 177
ec2-authorize ................................................................................................... 178
ec2-confirm-product-instance ......................................................................... 180
ec2-delete-group ..............................................................................................181
ec2-delete-keypair ........................................................................................... 182
ec2-deregister .................................................................................................. 183
ec2-describe-addresses .................................................................................... 184
ec2-disassociate-address ..................................................................................185
ec2-describe-availability-zones .......................................................................185
ec2-describe-group .......................................................................................... 186
ec2-describe-image-attribute ...........................................................................187
ec2-describe-images ........................................................................................ 189
ec2-describe-instances .....................................................................................191
ec2-describe-keypairs ......................................................................................192
ec2-fingerprint-key ..........................................................................................193
ec2-get-console-output .................................................................................... 194
ec2-modify-image-attribute .............................................................................194
ec2-reboot-instances ........................................................................................196
ec2-release-address ..........................................................................................197
ec2-register ...................................................................................................... 198
ec2-reset-image-attribute .................................................................................199
ec2-revoke ....................................................................................................... 200
ec2-run-instances .............................................................................................202
ec2-terminate-instances ...................................................................................205
Technical FAQ ............................................................................................................................. 206
General Information ..................................................................................................206
Operation Information .............................................................................................. 207
Instance Types and Architectures ............................................................................. 208
IP Information ...........................................................................................................210
Availability Zones .....................................................................................................212
Monitoring, Errors, and Unexpected Behavior .........................................................212
Error Messages ......................................................................................................... 213
Paid AMIs ................................................................................................................. 214
 Amazon Elastic Compute Cloud Developer Guide

Kernels, RAM Disks, and Block Device Mappings ................................................. 215

Miscellaneous ........................................................................................................... 216
Glossary ....................................................................................................................................... 217
Document Conventions ................................................................................................................218
Index .............................................................................................................................................221
 Amazon Elastic Compute Cloud Developer Guide

What's New

This What's New is associated with the 2008-02-01 release of Amazon EC2. This guide was last updated
on March 27, 2008.

The following table describes the important changes since the last release of the Amazon EC2
Developer Guide.

Change Description Release Date

Elastic IP Addresses Elastic IP addresses are static IP addresses designed for 27 March
dynamic cloud computing. Elastic IP addresses are associated 2008
with your account, not specific instances. Any elastic IP
address that you associate with your account remains
associated with your account until you explicitly release it.
Unlike traditional static IP addresses, however, elastic IP
addresses allow you to mask instance or availability zone
failures by rapidly remapping your public IP addresses to any
instance in your account. For more information, see Elastic IP
Addresses.
Availability Zones Amazon EC2 now provides the ability to place instances in 27 March
multiple locations. Amazon EC2 locations are composed of 2008
regions and availability zones. Regions are geographically
dispersed and are in separate geographic areas or countries.
Availability zones are separated from each other, but located
in the same region. For more information, see Availability
Zones.
User-Selectable Amazon EC2 now enables you to select the kernel and RAM 27 March
Kernels disk to bundle your AMI with or to specify a kernel and RAM 2008
disk at launch time. For more information, see Kernels, RAM
Disks, and Block Device Mappings.

API Version 2008-02-01

1
 Amazon Elastic Compute Cloud Developer Guide
Audience

Welcome

Topics

• Audience
• How This Guide Is Organized
• Related Resources

This is the Amazon Elastic Compute Cloud Developer Guide. This section describes who should read
this guide, how the guide is organized, and other resources related to Amazon Elastic Compute Cloud.

The Amazon Elastic Compute Cloud will occasionally be referred to within this guide as simply
"Amazon EC2"; all copyrights and legal protections still apply.

Audience
This guide picks up where the Getting Started Guide ends and provides you with the information to
create more sophisticated AMIs, using advanced service features.

Required Knowledge and Skills

Use of this guide assumes you are familiar with the following:

• XML (See W3 Schools XML Tutorial)

• Basic understanding of web services (See W3 Schools Web Services Tutorial))
• A programming language for consuming a web service and any related tools

You should also have worked through the Amazon EC2 Getting Started Guide, installed the command
line and API tools, and have a general understanding of the service.

How This Guide Is Organized

This guide is organized into several major sections described in the table below.

API Version 2008-02-01

2
 Amazon Elastic Compute Cloud Developer Guide
Related Resources

Information Relevant Sections

Describes how to create a customized • Creating and Preparing AMIs

software package (operating system
and applications) that you can run on
Amazon EC2

Describes Amazon EC2 instances and • Launching and Using Instances

provides tips for using them effectively

Describes instance network addressing, • Instance Addressing and Network Security

explains the distributed firewall, and
provides usage examples

Explains the basics of using the SOAP • Using the APIs

and Query APIs, including signing
requests

Provides a comprehensive reference to • API Reference

the SOAP and Query APIs

Provides a comprehensive reference to • Command Line Tools Reference

the Amazon EC2 command line tools

Provides answers to commonly asked • Technical FAQ

questions

Describes Amazon EC2 terms • Glossary

Typographic and symbol conventions • Document Conventions

Each section is written to stand on its own, so you should be able to look up the information you need
and go back to work. However, you can also read through the major sections sequentially to get in-depth
knowledge about Amazon EC2.

Related Resources
The table below lists related resources that you'll find useful as you work with this service.

Resource Description
Amazon EC2 Getting Started Guide The Getting Started Guide provides a quick tutorial of the
service based on a simple use case. Examples and
instructions are included.
Amazon EC2 Release Notes The Release Notes give a high-level overview of the current

API Version 2008-02-01

3
 Amazon Elastic Compute Cloud Developer Guide
Related Resources

Resource Description
release. They specifically note any new features, corrections,
and known issues.
AWS Developer Resource Center A central starting point to find documentation, code
samples, release notes, and other information to help you
build innovative applications with AWS.
Amazon EC2 product information The primary web page for information about Amazon EC2.
Discussion Forums A community-based forum for developers to discuss
technical questions related to Amazon Web Services.
E-mail address for questions related to This e-mail address is only for account questions. For
your AWS account: technical questions, use the Discussion Forums.
<[email protected]>

Conditions of Use Detailed information about the copyright and trademark

usage at Amazon.com.

API Version 2008-02-01

4
 Amazon Elastic Compute Cloud Developer Guide

Introduction to Amazon Elastic

Compute Cloud

Amazon EC2 is a web service that enables you to provision on-demand compute capacity from
Amazon's world class data centers.

This means you can allocate or release resources within minutes, not hours or weeks, as your application
requires. Most importantly, you only pay for what you use. If you use a server instance for an hour, you
pay for an hour. If you use an instance for a year, you pay for a year.

Although the applications for Amazon EC2 are only limited by your ingenuity, there are popular ways in
which our customers use Amazon EC2:

• Scalable Applications—You can build a scalable application that shrinks or expands to meet your
current demands.
This can help you use only the compute resources that you need and can help you respond to events
where a mention on a popular news site can result in a dramatic spike in traffic.
• Temporary Events—You can use Amazon EC2 for temporary solutions and one-off events that
would require you to maintain a fleet of compute resources that are normally idle.
This includes hosting conferences in virtual worlds, live blogging, distribution of newly released
media, and short-term promotional websites.
• Batch Processing—You can use Amazon EC2 for projects that require massive compute resources
which would be expensive to build on your own.
This includes video and image processing, financial data processing, and science and research
applications.
• Fault Resilient Applications—You can build an application across multiple availability zones which
will be protected against the loss of an entire physical location.

API Version 2008-02-01

5
 Amazon Elastic Compute Cloud Developer Guide
Creating an AMI

Creating and Preparing AMIs

Topics

• Creating an AMI
• Bundling an AMI
• Shared AMI Guidelines
• Sharing AMIs
• Creating Paid AMIs

This section details how to build, store, and share AMIs.

Creating an AMI
There are two common ways to create an AMI that offer a mix of ease of use and detailed customization
levels.

The easiest method involves starting from an existing public AMI and modifying it according to your
requirements, as described in Starting with an Existing AMI.

Another approach is to build a fresh installation either on a stand-alone machine or on an empty file
system mounted by loopback. This essentially entails building an operating system installation from
scratch and is described in Creating an AMI through a Loopback File.

After the installation package has been built to your satisfaction, you must bundle it and upload it to
Amazon Simple Storage Service (Amazon S3) as described in Bundling an AMI.

Starting with an Existing AMI

To quickly and easily get a new working AMI, start with an existing public AMI or one of your own.
You can then modify it and create a new AMI with the ec2-bundle-vol utility described in Bundling
an AMI.

Note

API Version 2008-02-01

6
 Amazon Elastic Compute Cloud Developer Guide
Starting with an Existing AMI

Before selecting an AMI, determine whether the instance types you plan to launch are
32-bit or 64-bit. For more information, see Instance Types

Make sure you are using GNU Tar 1.15 or later.

To use an existing AMI to create a new AMI:

1. Select an AMI
2. Generate a Key Pair
3. Launch the Instance
4. Authorize Network Access
5. Connect to the Instance
6. Upload the Key and Certificate

Select an AMI
First, locate an AMI that contains the packages and services you require. This can be one of your own
AMIs or a public AMIs provided by Amazon EC2.

To select an AMI:

1. Get a list of available AMIs by entering the ec2-describe-images command:

PROMPT> ec2-describe-images -a

The response includes the image ID, the location of the file in Amazon S3, and whether the file is
available.
2. Choose an AMI from the list and write down its AMI ID.

Example

PROMPT> ec2-describe-images -o self -o amazon

IMAGE ami-60a54009 ec2-public-images/base-fc4-apache.manifest.xml
475219833042 available public
IMAGE ami-61a54028 <your-s3-bucket>/image.manifest.xml 495219933132 available
private
IMAGE ami-2bb65342 ec2-public-images/getting-started.manifest.xml
475219833042 available public
IMAGE ami-6ea54007 ec2-public-images/base-fc3-mysql.manifest.xml 475219833042
available public

Generate a Key Pair

This step is only required if you selected one of the public AMIs provided by Amazon EC2. You must
create a public/private key pair to ensure that only you have access to instances that you launch.

After you generate a key pair, the public key is stored in Amazon EC2 using the key pair name you

API Version 2008-02-01

7
 Amazon Elastic Compute Cloud Developer Guide
Starting with an Existing AMI

selected. Whenever you launch an instance using the key pair name, the public key is copied to the
instance metadata. This allows you to access the instance securely using your private key.

To create a public/private key pair

1. Enter the following command:

PROMPT> ec2-add-keypair <keypair-name>

where <keypair-name> is the name you select for the key pair.

The resulting private key is displayed.

2. Open a text editor.
3. Paste the entire private key, starting with the line "-----BEGIN RSA PRIVATE KEY-----" and
ending with the line "-----END RSA PRIVATE KEY-----".
4. Save the file and exit.

API Version 2008-02-01

8
 Amazon Elastic Compute Cloud Developer Guide
Starting with an Existing AMI

Note

This file should only be readable by the file owner.

Example

PROMPT> ec2-add-keypair gsg-keypair

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-----

Launch the Instance

You are now ready to launch an instance of the AMI that you previously selected.

To launch an instance

1. Start the launch by entering the following command:

PROMPT> ec2-run-instances <ami_id> -k <keypair-name>

where <ami_id> is the AMI ID you selected earlier and <keypair-name> is the name of the key
pair. The command will return the AMI instance ID, a unique identifier for each launched instance.
You use the instance ID to manipulate the instance. This includes viewing the status of the instance,
terminating the instance, and so on.

Launching the instance will take a few minutes.

2. View the progress of the instance by entering the following command:
PROMPT> ec2-describe-instances <instance_id>

API Version 2008-02-01

9
 Amazon Elastic Compute Cloud Developer Guide
Starting with an Existing AMI

where <instance_id> is the ID of the instance.

When the status field displays "running," the instance was created and is booting. However, the
instance might not be immediately accessible over the network. Make sure to use the appropriate
DNS name provided by the ec2-describe-instances command.

Important

Once you launch an instance, you will be billed for all usage, including hourly CPU time.
Make sure to terminate any instances that you do not want to leave running. For
information on Amazon EC2 pricing, refer to the Amazon EC2 home page.

Example

The following example launches an instance of ami-2bb65342.

PROMPT> ec2-run-instances ami-2bb65342 -k gsg-keypair
RESERVATION r-302dc059 416161254515 default
INSTANCE i-eb977f82 ami-2bb65342 pending gsg-
keypair 0 m1.small 2007-10-16T07:56:20+0000 us-east-1a

The following shows the status of the launch:

PROMPT> ec2-describe-instances i-eb977f82
RESERVATION r-302dc059 416161254515 default
INSTANCE i-eb977f82 ami-2bb65342
ec2-72-44-40-222.compute-1.amazonaws.com 10-251-50-83.ec2.internal run
ning gsg-keypair 0 m1.small 2007-10-16T07:56:20+0000 us-east-1a

Authorize Network Access

To reach a running instance from the Internet, you must enable access for the SSH service on port 22.

To enable SSH service on port 22

• Enter the following command:

PROMPT> ec2-authorize default -p 22

PERMISSION default ALLOWS tcp 22 22 FROM CIDR
0.0.0.0/0

Connect to the Instance

After starting an instance, you can log in and modify it according to your requirements.

To connect to an instance

• If you are launching an AMI that supports SSH login (e.g., public AMIs), use the following command
to log in with your private key:

API Version 2008-02-01

10
 Amazon Elastic Compute Cloud Developer Guide
Starting with an Existing AMI

PROMPT> ssh -i <private-keyfile> root@<dns_location>

where <private-keyfile> is the file that contains the private key and dns_location is the DNS
location of the instance within Amazon EC2. Your instance displays a prompt that contains your
username and the hostname of the instance.

You now have complete control over the instance. You can add, remove, modify, or upgrade packages
and files to suit your needs.

Important

We recommend exercising extreme care when changing some of the basic Amazon EC2
configuration settings, such as the network interface configuration and the /etc/fstab
contents. Otherwise, the AMI might become unbootable or inaccessible from the network
once running.

Example

The following example shows logging in to an AMI using SSH.

PROMPT> ssh -i id_rsa-gsg-keypair
[email protected]
root@ec2-67-202-51-223 #

Upload the Key and Certificate

Your new AMI is encrypted and signed to ensure that only you and Amazon EC2 can access it.
Therefore, you must upload your Amazon EC2 private key and X.509 certificate to the running instance,
for use in the AMI bundling process.

Note

For information on obtaining your Amazon EC2 private key and X.509 certificate, refer to
the Amazon Elastic Compute Cloud Getting Started Guide.

To upload your Amazon EC2 private key and X.509 certificate

1. Copy your Amazon EC2 private key and X.509 certificate to the /mnt directory.
2. Enter the following command:
PROMPT> scp <private_keyfile> <certificate_file> root@<dns_location>:/mnt

where <private_keyfile> is the file that contains the private key, certificate_file is the
file that contains the certificate, and dns_location is the DNS location of the instance within
Amazon EC2.

Amazon EC2 returns the name of the files and some performance statistics.

API Version 2008-02-01

11
 Amazon Elastic Compute Cloud Developer Guide
Creating an AMI through a Loopback File

Note

It is important that the key and cert files are uploaded into /mnt to prevent them from
being bundled with the new AMI.

You are ready to bundle the volume and uploading the resulting AMI to Amazon S3. For more
information, see Bundling an AMI.

Example

PROMPT> scp pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem
[email protected]:/mnt
-i id_rsa-gsg-keypair
pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem 100% 717 0.7KB/s 00:00 cert-
HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem
100% 685 0.7KB/s 00:00

Creating an AMI through a Loopback File

This method involves doing a full operating system installation on a clean root file system, but avoids
having to create a new root disk partition and file system on a physical disk. Once you have installed
your operating system, the resulting image can be bundled as an AMI with the ec2-bundle-image
utility.

Note

Before selecting an AMI, determine whether the instance types you plan to launch are
32-bit or 64-bit. For more information, see Instance Types
Make sure you are using GNU Tar 1.15 or later.
These examples use Fedora Core 4. Please make any adjustments for your distribution.

AMI Creation Process

1 Create a File to Host the AMI

2 Create a Root File System Inside the File
3 Mount the File through Loopback
4 Prepare for the Installation
5 Install the Operating System
6 Configure the Operating System

Create a File to Host the AMI

API Version 2008-02-01

12
 Amazon Elastic Compute Cloud Developer Guide
Creating an AMI through a Loopback File

The dd utility can create files of arbitrary sizes. Make sure to create a file large enough to host the
operating system, tools, and applications that you will install. For example, a baseline Linux installation
requires about 700MB, so your file should be at least 1 GB.

To create a file to host the AMI

• Enter the following command:

# dd if=/dev/zero of=<image_name> bs=1M =<size>

where <image_name> is the name of the image file you are creating and <size> is the size of the
file in megabytes.

Example

The following command creates a one gigabyte file (1024*1MB):

# dd if=/dev/zero of=my-image.fs bs=1M count=1024
1024+0 records in
1024+0 records out

Create a Root File System Inside the File

There are several variations on the mkfs utility that can create a file system inside the image file you are
creating. Typical Linux installations default to ext2 or ext3 file systems.

To create an ext3 file system

• Enter the following command:

# mke2fs -F -j <image_name>

where <image_name> is the name of the image file.

Example

The following command creates an ext3 file system:

# mke2fs -F -j my-image.fs
mke2fs 1.38 (30-Jun-2005)
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
131072 inodes, 262144 blocks
13107 blocks (5.00%) reserved for the super user
First data block=0
Maximum filesystem blocks=268435456
8 block groups
32768 blocks per group, 32768 fragments per group
16384 inodes per group
Superblock backups stored on blocks:
32768, 98304, 163840, 229376

API Version 2008-02-01

13
 Amazon Elastic Compute Cloud Developer Guide
Creating an AMI through a Loopback File

Writing inode tables: done

Creating journal (8192 blocks): done
Writing superblocks and filesystem accounting information: done
This filesystem will be automatically checked every 24 mounts or
180 days, whichever comes first. Use tune2fs -c or -i to override.

Mount the File through Loopback

The loopback module allows you to use a normal file as if it were a raw device, which gives you a file
system within a file. Mounting a file system image file through loopback presents it as part of the
normal file system. You can then modify it using your favorite file management tools and utilities.

To mount the file through loopback

1. Create a mount point in the file system where the image will be attached:
# mkdir <image_mountpoint>

where <image_mountpoint> is the location where the image will be mounted.

2. Mount the file system image:
# mount -o loop <image_name> <image_mountpoint>

where <image_name> is the name of the image file and <image_mountpoint> is the mount
location.

Example

The following commands create and mount the my-image.fs image file:

# mkdir /mnt/ec2-fs
# mount -o loop my-image.fs /mnt/ec2-fs

Prepare for the Installation

Before the operating system installation can proceed, you must create and prepare the newly created root
file system.

To prepare for the installation

1. Create a /dev directory and populate it with a minimal set of devices (you can ignore the errors in
the output):
# mkdir /mnt/ec2-fs/dev
# /sbin/MAKEDEV -d <image_mountpoint>/dev -x console
# /sbin/MAKEDEV -d <image_mountpoint>/dev -x null
# /sbin/MAKEDEV -d <image_mountpoint>/dev -x zero

API Version 2008-02-01

14
 Amazon Elastic Compute Cloud Developer Guide
Creating an AMI through a Loopback File

where <image_mountpoint> is the mount location.

2. Create the fstab file within the /etc directory and add the following:
/dev/sda1 / ext3 defaults 1 1
none /dev/pts devpts gid=5,mode=620 0 0
none /dev/shm tmpfs defaults 0 0
none /proc proc defaults 0 0
none /sys sysfs defaults 0 0

3. Create a temporary yum configuration file (e.g., yum-xen.conf) and add the following
components:
[main]
cachedir=/var/cache/yum
debuglevel=2
logfile=/var/log/yum.log
exclude=*-debuginfo
gpgcheck=0
obsoletes=1
reposdir=/dev/null
[base]
name=Fedora Core 4 - $basearch - Base
mirrorl
ist=http://fedora.redhat.com/download/mirrors/fedora-core-$releasever
enabled=1
[updates-released]
name=Fedora Core 4 - $basearch - Released Updates
mirrorl
ist=http://fedora.redhat.com/download/mirrors/updates-released-fc$releasev
er
enabled=1

This ensures all the required basic packages and utilities are installed. This file can be located
anywhere on your main file system (not on your loopback file system) and is only used during
installation.
4. Enter the following:
# mkdir <image_mountpoint>/proc
# mount -t proc none <image_mountpoint>/proc

where <image_mountpoint> is the mount location. A groupadd utility bug in the

shadow-utils package (versions prior to 4.0.7-7) requires you to mount the new proc file
system manually with the above command.

Example

These commands create the /dev directory and populate it with a minimal set of devices:
# mkdir /mnt/ec2-fs/dev
# /sbin/MAKEDEV -d /mnt/ec2-fs/dev -x console
MAKEDEV: mkdir: File exists
MAKEDEV: mkdir: File exists
MAKEDEV: mkdir: File exists
# /sbin/MAKEDEV -d /mnt/ec2-fs/dev -x null
MAKEDEV: mkdir: File exists
MAKEDEV: mkdir: File exists
MAKEDEV: mkdir: File exists
# /sbin/MAKEDEV -d /mnt/ec2-fs/dev -x zero

API Version 2008-02-01

15
 Amazon Elastic Compute Cloud Developer Guide
Creating an AMI through a Loopback File

MAKEDEV: mkdir: File exists

MAKEDEV: mkdir: File exists
MAKEDEV: mkdir: File exists

This example creates and mounts the /mnt/ec2-fs/proc directory

# mkdir /mnt/ec2-fs/proc
# mount -t proc none /mnt/ec2-fs/proc

Install the Operating System

At this stage, the basic directories and files are created and you are ready to install the operating system.
Depending on the speed of the host and network link to the repository, this process might take a while.

To install the operating system

• Enter the following command:

# yum -c <yum_configuration_file> --installroot=<image_mountpoint> -y grou
pinstall Base

where <yum_configuration_file> is the name of the yum configuration file and

<image_mountpoint> is the mount location.

You now have a base installation, which you can configure for operation inside Amazon EC2 and
customize for your use.

Example

This example installs the operating system at the /mnt/ec2-fs mount point using the yum-xen.conf
yum configuration file.
# yum -c yum-xen.conf --installroot=/mnt/ec2-fs -y groupinstall Base
Setting up Group Process
Setting up repositories
base 100% |=========================| 1.1 kB 00:00
updates-released 100% |=========================| 1.1 kB 00:00
comps.xml 100% |=========================| 693 kB 00:00
comps.xml 100% |=========================| 693 kB 00:00
Setting up repositories
Reading repository metadata in from local files
primary.xml.gz 100% |=========================| 824 kB 00:00
base : ################################################## 2772/2772
Added 2772 new packages, deleted 0 old in 15.32 seconds
primary.xml.gz 100% |=========================| 824 kB 00:00
updates-re: ################################################## 2772/2772
Added 2772 new packages, deleted 0 old in 10.74 seconds
...
Complete!

Configure the Operating System

After successfully installing the base operating system, you must configure the networking and hard
drives to work in the Amazon EC2 environment.

API Version 2008-02-01

16
 Amazon Elastic Compute Cloud Developer Guide
Creating an AMI through a Loopback File

To configure the operating system

1. Edit (or create) /mnt/ec2-fs/etc/sysconfig/network-scripts/ifcfg-eth0 and make

sure it contains at least the following information:
DEVICE=eth0
BOOTPROTO=dhcp
ONBOOT=yes
TYPE=Ethernet
USERCTL=yes
PEERDNS=yes
IPV6INIT=no

Note

The Amazon EC2 DHCP server ignores hostname requests. If you set
DHCP_HOSTNAME, the local hostname will be set on the instance but not externally.
Additionally, the local hostname will be the same for all instances of the AMI, which
might be confusing.

2. Ensure that networking starts by making sure the following line appears in the
/mnt/ec2-fs/etc/sysconfig/network file:

NETWORKING=yes

3. Amazon EC2 provides the instance with additional local disk storage on /dev/sda2 and swap
space on /dev/sda3. To ensure both these are mounted at system startup, add the following lines
to /mnt/ec2-fs/etc/fstab:
/dev/sda2 /mnt ext3 defaults 0 0
/dev/sda3 swap swap defaults 0 0

Note

The /dev/sda2 and /dev/sda3 storage locations only apply to small instances. For
more information on instance storage, see Instance Storage .

4. Make sure all of your required services start at system startup by allocating them appropriate
system run levels. For example, to enable the service my-service on multi-user and networked
run levels, enter the following commands:
# chroot /mnt/ec2-fs /bin/sh
# chkconfig --level 345 my-service on
# exit

5. After your new installation is successfully installed and configured to operate in the Amazon EC2
environment, you can unmount the image:
# umount <image_mountpoint>/proc
# umount -d <image_mountpoint>

where <image_mountpoint> is the mount location.

API Version 2008-02-01

17
 Amazon Elastic Compute Cloud Developer Guide
Bundling an AMI

Example

The following example unmounts the installation from the /mnt/ec2-fs mount point.
# umount /mnt/ec2-fs/proc
# umount -d /mnt/ec2-fs

Bundling an AMI
To use a file system image with Amazon EC2, you must bundle it as an AMI. The bundling process
does the following:

• Compresses the image to minimize bandwidth usage and storage requirements.

• Encrypts and signs the compressed image to ensure confidentiality and authenticates the image
against its creator.
• Splits the encrypted image into manageable parts for upload.
• Creates a manifest file that contains a list of the image parts with their checksums.

This section describes the AMI tools that automate this process and provides examples of their use.

The AMI tools include three command-line utilities:

• ec2-bundle-image bundles an existing AMI

• ec2-bundle-vol creates an AMI from an existing machine or installed volume
• ec2-upload-bundle uploads a bundled AMI to Amazon S3 storage

Installing the AMI Tools

The AMI tools are packaged as an RPM suitable for running on Fedora Core with Ruby 1.8.2 (or
greater) installed. You need root privileges to install the software.

The AMI tools RPM is available from our public Amazon S3 downloads bucket.

To install the AMI tools

1. Install Ruby using the yum package manager:

# yum install ruby

2. Install the AMI tools RPM:

# rpm -i ec2-ami-tools-x.x-xxxx.i386.rpm

Installation Issues
The AMI tools libraries install in /usr/lib/site_ruby.

API Version 2008-02-01

18
 Amazon Elastic Compute Cloud Developer Guide
Viewing Documentation

If you receive a load error when running one of the AMI utilities, Ruby might not have found the path.
To fix this, add /usr/lib/site_ruby to Ruby's library path, which is set in the RUBYLIB
environment variable.

Viewing Documentation
To view the manual for each utility

• Append --manual to the command that invokes the utility:

# ec2-bundle-image --manual

To view help for each utility

• Append --help to the command that invokes the utility:

# ec2-bundle-image --help

Bundling an AMI Using the AMI Tools

After creating a machine image, it must be bundled as an AMI for use with Amazon EC2. How you
bundle the image depends on how you created the image (for information about creating AMIs, see
Creating an AMI).

To bundle the image you prepared in a loopback file

• Enter the following command:

# ec2-bundle-image -i <image_name>.img -k <private_keyfile> -c

<certificate_file> -u <user_id>

where <image_name> is the name of the image file, <private_keyfile> is the file that contains
the private key, <certificate_file> is the file that contains the certificate, and <user_id> is the
user ID associated with your account.

Note

The user ID is your AWS account ID without dashes. It is the same as your Amazon
Access ID and consists of 12 digits.

To bundle an AMI you created by taking a snapshot of the local machine root file system (requires
root privileges)

• Enter the following command:

# ec2-bundle-vol -k <private_keyfile> -c <certificate_file> -u <user_id>

API Version 2008-02-01

19
 Amazon Elastic Compute Cloud Developer Guide
Uploading a Bundled AMI

where <private_keyfile> is the file that contains the private key, <certificate_file> is the
file that contains the certificate, and <user_id> is the user ID associated with your account.

Note

Make sure to disable SELinux when running ec2-bundle-vol.

Note

The user ID is your AWS account ID without dashes. It is the same as your Amazon
Access ID and consists of 12 digits.

Example

This command bundles an image created in a loopback file:

# ec2-bundle-image -i my-image.fs -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem
-c cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -u 495219933132
image.part.00
image.part.01
...
image.part.NN
image.manifest.xml

This command bundles the local machine root file system:

# ec2-bundle-vol -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -c cert-
HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -u 495219933132
image.part.00
image.part.01
...
image.part.NN
image.manifest.xml

Uploading a Bundled AMI

You must upload the bundled AMI to Amazon S3 before it can be accessed by Amazon EC2. Use
ec2-upload-bundle to upload the bundled AMI that you created earlier. Amazon S3 stores data
objects in buckets, which are similar to directories.

Buckets must have globally unique names. The ec2-upload-bundle utility uploads the bundled AMI
to a specified bucket. If the specified bucket does not exist, it will be created. If the specified bucket
exists and belongs to another user, the ec2-upload-bundle command will fail.

To upload the bundled AMI

• Enter the following command:

# ec2-upload-bundle -b <bucket> -m image.manifest.xml -a <access_key> -s
<secret_key>

API Version 2008-02-01

20
 Amazon Elastic Compute Cloud Developer Guide
Sharing AMIs

where <bucket> is the target bucket, <access_key> is your AWS Access Key, and
<secret_key> is your AWS Secret Key.

The AMI manifest file and all image parts are uploaded to Amazon S3. The manifest file is encrypted
with the Amazon EC2 public key before being uploaded.

Sharing AMIs
Topics

• Shared AMI Guidelines

• Sharing AMIs
• Making an AMI Public
• Sharing an AMI with Specific Users
• Publishing Shared AMIs

This section describes how to build and share AMIs.

Shared AMIs are AMIs that developers build and make available for other AWS developers to use.
Building safe, secure, useable AMIs for public consumption is a fairly straightforward process, if you
follow a few simple guidelines.

For information on building shared AMIs, see Shared AMI Guidelines. For information on sharing
AMIs, see Sharing AMIs

Shared AMI Guidelines

These guidelines are not requirements and you are welcome to follow or ignore them. However,
following these guidelines should produce a better user experience and help ensure your users' instances
are secure.

To build a shared AMI, follow these guidelines:

1. Update the AMI Tools at Boot Time

2. Disable Password-Based Logins for Root
3. Install Public Key Credentials
4. Disable sshd DNS Checks (optional)
5. Identify Yourself
6. Protect Yourself

Note

These guidelines are written for Fedora distributions, but the principles apply to any AMI.
You might need to modify the provided examples for other distributions. For other
distributions, review their documentation or search the AWS forums in case someone else
has done it already.

Update the AMI Tools at Boot Time

API Version 2008-02-01

21
 Amazon Elastic Compute Cloud Developer Guide
Shared AMI Guidelines

We recommend that your AMIs download and upgrade the Amazon EC2 AMI creation tools during
startup. This ensures that new AMIs based on your shared AMIs will have the latest AMI tools.

To update the AMI tools at startup on Fedora

• Add the following to rc.local:

# Update the Amazon EC2 AMI creation tools
echo " + Updating ec2-ami-tools"
wget http://s3.amazonaws.com/ec2-downloads/ec2-ami-tools.noarch.rpm && \
rpm -Uvh ec2-ami-tools.noarch.rpm && \
echo " + Updated ec2-ami-tools"

Use this method to automatically update other software on your image.

Note

When deciding which software to automatically update, consider the amount of WAN
traffic that the update will generate (your users will be charged for it) and the risk of the
update breaking other software on the AMI.

Note

The above procedure applies to Fedora distributions. For other distributions:

• On most Red Hat systems, add these steps to your /etc/rc.d/rc.local script.
• On Gentoo systems, add them to /etc/conf.d/local.local.
• On Ubuntu systems, add them to /etc/rc.local.
• On Debian, you might need to create a start up script in /etc/init.d and use
update-rc.d <scriptname> defaults 99 (where <scriptname> is the name of
the script you created) and add the steps to this script.

Disable Password-Based Logins for Root

Using a fixed root password for a public AMI is a security risk that can quickly become known. Even
relying on users to change the password after the first login opens a small window of opportunity for
potential abuse.

To solve this problem, disable password-based logins for the root user. Additionally, we recommend
you randomize the root password at boot.

To disable password-based logins for root

1. Open the /etc/ssh/sshd_config file with a text editor and change the following line:
#PermitRootLogin yes

to
PermitRootLogin without-password

API Version 2008-02-01

22
 Amazon Elastic Compute Cloud Developer Guide
Shared AMI Guidelines

The location of this configuration file might differ for your distribution, or if you are not running
OpenSSH. If this is the case, consult the relevant documentation.
2. To randomize the root password, add the following to your boot process:
if [ -f "/root/firstrun" ] ; then
dd if=/dev/urandom count=50|md5sum|passwd --stdin root
rm -f /root/firstrun
else
echo "* Firstrun *" && touch /root/firstrun
fi

Note

This step assumes that a /root/firstboot file is bundled with the image. If file was not
created, the root password will never be randomized and will be set to the default.

Note

If you are using a distribution other than Fedora, you might need to consult the
documentation that accompanied the distribution.

Install Public Key Credentials

After configuring the AMI to prevent logging in using a password, you must make sure users can log in
using another mechanism.

Amazon EC2 allows users to specify a public-private key pair name when launching an instance. When
a valid key pair name is provided to the RunInstances API call (or through the command line API
tools), the public key (the portion of the key pair that Amazon EC2 retains on the server after a call to
CreateKeyPair) is made available to the instance through an HTTP query against the instance metadata.

To login through SSH, your AMI must retrieve the key value at boot and append it to
/root/.ssh/authorized_keys (or the equivalent for any other user account on the AMI). Users will
be able to launch instances of your AMI with a key pair and log in without requiring a root password.
if [ ! -d /root/.ssh ] ; then
mkdir -p /root/.ssh
chmod 700 /root/.ssh
fi
# Fetch public key using HTTP
curl http://169.254.169.254/2008-02-01//meta-data/public-keys/0/openssh-key >
/tmp/my-key
if [ $? -eq 0 ] ; then
cat /tmp/my-key >> /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys
rm /tmp/my-key
fi

This can be applied to any user account; you do not need to restrict it to root.

Note

Rebundling an instance based on this image includes the key with which it was launched.
To prevent the key's inclusion, you must clear out (or delete) the authorized_keys file
or exclude this file from rebundling.

API Version 2008-02-01

23
 Amazon Elastic Compute Cloud Developer Guide
Sharing AMIs

Disable sshd DNS Checks (optional)

Disabling sshd DNS checks slightly weakens your sshd security. However, if DNS resolution fails, SSH
logins will still work. If you do not disable sshd checks, DNS resolution failures prevent all logins.

To disable sshd DNS checks

• Open the /etc/ssh/sshd_config file with a text editor and change the following line:
#UseDNS yes

to:
UseDNS no

Note

The location of this configuration file can differ for your distribution or if you are not
running OpenSSH. If this is the case, consult the relevant documentation.

Identify Yourself
Currently, there is no easy way to know who provided a shared AMI as each AMI is represented by a
numeric user ID.

We recommend that you post a description of your AMI, and the AMI ID, in the Amazon EC2
developer forum. This provides a convenient central location for users who are interested in trying new
shared AMIs.

Protect Yourself
The previous sections described how to make your shared AMIs safe, secure, and useable for the users
who launch them. This section describes guidelines to protect yourself from the users of your AMI.

We recommend against storing sensitive data or software on any AMI that you share. Users who launch
a shared AMI might be able to rebundle it and register it as their own. Follow these guidelines to help
you to avoid some easily overlooked security risks:

• Always delete the shell history before bundling. If you attempt more than one bundle upload in the
same image, the shell history contains your secret access key.
• Bundling a running instance requires your private key and X.509 certificate. Put these and other
credentials in a location that is not bundled (such as the ephemeral store).
• Exclude the ssh authorized keys when bundling the image. The Amazon public images store the
public key used to launch an instance with its ssh authorized keys file.

Note

Unfortunately, it is not possible for this list of guidelines to be exhaustive. Build your
shared AMIs carefully and take time to consider where you might expose sensitive data.

API Version 2008-02-01

24
 Amazon Elastic Compute Cloud Developer Guide
Making an AMI Public

Sharing AMIs
Amazon EC2 enables users to share their AMIs with other users. This section describes how to share
AMIs using the Amazon EC2 command line tools.

Note

Before proceeding, make sure to read the security considerations of sharing AMIs in the
Shared AMI Guidelines section.

AMIs have a launchPermission property that controls which users, besides the owner, are allowed to
launch instances of that AMI. By modifying an AMI's launchPermission property, you can allow all
users to launch the AMI (make the AMI public) or only allow a few specific users to launch the AMI.

The launchPermission attribute is a list of users and launch groups. Launch permissions can be
granted by adding or removing items from the list. Explicit launch permissions for users are granted or
revoked by adding or removing their AWS account IDs. The only launch group currently supported is
the all group, which makes the AMI public. The rest of this section refers to launch groups simply as
groups. Launch groups are not the same as security groups and the two should not be confused. An AMI
can have both public and explicit launch permissions.

Note

You are not billed when your AMI is launched by other users. Users launching the AMI
are billed.

Select from the following:

1. Making an AMI Public

2. Sharing an AMI with Specific Users
3. Publishing Shared AMIs

Making an AMI Public

To make an AMI public

• Add the all group to the AMI's launchPermission attribute using the ec2-modify-image-attribute
command:
PROMPT> ec2-modify-image-attribute <ami_id> --launch-permission -a all

where <ami_id> is the ID of the AMI.

To check the launch permissions of an AMI

• Use the ec2-describe-image-attribute command:

PROMPT> ec2-describe-image-attribute <ami_id> -l

where <ami_id> is the ID of the AMI.

API Version 2008-02-01

25
 Amazon Elastic Compute Cloud Developer Guide
Sharing an AMI with Specific Users

To make an AMI private again

• Remove the all group from its launch permissions:

PROMPT> ec2-modify-image-attribute <ami_id> -l -r all

where <ami_id> is the ID of the AMI.

This will not affect any explicit launch permissions for the AMI or any running instances of the AMI.

Example

This example makes the ami-2bb65342 AMI public:

PROMPT> ec2-modify-image-attribute ami-2bb65342 --launch-permission -a all
launchPermission ami-2bb65342 ADD group all

This examples displays the launch permissions of the ami-2bb65342 AMI:

PROMPT> ec2-describe-image-attribute ami-2bb65342 -l
launchPermission ami-2bb65342 group all

This example removes the all group from the permissions of the ami-2bb65342 AMI, making it
private:
PROMPT> ec2-modify-image-attribute ami-2bb65342 -l -r all
launchPermission ami-2bb65342 REMOVE group all

Sharing an AMI with Specific Users

You can share an AMI with specific users without making the AMI public. All you need is the user's
AWS user's account ID, which is available on the AWS Account Activity page.

To grant explicit launch permissions

• Enter the following command:

PROMPT> ec2-modify-image-attribute <ami_id> -l -a <user_id>

where <ami_id> is the ID of the AMI and <user_id> is the user's account ID, without hyphens.

To remove launch permissions for a user

• Enter the following command:

PROMPT> ec2-modify-image-attribute <ami_id> -l -r <user_id>

where <ami_id> is the ID of the AMI and <user_id> is the user's account ID, without hyphens.

API Version 2008-02-01

26
 Amazon Elastic Compute Cloud Developer Guide
Publishing Shared AMIs

To remove all launch permissions

• Enter the following command to remove all public and explicit launch permissions:
PROMPT> ec2-reset-image-attribute <ami_id> -l

where <ami_id> is the ID of the AMI.

Note

The AMI owner always has rights to the AMI and will be unaffected by the
ec2-reset-image-attribute command.

Example

The following example grants launch permissions to the 495219933132 user for the ami-2bb65342
AMI:
PROMPT> ec2-modify-image-attribute ami-2bb65342 -l -a 495219933132
launchPermission ami-2bb65342 ADD userId 495219933132

The following example removes launch permissions from the 495219933132 user for the ami-2bb65342
AMI:
PROMPT> ec2-modify-image-attribute ami-2bb65342 -l -r 495219933132
launchPermission ami-2bb65342 REMOVE userId 495219933132

The following example removes all public and explicit launch permissions from the ami-2bb65342
AMI:
PROMPT> ec2-reset-image-attribute ami-2bb65342 -l
launchPermission ami-2bb65342 RESET

Publishing Shared AMIs

After creating a shared AMI, other developers can find it in the EC2 Resource Center.

To publish your AMI, post it in the Public AMIs Folder of the Amazon Web Services Resource Center.

You must include the following information when publishing AMIs:

• AMI ID
• AMI manifest

We recommend including the following information when publishing AMIs:

• Publisher
• Publisher URL
• OS / Distribution
• Key Features
• Description

API Version 2008-02-01

27
 Amazon Elastic Compute Cloud Developer Guide
Creating Paid AMIs

• Daemons / Services
• Release Notes

You can cut and paste the following template into the document. You must be in HTML edit mode.

<strong>AMI&nbsp;ID: </strong>[ami-id]<br />

<strong>AMI&nbsp;Manifest: </strong>[bucket/image.manifest.xml]<br />
<h2>About this &AMI;</h2>
<ul>
<li>Published by [Publisher] (<a
href="http://www.mysite.com">[http://www.mysite.com]</a>).<br />
</li>
<li>[Key Features] <br />
</li>
<li>[Description]</li>
<li>This image contains the following daemons / services:
<ul>
<li>[Daemon 1]</li>
<li>[Daemon 2]</li>
</ul>
</li>
</ul>
<h2><strong>What&#39;s New?</strong></h2>The following changes were made on
[Date].<br />
<ul>
<li>[Release Notes 1]</li>
</ul>
<span style="font-size: x-small; font-family: courier
new,courier">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;[Note 1]</span><br />
<span style="font-size: x-small; font-family: courier
new,courier">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;[Note 2]</span><br />
<span style="font-size: x-small; font-family: courier
new,courier">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;[Note 3]</span><br />
<ul>

Creating Paid AMIs

Introduction
A paid AMI is an AMI that you sell to other Amazon EC2 users. They pay you according to the price
you set. To be able to create a paid AMI, you use Amazon DevPay. What is Amazon DevPay?

Amazon DevPay is a billing and account management service that enables you to get paid for an AMI
you create and that other Amazon EC2 users use. Amazon DevPay creates and manages the order
pipeline and billing system for you. Your customers sign up for your AMI, and Amazon DevPay
automatically meters their usage of Amazon EC2, bills them based on the pricing you set, and collects
their payments. What else is special about DevPay?

• You can charge customers for your AMI; the charges can include recurring charges based on the
customer's usage Amazon EC2, a fixed one-time charge, and a recurring monthly charge.
• Your customers can easily sign up and pay for your AMI with their trusted Amazon.com accounts.
• Your customers are authenticated, thus ensuring they have access only to what they should.
• If your customers don't pay their bills, DevPay turns off their access to your AMI for you.
• Amazon Payments handles payment processing.

API Version 2008-02-01

28
 Amazon Elastic Compute Cloud Developer Guide
Paid and Supported AMIs

Basic DevPay Flow

1 Your customer uses an Amazon.com account to sign up and pay for your AMI. The
sign-up page indicates that you have teamed up with Amazon Payments to make billing
easy and secure.

2 Your customer pays the price you've defined to use your product.

3 DevPay subtracts the required DevPay fees and pays you the difference.

4 You pay the costs of Amazon EC2 that your AMI used.

To learn more about Amazon DevPay, see the Amazon DevPay Developer Guide.

Paid and Supported AMIs

Amazon DevPay and Amazon EC2 work together to support these two scenarios:

Paid and Supported AMIs

• Paid AMIs—You charge for the use of an AMI you've created and shared with either select
customers or the public. You might want to share the AMI with only select customers, for example, if
you're offering a special price to just those customers.
• Supported AMIs—You charge your customers for software or a service you provide that they use
with their own AMIs.

You determine the rates you want to charge customers who use paid AMIs or supported AMIs. The
price you charge can include a one-time charge, a monthly charge, and a markup on the hourly instance
or the data transferred charge. For more information about how you can set your prices, see the Amazon
DevPay Developer Guide.

Summary of How Paid AMIs Work

The following steps summarize the basic flow for creating and using paid AMIs:

Note

Detailed information about most of the following steps is provided in the Amazon DevPay
Developer Guide.

API Version 2008-02-01

29
 Amazon Elastic Compute Cloud Developer Guide
Summary of How Supported AMIs Work

Paid AMI Process

1 You create an AMI as described elsewhere in this guide.

2 You register a product with Amazon DevPay (see.Product Registration) As part of this
process, you provide a product description, product pricing, etc. This registration process
creates a product code for the product and a URL where customers can sign up to use the
product (called the purchase URL).

3 You use an Amazon EC2 command or API call to associate the product code with your
AMI (see Associating a Product Code with an AMI ). This makes the AMI a paid AMI.

4 You use an Amazon EC2 command or API call to share the AMI with select customers or
the public (see Sharing Your Paid AMI with Select Users or the Public).

Note

Even if you share a paid AMI and it has a product code, no one can use the
AMI until they sign up for it (see the following steps).

5 You advertise your paid AMI to customers and make the purchase URL available to them.
Note that you can submit your paid AMI to be listed on the AWS Resource Center with
other public AMIs at
http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=116.

6 Customers who want to use your AMI discover your product through your advertisements
or the AWS Resource Center, etc.

7 Customers then use the purchase URL you provide to sign up for and purchase your
product. If they're not already signed up for Amazon EC2, they'll be prompted to sign up.
They purchase your product with their Amazon.com accounts. They must have the
credentials needed to launch Amazon EC2 instances. At this point, they have the AMI ID
(from either step 5 or step 6 above).

8 Customers then launch an Amazon EC2 instance specifying the AMI ID. Because you
associated the shared AMI with the product code, the customers are charged at the rate you
set. For more information, see Paying for AMIs.

Each customer's bill for the AMI is displayed on their Application Billing page, which shows the
activity for DevPay products. For more information, see the Amazon DevPay Developer Guide.

Summary of How Supported AMIs Work

The following steps summarize the basic process for supported AMIs:

Supported AMI Process

1 You register a product with Amazon DevPay (see Product Registration). As part of this
process, you provide a product description, product pricing, etc. This registration process
creates a product code for the product and a URL where customers can sign up to use the
product (called the purchase URL).
2 You then advertise your paid AMI to customers and make the purchase URL available to

API Version 2008-02-01

30
 Amazon Elastic Compute Cloud Developer Guide
Product Registration

them.
3 Customers who want to use your product discover the product through your
advertisements, etc.
4 Customer then use the purchase URL to sign up for and purchase your product. If they're
not already signed up for Amazon EC2, they'll be prompted to sign up. They purchase
your product with their Amazon.com accounts. They must have the credentials needed to
launch Amazon EC2 instances. At this point, they have the product code (from either step
2 or step 3 above).
5 Customers then use an Amazon EC2 command or API call to associate the product code
with their AMIs (see Associating a Product Code with an AMI).
6 Customers then launch one or more instances of the AMIs. Because the customers
associated their AMIs with the product code, they are charged at the rate you set.

Each customer's bill for the AMI is displayed on their Application Billing page, which shows the
activity for DevPay products. For more information, see the Amazon DevPay Developer Guide.

When a customer contacts you for support for an AMI, you can confirm your product code is associated
with the AMI and the customer's instance is currently running the AMI (see Confirming an Instance Is
Running an AMI Associated with a Product Code).

Product Registration
You must register your AMI (referred to as your product) with Amazon DevPay. During registration,
you provide product information such as pricing, and you receive information you need to sell your
product.

Note

AWS must approve your product after you register it. The approval process takes several
business days. During that time you can begin integrating your product with DevPay.

You provide the following information during registration:

• Company name
• Product name
• Product description (as you want your customers to see it)
• Redirect URL (the page you want customers to see after they have purchased the product)
• Any terms and conditions you want displayed (optional)
• Contact e-mail address and telephone number (to be used by AWS and not displayed to customers)
• Contact e-mail or URL (to be displayed to customers)
• Pricing for use of the product

The information you display at the redirect URL should give information about the AMI.

Registration provides you with the following information:

• Product code
• Product token
• Purchase URL

API Version 2008-02-01

31
 Amazon Elastic Compute Cloud Developer Guide
Associating a Product Code with an AMI

You need the product code and purchase URL to integrate your product with DevPay as described in
Summary of How Paid AMIs Work and Summary of How Supported AMIs Work. You need the
product token if you're going to set up your system to later verify whether a customer is still subscribed
to your product. For more information, see the Amazon DevPay Developer Guide.

Important

The Amazon DevPay Developer Guide covers the procedure for registering your product
with Amazon DevPay. Before you register your product, we recommend you read the
information in that guide about how to set your AMI's price and how billing for Amazon
DevPay products works.

Associating a Product Code with an AMI

You must be the owner of an AMI to associate a product code with it. You can associate a single
product code with more than one paid AMI. You might do this if you have similar versions of an AMI
(for example, a 32-bit version and a 64-bit version), you've assigned them all the same price, and you'd
like to minimize the number of Amazon DevPay product codes you have (to make your bookkeeping
easier).

To associate a product code with an AMI

• Enter the following command:

PROMPT> ec2-modify-image-attribute <ami_id> --product-code <product_code>

where <ami_id> is the AMI ID and <product_code> is the product code.

To verify the product code is associated with the AMI

• Enter the following command:

PROMPT> ec2-describe-image-attribute <ami_id> --product-code

You can't change or remove the productCodes attribute after you've set it. If you want to use the same
image without the product code or associate a different product code with the image, you must reregister
the image to obtain a new AMI ID. You can then use that AMI without a product code or associate the
new product code with the AMI ID.

Example

The following example associates the ami-2bb65342 AMI with the 774F4FF8 product code:
PROMPT> ec2-modify-image-attribute ami-2bb65342 --product-code 774F4FF8
productCodes ami-2bb65342 productCode 774F4FF8

This example verifies that the product code is associated with the AMI:
PROMPT> ec2-describe-image-attribute ami-2bb65342 --product-code
productCodes ami-2bb65342 productCode 774F4FF8

API Version 2008-02-01

32
 Amazon Elastic Compute Cloud Developer Guide
Confirming an Instance Is Running an AMI Associated

Sharing Your Paid AMI with Select Users or the Public

After you associate the product code with the AMI, you need to share the AMI with select customers or
the public by using the ec2-modify-image-attribute command.

To share the AMI

• Enter the following command:

PROMPT> ec2-modify-image-attribute <ami_id> --launch-permission -a all

where <ami_id> is the AMI ID.

Even though you've shared the AMI, no one can use it until they sign up for your product by going to
the purchase URL. Once customers sign up, any instances of the paid AMI they launch will be billed at
the rate you specified during product registration.

Example

The following example shares the ami-2bb65342 AMI with the public:
PROMPT> ec2-modify-image-attribute ami-2bb65342 --launch-permission -a all
launchPermission ami-2bb65342 ADD group all

Confirming an Instance Is Running an AMI Associated with a

Product Code
If you have created a product for others to use with their AMIs (the supported AMI scenario), you might
want to confirm that a particular AMI is associated with your product code and a particular instance is
currently running that AMI.

Note

You must be the owner of the product code to successfully call

ec2-confirm-product-instance with that product code.
Because your customers don't own the product code, they should describe their instances to
confirm their instances are running with your product code.

To confirm an AMI is associated with your product code and an instance is running that AMI

• Enter the following command:

PROMPT> ec2-confirm-product-instance <product_code> -i <instance>

where <product_code> is the product code and <instance> is the instance.

If the AMI is associated with the product code, true is returned with the AMI owner's account ID.
Otherwise, false is returned.

API Version 2008-02-01

33
 with a Product Code

Example

The following example confirms whether the i-10a64379 instance is running the 6883959E product
code:
PROMPT> ec2-confirm-product-instance 6883959E -i i-10a64379
6883959E i-10a64379 true 495219933132

Getting the Product Code from Within an Instance

A running Amazon EC2 instance can determine if an Amazon DevPay product code is attached to itself.
The instance retrieves the product code like it retrieves its other metadata. For more information about
the retrieval of metadata, see Instance Metadata.

The instance retrieves the product code by querying a web server with this REST-like API call:
GET http://169.254.169.254/2007-03-01/meta-data/product-codes

Example response:
774F4FF8

API Version 2008-02-01

34
 Amazon Elastic Compute Cloud Developer Guide
Instance Usage

Launching and Using Instances

Topics

• Instance Usage
• Instance Types
• Instance Metadata
• Using Shared AMIs
• Paying for AMIs
• Get Console Output and Reboot Instances

This section describes how to launch instances and retrieve instance-specific data from within the
instance. It also covers launching shared AMIs and security risks associated with running shared AMIs.

Instance Usage
The instance is your basic computation building block. Amazon EC2 offers multiple instance types from
which you can choose. You can run as many or as few instances as you need at any given time.

For information about available instance types, see Instance Types.

Once launched, an instance looks very much like a traditional host. You have complete control of your
instances; you have root access to each one and you can interact with them as you would any machine.

Here are some suggestions for making the best use of Amazon EC2 instances.

• Do not rely on an instance's local storage for valuable, long-term data.

When instances fail, the data on the local disk is lost. Use a replication strategy across multiple
instances to keep your data safe or store your persistent data in Amazon S3
• Define images based on the type of work they perform.
For "Internet applications," you might define one image for database instances and another for web
servers. Image creation and storage are cheap and easy operations, so you can individualize and
customize as necessary. Specialized images can result in smaller AMI sizes, which will boot
considerably faster.

API Version 2008-02-01

35
 Amazon Elastic Compute Cloud Developer Guide
Instance Types

• Monitor the health of your instances.

You can make your instances work for you by configuring them to monitor each other. For example,
you could create an image that contains an open-source monitoring tool such as Nagios or OpenNMS.
Then, your other instances could report their health to the monitoring instance.
• Keep your Amazon EC2 firewall permissions as restrictive as possible.
Only open up permissions that you require. Use separate groups to deal with instances that have
different security requirements. Consider using additional security measures inside your instance
(such as using your own firewall). If you need to log in interactively (ssh), consider creating a bastion
security group that allows external login and keep the remainder of your instances in a group that does
not allow external login.

Instance Types
Amazon EC2 provides the flexibility to meet your computing needs by allowing you to choose from
different instance types. Each instance type provides a predictable amount of dedicated compute
capacity and is charged per instance-hour.

Available Instance Types

The following instance types are available:

Small Large Extra Large

CPU 1 EC2 Compute Unit (1 4 EC2 Compute Units (2 8 EC2 Compute Units (4
virtual core with 1 EC2 virtual cores with 2 EC2 virtual cores with 2 EC2
Compute Unit) Compute Units each) Compute Units each)h

Memory 1.7 GB 7.5 GB 15 GB

Storage 160 GB instance storage 850 GB instance storage (2 1690 GB instance storage
(150 GB plus 10 GB root x 420 GB plus 10 GB root (4 x 420 GB plus 10 GB
partition) partition) root partition)

Platform 32-bit 64-bit 64-bit

I/O Moderate High High

Performance

Instance m1.small m1.large m1.xlarge

Type Name

Note

The small instance type is the original Amazon EC2 instance type available since the
launch of Amazon EC2. It is the default instance type for all customers. To use other
instance types, you must specify them through the RunInstances operation.

API Version 2008-02-01

36
 Amazon Elastic Compute Cloud Developer Guide
I/O Resources

Measuring Compute Resources

Transitioning to a utility computing model changes how developers are trained to think about CPU
resources. Instead of purchasing or leasing a particular processor to use for several months or years, you
are renting capacity by the hour. Because Amazon EC2 is built on commodity hardware, over time there
might be several different types of physical processors underlying different virtual EC2 instances. Our
goal is to provide a consistent amount of CPU capacity regardless of the actual underlying hardware.

Amazon EC2 uses a variety of measures to provide each instance with a consistent and predictable
amount of CPU capacity. To make it easy for developers to compare CPU capacity between different
instance types, we defined an Amazon EC2 Compute Unit.

Note

We use several internal benchmarks and tests to manage the consistency and predictability
of the performance of an Amazon EC2 Compute Unit. For more information, go to the
Instance page.

To find out which instance will work best for your application, we recommend launching an instance
and using your own benchmark application. This will help you determine which instance type works
best for your specific use case.

I/O Resources
Amazon EC2 provides virtualized server instances. While some resources like CPU, memory and
instance storage are dedicated to a particular instance, other resources like the network and the disk
subsystem are shared amongst instances. If each instance on a physical host tries to use as much of one
of these shared resources as possible, each will receive an equal share of that resource. However, when a
resource is under-utilized you will often be able to consume a higher share of that resource while it is
available.

The different instance types will provide higher or lower minimum performance from the shared
resources depending on their size. Each of the instance types has an I/O performance indicator
(moderate or high). Instance types with high I/O performance have a larger allocation of shared
resources. Allocating larger share of shared resources also reduces the variance of I/O performance. For
most applications, moderate I/O performance is more than enough. However, for applications that
require greater or more consistent I/O performance, consider instances with high I/O performance.

Instance Metadata
Amazon EC2 instances can access instance-specific metadata as well as data supplied when launching
the instances. This data can be used to build more generic AMIs that can be modified by configuration
files supplied at launch time.

Example

If you run web servers for various small businesses, they can all use the same AMI and retrieve their
content from the Amazon S3 bucket you specify at launch.

To add a new customer at any time, simply create a bucket for the customer, add their content, and
launch your AMI.

API Version 2008-02-01

37
 Amazon Elastic Compute Cloud Developer Guide
Categories of Available Data

Categories of Available Data

The data available to instances is categorized into metadata and user-supplied data.

Metadata is specific to an instance. Currently, we provide:

Data Description Version Introduced

ami-id The AMI ID used to launch the instance. 1.0
ami-launch-index The index of this instance in the reservation (per 1.0
AMI).
ami-manifest-path The manifest path of the AMI with which the 1.0
instance was launched.
ancestor-ami-ids The AMI IDs of any instances that were 2007-10-10
rebundled to create this AMI.
block-device-mapping Defines native device names to use when 2007-10-10
exposing virtual devices.
instance-id The ID of this instance. 1.0
instance-type The type of instance to launch. For more 2007-08-29
information, see Instance Types.
local-hostname The local hostname of the instance. 2007-01-19
local-ipv4 Public IP address if launched with direct 1.0
addressing; private IP address if launched with
public addressing.
kernel-id The ID of the kernel launched with this instance, 2008-02-01
if applicable.
placement The availability zone in which the instance 2008-02-01
launched.
product-codes Product codes associated with this instance. 2007-03-01
public-hostname The public hostname of the instance. 2007-01-19
public-ipv4 NATted public IP Address 2007-01-19
public-keys/ Public keys. Only available if supplied at instance 1.0
launch time
ramdisk-id The ID of the RAM disk launched with this 2008-02-01
instance, if applicable.
reservation-id ID of the reservation. 1.0
security-groups Names of the security groups the instance is 1.0
launched in. Only available if supplied at instance
launch time

User-supplied data is treated as opaque data: what you give us is what you get back.

Note

API Version 2008-02-01

38
 Amazon Elastic Compute Cloud Developer Guide
Data Retrieval

• All instances launched together get the same user-supplied data. You can use the AMI
launch index as an index into the data.
• User data is limited to 16K. This limit applies to the data in raw form, not base64
encoded form.
• The user data must be base64 encoded before being submitted to the API. The API
command-line tools perform the base64 encoding for you. The data is in base64 and is
decoded before presented to the instance.

Data Retrieval
An instance retrieves the data by querying a web server using a Query API. The base URI of all requests
is http://169.254.169.254/2008-02-01/ where 2008-02-01 indicates the API version.

Note

Amazon EC2 Version 1.0 is part of a legacy versioning scheme. Newer versions follow a
date based versioning scheme. For more information on the versioning scheme used by
Amazon EC2, see API Versioning.

The latest version of the API is always available using the URI http://169.254.169.254/latest.

Security of Launch Data

Although only your specific instance can access launch data, the data is not protected by cryptographic
methods. You should take suitable precautions to protect sensitive data (such as long lived encryption
keys).

Note

You are not billed for HTTP requests used to retrieve metadata and user-supplied data.

Retrieving Metadata
Requests for a specific metadata resource returns the appropriate value or a 404 HTTP error code if the
resource is not available. All metadata is returned as text (content type text/plain).

Requests for a general metadata resource (i.e. an URI ending with a /) return a list of available resources
or a 404 HTTP error code if there is no such resource. The list items are on separate lines terminated by
line feeds (ASCII 10).

Example

The following examples list HTTP GET requests and responses. You can use a tool such as curl or wget
to make these types of requests.

This example gets the available API versions:

GET http://169.254.169.254/
1.0
2007-01-19

API Version 2008-02-01

39
 Amazon Elastic Compute Cloud Developer Guide
Data Retrieval

2007-03-01
2008-02-01

This example gets the top-level metadata items:

GET http://169.254.169.254/2008-02-01/meta-data/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
instance-id
instance-type
local-hostname
local-ipv4
placement/
public-hostname
public-ipv4
public-keys/
reservation-id
security-groups

This examples get the value of each metadata item in the above example:
GET http://169.254.169.254/2008-02-01/meta-data/ami-manifest-path
my-amis/spamd-image.manifest.xml
GET http://169.254.169.254/2008-02-01/meta-data/ami-manifest-path
my-amis/spamd-image.manifest.xml
GET http://169.254.169.254/2008-02-01/meta-data/ami-id
ami-2bb65342
GET http://169.254.169.254/2008-02-01/meta-data/reservation-id
r-fea54097
GET http://169.254.169.254/2008-02-01/meta-data/hostname
ec2-67-202-51-223.compute-1.amazonaws.com

This example gets the list of available public keys:

GET http://169.254.169.254/2008-02-01/meta-data/public-keys/
0=my-public-key

This example shows the formats in which public key 0 is available:

GET http://169.254.169.254/2008-02-01/meta-data/public-keys/0/
openssh-key

This example gets public key 0 (in openssh-key format):

GET http://169.254.169.254/2008-02-01/meta-data/public-keys/0/openssh-key
ssh-rsa AAAA.....wZEf my-public-key

This example gets the product code:

GET http://169.254.169.254/2008-02-01/meta-data/product-codes
774F4FF8

Retrieving User Data

Requests for the user data returns the data as-is (content type application/x-octetstream).

API Version 2008-02-01

40
 Amazon Elastic Compute Cloud Developer Guide
Example: AMI Launch Index Value

Note

All user-supplied data is treated as opaque data; what you give us is what you get back. It
is the responsibility of the instance to interpret this data appropriately.

Example

This shows an example of returning comma-separated user-supplied data:

GET http://169.254.169.254/2008-02-01/user-data
1234,fred,reboot,true | 4512,jimbo, | 173,,,

This shows an example of returning line-separated user-supplied data:

GET http://169.254.169.254/2008-02-01/user-data
[general]
instances: 4
[instance-0]
s3-bucket: fred
[instance-1]
reboot-on-error: yes

Example: AMI Launch Index Value

In this example, Alice wants to launch four instances of her favorite database AMI with the first acting
as master and the remainder acting as replicas.

The master database configuration specifies various database parameters (e.g., the size of store) while
the replicas' configuration specifies different parameters, such as the replication strategy. Alice decides
to provide this data as an ASCII string with a pipe symbol (| delimiting the data for the various
instances:
store-size=123PB backup-every=5min | replicate-every=1min | replicate-
every=2min | replicate-every=10min | replicate-every=20min

where store-size=123PB backup-every=5min defines the master database configuration,

replicate-every=1min defines the first replicant's configuration, replicate-every=2min defines
the second replicant's configuration, and so on.

Alice launches four instances:

$ ec2-run-instances ami-2bb65342 -n 4 -d "store-size=123PB backup-every=5min
| replicate-every=1min | replicate-every=2min | replicate-every=10min | rep
licate-every=20min"
RESERVATION r-fea54097 598916040194 default
INSTANCE i-3ea74257 ami-2bb65342 pending 0 m1.small 2007-08-07T11:29:58+0000
us-east-1c
INSTANCE i-31a74258 ami-2bb65342 pending 1 m1.small 2007-08-07T11:29:58+0000
us-east-1c
INSTANCE i-31a74259 ami-2bb65342 pending 2 m1.small 2007-08-07T11:29:58+0000
us-east-1c
INSTANCE i-31a7425a ami-2bb65342 pending 3 m1.small 2007-08-07T11:29:58+0000
us-east-1c

API Version 2008-02-01

41
 Amazon Elastic Compute Cloud Developer Guide
Example: AMI Launch Index Value

Once launched, all instances have a copy of the user data and the common metadata shown here:

• AMI id: ami-2bb65342

• AMI manifest path: ec2-public-images/getting-started.manifest.xml
• Reservation ID: r-fea54097
• Public keys: none
• Security group names: default
• Instance type: m1.small

However each instance has certain unique metadata:

Instance 1

Metadata Value
instance-id i-3ea74257
ami-launch-index 0
public-hostname ec2-67-202-51-223.compute-1.amazonaws.com
public-ipv4 67.202.51.223
local-hostname ip-10-251-50-35.ec2.internal
local-ipv4 10.251.50.35

Instance 2

Metadata Value
instance-id i-31a74258
ami-launch-index 1
public-hostname ec2-67-202-51-224.compute-1.amazonaws.com
public-ipv4 67.202.51.224
local-hostname ip-10-251-50-36.ec2.internal
local-ipv4 10.251.50.36

Instance 3

Metadata Value
instance-id i-31a74259
ami-launch-index 2
public-hostname ec2-67-202-51-225.compute-1.amazonaws.com
public-ipv4 67.202.51.225
local-hostname ip-10-251-50-37.ec2.internal

API Version 2008-02-01

42
 Amazon Elastic Compute Cloud Developer Guide
Instance Storage

Metadata Value
local-ipv4 10.251.50.37

Instance 4

Metadata Value
instance-id i-31a7425a
ami-launch-index 3
public-hostname ec2-67-202-51-226.compute-1.amazonaws.com
public-ipv4 67.202.51.226
local-hostname ip-10-251-50-38.ec2.internal
local-ipv4 10.251.50.38

Therefore, an instance can determine its portion of the user-supplied data by doing the following:

Metadata Discovery Process

1 Determine which instance in the launch group it is:

GET http://169.254.169.254/2008-02-01/meta-data/ami-launch-index
1

2 Retrieve the user data:

GET http://169.254.169.254/2008-02-01/user-data
store-size=123PB backup-every=5min | replicate-every=1min
| replicate-every=2min | replicate-every=10min | replicate-
every=20min

3 Extract the appropriate part of the user data:

user_data.split('|')[ami_launch_index]

Instance Storage
Every instance includes a fixed amount of storage space on which you can store data. Within this
document, it is referred to as the "ephemeral store" as it is not designed to be a permanent storage
solution.

If an instance reboots (intentionally or unintentionally), the data on the ephemeral store will survive. If
the underlying drive fails or the instance is terminated, the data will be lost.

We highly recommend backing up important data to Amazon S3.

Storage Locations
API Version 2008-02-01
43
 Amazon Elastic Compute Cloud Developer Guide
Disk Performance Optimization

Storage is exposed on the following instance types as follows:

Location Description
/dev/sda1 Formatted and mounted as root (/) on all instance types
/dev/sda2 Formatted and mounted as /mnt on small instances
/dev/sda3 Formatted and mounted as /swap on small instances
/dev/sdb Formatted and mounted as /mnt on large and extra large instances
/dev/sdc Available on large and extra large instances; not mounted
/dev/sdd Available on extra large instances; not mounted
/dev/sde Available on extra large instances; not mounted

Disk Performance Optimization

Due to how Amazon EC2 virtualizes disks, the first write to any location on an instance's drives will
perform slower than subsequent writes. For most applications, amortizing this cost over the lifetime of
the instance will be acceptable. However, if you require high disk performance, we recommend
initializing drives by writing once to every drive location before production use.

To initialize the stores, use the following commands on the m1.large and m1.xlarge instance types:
dd if=/dev/zero of=/dev/sdb bs=1M
dd if=/dev/zero of=/dev/sdc bs=1M
dd if=/dev/zero of=/dev/sdd bs=1M (m1.xlarge only)
dd if=/dev/zero of=/dev/sde bs=1M (m1.xlarge only)

To perform the initialization on all drives at the same time:

dd if=/dev/zero bs=1M|tee /dev/sdb|tee /dev/sdc|tee /dev/sde > /dev/sdd

Note

This can take a long time (about 8 hours for an extra-large instance).

RAID Configuration
Configuring drives for RAID initializes them by writing to every drive location. When configuring
software-based RAID, make sure to change the minimum reconstruction speed:
echo $((30*1024)) > /proc/sys/dev/raid/speed_limit_min

Note

You cannot use iostat (part of the sar System Activity Reporting package) to watch
performance. You also cannot watch 'cat /proc/mdstat'.

API Version 2008-02-01

44
 Amazon Elastic Compute Cloud Developer Guide
Availability Zone Selection

Availability Zones
Amazon operates state-of-the-art, highly available data center facilities. However, failures can occur that
affect the availability of instances that are in the same location. Although this is rare, if you host all your
Amazon EC2 instances in a single location that is affected by such a failure, your instances will be
unavailable.

Amazon EC2 provides the ability to place instances in multiple locations. Amazon EC2 locations are
composed of availability zones and regions. Regions are geographically dispersed and located in
separate geographic areas or countries. Currently, Amazon EC2 exposes only a single region with
multiple availability zones. Availability zones are distinct locations that are engineered to be insulated
from failures in other availability zones and provide inexpensive, low latency network connectivity to
other availability zones in the same region. Regions consist of one or more availability zones. By
launching instances in separate availability zones, you can protect your applications from the failure of a
single location.

For example, if you have instances distributed across three availability zones and one of them fails, you
can design your application so the instances in the remaining availability zones handle any requests.

Note

You can use availability zones in conjunction with elastic IP addresses to remap IP
addresses across availability zones. For information on elastic IP addresses, see Elastic IP
Addresses.

Availability Zone Selection

When you launch an instance, you can optionally specify an availability zone. If you do not specify an
availability zone, Amazon EC2 selects one for you. When launching your initial instances, we
recommend accepting the default availability zone, which will allow Amazon EC2 to select the best the
availability zone for you based on system health and available capacity. Even if you have other instances
running, you might consider not specifying an availability zone if your new instances do not need to be
close to. or separated from, your existing instances.

To view the availability zones that are available to you

• Enter this command:

$ ec2-describe-availability-zones
AVAILABILITYZONE us-east-1a available
AVAILABILITYZONE us-east-1b available
AVAILABILITYZONE us-east-1c available

Note

Availability zones are not the same across accounts. The availability zone us-east-1a for
account A is not necessarily the same as us-east-1a for account B. Zone assignments are
mapped independently for each account.

After determining the availability zones that are available to you, you can launch instances in any of the
zones.

Note

API Version 2008-02-01

45
 Amazon Elastic Compute Cloud Developer Guide
Availability Zone Selection

You will be charged a small bandwidth charge for data that crosses availability zones. For
more information, go to the Amazon EC2 portal page.

API Version 2008-02-01

46
 Amazon Elastic Compute Cloud Developer Guide
Using Shared AMIs

Using Shared AMIs

This section describes how to find and safely use shared AMIs. One of the easiest ways to get started
with Amazon EC2 is to use a shared AMI that has the components you need and add custom content.

Finding Shared AMIs

To find shared AMIs

• Use the ec2-describe-images command (or the abbreviated ec2dim command) with a flag to filter the
results.

Example

This command displays a list of all public AMIs.

PROMPT> ec2dim -x all

The -x all flag shows AMIs executable by all users. This includes AMIs you own.

This command displays a list of AMIs for which you have explicit launch permissions:
PROMPT> ec2dim -x self

AMIs that you own are excluded from the list.

This command displays a list of AMIs owned by Amazon:

PROMPT> ec2dim -o amazon

This command displays a list of AMIs owned by a particular user:

PROMPT> ec2dim -o <target_uid>

where <target_uid> is the account ID of the user who owns the AMIs for which you are looking.

Safe Use of Shared AMIs

AMIs are launched at the user's own risk. Amazon cannot vouch for the integrity or security of AMIs
shared by other users. Therefore, you should treat shared AMIs as you would any foreign code that you
might consider deploying in your own data center and perform the appropriate due diligence.

Ideally, you should get the AMI ID from a trusted source (a website, another user, etc). If you do not
know the source of an AMI, we recommended that you search the forums for comments on the AMI
before launching it. Conversely, if you have questions or observations about a shared AMI, feel free to
use the AWS forums to ask or comment.

Amazon's public images have an aliased owner and display amazon in the userId field. This allows you
to find Amazon's public images easily.

API Version 2008-02-01

47
 Amazon Elastic Compute Cloud Developer Guide
Paying for AMIs

Note

Users cannot alias an AMI's owner.

If you choose to launch a shared AMI, take the following minimum steps after launch to confirm the
AMI is not doing anything malicious:

1. Check the ssh authorized keys file. The only key in the file should be the key you used to launch the
AMI.
2. Check open ports and running services.
3. Change the root password if is not randomized on startup. For more information on randomizing the
root password on startup, see Disable Password-Based Logins for Root.
4. Check if ssh allows root password logins. See Disable Password-Based Logins for Root for more
information on disabling root based password logins.
5. Check whether there are any other user accounts that might allow backdoor entry to your instance.
Accounts with super user privileges are particularly dangerous.
6. Verify that all cron jobs are legitimate.

Paying for AMIs

• Finding Paid AMIs
• Purchasing a Paid AMI
• Launching Paid AMIs
• Paying for Support
• Bills for Paid and Supported AMIs

Amazon EC2 integrates with Amazon DevPay, allowing developers to charge users for the use of their
AMIs or to provide support for instances. To learn more about Amazon DevPay see the Amazon DevPay
Developer Guide. To learn more about charging for your use of your AMIs, or providing support, see
Creating Paid AMIs

This section describes how to discover paid AMIs, launch paid AMIs, and launch instances with a
support product code. Paid AMIs are AMIs you can purchase from other developers.

Finding Paid AMIs

There are several ways you can determine what paid AMIs are available for you to purchase. You can
look for information about them on the Amazon EC2 resource center and forums. Alternatively, a
developer might give you information about a paid AMI directly.

You can also tell if an AMI is a paid AMI by describing the image with the ec2-describe-images
command. This command lists the product code associated with an AMI (see the example below). If the
AMI is a paid AMI, it has a product code. Otherwise, it does not. You can then go to the Amazon EC2
resource center and forums, which might have more information about the paid Amazon EC2 and where
you can sign up to use it.

Note

You must sign up for a paid AMI before you can launch it.

API Version 2008-02-01

48
 Amazon Elastic Compute Cloud Developer Guide
Purchasing a Paid AMI

To check if an AMI is paid:

• Enter this command:

$ ec2-describe-images <ami_id>

where <ami_id> is the AMI ID.

The command returns the following:

IMAGE <ami_id> <manifest> <user_id>, <status> {private | public}

<product_code>

where <ami_id> is the AMI ID, <manifest> is the manifest location, <user_id> is the ID of the
user that owns the AMI, <status> indicates whether the AMI is available, and <product_code> is
the product code associated with the AMI. If a product code is present, the AMI is a paid AMI.

Example

This example shows an ec2-describe-images call describing a paid AMI. The product code is
774F4FF8.
$ ec2-describe-images ami-2bb65342
IMAGE ami-2bb65342 awesome-ami/webserver.manifest.xml 495219933132 available
private 774F4FF8

Purchasing a Paid AMI

You must sign up for (purchase) the paid AMI before you can launch it.

Typically a seller of a paid AMI presents you with information about the AMI, its price, and a link
where you can buy it. When you click the link, you're first asked to log in with an Amazon.com login,
and then you’re taken to a page where you see the paid AMI's price and you confirm you want to
purchase the AMI.

Launching Paid AMIs

This section describes how to launch paid AMIs and launch instances with a support product code.

After you purchase a paid AMI, you can launch instances of it. Launching a paid AMI is the same as
launching any other AMI. No additional parameters are required. The instance will be charged according
to the rates set by the owner of the AMI (which will be more than the base Amazon EC2 rate).

To launch a paid AMI

• Enter the following command:

$ ec2-run-instances <ami_id>

where <ami_id> is the AMI ID.

API Version 2008-02-01

49
 Amazon Elastic Compute Cloud Developer Guide
Paying for Support

Note

The owner of a paid AMI will be able to confirm if a particular instance was launched
using their paid AMI.

Example

This example shows the command used to launch the ami-2bb65342 AMI:
$ ec2-run-instances ami-2bb65342
RESERVATION r-a034c7c9 924417782495 default
INSTANCE i-400df629 ami-2bb65342 pending 0 m1.small 2008-03-21T18:49:33+0000
us-east-1c

Paying for Support

The paid AMI feature also allows developers to offer support for software (or derived AMIs).
Developers can create support products that you can sign up to use. With this model, the developer
provides you with a product. During sign-up for the product, the developer gives you a product code for
that product, which you must then associate with your own AMI. This allows the developer to confirm
that your instance is eligible for support. It also ensures that when you run instances of the product, you
are charged according to the developer's terms for the product.

To associate the product code with your AMI

• Use the ec2-modify-image-attribute command:

PROMPT> ec2-modify-image-attribute <ami_id> --product-code <product_code>

where <ami_id> is the AMI ID and <product_code> is the product code.

Important

Once set, the product code attribute cannot be changed or removed.

To launch a paid AMI, no additional parameters are required for the run-instances. The instance is
charged according to the rates set by the AMI owner.

Example

The following command associates the ami-2bb65342 AMI with the 774F4FF8 product code:
PROMPT> ec2-modify-image-attribute ami-2bb65342 --product-code 774F4FF8
productCodes ami-2bb65342 productCode 774F4FF8

The following command launches the ami-2bb65342 paid AMI:

$ ec2-run-instances ami-2bb65342
RESERVATION r-a034c7c9 924417782495 default
INSTANCE i-400df629 ami-2bb65342 pending 0 m1.small 2008-03-21T18:49:33+0000

API Version 2008-02-01

50
 Amazon Elastic Compute Cloud Developer Guide
Bills for Paid and Supported AMIs

us-east-1c

Bills for Paid and Supported AMIs

At the end of each month, you receive an e-mail with the amount your credit card has been charged for
using the paid or supported AMIs during the month. This bill is separate from your regular Amazon EC2
bill.

At any time you can view the usage information for your paid and supported AMIs at
http://www.amazon.com/dp-applications.

Get Console Output and Reboot Instances

Console output is a valuable tool for problem diagnosis. It is especially useful for troubleshooting kernel
problems and service configuration issues that could cause an instance to terminate or become
unreachable before its SSH daemon can be started.

Similarly, the ability to reboot instances that are otherwise unreachable is valuable for both
troubleshooting and general instance management.

Amazon EC2 instances do not have a physical monitor through which you can view their console
output. They also lack physical controls that allow you to power up, reboot, or shut them down. To
allow these actions, we provide them through the Amazon EC2 SOAP API, Query API, and
command-line tools.

Get Console Output

The Amazon EC2 instance console output displays the exact console output that would normally be
displayed on a physical monitor attached to a machine. This output is buffered because the instance
produces it and then posts it to a store where the instances owner can retrieve it.

The posted output is not continuously updated; only when it is likely to be of the most value. This
includes shortly after instance boot, after reboot, and when the instance terminates.

Note

Only the most recent 64 KB of posted output is stored, which is available for at least 1
hour after the last posting.

You can retrieve the console output for an instance through the SOAP API call described in
GetConsoleOutput, the Query API call described in GetConsoleOutput, and the command line tool
described in ec2-get-console-output.

Note

Only the instance owner can access the console output.

Reboot Instances
Just as you can reset a machine by pressing the reset button, you can reset Amazon EC2 instances
through the SOAP API described in RebootInstances, the Query API described in RebootInstances, and

API Version 2008-02-01

51
 Amazon Elastic Compute Cloud Developer Guide
Reboot Instances

the command line tool described in ec2-reboot-instances.

API Version 2008-02-01

52
 Amazon Elastic Compute Cloud Developer Guide
Instance Addressing

Instance Addressing and Network

Security

Topics

• Instance Addressing
• Network Security

This section provides information on the IP addresses that are assigned to instances and how to
configure the firewall provided by Amazon EC2.

Instance Addressing
All Amazon EC2 instances are assigned two IP addresses at launch: a private address (RFC 1918), and a
public address. The public IP address is directly mapped to the private address through Network Address
Translation (NAT). Private addresses are only reachable from within the Amazon EC2 network. Public
addresses are reachable from the Internet.

Amazon EC2 also provides an internal DNS name and a public DNS name which map to the private and
public IP addresses respectively. The internal DNS name can only be resolved within Amazon EC2. The
public DNS name resolves to the public IP address outside the Amazon EC2 network and the private IP
address within the Amazon EC2 network.

Note

If you require persistent Internet routable IP addresses that can be assigned to and removed
from instances as necessary, use elastic IP addresses. For more information, see Elastic IP
Addresses.

Private (RFC 1918) Addresses

All Amazon EC2 instances are allocated a private address by DHCP. These addresses are from a range
defined in "RFC 1918 - Address Allocation for Private Internets", are only routable within
Amazon EC2, and are used for communication between instances.

API Version 2008-02-01

53
 Amazon Elastic Compute Cloud Developer Guide
Internal DNS Name

This private address is associated exclusively with the instance for its lifetime and is only returned to
Amazon EC2 when the instance terminates.

Always use the internal address when you are communicating between Amazon EC2 instances. This
ensures that your network traffic follows the highest bandwidth, lowest cost, and lowest latency path
through our network.

To determine your IP address

1. Connect to the instance.

2. Enter one of the following:

•
PROMPT> ifconfig eth0

•
PROMPT> curl http://169.254.169.254/latest/meta-data/local-ipv4

The second option refers to the instance data (see Instance Metadata).

Internal DNS Name

Each instance is provided an internal DNS name in the form ip-10-251-157-188.ec2.internal. It
will resolve to the private IP address of the instance from within Amazon EC2; it will not resolve
outside of Amazon EC2.

Public Addresses
At launch, a public address is also associated with each Amazon EC2 instance using Network Address
Translation (NAT). For more information about NAT, see "RFC 1631: The IP Network Address
Translator (NAT)".

This public address is associated exclusively with the instance until it is terminated or replaced with an
elastic IP address.

Important

Amazon EC2 instances that access other instances through their public NAT IP address are
charged for regional data transfer.

From your instance, you can determine your public IP address by referring to the instance data. For
example:
PROMPT> curl http://169.254.169.254/latest/meta-data/public-ipv4

Public DNS
Each instance is provided an external DNS name in the form
ec2-72-44-45-204.compute-1.amazonaws.com. This DNS name resolves to the public IP address
of the instance outside the Amazon EC2 network and the private IP address from within Amazon EC2

API Version 2008-02-01

54
 Amazon Elastic Compute Cloud Developer Guide
Elastic IP Addresses

network.

Elastic IP Addresses
By default, all Amazon EC2 instances are assigned two IP addresses at launch: a private (RFC 1918)
address and a public address that is mapped to the private IP address through Network Address
Translation (NAT).

If you use dynamic DNS to map an existing DNS name to a new instance's public IP address, it might
take up to 24 hours for the IP address to propagate through the Internet. As a result, new instances might
not receive traffic while terminated instances continue to receive requests.

To solve this problem, Amazon EC2 provides elastic IP addresses. Elastic IP addresses are static IP
addresses designed for dynamic cloud computing. Elastic IP addresses are associated with your account,
not specific instances. Any elastic IP addresses that you associate with your account remain associated
with your account until you explicitly release them. Unlike traditional static IP addresses, however,
elastic IP addresses allow you to mask instance or availability zone failures by rapidly remapping your
public IP addresses to any instance in your account.

Note

You can only associate one elastic IP address with one instance at a time.

In the following example, web servers are connected to the Internet through elastic IP addresses and to
database servers through their private IP addresses.

API Version 2008-02-01

55
 Amazon Elastic Compute Cloud Developer Guide
Elastic IP Addresses

The administrator decides to replace a web server with a larger instance type. To do this, the
administrator starts a new instance using a larger instance type (1), disassociates an elastic IP address
from a running instance (2), associates the elastic IP address with the new instance (3), and terminates
the old instance (4).

The following code snippet demonstrates how to set up these tasks.

$ ec2-run-instances ami-6ba54002 -n 1 --availability-zone us-east-1a
RESERVATION r-a034c7c9 924417782495 default
INSTANCE i-3ea74257 ami-6ba54002 pending 0 m1.large 2007-07-11T16:40:44+0000
us-east-1a
$ ec2-disassociate-address 67.202.55.255
ADDRESS 67.202.55.255
$ ec2-associate-address -i i-3ea74257 67.202.55.255
ADDRESS 67.202.55.255 i-43a4412a
$ ec2-terminate-instances i-4bc32334
INSTANCE i-4bc32334 running shutting-down

API Version 2008-02-01

56
 Amazon Elastic Compute Cloud Developer Guide
Network Security

Note

To ensure our customers are efficiently using elastic IP addresses, we impose a small
hourly charge when these IP addresses are not mapped to an instance. When these IP
addresses are mapped to an instance, they are free of charge.

When you associate an elastic IP address with an instance, its current public IP address is released to the
Amazon EC2 public IP address pool. If you disassociate an elastic IP address from the instance, the
instance is automatically assigned a new public IP address within five to ten minutes.

Network Security
The Amazon EC2 service allows you to dynamically add and remove instances. However, this flexibility
can complicate firewall configuration and maintenance which traditionally relies on IP addresses, subnet
ranges or DNS host names as the basis for the firewall rules.

The Amazon EC2 firewall allows you to assign your instances to user-defined groups and define
firewall rules for these groups. As instances are added or removed, the appropriate rules are enforced.
Similarly, if you change a rule for a group, the changes are automatically applied to all members of the
group.

Concepts
Security Groups
A security group is a named collection of access rules. These access rules specify which ingress (i.e.,
incoming) network traffic should be delivered to your instance. All other ingress traffic will be
discarded.

You can modify rules for a group at any time. The new rules are automatically enforced for all running
instances and instances launched in the future.

Note

You can create up to 100 security groups.

Group Membership
When you launch an AMI instance, you can assign it to as many groups as you like.

If no groups are specified, the instance is assigned to the default group. By default, this group allows
all network traffic from other members of this group and discards traffic from other IP addresses and
groups. If this does not meet your needs, you can modify the rule settings of the default group.

Group Access Rights

The access rules define source based access either for named security groups or for IP addresses (i.e.,
CIDR-based rules). For CIDR-based rules, you can also specify the protocol and port range (or ICMP
type/code).

Examples
This section provides two examples of how to use the Amazon EC2 firewall.

API Version 2008-02-01

57
 Amazon Elastic Compute Cloud Developer Guide
Examples

Note

These examples use the Command Line Tools Reference. You can achieve the same
results using the Using the SOAP API.

Default Group
This example shows Albert modifying the default group to meet his security needs.

1. Albert launches a copy of his favorite public AMI:

$ ec2-run-instances ami-eca54085
RESERVATION r-a034c7c9 924417782495 default
INSTANCE i-cfd732a6 ami-eca54085 pending 0 m1.small
2007-07-11T16:40:44+0000 us-east-1c

2. After a little wait for image launch to complete. Albert, who is a cautious type, checks the access
rules of the default group:
$ ec2-describe-group default
GROUP 598916040194 default default group
PERMISSION default ALLOWS all FROM USER 598916040194 GRPNAME de
fault

Albert notices that it only accepts ingress network connections from other members of the default
group for all protocols and ports.
3. Albert, being paranoid as well as cautious, port scans his instance:
$ nmap -P0 -p1-100 ec2-67-202-51-105.compute-1.amazonaws.com
Starting nmap 3.81 ( http://www.insecure.org/nmap/ ) at 2006-08-07 15:42
SAST
All 100 scanned ports on ec2-67-202-51-105.compute-1.amazonaws.com
(67.202.51.105) are: filtered
Nmap finished: 1 IP address (1 host up) scanned in 31.008 seconds

4. Albert decides he should be able to SSH into his instance, but only from his own machine:
$ ec2-authorize default -P tcp -p 22 -s 192.168.1.130/32
GROUP default
PERMISSION default ALLOWS tcp 22 22 FROM CIDR 192.168.1.130/32

5. Albert repeats the port scan:

$ nmap -P0 -p1-100 ec2-67-202-51-105.compute-1.amazonaws.com
Starting nmap 3.81 ( http://www.insecure.org/nmap/ ) at 2006-08-07 15:43
SAST
Interesting ports on ec2-67-202-51-105.compute-1.amazonaws.com
(67.202.51.105):
(The 99 ports scanned but not shown below are in state: filtered)
PORT STATE SERVICE
22/tcp open ssh
Nmap finished: 1 IP address (1 host up) scanned in 32.705 seconds

Albert is happy (or at least less paranoid).

Three-Tier Web Service

API Version 2008-02-01

58
 Amazon Elastic Compute Cloud Developer Guide
Examples

Mary wants to deploy her public, failure resilient, three-tier web service in Amazon EC2. Her grand plan
is to have her web tier start off executing in seven instances of ami-fba54092, her application tier
executing in twenty instances of ami-e3a5408a, and her multi-master database in two instances of
ami-f1a54098. She's concerned about the security of her subscriber database, so she wants to restrict
network access to her middle and back tier machines. When the traffic to her site increases over the
holiday shopping period, she adds additional instances to her web and application tiers to handle the
extra load.

1. First, Mary creates a group for her Apache web server instances and allows HTTP access to the
world.
$ ec2-add-group apache -d "Mary's Apache group"
GROUP apache Mary's Apache group
$ ec2-describe-group apache
GROUP 598916040194 apache Mary's Apache group
$ ec2-authorize apache -P tcp -p 80 -s 0.0.0.0/0
GROUP apache
PERMISSION apache ALLOWS tcp 80 80 FROM CIDR 0.0.0.0/0
$ ec2-describe-group apache
GROUP 598916040194 apache Mary's Apache group
PERMISSION 598916040194 apache ALLOWS tcp 80 80 FROM CIDR
0.0.0.0/0

2. Mary launches seven instances of her web server AMI as members of the apache group:
$ ec2run ami-fba54092 -n 7 -g apache
RESERVATION r-0592776c 598916040194 default
INSTANCE i-cfd732a6 ami-fba54092 pending 0 m1.small
2007-07-11T16:40:44+0000 us-east-1c
INSTANCE i-cfd732a7 ami-fba54092 pending 0 m1.small
2007-07-11T16:40:44+0000 us-east-1c
INSTANCE i-cfd732a8 ami-fba54092 pending 0 m1.small
2007-07-11T16:40:44+0000 us-east-1c
INSTANCE i-cfd732a9 ami-fba54092 pending 0 m1.small
2007-07-11T16:40:44+0000 us-east-1c
INSTANCE i-cfd732aa ami-fba54092 pending 0 m1.small
2007-07-11T16:40:44+0000 us-east-1c
INSTANCE i-cfd732ab ami-fba54092 pending 0 m1.small
2007-07-11T16:40:44+0000 us-east-1c
INSTANCE i-cfd732ac ami-fba54092 pending 0 m1.small
2007-07-11T16:40:44+0000 us-east-1c

$ ec2din i-cfd732a6
RESERVATION r-0592776c 598916040194
INSTANCE i-cfd732a6 ami-fba54092
ec2-67-202-51-245.compute-1.amazonaws.com running 0
m1.small 2007-07-11T16:40:44+0000

3. Being as paranoid as Albert, Mary does a port scan to confirm the permissions she just configured:
$ nmap -P0 -p1-100 ec2-67-202-51-245.compute-1.amazonaws.com
Starting nmap 3.81 ( http://www.insecure.org/nmap/ ) at 2006-08-07 16:21
SAST
Interesting ports on ec2-67-202-51-245.compute-1.amazonaws.com
(67.202.51.245):
(The 99 ports scanned but not shown below are in state: filtered)
PORT STATE SERVICE
80/tcp open http
Nmap finished: 1 IP address (1 host up) scanned in 33.409 seconds

4. Mary verifies her web server can be reached:

API Version 2008-02-01

59
 Amazon Elastic Compute Cloud Developer Guide
Notes

$ telnet ec2-67-202-51-245.compute-1.amazonaws.com 80
Trying 67.202.51.245...
Connected to ec2-67-202-51-245.compute-1.amazonaws.com (67.202.51.245).
Escape character is '^]'.

Mary can reach her web server.

5. Mary creates a separate group for her application server:
$ ec2-add-group appserver -d "Mary's app server"
GROUP appserver Mary's app server

6. Mary starts twenty instances as members of appserver group:

$ ec2run ami-e3a5408a -n 20 -g appserver

7. Mary grants network access between her web server group and the application server group:
$ ec2-authorize appserver -o apache -u 495219933132
GROUP appserver
PERMISSION appserver ALLOWS all FROM USER 495219933132 GRPNAME
apache

8. Mary verifies access to her app server is restricted by port scanning one of the application servers:
$ nmap -P0 -p1-100 ec2-67-202-51-162.compute-1.amazonaws.com
Starting nmap 3.81 ( http://www.insecure.org/nmap/ ) at 2006-08-07 15:42
SAST
All 100 scanned ports on ec2-67-202-51-162.compute-1.amazonaws.com
(67.202.51.162) are: filtered
Nmap finished: 1 IP address (1 host up) scanned in 31.008 seconds

9. Mary confirms that her web servers have access to her application servers:
a. She (temporarily) grants SSH access from her workstation to the web server group:
$ ec2-authorize apache -P tcp -p 22 -s 192.168.1.130/32

b. She logs in to one of her web servers and connects to an application server on TCP port 8080:
$ telnet ec2-67-202-51-162.compute-1.amazonaws.com 8080
Trying 67.202.51.162...
Connected to ec2-67-202-51-162.compute-1.amazonaws.com (67.202.51.162).
Escape character is '^]'

c. Satisfied with the setup, she revokes SSH access to the web server group:
$ ec2-revoke apache -P tcp -p 22 -s 192.168.1.130/32

10.Mary repeats these steps to create the database server group and to grant access between the
application server and database server groups.

Notes
• Defining firewall rules in terms of groups is flexible enough to allow you to implement functionality
equivalent to a VLAN.
• In addition to the distributed firewall, you can maintain your own firewall on any of your instances.
This can be useful if you have specific requirements not met by the Amazon EC2 distributed firewall.

API Version 2008-02-01

60
 Amazon Elastic Compute Cloud Developer Guide
Using the SOAP API

Using the APIs

Topics

• Using the SOAP API

• Using the Query API

This section provides an overview of the SOAP and Query APIs.

Using the SOAP API

Topics

• WSDL and Schema Definitions

• Programming Language Support in Amazon EC2
• Request Authentication
• The Response Structure
• Web Services References

WSDL and Schema Definitions

The Amazon EC2 web service can be accessed using the SOAP web services messaging protocol. This
interface is described by a Web Services Description Language (WSDL) document which defines the
operations and security model for the service. The WSDL references an XML Schema document which
strictly defines the data types that might appear in SOAP requests and responses. For more information
on WSDL and SOAP, see Web Services References.

All schemas have a version number (the latest is 2008-02-01). The version number appears in the URL
of a schema file, and in a schema's target namespace. This makes upgrading easy by differentiating
requests based on the version number.

Note

API Version 2008-02-01

61
 Amazon Elastic Compute Cloud Developer Guide
Programming Language Support in Amazon EC2

In addition to the latest version, the service will support the older versions for some time,
allowing customers plenty of time to upgrade.

The Amazon EC2 services API WSDL is available from the web at
'http://ec2.amazonaws.com/doc/<version>/ec2.wsdl' where version is the version of the API. At the time
this document was released, the current API version was 2008-02-01, which is available at
http://ec2.amazonaws.com/doc/2008-02-01/AmazonEC2.wsdl

Programming Language Support in Amazon EC2

Since the SOAP requests and responses in the Amazon EC2 Web Service follow current standards, any
programming language with the appropriate library support can be used. Languages known to have this
support include C++, C#, Java, Perl, Python and Ruby.

Request Authentication
The Amazon EC2 web service complies with the current WS-Security standard, requiring SOAP request
messages to be hashed and signed for integrity and non-repudiation. WS-Security defines profiles which
are used to implement various levels of security. Amazon EC2 secure SOAP messages use the
BinarySecurityToken profile, consisting of an X.509 certificate with an RSA public key.

The following is the content of an insecure RunInstances operation:

<RunInstances xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instancesSet>
<item>
<imageId>ami-60a54009</imageId>
<minCount>1</minCount>
<maxCount>3</maxCount>
</item>
</instancesSet>
<groupSet/>
</RunInstances>

To secure the request, we add the BinarySecurityToken element. The Java libraries we supply rely on
the Apache Axis project for XML security, canonicalization, and SOAP support. The Sun Java Web
Service Developer's Pack supplies libraries of equivalent functionality.

The secure version of the request begins with the following:

<SOAP-ENV:Envelope xm
lns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header>
<wsse:Security xm
lns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd">
<wsse:BinarySecurityToken
xm
lns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-u
tility-1.0.xsd"
Encoding
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-se
curity-1.0#Base64Binary"
ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token
-profile-1.0#X509v3"
wsu:Id="CertId-1064304">....many, many lines of base64 encoded
X.509 certificate...</wsse:BinarySecurityToken>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>

API Version 2008-02-01

62
 Amazon Elastic Compute Cloud Developer Guide
The Response Structure

<ds:CanonicalizationMethod Al
gorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod
>
<ds:SignatureMethod Al
gorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
<ds:Reference URI="#id-17984263">
<ds:Transforms>
<ds:Transform Al
gorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Al
gorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
<ds:DigestValue>0pjZ1+TvgPf6uG7o+Yp3l2YdGZ4=</ds:DigestValue>
</ds:Reference>
<ds:Reference URI="#id-15778003">
<ds:Transforms>
<ds:Transform Al
gorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Al
gorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
<ds:DigestValue>HhRbxBBmc2OO348f8nLNZyo4AOM=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>bmVx24Qom4kd9QQtclxWIlgLk4QsQBPaKESi79x479xgbO9PEStXMiHZuB
Ai9luuKdNTcfQ8UE/d
jjHKZKEQR
COlLVy0Dn5ZL1RlMHsv+OzJzzvIJFTq3LQKNrzJzsNe</ds:SignatureValue>
<ds:KeyInfo Id="KeyId-17007273">
<wsse:SecurityTokenReference
xm
lns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-u
tility-1.0.xsd" wsu:Id="STRId-22438818">
<wsse:Reference URI="#CertId-1064304"
ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token
-profile-1.0#X509v3">
</wsse:Reference>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>
<wsu:Timestamp
xm
lns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-u
tility-1.0.xsd" wsu:Id="id-17984263">
<wsu:Created>2006-06-09T10:57:35Z</wsu:Created>
<wsu:Expires>2006-06-09T11:02:35Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</SOAP-ENV:Header>

If you are matching this against requests generated by Amazon EC2 supplied libraries, or those of
another vendor, the following are the most important elements:

Elements

• BinarySecurityToken—Contains the X.509 certficiate in base64 encoded PEM format.

• Signature—Contains an XML digital signature created using the canonicalization, signature
algorithm, and digest method.
• Timestamp—Requests to Amazon EC2 are valid within 5 minutes of this value. This helps prevent
replay attacks.

The Response Structure

In response to a request, the Amazon EC2 web service returns an XML data structure that conforms to

API Version 2008-02-01

63
 Amazon Elastic Compute Cloud Developer Guide
Web Services References

an XML schema defined as part of the Amazon EC2 WSDL. The structure of a XML response is
specific to the associated request. In general, the response data types are named according to the
operation performed and whether the data type is a container (can have children). Examples of
containers include groupSet for security groups and instancesSet for instances. Item elements are
children of containers and their contents vary according to the container's role.

An example response is:

<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<reservationId>r-47a5402e</reservationId>
<ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
<groupSet>
<item>
<groupId>default</groupId>
</item>
</groupSet>
<instancesSet>
<item>
<instanceId>i-2ba64342</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<dnsName></dnsName>
</item>
<item>
<instanceId>i-2bc64242</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<dnsName>ec2-67-202-51-176.compute-1.amazonaws.com </dnsName>
</item>
<item>
<instanceId>i-2be64332</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<dnsName>ec2-67-202-51-122.compute-1.amazonaws.com</dnsName>
<keyName>example-key-name</keyName>
<instanceType>m1.small</instanceType>
<launchTime>2007-08-07T11:54:42.000Z</launchTime>
</item>
</instancesSet>
</RunInstancesResponse>

Web Services References

• Web Service Description Language (WSDL)
• WS-Security BinarySecurityToken Profile

Using the Query API

Topics

• Query Parameters

API Version 2008-02-01

64
 Amazon Elastic Compute Cloud Developer Guide
Query Parameters

• Query API Authentication

• Example Request

HTTP Query-based requests are HTTP requests that use the HTTP verb GET or POST and a Query
parameter named Action or Operation. Action is used throughout this documentation, although
Operation is supported for backward compatibility with other AWS Query APIs.

Query Parameters
Each Query request must include some common parameters to handle authentication and selection of an
action. For more information, see Common Query Parameters.

Some operations take lists of parameters. These lists are specified using the param.n notation. Values
of n are integers starting from 1.

Query API Authentication

Every request to Amazon EC2 must contain a request signature. A request signature is calculated by
constructing a string and then calculating an RFC 2104-compliant HMAC-SHA1 hash, using the Secret
AWS Access Key as the key. For more information, see http://-www.faqs.org/-rfcs/-rfc2104.html.

The following are the basic steps used to authenticate requests to AWS. This assumes the developer is
registered with AWS and has an Access Key ID and Secret Access Key.

Query Authentication

1 The sender constructs a request to AWS.

2 The sender calculates the request signature, a Keyed-Hashing for Message Authentication
Code (HMAC) with a SHA-1 hash function, as defined in the next section of this topic.
3 The sender of the request sends the request data, the signature, and Access Key ID (the
key-identifier of the Secret Access Key used) to AWS.
4 AWS uses the Access Key ID to look up the Secret Access Key.
5 AWS generates a signature from the request data and the Secret Access Key using the
same algorithm used to calculate the signature in the request.
6 If the signatures match, the request is considered to be authentic. If the comparison fails,
the request is discarded, and AWS returns an error response.

Note

If a request contains a Timestamp parameter, the signature calculated for the request
expires 15 minutes its value. If a request contains an Expires parameter, the signature
expires at the time specified by the Expires parameter.

To calculate the request signature

1. Based on the API (Query/SOAP/REST) you are using, construct a string.

API Version 2008-02-01

65
 Amazon Elastic Compute Cloud Developer Guide
Query API Authentication

a. Sort the query parameters (not URL-encoded) without using case-sensitively.

b. Concatenate the parameter names and values without the initial ? or the separating & and =
characters.

2. Compute an RFC 2104 compliant HMAC using the Secret AWS Access Key as the "key".
3. Convert the value to base64.
4. Include the value as the value of the Signature parameter in the request.

For example, below is a Query string (linebreaks added for clarity):

?Action=DescribeImages
&AWSAccessKeyId=10QMXFEV71ZS32XQFTR2
&SignatureVersion=1
&Timestamp=2006-12-08T07%3A48%3A03Z
&Version=2007-01-03

For the above Query string, you would calculate the HMAC signature over the following string:
ActionDescribeImagesAWSAccessKey
Id10QMXFEV71ZS32XQFTR2SignatureVersion1Timestamp2006-12-08T07:48:03ZVersion20
07-01-03

Using the string above and the secret key DMADSSfPfdaDjbK+RRUhS/aDrjsiZadgAUm8gRU2 the
base64 encoded signature is as follows:
GjH3941IBe6qsgQu+k7FpCJjpnc=

The following is a Java code sample to compute the signature from the string and the private key.

import java.security.SignatureException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class HmacExample
{
private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";
/**
* Computes RFC 2104-compliant HMAC signature.
*
* @param data
* The data to be signed.
* @param key
* The signing key.
* @return
* The base64-encoded RFC 2104-compliant HMAC signature.
* @throws
* java.security.SignatureException when signature generation fails
*/
public static String calculateRFC2104HMAC(String data, String key)
throws java.security.SignatureException
{
String result;
try {
// get an hmac_sha1 key from the raw key bytes
SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(),
HMAC_SHA1_ALGORITHM);

API Version 2008-02-01

66
 Amazon Elastic Compute Cloud Developer Guide
Example Request

// get an hmac_sha1 Mac instance and initialize with the signing

key
Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
mac.init(signingKey);
// compute the hmac on input data bytes
byte[] rawHmac = mac.doFinal(data.getBytes());
// base64-encode the hmac
result = Base64.encodeBytes(rawHmac);
}
catch (Exception e) {
throw new SignatureException("Failed to generate HMAC : " +
e.getMessage());
}
return result;
}
}

Note

You must import a base 64 encoder to perform the last step above.

Example Request
Here is a complete example request, including all required parameters:
?AWSAccessKeyId=10QMXFEV71ZS32XQFTR2&Action=DescribeImages&SignatureVersion=1
&Timestamp=2006-12-08T07%3A48%3A03Z&Version=2007-01-03&Signature=69DSJs1z%2B0
wWJmdB77%2BLm0N0Trs%3D

API Version 2008-02-01

67
 Amazon Elastic Compute Cloud Developer Guide
API Conventions

API Reference

Topics

• API Conventions
• API Versioning
• API Error Codes
• Common Data Types
• Amazon EC2 SOAP API
• Amazon EC2 Query API

Amazon EC2 provides two APIs: Using the SOAP API and Using the Query API, which allow you to
launch and control instances from your own applications.

This section discusses the operations available in the Amazon EC2 APIs, their semantics, and their
required parameters. Examples of requests and responses are also provided.

Note

The same XML body is returned in both the Query API and SOAP API.

Before using the API, we recommend that you familiarize yourself with their API Conventions.

API Conventions
Overview
This section describes Amazon EC2 API conventions.

Actions
Actions encapsulate the possible interactions with Amazon EC2. These can be viewed as remote
procedure calls and consist of a request and response message pair. Requests must be signed, allowing

API Version 2008-02-01

68
 Amazon Elastic Compute Cloud Developer Guide
Data Types and the Amazon EC2 WSDL

Amazon EC2 to Request Authentication. For clarity, the sample requests and responses illustrating each
of the operations described in this reference are not signed.

Data Types and the Amazon EC2 WSDL

The current version of the Amazon EC2 WSDL is available at:
http://ec2.amazonaws.com/doc/2008-02-01/AmazonEC2.wsdl. Some libraries can generate code directly
from the WSDL. Other libraries require a little more work on your part.

Values provided as parameters to the various operations must be of the indicated type. Standard XSD
types (like string, boolean, int) are prefixed with xsd:. Complex types defined by the
Amazon EC2 WSDL are prefixed with ec2:.

Parameters that consist of lists of information are defined within our WSDL to require <info> tags
around each member. Throughout the API, type references for parameters that accept such a list of
values are specified using the notation type[] The type referred to in these instances is the type nested
within the <info> tag (for Amazon EC2 types this is defined in the WSDL).

For example, the <imagesSet> element in the following XML snippet is of type xsd:string[]:

<imagesSet>
<item>
<imageId>ami-61a54008</imageId>
</item>
<item>
<imageId>ami-61b54608</imageId>
</item>
</imagesSet>

And the <instancesSet> element in the following XML snippet is of type xsd:string[]:

<instancesSet>
<item>
<imageId>ami-60a54009</imageId>
<minCount>10</minCount>
<maxCount>30</maxCount>
</item>
<item>
<imageId>ami-60b54209</imageId>
<minCount>5</minCount>
<maxCount>20</maxCount>
</item>
</instancesSet>

API Versioning
Because features and changes can introduce incompatible API changes, all Amazon EC2 API updates
are versioned. By including a version in the request, clients receive responses they can process.

Each API revision is assigned a version in date form (the current API version is 2008-02-01). This
version is included in the request as part of the document namespace when using our SOAP API and as
a Version parameter when using our Query API. The response that Amazon EC2 returns honors the
version included in the request.

SOAP clients that retrieve the Amazon EC2 WSDL at runtime and generate their requests dynamically
using that WSDL should reference the WSDL for the version of the API that the client was developed
against. This ensures that the client software continues to work even if backwards incompatible API

API Version 2008-02-01

69
 Amazon Elastic Compute Cloud Developer Guide
API Error Codes

changes are introduced. The WSDL for each supported API version is available from the following URI:

http://ec2.amazonaws.com/doc/<api-version>/AmazonEC2.wsdl

The WSDL for latest version of our API is available from the following URI:

http://ec2.amazonaws.com/doc/AmazonEC2.wsdl

Note

The WSDL should be treated as a moving target as it will always map to the latest release
of the Amazon EC2 SOAP API. If your software depends on retrieving the WSDL at
runtime, we strongly recommend you reference the specific version of the WSDL you are
developing against.

API Error Codes

Overview
There are two types of error codes: client and server.

Client error codes suggest that the error was caused by something the client did, such as an
authentication failure or an invalid AMI identifier. In the SOAP API, These error codes are prefixed
with Client. For example: Client.AuthFailure. In the Query API, these errors are accompanied
by a 400-series HTTP response code.

Server error codes suggest a server-side issue caused the error and should be reported. In the SOAP API,
these error codes are prefixed with Server. For example: Server.Unavailable. In the Query API,
these errors are accompanied by a 500-series HTTP response code.

Summary of Client Error Codes

Error Code Description Notes
AddressLimitExceeded User has the maximum Each user has an IP address
number of allowed IP limit. For new users, this
addresses. limit is 5. If you need more
than 5 Elastic IP addresses,
please complete the
Amazon EC2 Elastic IP
Address Request Form. We
will ask you to think
through your use case and
help us understand your
need for additional
addresses.
AuthFailure User not authorized. You might be trying to run
an AMI for which you do
not have permission.
InvalidManifest Specified AMI has an
unparsable Manifest.
InvalidAMIID.Malformed Specified AMI ID is not

API Version 2008-02-01

70
 Amazon Elastic Compute Cloud Developer Guide
Summary of Client Error Codes

Error Code Description Notes

valid.
InvalidAMIID.NotFound Specified AMI ID does not
exist.
InvalidAMIID.Unavailable Specified AMI ID has been
deregistered and is no
longer available.
InvalidInstanceID.Malformed Specified instance ID is not
valid.
InvalidInstanceID.NotFound Specified instance ID does
not exist.
InvalidKeyPair.NotFound Specified key pair name
does not exist.
InvalidKeyPair.Duplicate Attempt to create a
duplicate key pair.
InvalidGroup.NotFound Specified group name does
not exist.
InvalidGroup.Duplicate Attempt to create a
duplicate group.
InvalidGroup.InUse Specified group cannot be
deleted because it is in use.
InvalidGroup.Reserved Specified group name is a
reserved name.
InvalidParameterValue The value supplied for a Requests that could cause
parameter was invalid. this error include (for
example) supplying an
invalid image attribute to
the
DescribeImageAttribute
request or an invalid
version or encoding
value for the userData in
a RunInstances request.
InvalidPermission.Duplicate Attempt to authorize a
permission that has already
been authorized.
InvalidPermission.Malformed Specified permission is
invalid.
InvalidReservationID.Malformed Specified reservation ID is
invalid.
InvalidReservationID.NotFound Specified reservation ID
does not exist.
InstanceLimitExceeded User has max allowed Each user has a concurrent
concurrent running running instance limit. For
instances. new users, this limit is 20.
API Version 2008-02-01
71
 Amazon Elastic Compute Cloud Developer Guide
Summary of Server Error Codes

Error Code Description Notes

If you need more than 20
instances, please complete
the Amazon EC2 Instance
Request Form and your
request will be considered.
InvalidParameterCombination RunInstances was called
with minCount and
maxCount set to 0 or
minCount > maxCount.
InvalidUserID.Malformed The user ID is neither in
the form of an AWS
account ID or one of the
special values accepted by
the owner or
executableBy flags in the
DescribeImages call.
InvalidAMIAttributeItemValue The value of an item added If you are specifying a
to, or removed from, an userId, check that it is in
image attribute is invalid. the form of an AWS
account ID.
UnknownParameter An unknown or Requests that could cause
unrecognized parameter this error include supplying
was supplied. a misspelled parameter or a
parameter that is not
supported for the specified
API version.

Summary of Server Error Codes

Error Code Description Notes
InternalError Internal Error. This error should not
occur. If it does, please
try to reproduce it and
let us know by posting
a message on the AWS
forums.
InsufficientAddressCapacity Not enough available addresses to Reduce the number of
satisfy your minimum request. addresses you are
requesting or wait for
additional capacity to
become available.
InsufficientInstanceCapacity Not enough available instances to Reduce the number of
satisfy your minimum request. instances in your
request or wait for
additional capacity to
become available.
Unavailable The server is overloaded and cannot

API Version 2008-02-01

72
 Amazon Elastic Compute Cloud Developer Guide
Common Data Types

Error Code Description Notes

handle the request.

Common Data Types

The Amazon EC2 API contains several data types that various operations use. This section describes
each data type in detail.

Since both the Query and SOAP APIs return the same XML body, the data types described in the
WSDL are used in both.

AvailabilityZoneItemType
The AvailabilityZoneItemType data type.

Relevant Operations
Operations that use this data type include:

• DescribeAvailabilityZones

Contents
The following table describes the elements contained in AvailabilityZoneItemType.

Name Description
zoneName Name of the Availability Zone.
Type: xsd:string

zoneState State of the Availability Zone.

Type: xsd:string

BlockDeviceMappingItemType
The BlockDeviceMappingItemType data type.

Relevant Operations
Operations that use this data type include:

• DescribeImageAttribute
• RunInstances

Contents
The following table describes the elements contained in BlockDeviceMappingItemType.

API Version 2008-02-01

73
 Amazon Elastic Compute Cloud Developer Guide
DescribeImagesResponseItemType

Name Description
virtualName Virtual name assigned to the device.
Type: xsd:string

deviceName Name of the device within Amazon EC2.

Type: xsd:string

DescribeImagesResponseItemType
The DescribeImagesResponseItemType data type.

Relevant Operations
Operations that use this data type include:

• DescribeImages

Contents
The following table describes the elements contained in DescribeImagesResponseItemType.

Name Description
imageId Unique ID of the AMI described.
Type: xsd:string

imageState Current state of the AMI.

If the operation returns available, the image is
successfully registered and available for launching
If the operation returns deregistered, the image is
deregistered and no longer available for launching. For more
information, see DeregisterImage.
Type: xsd:string

imageOwnerId AWS Access Key ID of the image owner.

Type: xsd:string

isPublic Returns true if this image has public launch permissions.

Returns false if it only has implicit and explicit launch
permissions.
Type: xsd:boolean

productCodes Product codes associated with this image.

Type: ProductCodeItemType[]

architecture The architecture of the image (i386 or x86_64).

Type: xsd:string

imageType The type of image (machine, kernel, or ramdisk).

Type: xsd:string
API Version 2008-02-01
74
 Amazon Elastic Compute Cloud Developer Guide
DescribeKeyPairsResponseItemType

Name Description

kernelId The kernel associated with the image, if any. Only

applicable for machine images.
Type: xsd:string

ramdiskId The ramdisk associated with the image, if any. Only

applicable for machine images.
Type: xsd:string

DescribeKeyPairsResponseItemType
The DescribeKeyPairsResponseItemType data type.

Relevant Operations
Operations that use this data type include:

• DeleteKeyPair
• DescribeKeyPairs

Contents
The following table describes the elements contained in DescribeKeyPairsResponseItemType.

Name Description
keyName The user supplied name for this key pair.
Type: xsd:string

keyFingerprint A fingerprint for the private key of this key pair. This is
computed as the SHA-1 digest of the DER encoded form of
the private key.
Type: xsd:string

EmptyElementType
The EmptyElementType data type.

Relevant Operations
Operations that use this data type include:

• ResetImageAttribute
• DescribeImageAttribute

Contents
API Version 2008-02-01
75
 Amazon Elastic Compute Cloud Developer Guide
GroupSetType

The empty element has no contents.

GroupSetType
The GroupSetType data type.

Relevant Operations
Operations that use this data type include:

• RunInstances

Contents
The following table describes the elements contained in GroupSetType.

Name Description
groupId Name of a security group.
Type: xsd:string

InstanceStateType
The InstanceStateTypedata type.

Relevant Operations
Operations that use this data type include:

• RunInstances
• DescribeInstances
• TerminateInstances

Contents
The following table describes the elements contained in InstanceStateType.

Name Description
code A 16-bit unsigned integer. The high byte is an opaque
internal value and should be ignored. The low byte is set
based on the state represented:

• 0: pending
• 16: running
• 32: shutting-down
• 48: terminated

Type: xsd:int

API Version 2008-02-01

76
 Amazon Elastic Compute Cloud Developer Guide
IpPermissionType

Name Description

state The current state of the instance.

• pending: the instance is in the process of being launched

• running: the instance launched (although the boot
process might not be completed)
• shutting-down: the instance started shutting down
• terminated: the instance terminated

Type: xsd:string

IpPermissionType
The IpPermissionType data type.

Relevant Operations
Operations that use this data type include:

• AuthorizeSecurityGroupIngress
• DescribeSecurityGroups
• RevokeSecurityGroupIngress

Contents
The following table describes the elements contained in IpPermissionType.

Name Description
ipProtocol IP protocol.
Type: xsd:string

fromPort Start of port range for the TCP and UDP protocols, or an
ICMP type number. An ICMP type number of -1 indicates a
wildcard (i.e., any ICMP type number).
Type: xsd:int

toPort End of port range for the TCP and UDP protocols, or an
ICMP code. An ICMP code of -1 indicates a wildcard (i.e.,
any ICMP code).
Type: xsd:int

groups List of security group and user ID pairs.

Type: UserIdGroupPairType[]

ipRanges List of CIDR IP range specifications.

Type: xsd:string

API Version 2008-02-01

77
 Amazon Elastic Compute Cloud Developer Guide
LaunchPermissionOperationType

LaunchPermissionItemType
The LaunchPermissionItemType data type.

Relevant Operations
Operations that use this data type include:

• ModifyImageAttribute
• DescribeImageAttribute

Contents
The following table describes the elements contained in LaunchPermissionItemType.

Name Description Required

group A launch permission for a group. Choice between group and
Currently only all is supported, which userId
gives public launch permissions.
Type: xsd:string

userId A launch permission for a user. userId is Choice between group and
an AWS account ID. userId
Type: xsd:string

LaunchPermissionOperationType
The LaunchPermissionOperationType data type.

Relevant Operations
Operations that use this data type include:

• ModifyImageAttribute

Contents
The following table describes the elements contained in LaunchPermissionOperationType.

Name Description Required

add Adds launch permissions. Choice between add and
Type: LaunchPermissionItemType[] remove

remove Removes launch permissions. Choice between add and

Type: LaunchPermissionItemType[] remove

API Version 2008-02-01

78
 Amazon Elastic Compute Cloud Developer Guide
PlacementResponseType

PlacementRequestType
The PlacementRequestType data type.

Relevant Operations
Operations that use this data type include:

• RunInstances

Contents
The following table describes the elements contained in PlacementRequestType.

Name Description
availabilityZone The availability zone in which to launch the instance(s).
Type: xsd:string

PlacementResponseType
The PlacementResponseType data type.

Relevant Operations
Operations that use this data type include:

• DescribeInstances

Contents
The following table describes the elements contained in PlacementResponseType.

Name Description
availabilityZone The availability zone in which to launch the instance(s).
Type: xsd:string

ProductCodeItemType
The ProductCodeItemType data type.

Relevant Operations
Operations that use this data type include:

• ModifyImageAttribute
• DescribeImageAttribute

API Version 2008-02-01

79
 Amazon Elastic Compute Cloud Developer Guide
ProductInstanceResponseItemType

Contents
The following table describes the elements contained in ProductCodeItemType.

Name Description Required

productCode A product code. Yes
Type: xsd:string

ProductInstanceResponseItemType
The ProductInstanceResponseItemType data type.

Relevant Operations
Operations that use this data type include:

• ConfirmProductInstance

Contents
The following table describes the elements contained in ProductInstanceResponseItemType.

Name Description
productCode The product code attached to the instance that matches one
of the product codes in the ConfirmProductInstance request.
Type: xsd:string

instanceId Unique ID of the instance.

Type: xsd:string

ownerId The account ID of the owner of the instance.

Type: xsd:string

ReservationInfoType
The ReservationInfoType data type.

Relevant Operations
Operations that use this data type include:

• RunInstances
• DescribeInstances

Contents

API Version 2008-02-01

80
 Amazon Elastic Compute Cloud Developer Guide
RunningInstancesItemType

The following table describes the elements contained in ReservationInfoType.

Name Description
reservationId Unique ID of the reservation described.
Type: xsd:string

ownerId AWS Access Key ID of the user who owns the reservation.
Type: xsd:string

groupSet Set of security groups these instances were launched in.

Type: GroupSetType[]

instancesSet Information about instances started.

Type: RunningInstancesItemType[]

RunningInstancesItemType
The RunningInstancesItemType data type.

Relevant Operations
Operations that use this data type include:

• RunInstances
• DescribeInstances

Contents
The following table describes the elements contained in RunningInstancesItemType.

Name Description
amiLaunchIndex Optional. The AMI launch index, which can be used to find
this instance within the launch group. For more information,
see Instance Metadata.
Type: xsd:string

dnsName The public DNS name assigned to the instance. This DNS
name is contactable from outside the Amazon EC2 network.
This element remains empty until the instance enters a
running state. For more information, see Instance
Addressing and Network Security.
Type: xsd:string

imageId Image ID of the AMI used to launch the instance.

Type: xsd:string

instanceId Unique ID of the instance launched.

Type: xsd:string

API Version 2008-02-01

81
 Amazon Elastic Compute Cloud Developer Guide
SecurityGroupItemType

Name Description
instanceState The current state of the instance.

• pending: the instance is in the process of launching

• running: the instance launched (although it the boot
process might not be complete)
• shutting-down: the instance is shutting down
• terminated: the instance terminated

Type: InstanceStateType

instanceType The instance type. For more information on instance types,

see Instance Types.
Type: xsd:string

keyName Optional. If this instance was launched with an associated

key pair, this displays the key pair name.
Type: xsd:string

launchTime The time the instance launched.

Type: xs:dateTime

placement The location where the instance launched.

Type: PlacementResponseType

privateDnsName The private DNS name assigned to the instance. This DNS
name can only be used inside the Amazon EC2 network.
This element remains empty until the instance enters a
running state. For more information, see Instance
Addressing and Network Security.
Type: xsd:string

productCodes Optional. Product codes attached to this instance.

Type: ProductCodeItemType[]

reason Optional. Reason for the most recent state transition. This
might be an empty string.
Type: xsd:string

SecurityGroupItemType
The SecurityGroupItemType data type.

Relevant Operations
Operations that use this data type include:

• DescribeSecurityGroups

API Version 2008-02-01

82
 Amazon Elastic Compute Cloud Developer Guide
TerminateInstancesResponseInfoType

Contents
The following table describes the elements contained in SecurityGroupItemType.

Name Description
ownerId AWS Access Key ID of the owner of the security group.
Type: xsd:string

groupName Name of the security group.

Type: xsd:string

groupDescription Description of the security group.

Type: xsd:string

ipPermissions Set of IP permissions associated with the security group.

Type: IpPermissionType[]

TerminateInstancesResponseInfoType
The TerminateInstancesResponseInfoType data type.

Relevant Operations
Operations that use this data type include:

• TerminateInstances

Contents
The following table describes the elements contained in TerminateInstancesResponseInfoType.

Name Description
instanceId Instance ID returned from previous call to RunInstances
Type: xsd:string

UserDataType
The UserDataType data type.

Relevant Operations
Operations that use this data type include:

• RunInstances

Contents
API Version 2008-02-01
83
 Amazon Elastic Compute Cloud Developer Guide
UserIdGroupPairType

The following table describes the elements contained in UserDataType.

Name Description
data The user data.
Type: xsd:string

Notes

• The version and encoding attributes are required.

• The user data is base64-encoded as described in RFC3548 with the following additional restrictions:
• Implementations MUST NOT add line feeds to encoded data.
• Implementations MUST pad the end of the encoded data with '=' if required.
• Implementations MUST ignore characters in the encoded stream that are not in the encoding
alphabet. This differs from RFC3548, but provides more leeway for clients.
• Implementation MUST use the encoding alphabet in table 1 of RFC3548 (i.e. A-Za-z0-9+/).
• Implementation MUST follow the user data size limit before base64 encoding.

UserIdGroupPairType
The UserIdGroupPairType data type.

Relevant Operations
Operations that use this data type include:

• AuthorizeSecurityGroupIngress
• DescribeSecurityGroups
• RevokeSecurityGroupIngress

Contents
The following table describes the elements contained in UserIdGroupPairType.

Name Description
userId AWS Access Key ID of a user.
Type: xsd:string

groupName Name of a security group.

Type: xsd:string

Amazon EC2 SOAP API

The Amazon EC2 API consists of web service operations for every task the service can perform. This
section describes each operation in detail.

API Version 2008-02-01

84
 Amazon Elastic Compute Cloud Developer Guide
List of Operations by Function

List of Operations by Function

Images

• RegisterImage
• DescribeImages
• DeregisterImage

Instances

• RunInstances
• DescribeInstances
• TerminateInstances
• ConfirmProductInstance

Key Pairs

• CreateKeyPair
• DescribeKeyPairs
• DeleteKeyPair

Image Attributes

• ModifyImageAttribute
• DescribeImageAttribute
• ResetImageAttribute

Security Groups

• CreateSecurityGroup
• DescribeSecurityGroups
• DeleteSecurityGroup
• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress

Elastic IP Addresses

• AllocateAddress
• DescribeAddresses
• ReleaseAddress
• AssociateAddress
• DisassociateAddress

API Version 2008-02-01

85
 Amazon Elastic Compute Cloud Developer Guide
AllocateAddress

Availability Zones

• DescribeAvailabilityZones

AllocateAddress
The AllocateAddress operation acquires an elastic IP address for use with your account.

Request Parameters
The AllocateAddress operation does not have any request parameters.

Response Elements
The following table describes the default response tags included in AllocateAddress responses.

Name Description
publicIp Returned IP address.
Type: xsd:string

Sample Request
<AllocateAddress/>

Sample Response
<AllocateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01/">
<publicIp>67.202.55.255</publicIp>
</AllocateAddressResponse>

Related Operations
• DescribeAddresses
• ReleaseAddress
• AssociateAddress
• DisassociateAddress

AssociateAddress
The AssociateAddress operation associates an elastic IP address with an instance. If the IP address is
currently assigned to another instance, the IP address is assigned to the new instance. This is an
idempotent operation. If you enter it more than once, Amazon EC2 does not return an error.

Request Parameters
The following table describes the request parameters for AssociateAddress. Parameter names are

API Version 2008-02-01

86
 Amazon Elastic Compute Cloud Developer Guide
AuthorizeSecurityGroupIngress

case sensitive.

Name Description Required

instanceId The instance to which the IP address is assigned. Yes
Type: xsd:string

publicIp IP address that you are assigning to the instance. Yes

Type: xsd:string

Response Elements
The following table describes the default response tags included in AssociateAddress responses.

Name Description
return true if the IP address is associated with the instance. Otherwise,
false.
Type: xsd:boolean

Sample Request
<AssociateAddress xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instanceId>i-28a64341</instanceId>
<publicIp>67.202.55.255</publicIp>
</AssociateAddress>

Sample Response
<AssociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</AssociateAddressResponse>

Related Operations
• AllocateAddress
• DescribeAddresses
• ReleaseAddress
• DisassociateAddress

AuthorizeSecurityGroupIngress
The AuthorizeSecurityGroupIngress operation adds permissions to a security group.

Permissions are specified by the IP protocol (TCP, UDP or ICMP), the source of the request (by IP
range or an Amazon EC2 user-group pair), the source and destination port ranges (for TCP and UDP),
and the ICMP codes and types (for ICMP).

Permission changes are propagated to instances within the security group as quickly as possible.

API Version 2008-02-01

87
 Amazon Elastic Compute Cloud Developer Guide
AuthorizeSecurityGroupIngress

However, depending on the number of instances, a small delay might occur.

Request Parameters
The following table describes the request parameters for AuthorizeSecurityGroupIngress.
Parameter names are case sensitive.

Name Description Required

userId AWS Access Key ID. Yes
Type: xsd:string

groupName Name of the group to modify. Yes

Type: xsd:string

ipPermissions Set of permissions to add to the group. Yes

Type: IpPermissionType[]

Response Elements
The following table describes the default response tags included in
AuthorizeSecurityGroupIngress responses.

Name Description
return true if permissions successfully added.
Type: xsd:boolean

Sample Request
<AuthorizeSecurityGroupIngress xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<userId/>
<groupName>WebServers</groupName>
<ipPermissions>
<item>
<ipProtocol>tcp</ipProtocol>
<fromPort>80</fromPort>
<toPort>80</toPort>
<groups/>
<ipRanges>
<item>
<cidrIp>0.0.0.0/0</cidrIp>
</item>
</ipRanges>
</item>
</ipPermissions>
</AuthorizeSecurityGroupIngress>

Sample Response
<AuthorizeSecurityGroupIngressResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>

API Version 2008-02-01

88
 Amazon Elastic Compute Cloud Developer Guide
ConfirmProductInstance

</AuthorizeSecurityGroupIngressResponse>

Related Operations
• CreateSecurityGroup
• DescribeSecurityGroups
• RevokeSecurityGroupIngress
• DeleteSecurityGroup

ConfirmProductInstance
The ConfirmProductInstance operation returns true if the specified product code is attached to the
specified instance. The operation returns false if the product code is not attached to the instance.

The ConfirmProductInstance operation can only be executed by the owner of the AMI. This feature
is useful when an AMI owner is providing support and wants to verify whether a user's instance is
eligible.

Request Parameters
The following table describes the request parameters for ConfirmProductInstance. Parameter
names are case sensitive.

Name Description Required

productCode The product code to confirm. Yes
Type: xsd:string

instanceId The instance for which to confirm the product code. Yes
Type: xsd:string

Response Elements
The following table describes the default response tags included in ConfirmProductInstance
responses.

Name Description
return True if the product code is attached to the instance, false if it is not.
Type: xsd:boolean

ownerId The instance owner's account ID. Only present if the product code
is attached to the instance.
Type: xsd:string

Sample Request
<ConfirmProductInstance

API Version 2008-02-01

89
 Amazon Elastic Compute Cloud Developer Guide
CreateKeyPair

xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<productCode>774F4FF8</productCode>
<instanceId>i-10a64379</instanceId>
</ConfirmProductInstance>

Sample Response
<ConfirmProductInstanceResponse
xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
<ownerId>254933287430</ownerId>
</ConfirmProductInstanceResponse>

Related Operations
• DescribeInstances
• RunInstances

CreateKeyPair
The CreateKeyPair operation creates a new 2048 bit RSA key pair and returns a unique ID that can
be used to reference this key pair when launching new instances. For more information, see
RunInstances.

Request Parameters
The following table describes the request parameters for CreateKeyPair. Parameter names are case
sensitive.

Name Description Required

keyName A unique name for the key pair. Yes
Type: xsd:string

Response Elements
The following table describes the default response tags included in CreateKeyPair responses.

Name Description
keyName The key pair name provided in the original request.
Type: xsd:string

keyFingerprint A SHA-1 digest of the DER encoded private key.

Type: xsd:string

keyMaterial An unencrypted PEM encoded RSA private key.

Type: xsd:string

API Version 2008-02-01

90
 Amazon Elastic Compute Cloud Developer Guide
CreateSecurityGroup

Sample Request
<CreateKeyPair xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<keyName>example-key-name</keyName>
</CreateKeyPair>

Sample Response
<CreateKeyPairResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<keyName>example-key-name</keyName>
<keyFingerprint>1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f</
keyFingerprint>
<keyMaterial>-----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-----</keyMaterial>
</CreateKeyPairResponse>

Related Operations
• DescribeKeyPairs
• DeleteKeyPair
• RunInstances

CreateSecurityGroup
The CreateSecurityGroup operation creates a new security group.

Every instance is launched in a security group. If no security group is specified during launch, the
instances are launched in the default security group. Instances within the same security group have
unrestricted network access to each other. Instances will reject network access attempts from other
instances in a different security group. As the owner of instances you can grant or revoke specific
permissions using the AuthorizeSecurityGroupIngress and RevokeSecurityGroupIngress operations.

Request Parameters
The following table describes the request parameters for CreateSecurityGroup. Parameter names are

API Version 2008-02-01

91
 Amazon Elastic Compute Cloud Developer Guide
DeleteKeyPair

case sensitive.

Name Description Required

groupName Name of the new security group. Yes
Type: xsd:string

groupDescription Description of the new security group. Yes

Type: xsd:string

Response Elements
The following table describes the default response tags included in CreateSecurityGroup responses.

Name Description
return true if call succeeded.
Type: xsd:boolean

Sample Request
<CreateSecurityGroup xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<groupName>WebServers</groupName>
<groupDescription>Web</groupDescription>
</CreateSecurityGroup>

Sample Response
<CreateSecurityGroupResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</CreateSecurityGroupResponse>

Related Operations
• RunInstances
• DescribeSecurityGroups
• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress
• DeleteSecurityGroup

DeleteKeyPair
The DeleteKeyPair operation deletes a key pair.

Request Parameters
The following table describes the request parameters for DeleteKeyPair. Parameter names are case
sensitive.

API Version 2008-02-01

92
 Amazon Elastic Compute Cloud Developer Guide
DeleteSecurityGroup

Name Description Required

keyName Name of the key pair to delete. Yes
Type: xsd:string

Response Elements
The following table describes the default response tags included in DeleteKeyPair responses.

Name Description
return true if the key was successfully deleted.
Type: xsd:boolean

Sample Request
<DeleteKeyPair xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<keyName>example-key-name</keyName>
</DeleteKeyPair>

Sample Response
<DeleteKeyPair xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</DeleteKeyPair>

Related Operations
• CreateKeyPair
• DescribeKeyPairs

DeleteSecurityGroup
The DeleteSecurityGroup operation deletes a security group.

Note

If you attempt to delete a security group that contains instances, a fault is returned.
If you attempt to delete a security group that is referenced by another security group, a
fault is returned. For example, if security group B has a rule that allows access from
security group A, security group A cannot be deleted until the allow rule is removed.

Request Parameters
The following table describes the request parameters for DeleteSecurityGroup. Parameter names are
case sensitive.

API Version 2008-02-01

93
 Amazon Elastic Compute Cloud Developer Guide
DeregisterImage

Name Description Required

groupName Name of the security group to delete. Yes
Type: xsd:string

Response Elements
The following table describes the default response tags included in DeleteSecurityGroup responses.

Name Description
return true if the group is deleted. Otherwise, false.
Type: xsd:boolean

Sample Request
<DeleteSecurityGroup xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<groupName>RangedPortsBySource</groupName>
</DeleteSecurityGroup>

Sample Response
<DeleteSecurityGroupResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</DeleteSecurityGroupResponse>

Related Operations
• CreateSecurityGroup
• DescribeSecurityGroups
• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress

DeregisterImage
The DeregisterImage operation deregisters an AMI. Once deregistered, instances of the AMI can no
longer be launched.

Request Parameters
The following table describes the request parameters for DeregisterImage. Parameter names are case
sensitive.

Name Description Required

imageId Unique ID of the AMI which was assigned during Yes
registration (see RegisterImage). For information on
viewing the IDs of AMIs you own, see DescribeImages.
API Version 2008-02-01
94
 Amazon Elastic Compute Cloud Developer Guide
DescribeAddresses

Name Description Required

Type: xsd:string

Response Elements
The following table describes the default response tags included in DeregisterImage responses.

Name Description
return true if deregistration succeeded; otherwise false.
Type: xsd:boolean

Sample Request
<DeregisterImage xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
</DeregisterImage>

Sample Response
<DeregisterImageResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</DeregisterImageResponse>

Related Operations
• RegisterImage
• DescribeImages

DescribeAddresses
The DescribeAddresses operation lists elastic IP addresses assigned to your account.

Request Parameters
The following table describes the request parameters for DescribeAddresses. Parameter names are
case sensitive.

Name Description Required

publicIpsSet Elastic IP addresses to describe. Yes (but can
Type: xsd:string[] be empty)

Response Elements

API Version 2008-02-01

95
 Amazon Elastic Compute Cloud Developer Guide
DescribeAvailabilityZones

The following table describes the default response tags included in DescribeAddresses responses.

Name Description
publicIp Elastic IP address assigned to your account.
Type: xsd:string

instanceId Instance ID to which the IP address is assigned.

Type: xsd:string

Sample Request
<DescribeAddresses xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<publicIpsSet>
<item>
<publicIp>67.202.55.255</publicIp>
</item>
</publicIpsSet>
</DescribeAddresses>

Sample Response
<DescribeAddressesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instanceId>i-28a64341</instanceId>
<publicIp>67.202.55.255</publicIp>
</DescribeAddressesResponse>

Related Operations
• AllocateAddress
• ReleaseAddress
• AssociateAddress
• DisassociateAddress

DescribeAvailabilityZones
The DescribeAvailabilityZones operation displays availability zones that are currently available
to the account and their states.

Note

Availability zones are not the same across accounts. The availability zone us-east-1a for
account A is not necessarily the same as us-east-1a for account B. Zone assignments are
mapped independently for each account.

Request Parameters
The following table describes the request parameters for DescribeAvailabilityZones. Parameter
names are case sensitive.

API Version 2008-02-01

96
 Amazon Elastic Compute Cloud Developer Guide
DescribeImageAttribute

Name Description Required

zoneName Name of an availability zone. No
Type: xsd:string[]

Response Elements
The following table describes the default response tags included in DescribeAvailabilityZones
responses.

Name Description
availabilityZoneInfo Availability zone information.
Type: AvailabilityZoneItemType[]

Sample Request
<DescribeAvailabilityZones
xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<availabilityZoneSet/>
<DescribeAvailabilityZones>

Sample Response
<DescribeAvailabilityZonesResponse
xmlns="http://ec2.amazonaws.com/doc/2008-02-01/">
<availabilityZoneInfo>
<item>
<zoneName>us-east-1a</zoneName>
<zoneState>available</zoneState>
</item>
<item>
<zoneName>us-east-1b</zoneName>
<zoneState>available</zoneState>
</item>
<item>
<zoneName>us-east-1c</zoneName>
<zoneState>available</zoneState>
</item>
</availabilityZoneInfo>
</DescribeAvailabilityZonesResponse>

Related Operations
• RunInstances

DescribeImageAttribute
The DescribeImageAttribute operation returns information about an attribute of an AMI. Only one
attribute can be specified per call.

Request Parameters

API Version 2008-02-01

97
 Amazon Elastic Compute Cloud Developer Guide
DescribeImageAttribute

The following table describes the request parameters for DescribeImageAttribute. Parameter
names are case sensitive.

Name Description Required

imageId ID of the AMI for which an attribute will be described. Yes
Type: xsd:string

launchPermission Describes launch permissions of the AMI. Choice

Type: EmptyElementType

productCodes Describes the product code associated with the AMI. Choice
Type: EmptyElementType

kernel Describes the ID of the kernel associated with the AMI. No

Type: xsd:string

ramdisk Describes the ID of the RAM disk associated with the No

AMI.
Type: xsd:string

blockDeviceMapping Describes the mapping that defines native device names No

to use when exposing virtual devices.
Type: xsd:string

Response Elements
The following table describes the default response tags included in DescribeImageAttribute
responses.

Name Description
imageId ID of the AMI of which parameters are described.
Type: xsd:string

launchPermission Launch permissions of the AMI. Returned if launchPermission

is specified.
Type: LaunchPermissionItemType[]

productCodes Product codes of the AMI. Returned if productCodes is specified.

Type: ProductCodeItemType[]

kernel ID of the kernel associated with the AMI. Returned if kernel is

specified.
Type: xsd:string

ramdisk ID of the RAM disk associated with the AMI. Returned if ramdisk
is specified.
Type: xsd:string

blockDeviceMapping Mapping that defines native device names to use when exposing
virtual devices. Returned if blockDeviceMapping is specified.

API Version 2008-02-01

98
 Amazon Elastic Compute Cloud Developer Guide
DescribeImages

Name Description
Type: BlockDeviceMappingItemType[]

Sample Request - Launch Permission

<DescribeImageAttribute xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
<launchPermission />
</DescribeImageAttribute>

Sample Response - Launch Permission

<DescribeImageAttributeResponse
xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
<launchPermission>
<item>
<group>all</group>
</item>
<item>
<userId>495219933132</userId>
</item>
</launchPermission>
</DescribeImageAttributeResponse>

Sample Request - Product Codes

<DescribeImageAttribute xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
<productCodes />
</DescribeImageAttribute>

Sample Response - Product Codes

<DescribeImageAttributeResponse
xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
<productCodes>
<item>
<productCode>774F4FF8</productCode>
</item>
</productCodes>
</DescribeImageAttributeResponse>

Related Operations
• DescribeImages
• ModifyImageAttribute
• ResetImageAttribute

API Version 2008-02-01

99
 Amazon Elastic Compute Cloud Developer Guide
DescribeImages

DescribeImages
The DescribeImages operation returns information about AMIs available to the user. This includes
public AMIs available for any user to launch, private AMIs owned by the user making the request, and
private AMIs owned by other users for which the user has explicit launch permissions.

Launch permissions fall into three categories:

Launch Description
Permission
public The owner of the AMI granted launch permissions for the AMI to the all group.
All users have launch permissions for these AMIs.
explicit The owner of the AMI granted launch permissions to a specific user.
implicit A user has implicit launch permissions for all AMIs he or she owns.

The list of AMIs returned can be modified by specifying AMI IDs, AMI owners, or users with launch
permissions. If no options are specified, Amazon EC2 returns all AMIs for which the user has launch
permissions.

If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned. If you specify
an invalid AMI ID, a fault is returned. If you specify an AMI ID for which you do not have access, it
will not be included in the returned results.

If you specify one or more AMI owners, only AMIs from the specified owners and for which you have
access are returned. The results can include the account IDs of the specified owners, amazon for AMIs
owned by Amazon or self for AMIs that you own.

If you specify a list of executable users, only users that have launch permissions for the AMIs are
returned. You can specify account IDs (if you own the AMI(s)), self for AMIs for which you own or
have explicit permissions, or all for public AMIs.

Note

Deregistered images are included in the returned results for an unspecified interval after
deregistration.

If you use the DescribeImages operation on machine images, it displays the kernel IDs and RAM disk
IDs associated with the images. If you specify a kernel or RAM disk ImageType, it displays
information about kernel or RAM disk images.

Request Parameters
The following table describes the request parameters for DescribeImages. Parameter names are case
sensitive.

Name Description Required

imageType The type of images to describe. Options include Yes (but can
machine, kernel, or ramdisk. be empty)
Type: xsd:string[]

imagesSet AMI IDs to describe Yes (but can

API Version 2008-02-01

100
 Amazon Elastic Compute Cloud Developer Guide
DescribeImages

Name Description Required

Type: xsd:string[] be empty)

ownersSet Owners of AMIs to describe Yes (but can

Type: xsd:string[] be empty)

executableBySet AMIs for which specified users have access Yes (but can
Type: xsd:string[] be empty)

imageType Specify whether to return kernel or ramdisk images. Yes (but can
Type: xsd:string[] be empty)

Response Elements
The following table describes the default response tags included in DescribeImages responses.

Name Description
imagesSet A list of image descriptions
Type: DescribeImagesResponseItemType[]

Sample Request
<DescribeImages xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<executableBySet>
<item>
<user>all</user>
</item>
</executableBySet>
<ownersSet />
<imagesSet>
<item>
<imageId>ami-be3adfd7</imageId>
</item>
</imagesSet>
</DescribeImages>

Sample Response
<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imagesSet>
<item>
<imageId>ami-be3adfd7</imageId>
<imageLocation>ec2-public-images/fedora-8-i386-base-v1.04.manifest.xml
</imageLocation>
<imageState>available</imageState>
<imageOwnerId>206029621532</imageOwnerId>
<isPublic>false</isPublic>
<architecture>i386</architecture>
<imageType>machine</imageType>
<kernelId>aki-4438dd2d</kernelId>
<ramdiskId>ari-4538dd2c</ramdiskId>
</item>
</imagesSet>

API Version 2008-02-01

101
 Amazon Elastic Compute Cloud Developer Guide
DescribeInstances

</DescribeImagesResponse>

Related Operations
• DescribeInstances
• DescribeImageAttribute

DescribeInstances
The DescribeInstances operation returns information about instances that you own.

If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do
not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an
invalid instance ID, a fault is returned. If you specify an instance that you do not own, it will not be
included in the returned results.

Recently terminated instances might appear in the returned results. This interval is usually less than one
hour.

Request Parameters
The following table describes the request parameters for DescribeInstances. Parameter names are
case sensitive.

Name Description Required

instancesSet Set of instances IDs to get the status of. Yes (but can
Type: xsd:string[] be empty)

Response Elements
The following table describes the default response tags included in DescribeInstances responses.

Name Description
reservationSet A list of structures describing the status of all requested instances.
Type: ReservationInfoType[]

Sample Request
<DescribeInstances xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instancesSet>
<item>
<instanceId>i-28a64341</instanceId>
</item>
</instancesSet>
</DescribeInstances>

Sample Response

API Version 2008-02-01

102
 Amazon Elastic Compute Cloud Developer Guide
DescribeKeyPairs

<DescribeInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<reservationSet>
<item>
<reservationId>r-44a5402d</reservationId>
<ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
<groupSet>
<item>
<groupId>default</groupId>
</item>
</groupSet>
<instancesSet>
<item>
<instanceId>i-28a64341</instanceId>
<imageId>ami-6ea54007</imageId>
<instanceState>
<code>0</code>
<name>running</name>
</instanceState>
<privateDnsName>10-251-50-132.ec2.internal</privateDnsName>
<dnsName>ec2-72-44-33-4.compute-1.amazonaws.com</dnsName>
<keyName>example-key-name</keyName>
<amiLaunchIndex>23</amiLaunchIndex>
<productCodesSet>
<item><productCode>774F4FF8</productCode></item>
</productCodesSet>
<instanceType>m1.large</instanceType>
<launchTime>2007-08-07T11:54:42.000Z</launchTime>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
<kernelId>aki-ba3adfd3</kernelId>
<ramdiskId>ari-badbad00</ramdiskId>
</item>
</instancesSet>
</item>
</reservationSet>
</DescribeInstancesResponse>

Related Operations
• RunInstances
• TerminateInstances

DescribeKeyPairs
The DescribeKeyPairs operation returns information about key pairs available to you. If you specify
key pairs, information about those key pairs is returned. Otherwise, information for all registered key
pairs is returned.

Request Parameters
The following table describes the request parameters for DescribeKeyPairs. Parameter names are
case sensitive.

Name Description Required

keySet Key pair IDs to describe. Yes (but can
Type: xsd:string[] be empty)

API Version 2008-02-01

103
 Amazon Elastic Compute Cloud Developer Guide
DescribeSecurityGroups

Response Elements
The following table describes the default response tags included in DescribeKeyPairs responses.

Name Description
keySet A list of key pair descriptions
Type: DescribeKeyPairsResponseItemType[]

Sample Request
<DescribeKeyPairs xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<keySet>
<item>
<keyName>example-key-name</keyName>
</item>
</keySet>
</DescribeKeyPairs>

Sample Response
<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<keySet>
<item>
<keyName>example-key-name</keyName>
<keyFingerprint>1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f</
keyFingerprint>
</item>
</keySet>
</DescribeKeyPairsResponse>

Related Operations
• CreateKeyPair
• DeleteKeyPair
• RunInstances

DescribeSecurityGroups
The DescribeSecurityGroups operation returns information about security groups that you own.

If you specify security group names, information about those security group is returned. Otherwise,
information for all security group is returned. If you specify a group that does not exist, a fault is
returned.

Request Parameters
The following table describes the request parameters for DescribeSecurityGroups. Parameter
names are case sensitive.

API Version 2008-02-01

104
 Amazon Elastic Compute Cloud Developer Guide
DescribeSecurityGroups

Name Description Required

securityGroupSet List of security groups to describe. Yes
Type: xsd:string[]

Response Elements
The following table describes the default response tags included in DescribeSecurityGroups
responses.

Name Description
securityGroupInfo Information about security groups.
Type: SecurityGroupItemType[]

Sample Request
<DescribeSecurityGroups xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<securityGroupSet>
<item>
<groupName>WebServers</groupName>
</item>
<item>
<groupName>RangedPortsBySource</groupName>
</item>
</securityGroupSet>
</DescribeSecurityGroups>

Sample Response
<DescribeSecurityGroupsResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<securityGroupInfo>
<item>
<ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
<groupName>WebServers</groupName>
<groupDescription>Web</groupDescription>
<ipPermissions>
<item>
<ipProtocol>tcp</ipProtocol>
<fromPort>80</fromPort>
<toPort>80</toPort>
<groups/>
<ipRanges>
<item>
<cidrIp>0.0.0.0/0</cidrIp>
</item>
</ipRanges>
</item>
</ipPermissions>
</item>
<item>
<ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
<groupName>RangedPortsBySource</groupName>
<groupDescription>A</groupDescription>
<ipPermissions>
<item>
<ipProtocol>tcp</ipProtocol>

API Version 2008-02-01

105
 Amazon Elastic Compute Cloud Developer Guide
DisassociateAddress

<fromPort>6000</fromPort>
<toPort>7000</toPort>
<groups/>
<ipRanges/>
</item>
</ipPermissions>
</item>
</securityGroupInfo>
</DescribeSecurityGroupsResponse>

Related Operations
• CreateSecurityGroup
• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress
• DeleteSecurityGroup

DisassociateAddress
The DisassociateAddress operation disassociates the specified elastic IP address from the instance
to which it is assigned. This is an idempotent operation. If you enter it more than once, Amazon EC2
does not return an error.

Request Parameters
The following table describes the request parameters for DisassociateAddress. Parameter names are
case sensitive.

Name Description Required

publicIp IP address that you are disassociating from the instance. Yes
Type: xsd:string

Response Elements
The following table describes the default response tags included in DisassociateAddress responses.

Name Description
return true if the IP address is disassociated from the instance.
Otherwise, false.
Type: xsd:boolean

Sample Request
<DisassociateAddress xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<publicIp>67.202.55.255</publicIp>
</DisassociateAddress>

Sample Response
API Version 2008-02-01
106
 Amazon Elastic Compute Cloud Developer Guide
GetConsoleOutput

<DisassociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</DisassociateAddressResponse>

Related Operations
• AllocateAddress
• DescribeAddresses
• ReleaseAddress
• AssociateAddress

GetConsoleOutput
The GetConsoleOutput operation retrieves console output for the specified instance.

Instance console output is buffered and posted shortly after instance boot, reboot, and termination.
Amazon EC2 preserves the most recent 64 KB output which will be available for at least one hour after
the most recent post.

Request Parameters
The following table describes the request parameters for GetConsoleOutput. Parameter names are
case sensitive.

Name Description Required

instanceId An instance ID returned from a previous call to Yes
RunInstances.
Type: xsd:string

Response Elements
The following table describes the default response tags included in GetConsoleOutput responses.

Name Description
instanceId The instance ID.
Type: xsd:string

timestamp The time the output was last updated.

Type: xsd:dateTime

output The console output, Base64 encoded.

Type: xsd:string

Sample Request
<GetConsoleOutput xmlns="http://ec2.amazonaws.com/doc/2008-02-01">

API Version 2008-02-01

107
 Amazon Elastic Compute Cloud Developer Guide
ModifyImageAttribute

<instanceId>i-28a64341</instanceId>
</GetConsoleOutput>

Sample Response
<GetConsoleOutputResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instanceId>i-28a64341</instanceId>
<timestamp>2007-01-03 15:00:00</timestamp>
<output>TGludXggdmVyc2lvbiAyLjYuMTYteGVuVSAoYnVpbGRlckBwYXRjaGJhdC5hbWF6b25zY
SkgKGdj
YyB2ZXJzaW9uIDQuMC4xIDIwMDUwNzI3IChSZWQgSGF0IDQuMC4xLTUpKSAjMSBTTVAgVGh1IE9j
dCAyNiAwODo0MToyNiBTQVNUIDIwMDYKQklPUy1wcm92aWRlZCBwaHlzaWNhbCBSQU0gbWFwOgpY
ZW46IDAwMDAwMDAwMDAwMDAwMDAgLSAwMDAwMDAwMDZhNDAwMDAwICh1c2FibGUpCjk4ME1CIEhJ
R0hNRU0gYXZhaWxhYmxlLgo3MjdNQiBMT1dNRU0gYXZhaWxhYmxlLgpOWCAoRXhlY3V0ZSBEaXNh
YmxlKSBwcm90ZWN0aW9uOiBhY3RpdmUKSVJRIGxvY2t1cCBkZXRlY3Rpb24gZGlzYWJsZWQKQnVp
bHQgMSB6b25lbGlzdHMKS2VybmVsIGNvbW1hbmQgbGluZTogcm9vdD0vZGV2L3NkYTEgcm8gNApF
bmFibGluZyBmYXN0IEZQVSBzYXZlIGFuZCByZXN0b3JlLi4uIGRvbmUuCg==</output>
</GetConsoleOutputResponse>

ModifyImageAttribute
The ModifyImageAttribute operation modifies an attribute of an AMI.

Request Parameters
The following table describes the request parameters for ModifyImageAttribute. Parameter names
are case sensitive.

Name Description Required

imageId AMI ID to modify. Yes
Type: xsd:string

launchPermission Adds or removes launch permissions for the AMI. Choice

Type: LaunchPermissionOperationType[]

productCodes Attaches a product code to the AMI, allowing developers Choice

to charge for the use of their AMIs. Currently only one
product code can be associated with an AMI. Once set,
the product code cannot be changed or reset.
Type: ProductCodeItemType[]

Response Elements
The following table describes the default response tags included in ModifyImageAttribute
responses.

Name Description
return true if the operation succeeded, otherwise false.
Type: xsd:boolean

API Version 2008-02-01

108
 Amazon Elastic Compute Cloud Developer Guide
RebootInstances

Sample Request - Launch Permission

<ModifyImageAttribute xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
<launchPermission>
<add>
<item>
<group>all</group>
</item>
<item>
<userId>495219933132</userId>
</item>
</add>
<launchPermission>
</ModifyImageAttribute>

Sample Request - Product Codes

<ModifyImageAttribute xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
<productCodes>
<item>
<productCode>774F4FF8</productCode>
</item>
<productCodes>
</ModifyImageAttribute>

Sample Response
<ModifyImageAttributeResponse
xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</ModifyImageAttributeResponse>

Related Operations
• ResetImageAttribute
• DescribeImageAttribute

RebootInstances
The RebootInstances operation requests a reboot of one or more instances. This operation is
asynchronous; it only queues a request to reboot the specified instance(s). The operation will succeed if
the instances are valid and belong to the user. Requests to reboot terminated instances are ignored.

Request Parameters
The following table describes the request parameters for RebootInstances. Parameter names are case
sensitive.

Name Description Required

instancesSet One or more instance IDs. Yes
Type: xsd:string[]

API Version 2008-02-01

109
 Amazon Elastic Compute Cloud Developer Guide
RegisterImage

Name Description Required

Response Elements
The following table describes the default response tags included in RebootInstances responses.

Name Description
result true if the operation succeeded.
Type: xsd:boolean

Sample Request
<RebootInstances xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instancesSet>
<item>
<instanceId>i-28a64341</instanceId>
</item>
</instancesSet>
</RebootInstances>

Sample Response
<RebootInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</RebootInstancesResponse>

RegisterImage
The RegisterImage operation registers an AMI with Amazon EC2. Images must be registered before
they can be launched. For more information, see RunInstances.

Each AMI is associated with an unique ID which is provided by the Amazon EC2 service through the
RegisterImage operation. During registration, Amazon EC2 retrieves the specified image manifest
from Amazon S3 and verifies that the image is owned by the user registering the image.

The image manifest is retrieved once and stored within the Amazon EC2. Any modifications to an
image in Amazon S3 invalidates this registration. If you make changes to an image, deregister the
previous image and register the new image. For more information, see DeregisterImage.

Request Parameters
The following table describes the request parameters for RegisterImage. Parameter names are case
sensitive.

Name Description Required

imageLocation Full path to your AMI manifest in Amazon S3 storage. Yes
Type: xsd:string

API Version 2008-02-01

110
 Amazon Elastic Compute Cloud Developer Guide
ReleaseAddress

Response Elements
The following table describes the default response tags included in RegisterImage responses.

Name Description
imageId Unique ID of the newly registered machine image.
Type: xsd:string

Sample Request
<RegisterImage xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageLocation>/mybucket/myimage.manifest.xml</imageLocation>
</RegisterImage>

Sample Response
<RegisterImageResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
</RegisterImageResponse>

Related Operations
• DescribeImages
• DeregisterImage

ReleaseAddress
The ReleaseAddress operation releases an elastic IP address associated with your account.

If you run this operation on an elastic IP address that is already released, the address might be assigned
to another account which will cause Amazon EC2 to return an error.

Note

Releasing an IP address automatically disassociates it from any instance with which it is

associated. For more information, see DisassociateAddress.

Important

After releasing an elastic IP address, it is released to the IP address pool and might no
longer be available to your account. Make sure to update your DNS records and any
servers or devices that communicate with the address.

Request Parameters
The following table describes the request parameters for ReleaseAddress. Parameter names are case
sensitive.

API Version 2008-02-01

111
 Amazon Elastic Compute Cloud Developer Guide
ResetImageAttribute

Name Description Required

publicIp IP address that you are releasing from your account. Yes
Type: xsd:string

Response Elements
The following table describes the default response tags included in ReleaseAddress responses.

Name Description
return true if the IP address is released. Otherwise, false.
Type: xsd:boolean

Sample Request
<ReleaseAddress xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<publicIp>67.202.55.255</publicIp>
</ReleaseAddress>

Sample Response
<ReleaseAddressResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</ReleaseAddressResponse>

Related Operations
• AllocateAddress
• DescribeAddresses
• AssociateAddress
• DisassociateAddress

ResetImageAttribute
The ResetImageAttribute operation resets an attribute of an AMI to its default value.

Note

The productCodes attribute cannot be reset.

Request Parameters
The following table describes the request parameters for ResetImageAttribute. Parameter names are
case sensitive.

API Version 2008-02-01

112
 Amazon Elastic Compute Cloud Developer Guide
RevokeSecurityGroupIngress

Name Description Required

imageId ID of the AMI on which the attribute will be reset. Yes
Type: xsd:string

launchPermission Resets the AMI's launch permissions. All public and Yes
explicit launch permissions for the AMI are revoked.
Type: EmptyElementType

Response Elements
The following table describes the default response tags included in ResetImageAttribute responses.

Name Description
return true if the operation succeeded, otherwise false.
Type: xsd:boolean

Sample Request
<ResetImageAttribute xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
<launchPermission />
</ResetImageAttribute>

Sample Response
<ResetImageAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</ResetImageAttributeResponse>

Related Operations
• ModifyImageAttribute
• DescribeImageAttribute

RevokeSecurityGroupIngress
The RevokeSecurityGroupIngress operation revokes permissions from a security group. The
permissions used to revoke must be specified using the same values used to grant the permissions.

Permissions are specified by IP protocol (TCP, UDP, or ICMP), the source of the request (by IP range or
an Amazon EC2 user-group pair), the source and destination port ranges (for TCP and UDP), and the
ICMP codes and types (for ICMP).

Permission changes are quickly propagated to instances within the security group. However, depending
on the number of instances in the group, a small delay is might occur, .

API Version 2008-02-01

113
 Amazon Elastic Compute Cloud Developer Guide
RevokeSecurityGroupIngress

Request Parameters
The following table describes the request parameters for RevokeSecurityGroupIngress. Parameter
names are case sensitive.

Name Description Required

userId AWS Access Key ID. Yes
Type: xsd:string

groupName Name of the group to modify. Yes

Type: xsd:string

ipPermissions Set of permissions to remove from the group. Yes

Type: IpPermissionType[]

Response Elements
The following table describes the default response tags included in RevokeSecurityGroupIngress
responses.

Name Description
return true if permissions successfully revoked.
Type: xsd:boolean

Sample Request
<RevokeSecurityGroupIngress xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<userId/>
<groupName>RangedPortsBySource</groupName>
<ipPermissions>
<item>
<ipProtocol>tcp</ipProtocol>
<fromPort>6000</fromPort>
<toPort>7000</toPort>
<groups/>
<ipRanges/>
</item>
</ipPermissions>
</RevokeSecurityGroupIngress>

Sample Response
<RevokeSecurityGroupIngressResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</RevokeSecurityGroupIngressResponse>

Related Operations

API Version 2008-02-01

114
 Amazon Elastic Compute Cloud Developer Guide
RunInstances

• CreateSecurityGroup
• DescribeSecurityGroups
• AuthorizeSecurityGroupIngress
• DeleteSecurityGroup

RunInstances
The RunInstances operation launches a specified number of instances.

If Amazon EC2 cannot launch the minimum number AMIs you request, no instances will be launched. If
there is insufficient capacity to launch the maximum number of AMIs you request, Amazon EC2
launches the minimum number specified for each AMI and allocate the remaining available instances
using round robin.

In the following example, Libby generates a request to launch two images (database and web_server):

1. Libby runs the RunInstances operation to launch database instances (min. 10, max. 15) and
web_server instances (min. 30, max. 40).

Because there are currently 30 instances available and Libby needs a minimum of 40, no instances
are launched.
2. Libby adjusts the number of instances she needs and runs the RunInstances operation to launch
database instances (min. 5, max. 10) and web_server instances (min. 20, max. 40).

Amazon EC2 launches the minimum number of instances for each AMI (5 database, 20 web_server).

The remaining 5 instances are allocated using round robin.

3. Libby adjusts the number of instances she needs and runs the RunInstances operation again to
launch database instances (min. 5, max. 10) and web_server instances (min. 20, max. 40).

Note

Every instance is launched in a security group (see CreateSecurityGroup. If you do not

specify a security group at launch, the instances start in your default security group.

You can provide an optional key pair ID for each image in the launch request (see CreateKeyPair). All
instances that are created from images that use this key pair will have access to the associated public key
at boot. You can use this key to provide secure access to an instance of an image on a per-instance basis.
Amazon EC2 public images use this feature to provide secure access without passwords.

Important

Launching public images without a key pair ID will leave them inaccessible.

The public key material is made available to the instance at boot time by placing it in the
openssh_id.pub file on a logical device that is exposed to the instance as /dev/sda2 (the ephemeral
store). The format of this file is suitable for use as an entry within ~/.ssh/authorized_keys (the
OpenSSH format). This can be done at boot (e.g., as part of rc.local) allowing for secure access
without passwords.

Optional user data can be provided in the launch request. All instances comprising the launch request
have access to this data (see Instance Metadata for details).

API Version 2008-02-01

115
 Amazon Elastic Compute Cloud Developer Guide
RunInstances

Note

If any of the AMIs have a product code attached for which the user has not subscribed, the
RunInstances call will fail.

Request Parameters
The following table describes the request parameters for RunInstances. Parameter names are case
sensitive.

Name Description Required

imageId Unique ID of a machine image, returned by a call to Yes
RegisterImage.
Type: xsd:string

minCount Minimum number of instances to launch. If minCount is Yes

more than Amazon EC2 can launch, no instances are
launched at all.
Type: xsd:int

maxCount Maximum number of instances to launch. If maxCount is Yes

more than Amazon EC2 can launch, the largest possible
number above minCount will be launched instead.
Type: xsd:int

keyName The name of the key pair. No

Type: xsd:string

groupSet Description of the security groups with which to Yes

associate the instances.
Type: GroupSetType[]

userData The user data available to the launched instances. No

Type: UserDataType[]

instanceType This specifies the instance type. No

Options include m1.small, m1.large, and m1.xlarge.
The default value is m1.small.
For more information on instance types, see Instance
Types.
Type: xsd:string

placement Specifies the placement constraints (availability zones) No

for launching the instances.
To display the list of available availability zones, use the
DescribeAvailabilityZones operation.
Type: PlacementRequestType
By default, Amazon EC2 selects an availability zone for
you. For more information, see Availability Zones.

kernelId The ID of the kernel with which to launch the instance. No

API Version 2008-02-01

116
 Amazon Elastic Compute Cloud Developer Guide
RunInstances

Name Description Required

For information on finding available kernel IDs, see
ec2-describe-images.
Example: aki-ba3adfd3

ramdiskId The ID of the RAM disk with which to launch the No

instance.
Some kernels require additional drivers at launch. Check
the kernel requirements for information on whether you
need to specify a RAM disk. To find kernel requirements,
go to the Resource Center and search for the kernel ID.
Example: ari-badbad00

blockDeviceMapping Specifies how block devices are exposed to the instance. No

Each mapping is made up of a virtualName and a
deviceName.
Virtual name example: ephemeral0
Device name example: sdb
Type: BlockDeviceMappingItemType[]

Response Elements
The following table describes the default response tags included in RunInstances responses.

Name Description
RunInstancesResponse Status information about the instances launched.
Type: ReservationInfoType

Sample Request
<RunInstances xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instancesSet>
<item>
<imageId>ami-60a54009</imageId>
<minCount>1</minCount>
<maxCount>3</maxCount>
<keyName>example-key-name</keyName>
<groupSet/>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
<kernelId>aki-ba3adfd3</kernelId>
<ramdiskId>ari-badbad00</ramdiskId>
<blockDeviceMapping>
<item>
<virtualName>ami</virtualName>
<deviceName>sda1<deviceName>
</item>
<item>
<virtualName>root</virtualName>
<deviceName>/dev/sda1</deviceName>
</item>
<item>

API Version 2008-02-01

117
 Amazon Elastic Compute Cloud Developer Guide
RunInstances

<virtualName>ephemeral0</virtualName>
<deviceName>sdb</deviceName>
</item>
<item>
<virtualName>ephemeral1</virtualName>
<deviceName>sdc</deviceName>
</item>
</blockDeviceMapping>
</item>
</instancesSet>
<userData version="1.0" encod
ing="base64"><data>"VGhpcyBpcyBiYXNlIDY0IQ==</data></userData>
<addressingType>public</addressingType>
</RunInstances>

Sample Response
<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<reservationId>r-47a5402e</reservationId>
<ownerId>495219933132</ownerId>
<groupSet>
<item>
<groupId>default</groupId>
</item>
</groupSet>
<instancesSet>
<item>
<instanceId>i-2ba64342</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<privateDnsName></privateDnsName>
<dnsName></dnsName>
<keyName>example-key-name</keyName>
<amiLaunchIndex>0</amiLaunchIndex>
<instanceType>m1.small</instanceType>
<launchTime>2007-08-07T11:51:50.000Z</launchTime>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
</item>
<item>
<instanceId>i-2bc64242</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<privateDnsName></privateDnsName>
<dnsName></dnsName>
<keyName>example-key-name</keyName>
<amiLaunchIndex>1</amiLaunchIndex>
<instanceType>m1.small</instanceType>
<launchTime>2007-08-07T11:51:50.000Z</launchTime>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
</item>
<item>
<instanceId>i-2be64332</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<privateDnsName></privateDnsName>

API Version 2008-02-01

118
 Amazon Elastic Compute Cloud Developer Guide
TerminateInstances

<dnsName></dnsName>
<keyName>example-key-name</keyName>
<amiLaunchIndex>2</amiLaunchIndex>
<instanceType>m1.small</instanceType>
<launchTime>2007-08-07T11:51:50.000Z</launchTime>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
</item>
</instancesSet>
</RunInstancesResponse>

Related Operations
• DescribeInstances
• TerminateInstances
• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress
• DescribeSecurityGroups

TerminateInstances
The TerminateInstances operation shuts down one or more instances. This operation is idempotent;
if you terminate an instance more than once, each call will succeed.

Terminated instances will remain visible after termination (approximately one hour).

Request Parameters
The following table describes the request parameters for TerminateInstances. Parameter names are
case sensitive.

Name Description Required

instancesSet One or more instance IDs. Yes
Type: xsd:string[]

Response Elements
The following table describes the default response tags included in TerminateInstances responses.

Name Description
instancesSet A complex type describing the current and new state of each
instance specified.
Type: TerminateInstancesResponseInfoType[]

Sample Request
<TerminateInstances xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instancesSet>

API Version 2008-02-01

119
 Amazon Elastic Compute Cloud Developer Guide
Amazon EC2 Query API

<item>
<instanceId>i-28a64341</instanceId>
</item>
</instancesSet>
</TerminateInstances>

Sample Response
<TerminateInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instancesSet>
<item>
<instanceId>i-28a64341</instanceId>
<shutdownState>
<code>32</code>
<name>shutting-down</name>
</shutdownState>
<previousState>
<code>16</code>
<name>running</name>
</previousState>
</item>
</instancesSet>
</TerminateInstancesResponse>

Related Operations
• DescribeInstances

Amazon EC2 Query API

The Amazon EC2 API consists of web service operations for every task the service can perform. This
section describes each operation in detail.

Common Query Parameters

Request Parameters
All Query operations share a set of common parameters that must be present in each call:

Name Description Required

Action Indicates the action to perform. Yes
Example: RunInstances

Version The API version to use, as specified in the WSDL. Yes

Example: 2008-02-01

AWSAccessKeyId The Access Key ID for the request sender. This identifies Yes
the account which will be charged for usage of the
service. The account with which the Access Key ID is
associated must be signed up for Amazon EC2, or
requests will not be accepted.
10QMXFEV71ZS32XQFTR2

Timestamp The date and time at which the request is signed, in the Yes
API Version 2008-02-01
120
 Amazon Elastic Compute Cloud Developer Guide
List of Operations by Function

Name Description Required

format YYYY-MM-DDThh:mm:ssZ, as specified in the
ISO 8601 standard.
Example: 2006-07-07T15:04:56Z

Expires The date and time at which the signature included in the Yes
request expires, in the format
YYYY-MM-DDThh:mm:ssZ, as specified in the ISO
8601 standard.
Example: 2006-07-07T15:04:56Z

Signature A request signature is calculated as explained in Request Yes

Authentication.
Example: Qnpl4Qk/7tINHzfXCiT7VbBatDA=

SignatureVersion A value of 0 or 1 indicates the method chosen to Yes

construct the string to be signed. Currently, only a value
of 1 is valid.
Example: 1

Note

The Timestamp parameter can be used instead of Expires. Requests must include either
Timestamp or Expires, but cannot contain both.

Parameter values must be URL-encoded. This is true for any Query parameter passed to Amazon EC2
and is typically necessary in the Signature parameter. Some clients do this automatically, but this is
not the norm.

List of Operations by Function

Images

• RegisterImage
• DescribeImages
• DeregisterImage

Instances

• RunInstances
• DescribeInstances
• TerminateInstances
• ConfirmProductInstance

Key Pairs

API Version 2008-02-01

121
 Amazon Elastic Compute Cloud Developer Guide
AllocateAddress

• CreateKeyPair
• DescribeKeyPairs
• DeleteKeyPair

Image Attributes

• ModifyImageAttribute
• DescribeImageAttribute
• ResetImageAttribute

Security Groups

• CreateSecurityGroup
• DescribeSecurityGroups
• DeleteSecurityGroup
• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress

Elastic IP Addresses

• AllocateAddress
• DescribeAddresses
• ReleaseAddress
• AssociateAddress
• DisassociateAddress

Availability Zones

• DescribeAvailabilityZones

AllocateAddress
The AllocateAddress operation acquires an elastic IP address for use with your account.

Request Parameters
The AllocateAddress operation does not have any request parameters.

Response Elements
The following table describes the default response tags included in AllocateAddress responses.

Name Description
PublicIp Returned IP address.
Type: xsd:string

API Version 2008-02-01

122
 Amazon Elastic Compute Cloud Developer Guide
AssociateAddress

Name Description

Sample Request
https://ec2.amazonaws.com/
?Action=AllocateAddress
&...auth parameters...

Sample Response
<AllocateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<publicIp>67.202.55.255</publicIp>
</AllocateAddressResponse>

Related Operations
• DescribeAddresses
• ReleaseAddress
• AssociateAddress
• DisassociateAddress

AssociateAddress
The AssociateAddress operation associates an elastic IP address with an instance.

If the IP address is currently assigned to another instance, the IP address is assigned to the new instance.
This is an idempotent operation. If you enter it more than once, Amazon EC2 does not return an error.

Request Parameters
The following table describes the request parameters for AssociateAddress. Parameter names are
case sensitive.

Name Description Required

InstanceId The instance to which the IP address is assigned. Yes
Type: String

PublicIp IP address that you are assigning to the instance. Yes

Type: String

Response Elements
The following table describes the default response tags included in AssociateAddress responses.

Name Description
return true if the IP address is associated with the instance. Otherwise,

API Version 2008-02-01

123
 Amazon Elastic Compute Cloud Developer Guide
AuthorizeSecurityGroupIngress

Name Description
false.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=AssociateAddress
&InstanceId=i-2ea64347
&PublicIp=67.202.55.255
&...auth parameters...

Sample Response
<AssociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</AssociateAddressResponse>

Related Operations
• AllocateAddress
• DescribeAddresses
• ReleaseAddress
• DisassociateAddress

AuthorizeSecurityGroupIngress
The AuthorizeSecurityGroupIngress operation adds permissions to a security group.

Permissions are specified by the IP protocol (TCP, UDP or ICMP), the source of the request (by IP
range or an Amazon EC2 user-group pair), the source and destination port ranges (for TCP and UDP),
and the ICMP codes and types (for ICMP). When authorizing ICMP, -1 can be used as a wildcard in the
type and code fields.

Permission changes are propagated to instances within the security group as quickly as possible.
However, depending on the number of instances, a small delay might occur.

When authorizing a user/group pair permission, GroupName, SourceSecurityGroupName and

SourceSecurityGroupOwnerId must be specified. When authorizing a CIDR IP permission,
GroupName, IpProtocol, FromPort, ToPort and CidrIp must be specified. Mixing these two types
of parameters is not allowed.

Request Parameters
The following table describes the request parameters for AuthorizeSecurityGroupIngress.
Parameter names are case sensitive.

Name Description Required

GroupName Name of the group to modify. Yes

API Version 2008-02-01

124
 Amazon Elastic Compute Cloud Developer Guide
AuthorizeSecurityGroupIngress

Name Description Required

Type: String

SourceSecurityGroupName Name of security group to authorize access to when When

operating on a user/group pair. authorizing
Type: String user/group
pair
permission.

SourceSecurityGroupOwnerIdOwner of security group to authorize access to when When

operating on a user/group pair. authorizing
Type: String user/group
pair
permisison.

IpProtocol IP protocol to authorize access to when operating on When

a CIDR IP. authorizing
Type: String CIDR IP
permission.
Valid Values: tcp | udp | icmp

FromPort Bottom of port range to authorize access to when When

operating on a CIDR IP. This contains the ICMP type authorizing
if ICMP is being authorized. CIDR IP
Type: Int permission.

ToPort Top of port range to authorize access to when When

operating on a CIDR IP. This contains the ICMP authorizing
code if ICMP is being authorized. CIDR IP
Type: Int permission.

CidrIp CIDR IP range to authorize access to when operating When

on a CIDR IP. authorizing
Type: String CIDR IP
permission.

Response Elements
The following table describes the default response tags included in
AuthorizeSecurityGroupIngress responses.

Name Description
return true if permissions successfully added.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=AuthorizeSecurityGroupIngress
&IpProtocol=tcp
&FromPort=80
&ToPort=80

API Version 2008-02-01

125
 Amazon Elastic Compute Cloud Developer Guide
ConfirmProductInstance

&CidrIp=0.0.0.0/0
&...auth parameters...

Sample Response
<AuthorizeSecurityGroupIngressResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</AuthorizeSecurityGroupIngressResponse>

Related Operations
• CreateSecurityGroup
• CreateSecurityGroup
• CreateSecurityGroup
• CreateSecurityGroup

ConfirmProductInstance
The ConfirmProductInstance operation returns true if the specified product code is attached to the
specified instance. The operation returns false if the product code is not attached to the instance.

The ConfirmProductInstance operation can only be executed by the owner of the AMI. This feature
is useful when an AMI owner is providing support and wants to verify whether a user's instance is
eligible.

Request Parameters
The following table describes the request parameters for ConfirmProductInstance. Parameter
names are case-sensitive.

Name Description Required

ProductCode The product code to confirm. Yes
Type: String

InstanceId The instance for which to confirm the product code. Yes
Type: String

Response Elements
The following table describes the default response tags included in ConfirmProductInstance
responses.

Name Description
result true if the product code is attached to the instance, false if it is
not.
Type: xsd:boolean

API Version 2008-02-01

126
 Amazon Elastic Compute Cloud Developer Guide
CreateKeyPair

Name Description
ownerId The instance owner's account ID. Only present if the product code
is attached to the instance.
Type: xsd:string

Sample Request
https://ec2.amazonaws.com/
?Action=ConfirmProductInstance
&ProductCode=774F4FF8
&InstanceId=i-10a64379
&...auth parameters...

Sample Response
<ConfirmProductInstanceResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<result>true</result>
<ownerId>254933287430</ownerId>
</ConfirmProductInstanceResponse>

Related Operations
• DescribeInstances
• RunInstances

CreateKeyPair
The CreateKeyPair operation creates a new 2048 bit RSA key pair and returns a unique ID that can
be used to reference this key pair when launching new instances. For more information, see
RunInstances.

Request Parameters
The following table describes the request parameters for CreateKeyPair. Parameter names are case
sensitive.

Name Description Required

KeyName A unique name for the key pair. Yes
Type: String

Response Elements
The following table describes the default response tags included in CreateKeyPair responses.

API Version 2008-02-01

127
 Amazon Elastic Compute Cloud Developer Guide
CreateSecurityGroup

Name Description
keyName The key pair name provided in the original request.
Type: xsd:string

KeyFingerprint A SHA-1 digest of the DER encoded private key.

Type: xsd:string

KeyMaterial An unencrypted PEM encoded RSA private key.

Type: xsd:string

Sample Request
https://ec2.amazonaws.com/
?Action=CreateKeyPair
&KeyName=example-key-name
&...auth parameters...

Sample Response
<CreateKeyPairResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<keyName>example-key-name</keyName>
<keyFingerprint>1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f</
keyFingerprint>
<keyMaterial>-----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-----</keyMaterial>
</CreateKeyPairResponse>

Related Operations
• DescribeKeyPairs
• DeleteKeyPair
• RunInstances

API Version 2008-02-01

128
 Amazon Elastic Compute Cloud Developer Guide
CreateSecurityGroup

CreateSecurityGroup
The CreateSecurityGroup operation creates a new security group.

Every instance is launched in a security group. If no security group is specified during launch, the
instances are launched in the default security group. Instances within the same security group have
unrestricted network access to each other. Instances will reject network access attempts from other
instances in a different security group. As the owner of instances you can grant or revoke specific
permissions using the AuthorizeSecurityGroupIngress and RevokeSecurityGroupIngress operations.

Request Parameters
The following table describes the request parameters for CreateSecurityGroup. Parameter names are
case sensitive.

Name Description Required

GroupName Name of the new security group. Yes
Type: String

GroupDescription Description of the new security group. Yes

Type: String

Response Elements
The following table describes the default response tags included in CreateSecurityGroup responses.

Name Description
return true if call succeeded.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action==CreateSecurityGroup
&GroupName=WebServers
&GroupDescription=Web
&...auth parameters...

Sample Response
<CreateSecurityGroupResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</CreateSecurityGroupResponse>

Related Operations
• RunInstances
• DescribeSecurityGroups
• AuthorizeSecurityGroupIngress

API Version 2008-02-01

129
 Amazon Elastic Compute Cloud Developer Guide
DeleteKeyPair

• RevokeSecurityGroupIngress
• DeleteSecurityGroup

DeleteKeyPair
The DeleteKeyPair operation deletes a key pair.

Request Parameters
The following table describes the request parameters for DeleteKeyPair. Parameter names are case
sensitive.

Name Description Required

KeyName Name of the key pair to delete. Yes
Type: String

Response Elements
The following table describes the default response tags included in DeleteKeyPair responses.

Name Description
return true if the key was successfully deleted.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=DeleteKeyPair
&KeyName=example-key-name
&...auth parameters...

Sample Response
<DeleteKeyPair xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</DeleteKeyPair>

Related Operations
• CreateKeyPair
• DescribeKeyPairs

DeleteSecurityGroup
The DeleteSecurityGroup operation deletes a security group.

API Version 2008-02-01

130
 Amazon Elastic Compute Cloud Developer Guide
DeleteSecurityGroup

Note

If you attempt to delete a security group that contains instances, a fault is returned.
If you attempt to delete a security group that is referenced by another security group, a
fault is returned. For example, if security group B has a rule that allows access from
security group A, security group A cannot be deleted until the allow rule is removed.

Request Parameters
The following table describes the request parameters for DeleteSecurityGroup. Parameter names are
case sensitive.

Note

A security group cannot be deleted if it is referenced by another security group. For

example, if security group B has a rule that allows access from security group A, security
group A cannot be deleted until the allow rule is removed.

Name Description Required

GroupName Name of the security group to delete. Yes
Type: String

Response Elements
The following table describes the default response tags included in DeleteSecurityGroup responses.

Name Description
return true if the group is deleted. Otherwise, false.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=DeleteSecurityGroup
&GroupName=RangedPortsBySource
&...auth parameters...

Sample Response
<DeleteSecurityGroupResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</DeleteSecurityGroupResponse>

Related Operations
• CreateSecurityGroup

API Version 2008-02-01

131
 Amazon Elastic Compute Cloud Developer Guide
DeregisterImage

• DescribeSecurityGroups
• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress

DeregisterImage
The DeregisterImage operation deregisters an AMI. Once deregistered, instances of the AMI can no
longer be launched.

Request Parameters
The following table describes the request parameters for DeregisterImage. Parameter names are case
sensitive.

Name Description Required

ImageId Unique ID of a machine image, returned by a call to Yes
RegisterImage or DescribeImages.
Type: String

Response Elements
The following table describes the default response tags included in DeregisterImage responses.

Name Description
return true if deregistration succeeded; otherwise false.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=DeregisterImage
&ImageId=ami-61a54008
&...auth parameters...

Sample Response
<DeregisterImageResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</DeregisterImageResponse>

Related Operations
• RegisterImage
• DescribeImages

DescribeAddresses
API Version 2008-02-01
132
 Amazon Elastic Compute Cloud Developer Guide
DescribeAvailabilityZones

The DescribeAddresses operation lists elastic IP addresses assigned to your account.

Request Parameters
The following table describes the request parameters for DescribeAddresses. Parameter names are
case sensitive.

Name Description Required

PublicIp.n Elastic IP addresses to describe. Yes (but can
Type: String be empty)

Response Elements
The following table describes the default response tags included in DescribeAddresses responses.

Name Description
publicIp Elastic IP address assigned to your account.
Type: xsd:string

instanceId Instance ID to which the IP address is assigned.

Type: xsd:string

Sample Request
https://ec2.amazonaws.com/
?Action=DescribeAddresses
&PublicIp.1=67.202.55.255
&...auth parameters...

Sample Response
<DescribeAddressesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instanceId>i-28a64341</instanceId>
<publicIp>67.202.55.255</publicIp>
</DescribeAddressesResponse>

Related Operations
• AllocateAddress
• ReleaseAddress
• AssociateAddress
• DisassociateAddress

DescribeAvailabilityZones
The DescribeAvailabilityZones operation describes availability zones that are currently available
to the account and their states.

API Version 2008-02-01

133
 Amazon Elastic Compute Cloud Developer Guide
DescribeAvailabilityZones

Note

Availability zones are not the same across accounts. The availability zone us-east-1a for
account A is not necessarily the same as us-east-1a for account B. Zone assignments are
mapped independently for each account.

Request Parameters
The following table describes the request parameters for DescribeAvailabilityZones. Parameter
names are case sensitive.

Name Description Required

ZoneName.n Name of an availability zone. No
Type: String

Response Elements
The following table describes the default response tags included in DescribeAvailabilityZones
responses.

Name Description
availabilityZoneInfo Availability zone information.
Type: AvailabilityZoneItemType[]

Sample Request
https://ec2.amazonaws.com/
?Action=DescribeAvailabilityZones
&ZoneName.0=us-east-1a
&ZoneName.1=us-east-1b
&...auth parameters...

Sample Response
<DescribeAvailabilityZonesResponse
xmlns="http://ec2.amazonaws.com/doc/2008-02-01/">
<availabilityZoneInfo>
<item>
<zoneName>us-east-1a</zoneName>
<zoneState>available</zoneState>
</item>
<item>
<zoneName>us-east-1b</zoneName>
<zoneState>available</zoneState>
</item>
<item>
<zoneName>us-east-1c</zoneName>
<zoneState>available</zoneState>
</item>
</availabilityZoneInfo>
</DescribeAvailabilityZonesResponse>

API Version 2008-02-01

134
 Amazon Elastic Compute Cloud Developer Guide
DescribeImageAttribute

Related Operations
• RunInstances

DescribeImageAttribute
The DescribeImageAttribute operation returns information about an attribute of an AMI. Only one
attribute can be specified per call.

Request Parameters
The following table describes the request parameters for DescribeImageAttribute. Parameter
names are case-sensitive.

Name Description Required

ImageId ID of the AMI for which an attribute will be described. Yes
Type: String

Attribute Specifies the attribute to describe. Yes

Type: String
Valid Value: launchPermission

Attributes
Attribute Name Description
launchPermission The AMIs launch permissions.

ImageId ID of the AMI for which an attribute will be described.

productCodes The product code attached to the AMI.

kernel Describes the ID of the kernel associated with the AMI.

Type: String

ramdisk Describes the ID of RAM disk associated with the AMI.

Type: String

blockDeviceMapping Defines native device names to use when exposing virtual devices.
Type: String

Response Elements
The following table describes the default response tags included in DescribeImageAttribute
responses.

Name Description
imageId ID of the AMI described.
API Version 2008-02-01
135
 Amazon Elastic Compute Cloud Developer Guide
DescribeImageAttribute

Name Description
Type: xsd:string

launchPermission Launch permissions of the AMI. Returned if launchPermission

is specified.
Type: LaunchPermissionItemType[]

productCodes Product codes of the AMI. Returned if productCodes is specified.

Type: ProductCodeItemType[]

kernel ID of the kernel associated with the AMI. Returned if kernel is

specified.
Type: xsd:string

ramdisk ID of the RAM disk associated with the AMI. Returned if ramdisk
is specified.
Type: xsd:string

blockDeviceMapping Mapping that defines native device names to use when exposing
virtual devices. Returned if BlockDeviceMapping is specified.
Type: BlockDeviceMappingItemType[]

Sample Request - Launch Permission

https://ec2.amazonaws.com/
?Action=DescribeImageAttribute
&ImageId=ami-61a54008
&Attribute=launchPermission
&...auth parameters...

Sample Response - Launch Permission

<DescribeImageAttributeResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
<launchPermission>
<item>
<group>all</group>
</item>
<item>
<userId>495219933132</userId>
</item>
</launchPermission>
</DescribeImageAttributeResponse>

Sample Request - Product Codes

https://ec2.amazonaws.com/
?Action=DescribeImageAttribute
&ImageId=ami-61a54008
&Attribute=productCodes
&...auth parameters...

API Version 2008-02-01

136
 Amazon Elastic Compute Cloud Developer Guide
DescribeImages

Sample Response - Product Codes

<DescribeImageAttributeResponse xm
lns="http://ec2.amazonaws.com/doc/2007-01-03">
<imageId>ami-61a54008</imageId>
<productCodes>
<item>
<productCode>774F4FF8</productCode>
</item>
</productCodes>
</DescribeImageAttributeResponse>

Related Operations
• DescribeImages
• ModifyImageAttribute
• ResetImageAttribute

DescribeImages
The DescribeImages operation returns information about AMIs available to the user. This includes
public AMIs available for any user to launch, private AMIs owned by the user making the request, and
private AMIs owned by other users for which the user has explicit launch permissions.

Launch permissions fall into three categories:

Launch Description
Permission
public The owner of the AMI granted launch permissions for the AMI to the all group.
All users have launch permissions for these AMIs.
explicit The owner of the AMI granted launch permissions to a specific user.
implicit A user has implicit launch permissions for all AMIs he or she owns.

The list of AMIs returned can be modified by specifying AMI IDs, AMI owners, or users with launch
permissions. If no options are specified, Amazon EC2 returns all AMIs for which the user has launch
permissions.

If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned. If you specify
an invalid AMI ID, a fault is returned. If you specify an AMI ID for which you do not have access, it
will not be included in the returned results.

If you specify one or more AMI owners, only AMIs from the specified owners and for which you have
access are returned. The results can include the account IDs of the specified owners, amazon for AMIs
owned by Amazon or self for AMIs that you own.

If you specify a list of executable users, only users that have launch permissions for the AMIs are
returned. You can specify account IDs (if you own the AMI(s)), self for AMIs for which you own or
have explicit permissions, or all for public AMIs.

Note

API Version 2008-02-01

137
 Amazon Elastic Compute Cloud Developer Guide
DescribeImages

Deregistered images are included in the returned results for an unspecified interval after
deregistration.

If you use the DescribeImages operation on machine images, it displays the kernel IDs and RAM disk
IDs associated with the images. If you specify a kernel or RAM disk ImageType, it displays
information about kernel or RAM disk images.

Request Parameters
The following table describes the request parameters for DescribeImages. Parameter names are case
sensitive.

Name Description Required

ImageType The type of images to describe. Options include No
machine, kernel, or ramdisk.
Type: String

ImageId.n A list of image descriptions No

Type: String

Owner.n Owners of AMIs to describe. No

Type: String

ExecutableBy.n AMIs for which specified users have access. No

Type: String

Response Elements
The following table describes the default response tags included in DescribeImages responses.

Name Description
imagesSet A list of image descriptions.
Type: DescribeImagesResponseItemType[]

Sample Request
https://ec2.amazonaws.com/
?Action=DescribeImages
&ImageId.1=ami-be3adfd7
&...auth parameters...

Sample Response
<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imagesSet>
<item>
<imageId>ami-be3adfd7</imageId>
<imageLocation>ec2-public-images/fedora-8-i386-base-v1.04.manifest.xml</image

API Version 2008-02-01

138
 Amazon Elastic Compute Cloud Developer Guide
DescribeInstances

Location>
<imageState>available</imageState>
<imageOwnerId>206029621532</imageOwnerId>
<isPublic>false</isPublic>
<architecture>i386</architecture>
<imageType>machine</imageType>
<kernelId>aki-4438dd2d</kernelId>
<ramdiskId>ari-4538dd2c</ramdiskId>
</item>
</imagesSet>
</DescribeImagesResponse>

Related Operations
• DescribeInstances
• DescribeImageAttribute

DescribeInstances
The DescribeInstances operation returns information about instances that you own.

If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do
not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an
invalid instance ID, a fault is returned. If you specify an instance that you do not own, it will not be
included in the returned results.

Recently terminated instances might appear in the returned results. This interval is usually less than one
hour.

Request Parameters
The following table describes the request parameters for DescribeInstances. Parameter names are
case sensitive.

Name Description Required

InstanceId.n Set of instances IDs of which to get the status. No
Type: String

Response Elements
The following table describes the default response tags included in DescribeInstances responses.

Name Description
reservationSet A list of structures describing the status of all requested instances.
Type: ReservationInfoType

Sample Request
https://ec2.amazonaws.com/
?Action=DescribeInstances
&InstanceId.1=i-28a64341

API Version 2008-02-01

139
 Amazon Elastic Compute Cloud Developer Guide
DescribeKeyPairs

&...auth parameters...

Sample Response
<DescribeInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<reservationSet>
<item>
<reservationId>r-44a5402d</reservationId>
<ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
<groupSet>
<item>
<groupId>default</groupId>
</item>
</groupSet>
<instancesSet>
<item>
<instanceId>i-28a64341</instanceId>
<imageId>ami-6ea54007</imageId>
<instanceState>
<code>0</code>
<name>running</name>
</instanceState>
<privateDnsName>10-251-50-75.ec2.internal</privateDnsName>
<dnsName>ec2-72-44-33-4.compute-1.amazonaws.com</dnsName>
<keyName>example-key-name</keyName>
<productCodesSet>
<item><productCode>774F4FF8</productCode></item>
</productCodesSet>
<InstanceType>m1.small</InstanceType>
<launchTime>2007-08-07T11:54:42.000Z</launchTime>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
<kernelId>aki-ba3adfd3</kernelId>
<ramdiskId>ari-badbad00</ramdiskId>
</item>
</instancesSet>
</item>
</reservationSet>
</DescribeInstancesResponse>

Related Operations
• RunInstances
• TerminateInstances

DescribeKeyPairs
The DescribeKeyPairs operation returns information about key pairs available to you. If you specify
key pairs, information about those key pairs is returned. Otherwise, information for all registered key
pairs is returned.

Request Parameters
The following table describes the request parameters for DescribeKeyPairs. Parameter names are
case sensitive.

Name Description Required

KeyName.n Key pair IDs to describe. No
API Version 2008-02-01
140
 Amazon Elastic Compute Cloud Developer Guide
DescribeSecurityGroups

Name Description Required

Type: String

Response Elements
The following table describes the default response tags included in DescribeKeyPairs responses.

Name Description
keySet A list of key pair descriptions.
Type: DescribeKeyPairsResponseItemType[]

Sample Request
https://ec2.amazonaws.com/
?Action=DescribeKeyPairs
&KeyName.1=example-key-name
&...auth parameters...

Sample Response
<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<keySet>
<item>
<keyName>example-key-name</keyName>
<keyFingerprint>1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f</
keyFingerprint>
</item>
</keySet>
</DescribeKeyPairsResponse>

Related Operations
• CreateKeyPair
• DeleteKeyPair
• RunInstances

DescribeSecurityGroups
The DescribeSecurityGroups operation returns information about security groups that you own.

If you specify security group names, information about those security group is returned. Otherwise,
information for all security group is returned. If you specify a group that does not exist, a fault is
returned.

Request Parameters
The following table describes the request parameters for DescribeSecurityGroups. Parameter
names are case sensitive.

API Version 2008-02-01

141
 Amazon Elastic Compute Cloud Developer Guide
DescribeSecurityGroups

Name Description Required

GroupName.n List of security groups to describe. No
Type: String

Response Elements
The following table describes the default response tags included in DescribeSecurityGroups
responses.

Name Description
securityGroupInfo Information about security groups.
Type: SecurityGroupItemType[]

Sample Request
https://ec2.amazonaws.com/
?Action=DescribeSecurityGroups
&GroupName.1=WebServers
&GroupName.2=RangedPortsBySource
&...auth parameters...

Sample Response
<DescribeSecurityGroupsResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<securityGroupInfo>
<item>
<ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
<groupName>WebServers</groupName>
<groupDescription>Web</groupDescription>
<ipPermissions>
<item>
<ipProtocol>tcp</ipProtocol>
<fromPort>80</fromPort>
<toPort>80</toPort>
<groups/>
<ipRanges>
<item>
<cidrIp>0.0.0.0/0</cidrIp>
</item>
</ipRanges>
</item>
</ipPermissions>
</item>
<item>
<ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
<groupName>RangedPortsBySource</groupName>
<groupDescription>A</groupDescription>
<ipPermissions>
<item>
<ipProtocol>tcp</ipProtocol>
<fromPort>6000</fromPort>
<toPort>7000</toPort>
<groups/>
<ipRanges/>
</item>
</ipPermissions>

API Version 2008-02-01

142
 Amazon Elastic Compute Cloud Developer Guide
DisassociateAddress

</item>
</securityGroupInfo>
</DescribeSecurityGroupsResponse>

Related Operations
• CreateSecurityGroup
• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress
• DeleteSecurityGroup

DisassociateAddress
The DisassociateAddress operation disassociates the specified elastic IP address from the instance
to which it is assigned. This is an idempotent operation. If you enter it more than once, Amazon EC2
does not return an error.

Request Parameters
The following table describes the request parameters for DisassociateAddress. Parameter names are
case sensitive.

Name Description Required

PublicIp IP address that you are disassociating from the instance. Yes
Type: String

Response Elements
The following table describes the default response tags included in DisassociateAddress responses.

Name Description
return true if the IP address is disassociated from the instance.
Otherwise, false.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=DisassociateAddress
&PublicIp=67.202.55.255
&...auth parameters...

Sample Response
<DisassociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</DisassociateAddressResponse>

API Version 2008-02-01

143
 Amazon Elastic Compute Cloud Developer Guide
GetConsoleOutput

Related Operations
• AllocateAddress
• DescribeAddresses
• ReleaseAddress
• AssociateAddress

GetConsoleOutput
The GetConsoleOutput operation retrieves console output for the specified instance.

Instance console output is buffered and posted shortly after instance boot, reboot, and termination.
Amazon EC2 preserves the most recent 64 KB output which will be available for at least one hour after
the most recent post.

Request Parameters
The following table describes the request parameters for GetConsoleOutput. Parameter names are
case sensitive.

Name Description Required

InstanceId An instance ID returned from a previous call to Yes
RunInstances.
Type: String

Response Elements
The following table describes the default response tags included in GetConsoleOutput responses.

Name Description
instanceId The instance ID.
Type: xsd:string

timestamp The time the output was last updated.

Type: xsd:dateTime

output The console output, Base64 encoded.

Type: xsd:string

Sample Request
https://ec2.amazonaws.com/
?Action=GetConsoleOutput
&InstanceId=i-2ea64347
&...auth parameters...

Sample Response
API Version 2008-02-01
144
 Amazon Elastic Compute Cloud Developer Guide
ModifyImageAttribute

<GetConsoleOutputResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instanceId>i-28a64341</instanceId>
<timestamp>2007-01-03 15:00:00</timestamp>
<output>TGludXggdmVyc2lvbiAyLjYuMTYteGVuVSAoYnVpbGRlckBwYXRjaGJhdC5hbWF6b25zY
SkgKGdj
YyB2ZXJzaW9uIDQuMC4xIDIwMDUwNzI3IChSZWQgSGF0IDQuMC4xLTUpKSAjMSBTTVAgVGh1IE9j
dCAyNiAwODo0MToyNiBTQVNUIDIwMDYKQklPUy1wcm92aWRlZCBwaHlzaWNhbCBSQU0gbWFwOgpY
ZW46IDAwMDAwMDAwMDAwMDAwMDAgLSAwMDAwMDAwMDZhNDAwMDAwICh1c2FibGUpCjk4ME1CIEhJ
R0hNRU0gYXZhaWxhYmxlLgo3MjdNQiBMT1dNRU0gYXZhaWxhYmxlLgpOWCAoRXhlY3V0ZSBEaXNh
YmxlKSBwcm90ZWN0aW9uOiBhY3RpdmUKSVJRIGxvY2t1cCBkZXRlY3Rpb24gZGlzYWJsZWQKQnVp
bHQgMSB6b25lbGlzdHMKS2VybmVsIGNvbW1hbmQgbGluZTogcm9vdD0vZGV2L3NkYTEgcm8gNApF
bmFibGluZyBmYXN0IEZQVSBzYXZlIGFuZCByZXN0b3JlLi4uIGRvbmUuCg==</output>
</GetConsoleOutputResponse>

ModifyImageAttribute
The ModifyImageAttribute operation modifies an attribute of an AMI.

Attributes
Attribute Name Type Description
launchPermission List Controls who has permission to
launch the AMI. Launch
permissions can be granted to
specific users by adding userIds.
To make the AMI public, add
the all group.

productCodes List Associates a product code with

AMIs. This allows developers to
charge users for using AMIs.
The user must be signed up for
the product before they can
launch the AMI. This is a write
once attribute; after it is set, it
cannot be changed or removed.

Request Parameters
The following table describes the request parameters for ModifyImageAttribute. Parameter names
are case sensitive.

Name Description Required

ImageId AMI ID to modify. Yes
Type: String

Attribute Specifies the attribute to modify. See the preceding Yes

attributes table for supported attributes.
Type: String

OperationType Specifies the operation to perform on the attribute. See Conditional

the preceding attributes table for supported operations for
attributes.

API Version 2008-02-01

145
 Amazon Elastic Compute Cloud Developer Guide
ModifyImageAttribute

Name Description Required

Type: String
Valid Values: add | remove
Condition: Required for launchPermission

UserId.n User IDs to add to or remove from the Conditional

launchPermission attribute.
Type: String
Condition: Required for launchPermission

UserGroup.n User groups to add to or remove from the Conditional

launchPermission attribute. Currently, the all group
is available, which will make it a public AMI.
Type: String
Condition: Required for launchPermission

ProductCode.n Attaches a product code to the AMI. Currently only one Conditional
product code can be associated with an AMI. Once set,
the product code cannot be changed or reset.
Type: String
Condition: Required for productCodes

Response Elements
The following table describes the default response tags included in ModifyImageAttribute
responses.

Name Description
return true if the operation succeeded, otherwise false.
Type: xsd:boolean

Sample Request - Launch Permission

https://ec2.amazonaws.com/
?Action=ModifyImageAttribute
&ImageId=ami-61a54008
&Attribute=launchPermission
&OperationType=add
&Group.1=all
&UserId.1=495219933132
&...auth parameters...

Sample Request - Product Codes

https://ec2.amazonaws.com/
?Action=ModifyImageAttribute
&ImageId=ami-61a54008
&Attribute=productCodes
&ProductCode.1=774F4FF8
&...auth parameters...

API Version 2008-02-01

146
 Amazon Elastic Compute Cloud Developer Guide
RebootInstances

Sample Response
<ModifyImageAttributeResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</ModifyImageAttributeResponse>

Related Operations
• ResetImageAttribute
• DescribeImageAttribute

RebootInstances
The RebootInstances operation requests a reboot of one or more instances. This operation is
asynchronous; it only queues a request to reboot the specified instance(s). The operation will succeed if
the instances are valid and belong to the user. Requests to reboot terminated instances are ignored.

Request Parameters
The following table describes the request parameters for RebootInstance. Parameter names are case
sensitive.

Name Description Required

InstanceId.n One or more instance IDs. Yes
Type: String

Response Elements
The following table describes the default response tags included in RebootInstances responses.

Name Description
result true if the operation succeeded.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=RebootInstances
&InstanceId.1=i-2ea64347
&InstanceId.2=i-21a64348
&...auth parameters...

Sample Response
<RebootInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>

API Version 2008-02-01

147
 Amazon Elastic Compute Cloud Developer Guide
ReleaseAddress

</RebootInstancesResponse>

ReleaseAddress
The ReleaseAddress operation releases an elastic IP address associated with your account.

If you run this operation on an elastic IP address that is already released, the address might be assigned
to another account which will cause Amazon EC2 to return an error.

Note

Releasing an IP address automatically disassociates it from any instance with which it is

associated. For more information, see DisassociateAddress.

Important

After releasing an elastic IP address, it is released to the IP address pool and might no
longer be available to your account. Make sure to update your DNS records and any
servers or devices that communicate with the address.

Request Parameters
The following table describes the request parameters for ReleaseAddress. Parameter names are case
sensitive.

Name Description Required

PublicIp IP address that you are releasing from your account. Yes
Type: String

Response Elements
The following table describes the default response tags included in ReleaseAddress responses.

Name Description
return true if the IP address is released. Otherwise, false.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=ReleaseAddress
&PublicIp=67.202.55.255
&...auth parameters...

Sample Response
<ReleaseAddressResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">

API Version 2008-02-01

148
 Amazon Elastic Compute Cloud Developer Guide
RegisterImage

<return>true</return>
</ReleaseAddressResponse>

Related Operations
• AllocateAddress
• DescribeAddresses
• AssociateAddress
• DisassociateAddress

RegisterImage
The RegisterImage operation registers an AMI with Amazon EC2. Images must be registered before
they can be launched. For more information, see RunInstances.

Each AMI is associated with an unique ID which is provided by the Amazon EC2 service through the
RegisterImage operation. During registration, Amazon EC2 retrieves the specified image manifest
from Amazon S3 and verifies that the image is owned by the user registering the image.

The image manifest is retrieved once and stored within the Amazon EC2. Any modifications to an
image in Amazon S3 invalidates this registration. If you make changes to an image, deregister the
previous image and register the new image. For more information, see DeregisterImage.

Request Parameters
The following table describes the request parameters for RegisterImage. Parameter names are case
sensitive.

Name Description Required

ImageLocation Full path to your AMI manifest in Amazon S3 storage. Yes
Type: String

Response Elements
The following table describes the default response tags included in RegisterImage responses.

Name Description
imageId Unique ID of the newly registered machine image.
Type: xsd:string

Sample Request
https://ec2.amazonaws.com/
?Action=RegisterImage
&ImageLocation=mybucket-myimage.manifest.xml
&...auth parameters...

API Version 2008-02-01

149
 Amazon Elastic Compute Cloud Developer Guide
ResetImageAttribute

Sample Response
<RegisterImageResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<imageId>ami-61a54008</imageId>
</RegisterImageResponse>

Related Operations
• DescribeImages
• DeregisterImage

ResetImageAttribute
The ResetImageAttribute operation resets an attribute of an AMI to its default value.

Note

The productCodes attribute cannot be reset.

Request Parameters
The following table describes the request parameters for ResetImageAttribute. Parameter names are
case sensitive.

Name Description Required

ImageId ID of the AMI for which an attribute will be described. Yes
Type: String

Attribute Specifies the attribute to reset. Currently, only Yes

launchPermission is supported. In the case of
launchPermission, all public and explicit launch
permissions for the AMI are revoked.
Type: String

Response Elements
The following table describes the default response tags included in ResetImageAttribute responses.

Name Description
return true if the operation succeeded, otherwise false.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/

API Version 2008-02-01

150
 Amazon Elastic Compute Cloud Developer Guide
RevokeSecurityGroupIngress

?Action=ResetImageAttribute
&ImageId=ami-61a54008
&Attribute=launchPermission
&...auth parameters...

Sample Response
<ResetImageAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</ResetImageAttributeResponse>

Related Operations
• ModifyImageAttribute
• DescribeImageAttribute

RevokeSecurityGroupIngress
The RevokeSecurityGroupIngress operation revokes permissions from a security group. The
permissions used to revoke must be specified using the same values used to grant the permissions.

Permissions are specified by IP protocol (TCP, UDP, or ICMP), the source of the request (by IP range or
an Amazon EC2 user-group pair), the source and destination port ranges (for TCP and UDP), and the
ICMP codes and types (for ICMP).

Permission changes are quickly propagated to instances within the security group. However, depending
on the number of instances in the group, a small delay is might occur, .

When revoking a user/group pair permission, GroupName, SourceSecurityGroupName and

SourceSecurityGroupOwnerId must be specified. When authorizing a CIDR IP permission,
GroupName, IpProtocol, FromPort, ToPort and CidrIp must be specified. Mixing these two types
of parameters is not allowed.

Request Parameters
The following table describes the request parameters for RevokeSecurityGroupIngress. Parameter
names are case sensitive.

Name Description Required

GroupName Name of the group to modify. Yes
Type: String

SourceSecurityGroupName Name of security group to revoke access Conditional

to when operating on a user/group pair.
Type: String
Condition: Required when revoking
user/group pair permission.

SourceSecurityGroupOwnerId Owner of security group to revoke access Conditional

to when operating on a user/group pair.
Type: String
Condition: Required when revoking
API Version 2008-02-01
151
 Amazon Elastic Compute Cloud Developer Guide
RevokeSecurityGroupIngress

Name Description Required

user/group pair permission.

IpProtocol IP protocol to revoke access to when Conditional

operating on a CIDR IP.
Type: String
Valid Values: tcp | udp | icmp
Condition: Required when revoking CIDR
IP permission.

FromPort Bottom of port range to revoke access to Conditional

when operating on a CIDR IP. This
contains the ICMP type if ICMP is being
authorized.
Type: Int
Condition: Required when revoking CIDR
IP permission.

ToPort Top of port range to revoke access to Conditional

when operating on a CIDR IP. This
contains the ICMP code if ICMP is being
authorized.
Type: Int
Condition: Required when revoking CIDR
IP permission.

CidrIp CIDR IP range to revoke access to when Conditional

operating on a CIDR IP.
Type: String
Condition: Required when revoking CIDR
IP permission.

Response Elements
The following table describes the default response tags included in RevokeSecurityGroupIngress
responses.

Name Description
return true if permissions successfully revoked.
Type: xsd:boolean

Sample Request
https://ec2.amazonaws.com/
?Action=AuthorizeSecurityGroupIngress
&IpProtocol=tcp
&FromPort=80
&ToPort=80
&CidrIp=0.0.0.0/0
&...auth parameters...

API Version 2008-02-01

152
 Amazon Elastic Compute Cloud Developer Guide
RunInstances

Sample Response
<RevokeSecurityGroupIngressResponse xm
lns="http://ec2.amazonaws.com/doc/2008-02-01">
<return>true</return>
</RevokeSecurityGroupIngressResponse>

Related Operations
• CreateSecurityGroup
• DescribeSecurityGroups
• AuthorizeSecurityGroupIngress
• DeleteSecurityGroup

RunInstances
The RunInstances operation launches a specified number of instances.

Note

The Query version of RunInstances only allows instances of a single AMI to be

launched in one call. This is different from the SOAP API version of the call, but similar to
the ec2-run-instances command line tool.

If Amazon EC2 cannot launch the minimum number AMIs you request, no instances launch. If there is
insufficient capacity to launch the maximum number of AMIs you request, Amazon EC2 launches as
many as possible to satisfy the requested maximum values.

Every instance is launched in a security group. If you do not specify a security group at launch, the
instances start in your default security group. For more information on creating security groups, see
CreateSecurityGroup.

An optional instance type can be specified. For information about instance types, see Instance Types.

You can provide an optional key pair ID for each image in the launch request (see CreateKeyPair. All
instances that are created from images that use this key pair will have access to the associated public key
at boot. You can use this key to provide secure access to an instance of an image on a per-instance basis.
Amazon EC2 public images use this feature to provide secure access without passwords.

Important

Launching public images without a key pair ID will leave them inaccessible.

The public key material is made available to the instance at boot time by placing it in the
openssh_id.pub file on a logical device that is exposed to the instance as /dev/sda2 (the ephemeral
store). The format of this file is suitable for use as an entry within ~/.ssh/authorized_keys (the
OpenSSH format). This can be done at boot (e.g., as part of rc.local) allowing for secure access
without passwords.

API Version 2008-02-01

153
 Amazon Elastic Compute Cloud Developer Guide
RunInstances

Optional user data can be provided in the launch request. All instances comprising the launch request
have access to this data (see Instance Metadata for details).

Note

If any of the AMIs have a product code attached for which the user has not subscribed, the
RunInstances call will fail.

Request Parameters
The following table describes the request parameters for RunInstances. Parameter names are case
sensitive.

Name Description Required

ImageId ID of the AMI with which to launch instances. Yes
Type: String

MinCount Minimum number of instances to launch. Yes

Type: Int

MaxCount Maximum number of instances to launch. Yes

Type: Int

KeyName Name of the key pair with which to launch instances. No

Type: String

SecurityGroup.n Names of the security groups with which to associate No

the instances.
Type: String

UserData The user data available to the launched instances. No

This should be Base64 encoded. For more
information on encoding details, see UserDataType.
Type: String

InstanceType This specifies the instance type. No

Options include m1.small, m1.large, and
m1.xlarge.
The default value is m1.small.
For more information on instance types, see Instance
Types.
Type: xsd:string

Placement.AvailabilityZone Specifies the availability zone in which to launch the No

instance(s).
To display a list of availability zones in which you
can launch the instances, use the
DescribeAvailabilityZones operation. For
more information, see DescribeAvailabilityZones.
For more information on instance types, see
Availability Zones.

API Version 2008-02-01

154
 Amazon Elastic Compute Cloud Developer Guide
RunInstances

Name Description Required

Type: xsd:string
By default, Amazon EC2 selects an availability zone
for you.

KernelId The ID of the kernel with which to launch the No

instance. For information on finding available kernel
IDs, see ec2-describe-images.
Example: aki-ba3adfd3

RamdiskId The ID of the RAM disk with which to launch the No

instance.
Some kernels require additional drivers at launch.
Check the kernel requirements for information on
whether you need to specify a RAM disk. To find
kernel requirements, go to the Resource Center and
search for the kernel ID.
Example: ari-badbad00

BlockDeviceMapping. Specifies the virtual name to map to the No

n.VirtualName corresponding device name. For example:
ephemeral0
This parameter must be used in conjunction with
BlockDeviceMapping.n.DeviceName.

BlockDeviceMapping. Specifies the device to which you are mapping a No

n.DeviceName virtual name. For example: sdb
This parameter must be used in conjunction with
BlockDeviceMapping.n.VirtualName.

Response Elements
The following table describes the default response tags included in RunInstances responses.

Name Description
RunInstancesResponse Status information about the instances launched.
Type: ReservationInfoType

Sample Request
https://ec2.amazonaws.com/
?Action=RunInstances
&ImageId=ami-60a54009
&MaxCount=3
&MinCount=1
&AddressingType=public
&Placement.AvailabilityZone=us-east-1b
&...auth parameters...

Sample Response
API Version 2008-02-01
155
 Amazon Elastic Compute Cloud Developer Guide
RunInstances

<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<reservationId>r-47a5402e</reservationId>
<ownerId>495219933132</ownerId>
<groupSet>
<item>
<groupId>default</groupId>
</item>
</groupSet>
<instancesSet>
<item>
<instanceId>i-2ba64342</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<privateDnsName></privateDnsName>
<dnsName></dnsName>
<keyName>example-key-name</keyName>
<amiLaunchIndex>0</amiLaunchIndex>
<InstanceType>m1.small</InstanceType>
<launchTime>2007-08-07T11:51:50.000Z</launchTime>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
</item>
<item>
<instanceId>i-2bc64242</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<privateDnsName></privateDnsName>
<dnsName></dnsName>
<keyName>example-key-name</keyName>
<amiLaunchIndex>1</amiLaunchIndex>
<InstanceType>m1.small</InstanceType>
<launchTime>2007-08-07T11:51:50.000Z</launchTime>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
</item>
<item>
<instanceId>i-2be64332</instanceId>
<imageId>ami-60a54009</imageId>
<instanceState>
<code>0</code>
<name>pending</name>
</instanceState>
<privateDnsName></privateDnsName>
<dnsName></dnsName>
<keyName>example-key-name</keyName>
<amiLaunchIndex>2</amiLaunchIndex>
<InstanceType>m1.small</InstanceType>
<launchTime>2007-08-07T11:51:50.000Z</launchTime>
<placement>
<availabilityZone>us-east-1b</availabilityZone>
</placement>
</item>
</instancesSet>
</RunInstancesResponse>

Related Operations
• DescribeInstances
• TerminateInstances

API Version 2008-02-01

156
 Amazon Elastic Compute Cloud Developer Guide
TerminateInstances

• AuthorizeSecurityGroupIngress
• RevokeSecurityGroupIngress
• DescribeSecurityGroups

TerminateInstances
The TerminateInstances operation shuts down one or more instances. This operation is idempotent;
if you terminate an instance more than once, each call will succeed.

Terminated instances will remain visible after termination (approximately one hour).

Request Parameters
The following table describes the request parameters for TerminateInstances. Parameter names are
case-sensitive.

Name Description Required

InstanceId.n One or more instance IDs returned. Yes
Type: String

Response Elements
The following table describes the default response tags included in TerminateInstances responses.

Name Description
instancesSet A complex type describing the current and new state of each
instance specified.
Type: TerminateInstancesResponseInfoType[]

Sample Request
https://ec2.amazonaws.com/
?Action=TerminateInstances
&InstanceId.1=i-2ea64347
&InstanceId.2=i-21a64348
&...auth parameters...

Sample Response
<TerminateInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2008-02-01">
<instancesSet>
<item>
<instanceId>i-28a64341</instanceId>
<shutdownState>
<code>32</code>
<name>shutting-down</name>
</shutdownState>
<previousState>
<code>16</code>
<name>running</name>
</previousState>

API Version 2008-02-01

157
 Amazon Elastic Compute Cloud Developer Guide
TerminateInstances

</item>
<item>
<instanceId>i-21a64348</instanceId>
<shutdownState>
<code>32</code>
<name>shutting-down</name>
</shutdownState>
<previousState>
<code>16</code>
<name>running</name>
</previousState>
</item>
</instancesSet>
</TerminateInstancesResponse>

Related Operations
• DescribeInstances

API Version 2008-02-01

158
 Amazon Elastic Compute Cloud Developer Guide
Introduction

Command Line Tools Reference

Introduction
The Amazon EC2 command line tools provide a command line interface to the web service API. This
section describes each tool and its command line arguments in detail.

Command line options and arguments are based on the GNU getopt conventions. Parameters are
invoked using flags, which typically come in short and long form. In their short form, flags use a single
character preceded by a dash. In their long form, flags use a more expressive name preceded by two
dashes.

Note

Some common options apply to all command line tools. These are described below and are
not included in the description of the specific tools.

Errors
Any service errors encountered by the command line tools are passed straight through from the API. For
more information about these errors, see API Error Codes.

Common Options
Most command line tools described in this section accept the following set of optional parameters:

Option Description
-U URL URL is the uniform resource locator of the Amazon EC2 web service
entry point.
Default: The EC2_URL environment variable, or
http://ec2.amazonaws.com if the environment variable is not set.
Example: -U http://ec2.amazonaws.com

-K EC2-PRIVATE-KEY The private key to use when constructing requests to Amazon EC2.

API Version 2008-02-01

159
 Amazon Elastic Compute Cloud Developer Guide
AMI Tools

Option Description
Default: The value of the EC2_PRIVATE_KEY environment variable.
Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

-C EC2-CERT The X.509 certificate to use when constructing requests to

Amazon EC2.
Default: The value of the EC2_CERT environment variable.
Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

-v Displays verbose output by showing the SOAP request and response on

the command line. This is particularly useful if you are building tools to
talk directly to our SOAP API.

--show-empty-fields Shows empty columns as (nil).

--debug Prints internal debugging information. This is useful to assist us when

troubleshooting problems.

-? Displays help.

- If - is specified as an argument to one of the parameters, a list of

arguments are read from standard input. This is useful for piping the
output of one command into the input of another.
Example: ec2-describe-instances | grep running | cut
-f 2 | ec2-terminate-instances -i -

AMI Tools
This section describes each tool used to create AMIs and its command line arguments in detail.

ec2-bundle-image
Syntax
ec2-bundle-image -k private_key -c ec2_cert -u user_id -i image_path -r {i386
| x86_64} [-d destination] [-p ami_prefix] [-b, --batch] [--kernel kernel-id]
[--ramdisk ramdisk_id] [--block-device-mappingblock_device_mapping]

Description
Create a bundled AMI from an operating system image created in a loopback file. For more information,
see Creating an AMI through a Loopback File.

Note

Scripts that require a copy of the public key from the launch key pair must obtain the key
from the instance's metadata (not the key file in the ephemeral store) for instances bundled
with the 2007-08-29 AMI tools and later. AMIs bundled before this release will continue
to work normally.

API Version 2008-02-01

160
 Amazon Elastic Compute Cloud Developer Guide
ec2-bundle-image

Options
Note

This tool does not support the Common Options.

Option Description Required

-k, --privatekey The path to the user's PEM-encoded RSA key file. Yes
private_key Example: -k
pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

-c, --cert ec2_cert The user's PEM encoded RSA public key certificate Yes
file.
Example: -c
cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

-u, --user user_id The user's AWS account number without dashes. Do Yes
not use the Access Key ID.
Example: -u 495219933132

-i, --image image_path The path to the image to bundle. Yes

Example: -i
/var/spool/my-image/version-2/debian.img

-r, --arch {i386 | Specifies 32-bit (m1.small) or 64-bit architecture Yes

x86_64} (m1-large and m1-xlarge).
Default: None
Example: -r x86_64

-d, --destination The directory in which to create the bundle. No

destination Default: The current directory
Example: -d /var/run/my-bundle

-p, --prefix ami_prefix The filename prefix for bundled AMI files. No
Default: image
Example: -p my-image-is-special

--help Display the help message. No

Example: --help

--manual Display the manual entry. No

Example: --manual

-b, --batch Runs without interaction and suppresses all warnings. No

Will attempt to automatically determine architecture.
Example: -b

--kernel kernel_id The ID of the kernel to select. For information on No

finding available kernel IDs, see
ec2-describe-images.
Example: aki-ba3adfd3
API Version 2008-02-01
161
 Amazon Elastic Compute Cloud Developer Guide
ec2-bundle-vol

Option Description Required

--ramdisk ramdisk_id The ID of the RAM disk to select. No

Some kernels require additional drivers at launch.
Check the kernel requirements for information on
whether you need to specify a RAM disk. To find
kernel requirements, go to the Resource Center and
search for the kernel ID.
Example: ari-badbad00

--block-device-mappings Specifies how block devices are exposed. . No

mappings Virtual name example: ephemeral0
Device name example: sdb

Output
Status messages describing the stages and status of the bundling process.

Example
This example creates a bundled AMI from an operating system image that was created in a loopback
file:
$ ec2-bundle-image -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -c cert-
HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -u 495219933132 -i image.img -d bundled/
-p fred -r x86_64
Splitting bundled/fred.gz.crypt...
Created fred.part.00
Created fred.part.01
Created fred.part.02
Created fred.part.03
Created fred.part.04
Created fred.part.05
Created fred.part.06
Created fred.part.07
Created fred.part.08
Created fred.part.09
Created fred.part.10
Created fred.part.11
Created fred.part.12
Created fred.part.13
Created fred.part.14
Generating digests for each part...
Digests generated.
Creating bundle manifest...
Bundle Image complete.

Related Topics
• ec2-bundle-vol
• ec2-unbundle
• ec2-upload-bundle
• ec2-download-bundle
• ec2-delete-bundle

API Version 2008-02-01

162
 Amazon Elastic Compute Cloud Developer Guide
ec2-bundle-vol

ec2-bundle-vol
Syntax
ec2-bundle-vol -k private_key -u user_id -c ec2_cert -r {i386 | x86_64} [-s
size] [-d destination] [-e exclude_directory_1,exclude_directory_1,...] [-p
ami_prefix] [-v volume] [--ec2cert ami_path] [--fstab fstab_path] [--kernel
kernel-id] [--ramdisk ramdisk_id]
[--block-device-mappingblock_device_mapping] [-b, --batch]

Description
Creates a bundled AMI by compressing, encrypting and signing a snapshot of the local machine's root
file system.

Note

Scripts that require a copy of the public key from the launch key pair must obtain the key
from the instance's metadata (not the key file in the ephemeral store) for instances bundled
with the 2007-08-29 AMI tools and later. AMIs bundled before this release will continue
to work normally.
On a running instance, Amazon EC2 attempts to inherit product codes, kernel settings,
RAM disk settings, and block device mappings with which the instance launched.

Options
Note

This tool does not support the Common Options

Option Description Required

-k, --privatekey The path to the user's PEM-encoded RSA key file. Yes
private_key Example: -k
pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

-c, --cert ec2_cert The user's PEM encoded RSA public key certificate Yes
file.
Example: -c
cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

-u, --user user_id The user's AWS account number without dashes. Do Yes
not use the Access Key ID.
Example: -u 495219933132

-r, --arch {i386 | Specifies 32-bit (m1.small) or 64-bit architecture Yes

x86_64} (m1-large and m1-xlarge).
Example: -r i386

-s, --size size The size, in MB (1024 * 1024 bytes), of the image No
file to create. The maximum size is 10240 MB.
Default: 10240

API Version 2008-02-01

163
 Amazon Elastic Compute Cloud Developer Guide
ec2-bundle-vol

Option Description Required

Example: -s 2048

-d, --destination The directory in which to create the bundle. No

destination Default: /tmp
Example: -d /var/run/my-bundle

-e, --exclude A list of absolute directory paths to exclude from the No

bundle operation. This overrides the --all
directory_1,directory_2,...
parameter.
Example: -e /tmp,/home/secret-data

-p, --prefix ami_prefix The filename prefix for bundled AMI files. No
Default: image
Example: -p my-image-is-special

-v, --volume volume The absolute path to the mounted volume from which No
to create the bundle.
Default: The root directory (/)
Example: -v /mnt/my-customized-ami

-a, --all Bundle all directories, including those on remotely No

mounted filesystems.
Example: -a

--ec2cert ami_path The path to the Amazon EC2 X509 public key No
certificate.
Default: /etc/aes/amiutil/cert-ec2.pem
Example: --ec2cert
/etc/aes/amiutil/cert-ec2.pem

--help Display the help message. No

Example: --help

--manual Display the manual entry. No

Example: --manual

--fstab fstab_path The path to the fstab to bundle into the image. If this No
is not specified, Amazon EC2 will provide its own
fstab.
Example: --fstab /etc/fstab

-b, --batch Runs without interaction and suppresses all warnings. No

Will attempt to automatically determine architecture.
Example: -b

--kernelkernel_id The ID of the kernel to select. For information on No

finding available kernel IDs, see
ec2-describe-images.
Example: aki-ba3adfd3

--ramdiskramdisk_id The ID of the RAM disk to select. No

API Version 2008-02-01

164
 Amazon Elastic Compute Cloud Developer Guide
ec2-bundle-vol

Option Description Required

Some kernels require additional drivers at launch.
Check the kernel requirements for information on
whether you need to specify a RAM disk. To find the
kernel requirements, go to the Resource Center and
search for the kernel ID.
Example: ari-badbad00

Specifies how block devices are exposed. .

--block-device-mappingsmappings No
Virtual name example: ephemeral0
Device name example: sdb

Output
Status messages describing the stages and status of the bundling

Example
This example creates a bundled AMI by compressing, encrypting and signing a snapshot of the local
machine's root file system.
$ ec2-bundle-vol -d /mnt -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -c cert-
HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -u 495219933132 -r x86_64
Copying / into the image file /mnt/image.img...
Excluding:
sys
dev/shm
proc
dev/pts
proc/sys/fs/binfmt_misc
dev
media
mnt
proc
sys
tmp/image.img
mnt/img-mnt
1+0 records in
1+0 records out
mke2fs 1.38 (30-Jun-2005)
warning: 256 blocks unused.
Splitting /mnt/image.gz.crypt...
Created image.part.00
Created image.part.01
Created image.part.02
Created image.part.03
...
Created image.part.22
Created image.part.23
Generating digests for each part...
Digests generated.
Creating bundle manifest...
Bundle Volume complete.

Related Topics
• ec2-bundle-image

API Version 2008-02-01

165
 Amazon Elastic Compute Cloud Developer Guide
ec2-delete-bundle

• ec2-unbundle
• ec2-upload-bundle
• ec2-download-bundle
• ec2-delete-bundle

ec2-delete-bundle
Syntax
ec2-delete-bundle -b s3_bucket -a access_key_id -s secret_key [-m
manifest_path] [-p ami_prefix] [--url url] [--retry] [-y] [--clear]

Description
Deletes the specified bundle from Amazon S3 storage.

Options
Note

This tool does not support the Common Options.

Option Description Required

-b, --bucket The name of the Amazon S3 bucket containing the Yes
s3_bucket bundled AMI
Example: -b aes-cracker-ami-bucket

-a, --access-key The AWS access key ID. Yes

access_key_id Example: -a 10QMXFEV71ZS32XQFTR2

-s, --secret-key The AWS secret access key. Yes

secret_key Example: -s
DMADSSfPfdaDjbK+RRUhS/aDrjsiZadgAUm8gRU2

-m, --manifest The path to the unencrypted manifest file. No

manifest_path Example: -m
/var/spool/my-first-bundle/Manifest

-p, --prefix The bundled AMI filename prefix. No

ami_prefix Example: -p eos-

--url url The Amazon S3 service URL. No

Default: https://s3.amazonaws.com
Example: --url https://s3.amazonaws.ie

--retry Automatically retries failed uploads. Use with No

caution.
Example: --retry

-y, --yes Automatically assumes the answer to all prompts is No

API Version 2008-02-01

166
 Amazon Elastic Compute Cloud Developer Guide
ec2-download-bundle

Option Description Required

'yes'.
Example: -y

--help Display the help message. No

Example: --help

--manual Display the manual entry. No

Example: --manual

--clear Deletes the specified bundle from the Amazon S3 No

bucket and deletes the bucket, if empty.
Example: --clear

Output
Amazon EC2 displays status messages indicating the stages and status of the delete process.

Example
This example deletes a bundle from Amazon S3:
$ ec2-delete-bundle -b my-s3-bucket -a 10QMXFEV71ZS32XQFTR2 -s DMADSSfPfdaD
jbK+RRUhS/aDrjsiZadgAUm8gRU2 -p fred
Deleting files:
my-s3-bucket/fred.manifest.xml
my-s3-bucket/fred.part.00
my-s3-bucket/fred.part.01
my-s3-bucket/fred.part.02
my-s3-bucket/fred.part.03
my-s3-bucket/fred.part.04
my-s3-bucket/fred.part.05
my-s3-bucket/fred.part.06
Continue? [y/n]
y
Deleted my-s3-bucket/fred.manifest.xml
Deleted my-s3-bucket/fred.part.00
Deleted my-s3-bucket/fred.part.01
Deleted my-s3-bucket/fred.part.02
Deleted my-s3-bucket/fred.part.03
Deleted my-s3-bucket/fred.part.04
Deleted my-s3-bucket/fred.part.05
Deleted my-s3-bucket/fred.part.06
ec2-delete-bundle complete.

Related Topics
• ec2-bundle-image
• ec2-bundle-vol
• ec2-unbundle
• ec2-upload-bundle
• ec2-download-bundle

API Version 2008-02-01

167
 Amazon Elastic Compute Cloud Developer Guide
ec2-download-bundle

ec2-download-bundle
Syntax
ec2-download-bundle -b s3_bucket -m manifest -a access_key_id -s secret_key
-k private_key [-p ami_prefix] [-d directory] [--url url]

Description
Download the specified bundles from S3 storage.

Options
Note

This tool does not support the Common Options.

Option Description Required

b, --bucket The name of the Amazon S3 bucket where the bundle Yes
-s3_bucket is located.
Example: -b aes-cracked

-m, --manifest The manifest path and filename. Yes

manifest Example: -m
/var/spool/my-first-bundle/Manifest

-a, --access-key Your AWS access key ID. Yes

access_key_id Example: -a 10QMXFEV71ZS32XQFTR2

-s, --secret-key Your AWS secret access key. Yes

secret_key Example: -s
DMADSSfPfdaDjbK+RRUhS/aDrjsiZadgAUm8gRU2

-k, --privatekey The private key used to decrypt the manifest. Yes
private_key Example: -k
pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

-p, --prefix The filename prefix for the bundled AMI files. No
ami_prefix Default: image
Example: -p my-image

-d, --directory The directory where the downloaded bundles are No

directory saved. The directory must exist.
Default: The current working directory
Example: -d /tmp/my-downloaded-bundle

--url url The S3 service URL. No

Default: https://s3.amazonaws.com
Example: --url https://s3.amazonaws.ie

--help Display the help message. No

API Version 2008-02-01

168
 Amazon Elastic Compute Cloud Developer Guide
ec2-unbundle

Option Description Required

Example: --help

Output
Status messages indicating the various stages of the download process are displayed.

Example
This example downloads creates the bundled directory and downloads the bundle from the
my-s3-bucket Amazon S3 bucket.

$ mkdir bundled
$ ec2-download-bundle -b my-s3-bucket -m fred.manifest.xml -a
10QMXFEV71ZS32XQFTR2 -s DMADSSfPfdaDjbK+RRUhS/aDrjsiZadgAUm8gRU2 -k pk-
HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -d bundled
downloading manifest https://s3.amazonaws.com/my-s3-bucket/image.manifest.xml
to bundled/image.manifest.xml ...
downloading part https://s3.amazonaws.com/my-s3-bucket/image.part.00 to
bundled/image.part.00 ...
Downloaded image.part.00 from https://s3.amazonaws.com/my-s3-bucket.
downloading part https://s3.amazonaws.com/my-s3-bucket/image.part.01 to
bundled/image.part.01 ...
Downloaded image.part.01 from https://s3.amazonaws.com/my-s3-bucket.
downloading part https://s3.amazonaws.com/my-s3-bucket/image.part.02 to
bundled/image.part.02 ...
Downloaded image.part.02 from https://s3.amazonaws.com/my-s3-bucket.
downloading part https://s3.amazonaws.com/my-s3-bucket/image.part.03 to
bundled/image.part.03 ...
Downloaded image.part.03 from https://s3.amazonaws.com/my-s3-bucket.
downloading part https://s3.amazonaws.com/my-s3-bucket/image.part.04 to
bundled/image.part.04 ...
Downloaded image.part.04 from https://s3.amazonaws.com/my-s3-bucket.
downloading part https://s3.amazonaws.com/my-s3-bucket/image.part.05 to
bundled/image.part.05 ...
Downloaded image.part.05 from https://s3.amazonaws.com/my-s3-bucket.
downloading part https://s3.amazonaws.com/my-s3-bucket/image.part.06 to
bundled/image.part.06 ...
Downloaded image.part.06 from https://s3.amazonaws.com/my-s3-bucket.
Download Bundle complete.

Related Topics
• ec2-bundle-image
• ec2-bundle-vol
• ec2-unbundle
• ec2-upload-bundle
• ec2-delete-bundle

ec2-unbundle
Syntax
ec2-unbundle -m manifest -k private_key [-d destination_directory] [-s
source_directory]

API Version 2008-02-01

169
 Amazon Elastic Compute Cloud Developer Guide
ec2-unbundle

Description
Recreates the AMI from the bundled AMI parts.

Options
Note

This tool does not support the Common Options.

Option Description Required

-m, --manifest manifest The path to the unencrypted AMI manifest file. Yes
Example: -m
/var/spool/my-first-bundle/Manifest

-k, --privatekey The path to your PEM-encoded RSA key file. Yes
private_key Example: -k $HOME/pk-234242DEADCAFE.pem

-d, --destination The directory in which to unbundle the AMI. The No

destination_directory destination directory must exist.
Default: The current directory
Example: -d /tmp/my-image

-s, --source The directory containing the bundled AMI parts. No

source_directory Default: The current directory
Example: -s /tmp/my-bundled-image

--help Display the help message. No

Example: --help

Example
This example unbundles the AMI specified in the fred.manifest.xml file:
$ mkdir unbundled
$ ec2-unbundle -m fred.manifest.xml -s bundled -d unbundled
cat bundled/fred.part.00 bundled/fred.part.01 bundled/fred.part.02 bundled/
fred.part.03 bundled/fred.part.04 bundled/fred.part.05 bundled/fred.part.06
bundled/fred.part.07 bundled/fred.part.08 bundled/fred.part.09 bundled/
fred.part.10 bundled/fred.part.11 bundled/fred.part.12 bundled/fred.part.13
bundled/fred.part.14 | openssl enc -d -aes-128-cbc -K
a8fbe9586b7fd3df893b237f88e351a9 -iv 121febdf64b0322cd4ffda03aa1ab535 | gun
zip > unbundled/fred.img
Unbundle complete.
$ ls -l unbundled
total 1025008
-rw-r--r-- 1 root root 1048578048 Aug 25 23:46 fred.img

Output
Status messages indicating the various stages of the unbundling process are displayed.

API Version 2008-02-01

170
 Amazon Elastic Compute Cloud Developer Guide
ec2-upload-bundle

Related Topics
• ec2-bundle-image
• ec2-bundle-vol
• ec2-upload-bundle
• ec2-download-bundle
• ec2-delete-bundle

ec2-upload-bundle
Syntax
ec2-upload-bundle -b s3_bucket -m manifest -a access_key_id -s secret_key
[--acl acl] [--ec2cert certificate] [-d directory] [--part part] [--url url]
[--retry] [--skipmanifest]

Description
Upload a bundled AMI to Amazon S3 storage.

Options
Note

This tool does not support the Common Options.

Option Description Required

-b, --bucket The name of the Amazon S3 bucket in which to store Yes
s3_bucket the bundle. If the bucket doesn't exist it will be
created (if the bucket name is available).
Example: -b aes-cracker-ami

-m, --manifest The path to the manifest file. The manifest file is Yes
manifest created during the bundling process and can be found
in the directory containing the bundle.
Example: -m
/var/spool/my-first-bundle/Manifest

-a, --access-key Your AWS access key ID. Yes

access_key_id Example: -a 10QMXFEV71ZS32XQFTR2

-s, --secret-key Your AWS secret access key. Yes

secret_key Example: -s
DMADSSfPfdaDjbK+RRUhS/aDrjsiZadgAUm8gRU2

--acl acl The access control list policy of the bundled image. No
Valid Values: public-read | aws-exec-read
Default: aws-exec-read
Example: --acl public-read
API Version 2008-02-01
171
 Amazon Elastic Compute Cloud Developer Guide
ec2-upload-bundle

Option Description Required

--ec2cert The path to the Amazon EC2 X509 public key No

certificate certificate.
Default: /etc/aes/amiutil/cert-ec2.pem
Example: --ec2cert
/etc/aes/amiutil/cert-ec2.pem

-d, --directory The directory containing the bundled AMI parts. No

directory Default: The directory containing the manifest file
(see the -m option).
Example: -d /var/run/my-bundle

--part part Starts uploading the specified part and all subsequent No
parts.
Example: --part

--url url The S3 service URL. No

Default: https://s3.amazonaws.com
Example: --url https://s3.amazonaws.ie

--retry Automatically retries failed uploads. Use with No

caution.
Example: --retry

--skipmanifest Does not upload the manifest. No

Example: --skipmanifest

--help Display the help message. No

Example: --help

--manual Display the manual entry. No

Example: --manual

Output
Amazon EC2 displays status messages that indicate the stages and status of the upload process.

Example
This example uploads the bundle specified by the bundled/fred.manifest.xml manifest:
$ ec2-upload-bundle -b my-s3-bucket -m bundled/fred.manifest.xml -a
10QMXFEV71ZS32XQFTR2 -s DMADSSfPfdaDjbK+RRUhS/aDrjsiZadgAUm8gRU2 -d bundled
Encrypting bundle manifest...
Completed encryption.
Uploading encrypted manifest...
Uploaded encrypted manifest to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.manifest.xml.
Uploading bundled AMI parts to http://s3.amazonaws.com:80/alpowell-images...
Uploaded fred.part.00 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.00.
Uploaded fred.part.01 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.01.

API Version 2008-02-01

172
 Amazon Elastic Compute Cloud Developer Guide
API Tools

Uploaded fred.part.02 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.02.
Uploaded fred.part.03 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.03.
Uploaded fred.part.04 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.04.
Uploaded fred.part.05 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.05.
Uploaded fred.part.06 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.06.
Uploaded fred.part.07 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.07.
Uploaded fred.part.08 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.08.
Uploaded fred.part.09 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.09.
Uploaded fred.part.10 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.10.
Uploaded fred.part.11 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.11.
Uploaded fred.part.12 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.12.
Uploaded fred.part.13 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.13.
Uploaded fred.part.14 to ht
tp://s3.amazonaws.com:80/alpowell-images/fred.part.14.
Upload Bundle complete.

Related Topics
• ec2-bundle-image
• ec2-bundle-vol
• ec2-unbundle
• ec2-download-bundle
• ec2-delete-bundle

API Tools
This section describes each API tool and its command line arguments in detail.

List of Operations by Function

Images

• ec2-register
• ec2-deregister
• ec2-describe-images

Instances

• ec2-run-instances
• ec2-describe-instances
• ec2-terminate-instances
• ec2-confirm-product-instance

API Version 2008-02-01

173
 Amazon Elastic Compute Cloud Developer Guide
ec2-add-group

Key Pairs

• ec2-add-keypair
• ec2-describe-keypairs
• ec2-delete-keypair
• ec2-fingerprint-key

Image Attributes

• ec2-modify-image-attribute
• ec2-describe-image-attribute
• ec2-reset-image-attribute

Security Groups

• ec2-add-group
• ec2-delete-group
• ec2-describe-group
• ec2-authorize
• ec2-revoke

Elastic IP Addresses

• ec2-allocate-address
• ec2-describe-addresses
• ec2-release-address
• ec2-associate-address
• ec2-disassociate-address

Availability Zones

• ec2-describe-availability-zones

ec2-add-group
Syntax
ec2-add-group group -d description

Description
Creates a new security group. Group names must be unique per account.

Options

API Version 2008-02-01

174
 Amazon Elastic Compute Cloud Developer Guide
ec2-add-keypair

Option Description Required

group Name of the security group. Yes
Example: webservers

-d description Description of the group. This is informational only. Yes

If the description contains spaces, you must enclose it
in single quotes (').
Example: -d 'Web servers'

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("GROUP").

• Group name.
• Group description.

Amazon EC2 displays errors on stderr.

Example
This example creates the websrv security group.
$ ec2-add-group websrv -d 'Web servers'
GROUP websrv Web servers

Related Topics
• CreateSecurityGroup
• ec2-describe-group
• ec2-delete-group
• ec2-authorize
• ec2-revoke

ec2-add-keypair
Syntax
ec2-add-keypair key

Description
Creates a new 2048 bit RSA key pair with the specified name. The public key is stored by Amazon EC2
and the private key is displayed on the console. The private key is returned as an unencrypted PEM
encoded PKCS#8 private key. If a key with the specified name already exists, Amazon EC2 returns an
error.

Options
API Version 2008-02-01
175
 Amazon Elastic Compute Cloud Developer Guide
ec2-allocate-address

Option Description Required

key Name of the key pair. Yes
Example: mysecretkey

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("KEYPAIR").

• Key pair name.
• Private key fingerprint.
• Private key. This value is displayed on a new line.

Amazon EC2 displays errors on stderr.

Example
This example creates a key pair named gsg-keypair:
$ ec2-add-keypair gsg-keypair
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-----

Related Topics
• CreateKeyPair
• ec2-describe-keypairs
• ec2-delete-keypair

ec2-allocate-address

API Version 2008-02-01

176
 Amazon Elastic Compute Cloud Developer Guide
ec2-associate-address

Syntax
ec2-allocate-address

Description
Acquires an elastic IP address for use with your account.

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("ADDRESS").

• Elastic IP address for use with your account.

Amazon EC2 displays errors on stderr.

Example
This example returns an elastic IP address for use with the account.
$ ec2-allocate-address
ADDRESS 67.202.55.255

Related Topics
• ec2-describe-addresses
• ec2-release-address
• ec2-associate-address
• ec2-disassociate-address

ec2-associate-address
Syntax
ec2-associate-address -i instance_id ip_address

Description
Associates an elastic IP address with an instance. If the IP address is currently assigned to another
instance, the IP address is assigned to the new instance. This is an idempotent operation. If you enter it
more than once, Amazon EC2 does not return an error.

Options
Option Description Required
instance_id The instance to which the IP address is assigned. Yes
Example: i-43a4412a

ip_address The IP address that you are assigning to the instance. Yes
API Version 2008-02-01
177
 Amazon Elastic Compute Cloud Developer Guide
ec2-authorize

Option Description Required

Example: 67.202.55.255

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("ADDRESS").

• Elastic IP address that you are assigning to the instance.
• Instance to which the IP address is assigned.

Amazon EC2 displays errors on stderr.

Example
This example assigns the 67.202.55.255 IP address to the i-43a4412a instance.
$ ec2-associate-address -i i-43a4412a 67.202.55.255
ADDRESS 67.202.55.255 i-43a4412a

Related Topics
• ec2-allocate-address
• ec2-describe-addresses
• ec2-release-address
• ec2-disassociate-address

ec2-authorize
Syntax
ec2-authorize group [-P protocol] (-p port_range | -t icmp_type_code) [-u
source_group_user ...] [-o source_group ...] [-s source_subnet ...]

Description
Adds a rule to the specified security group. If no source host, group or subnet is provided, requests from
any source address will be honored.

Options
Option Description Required
group The group to which this rule will apply. Yes
Example: webservers

-P protocol The protocol to allow. Yes

Condition: Applies when specifying a CIDR subnet

API Version 2008-02-01

178
 Amazon Elastic Compute Cloud Developer Guide
ec2-authorize

Option Description Required

as the source.
Valid Values: tcp | udp | icmp
Example: -P tcp

-p port_range For the TCP or UDP protocols, this specifies the Yes
range of ports to allow. You specify a single integer
or a range (min-max).
Condition: Applies when specifying a CIDR subnet
as the source.
Example: -p 80

-t icmp_type_code For the ICMP protocol, the ICMP type and code must Yes
be specified. This must be specified in the format
type:code where both are integers. Type, code, or
both can be specified as -1, which is a wildcard.
Condition: Applies when specifying a CIDR subnet
as the source.
Example: -t 2:5

-u The owner of a group specified using -o. If this is No

source_group_user not specified, all groups will refer to the current user.
If specified more than once, there must be exactly
one -u per -o and each user will be mapped to the
corresponding group.
Example: -u 495219933132

-o source_group The network source from which traffic will be No

authorized specified as a security Group. See the
description of the -u option for group owner
information.
Example: -o headoffice

-s source_subnet The network source from which traffic is to be No

authorized specified as a CIDR subnet range.
Example: -s 205.192.8.45/24

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("GROUP", "PERMISSION").

• Group name. Currently, this will report an empty string.
• Type of rule. Currently, only ALLOW rules are supported.
• Protocol to allow.
• Start of port range.
• End of port range.
• FROM
• Source.

API Version 2008-02-01

179
 Amazon Elastic Compute Cloud Developer Guide
ec2-confirm-product-instance

Amazon EC2 displays errors on stderr.

Example
This example grants TCP port 80 access from the 205.192.0.0/16 address range to the websrv security
group:
$ ec2-authorize websrv -P tcp -p 80 -s 205.192.0.0/16
GROUP websrv ""
PERMISSION websrv ALLOWS tcp 80 80 FROM CIDR 205.192.0.0/16

Related Topics
• AuthorizeSecurityGroupIngress
• ec2-add-group
• ec2-describe-group
• ec2-delete-group
• ec2-revoke

ec2-confirm-product-instance
Syntax
ec2-confirm-product-instance product_code -i instance_id

Description
Returns a boolean indicating whether the specified product code is attached to the specified instance. If
it is attached, It returns true. Otherwise, it returns false.

This command can only be executed by the AMI owner. This is useful when an AMI owner is providing
support and wants to verify whether a user's instance is eligible.

Options
Option Description Required
instance_id Instance identifier that was generated when the Yes
instance launched.
Example: i-10a64379

product_code The product code. Yes

Example: 774F4FF8

Output
Amazon EC2 returns a table that contains the following information:

• Product code.
• Instance ID.

API Version 2008-02-01

180
 Amazon Elastic Compute Cloud Developer Guide
ec2-delete-group

• Boolean indicating if the product code is attached to the instance.

• The instance owner's account ID (if the product code is attached).

Amazon EC2 displays errors on stderr.

Example
This example confirms whether the 774F4FF8 product code is attached to the i-10a64379 instance:
$ ec2-confirm-product-instance 774F4FF8 -i i-10a64379
774F4FF8 i-10a64379 true

Related Topics
• DescribeInstances
• ec2-modify-image-attribute

ec2-delete-group
Syntax
ec2-delete-groupgroup

Description
Deletes the specified security group.

Note

If you attempt to delete a security group that contains instances, a fault is returned.
If you attempt to delete a security group that is referenced by another security group, a
fault is returned. For example, if security group B has a rule that allows access from
security group A, security group A cannot be deleted until the allow rule is removed.

Options
Option Description Required
group Name of the security group. Yes
Example: webservers

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("GROUP").

• Name of the deleted security group.

API Version 2008-02-01

181
 Amazon Elastic Compute Cloud Developer Guide
ec2-delete-keypair

Amazon EC2 displays errors on stderr.

Example
This command deletes the websrv security group:
$ ec2-delete-group websrv
GROUP websrv

Related Topics
• DeleteSecurityGroup
• ec2-add-group
• ec2-describe-group
• ec2-authorize
• ec2-revoke

ec2-delete-keypair
Syntax
ec2-delete-keypair key_pair

Description
Deletes the specified key pair, by removing the public key from Amazon EC2

Options
Option Description Required
key_pair Name of the key pair. Yes
Example: primary_keypair

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("KEYPAIR").

• Name of the deleted key pair.
• Private key fingerprint.

Amazon EC2 displays errors on stderr.

Example
This example deletes the gsg-keypair key pair:

API Version 2008-02-01

182
 Amazon Elastic Compute Cloud Developer Guide
ec2-deregister

$ ec2-delete-keypair gsg-keypair
KEYPAIR gsg-keypair

Related Topics
• DeleteKeyPair
• ec2-add-keypair
• ec2-describe-keypairs

ec2-deregister
Syntax
ec2-deregister ami_id

Description
Deregisters the specified AMI. Once deregistered, the AMI cannot be used to launch new instances.

Note

This command does not delete the AMI from Amazon S3.

Options
Option Description Required
ami_id AMI identifier. Yes
Example: ami-4fa54026

Output
Amazon EC2 returns a table that contains the following information:

• A record type identifier ("IMAGE")

• The image identifier that was deregistered

Amazon EC2 displays errors on stderr.

Example
This example deregisters the ami-4fa54026 AMI:
$ ec2-deregister ami-4fa54026
IMAGE ami-4fa54026

Related Topics

API Version 2008-02-01

183
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-addresses

• DeregisterImage
• ec2-register
• ec2-describe-images

ec2-describe-addresses
Syntax
ec2-describe-addresses [public_ip ...]

Description
Lists elastic IP addresses assigned to your account.

Options
Option Description Required
public_ip Elastic IP addresses to describe No
Example: 67.202.55.255

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("ADDRESS").

• Elastic IP address assigned to your account.
• Instance ID to which the IP address is assigned.

Amazon EC2 displays errors on stderr.

Example
This example returns elastic IP addresses assigned to the account.
$ ec2-describe-addresses

Amazon EC2 returns 67.202.55.255 which is assigned to instance i-f15ebb98 and

67.202.55.233 which is not assigned to an instance.

ADDRESS 67.202.55.255 i-f15ebb98

ADDRESS 67.202.55.233

Related Topics
• ec2-allocate-address
• ec2-release-address
• ec2-associate-address
• ec2-disassociate-address

API Version 2008-02-01

184
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-availability-zones

ec2-disassociate-address
Syntax
ec2-disassociate-address ip_address

Description
Disassociates the specified elastic IP address from the instance to which it is assigned. This is an
idempotent operation. If you enter it more than once, Amazon EC2 does not return an error.

Options
Option Description Required
ip_address The IP address that you are disassociating from the Yes
instance.
Example: 67.202.55.255

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("ADDRESS").

• Elastic IP address you are disassociating from the instance.

Amazon EC2 displays errors on stderr.

Example
This example disassociates the 67.202.55.255 IP address from the instance to which it is assigned.
$ ec2-disassociate-address 67.202.55.255
ADDRESS 67.202.55.255

Related Topics
• ec2-allocate-address
• ec2-describe-addresses
• ec2-release-address
• ec2-associate-address

ec2-describe-availability-zones
Syntax
ec2-describe-availability-zones [zone-name...]

Description
API Version 2008-02-01
185
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-group

Describes availability zones that are currently available to the account and their states.

Note

Availability zones are not the same across accounts. The availability zone us-east-1a for
account A is not necessarily the same as us-east-1a for account B. Zone assignments are
mapped independently for each account.

Options
Option Description Required
zone-name Name of an availability zone. No
Example: us-east-1a

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("AVAILABILITYZONE").

• Availability zone name.
• State.

Amazon EC2 displays errors on stderr.

Example
This example displays the availability zones that are available to the account:
$ ec2-describe-availability-zones
AVAILABILITYZONE us-east-1a available
AVAILABILITYZONE us-east-1b available
AVAILABILITYZONE us-east-1c available

Related Topics
• ec2-run-instances

ec2-describe-group
Syntax
ec2-describe-group [group ...]

Description
Describes the current state of each specified security group. If no security groups are explicitly listed,
Amazon EC2 displays all security groups owned by the current user.

API Version 2008-02-01

186
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-image-attribute

Options
Option Description Required
group Name of the security group. Yes
Example: webservers

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("GROUP", "PERMISSION").

• User ID of security group owner.
• Security group name.
• Description of the security group.
• Firewall rule.

Amazon EC2 displays errors on stderr.

Example
This example displays the state of the websrv security group:
$ ec2-describe-group websrv
GROUP 495219933132 websrv Web servers
PERMISSION 495219933132 websrv ALLOWS tcp 80 80 FROM CIDR 0.0.0.0/0

Related Topics
• DescribeSecurityGroups
• ec2-add-group
• ec2-delete-group
• ec2-authorize
• ec2-revoke

ec2-describe-image-attribute
Syntax
ec2-describe-image-attribute ami_id ( -l | -p )

Description
Describes an attribute for the specified AMI.

Options

API Version 2008-02-01

187
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-image-attribute

Option Description Required

ami_id AMI identifier. Yes
Example: ami-4fa54026

-B, Describes the mapping that defines native device No

names to use when exposing virtual devices.
--block-device-mapping
Type: String

-l, Describes the launchPermission attribute. Choice

--launch-permission Example: -l

-p, --product-code Describes the productCodes attribute. Choice

Example: -p

--kernel Describes the ID of the kernel associated with the No

AMI.
Type: String

--ramdisk Describes the ID of the RAM disk associated with No

the AMI.
Type: String

Output
Amazon EC2 returns a table that contains the following information:

• Attribute type identifier

• ID of the AMI.
• Attribute value type or attribute list item value type.
• Attribute or attribute list item value.

Amazon EC2 displays errors on stderr.

Examples
This example lists the launch permissions for the ami-2bb65342 AMI:
$ ec2-describe-image-attribute ami-2bb65342 -l
launchPermission ami-2bb65342 group all
launchPermission ami-2bb65342 userId 495219933132

This example lists the product code for the ami-2bb65342 AMI:
$ ec2-describe-image-attribute ami-2bb65342 -p
productCodes ami-2bb65342 productCode 774F4FF8

Related Topics
• DescribeImageAttribute

API Version 2008-02-01

188
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-images

• ec2-modify-image-attribute
• ec2-reset-image-attribute
• Sharing AMIs

ec2-describe-images
Syntax
ec2-describe-images[ami_id ...] [-a] [-o owner ...] [-x user_id]

Description
Returns information about AMIs available to the user. This includes public AMIs available for any user
to launch, private AMIs owned by the user making the request, and private AMIs owned by other users
for which the user has explicit launch permissions.

The list of AMIs returned can be modified by specifying AMI IDs, AMI owners, or users with launch
permissions. If no options are specified, Amazon EC2 returns all AMIs for which the user has launch
permissions.

If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned. If you specify
an invalid AMI ID, a fault is returned. If you specify an AMI ID for which you do not have access, it
will not be included in the results.

If you specify one or more AMI owners, only AMIs from the specified owners and for which you have
access are returned. The results can include the account IDs of the specified owners, amazon for AMIs
owned by Amazon or self for AMIs that you own.

If you specify a list of executable users, only users that have launch permissions for the AMIs are
returned. You can specify account IDs (if you own the AMI(s)), self for AMIs for which you own or
have explicit permissions, or all for public AMIs.

Note

If you do not specify any optional parameters, Amazon EC2 returns images you own or
images for which you have explicit access. Public images are not returned.

If you use this command on machine images, it displays the kernel IDs and RAM disk IDs associated
with the images. If you specify a kernel or RAM disk ImageType, it displays information about kernel
or RAM disk images.

In addition to machine images, you can view available kernel or RAM disk images by specifying
kernel or ramdisk.

Options
Option Description Required
--image-type Returns machine (default), kernel, or RAM disk No
images.
Accepts the values machine, kernel, or ramdisk.
Example: kernel

-a Returns AMIs that the user owns and for which the No
API Version 2008-02-01
189
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-images

Option Description Required

user has execution permissions.
Example: -a

-o owner Returns AMIs owned by the specified owner. No

Multiple owners can be specified. Owners are
specified with AWS user account ID, without dashes.
The IDs amazon, self, and explicit can be used
to include AMIs owned by Amazon, AMIs owned by
the user, and AMIs for which the user has explicit
launch permissions, respectively.
Example: -o 495219933132

-x user_id Returns AMIs for which the specified user has No

explicit launch permissions. The user ID can be a
user's account ID, self to return AMIs for which the
sender of the request has explicit launch permissions,
or all to return AMIs with public launch
permissions.
Example: -x self

Output
Amazon EC2 returns a table that contains the following information:

• A record type identifier ("IMAGE")

• Image identifier
• Manifest location
• User identifier of the user that registered the image
• Image status
• Image visibility (public or private)
• Product codes, if any, that are attached to the instance

Amazon EC2 displays errors on stderr.

Example
This example describes the ami-78a54011 AMI:
$ ec2-describe-images ami-78a54011
IMAGE ami-78a54011 powerdns/image.manifest.xml 495219933132 available private
774F4FF8

This example describes the Amazon 64-bit AMI::

$ ec2-describe-images –o amazon | grep x86_64
IMAGE ami-78a54034
ec2-public-images/fedora-core6-base-x86_64.manifest.xml
amazon available public

API Version 2008-02-01

190
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-instances

Related Topics
• DescribeImages
• ec2-register
• ec2-deregister

ec2-describe-instances
Syntax
ec2-describe-instances [instance_id|availability-zone ...]

Description
Describes the current state of the specified instance(s). If you do not specify instances, all your instances
are included in the output.

Options
Option Description Required
instance_id Instance identifier that was generated when the No
instance launched.
Example: r-15a4417c

availability-zone Returns instances within the specified availability No

zone.
Example: us-east-1a

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("RESERVATION", "INSTANCE")

• Instance ID for each running instance.
• AMI ID of the image on which the instance is based.
• Public DNS name associated with the instance. This is only present for instances in the running
state.
• Private DNS name associated with the instance. This is only present for instances in the running
state, but is not valid for instances using legacy direct addressing.
• Instance state.
• Key name. If a key was associated with the instance at launch, its name will appear.
• AMI launch index. For more information, see Instance Metadata.
• Product codes attached to the instance.
• Instance type. The type of the instance (e.g., m1.small, m1.large, m1.xlarge).
• Instance launch time. The time the instance launched.
• Availability zone. The availability zone in which the instance is located.

API Version 2008-02-01

191
 Amazon Elastic Compute Cloud Developer Guide
ec2-describe-keypairs

Amazon EC2 displays errors on stderr.

Example
This example describes the current state of the instances (currently one) owned by this user:
$ ec2-describe-instances
RESERVATION r-15a4417c 495219933132
INSTANCE i-3ea74257 ami-6ba54002 ec2-72-44-33-4.compute-1.amazonaws.com
10-251-50-154.ec2.internal running 0 774F4FF8 m1.small
2007-07-11T16:40:44+0000 aki-ba3adfd3 ari-badbad00 us-east-1a
INSTANCE i-31a74258 ami-6ba54002 ec2-72-44-34-23.compute-1.amazonaws.com
10-251-50-156.ec2.internal running 1 m1.small 2007-07-11T16:40:44+0000 aki-
ba3adfd3 ari-badbad00 us-east-1a

Related Topics
• DescribeInstances
• ec2-run-instances
• ec2-terminate-instances

ec2-describe-keypairs
Syntax
ec2-describe-keypairs [key_id ...]

Description
Describes the current state of each specified key. If no keys are specified, all keys owned by the current
user are included in the output.

Options
Option Description Required
key_id Names of one or more keys. No
Example: gsg-keypair

Output
Amazon EC2 returns a table that contains the following information:

• A output type identifier ("KEYPAIR")

• Key pair identifier
• Private key fingerprint

Amazon EC2 displays errors on stderr.

Example

API Version 2008-02-01

192
 Amazon Elastic Compute Cloud Developer Guide
ec2-fingerprint-key

This example describes the state of the current keys:

$ ec2-describe-keypairs gsg-keypair
KEYPAIR gsg-keypair
1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f

Related Topics
• DescribeKeyPairs
• ec2-add-keypair
• ec2-delete-keypair

ec2-fingerprint-key
Syntax
ec2-fingerprint-key keyfile

Description
Computes and displays the fingerprint for a private key produced by Amazon EC2. .

This operation is performed entirely on the client-side. Network access is not required.

Options
Option Description Required
keyfile The path to a file containing an unencrypted Yes
PEM-encoded PKCS#8 private key.
Example: mykey.pem

Output
A key fingerprint. This is formatted as a hash digest with each octet separated by a colon.

Amazon EC2 displays errors on stderr.

Example
This example computes and displays the fingerprint for the mykey.pem private key:
$ ec2-fingerprint-key mykey.pem
1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f

Related Topics
• ec2-add-keypair
• ec2-describe-keypairs

API Version 2008-02-01

193
 Amazon Elastic Compute Cloud Developer Guide
ec2-modify-image-attribute

ec2-get-console-output
Syntax
ec2-get-console-output instance_id [-r]

Description
Retrieves the console output for specified instance, if available, and displays it to stdout.

Options
Option Description Required
instance_id Instance identifier generated when the instance Yes
launched.
Example: i-10a64379

-r Raw output. Do not escape the output to facilitate No

reading.

Output
• A timestamp indicating the time of the last update.
• The instance console output. By default the ^ESC character is escaped and duplicate new-lines are
removed to facilitate reading.

Amazon EC2 displays errors on stderr.

Example
This example retrieves the console output for the i-10a64379 instance
$ ec2-get-console-output i-10a64379
2007-01-03 12:00:00
Linux version 2.6.16-xenU ([email protected]) (gcc version 4.0.1
20050727 (Red Hat 4.0.1-5)) #1 SMP Thu Oct 26 08:41:26 SAST 2006
BIOS-provided physical RAM map:
Xen: 0000000000000000 - 000000006a400000 (usable)
980MB HIGHMEM available.
727MB LOWMEM available.
NX (Execute Disable) protection: active
IRQ lockup detection disabled
Built 1 zonelists
Kernel command line: root=/dev/sda1 ro 4
Enabling fast FPU save and restore... done.

ec2-modify-image-attribute
Syntax
ec2-modify-image-attribute ami_id -l (-a item_value | -r item_value)

ec2-modify-image-attribute ami_id -p product_code [-p product_code ...]

API Version 2008-02-01

194
 Amazon Elastic Compute Cloud Developer Guide
ec2-modify-image-attribute

Description
Modifies an attribute for the specified AMI.

Attributes
Attribute Name Type Description
launchPermission List Controls who has permission to launch
the AMI. You can grant launch
permissions by adding user IDs or
make the AMI public by adding the
all group. To learn more about
sharing AMIs see Sharing AMIs.

Note

If another user launches

your AMI there is no
mechanism to prevent that
user from rebundling the
image and registering it as
a new AMI.

productCodes List Associates a product code with an

AMI. This allows a developer to charge
a user for using the AMI.

Note

The user must be signed

up for the product before
they can launch the AMI.

The product code attribute is a

write-once attribute. After a product
code is set for an AMI it cannot be
altered or removed. AMIs are limited to
one product code.

Options
Option Description Required
-l Modifies the launchPermission property. Yes
Example: -l

-a item_value | -r Adds or removes an attribute item. The type of the Yes

item_value item is inferred from the item value. For
launchPermission there are two item types:

• group: The only group currently supported is the

all group. Adding this group sets public launch

API Version 2008-02-01

195
 Amazon Elastic Compute Cloud Developer Guide
ec2-reboot-instances

Option Description Required

permissions for the AMI.

• userId: The user ID is an AWS account ID,
without dashes. Adding user IDs grants explicit
launch permissions for the AMI.

Example: -a all

-p product_code Sets the productCodes property. Yes

Example: -p 774F4FF8

Output
Amazon EC2 returns a table that contains the following information:

• Attribute type identifier.

• ID of the AMI on which attributes are being modified.
• Action performed on the attribute.
• Attribute or attribute list item value type.
• Attribute or attribute list item value.

Amazon EC2 displays errors on stderr.

Examples
The following example modifies launch permission attributes for the ami-2bb65342 AMI:
$ ec2-modify-image-attribute ami-2bb65342 -l -a 495219933132
launchPermission ami-2bb65342 ADD userId 495219933132

The following example adds the 774F4FF8 product code to the ami-2bb65342 AMI:
$ ec2-modify-image-attribute ami-2bb65342 -p 774F4FF8
productCodes ami-2bb65342 productCode 774F4FF8

Related Topics
• ModifyImageAttribute
• ec2-reset-image-attribute
• ec2-describe-image-attribute
• Sharing AMIs

ec2-reboot-instances
Syntax
ec2-reboot-instances instance_id [instance_id ...]

API Version 2008-02-01

196
 Amazon Elastic Compute Cloud Developer Guide
ec2-release-address

Description
Reboots one or more specified instances. You must specify at least one instance ID.

Options
Option Description Required
instance_id Instance identifier that was assigned to the instance at Yes
launch.
Example: i-3ea74257

Output
This command displays no output on success.

Amazon EC2 displays errors on stderr.

Example
This example reboots the i-3ea74257 instance.
$ ec2-reboot-instances i-3ea74257

ec2-release-address
Syntax
ec2-release-address ip_address

Description
Releases an elastic IP address associated with your account.

If you run this operation on an elastic IP address that is already released, the address might be assigned
to another account which will cause Amazon EC2 to return an error.

Note

Releasing an IP address automatically disassociates it from any instance with which it is

associated. For more information, see ec2-disassociate-address.

Important

After releasing an elastic IP address, it is released to the IP address pool and might no
longer be available to your account. Make sure to update your DNS records and any
servers or devices that communicate with the address.

Options

API Version 2008-02-01

197
 Amazon Elastic Compute Cloud Developer Guide
ec2-register

Option Description Required

ip_address The IP address that you are releasing from your Yes
account.
Example: 67.202.55.255

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("ADDRESS").

• Elastic IP address that you are releasing.

Amazon EC2 displays errors on stderr.

Example
This example releases an elastic IP address associated with the account.
$ ec2-release-address 67.202.55.255
ADDRESS 67.202.55.255

Related Topics
• ec2-allocate-address
• ec2-describe-addresses
• ec2-associate-address
• ec2-disassociate-address

ec2-register
Syntax
ec2-register manifest

Description
Registers the Amazon Machine Image (AMI) specified in the manifest file and generates a new Amazon
Machine Image (AMI) ID.

Options
Option Description Required
manifest Location and filename of the manifest file. The Yes
manifest file must be located in Amazon S3 and must
be in the bucket/object form.
Example: mybucket/image.manifest.xml

API Version 2008-02-01

198
 Amazon Elastic Compute Cloud Developer Guide
ec2-reset-image-attribute

Output
Amazon EC2 assigns and returns an AMI ID.

Amazon EC2 displays errors on stderr.

Example
This example registers the AMI specified in the image.manifest.xml manifest file:
$ ec2-register mybucket/image.manifest.xml
IMAGE ami-78a54011

Related Topics
• RegisterImage
• ec2-deregister
• ec2-describe-images

ec2-reset-image-attribute
Syntax
ec2-reset-image-attribute ami_id -l

Description
Resets an attribute for the specified AMI.

The productCodes attribute cannot be reset.

Options
Option Description Required
ami_id The identifier that was assigned to the AMI when it Yes
was registered.
Example: r-15a4417c

-l Resets the launchPermission attribute. Yes

Example: -l

Output
Amazon EC2 returns a table that contains the following information:

• Attribute type identifier

• ID of the AMI on which the attribute is being reset
• Action identifier ("RESET")

API Version 2008-02-01

199
 Amazon Elastic Compute Cloud Developer Guide
ec2-revoke

Amazon EC2 displays errors on stderr.

Example
This example resets the lauchPermission attribute:
$ ec2-reset-image-attribute ami-6ba54002 -l
launchPermission ami-6ba54002 RESET

Related Topics
• ResetImageAttribute
• ec2-modify-image-attribute
• ec2-describe-image-attribute
• Sharing AMIs

ec2-revoke
Syntax
ec2-revoke group [-P protocol] (-p port_range | -t icmp_type_code) [-u
source_group_user ...] [-o source_group ...] [-s source_subnet ...]

Description
Revokes a rule from the security group named GROUP. To identify the rule to be removed you must
provide exactly the same set of options used to create that rule (see ec2-add-group).

Options
Option Description Required
group The group to which this rule will apply. Yes
Example: webservers

-P protocol The protocol to revoke. Yes

Condition: Applies when specifying a CIDR subnet
as the source.
Valid Values: tcp | udp | icmp
Example: -P tcp

-p port_range For the TCP or UDP protocols, this specifies the Yes
range of ports to revoke. You specify a single integer
or a range (min-max).
Condition: Applies when specifying a CIDR subnet
as the source.
Example: -p 80

-t icmp_type_code For the ICMP protocol, you must specify the ICMP Yes
type and code. Use the type:code format, where both
are integers. To specify a wildcard for either or both,
enter -1.
API Version 2008-02-01
200
 Amazon Elastic Compute Cloud Developer Guide
ec2-revoke

Option Description Required

Condition: Applies when specifying a CIDR subnet
as the source.
Example: -t 2:5

-u The owner of a group specified using -o. If this is No

source_group_user not specified, all groups will refer to the current user.
If specified more than once, there must be exactly
one -u per -o and each user will be mapped to the
corresponding group.
Example: -u 495219933132

-o source_group The network source from which traffic will be No

revoked specified as a security Group. See the
description of the -u option for group owner
information.
Example: -o headoffice

-s source_subnet The network source from which traffic is to be No

revoked specified as a CIDR subnet range.
Example: -s 205.192.8.45/24

Output
A table containing the following information is returned:

• Output type identifier ("GROUP", "PERMISSION").

• Group name. Currently, this will report an empty string.
• Type of rule. Currently, only ALLOW rules are supported.
• Protocol to allow.
• Start of port range.
• End of port range.
• FROM
• Source.

Amazon EC2 displays errors on stderr.

Example
This example revokes TCP port 80 access from the 205.192.0.0/16 address range for the websrv
security group:
$ ec2-revoke websrv -P tcp -p 80 -s 205.192.0.0/16
GROUP websrv ""
PERMISSION websrv ALLOWS tcp 80 80 FROM CIDR 205.192.0.0/16

Related Topics
• RevokeSecurityGroupIngress

API Version 2008-02-01

201
 Amazon Elastic Compute Cloud Developer Guide
ec2-run-instances

• ec2-add-group
• ec2-describe-group
• ec2-delete-group
• ec2-authorize

ec2-run-instances
Syntax
ec2-run-instances ami_id [-n instance_count] [-g group [-g group ...]] [-k
keyname] [-d user_data | -f user_data_file] [ --addressing addressing_type] [
--instance-type instance_type] [ --availability-zone zone] [ --kernel
kernel_id] [ --ramdisk ramdisk_id] [
--block-device-mappingblock_device_mapping]

Description
Launches one or more instances of the specified AMI.

Every instance is launched in a security group. If you do not specify a security group at launch, the
instances start in your default security group. For more information on creating security groups, see
CreateSecurityGroup.

An optional instance type can be specified. For information about instance types, see Instance Types.

You can provide an optional key pair ID for each image in the launch request (see CreateKeyPair. All
instances that are created from images that use this key pair will have access to the associated public key
at boot. You can use this key to provide secure access to an instance of an image on a per-instance basis.
Amazon EC2 public images use this feature to provide secure access without passwords.

Important

Launching public images without a key pair ID will leave them inaccessible.

The public key material is made available to the instance at boot time by placing it in the
openssh_id.pub file on a logical device that is exposed to the instance as /dev/sda2 (the ephemeral
store). The format of this file is suitable for use as an entry within ~/.ssh/authorized_keys (the
OpenSSH format). This can be done at boot (e.g., as part of rc.local) allowing for secure access
without passwords.

Optional user data can be provided in the launch request. All instances comprising the launch request
have access to this data (see Instance Metadata for details).

Note

If the AMI has a Amazon DevPay product code attached for which the user has not
subscribed, the ec2-run-instances call will fail.

Options
Option Description Required
ami_id The identifier that was assigned to the AMI when it Yes
API Version 2008-02-01
202
 Amazon Elastic Compute Cloud Developer Guide
ec2-run-instances

Option Description Required

was registered.
Example: r-15a4417c

-n instance_count The number of instances to launch. If Amazon EC2 No

cannot launch the specified number of instances, no
instances will launch. If this is specified as a range
(min-max), Amazon EC2 will try to launch the
maximum number, but no fewer than the minimum
number.
Default: 1
Example: -n 5

-g group The security group(s) within which to launch the No

instances. This determines the ingress firewall rules
applied to the instances. If you specify more than one
group, the security policy will be the union of the
security policies of the specified groups.
Default: The default group.
Example: -g fooGroup

-k keyname The key pair to make available to these instances at No

boot.
Example: -k fooKeyPair

-d user_data Data to make available to the instances. This data is No

read from the command line of the USER_DATA
argument. If you want the data to be read from a file,
see the -f option.
Example: -d "my user data"

-f user_data_file Data to make available to these instances. The data is No

read from the file specified by FILE_NAME. To
specify user data on the command line, use the -d
option.
Example: -f data.zip

--instance-type The type of instance to launch. For more information, No

instance_type see Instance Types.
Example: --instance-type m1.small

--availability-zonezone The availability zone in which to launch the No

instance(s). For more information, see
ec2-describe-availability-zones.
Example: us-east-1a

--kernelkernel_id The ID of the kernel with which to launch the No

instance. For information on finding available kernel
IDs, see ec2-describe-images.
Example: aki-ba3adfd3

--ramdiskramdisk_id The ID of the RAM disk with which to launch the No

instance.

API Version 2008-02-01

203
 Amazon Elastic Compute Cloud Developer Guide
ec2-run-instances

Option Description Required

Some kernels require additional drivers at launch.
Check the kernel requirements for information on
whether you need to specify a RAM disk.To find
kernel requirements, go to the Resource Center and
search for the kernel ID.
Example: ari-badbad00

Specifies how block devices are exposed to the

--block-device-mappingsmappings No
instance. .
Virtual name example: ephemeral0
Device name example: sdb

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("INSTANCE")

• Instance ID which uniquely identifies each running instance.
• AMI ID of the image on which the instance(s) are based.
• DNS name associated with the instance (only present for instances in the running state).
• Instance state. This is usually pending, which indicates that the instance(s) are preparing to launch.
• Key name. If a key was associated with the instance at launch its name is displayed
• AMI launch index. For more information, see Instance Metadata.
• Instance type. For more information on instance types, see Instance Types.
• Instance launch time. Specifies when the instance launched.
• Availability zone. Specifies the zone in which the instance launched.

Amazon EC2 displays errors on stderr.

Example
This example launches five instances of the ami-6ba54002 AMI:
$ ec2-run-instances ami-6ba54002 -n 5 --availability-zone us-east-1a --
RESERVATION r-0ea54067 495219933132 default
INSTANCE i-3ea74257 ami-6ba54002 pending 0 m1.small 2007-07-11T16:40:44+0000
us-east-1a
INSTANCE i-31a74258 ami-6ba54002 pending 1 m1.small 2007-07-11T16:40:44+0000
us-east-1a
INSTANCE i-31a74259 ami-6ba54002 pending 2 m1.small 2007-07-11T16:40:44+0000
us-east-1a
INSTANCE i-31a7425a ami-6ba54002 pending 3 m1.small 2007-07-11T16:40:44+0000
us-east-1a
INSTANCE i-31a7425b ami-6ba54002 pending 4 m1.small 2007-07-11T16:40:44+0000
us-east-1a
INSTANCE i-31a7425c ami-6ba54002 pending 5 m1.small 2007-07-11T16:40:44+0000
us-east-1a

Related Topics

API Version 2008-02-01

204
 Amazon Elastic Compute Cloud Developer Guide
ec2-terminate-instances

• RunInstances
• ec2-terminate-instances
• ec2-describe-instances
• ec2-add-keypair
• Instance Metadata

ec2-terminate-instances
Syntax
ec2-terminate-instances instance_id [instance_id ...]

Description
Terminates the specified instances.

Options
Option Description Required
instance_id ID of the instance that was assigned at lauch. Yes
Example: i-3ea74257

Output
Amazon EC2 returns a table that contains the following information:

• Output type identifier ("INSTANCE")

• The instance ID of the instance being terminated.
• The state of the instance prior to being terminated.
• The new state of the instance.

Amazon EC2 displays errors on stderr.

Example
This example terminates the i-3ea74257 instance:
$ ec2-terminate-instances i-3ea74257
INSTANCE i-3ea74257 running shutting-down

Related Topics
• TerminateInstances
• ec2-run-instances
• ec2-describe-instances

API Version 2008-02-01

205
 Amazon Elastic Compute Cloud Developer Guide
General Information

Technical FAQ

Topics

• General Information
• Operation Information
• Instance Types and Architectures
• IP Information
• Availability Zones
• Monitoring, Errors, and Unexpected Behavior
• Error Messages
• Paid AMIs
• Miscellaneous

This section contains answers to commonly asked questions.

General Information
How many instances can I launch?

Each user has a concurrent running instance limit. For new users, this limit is 20. If you need more than
20 instances, please complete the Amazon EC2 Instance Request Form and your request will be
considered.

How do I sign a request?

Information on signing SOAP requests is provided in Request Authentication. Information on signing

Query requests is provided in Query API Authentication

What username do I use for the various Amazon EC2 tools?

When you sign up with Amazon Web Services, you are provided an AWS Account ID. This is your
username. For more information, refer to the Amazon Elastic Compute Cloud Getting Started Guide.

Why do my instances take so long to start?

API Version 2008-02-01

206
 Amazon Elastic Compute Cloud Developer Guide
Operation Information

Amazon EC2 must move the images around the network before they can be launched. For big images
and/or congested networks, this can take several minutes. To improve performance, images are cached.
As you launch your images more frequently, it should be less noticeable.

How durable are the instance stores?

Instance stores appear to an instance as a local disk. They will survive intentional and unintentional
reboots of the instance unless the instance terminates or the underlying drive fails.

You should always backup or replicate important data.

What happens to my running instances if the machines on which they are running go down?

The instances will terminate and will need to be relaunched. The data on the instances' hard drives will
be lost.

Always replicate important data or store it in Amazon S3.

Can I get a bigger/smaller/differently optimized virtual machine?

Yes. For more information, see Instance Types.

Is there a REST interface to Amazon EC2?

Not at present. You can use the SOAP API, Query API, or the command-line tools.

How does Amazon EC2 handle load balancing?

With a service as flexible as Amazon EC2, you can use many types of load balancing systems. The load
balancing instances can forward traffic to other systems. There are several open source solutions that are
in wide use.

Does Amazon perform system maintenance?

Yes. Periodically, Amazon might perform maintenance that requires a reboot of your system. Make sure
your instances can recover and restart after being rebooted.

Operation Information
How do I handle time synchronization between instances?

You can set up NTP (Network Time Protocol). For more information, go to www.ntp.org. NTP is
particularly important if you plan on using any Amazon web services (such as Amazon S3 or
Amazon EC2) from within an instance, since requests to these services must be timestamped.

Is there a method for an instance to discover its own instance ID?

From within your instance you can use REST-like queries to http://169.254.169.254/2008-02-01/ to
retrieve various instance-specific metadata, including the instance ID. For more information, see
Instance Metadata.

Can I pass arbitrary configuration values to an instance at launch time?

Yes, although the size of the data is limited to 16K. For more information, see Instance Metadata.

Is there a way to run a script on instance termination?

Not with any reliability. Amazon EC2 tries to shut an instance down cleanly (running system shutdown

API Version 2008-02-01

207
 Amazon Elastic Compute Cloud Developer Guide
Instance Types and Architectures

scripts), but there is only a short time available. In some cases (e.g., hardware failure), this does not
happen.

Since there is no way to ensure shutdown scripts run, have a strategy to deal with abnormal
terminations.

How can I allow other people to launch my AMIs?

You can allow other users to launch your AMIs by modifying the AMI's launchPermission attribute.
You can grant public launch permissions or explicit permissions to specific users. For more information,
see Sharing AMIs.

Why do I need to reregister a rebundled AMI? Can I keep the same AMI ID?

An AMI ID is associated with the physical bits in an image. To protect users from images being
modified, we require you to reregister AMIs after rebundling.

Can I pass JVM properties to the command line tools?

Yes. By setting the environment variable EC2_JVM_ARGS, you can pass arbitrary JVM properties to the
command line tools.

Can I use a proxy with the command line tools?

Yes. By passing in JVM properties through the EC2_JVM_ARGS environment variable, you can specify
proxy settings for the command line tools. For example, in Linux:
export EC2_JVM_ARGS="-Dhttp.proxyHost=http://my.proxy.com -Dht
tp.proxyPort=8080"

The following properties are supported for configuring a proxy:

Setting Description
https.proxyHost HTTPS proxy host
https.proxyPort HTTPS proxy port
http.proxyHost HTTPS proxy host
http.proxyPort HTTPS proxy port
http.proxyRealm Proxy realm (https and http)
http.proxyUser Proxy username (https and http)
http.proxyPass Proxy password (https and http)

Note

https.proxyHost should be used when EC2_URL points to an https host, and

http.proxyHost when EC2_URL points to an http host.

Instance Types and Architectures

What happened to the original instance type?

API Version 2008-02-01

208
 Amazon Elastic Compute Cloud Developer Guide
Instance Types and Architectures

The original instance type is still available. It is called the small instance (m1.small) and it has the same
technical specifications.

Will the original instance type be retired soon?

There are no plans to retire the original instance type.

If I do not specify an instance type at launch, what type of instance will I get?

You will get a m1.small Amazon EC2 instance type.

Does my instance limit apply to all instance types or is there a separate limit for each type?

The instance limit applies to the sum of all instances, regardless of type. There is no separate instance
limit per type.

Can I mix instance types, or do I have to use the same type for all of my instances?

You can launch any combination of instance types. Choose the instance types that have the most
appropriate memory, CPU, and storage for each function within your application.

Which instance types are 32-bit and which are 64-bit?

The small instance (m1.small) is 32-bit. The large (m1.large) and extra large (m1.xlarge) instances are
64-bit.

Can I launch any AMI on any type of instance?

No. You must use 64-bit AMIs on large (m1.large) and extra large (m1.xlarge) instances and 32-bit
AMIs on small Instances (m1.small).

Can I use my own kernel?

Not at present. However, as of version 2008-02-01 of the Amazon EC2 API you can use any of the
kernels published by Amazon EC2 or selected vendors.

Do I have to do anything special to bundle the large or extra large instances?

Make sure to use the latest AMI Tools.

Can I build an AMI that works on both 32-bit and 64-bit instances?

No, an AMI is either a 32-bit AMI or a 64-bit.

Can I run 32- bit applications on 64-bit AMIs?

You can run a 32-bit application on a 64-bit host if the Linux kernel is compiled with IA32 emulation
and the correct 32-bit libraries are available.

By default, the Amazon DomU Kernel has IA32 emulation enabled and there are many public AMIs that
include pre-installed 32-bit libraries. If the library you require is not included with the AMI, you can
install it using standard tools (e.g., yum).

How fast is the disk?

The large and extra large instances have higher and more consistent I/O performance than the original
(small) instance.

Note

API Version 2008-02-01

209
 Amazon Elastic Compute Cloud Developer Guide
IP Information

The first write to any given block of the disk will be slower than subsequent writes. For
more information, see Disk Performance Optimization

Can I RAID the spindles exposed on large and extra large instances?

Yes, you can use software RAID on top of the exposed spindles.

Note

The initial RAID setup might take a long time. For more information, see Disk
Performance Optimization

IP Information
How do I host a public domain if I have to DHCP an IP address?

You can use a dynamic DNS service, such as DynDNS or ZoneEdit. Alternatively, you can map an
elastic IP address to your instance and avoid the propagation delays possible with a dynamic DNS
solution.

Why do I get an internal (RFC 1918) IP address when I look up a DNS name that I expect to map to my
instance's external IP address?

The Amazon EC2 DNS servers return the internal IP address when asked about an instance's public
DNS name. In this way, DNS lookups that would resolve to a public Amazon EC2 IP address will be
translated to the correct internal IP address. This only works when using the Amazon EC2 DNS servers
from an Amazon EC2 instance.

Why is Amazon EC2 Using NAT?

Public IP space is a limited resource. Amazon EC2 is adopting NAT to ensure that we are able to
efficiently make use of our public Internet addresses.

Furthermore, the new NAT networking will enable Amazon to deliver new features in the future. For
example, some users might not want external addresses. This would allow for non-Internet routable
clusters, which will further preserve IPs and increase security for those not running public facing
servers.

Can I use a static IP in my instances?

Not at present. Your image must be configured as a DHCP client and it will be assigned an IP address.
Currently, all instances come with Internet- addressable IP addresses. If you enable access through the
firewall from the "world", you can address them from anywhere.

How does the instance know its public and private addresses?

From within the instance, issue the following HTTP queries:

To obtain the internal IP address:

curl http://169.254.169.254/2008-02-01//meta-data/local-ipv4

To obtain the public IP address:

API Version 2008-02-01

210
 Amazon Elastic Compute Cloud Developer Guide
IP Information

curl http://169.254.169.254/2008-02-01//meta-data/public-ipv4

Why am I limited to 5 elastic IP addresses?

Public (IPV4) Internet addresses are a scarce public resource. Amazon EC2 is committed to helping use
that space efficiently.

By default, all accounts are limited to 5 elastic IP addresses. If you need more than 5 Elastic IP
addresses, please complete the Amazon EC2 Elastic IP Address Request Form. We will ask you to think
through your use case and help us understand your need for additional addresses.

Is my elastic IP addressed fixed to a single instance?

Unlike a traditional dedicated IP addresses, an elastic IP can be assigned to many different instances
over time.

In there a minimum usage required for elastic IP addresses?

When operating within the 5 address limit, you can leave addresses unattached as you need. However,
we reserve the right to reclaim elastic IP addresses that are chronically underutilized.

In there a charge for elastic IP addresses?

To ensure our customers are efficiently using elastic IP addresses, we impose the a small hourly charge
when these IP addresses are not mapped to an instance. When these IP addresses are mapped to an
instance, they are free of charge. To avoid charges for elastic IP addresses that you are not using, use
ReleaseAddress.

Do I need one elastic IP address for every instance that I have running?

You do not need an elastic IP address for all your instances. By default, every instance comes with a
private IP address and an Internet routable public IP address. These addresses are fixed for the life of the
instance. We believe this should be adequate for many applications where you do not need a long lived
Internet routable end point (e.g., compute clusters, web crawling, and backend services).

Why don't you use IPV6 addresses?

Because of the scarcity of IPV4 Internet address, Amazon EC2 will be actively investigating the use of
IPV6 addresses. We believe this is the only tenable long term solution. We don't yet have a timeline for
introducing IPV6 addresses, but when we do support IPV6 addresses, we will be able to remove the
friction we have imposed with IPV4 address.

Can I launch an instance with no public IP address?

You cannot currently launch an instance without a public IP address. We understand that for many
applications, it is desirable to have no Internet routable IP address (e.g., internal databases).

How long does it take to remap an elastic IP address?

After you successfully make an API call to remap an IP address, it will usually occur within a few
minutes.

Will I be charged for the time when my IP address is unattached because my instance failed?

You are not charged until your elastic IP address has been unattached for a full hour. As long as you are
monitoring your instances, you will have plenty of time to reattach your instance before the charge is
metered.

Am I limited to 100 elastic IP remaps per month?

API Version 2008-02-01

211
 Amazon Elastic Compute Cloud Developer Guide
Availability Zones

No. The first 100 remaps per account are free. After that, there will be a charge for each remap.

Availability Zones
Can I assume that my availability zone us-east-1a is the same location as someone else's availability
zone us-east-1a?

No. Currently, we do not support cross-account proximity. Each account's availability zones are
independent. There is no assurance that your availability zone us-east-1a will be the same as any other
account's availability zone us-east-1a.

How can I make sure that I am in the same availability zone as another developer?

We do not currently support the ability to coordinate availability groups between developer accounts.
We are seeking customer feedback to understand the types of use cases for proximity control between
accounts. We will use this feedback to determine how and when we can provide availability zone
control between accounts.

Do I get double charged for regional data transfer? Why do you meter regional data transfer on both
the sender and the receiver?

The cost of regional data transfer is divided between the sender and the receiver and each instance will
accrue half the cost. This is useful when a transfer involves multiple accounts as each account is equally
charged.

Regional data transfer seems like such a small charge, why are you complicating my bill with this?

We anticipate that for most common use cases, regional data transfer will only constitute a very small
portion of your monthly usage charges. There are valid use cases that involve moving large amounts of
data between availability zones. In these cases, the regional data transfer can be a significant cost.

We try to enable as many use cases as possible while charging you only for what you use. Because of
the large potential differences in the way developers will use regional data transfer, we think it is
appropriate to break this cost out rather than amortize it across other charges.

Why does my account show that I am using regional data transfer but no associated charge?

Until recently, Amazon EC2 did not support availability zone control. Therefore, you might want to
relaunch your instances to arrange them for optimal cost effectiveness and availability. To give you time
to do this, regional data transfer activity shows up on your account, but does not accrue charges until
July 1, 2008.

Monitoring, Errors, and Unexpected Behavior

How do I monitor my systems?

Amazon EC2 provides basic monitoring. You can use DescribeInstances to check whether an instance
appears to be running. However, if you are using Amazon EC2 as your data center, you might want to
set up for sophisticated monitoring on your instances, such as SNMP.

Why can't I "talk" to my instances?

There are a few common reasons for broken connectivity to your instance.

Amazon EC2 changes the state of your instance to running after your operating system starts booting.
Depending on your AMI, there will be a delay before the instance is fully set up and functional.

API Version 2008-02-01

212
 Amazon Elastic Compute Cloud Developer Guide
Error Messages

If your instance has been running for several minutes, you verify you authorized the appropriate access
to your host through the Amazon EC2 firewall. If you have launched your instances without specifying a
security group, the default group is used. Permissions on the default group are very strict and
disallow all access from the Internet and other groups. You will need to modify the permissions of your
default group or set up a new group with appropriate permissions. For more information, see
Network Security

If this doesn't solve your issue, make sure you authorized port 22 and try to open an SSH connection
with verbose output. Use the man page for the exact syntax of your system, but the command is likely to
be similar to ssh -vv root@[hostname]. This output is very useful if you are posting to the forum.

Why did my instance terminate immediately after launch?

Launch errors can be the result of an internal error during launch or a corrupt Amazon EC2 image.
Internal errors are rare, as we actively test for and isolate suspect hosts. Consult the DescribeInstances
operation for details on why your instance failed to launch.

Note

The ec2-describe-instances command line tool does not provide this information.
Use the -v flag to read the detailed SOAP response and get detailed information.

You can also attempt to launch the image again. If this proves to be a persistent problem (especially with
a shared image), post to the AWS forums.

I ran shutdown from within an ssh session, but my instance still shows up as running when I query it
with DescribeInstances and I can't shell into it.

To shut down an instance, use the TerminateInstances call (ec2-terminate) on the command line.
You can also use shutdown -h, but must verify the instance shut down using the DescribeInstances
call.

Why are my instances stuck in a pending state (or a shutting-down state)?

This situation is rare and might be the result of a software error or misconfiguration.

We actively monitor for this; please contact us if it occurs.

Why do I get an "AuthFailure: User is not AMI creator" error when I try to register an image?

Make sure that you are using the correct user ID and certificate to create and upload the image. You
must use the same ID and certificate to register the image with Amazon EC2.

Error Messages
Why do I get an "InsufficientInstanceCapacity" error when I try to launch an instance?

This error indicates that we do not currently have enough available capacity to service your request.

If you are requesting a large number of instances, there might not be enough server capacity to host
them. You can try again later or specify a smaller number of instances.

Why do I get an "InstanceLimitExceeded" error when I try to launch an instance?

This error indicates you reached your concurrent running instance limit. For new users during the public
beta, the limit is 20.

API Version 2008-02-01

213
 Amazon Elastic Compute Cloud Developer Guide
Paid AMIs

If you need additional capacity, please contact us at [email protected].

Why can't I retrieve my instance-specific data from within a running instance when querying
http://169.254.169.254/2008-02-01/?

The Parameterized Launches feature is available to instances that were launched after the feature was
released. If you launched your instance before this, the data will not be available. If you want to use this
functionality, relaunch your instances.

If, after relaunching your instance, you still experience problems retrieving the data, check the
following:

• Are you using the correct base URI (http://169.254.169.254/2008-02-01/)

• Are you using the correct URI for the data you're trying to retrieve? Depending on the data you're
trying to retrieve, a trailing '/' might be required.
• Did you specify any launch data when launching your instances? If not you will get a HTTP error
response (404) when trying to retrieve the user data.

Note

Instance metadata is always available, even if you do not specify it at instance launch.

Why do I get keep getting "Request has expired" errors?

To reduce the risk of replay attacks, our requests include a timestamp. This and the most important parts
of the request are signed to ensure the message (including the timestamp) cannot be modified without
detection.

If the difference between the timestamp in the request and the time on our servers is larger than 5
minutes, the request is too old (or too new) and an error is returned.

You need to ensure that your system clock is accurate and configured to use the correct timezone. For
more information, go to NTP.

Paid AMIs
Note

You can still share AMIs without charging. Public and paid AMIs can be listed in the
Resource Center.

How can I determine if a particular AMI is a paid AMI?

By describing images (ec2dim) with the "-a" flag and looking for AMIs that have a product code. For
example, if you run ec2dim -a, the result contains an AMI with the ID ami-bd9d78d4. This is our
Demo Paid AMI with product code A79EC0DB.

How can I determine if a public AMI is paid?

By describing images (ec2dim). An AMI is a paid AMI if a product code is returned. Example: run
ec2dim -a amazon, and the AMI ami-bd9d78d4 will be returned with a product code (A79EC0DB).

Is there anything that prevents a paid AMI from being rebundled? How can this be restricted?

API Version 2008-02-01

214
 Amazon Elastic Compute Cloud Developer Guide
Kernels, RAM Disks, and Block Device Mappings

Paid AMIs are comparable to shared AMIs with regards to rebundling and trying to restrict rebundling.
If you allow a user running the AMI to see all of its contents (e.g. by giving root access to the AMI), the
user could rebundle these into their own AMI.

Why can't I query a particular AMI's attributes to see if the AMI is paid?

Only the owner of an AMI can query the AMI attributes. However, anyone can tell if an AMI is paid by
describing images (ec2dim). An AMI is paid if a product code is returned. Example: run ec2dim -a
amazon, and the AMI with ID ami-bd9d78d4 will be returned with a product code (A79EC0DB).

Who can use the confirm-product-instance command?

Only the owner of the AMI can use this command. Owners use this command with supported AMIs to
determine if a supported instance with a given product code attached is up and running.

Will the product code be inherited by the rebundled AMI?

If your customer uses AWS tools to rebundle the AMI, the product code associated with the AMI is
inherited by the rebundled AMI. When launching the rebundled AMI the customer is still billed for
usage based on your price.

Note

This is a convenience feature and not a guarantee that the product code will always be
attached to rebundled AMIs.

Note that the customer's workflow could bundle the AMI outside of Amazon EC2, or the customer could
use modified versions of the AWS tools, preventing the product code from being inherited.

Will the kernel/RAM disk be inherited by the rebundled AMI?

If you rebundle an AMI, it inherits the kernel and RAM disk from the source AMI unless you specify a
different kernel and RAM disk.

Note

This is a convenience feature and not a guarantee that the kernel/RAM disk will always be
attached to rebundled AMIs.

I created my paid AMIs with one AWS developer account, but I want to sell them using a different AWS
developer account. Can I transfer them?

No, you can't automatically transfer AMIs from one account to another. You would have to upload them
again using the second AWS developer account and then register them with DevPay using that account.
Alternately, you could leave the AMIs with the original account (the AMI owner account) and register
them with DevPay using another AWS developer account (the product owner account). You could then
use the AMI owner account to associate the product code with the AMIs. However, keep in mind that
only the product owner (and not the AMI owner in this case) can use the ec2-confirm-product-instance
command, which confirms that an instance is running an AMI associated with the product owner's
product code.

Kernels, RAM Disks, and Block Device Mappings

What are user selectable kernels?

Amazon EC2 provides user selectable kernels which enables you to select a kernel when bundling an

API Version 2008-02-01

215
 Amazon Elastic Compute Cloud Developer Guide
Miscellaneous

AMI or launching an instance. User selectable kernels are useful for keeping your instances up to date
with security fixes and updates, being able to use functionality provided by new distributions, and for
using specialty applications that have unique timing requirements.

How do I find user selectable kernels?

Use the DescribeInstances operation with the --kernel option. This lists all public kernels that are
currently available. After locating a kernel to launch or bundle with your AMI, go to the Resource
Center and search for it to determine whether there are any known issues and whether it has any
dependencies.

Can I use my own kernel?

Not at present. However, as of version 2008-02-01 of the Amazon EC2 API you can use any of the
kernels published by Amazon EC2 or selected vendors.

What type of dependencies do kernels have?

Kernels are most likely to require a RAM disk that contains required drivers (e.g., Xen drivers, video
drivers, and so on). If you launch a kernel without a required RAM disk, it will not work properly.

How do I know a kernel/AMI combination will work together?

If you are concerned about whether the kernel/image combination will work well together, Amazon
provides several AMIs that have tested combinations that you can use as a starting point for your AMIs
or AMIs that you can use as a foundations for a public AMIs. If you require a certified kernel/ AMI
combination, you can find them as paid AMIs through organizations such as RedHat. For more
information, see Paying for AMIs.

Miscellaneous
Are there any special requirements to use FTP?
The File Transfer Protocol (FTP) has a PORT command by which a client sends its address back to the
server. The server then connects to the client at that address to send the file data. If the client looks up its
own internal address and sends this to the server, the connection will fail. In this specific case, there are
two solutions to the problem. First, configure the client to send its public IP address. Second, the client
can use "passive FTP" which makes connections only to the server, rather than from the server to the
client. In general, applications which encode local addresses and port numbers in data sent to external
servers might have problems with NAT. Care must always be taken to send the public address, rather
than the internal one.
We recommend using passive mode unless it is not supported by the FTP server.

API Version 2008-02-01

216
 Amazon Elastic Compute Cloud Developer Guide

Glossary

Amazon machine image (AMI) An Amazon Machine Image (AMI) is an encrypted machine image
stored in Amazon S3. It contains all the information necessary to
boot instances of your software.

explicit launch permission Launch permission granted to a specific user.

instance Once an AMI has been launched, the resulting running system is
referred to as an instance. All instances based on the same AMI start
out identical and any information on them is lost when the instances
are terminated or fail.

group Also known as a security group, groups define firewall rules that can
be shared among a group of instances that have similar security
requirements. The group is specified at instance launch.

launch permission AMI attribute allowing users to launch an AMI

public AMI An AMI that all users have launch permissions for.

reservation A collection of instances started as part of the same launch request.

shared AMI AMIs that developers build and make available for other AWS
developers to use.

API Version 2008-02-01

217
 Amazon Elastic Compute Cloud Developer Guide
Typographical Conventions

Document Conventions

This section lists the common typographical and symbol use conventions for AWS technical
publications.

Typographical Conventions
This section describes common typographical use conventions.

Convention Description/Example
Call-outs A call-out is a number in the body text to give you a visual reference. The
reference point is for further discussion elsewhere.
You can use this resource regularly.

Code in text Inline code samples (including XML) and commands are identified with a
special font.
You can use the command java -version.

Code blocks Blocks of sample code are set apart from the body and marked accordingly.

# ls -l /var/www/html/index.html
-rw-rw-r-- 1 root root 1872 Jun 21 09:33 /
var/www/html/index.html
# date
Wed Jun 21 09:33:42 EDT 2006

Emphasis Unusual or important words and phrases are marked with a special font.
You must sign up for an account before you can use the service.

Internal cross References to a section in the same document are marked.

references See Document Conventions.

Logical values, A special font is used for expressions that are important to identify, but are
constants, and regular not code.
expressions, abstracta If the value is null, the returned response will be false.

API Version 2008-02-01

218
 Amazon Elastic Compute Cloud Developer Guide
Typographical Conventions

Convention Description/Example

Product and feature Named AWS products and features are identified on first use.
names Create an Amazon Machine Image (AMI).

Operations In-text references to operations.

Use the GetHITResponse operation.

Parameters In-text references to parameters.

The operation accepts the parameter AccountID.

Response elements In-text references to responses.

A container for one CollectionParent and one or more
CollectionItems.

Technical publication References to other AWS publications. If the reference is hyperlinked, it is

references also underscored.
For detailed conceptual information, see the Amazon Mechanical Turk
Developer Guide.

User entered values A special font marks text that the user types.
At the password prompt, type MyPassword.

User interface controls Denotes named items on the UI for easy identification.
and labels On the File menu, click Properties.

Variables When you see this style, you must change the value of the content when you
copy the text of a sample to a command line.
% ec2-register <your-s3-bucket>/image.manifest
See also the symbol convention below.

API Version 2008-02-01

219
 Amazon Elastic Compute Cloud Developer Guide
Symbol Conventions

Symbol Conventions
This section describes the common use of symbols.

Convention Symbol Description/Example

Mutually (Parentheses | and | Within a code description, bar separators denote options from
exclusive vertical | bars) which one must be chosen.
parameters
% data = hdfread (start | stride | edge)

Optional [square brackets] Within a code description, square brackets denote completely
parameters optional commands or parameters.
XML variable
text % sed [-n, -quiet]

Use square brackets in XML examples to differentiate them

from tags.

<CustomerId>[ID]</CustomerId>

Variables <arrow brackets> Within a code sample, arrow brackets denote a variable that
must be replaced with a valid value.

% ec2-register <your-s3-bucket>/image.manifest

API Version 2008-02-01

220
 Amazon Elastic Compute Cloud Developer Guide

CLI
ec2-add-group, 174
Index ec2-add-keypair, 171, 175
ec2-allocate-address, 176
ec2-associate-address, 177
A ec2-authorize, 178
actions, 68 ec2-bundle-image, 160
addressing, 53 ec2-bundle-vol, 163
AllocateAddress, 86, 122 ec2-confirm-product-instance, 180
allocating elastic IP addresses, 86, 122, 176 ec2-delete-bundle, 166
Amazon DevPay, 28 ec2-delete-group, 181
AMI tools ec2-delete-keypair, 182
ec2-add-keypair, 171 ec2-deregister, 183
ec2-bundle-image, 160 ec2-describe-addresses, 184
ec2-bundle-vol, 163 ec2-describe-availability-zones, 185
ec2-delete-bundle, 166 ec2-describe-group, 186
ec2-download-bundle, 168 ec2-describe-image-attribute, 187
ec2-unbundle, 169 ec2-describe-images, 189
AMIs ec2-describe-instances, 191
bundling, 18 ec2-describe-keypairs, 192
creating, 6 ec2-disassociate-address, 185
paid, 48 ec2-download-bundle, 168
shared, 47 ec2-fingerprint-key, 193
finding, 47 ec2-get-console-output, 194
security, 47 ec2-modify-image-attribute, 194
sharing, 21 ec2-reboot-instances, 196
API ec2-register, 198
actions, 68 ec2-release-address, 197
common data types, 73 ec2-reset-image-attribute, 199
conventions, 68 ec2-revoke, 200
data types, 69 ec2-run-instances, 202
Query, 64 ec2-terminate-instances, 205
reference, 68 ec2-unbundle, 169
SOAP, 61 list of operations, 173
APIs, using, 61 client error codes, 70
AssociateAddress, 86, 123 command line tools, 159
associating elastic IP addresses, 86, 123, 177 AMI tools, 160
audience, 2 API tools, 173
authentication errors, 159
Query, 65 options, 159
SOAP, 62 common data types, 73
AuthorizeSecurityGroupIngress, 87, 124 computation building block, 35
authorizing security group ingress, 87, 124, 178 compute resources, measuring, 37
availability zones, 45, 212 confirming instances, 89, 126, 180
describing, 96, 133, 185 ConfirmProductInstance, 89, 126
AvailabilityZoneItemType, 73 console output, 51
getting, 107, 144, 194
conventions
B API, 68
batch processing, 5 CPU, 37
best practices, 35 CreateKeyPair, 90, 127
block device mapping, 215 CreateSecurityGroup, 91, 129
BlockDeviceMappingItemType, 73 creating AMIs, 6
bundling AMIs, 18 creating keypairs, 90, 127
creating paid AMIs, 28
C
categories, 38 D
changes to Amazon EC2, 1 data retrieval, 39

API Version 2008-02-01

221
 Amazon Elastic Compute Cloud Developer Guide

data types, 69 ec2-bundle-image, 160

AvailabilityZoneItemType, 73 ec2-bundle-vol, 163
BlockDeviceMappingItemType, 73 ec2-confirm-product-instance, 180
DescribeImagesResponseItemType, 74 ec2-delete-bundle, 166
DescribeKeyPairsResponseItemType, 75 ec2-delete-group, 181
EmptyElementType, 75 ec2-delete-keypair, 182
GroupSetType, 76 ec2-deregister, 183
InstanceStateType, 76 ec2-describe-addresses, 184
IpPermissionType, 77 ec2-describe-availability-zones, 185
LaunchPermissionItemType, 78 ec2-describe-group, 186
LaunchPermissionOperationType, 78 ec2-describe-image-attribute, 187
PlacementRequestType, 79 ec2-describe-images, 189
PlacementResponseType, 79 ec2-describe-instances, 191
ProductCodeItemType, 79 ec2-describe-keypairs, 192
ProductInstanceResponseItemType, 80 ec2-disassociate-address, 185
ReservationInfoType, 80 ec2-download-bundle, 168
RunningInstancesItemType, 81 ec2-fingerprint-key, 193
SecurityGroupItemType, 82 ec2-get-console-output, 194
TerminateInstancesResponseInfoType, 83 ec2-modify-image-attribute, 194
UserDataType, 83 ec2-reboot-instances, 196
UserIdGroupPairType, 84 ec2-register, 198
DeleteKeyPair, 92, 130 ec2-release-address, 197
DeleteSecurityGroup, 93, 130 ec2-reset-image-attribute, 199
deleting keypairs, 92, 130, 182 ec2-revoke, 200
deleting security groups, 93, 130, 181 ec2-run-instances, 202
DeregisterImage, 94, 132 ec2-terminate-instances, 205
deregistering images, 94, 132, 183 ec2-unbundle, 169
DescribeAddresses, 95, 132 elastic IP addresses, 53
DescribeAvailabilityZones, 96, 133 allocating, 86, 122, 176
DescribeImageAttribute, 97, 135 associating, 86, 123, 177
DescribeImages, 100, 137 describing, 95, 132, 184
DescribeImagesResponseItemType, 74 disassociating, 106, 143, 185
DescribeInstances, 102, 139 releasing, 111, 148, 197
DescribeKeyPairs, 103, 140 EmptyElementType, 75
DescribeKeyPairsResponseItemType, 75 ephemeral store, 43
DescribeSecurityGroups, 104, 141 error codes, 70
describing availability zones, 96, 133, 185 errors, 212
describing elastic IP addresses, 95, 132, 184 messages, 213
describing image attributes, 97, 135, 187 example Query request, 67
describing images, 100, 137, 189
describing instances, 102, 139, 191 F
describing keypairs, 103, 140, 192
describing security groups, 104, 141, 186 FAQs, 206
device mapping, 215 availability zones, 212
DevPay, 28 block device mapping, 215
DisassociateAddress, 106, 143 errors, 212
disassociating elastic IP addresses, 106, 143, 185 general, 206
disk instance types, 208
performance, 44 IP addresses, 210
RAID, 44 kernels, 215
DNS, internal, 54 miscellaneous, 216
monitoring, 212
operations, 207
E paid AMIs, 214
ec2-add-group, 174 proximity, 212
ec2-add-keypair, 171, 175 RAM disk, 215
ec2-allocate-address, 176 unexpected behaviors, 212
ec2-associate-address, 177 firewall
ec2-authorize, 178 concepts, 57

API Version 2008-02-01

222
 Amazon Elastic Compute Cloud Developer Guide

LaunchPermissionOperationType, 78
G locality, 45
general information, 206
GetConsoleOutput, 107, 144 M
getopt, 159 mapping, block device, 215
getting console output, 107, 144, 194 memory, 37
glossary, 217 metadata, 37
groups, 57 categories, 38
GroupSetType, 76 retrieval, 39
miscellaneous FAQs, 216
I ModifyImageAttribute, 108, 145
modifying image attributes, 108, 145, 194
I/O resources, 37 monitoring information, 212
images
deregistering, 94, 132, 183
describing, 100, 137, 189 N
describing attributes, 97, 135, 187 NAT, 53
modifying attributes, 108, 145, 194 network security, 53
registering, 110, 149, 198 new features, 1
resetting attributes, 112, 150, 199
instance types, 208 O
instances
addressing, 53 operations
confirming, 89, 126, 180 CLI, 173
describing, 102, 139, 191 information, 207
launching, 35 Query, 85, 120, 121
metadata, 37 SOAP, 84
rebooting, 51, 109, 147, 196 output, console, 51
running, 115, 153, 202 overview, 5
security, 53
sizes, 36 P
storage, 43 paid AMIs
terminating, 119, 157, 205 creating, 28
types, 36 information, 214
usage, 35 Paid AMIs, 48
InstanceStateType, 76 parameters, Query, 120
introduction, 5 performance, optimization, 44
IP address information, 210 permissions, 35
IP addresses PlacementRequestType, 79
allocating, 86, 122, 176 PlacementResponseType, 79
associating, 86, 123, 177 private addresses, 53
describing, 95, 132, 184 ProductCodeItemType, 79
disassociating, 106, 143, 185 ProductInstanceResponseItemType, 80
releasing, 111, 148, 197 programming language support, 62
IpPermissionType, 77 proximity, 45, 212
public addresses, 53
K
kernels, 215 Q
keypairs Query
creating, 90, 127 AllocateAddress, 122
deleting, 92, 130, 182 API, 64
describing, 103, 140, 192 AssociateAddress, 123
authentication, 65
L AuthorizeSecurityGroupIngress, 124
launch data, security, 39 common parameters, 120
launch index, example, 41 ConfirmProductInstance, 126
LaunchPermissionItemType, 78 CreateKeyPair, 127
CreateSecurityGroup, 129

API Version 2008-02-01

223
 Amazon Elastic Compute Cloud Developer Guide

DeleteKeyPair, 130 authorizing ingress, 87, 124, 178

DeleteSecurityGroup, 130 deleting, 93, 130, 181
DeregisterImage, 132 describing, 104, 141, 186
DescribeAddresses, 132 revoking ingress, 113, 151, 200
DescribeAvailabilityZones, 133 SecurityGroupItemType, 82
DescribeImageAttribute, 135 server error codes, 70
DescribeImages, 137 service overview, 5
DescribeInstances, 139 shared AMIs, 47
DescribeKeyPairs, 140 finding, 47
DescribeSecurityGroups, 141 security, 47
DisassociateAddress, 143 sharing AMIs, 21
example request, 67 sizes of instances, 36
GetConsoleOutput, 144 SOAP
list of operations, 85, 121 AllocateAddress, 86
ModifyImageAttribute, 145 API, 61
operations, 120 AssociateAddress, 86
parameters, 65 authentication, 62
RebootInstances, 147 AuthorizeSecurityGroupIngress, 87
RegisterImage, 149 ConfirmProductInstance, 89
ReleaseAddress, 148 CreateKeyPair, 90
ResetImageAttribute, 150 CreateSecurityGroup, 91
RevokeSecurityGroupIngress, 151 DeleteKeyPair, 92
RunInstances, 153 DeleteSecurityGroup, 93
TerminateInstances, 157 DeregisterImage, 94
DescribeAddresses, 95
R DescribeAvailabilityZones, 96
DescribeImageAttribute, 97
RAID, 44 DescribeImages, 100
RAM disk, 215 DescribeInstances, 102
reboot, 51 DescribeKeyPairs, 103
rebooting instances, 109, 147, 196 DescribeSecurityGroups, 104
RebootInstances, 109, 147 DisassociateAddress, 106
reference, API, 68 GetConsoleOutput, 107
RegisterImage, 110, 149 ModifyImageAttribute, 108
registering images, 110, 149, 198 operations, 84
ReleaseAddress, 111, 148 RebootInstances, 109
releasing elastic IP addresses, 111, 148, 197 RegisterImage, 110
required knowledge, 2 ReleaseAddress, 111
ReservationInfoType, 80 ResetImageAttribute, 112
ResetImageAttribute, 112, 150 response structure, 63, 63
resetting image attributes, 112, 150, 199 RevokeSecurityGroupIngress, 113
resources, 3 RunInstances, 115
I/O, 37 TerminateInstances, 119
measuring, 37 WSDL, 61
response structure, 63 static IPs, 53
response structure, SOAP, 63 storage, 37, 43
retrieving metadata, 39 locations, 43
retrieving user data, 40 suggestions, 35
RevokeSecurityGroupIngress, 113, 151
revoking security group ingress, 113, 151, 200
RunInstances, 115, 153 T
running instances, 115, 153, 202 temporary events, 5
RunningInstancesItemType, 81 TerminateInstances, 119, 157
TerminateInstancesResponseInfoType, 83
S terminating instances, 119, 157, 205
types of instances, 36
scalable applications, 5
security, 53
security groups, 57 U

API Version 2008-02-01

224
 Amazon Elastic Compute Cloud Developer Guide

unexpected behavior information, 212

user data, retrieval, 40
UserDataType, 83
UserIdGroupPairType, 84

W
web services references, 64
WSDL, 61

Z
zones, availability, 212

API Version 2008-02-01

225