1VM::EC2::SecurityGroup(U3s)er Contributed Perl DocumentatViMo:n:EC2::SecurityGroup(3)
2
3
4

NAME

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

SYNOPSIS

9         use VM::EC2;
10
11         $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
28        $sg = $sg[0];
29
30        # 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
35        # write it to AWS.
36        $sg->update();
37

DESCRIPTION

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

METHODS

45       The following object methods are supported:
46
47        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
64       For convenience, the following aliases are provided for commonly used
65       methods:
66
67        inbound_permissions  -- same as ipPermissions()
68        outbound_permissions -- same as ipPermissionsEgress()
69        name                 -- same as groupName()
70
71       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

MODIFYING FIREWALL RULES

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
83   $permission = $group->authorize_incoming(%args)
84       Add a rule for incoming firewall traffic. Arguments are as follows:
85
86        -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
90        -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
101        -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
107                           "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
113        -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
121       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
125       Here are some examples:
126
127        $sg->authorize_incoming(-protocol  => 'tcp',
128                                -port      => 80,
129                                -source_ip => ['192.168.2.0/24','192.168.2.1/24'});
130
131        # 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
136        # 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
141        # 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
147   $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
152   $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
161       Here is an example of revoking all rules that allow ssh (port 22)
162       access:
163
164        @ssh_rules = grep {$_->fromPort == 22} $group->ipPermissions;
165        $group->revoke_incoming($_) foreach @ssh_rules;
166        $group->update();
167
168   $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
176   $boolean = $group->write()
177       An alias for update()
178
179   $group->refresh()
180       This method refreshes the group information from Amazon. It is called
181       automatically by update().
182

STRING OVERLOADING

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

SEE ALSO

188       VM::EC2 VM::EC2::Generic VM::EC2::Instance VM::EC2::Group
189       VM::EC2::SecurityGroup::IpPermission
190

AUTHOR

192       Lincoln Stein <lincoln.stein@gmail.com>.
193
194       Copyright (c) 2011 Ontario Institute for Cancer Research
195
196       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.
201
202
203
204perl v5.34.0                      2022-01-21         VM::EC2::SecurityGroup(3)
Impressum