Amazon Elastic Compute Cloud
CLI Reference (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » Command Line Reference » Commands (CLI Tools) » ec2-describe-group
« 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-group

Description

Describes one or more of your security groups.

A security group is for use with instances either in the EC2-Classic platform or in a specific VPC. For more information, see Amazon EC2 Security Groups in the Amazon Elastic Compute Cloud User Guide and Security Groups for Your VPC in the Amazon Virtual Private Cloud User Guide.

The short version of this command is ec2dgrp.

Syntax

ec2-describe-group [ec2_group_name_or_id | vpc_group_id ...] [[--filter "name=value"] ...]

Options

NameDescription

ec2_group_name_or_id or vpc_group_id

EC2-Classic, default VPC: The name or ID of one or more security groups.

nondefault VPC: The ID of one more security groups.

Type: String

Default: Describes all your security groups, or only those you specified by name.

Required: No

Example: websrv

-F, --filter name=value

A filter for limiting the results. See the Supported Filters section for a list of supported filters. 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=value").

Type: String

Default: Describes all your security groups, or only those you specified by ID.

Required: No

Example: --filter "group-name=*webserver*"

Supported Filters

You can specify filters so that the response includes information for only certain security groups. For example, you can use a filter to specify that you're interested in groups whose name contains a specific string. You can specify multiple values for a filter. The response includes information for a security group only if it matches at least one of the filter values that you specified.

You can specify multiple filters; for example, specify group's whose name contains a specific string, and that give permission to another security group with a different string in its name. The response includes information for a group 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.

Important

Filters are based on literal strings only. This is important to remember when you want to use filters to return only security groups with access allowed on a specific port number or numbers. For example, suppose that you want to get all groups that have access on port 22, and that GroupA gives access on a range of ports using fromPort=20 and toPort=30. If you filter with ip-permission.from-port=22 or ip-permission.to-port=22 (or both), the response does not contain information for GroupA. You get information for GroupA only if you specify ip-permission.from-port=20 or ip-permission.to-port=30 (or both).

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.

description

The description of the security group.

Type: String

group-id

The ID of the security group.

Type: String

group-name

The name of the security group.

Type: String

ip-permission.cidr

The CIDR range that has been granted the permission.

Type: String

ip-permission.from-port

The start of port range for the TCP and UDP protocols, or an ICMP type number.

Type: String

ip-permission.group-name

The name of security group that has been granted the permission.

Type: String

ip-permission.protocol

The IP protocol for the permission.

Type: String

Valid values: tcp | udp | icmp or a protocol number

ip-permission.to-port

The end of port range for the TCP and UDP protocols, or an ICMP code.

Type: String

ip-permission.user-id

The ID of an AWS account that has been granted the permission.

Type: String

owner-id

The AWS account ID of the owner of the security group.

Type: String

tag-key

The key of a tag assigned to the security group.

Type: String

tag-value

The value of a tag assigned to the security group.

Type: String

vpc-id

Only return the security groups that belong to the specified EC2-VPC ID.

Type: String

Common Options

OptionDescription

--region REGION

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

Default: The value of the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

Example: --region eu-west-1

-U, --url URL

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

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

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

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

The private key that identifies you to Amazon EC2. For more information, see Tell the Tools Who You Are.

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

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert EC2-CERT

The X.509 certificate that identifies you to Amazon EC2.

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

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-O, --aws-access-key AWS_ACCESS_KEY

The access key ID associated with your AWS account. 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

Note

For more information, see the following section, Deprecated Options.

-W, --aws-secret-key AWS_SECRET_KEY

The secret access key associated with your AWS account.

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

Note

For more information, see the following section, Deprecated Options.

-T, --security-token TOKEN AWS_DELEGATION_TOKEN

The AWS delegation token.

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

--connection-timeout TIMEOUT

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout TIMEOUT

The request timeout, in seconds.

Example: --request-timeout 45

-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 our Query API.

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

-?, --help, -h

Displays usage information for the command.

-

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 -

Deprecated Options

For a limited time, you can still use the private key and X.509 certificate instead of your access key ID and secret access key. However, we recommend that you start using your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) now, as the private key (-K, --private-key) and X.509 certificate (-C, --cert) won't be supported after the transition period elapses. For more information, see Tell the Tools Who You Are.

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

A line containing the group information

  • The GROUP identifier

  • The ID of the security group

  • The AWS account ID of the owner of the security group

  • The name of the security group

  • A description of the security group

  • [VPC only] The ID of the VPC the group belongs to

One of each of the following lines for each permission defined by the group:

  • The PERMISSION identifier

  • The AWS account ID of the owner of the group

  • The name of the group granting permission

  • The type of rule. Currently, only ALLOWS rules are supported

  • The protocol to allow (e.g. tcp, udp, etc)

  • The start of port range

  • The end of port range

  • FROM for an ingress rule or TO for an egress rule

  • The source type (for ingress rules) or destination type (for egress rules)

  • The source (for ingress rules) or destination (for egress rules)

  • [USER only] The name of the source or destination entity

  • [USER only] The group ID

  • Whether the rule is ingress rule or an egress rule

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example returns information about a security group for EC2-Classic named StandardGroup.

PROMPT> ec2-describe-group StandardGroup
GROUP	sg-1a2b3c4d	111122223333	StandardGroup	A standard EC2 group		
PERMISSION	111122223333	StandardGroup	ALLOWS	tcp	80	80	FROM	CIDR	102.11.43.32/32	ingress

Example Request

This example returns information about a security group for EC2-VPC with the ID sg-1a2b3c4d.

PROMPT> ec2-describe-group sg-1a2b3c4d
GROUP	sg-1a2b3c4d	111122223333	WebServerSG	web servers	vpc-1a2b3c4d
PERMISSION	111122223333	WebServerSG	ALLOWS	tcp	80	80	FROM	CIDR	162.5.5.5/32	ingress
PERMISSION	111122223333	WebServerSG	ALLOWS	tcp	80	80	FROM	USER	111122223333	NAME default	ID sg-1a2b3c4d	ingress
PERMISSION	111122223333	WebServerSG	ALLOWS	tcp	443	443	FROM	USER	111122223333	NAME default	ID sg-1a2b3c4d		ingress
PERMISSION	111122223333	WebServerSG	ALLOWS	all			TO	CIDR	0.0.0.0/0	egress
PERMISSION	111122223333	WebServerSG	ALLOWS	tcp	433	433	TO	USER	111122223333	NAME default	ID sg-1a2b3c4d		egress

Example Request

This example returns information about all security groups that grant access over TCP specifically on port 22 from instances in either the app_server_group or database_group. 

PROMPT> ec2-describe-group --filter "ip-permission.protocol=tcp" 
--filter "ip-permission.from-port=22" --filter "ip-permission.to-port=22" 
--filter "ip-permission.group-name=app_server_group" --filter "ip-permission.group-name=database_group"

Related Topics

Download

Related Action

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...