



Annotate this POD


New  2
Open  1
View/Report Bugs
Source   Latest Release: VM-EC2-1.25


VM::EC2::SecurityGroup - Object describing an Amazon EC2 security group


  use VM::EC2;

  @sg = $ec2->describe_security_groups;
  for my $sg (@sg) {
      $name = $sg->groupName;
      $id   = $sg->groupId;
      $desc = $sg->groupDescription;
      $tags = $sg->tags;
      @inbound_permissions  = $sg->ipPermissions;
      @outbound_permissions = $sg->ipPermissionsEgress;
      for $i (@inbound_permissions) {
         $protocol = $i->ipProtocol;
         $fromPort = $i->fromPort;
         $toPort   = $i->toPort;
         @ranges   = $i->ipRanges;

 $sg = $sg[0];

 # Add a new security rule
 $sg->authorize_incoming(-protocol  => 'tcp',
                         -port      => 80,

 # write it to AWS.


This object is used to describe an Amazon EC2 security group. It is returned by VM::EC2->describe_security_groups(). You may also obtain this object by calling an Instance object's groups() method, and then invoking one of the group's permissions() method. See VM::EC2::Group.


The following object methods are supported:

 ownerId          -- Owner of this security group
 groupId          -- ID of this security group
 groupName        -- Name of this security group
 groupDescription -- Description of this group
 vpcId            -- Virtual Private Cloud ID, if applicable
 ipPermissions    -- A list of rules that govern incoming connections
                     to instances running under this security group.
                     Each rule is a
                     L<VM::EC2::SecurityGroup::IpPermission> object.
 ipPermissionsEgress -- A list of rules that govern outgoing connections
                     from instances running under this security group.
                     Each rule is a
                     L<VM::EC2::SecurityGroup::IpPermission object>.
                     This field is only valid for VPC groups.
 tags             -- Hashref containing tags associated with this group.
                     See L<VM::EC2::Generic>. 

For convenience, the following aliases are provided for commonly used methods:

 inbound_permissions  -- same as ipPermissions()
 outbound_permissions -- same as ipPermissionsEgress()
 name                 -- same as groupName()

See VM::EC2::SecurityGroup::IpPermission for details on accessing port numbers, IP ranges and other fields associated with incoming and outgoing firewall rules.


To add or revoke firewall rules, call the authorize_incoming, authorize_outgoing, revoke_incoming or revoke_outgoing() methods one or more times. Each of these methods either adds or removes a single firewall rule. After adding or revoking the desired rules, call update() to write the modified group back to Amazon. The object will change to reflect the new permissions.

$permission = $group->authorize_incoming(%args)

Add a rule for incoming firewall traffic. Arguments are as follows:

 -protocol        The protocol, either a string (tcp,udp,icmp) or
                   the corresponding protocol number (6, 17, 1).
                   Use -1 to indicate all protocols. (required)

 -port, -ports    The port or port range. When referring to a single
                   port, you may use either the port number or the
                   service name (e.g. "ssh"). For this to work the
                   service name must be located in /etc/services.
                   When specifying a port range, use "start..end" as
                   in "8000..9000". Note that this is a string that
                   contains two dots, and not two numbers separated
                   by the perl range operator. For the icmp protocol,
                   this argument corresponds to the ICMP type number.

 -group, -groups   Security groups to authorize. Instances that belong
                    to the named security groups will be allowed
                    access. You may specify either a single group or
                    a list of groups as an arrayref. The following
                    syntaxes are recognized:

                    "sg-12345"       authorize group with this groupId
                    "12345/my group" authorize group named "my group" 
                                      owned by user 12345
                     "my group"      authorize group named "my group"
                                      owned by yourself

 -source, -source_ip Authorize incoming traffic from an IP address, IP
                      address range, or set of such ranges. IP
                      addresses use the CIDR notation of a.b.c.d/mask,
                      as described in 
                      Pass an arrayref to simultaneously authorize
                      multiple CIDR ranges.

The result of this call is a VM::EC2::SecurityGroup::IpPermission object corresponding to the rule you defined. Note that the rule is not written to Amazon until you call update().

Here are some examples:

                         -port      => 80,

 # TCP on ports 22 and 23 from anyone
                         -port      => '22..23',
                         -source_ip => '');

 # ICMP on echo (ping) port from anyone
 $sg->authorize_incoming(-protocol  => 'icmp',
                         -port      => 0,
                         -source_ip => '');

 # TCP to port 25 (mail) from instances belonging to
 # the "Mail relay" group belonging to user 12345678.
                         -port      => 25,
                         -group     => '12345678/Mail relay');

$permission = $group->authorize_outgoing(%args)

This is identical to authorize_incoming() except that the rule applies to outbound traffic. Only VPC security groups can define outgoing firewall rules.

$permission = $group->revoke_incoming($rule)

$permission = $group->revoke_incoming(%args)

This method revokes an incoming firewall rule. You can call it with a single argument consisting of a VM::EC2::SecurityGroup::IpPermission object in order to revoke that rule. Alternatively, when called with the named arguments listed for authorize_incoming(), it will attempt to match an existing rule to the provided arguments and queue it for deletion.

Here is an example of revoking all rules that allow ssh (port 22) access:

 @ssh_rules = grep {$_->fromPort == 22} $group->ipPermissions;
 $group->revoke_incoming($_) foreach @ssh_rules;

$boolean = $group->update()

This method will write all queued rule authorizations and revocations to Amazon, and return a true value if successful. The method will return false if any of the rule updates failed. You can examine the VM::EC2 object's error_str() method to determine what went wrong, and check the group object's ipPermissions() method to see what firewall rules are currently defined.

$boolean = $group->write()

An alias for update()


This method refreshes the group information from Amazon. It is called automatically by update().


When used in a string context, this object will interpolate the groupId.


VM::EC2 VM::EC2::Generic VM::EC2::Instance VM::EC2::Group VM::EC2::SecurityGroup::IpPermission


Lincoln Stein <>.

Copyright (c) 2011 Ontario Institute for Cancer Research


syntax highlighting: