Amazon Elastic Compute Cloud
CLI Reference (API Version 2014-06-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

ec2-describe-instances

Description

Describes one or more of your instances.

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 instance that you do not own, it's not included in the output.

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

The short version of this command is ec2din.

Tip

If you are using the AWS CLI, see describe-instances instead.

Syntax

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

Options

NameDescription

instance_id

One or more instance IDs.

Type: String

Default: Describes all your instances.

Required: No

Example: i-15a4417c

-F, --filter name=value

A filter for limiting the results. For more information, see the Supported Filters section. Filter names and values are case-sensitive. Use quotation marks if the value string has a space ("name=value example"). On a Windows system, use quotation marks even without a space in the value string ("name=valueexample"). If you are using Windows Powershell, you might need to use a second set of quotation marks, escaped with backticks ("`"name=valueexample`"").

Type: String

Default: Describes all your instances, or only those you specified.

Required: No

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

Supported Filters

You can specify filters so that the response includes information for only certain instances. For example, you can use a filter to specify that you're interested in instances launched with a specific key pair. You can specify multiple values for a filter. The response includes information for an instance only if it matches at least one of the filter values that you specified.

You can specify multiple filters; for example, specify instances that are launched with a specific key pair and use an Amazon EBS volume as the root device. The response includes information for an instance only if it matches all the filters that you specified. If there's no match, no special message is returned; the response is simply empty.

You can use wildcards in a filter value. An asterisk (*) matches zero or more characters, and a question mark (?) 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 are the available filters.

architecture

The instance architecture.

Type: String

Valid values: i386 | x86_64

availability-zone

The Availability Zone of the instance.

Type: String

block-device-mapping.attach-time

The attach time for an Amazon EBS volume mapped to the instance (for example, 2010-09-15T17:15:20.000Z)

Type: DateTime

block-device-mapping.delete-on-termination

Indicates whether the Amazon EBS volume is deleted on instance termination.

Type: Boolean

block-device-mapping.device-name

The device name (for example, /dev/sdh) for the Amazon EBS volume.

Type: String

block-device-mapping.status

The status for the Amazon EBS volume.

Type: String

Valid values: attaching | attached | detaching | detached

block-device-mapping.volume-id

The volume ID of the Amazon EBS volume.

Type: String

client-token

The idempotency token you provided when you launched the instance.

Type: String

dns-name

The public DNS name of the instance.

Type: String

group-id

The ID of the security group for the instance. If the instance is in EC2-Classic or a default VPC, you can use group-name instead.

Type: String

group-name

The name of the security group for the instance. If the instance is in a nondefault VPC, you must use group-id instead.

Type: String

iam-instance-profile.arn

The instance profile associated with the instance.

Type: ARN

image-id

The ID of the image used to launch the instance.

Type: String

instance-id

The ID of the instance.

Type: String

instance-lifecycle

Indicates whether this is a Spot Instance.

Type: String

Valid values: spot

instance-state-code

The state of the instance. The high byte is an opaque internal value and should be ignored. The low byte is set based on the state represented.

Type: Integer (16-bit unsigned integer)

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

instance-state-name

The state of the instance.

Type: String

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

instance-type

The type of instance (for example, m1.small).

Type: String

instance.group-id

The ID of the security group for the instance. If the instance is in EC2-Classic or a default VPC, you can use instance.group-name instead.

Type: String

instance.group-name

The name of the security group for the instance. If the instance is in a nondefault VPC, you must use instance.group-id instead.

Type: String

ip-address

The public IP address of the instance.

Type: String

kernel-id

The kernel ID.

Type: String

key-name

The name of the key pair used when the instance was launched.

Type: String

launch-index

When launching multiple instances, this is the index for the instance in the launch group (for example, 0, 1, 2, and so on).

Type: String

launch-time

The time when the instance was launched (for example, 2010-08-07T11:54:42.000Z).

Type: DateTime

monitoring-state

Indicates whether monitoring is enabled for the instance.

Type: String

Valid values: disabled | enabled

owner-id

The AWS account ID of the instance owner.

Type: String

placement-group-name

The name of the placement group for the instance.

Type: String

platform

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

Type: String

Valid value: windows

private-dns-name

The private DNS name of the instance.

Type: String

private-ip-address

The private IP address of the instance.

Type: String

product-code

The product code associated with the AMI used to launch the instance.

Type: String

product-code.type

The type of product code.

Type: String

Valid values: devpay | marketplace

ramdisk-id

The RAM disk ID.

Type: String

reason

The reason for the current state of the instance (for example, shows "User Initiated [date]" when you stop or terminate the instance). Similar to the state-reason-code filter.

Type: String

requester-id

The ID of the entity that launched the instance on your behalf (for example, AWS Management Console, Auto Scaling, and so on)

Type: String

reservation-id

The 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

The name of the root device for the instance (for example, /dev/sda1).

Type: String

root-device-type

The type of root device that the instance uses.

Type: String

Valid values: ebs | instance-store

source-dest-check

Indicates whether the instance performs source/destination checking. A value of true means that 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

The ID of the Spot Instance request.

Type: String

state-reason-code

The reason code for the state change.

Type: String

state-reason-message

A message that describes the state change.

Type: String

subnet-id

The ID of the subnet for the instance.

Type: String

tag-key

The 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 is X, see the tag:key=value filter.

For more information about tags, see Tagging Your Resources in the Amazon EC2 User Guide for Linux Instances.

Type: String

tag-value

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

Type: String

tag:key=value

The key/value combination of a tag assigned to the resource.

Example: To list the resources with the tag Purpose=X, use:

--filter tag:Purpose=X

Example: To list resources with the tag Purpose=X or the tag Purpose=Y, use:

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

tenancy

The tenancy of an instance.

Type: String

Valid values: dedicated | default

virtualization-type

The virtualization type of the instance.

Type: String

Valid values: paravirtual | hvm

vpc-id

The ID of the VPC that the instance is running in.

Type: String

hypervisor

The hypervisor type of the instance.

Type: String

Valid values: ovm | xen

network-interface.description

The description of the network interface.

Type: String

network-interface.subnet-id

The ID of the subnet for the network interface.

Type: String

network-interface.vpc-id

The ID of the VPC for the network interface.

Type: String

network-interface.network-interface.id

The ID of the network interface.

Type: String

network-interface.owner-id

The ID of the owner of the network interface.

Type: String

network-interface.availability-zone

The Availability Zone for the network interface.

Type: String

network-interface.requester-id

The requester ID for the network interface.

Type: String

network-interface.requester-managed

Indicates whether the network interface is being managed by AWS.

Type: Boolean

network-interface.status

The status of the network interface.

Type: String

Valid values: available | in-use

network-interface.mac-address

The MAC address of the network interface.

Type: String

network-interface-private-dns-name

The private DNS name of the network interface.

Type: String

network-interface.source-destination-check

Whether the network interface 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 network interface to perform network address translation (NAT) in your VPC.

Type: Boolean

network-interface.group-id

The ID of a security group associated with the network interface.

Type: String

network-interface.group-name

The name of a security group associated with the network interface.

Type: String

network-interface.attachment.attachment-id

The ID of the interface attachment.

Type: String

network-interface.attachment.instance-id

The ID of the instance to which the network interface is attached.

Type: String

network-interface.attachment.instance-owner-id

The owner ID of the instance to which the network interface is attached.

Type: String

network-interface.addresses.private-ip-address

The private IP address associated with the network interface.

Type: String

network-interface.attachment.device-index

The device index to which the network interface is attached.

Type: Integer

network-interface.attachment.status

The status of the attachment.

Type: String

Valid values: attaching | attached | detaching | detached

network-interface.attachment.attach-time

The time that the network interface was attached to an instance.

Type: Date

network-interface.attachment.delete-on-termination

Specifies whether the attachment is deleted when an instance is terminated.

Type: Boolean

network-interface.addresses.primary

Specifies whether the IP address of the network interface is the primary private IP address.

Type: Boolean

network-interface.addresses.association.public-ip

The ID of the association of an Elastic IP address with a network interface.

Type: String

network-interface.addresses.association.ip-owner-id

The owner ID of the private IP address associated with the network interface.

Type: String

association.public-ip

The address of the Elastic IP address bound to the network interface.

Type: String

association.ip-owner-id

The owner of the Elastic IP address associated with the network interface.

Type: String

association.allocation-id

The allocation ID returned when you allocated the Elastic IP address for your network interface.

Type: String

association.association-id

The association ID returned when the network interface was associated with an IP address.

Type: String

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. For more information, see Tell the Tools Who You Are.

Default: The value of the AWS_ACCESS_KEY environment variable. If AWS_ACCESS_KEY isn't set, you must specify this option.

Example: -O AKIAIOSFODNN7EXAMPLE

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

Default: The value of the AWS_SECRET_KEY environment variable. If AWS_SECRET_KEY isn't set, you must specify this option.

Example: -W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-T, --security-token delegation_token

The delegation token to pass along to the AWS request. This is only required when you are using temporary security credentials. For more information, see Using Temporary Security Credentials.

Default: The value of the AWS_DELEGATION_TOKEN environment variable (if set).

Example: -t AQoDYXdzEJr...<remainder of security token>

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

-H, --headers

Includes column headers in the command output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Omits tags for tagged resources.

--debug

Displays internal debugging information. This can assist us when helping you troubleshooting problems.

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-v, --verbose

Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to the Query API.

-

Reads arguments from standard input. This is useful when piping the output from one command to the input of another.

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

-?, --help, -h

Displays usage information for the command.

Deprecated Options

We have deprecated the SOAP API for Amazon EC2. For more information, see SOAP Requests. From version 1.6.14.0 onwards of the Amazon EC2 CLI tools, the private key (-K, --private-key) and X.509 certificate (-C, --cert) options are not supported. Use your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools.

OptionDescription

-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-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.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-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

Output

This command returns a table that contains the following rows of information for each instance. Some fields may be empty.

  1. The reservation information

    • The RESERVATION identifier

    • The ID of the reservation

    • The AWS account ID of the instance owner

    • The name of each security group the instance is in

  2. The instance information

    • The INSTANCE identifier

    • The ID of the instance

    • The AMI ID of the image on which the instance is based

    • The public DNS name associated with the instance. This is only present for instances in the running state.

    • The private DNS name associated with the instance. This is only present for instances in the running state.

    • The state of the instance

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

    • The AMI launch index

    • The product codes associated with the instance

    • The instance type

    • The instance launch time

    • The Availability Zone

    • The ID of the kernel

    • The ID of the RAM disk

    • The platform (windows or empty)

    • The monitoring state

    • The public IP address

    • The private IP address

    • [EC2-VPC] The ID of the VPC

    • [EC2-VPC] The ID of the subnet

    • The type of root device (ebs or instance-store)

    • The instance lifecycle

    • The Spot Instance request ID

    • The instance license

    • The placement group the cluster instance is in

    • The virtualization type (paravirtual or hvm)

    • The hypervisor type (xen or ovm)

    • The client token

    • The ID of each security group the instance is in

    • The tenancy of the instance (default or dedicated)

    • Whether or not the instance is EBS optimized (true or false)

    • The Amazon Resource Name (ARN) of the IAM role

  3. Any Amazon EBS volumes associated with the instance. There will be one of the following for each volume:

    • The BLOCKDEVICE identifier

    • The device name

    • The ID of the volume

    • The volume attach timestamp

    • Indicates whether the volume is deleted on instance termination (true or false)

    • The volume type

    • The I/O operations per second (IOPS)

  4. [EC2-VPC] The network interface information. There will be a set of the following for each network interface:

    1. The network interface information

      • The NIC identifier

      • The ID of the network interface

      • The ID of the subnet

      • The ID of the VPC

      • The owner ID

      • The network interface status

      • The private IP address of the network interface

      • The private DNS name

      • Whether or not source destination check is enabled (true or false)

    2. The network interface attachment information

      • The NICATTACHMENT identifier

      • The attachment ID

      • The device index

      • The device status

      • The attachment timestamp

      • Whether or not the attachment is deleted on termination (true or false)

    3. The network interface association information

      • The NICASSOCIATION identifier

      • The public IP address

      • The public IP address owner

      • The private IP address

    4. The security group information

      • The GROUP identifier

      • The security group identifier

      • The security group name

    5. The private IP address information

      • The PRIVATEIPADDRESS identifier

      • The private IP address

  5. Any tags associated with the instance. There will be one of the following for each tag

    • The TAG identifier

    • The resource type identifier

    • The ID of the resource

    • The tag key

    • The tag value

Amazon EC2 command line tools display errors on stderr.

Examples

Example 1

This example command describes all instances you own.

PROMPT> ec2-describe-instances

RESERVATION	r-1a2b3c4d	111122223333	my-security-group
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d	ec2-203-0-113-25.compute-1.amazonaws.com	ip-10-251-50-12.ec2.internal	running	my-key-pair	0		t1.micro	YYYY-MM-DDTHH:MM:SS+0000	us-west-2a	aki-1a2b3c4d			monitoring-disabled	184.73.10.99	10.254.170.223			ebs					paravirtual	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sda1       vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
RESERVATION     r-2a2b3c4d      111122223333    another-security-group
INSTANCE	i-2a2b3c4d	ami-2a2b3c4d	ec2-203-0-113-25.compute-1.amazonaws.com	ip-10-251-50-12.ec2.internal	running	my-key-pair	0		t1.micro	YYYY-MM-DDTHH:MM:SS+0000	us-west-2c			windows	monitoring-disabled	50.112.203.9	10.244.168.218			ebs					hvm	xen	ABCDE1234567890123	sg-2a2b3c4d	default	false
BLOCKDEVICE     /dev/sda1        vol-2a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true

Example 2

This example describes only the instances that have the m1.small or m1.large instance type and an attached Amazon EBS volume that will be deleted 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-1a2b3c4d	111122223333	my-security-group
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d	ec2-203-0-113-25.compute-1.amazonaws.com	ip-10-251-50-12.ec2.internal	running	my-key-pair	0		t1.micro	YYYY-MM-DDTHH:MM:SS+0000	us-west-2a	aki-1a2b3c4d			monitoring-disabled	184.73.10.99	10.254.170.223			ebs					paravirtual	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sdb        vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true

Example 3

This example command describes all your instances that are running in a VPC.

PROMPT> ec2-describe-instances --filter "vpc-id=*" 
RESERVATION	r-1a2b3c4d	111122223333		
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d			running	my-key-pair	0		m1.small	YYYY-MM-DDTHH:MM:SS+0000	us-west-2b			windows	monitoring-disabled	50.112.172.209	10.0.0.167	vpc-1a2b3c4d	subnet-1a2b3c4d	ebs					hvm	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sdb        vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
NIC	eni-1a2b3c4d	subnet-1a2b3c4d	vpc-1a2b3c4d	111122223333	in-use	10.0.1.167		true
NICATTACHMENT	eni-attach-1a2b3c4d	0	attached	YYYY-MM-DDTHH:MM:SS+0000	true
GROUP	sg-1a2b3c4d	my-security-group
PRIVATEIPADDRESS	10.0.1.167
PRIVATEIPADDRESS	10.0.1.12
TAG	instance	i-1a2b3c4d	Name	Windows
RESERVATION	r-2a2b3c4d	111122223333		
INSTANCE	i-2a2b3c4d	ami-2a2b3c4d			running	my-key-pair	0		c1.medium	YYYY-MM-DDTHH:MM:SS+0000	us-west-2b	aki-1a2b3c4d			monitoring-disabled	50.112.172.209	10.0.0.233	vpc-1a2b3c4d	subnet-1a2b3c4d	ebs					hvm	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sda1       vol-2a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
NIC	eni-2a2b3c4d	subnet-1a2b3c4d	vpc-1a2b3c4d	111122223333	in-use	10.0.1.233		true
NICATTACHMENT	eni-attach-2a2b3c4d	0	attached	YYYY-MM-DDTHH:MM:SS+0000	true
GROUP	sg-1a2b3c4d	my-security-group
PRIVATEIPADDRESS	10.0.1.233
PRIVATEIPADDRESS	10.0.1.20
TAG	instance	i-1a2b3c4d	Name	Linux

Example 4

This example command describes any instances with a network interface that has a private IP address of 10.0.0.120.

PROMPT> ec2-describe-instances --filter "network-interface.addresses.private-ip-address=10.0.0.120" 
RESERVATION	r-1a2b3c4d	111122223333 
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d			running	my-key-pair	0		c1.medium	YYYY-MM-DDTHH:MM:SS+0000	us-west-2b	aki-1a2b3c4d			monitoring-disabled	50.112.172.209	10.0.0.98	vpc-1a2b3c4d	subnet-1a2b3c4d	ebs					hvm	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sdb        vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
NIC	eni-1a2b3c4d	subnet-1a2b3c4d	vpc-1a2b3c4d	111122223333	in-use	10.0.1.98		true
NICATTACHMENT	eni-attach-1a2b3c4d	0	attached	YYYY-MM-DDTHH:MM:SS+0000	true
GROUP	sg-1a2b3c4d	my-security-group
PRIVATEIPADDRESS	10.0.0.98 
PRIVATEIPADDRESS	10.0.0.120

Example 5

This example command describes any instances that have a tag with the key Owner and the value DbAdmin.

PROMPT> ec2-describe-instances --filter "tag:Owner=DbAdmin" 
RESERVATION	r-1a2b3c4d	111122223333 
INSTANCE    i-1a2b3c4d	ami-1a2b3c4d			running	my-key-pair	0		c1.medium	YYYY-MM-DDTHH:MM:SS+0000	us-west-2b	aki-1a2b3c4d			monitoring-disabled	50.112.172.209	10.0.0.98	vpc-1a2b3c4d	subnet-1a2b3c4d	ebs					hvm	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE    /dev/sdb        vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
TAG    instance    i-1a2b3c4d    Owner    DbAdmin

To list all instances that have a tag with the key Owner, regardless of the value of the tag, use the following command.

PROMPT> ec2-describe-instances --filter "tag-key=Owner"