ec2-describe-group

Description

Returns information about security groups in your account. This includes both EC2 security groups and VPC security groups. For information about how the two types of groups differ, go to Security Groups in the Amazon Virtual Private Cloud User Guide.

You can filter the results to return information only about security groups that match criteria you specify. For example, you could get information about groups whose name contains a particular string. You can specify multiple values for a filter. A security group 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 group's name contains a particular string, and the group gives permission to another security group with a different string in its name). The result includes information for a particular group only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty.

Important

	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, let's say you want to get all groups that have access on port 22. And let's say 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), GroupA will not be returned in the results. It will only be returned in the results if you specify `ip-permission.from-port=20` or `ip-permission.to-port=30` (or both).

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, let's say you want to get all groups that have access on port 22. And let's say 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), GroupA will not be returned in the results. It will only be returned in the results if you specify ip-permission.from-port=20 or ip-permission.to-port=30 (or both).

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 security group. Type: String
`group-id`	ID of the security group. Type: String
`group-name`	Name of the security group. Type: String
`ip-permission.cidr`	CIDR range that has been granted the permission. Type: String
`ip-permission.from-port`	Start of port range for the TCP and UDP protocols, or an ICMP type number. Type: String
`ip-permission.group-name`	Name of security group that has been granted the permission. Type: String
`ip-permission.protocol`	IP protocol for the permission. Type: String Valid Values: `tcp` \| `udp` \| `icmp` or a protocol number
`ip-permission.to-port`	End of port range for the TCP and UDP protocols, or an ICMP code. Type: String
`ip-permission.user-id`	ID of AWS account that has been granted the permission. Type: String
`owner-id`	AWS account ID of the owner of the security group. Type: String
`tag-key`	Key of a tag assigned to the security group. Type: String
`tag-value`	Value of a tag assigned to the security group. Type: String

The short version of this command is ec2dgrp.

Syntax

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

Options

Name Description Required

Name	Description	Required
`ec2_group_name_or_id` or `vpc_group_id`	For EC2 security groups: the name or ID of the group. For VPC security groups: the ID of the group. Type: String Default: Describes all groups you own, or only those otherwise specified. Example: websrv	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 security groups you own, or only those otherwise specified. Example: --filter "group-name=webserver"	No

ec2_group_name_or_id or vpc_group_id

For EC2 security groups: the name or ID of the group.

For VPC security groups: the ID of the group.

Type: String

Default: Describes all groups you own, or only those otherwise specified.

Example: websrv

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 security groups you own, or only those otherwise specified.

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

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-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 ("GROUP")
Security group ID
AWS account ID of security group owner
Security group name
Security group description
Output type identifier ("PERMISSION")
AWS account ID of the group owner
Name of group granting permission
Type of rule. Currently, only ALLOW rules are supported
Protocol to allow
Start of port range
End of port range
Source (for ingress rules) or destination (for egress rules)
Any tags assigned to the security group

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example returns information about a specific EC2 security group called StandardGroup.

PROMPT> ec2-describe-group StandardGroup
GROUP   sg-1974436d     999988887777    StandardGroup      A standard EC2 group
PERMISSION      999988887777    StandardGroup      ALLOWS  tcp     80      80      FROM    CIDR    102.11.43.32/32  ingress

Example Request

This example returns information about a specific VPC security group with ID sg-eea7b782.

PROMPT> ec2-describe-group sg-eea7b782GROUP   sg-eea7b782     999988887777    WebServerSG     web servers     vpc-5266953b
PERMISSION      999988887777    WebServerSG     ALLOWS  6       80      80      FROM    CIDR    162.5.5.5/32    ingress
PERMISSION      999988887777    WebServerSG     ALLOWS  6       80      80      FROM    USER    999988887777            ID sg-78a9b914  ingress
PERMISSION      999988887777    WebServerSG     ALLOWS  6       443     443     FROM    USER    999988887777            ID sg-78a9b914  ingress
PERMISSION      999988887777    WebServerSG     ALLOWS  all                      TO      CIDR    0.0.0.0/0       egress
PERMISSION      999988887777    WebServerSG     ALLOWS  6       1433    1433    TO      USER    999988887777            ID sg-80aebeec  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"

Description

Syntax

Options

Common Options

Output

Examples

Example Request

Example Request

Example Request

Related Operations