ec2-describe-snapshots

Description

Returns information about Amazon EBS snapshots available to you. Snapshots available to you include public snapshots available for any AWS account to launch, private snapshots you own, and private snapshots owned by another AWS account but for which you've been given explicit create volume permissions.

The create volume permissions fall into 3 categories:

Permission	Description
public	The owner of the snapshot granted create volume permissions for the snapshot to the `all` group. All AWS accounts have create volume permissions for these snapshots.
explicit	The owner of the snapshot granted create volume permissions to a specific AWS account.
implicit	An AWS account has implicit create volume permissions for all snapshots it owns.

The list of snapshots returned can be modified by specifying snapshot IDs, snapshot owners, or AWS accounts with create volume permissions. If no options are specified, Amazon EC2 returns all snapshots for which you have create volume permissions.

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

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

If you specify a list of restorable users, only snapshots with create snapshot permissions for those users are returned. You can specify AWS account IDs (if you own the snapshot(s)), self for snapshots for which you own or have explicit permissions, or all for public snapshots.

	Tip
	Use the `--help` option to view examples of ways to use this command.

You can filter the results to return information only about snapshots that match criteria you specify. For example, you could get information about snapshots whose status is pending. You can specify multiple values for a filter (e.g., the snapshot's status is either pending or completed). A snapshot 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 snapshot's status is pending, and it is tagged with a particular value). The result includes information for a particular snapshot only if it matches all your filters. 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
`description`	Description of the snapshot. Type: String
`owner-alias`	The AWS account alias (e.g., `amazon`) that owns the snapshot. Type: String
`owner-id`	ID of the AWS account that owns the snapshot. Type: String
`progress`	The progress of the snapshot, in percentage (e.g., `80%`). Type: String
`snapshot-id`	Snapshot ID. Type: String
`start-time`	Time stamp when the snapshot was initiated. Type: xsd:dateTime
`status`	Status of the snapshot. Type: String Valid Values: `pending` \| `completed` \| `error`
`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`
`volume-id`	ID of the volume the snapshot is for. Type: String
`volume-size`	The size of the volume, in GiB (e.g., `20`). Type: String

The short version of this command is ec2dsnap.

Syntax

ec2-describe-snapshots [snapshot_id ...] [-a] [-o owner ...] [-r user_id] [[--filter name=value] ...]

Options

Name	Description	Required
`snapshot_id`	The ID of the Amazon EBS snapshot. Type: String Default: Describes snapshots for which you have launch permissions. Example: snap-78a54011	No
`-a, --all` `owner`	Describe all snapshots (public, private or shared) to which you have access. Type: String Default: None Example: -a	No
`-o, --owner` `owner`	Returns snapshots owned by the specified owner. Multiple owners can be specified. Type: String Valid Values: `self` \| `amazon` \| `AWS Account ID` Default: None Example: -o 218213537122	No
`-r, --restorable-by` `user_id`	ID of an AWS account that can create volumes from the snapshot. Type: String Valid Values: `self` \| `all` \| an AWS account ID Default: None Example: -r self	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 snapshots you own, or only those otherwise specified. Example: --filter "tag-key=Production"	No

Common Options

Option	Description
`--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-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`
`--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:

SNAPSHOT identifier
ID of the snapshot
ID of the volume
Snapshot state (e.g., pending, completed, error)
Time stamp when snapshot initiated
Percentage of completion
ID of the owner
Size of the volume
Description
Any tags assigned to the snapshot

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example describes snapshot snap-7ddb6e14.

PROMPT> ec2-describe-snapshots snap-7ddb6e14
SNAPSHOT snap-7ddb6e14 vol-9539dcfc completed 2009-09-15T22:06:15.000Z 100% 111122223333 1 Daily Backup

Example Request

This example filters the results to display only snapshots with the pending status, and that are also tagged with a value that includes the string db_.

PROMPT> ec2-describe-snapshots --filter "status=pending" --filter "tag-value=*db_*"
SNAPSHOT snap-1a2b3c4d vol-8875daef pending 2010-07-29T04:12:01.000Z 30% 111122223333 15  demo_db_14_backup

Description

Syntax

Options

Common Options

Output

Examples

Example Request

Example Request

Related Operations