documentation/manual/en/module_specs/Zend_Service_Amazon_Ec2-Securitygroups.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.amazon.ec2.securitygroups">
   4     <title>Zend_Service_Amazon_Ec2: Security Groups</title>
   5
   6     <para>
   7          A security group is a named collection of access rules. These access
   8          rules specify which ingress (i.e., incoming) network traffic should
   9          be delivered to your instance. All other ingress traffic will be
  10          discarded.
  11     </para>
  12
  13     <para>
  14         You can modify rules for a group at any time. The new rules are
  15         automatically enforced for all running instances and instances
  16         launched in the future.
  17     </para>
  18
  19     <note>
  20         <title>Maximum Security Groups</title>
  21
  22         <para>You can create up to 100 security groups.</para>
  23     </note>
  24
  25     <sect2 id="zend.service.amazon.ec2.securitygroups.maintenance">
  26         <title>Security Group Maintenance</title>
  27
  28         <example id="zend.service.amazon.ec2.securitygroups.maintenance.create">
  29             <title>Create a new Security Group</title>
  30
  31             <para>
  32                 <code>create</code> a new security group. Every instance is
  33                 launched in a security group. If no security group is specified
  34                 during launch, the instances are launched in the default security
  35                 group. Instances within the same security group have unrestricted
  36                 network access to each other. Instances will reject network access
  37                 attempts from other instances in a different security group.
  38             </para>
  39
  40             <para>
  41                 <code>create</code> returns boolean <constant>TRUE</constant> or
  42                 <constant>FALSE</constant>
  43             </para>
  44
  45             <programlisting language="php"><![CDATA[
  46 $ec2_sg = new Zend_Service_Amazon_Ec2_Securitygroups('aws_key',
  47                                                      'aws_secret_key');
  48 $return = $ec2_sg->create('mygroup', 'my group description');
  49 ]]></programlisting>
  50         </example>
  51
  52         <example id="zend.service.amazon.ec2.securitygroups.maintenance.describe">
  53             <title>Describe a Security Group</title>
  54
  55             <para>
  56                 <code>describe</code> returns information about security groups that
  57                 you own.
  58             </para>
  59
  60             <para>
  61                 If you specify security group names, information about those security
  62                 groups is returned. Otherwise, information for all security groups is
  63                 returned. If you specify a group that does not exist, a fault is returned.
  64             </para>
  65
  66             <para>
  67                 <code>describe</code> will return an array containing information
  68                 about security groups which includes the ownerId, groupName,
  69                 groupDescription and an array containing all the rules for that security
  70                 group.
  71             </para>
  72
  73             <programlisting language="php"><![CDATA[
  74 $ec2_sg = new Zend_Service_Amazon_Ec2_Securitygroups('aws_key',
  75                                                      'aws_secret_key');
  76 $return = $ec2_sg->describe('mygroup');
  77 ]]></programlisting>
  78         </example>
  79
  80         <example id="zend.service.amazon.ec2.securitygroups.maintenance.delete">
  81             <title>Delete a Security Group</title>
  82
  83             <para>
  84                 <code>delete</code> will remove the security group. If you attempt to
  85                 delete a security group that contains instances, a fault is returned.
  86                 If you attempt to delete a security group that is referenced by another
  87                 security group, a fault is returned. For example, if security group B
  88                 has a rule that allows access from security group A, security group A
  89                 cannot be deleted until the allow rule is removed.
  90             </para>
  91
  92             <para>
  93                 <code>delete</code> returns boolean <constant>TRUE</constant> or
  94                 <constant>FALSE</constant>.
  95             </para>
  96
  97             <programlisting language="php"><![CDATA[
  98 $ec2_sg = new Zend_Service_Amazon_Ec2_Securitygroups('aws_key',
  99                                                      'aws_secret_key');
 100 $return = $ec2_sg->delete('mygroup');
 101 ]]></programlisting>
 102         </example>
 103     </sect2>
 104
 105     <sect2 id="zend.service.amazon.ec2.securitygroups.authorize">
 106         <title>Authorizing Access</title>
 107
 108         <example id="zend.service.amazon.ec2.securitygroups.authorize.ip">
 109             <title>Authorizing by IP</title>
 110
 111             <para>
 112                 <code>authorizeIp</code> Adds permissions to a security group based on
 113                 an IP address, protocol type and port range.
 114             </para>
 115
 116             <para>
 117                 Permissions are specified by the IP protocol (TCP, UDP or ICMP), the
 118                 source of the request (by IP range or an Amazon EC2 user-group pair),
 119                 the source and destination port ranges (for <acronym>TCP</acronym> and UDP), and the
 120                 ICMP codes and types (for ICMP). When authorizing ICMP, -1 can be used
 121                 as a wildcard in the type and code fields.
 122             </para>
 123
 124             <para>
 125                 Permission changes are propagated to instances within the security group
 126                 as quickly as possible. However, depending on the number of instances, a
 127                 small delay might occur.
 128             </para>
 129
 130             <para>
 131                 <code>authorizeIp</code> returns boolean <constant>TRUE</constant> or
 132                 <constant>FALSE</constant>
 133             </para>
 134
 135             <programlisting language="php"><![CDATA[
 136 $ec2_sg = new Zend_Service_Amazon_Ec2_Securitygroups('aws_key',
 137                                                      'aws_secret_key');
 138 $return = $ec2_sg->authorizeIp('mygroup',
 139                                 'protocol',
 140                                 'fromPort',
 141                                 'toPort',
 142                                 'ipRange');
 143 ]]></programlisting>
 144         </example>
 145
 146         <example id="zend.service.amazon.ec2.securitygroups.authorize.group">
 147             <title>Authorize By Group</title>
 148
 149             <para>
 150                 <code>authorizeGroup</code> Adds permissions to a security group.
 151             </para>
 152
 153             <para>
 154                 Permission changes are propagated to instances within the security group
 155                 as quickly as possible. However, depending on the number of instances, a
 156                 small delay might occur.
 157             </para>
 158
 159             <para>
 160                 <code>authorizeGroup</code> returns boolean <constant>TRUE</constant> or
 161                 <constant>FALSE</constant>.
 162             </para>
 163
 164             <programlisting language="php"><![CDATA[
 165 $ec2_sg = new Zend_Service_Amazon_Ec2_Securitygroups('aws_key',
 166                                                      'aws_secret_key');
 167 $return = $ec2_sg->authorizeGroup('mygroup', 'securityGroupName', 'ownerId');
 168 ]]></programlisting>
 169         </example>
 170     </sect2>
 171
 172     <sect2 id="zend.service.amazon.ec2.securitygroups.revoke">
 173         <title>Revoking Access</title>
 174
 175         <example id="zend.service.amazon.ec2.securitygroups.revoke.ip">
 176             <title>Revoke by IP</title>
 177
 178             <para>
 179                 <code>revokeIp</code> Revokes permissions to a security group based on
 180                 an IP address, protocol type and port range. The permissions used to revoke
 181                 must be specified using the same values used to grant the permissions.
 182             </para>
 183
 184             <para>
 185                 Permissions are specified by the IP protocol (TCP, UDP or ICMP), the
 186                 source of the request (by IP range or an Amazon EC2 user-group pair),
 187                 the source and destination port ranges (for <acronym>TCP</acronym> and UDP), and the
 188                 ICMP codes and types (for ICMP). When authorizing ICMP, -1 can be used
 189                 as a wildcard in the type and code fields.
 190             </para>
 191
 192             <para>
 193                 Permission changes are propagated to instances within the security group
 194                 as quickly as possible. However, depending on the number of instances, a
 195                 small delay might occur.
 196             </para>
 197
 198             <para>
 199                 <code>revokeIp</code> returns boolean <constant>TRUE</constant> or
 200                 <constant>FALSE</constant>
 201             </para>
 202
 203             <programlisting language="php"><![CDATA[
 204 $ec2_sg = new Zend_Service_Amazon_Ec2_Securitygroups('aws_key',
 205                                                      'aws_secret_key');
 206 $return = $ec2_sg->revokeIp('mygroup',
 207                              'protocol',
 208                              'fromPort',
 209                              'toPort',
 210                              'ipRange');
 211 ]]></programlisting>
 212         </example>
 213
 214         <example id="zend.service.amazon.ec2.securitygroups.revoke.group">
 215             <title>Revoke By Group</title>
 216
 217             <para>
 218                 <code>revokeGroup</code> Adds permissions to a security group. The permissions
 219                 to revoke must be specified using the same values used to grant the
 220                 permissions.
 221             </para>
 222
 223             <para>
 224                 Permission changes are propagated to instances within the security group
 225                 as quickly as possible. However, depending on the number of instances, a
 226                 small delay might occur.
 227             </para>
 228
 229             <para>
 230                 <code>revokeGroup</code> returns boolean <constant>TRUE</constant> or
 231                 <constant>FALSE</constant>.
 232             </para>
 233
 234             <programlisting language="php"><![CDATA[
 235 $ec2_sg = new Zend_Service_Amazon_Ec2_Securitygroups('aws_key',
 236                                                      'aws_secret_key');
 237 $return = $ec2_sg->revokeGroup('mygroup', 'securityGroupName', 'ownerId');
 238 ]]></programlisting>
 239         </example>
 240     </sect2>
 241 </sect1>