Amazon Elastic Compute Cloud
CLI Reference (API Version 2011-12-15)
Print this pageEmail this pageGo to the ForumsView the PDFShare this page on TwitterShare this page on FacebookBookmark this page on DeliciousSubmit this page to RedditSubmit this page to DiggDid this page help you?  Yes  No   Tell us about it...

ec2-describe-instances

Description

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, an error 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.

You can filter the results to return information only about instances that match criteria you specify. For example, you could get information about only instances launched with a certain key pair. You can specify multiple values for a filter (e.g., the instance was launched with either key pair A or key pair B). An instance must match at least one of the specified values for it to be included in the results.

You can specify multiple filters (e.g., the instance was launched with a certain key pair and uses an Amazon EBS volume as the root device). An instance must match all the filters for it to be included in the results. If there's no match, no special message is returned; the response is simply empty.

You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.

The following table shows the available filters.

Filter Name Description

architecture

Instance architecture.

Type: String

Valid Values: i386 | x86_64

availability-zone

Instance's Availability Zone.

Type: String

block-device-mapping.attach-time

Attach time for an Amazon EBS volume mapped to the instance, e.g., 2010-09-15T17:15:20.000Z

Type: xsd:dateTime

block-device-mapping.delete-on-termination

Whether the Amazon EBS volume is deleted on instance termination.

Type: Boolean

block-device-mapping.device-name

Device name (e.g., /dev/sdh) for an Amazon EBS volume mapped to the instance.

Type: String

block-device-mapping.status

Status for an Amazon EBS volume mapped to the instance.

Type: String

Valid Values: attaching | attached | detaching | detached

block-device-mapping.volume-id

ID for an Amazon EBS volume mapped to the instance.

Type: String

client-token

Idempotency token you provided when you launched the instance.

Type: String

dns-name

Public DNS name of the instance.

Type: String

group-id

ID of a EC2 security group the instance is in. This filter does not work for VPC security groups (instead, use instance.group-id).

Type: String

group-name

Name of a EC2 security group the instance is in. This filter does not work for VPC security groups (instead, use instance.group-name).

Type: String

image-id

ID of the image used to launch the instance.

Type: String

instance-id

ID of the instance.

Type: String

instance-lifecycle

Whether this is a Spot Instance.

Type: String

Valid Values: spot

instance-state-code

Code identifying the instance's state. 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

Type: Integer

Valid Values: 0 (pending) | 16 (running) | 32 (shutting-down) | 48 (terminated) | 64 (stopping) | 80 (stopped)

instance-state-name

Instance's state.

Type: String

Valid Values: pending | running | shutting-down | terminated | stopping | stopped

instance-type

Type of instance (e.g., m1.small).

Type: String

instance.group-id

ID of a VPC security group the instance is in. This filter does not work for EC2 security groups (instead, use group-id).

Type: String

instance.group-name

Name of a VPC security group the instance is in. This filter does not work for EC2 security groups (instead, use group-name).

Type: String

ip-address

Public IP address of the instance.

Type: String

kernel-id

Kernel ID.

Type: String

key-name

Name of the key pair used when the instance was launched.

Type: String

launch-index

When launching multiple instances at once, this is the index for the instance in the launch group (e.g., 0, 1, 2, etc.).

Type: String

launch-time

Time instance was launched, e.g., 2010-08-07T11:54:42.000Z.

Type: xsd:dateTime

monitoring-state

Whether monitoring is enabled for the instance.

Type: String

Valid Values: disabled | enabled

owner-id

AWS account ID of the instance owner.

Type: String

placement-group-name

Name of the placement group the instance is in.

Type: String

platform

Use windows if you have Windows based instances; otherwise, leave blank.

Type: String

Valid Value: windows

private-dns-name

Private DNS name of the instance.

Type: String

private-ip-address

Private IP address of the instance.

Type: String

product-code

Product code associated with the AMI used to launch the instance.

Type: String

ramdisk-id

RAM disk ID.

Type: String

reason

Reason for the instance's current state (e.g., shows "User Initiated [date]" when you stop or terminate the instance). Similar to the state-reason-code filter.

Type: String

requester-id

ID of the entity that launched the instance on your behalf (e.g., AWS Management Console, Auto Scaling, etc.)

Type: String

reservation-id

ID of the instance's reservation. A reservation ID is created any time you launch an instance. A reservation ID has a one-to-one relationship with an instance launch request, but can be associated with more than one instance if you launch multiple instances using the same launch request. For example, if you launch one instance, you’ll get one reservation ID. If you launch ten instances using the same launch request, you’ll also get one reservation ID.

Type: String

root-device-name

Root device name of the instance (e.g., /dev/sda1).

Type: String

root-device-type

Root device type the instance uses.

Type: String

Valid Values: ebs | instance-store

source-dest-check

Whether the instance performs source/destination checking. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the instance to perform Network Address Translation (NAT) in your VPC.

Type: Boolean

spot-instance-request-id

ID of the Spot Instance request.

Type: String

state-reason-code

Reason code for the state change.

Type: String

state-reason-message

Message for the state change.

Type: String

subnet-id

ID of the subnet the instance is in (if using Amazon Virtual Private Cloud).

Type: String

tag-key

Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table.

For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide.

Type: String

tag-value

Value of a tag assigned to the resource. This filter is independent of the tag-key filter.

Type: String

tag:key

Filters the results based on a specific tag/value combination.

Example: To list just the resources assigned tag Purpose=X, then specify:

--filter tag:Purpose=X

Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify:

--filter tag:Purpose=X --filter tag:Purpose=Y

virtualization-type

Virtualization type of the instance.

Type: String

Valid Values: paravirtual | hvm

vpc-id

ID of the VPC the instance is in (if using Amazon Virtual Private Cloud).

Type: String

hypervisor

Hypervisor type of the instance.

Type: String

Valid Values: ovm | xen

The short version of this command is ec2din.

Syntax

ec2-describe-instances [instance_id ...] [[--filter name=value] ...]

Options

NameDescriptionRequired

instance_id

Instance IDs to describe.

Type: String

Default: Returns all instances, or only those otherwise specified.

Example: i-15a4417c

No

--filter name=value

A filter for limiting the results. See the preceding table for a list of allowed filter names and values. If you're using the command line tools on a Windows system, you might need to use quotation marks (i.e., "name=value").

Type: String

Default: Describes all instances you own or those you specify by ID.

Example: --filter "tag-key=Production"

No

Common Options

OptionDescription

--region REGION

Overrides the Region specified in the EC2_URL environment variable and the URL specified by the -U option.

Default: The EC2_URL environment variable, or us-east-1 if the environment variable is not set.

Example: --region eu-west-1

-U, --url URL

URL is the uniform resource locator of the Amazon EC2 web service entry point.

Default: The EC2_URL environment variable, or https://ec2.amazonaws.com if the environment variable is not set.

Example: -U https://ec2.amazonaws.com

-K, --private-key EC2-PRIVATE-KEY

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem

-C, --cert 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

--connection-timeout TIMEOUT

Specifies a connection timeout (in seconds).

Example: --connection-timeout 30

--request-timeout TIMEOUT

Specifies a request timeout (in seconds).

Example: --request-timeout 45

-v, --verbose

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.

-H, --headers

Displays column headers in the output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Do not display tags for tagged resources.

--debug

Prints internal debugging information. This is useful to assist us when troubleshooting problems.

-?, --help, -h

Displays Help.

-

If - is specified as an argument to one of the parameters, a list of arguments is read from standard input. This is useful for piping the output of one command into the input of another.

Example: ec2-describe-instances | grep stopped | cut -f 2 | ec2-start-instances -

Output

The command returns a table that contains the following information:

  • Output type identifier ("RESERVATION")

  • Reservation ID

  • AWS account ID

  • Name of each security group the instance is in (for instances not running in a VPC)

  • Output type identifier ("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.

  • Instance state

  • Key name. If a key was associated with the instance at launch, its name will appear.

  • AMI launch index

  • Product codes attached to the instance

  • Instance type

  • Instance launch time

  • Availability Zone

  • Kernel ID

  • RAM disk ID

  • Monitoring state

  • Public IP address

  • Private IP address

  • The tenancy of the instance (if the instance is running within a VPC). An instance with a tenancy of dedicated runs on single-tenant hardware.

  • Subnet ID (if the instance is running in a VPC)

  • VPC ID (if the instance is running in a VPC)

  • Type of root device (ebs or instance-store)

  • Placement group the cluster instance is in

  • Virtualization type (paravirtual or hvm)

  • IDs of each security group the instance is in (for instances running in a VPC)

  • Any tags assigned to the instance

  • Hypervisor type (xen or ovm)

  • BLOCKDEVICE identifier for each Amazon EBS volume the instance is using, along with the device name, the volume ID, and the timestamp

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example describes the current state of the instances owned by your AWS account.

PROMPT> ec2-describe-instances

RESERVATION     r-705d5818      999988887777    default
INSTANCE        i-53cb5b38      ami-b232d0db    ec2-184-73-10-99.compute-1.amazonaws.com domU-12-31-39-00-A5-11.compute-1.internal        running         0               m1.small 2010-04-07T12:49:28+0000 us-east-1a      aki-94c527fd    ari-96c527ff            monitoring-disabled       184.73.10.99    10.254.170.223                  ebs   paravirtual  xen
BLOCKDEVICE     /dev/sda1       vol-a36bc4ca    2010-04-07T12:28:01.000Z
BLOCKDEVICE     /dev/sdb        vol-a16bc4c8    2010-04-07T12:28:01.000Z
RESERVATION     r-705d5818      999988887777    default
INSTANCE        i-39c85852      ami-b232d0db                    terminated      gsg-keypair       0               m1.small        2010-04-07T12:21:21+0000        us-east-1a      aki-94c527fd      ari-96c527ff            monitoring-disabled                              ebs   paravirtual  xen
RESERVATION     r-9284a1fa      999988887777    default
INSTANCE        i-996fc0f2      ami-3c47a355    ec2-184-73-195-182.compute-1.amazonaws.com domU-12-31-39-09-25-62.compute-1.internal       running keypair    0               m1.small  2010-03-17T13:17:41+0000        us-east-1a      aki-a71cf9ce    ari-a51cf9cc     monitoring-disabled      184.73.195.182  10.210.42.144                   instance-store   paravirtual  xen

Example Request

This example filters the results to display only the m1.small or m1.large instances that have an Amazon EBS volume that is both attached and set to delete on termination.

PROMPT> ec2-describe-instances --filter "instance-type=m1.small" --filter "instance-type=m1.large" --filter "block-device-mapping.status=attached" --filter "block-device-mapping.delete-on-termination=true"
RESERVATION     r-bc7e30d7      999988887777    default
INSTANCE        i-c7cd56ad      ami-b232d0db    ec2-72-44-52-124.compute-1.amazonaws.com        domU-12-31-39-01-76-06.compute-1.internal       running       GSG_Keypair     0               m1.small        2010-08-17T01:15:16+0000        us-east-1b  aki-94c527fd        ari-96c527ff            monitoring-disabled   72.44.52.124    10.255.121.240                  ebs    paravirtual  xen
BLOCKDEVICE     /dev/sda1       vol-a482c1cd    2010-08-17T01:15:26.000Z