1VM::EC2::SecurityGroup(U3s)er Contributed Perl DocumentatViMo:n:EC2::SecurityGroup(3)
2
6 VM::EC2::SecurityGroup - Object describing an Amazon EC2 security group
7
9 use VM::EC2;
10 $ec2 = VM::EC2->new(...);
12 @sg = $ec2->describe_security_groups;
13 for my $sg (@sg) {
14 $name = $sg->groupName;
15 $id = $sg->groupId;
16 $desc = $sg->groupDescription;
17 $tags = $sg->tags;
18 @inbound_permissions = $sg->ipPermissions;
19 @outbound_permissions = $sg->ipPermissionsEgress;
20 for $i (@inbound_permissions) {
21 $protocol = $i->ipProtocol;
22 $fromPort = $i->fromPort;
23 $toPort = $i->toPort;
24 @ranges = $i->ipRanges;
25 }
26 }
27 $sg = $sg[0];
29 # Add a new security rule
31 $sg->authorize_incoming(-protocol => 'tcp',
32 -port => 80,
33 -source_ip => ['192.168.2.0/24','192.168.2.1/24'});
34 # write it to AWS.
36 $sg->update();
37
39 This object is used to describe an Amazon EC2 security group. It is
40 returned by VM::EC2->describe_security_groups(). You may also obtain
41 this object by calling an Instance object's groups() method, and then
42 invoking one of the group's permissions() method. See VM::EC2::Group.
43
45 The following object methods are supported:
46 ownerId -- Owner of this security group
48 groupId -- ID of this security group
49 groupName -- Name of this security group
50 groupDescription -- Description of this group
51 vpcId -- Virtual Private Cloud ID, if applicable
52 ipPermissions -- A list of rules that govern incoming connections
53 to instances running under this security group.
54 Each rule is a
55 L<VM::EC2::SecurityGroup::IpPermission> object.
56 ipPermissionsEgress -- A list of rules that govern outgoing connections
57 from instances running under this security group.
58 Each rule is a
59 L<VM::EC2::SecurityGroup::IpPermission object>.
60 This field is only valid for VPC groups.
61 tags -- Hashref containing tags associated with this group.
62 See L<VM::EC2::Generic>.
63 For convenience, the following aliases are provided for commonly used
65 methods:
66 inbound_permissions -- same as ipPermissions()
68 outbound_permissions -- same as ipPermissionsEgress()
69 name -- same as groupName()
70 See VM::EC2::SecurityGroup::IpPermission for details on accessing port
72 numbers, IP ranges and other fields associated with incoming and
73 outgoing firewall rules.
74
76 To add or revoke firewall rules, call the authorize_incoming,
77 authorize_outgoing, revoke_incoming or revoke_outgoing() methods one or
78 more times. Each of these methods either adds or removes a single
79 firewall rule. After adding or revoking the desired rules, call
80 update() to write the modified group back to Amazon. The object will
81 change to reflect the new permissions.
82 $permission = $group->authorize_incoming(%args)
84 Add a rule for incoming firewall traffic. Arguments are as follows:
85 -protocol The protocol, either a string (tcp,udp,icmp) or
87 the corresponding protocol number (6, 17, 1).
88 Use -1 to indicate all protocols. (required)
89 -port, -ports The port or port range. When referring to a single
91 port, you may use either the port number or the
92 service name (e.g. "ssh"). For this to work the
93 service name must be located in /etc/services.
94 When specifying a port range, use "start..end" as
95 in "8000..9000". Note that this is a string that
96 contains two dots, and not two numbers separated
97 by the perl range operator. For the icmp protocol,
98 this argument corresponds to the ICMP type number.
99 (required).
100 -group, -groups Security groups to authorize. Instances that belong
102 to the named security groups will be allowed
103 access. You may specify either a single group or
104 a list of groups as an arrayref. The following
105 syntaxes are recognized:
106 "sg-12345" authorize group with this groupId
108 "12345/my group" authorize group named "my group"
109 owned by user 12345
110 "my group" authorize group named "my group"
111 owned by yourself
112 -source, -source_ip Authorize incoming traffic from an IP address, IP
114 address range, or set of such ranges. IP
115 addresses use the CIDR notation of a.b.c.d/mask,
116 as described in
117 http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing.
118 Pass an arrayref to simultaneously authorize
119 multiple CIDR ranges.
120 The result of this call is a VM::EC2::SecurityGroup::IpPermission
122 object corresponding to the rule you defined. Note that the rule is not
123 written to Amazon until you call update().
124 Here are some examples:
126 $sg->authorize_incoming(-protocol => 'tcp',
128 -port => 80,
129 -source_ip => ['192.168.2.0/24','192.168.2.1/24'});
130 # TCP on ports 22 and 23 from anyone
132 $sg->authorize_incoming(-protocol => 'tcp',
133 -port => '22..23',
134 -source_ip => '0.0.0.0/0');
135 # ICMP on echo (ping) port from anyone
137 $sg->authorize_incoming(-protocol => 'icmp',
138 -port => -1,
139 -source_ip => '0.0.0.0/0');
140 # TCP to port 25 (mail) from instances belonging to
142 # the "Mail relay" group belonging to user 12345678.
143 $sg->authorize_incoming(-protocol => 'tcp',
144 -port => 25,
145 -group => '12345678/Mail relay');
146 $permission = $group->authorize_outgoing(%args)
148 This is identical to authorize_incoming() except that the rule applies
149 to outbound traffic. Only VPC security groups can define outgoing
150 firewall rules.
151 $permission = $group->revoke_incoming($rule)
153 $permission = $group->revoke_incoming(%args)
154 This method revokes an incoming firewall rule. You can call it with a
155 single argument consisting of a VM::EC2::SecurityGroup::IpPermission
156 object in order to revoke that rule. Alternatively, when called with
157 the named arguments listed for authorize_incoming(), it will attempt to
158 match an existing rule to the provided arguments and queue it for
159 deletion.
160 Here is an example of revoking all rules that allow ssh (port 22)
162 access:
163 @ssh_rules = grep {$_->fromPort == 22} $group->ipPermissions;
165 $group->revoke_incoming($_) foreach @ssh_rules;
166 $group->update();
167 $boolean = $group->update()
169 This method will write all queued rule authorizations and revocations
170 to Amazon, and return a true value if successful. The method will
171 return false if any of the rule updates failed. You can examine the
172 VM::EC2 object's error_str() method to determine what went wrong, and
173 check the group object's ipPermissions() method to see what firewall
174 rules are currently defined.
175 $boolean = $group->write()
177 An alias for update()
178 $group->refresh()
180 This method refreshes the group information from Amazon. It is called
181 automatically by update().
182
184 When used in a string context, this object will interpolate the
185 groupId.
186
188 VM::EC2 VM::EC2::Generic VM::EC2::Instance VM::EC2::Group
189 VM::EC2::SecurityGroup::IpPermission
190
192 Lincoln Stein <lincoln.stein@gmail.com>.
193 Copyright (c) 2011 Ontario Institute for Cancer Research
195 This package and its accompanying libraries is free software; you can
197 redistribute it and/or modify it under the terms of the GPL (either
198 version 1, or at your option, any later version) or the Artistic
199 License 2.0. Refer to LICENSE for the full license text. In addition,
200 please see DISCLAIMER.txt for disclaimers of warranty.
201perl v5.34.0 2022-01-21 VM::EC2::SecurityGroup(3)