You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: AWS::EC2::SecurityGroup

Inherits:
Resource
  • Object
show all
Includes:
TaggedItem
Defined in:
lib/aws/ec2/security_group.rb,
lib/aws/ec2/security_group/ip_permission.rb,
lib/aws/ec2/security_group/ip_permission_collection.rb

Overview

Represents a security group in EC2.

Defined Under Namespace

Classes: EgressIpPermissionCollection, IngressIpPermissionCollection, IpPermission, IpPermissionCollection

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from TaggedItem

#add_tag, #clear_tags, #tags

Constructor Details

#initialize(security_group_id, options = {}) ⇒ SecurityGroup

Returns a new instance of SecurityGroup



39
40
41
42
 
# File 'lib/aws/ec2/security_group.rb', line 39

def initialize security_group_id, options = {}
  @security_group_id = security_group_id
  super
end

Instance Attribute Details

#description ⇒ String (readonly)

The short informal description given when the group was created.

Returns:

  • (String) —

    the current value of description



30
31
32
 
# File 'lib/aws/ec2/security_group.rb', line 30

def description
  @description
end

#name ⇒ String (readonly)

The name of the security group.

Returns:

  • (String) —

    the current value of name



30
31
32
 
# File 'lib/aws/ec2/security_group.rb', line 30

def name
  @name
end

#owner_id ⇒ String (readonly)

The security group owner's id.

Returns:

  • (String) —

    the current value of owner_id



30
31
32
 
# File 'lib/aws/ec2/security_group.rb', line 30

def owner_id
  @owner_id
end

#security_group_id ⇒ String (readonly) Also known as: group_id, id

Returns:

  • (String) 


45
46
47
 
# File 'lib/aws/ec2/security_group.rb', line 45

def security_group_id
  @security_group_id
end

#vpc_id ⇒ String? (readonly)

If this is a VPC security group, vpc_id is the ID of the VPC this group was created in. Returns false otherwise.

Returns:

  • (String, nil) —

    the current value of vpc_id



30
31
32
 
# File 'lib/aws/ec2/security_group.rb', line 30

def vpc_id
  @vpc_id
end

Instance Method Details

#allow_ping(*sources) ⇒ nil

Adds ingress rules for ICMP pings. Defaults to 0.0.0.0/0 for the list of allowed IP ranges the ping can come from.

security_group.allow_ping # anyone can ping servers in this group

# only allow ping from a particular address security_group.allow_ping('123.123.123.123/0')

Parameters:

  • sources (String) —

    One or more IP ranges to allow ping from. Defaults to 0.0.0.0/0

Returns:

  • (nil) 


131
132
133
134
 
# File 'lib/aws/ec2/security_group.rb', line 131

def allow_ping *sources
  sources << '0.0.0.0/0' if sources.empty?
  authorize_ingress('icmp', -1, *sources)
end

#authorize_egress(*sources, options = {}) ⇒ nil

Note:

Calling this method on a non-VPC security group raises an error.

Authorize egress (outbound) traffic for a VPC security group.

# allow traffic for all protocols/ports from the given sources
security_group.authorize_egress('10.0.0.0/16', '10.0.0.1/16')

# allow tcp traffic outband via port 80
security_group.authorize_egress('10.0.0.0/16',
  :protocol => :tcp, :ports => 80..80)

Parameters:

  • sources (Mixed) —

    One or more CIDR IP addresses, security groups or load balancers. See #authorize_ingress for more information on accepted formats for sources.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :protocol (Symbol) — default: :any —

    The protocol name or number to authorize egress traffic for. For a complete list of protocols see: protocol-numbers.xml

  • :ports (Range<Integer>, Integer) — default: nil —

    An optional port or range of ports. This option is required depending on the protocol.

Returns:

  • (nil) 


297
298
299
300
301
302
 
# File 'lib/aws/ec2/security_group.rb', line 297

def authorize_egress *sources
  client.authorize_security_group_egress(
    :group_id => id,
    :ip_permissions => [egress_opts(sources)])
  nil
end

#authorize_ingress(protocol, ports, *sources) ⇒ nil

Add an ingress rules to this security group. Ingress rules permit inbound traffic over a given protocol for a given port range from one or more source ip addresses.

This example grants the whole internet (0.0.0.0/0) access to port 80 over TCP (HTTP web traffic).

security_group.authorize_ingress(:tcp, 80)

You can specify port ranges as well:

# ftp
security_group.authorize_ingress(:tcp, 20..21)

Sources

Security groups accept ingress trafic from:

  • CIDR IP addresses
  • security groups
  • load balancers

Ip Addresses

In the following example allow incoming SSH from a list of IP address ranges.

security_group.authorize_ingress(:tcp, 22,
  '111.111.111.111/0', '222.222.222.222/0')

Security Groups

To autohrize ingress traffic from all EC2 instance in another security group, just pass the security group:

web = security_groups.create('webservers')
db = security_groups.create('database')
db.authorize_ingress(:tcp, 3306, web)

You can also pass a hash of security group details instead of a AWS::EC2::SecurityGroup object.

# by security group name
sg.authorize_ingress(:tcp, 80, { :group_name => 'other-group' })

# by security group id
sg.authorize_ingress(:tcp, 80, { :group_id => 'sg-1234567' })

If the security group belongs to a different account, just make sure it has the correct owner ID populated:

not_my_sg = SecurityGroup.new('sg-1234567', :owner_id => 'abcxyz123')
my_sg.authorize_ingress(:tcp, 80, not_my_sg)

You can do the same with a hash as well (with either :group_id or :group_name):

sg.authorize_ingress(:tcp, 21..22, { :group_id => 'sg-id', :user_id => 'abcxyz123' })

Load Balancers

If you use ELB to manage load balancers, then you need to add ingress permissions to the security groups they route traffic into. You can do this by passing the AWS::ELB::LoadBalancer into authorize_ingress:

load_balancer = AWS::ELB.new.load_balancers['web-load-balancer']

sg.authorize_ingress(:tcp, 80, load_balancer)

Multiple Sources

You can provide multiple sources each time you call authorize ingress, and you can mix and match the source types:

sg.authorize_ingress(:tcp, 80, other_sg, '1.2.3.4/0', load_balancer)

Parameters:

  • protocol (String, Symbol) —

    Should be :tcp, :udp or :icmp or the string equivalent.

  • ports (Integer, Range) —

    The port (or port range) to allow traffic through. You can pass a single integer (like 80) or a range (like 20..21).

  • sources (Mixed) —

    One or more CIDR IP addresses, security groups, or load balancers. Security groups can be specified as hashes.

    A security group hash must provide either :group_id or :group_name for the security group. If the security group does not belong to you aws account then you must also provide :user_id (which can be an AWS account ID or alias).

Returns:

  • (nil) 


244
245
246
247
248
249
250
 
# File 'lib/aws/ec2/security_group.rb', line 244

def authorize_ingress protocol, ports, *sources
  client.authorize_security_group_ingress(
    :group_id => id,
    :ip_permissions => [ingress_opts(protocol, ports, sources)]
  )
  nil
end

#delete ⇒ nil

Deletes this security group.

If you attempt to delete a security group that contains instances, or attempt to delete a security group that is referenced by another security group, an error is raised. For example, if security group B has a rule that allows access from security group A, security group A cannot be deleted until the rule is removed.

Returns:

  • (nil) 


328
329
330
331
 
# File 'lib/aws/ec2/security_group.rb', line 328

def delete
  client.delete_security_group(:group_id => id)
  nil
end

#describe_call_name ⇒ Object 



352
 
# File 'lib/aws/ec2/security_group.rb', line 352

def describe_call_name; self.class.describe_call_name; end

#disallow_ping(*sources) ⇒ nil

Removes ingress rules for ICMP pings. Defaults to 0.0.0.0/0 for the list of IP ranges to revoke.

Parameters:

  • sources (String) —

    One or more IP ranges to disallow ping from. Defaults to 0.0.0.0/0

Returns:

  • (nil) 


144
145
146
147
 
# File 'lib/aws/ec2/security_group.rb', line 144

def disallow_ping *sources
  sources << '0.0.0.0/0' if sources.empty?
  revoke_ingress('icmp', -1, *sources)
end

#egress_ip_permissions ⇒ SecurityGroup::EgressIpPermissionCollection

Returns a collection of IpPermission objects that represents all of the egress permissions this security group has authorizations for.

Returns:



114
115
116
 
# File 'lib/aws/ec2/security_group.rb', line 114

def egress_ip_permissions
  EgressIpPermissionCollection.new(self, :config => config)
end

#exists? ⇒ Boolean

Returns True if the security group exists.

Returns:

  • (Boolean) —

    True if the security group exists.



79
80
81
82
83
 
# File 'lib/aws/ec2/security_group.rb', line 79

def exists?
  client.describe_security_groups(:filters => [
    { :name => "group-id", :values => [id] }
  ]).security_group_index.key?(id)
end

#ingress_ip_permissions ⇒ SecurityGroup::IngressIpPermissionCollection Also known as: ip_permissions

Returns a collection of IpPermission objects that represents all of the (ingress) permissions this security group has authorizations for.

Returns:



106
107
108
 
# File 'lib/aws/ec2/security_group.rb', line 106

def ingress_ip_permissions
  IngressIpPermissionCollection.new(self, :config => config)
end

#instances ⇒ InstanceCollection

Returns an instance collection that will only enumerate instances in this security group.

Returns:

  • (InstanceCollection) —

    Returns an instance collection that will only enumerate instances in this security group.



69
70
71
72
73
74
75
76
 
# File 'lib/aws/ec2/security_group.rb', line 69

def instances
  instances = InstanceCollection.new(:config => config)
  if vpc?
    instances.filter('instance.group-id', [group_id])
  else
    instances.filter('group-id', [group_id])
  end
end

#revoke_egress(*sources) ⇒ nil

Revokes an egress (outound) ip permission. This is the inverse operation to #authorize_egress. See #authorize_egress for param and option documentation.

Returns:

  • (nil)

See Also:



312
313
314
315
316
317
 
# File 'lib/aws/ec2/security_group.rb', line 312

def revoke_egress *sources
  client.revoke_security_group_egress(
    :group_id => id,
    :ip_permissions => [egress_opts(sources)])
  nil
end

#revoke_ingress(protocol, ports, *sources) ⇒ nil

Revokes an ingress (inbound) ip permission. This is the inverse operation to #authorize_ingress. See #authorize_ingress for param and option documentation.

Returns:

  • (nil)

See Also:



260
261
262
263
264
265
266
 
# File 'lib/aws/ec2/security_group.rb', line 260

def revoke_ingress protocol, ports, *sources
  client.revoke_security_group_ingress(
    :group_id => id,
    :ip_permissions => [ingress_opts(protocol, ports, sources)]
  )
  nil
end

#vpc ⇒ VPC?

Returns the VPC this security group belongs to, or nil if this is not a VPC security group.

Returns:

  • (VPC, nil) —

    Returns the VPC this security group belongs to, or nil if this is not a VPC security group.



96
97
98
99
100
 
# File 'lib/aws/ec2/security_group.rb', line 96

def vpc
  if vpc_id
    VPC.new(vpc_id, :config => config)
  end
end

#vpc? ⇒ Boolean

Returns true if this security group is a VPC security group and not an EC2 security group. VPC security groups belong to a VPC subnet and can have egress rules.

Returns:

  • (Boolean) —

    Returns true if this is a VPC security group and false if this is an EC2 security group.



90
91
92
 
# File 'lib/aws/ec2/security_group.rb', line 90

def vpc?
  vpc_id ? true : false
end