Class: AWS::EC2::SecurityGroup

Inherits:
Resource 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/egress_ip_permission_collection.rb,
lib/aws/ec2/security_group/ingress_ip_permission_collection.rb

Overview

Represents a security group in EC2.

Defined Under Namespace

Classes: EgressIpPermissionCollection, IngressIpPermissionCollection, IpPermission

Constant Summary collapse

IpPermissionCollection =

alias for ingress permissions

IngressIpPermissionCollection

Instance Attribute Summary collapse

Attributes included from Core::Model

#config

Class Method Summary collapse

Instance Method Summary collapse

Methods included from TaggedItem

#add_tag, #cached_tags, #clear_tags, #tagging_resource_type, #tags

Methods inherited from Core::Resource

attribute_providers, attribute_providers_for, attributes, #attributes_from_response, define_attribute_type, #eql?, #inspect, new_from

Methods included from Core::Cacheable

included, #retrieve_attribute

Methods included from Core::Model

#client, #config_prefix, #inspect

Constructor Details

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

Returns a new instance of SecurityGroup.



41
42
43
44
 
# File 'lib/aws/ec2/security_group.rb', line 41

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) 


47
48
49
 
# File 'lib/aws/ec2/security_group.rb', line 47

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

Class Method Details

.describe_call_name ⇒ Object 



335
336
337
 
# File 'lib/aws/ec2/security_group.rb', line 335

def self.describe_call_name
  :describe_security_groups
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) 


122
123
124
125
 
# File 'lib/aws/ec2/security_group.rb', line 122

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: http://www.iana.org/assignments/protocol-numbers/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) 


288
289
290
291
292
293
 
# File 'lib/aws/ec2/security_group.rb', line 288

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 souce 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) 


235
236
237
238
239
240
241
 
# File 'lib/aws/ec2/security_group.rb', line 235

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) 


319
320
321
322
 
# File 'lib/aws/ec2/security_group.rb', line 319

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

#describe_call_name ⇒ Object 



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

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) 


135
136
137
138
 
# File 'lib/aws/ec2/security_group.rb', line 135

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:



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

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.



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

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

#inflected_name ⇒ Object 



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

def inflected_name
  "group"
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:



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

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

#resource_type ⇒ Object 



325
326
327
 
# File 'lib/aws/ec2/security_group.rb', line 325

def resource_type
  'security-group'
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:



303
304
305
306
307
308
 
# File 'lib/aws/ec2/security_group.rb', line 303

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:



251
252
253
254
255
256
257
 
# File 'lib/aws/ec2/security_group.rb', line 251

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.



87
88
89
90
91
 
# File 'lib/aws/ec2/security_group.rb', line 87

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.



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

def vpc?
  vpc_id ? true : false
end