Class: RightAws::Ec2

Inherits:
RightAwsBase show all
Includes:
RightAwsBaseInterface
Defined in:
lib/ec2/right_ec2.rb

Overview

RightAWS::EC2 – RightScale Amazon EC2 interface

The RightAws::EC2 class provides a complete interface to Amazon’s Elastic Compute Cloud service, as well as the associated EBS (Elastic Block Store). For explanations of the semantics of each call, please refer to Amazon’s documentation at developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=87

Examples:

Create an EC2 interface handle:

@ec2   = RightAws::Ec2.new(aws_access_key_id,
                            aws_secret_access_key)

Create a new SSH key pair:

@key   = 'right_ec2_awesome_test_key'
new_key = @ec2.create_key_pair(@key)
keys = @ec2.describe_key_pairs

Create a security group:

@group = 'right_ec2_awesome_test_security_group'
@ec2.create_security_group(@group,'My awesome test group')
group = @ec2.describe_security_groups([@group])[0]

Configure a security group:

@ec2.authorize_security_group_named_ingress(@group, , 'default')
@ec2.authorize_security_group_IP_ingress(@group, 80,80,'udp','192.168.1.0/8')

Describe the available images:

images = @ec2.describe_images

Launch an instance:

ec2.run_instances('ami-9a9e7bf3', 1, 1, ['default'], @key, 'SomeImportantUserData', 'public')

Describe running instances:

@ec2.describe_instances

Error handling: all operations raise an RightAws::AwsError in case of problems. Note that transient errors are automatically retried.

Defined Under Namespace

Classes: QEc2AllocateAddressParser, QEc2AttachAndDetachVolumeParser, QEc2ConfirmProductInstanceParser, QEc2CreateKeyPairParser, QEc2CreateSnapshotParser, QEc2CreateVolumeParser, QEc2DescribeAddressesParser, QEc2DescribeAvailabilityZonesParser, QEc2DescribeImageAttributeParser, QEc2DescribeImagesParser, QEc2DescribeInstancesParser, QEc2DescribeKeyPairParser, QEc2DescribeSecurityGroupsParser, QEc2DescribeSnapshotsParser, QEc2DescribeVolumesParser, QEc2DummyParser, QEc2GetConsoleOutputParser, QEc2IpPermissionType, QEc2RegisterImageParser, QEc2SecurityGroupItemType, QEc2TerminateInstancesParser, QEc2UserIdGroupPairType, RightBoolResponseParser

Constant Summary collapse

API_VERSION =

Amazon EC2 API version being used

"2008-05-05"
DEFAULT_HOST = 
"ec2.amazonaws.com"
DEFAULT_PATH = 
'/'
DEFAULT_PROTOCOL = 
'https'
DEFAULT_PORT = 
443
DEFAULT_ADDRESSING_TYPE =

Default addressing type (public=NAT, direct=no-NAT) used when launching instances.

'public'
DNS_ADDRESSING_SET = 
['public','direct']
DEFAULT_INSTANCE_TYPE =

Amazon EC2 Instance Types : www.amazon.com/b?ie=UTF8&node=370375011 Default EC2 instance type (platform)

'm1.small'
INSTANCE_TYPES = 
['m1.small','c1.medium','m1.large','m1.xlarge','c1.xlarge']
@@bench = 
AwsBenchmarkingBlock.new
@@api =

Current API version (sometimes we have to check it outside the GEM).

ENV['EC2_API_VERSION'] || API_VERSION

Constants included from RightAwsBaseInterface

RightAwsBaseInterface::DEFAULT_SIGNATURE_VERSION

Constants inherited from RightAwsBase

RightAwsBase::AMAZON_PROBLEMS

Instance Attribute Summary

Attributes included from RightAwsBaseInterface

#aws_access_key_id, #cache, #connection, #last_errors, #last_request, #last_request_id, #last_response, #logger, #params, #signature_version

Class Method Summary collapse

Instance Method Summary collapse

Methods included from RightAwsBaseInterface

#cache_hits?, caching, caching=, #caching?, #init, #multi_thread, #on_exception, #request_info_impl, #update_cache

Methods inherited from RightAwsBase

amazon_problems, amazon_problems=

Constructor Details

#initialize(aws_access_key_id = nil, aws_secret_access_key = nil, params = {}) ⇒ Ec2

Create a new handle to an EC2 account. All handles share the same per process or per thread HTTP connection to Amazon EC2. Each handle is for a specific account. The params have the following options:

  • :server: EC2 service host, default: DEFAULT_HOST

  • :port: EC2 service port, default: DEFAULT_PORT

  • :protocol: ‘http’ or ‘https’, default: DEFAULT_PROTOCOL

  • :multi_thread: true=HTTP connection per thread, false=per process

  • :logger: for log messages, default: RAILS_DEFAULT_LOGGER else STDOUT

  • :signature_version: The signature version : ‘0’ or ‘1’(default)



110
111
112
113
114
115
116
117
118
119
 
# File 'lib/ec2/right_ec2.rb', line 110

def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
  init({ :name             => 'EC2', 
         :default_host     => ENV['EC2_URL'] ? URI.parse(ENV['EC2_URL']).host   : DEFAULT_HOST, 
         :default_port     => ENV['EC2_URL'] ? URI.parse(ENV['EC2_URL']).port   : DEFAULT_PORT,
         :default_service  => ENV['EC2_URL'] ? URI.parse(ENV['EC2_URL']).path   : DEFAULT_PATH,             
         :default_protocol => ENV['EC2_URL'] ? URI.parse(ENV['EC2_URL']).scheme : DEFAULT_PROTOCOL }, 
       aws_access_key_id    || ENV['AWS_ACCESS_KEY_ID'] , 
       aws_secret_access_key|| ENV['AWS_SECRET_ACCESS_KEY'],
       params)
end

Class Method Details

.api ⇒ Object 



96
97
98
 
# File 'lib/ec2/right_ec2.rb', line 96

def self.api 
  @@api
end

.bench_ec2 ⇒ Object 



90
91
92
 
# File 'lib/ec2/right_ec2.rb', line 90

def self.bench_ec2
  @@bench.service
end

.bench_xml ⇒ Object 



87
88
89
 
# File 'lib/ec2/right_ec2.rb', line 87

def self.bench_xml
  @@bench.xml
end

Instance Method Details

#allocate_address ⇒ Object

Acquire a new elastic IP address for use with your account. Returns allocated IP address or an exception.

ec2.allocate_address #=> '75.101.154.140'



779
780
781
782
783
784
 
# File 'lib/ec2/right_ec2.rb', line 779

def allocate_address
  link = generate_request("AllocateAddress")
  request_info(link, QEc2AllocateAddressParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#associate_address(instance_id, public_ip) ⇒ Object

Associate an elastic IP address with an instance. Returns true or an exception.

ec2.associate_address('i-d630cbbf', '75.101.154.140') #=> true



791
792
793
794
795
796
797
798
 
# File 'lib/ec2/right_ec2.rb', line 791

def associate_address(instance_id, public_ip)
  link = generate_request("AssociateAddress", 
                          "InstanceId" => instance_id.to_s,
                          "PublicIp"   => public_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#attach_volume(volume_id, instance_id, device) ⇒ Object

Attach the specified EBS volume to a specified instance, exposing the volume using the specified device name.

ec2.attach_volume('vol-898a6fe0', 'i-7c905415', '/dev/sdh') #=>
  { :aws_instance_id => "i-7c905415",
    :aws_device      => "/dev/sdh",
    :aws_status      => "attaching",
    :aws_attached_at => "2008-03-28T14:14:39.000Z",
    :aws_id          => "vol-898a6fe0" }



939
940
941
942
943
944
945
946
947
 
# File 'lib/ec2/right_ec2.rb', line 939

def attach_volume(volume_id, instance_id, device)
  link = generate_request("AttachVolume", 
                          "VolumeId"   => volume_id.to_s,
                          "InstanceId" => instance_id.to_s,
                          "Device"     => device.to_s)
  request_info(link, QEc2AttachAndDetachVolumeParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#authorize_security_group_IP_ingress(name, from_port, to_port, protocol = 'tcp', cidr_ip = '0.0.0.0/0') ⇒ Object

Add permission to a security group. Returns true or an exception. protocol is one of :‘tcp’|‘udp’|‘icmp’.

ec2.authorize_security_group_IP_ingress('my_awesome_group', 80, 82, 'udp', '192.168.1.0/8') #=> true
ec2.authorize_security_group_IP_ingress('my_awesome_group', -1, -1, 'icmp') #=> true



696
697
698
699
700
701
702
703
704
705
706
 
# File 'lib/ec2/right_ec2.rb', line 696

def authorize_security_group_IP_ingress(name, from_port, to_port, protocol='tcp', cidr_ip='0.0.0.0/0')
  link = generate_request("AuthorizeSecurityGroupIngress", 
                          'GroupName'  => name.to_s, 
                          'IpProtocol' => protocol.to_s, 
                          'FromPort'   => from_port.to_s, 
                          'ToPort'     => to_port.to_s, 
                          'CidrIp'     => cidr_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#authorize_security_group_named_ingress(name, owner, group) ⇒ Object

Authorize named ingress for security group. Allows instances that are member of someone else’s security group to open connections to instances in my group.

ec2.authorize_security_group_named_ingress('my_awesome_group', '7011-0219-8268', 'their_group_name') #=> true



667
668
669
670
671
672
673
674
675
 
# File 'lib/ec2/right_ec2.rb', line 667

def authorize_security_group_named_ingress(name, owner, group)
  link = generate_request("AuthorizeSecurityGroupIngress", 
                          'GroupName'                  => name.to_s, 
                          'SourceSecurityGroupName'    => group.to_s, 
                          'SourceSecurityGroupOwnerId' => owner.to_s.gsub(/-/,''))
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#confirm_product_instance(instance, product_code) ⇒ Object

Return the product code attached to instance or nil otherwise.

ec2.confirm_product_instance('ami-e444444d','12345678') #=> nil
ec2.confirm_product_instance('ami-e444444d','00001111') #=> "000000000888"



413
414
415
416
417
 
# File 'lib/ec2/right_ec2.rb', line 413

def confirm_product_instance(instance, product_code)
  link = generate_request("ConfirmProductInstance", { 'ProductCode' => product_code,
                                                      'InstanceId'  => instance })
  request_info(link, QEc2ConfirmProductInstanceParser.new(:logger => @logger))
end

#create_key_pair(name) ⇒ Object

Create new SSH key. Returns a hash of the key’s data or an exception.

ec2.create_key_pair('my_awesome_key') #=>
  {:aws_key_name    => "my_awesome_key",
   :aws_fingerprint => "01:02:03:f4:25:e6:97:e8:9b:02:1a:26:32:4e:58:6b:7a:8c:9f:03",
   :aws_material    => "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAK...Q8MDrCbuQ=\n-----END RSA PRIVATE KEY-----"}



750
751
752
753
754
755
756
 
# File 'lib/ec2/right_ec2.rb', line 750

def create_key_pair(name)
  link = generate_request("CreateKeyPair", 
                          'KeyName' => name.to_s)
  request_info(link, QEc2CreateKeyPairParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#create_security_group(name, description) ⇒ Object

Create new Security Group. Returns true or an exception.

ec2.create_security_group('default-1',"Default allowing SSH, HTTP, and HTTPS ingress") #=> true



639
640
641
642
643
644
645
646
647
648
 
# File 'lib/ec2/right_ec2.rb', line 639

def create_security_group(name, description)
  # EC2 doesn't like an empty description...
  description = " " if description.blank?
  link = generate_request("CreateSecurityGroup", 
                          'GroupName'        => name.to_s, 
                          'GroupDescription' => description.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#create_snapshot(volume_id) ⇒ Object

Create a snapshot of specified volume.

ec2.create_snapshot('vol-898a6fe0') #=> 
    {:aws_volume_id  => "vol-fd9f7a94",
     :aws_started_at => Tue Jun 24 18:40:40 UTC 2008,
     :aws_progress   => "",
     :aws_status     => "pending",
     :aws_id         => "snap-d56783bc"}



1006
1007
1008
1009
1010
1011
1012
 
# File 'lib/ec2/right_ec2.rb', line 1006

def create_snapshot(volume_id)
  link = generate_request("CreateSnapshot", 
                          "VolumeId" => volume_id.to_s)
  request_info(link, QEc2CreateSnapshotParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#create_volume(snapshot_id, size, zone) ⇒ Object

Create new EBS volume based on previously created snapshot. Size in Gigabytes.

ec2.create_volume('snap-000000', 10, zone) #=> 
    {:snapshot_id    => "snap-e21df98b",
     :aws_status     => "creating",
     :aws_id         => "vol-fc9f7a95",
     :zone           => "merlot",
     :aws_created_at => Tue Jun 24 18:13:32 UTC 2008,
     :aws_size       => 94}



906
907
908
909
910
911
912
913
914
 
# File 'lib/ec2/right_ec2.rb', line 906

def create_volume(snapshot_id, size, zone)
  link = generate_request("CreateVolume", 
                          "SnapshotId"        => snapshot_id.to_s,
                          "Size"              => size.to_s,
                          "AvailabilityZone"  => zone.to_s )
  request_info(link, QEc2CreateVolumeParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#delete_key_pair(name) ⇒ Object

Delete a key pair. Returns true or an exception.

ec2.delete_key_pair('my_awesome_key') #=> true



762
763
764
765
766
767
768
 
# File 'lib/ec2/right_ec2.rb', line 762

def delete_key_pair(name)
  link = generate_request("DeleteKeyPair", 
                          'KeyName' => name.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#delete_security_group(name) ⇒ Object

Remove Security Group. Returns true or an exception.

ec2.delete_security_group('default-1') #=> true



654
655
656
657
658
659
660
 
# File 'lib/ec2/right_ec2.rb', line 654

def delete_security_group(name)
  link = generate_request("DeleteSecurityGroup", 
                          'GroupName' => name.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#delete_snapshot(snapshot_id) ⇒ Object

Delete the specified snapshot.

ec2.delete_snapshot('snap-55a5403c') #=> true



1018
1019
1020
1021
1022
1023
1024
 
# File 'lib/ec2/right_ec2.rb', line 1018

def delete_snapshot(snapshot_id)
  link = generate_request("DeleteSnapshot", 
                          "SnapshotId" => snapshot_id.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#delete_volume(volume_id) ⇒ Object

Delete the specified EBS volume. This does not deletes any snapshots created from this volume.

ec2.delete_volume('vol-b48a6fdd') #=> true



921
922
923
924
925
926
927
 
# File 'lib/ec2/right_ec2.rb', line 921

def delete_volume(volume_id)
  link = generate_request("DeleteVolume", 
                          "VolumeId" => volume_id.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#deregister_image(image_id) ⇒ Object

Deregister image at Amazon. Returns true or an exception.

ec2.deregister_image('ami-e444444d') #=> true



254
255
256
257
258
259
260
 
# File 'lib/ec2/right_ec2.rb', line 254

def deregister_image(image_id)
  link = generate_request("DeregisterImage", 
                          'ImageId' => image_id.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#describe_addresses(list = []) ⇒ Object

List elastic IP addresses assigned to your account. Returns an array of 2 keys (:instance_id and :public_ip) hashes:

ec2.describe_addresses  #=> [{:instance_id=>"i-d630cbbf", :public_ip=>"75.101.154.140"},
                             {:instance_id=>nil, :public_ip=>"75.101.154.141"}]

ec2.describe_addresses('75.101.154.140') #=> [{:instance_id=>"i-d630cbbf", :public_ip=>"75.101.154.140"}]



808
809
810
811
812
813
814
 
# File 'lib/ec2/right_ec2.rb', line 808

def describe_addresses(list=[])
  link = generate_request("DescribeAddresses", 
                          hash_params('PublicIp',list.to_a))
  request_cache_or_info :describe_addresses, link,  QEc2DescribeAddressesParser, list.blank?
rescue Exception
  on_exception
end

#describe_availability_zones(list = []) ⇒ Object

Describes availability zones that are currently available to the account and their states. Returns an array of 2 keys (:zone_name and :zone_state) hashes:

ec2.describe_availability_zones  #=> [{:zone_state=>"available", :zone_name=>"us-east-1a"}, 
                                      {:zone_state=>"available", :zone_name=>"us-east-1b"}, 
                                      {:zone_state=>"available", :zone_name=>"us-east-1c"}]

ec2.describe_availability_zones('us-east-1c') #=> [{:zone_state=>"available", :zone_name=>"us-east-1c"}]



855
856
857
858
859
860
861
 
# File 'lib/ec2/right_ec2.rb', line 855

def describe_availability_zones(list=[])
  link = generate_request("DescribeAvailabilityZones", 
                          hash_params('ZoneName',list.to_a))
  request_cache_or_info :describe_availability_zones, link,  QEc2DescribeAvailabilityZonesParser, list.blank?
rescue Exception
  on_exception
end

#describe_image_attribute(image_id, attribute = 'launchPermission') ⇒ Object

Describe image attributes. Currently ‘launchPermission’, ‘productCodes’, ‘kernel’, ‘ramdisk’ and ‘blockDeviceMapping’ are supported.

ec2.describe_image_attribute('ami-e444444d') #=> {:groups=>["all"], :users=>["000000000777"]}



267
268
269
270
271
272
273
274
 
# File 'lib/ec2/right_ec2.rb', line 267

def describe_image_attribute(image_id, attribute='launchPermission')
  link = generate_request("DescribeImageAttribute", 
                          'ImageId'   => image_id,
                          'Attribute' => attribute)
  request_info(link, QEc2DescribeImageAttributeParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#describe_images(list = [], image_type = nil) ⇒ Object

Retrieve a list of images. Returns array of hashes describing the images or an exception: image_type = ‘machine’ || ‘kernel’ || ‘ramdisk’ 

ec2.describe_images #=>
  [{:aws_owner => "522821470517",
    :aws_id => "ami-e4b6538d",
    :aws_state => "available",
    :aws_location => "marcins_cool_public_images/ubuntu-6.10.manifest.xml",
    :aws_is_public => true,
    :aws_architecture => "i386",
    :aws_image_type => "machine"},
   {...},
   {...} ]

If list param is set, then retrieve information about the listed images only:

ec2.describe_images(['ami-e4b6538d']) #=>
  [{:aws_owner => "522821470517",
    :aws_id => "ami-e4b6538d",
    :aws_state => "available",
    :aws_location => "marcins_cool_public_images/ubuntu-6.10.manifest.xml",
    :aws_is_public => true,
    :aws_architecture => "i386",
    :aws_image_type => "machine"}]



212
213
214
 
# File 'lib/ec2/right_ec2.rb', line 212

def describe_images(list=[], image_type=nil)
  ec2_describe_images(list, 'ImageId', image_type)
end

#describe_images_by_executable_by(list, image_type = nil) ⇒ Object

Example:

ec2.describe_images_by_executable_by('522821470517')
ec2.describe_images_by_executable_by('self')



232
233
234
 
# File 'lib/ec2/right_ec2.rb', line 232

def describe_images_by_executable_by(list, image_type=nil)
  ec2_describe_images(list, 'ExecutableBy', image_type)
end

#describe_images_by_owner(list, image_type = nil) ⇒ Object

Example:

ec2.describe_images_by_owner('522821470517')
ec2.describe_images_by_owner('self')



222
223
224
 
# File 'lib/ec2/right_ec2.rb', line 222

def describe_images_by_owner(list, image_type=nil)
  ec2_describe_images(list, 'Owner', image_type)
end

#describe_instances(list = []) ⇒ Object

Retrieve information about EC2 instances. If list is omitted then returns the list of all instances.

ec2.describe_instances #=> 
  [{:aws_image_id       => "ami-e444444d",
    :aws_reason         => "",
    :aws_state_code     => "16",
    :aws_owner          => "000000000888",
    :aws_instance_id    => "i-123f1234",
    :aws_reservation_id => "r-aabbccdd",
    :aws_state          => "running",
    :dns_name           => "domU-12-34-67-89-01-C9.usma2.compute.amazonaws.com",
    :ssh_key_name       => "staging",
    :aws_groups         => ["default"],
    :private_dns_name   => "domU-12-34-67-89-01-C9.usma2.compute.amazonaws.com",
    :aws_instance_type  => "m1.small",
    :aws_launch_time    => "2008-1-1T00:00:00.000Z"},
    :aws_availability_zone => "us-east-1b",
    :aws_kernel_id      => "aki-ba3adfd3",
    :aws_ramdisk_id     => "ari-badbad00",
     ..., {...}]



399
400
401
402
403
404
405
406
 
# File 'lib/ec2/right_ec2.rb', line 399

def describe_instances(list=[])
  link = generate_request("DescribeInstances", hash_params('InstanceId',list.to_a))
  request_cache_or_info(:describe_instances, link,  QEc2DescribeInstancesParser, list.blank?) do |parser|
    get_desc_instances(parser.result)
  end
rescue Exception
  on_exception
end

#describe_key_pairs(list = []) ⇒ Object

Retrieve a list of SSH keys. Returns an array of keys or an exception. Each key is represented as a two-element hash.

ec2.describe_key_pairs #=>
  [{:aws_fingerprint=> "01:02:03:f4:25:e6:97:e8:9b:02:1a:26:32:4e:58:6b:7a:8c:9f:03", :aws_key_name=>"key-1"},
   {:aws_fingerprint=> "1e:29:30:47:58:6d:7b:8c:9f:08:11:20:3c:44:52:69:74:80:97:08", :aws_key_name=>"key-2"},
    ..., {...} ]



736
737
738
739
740
741
 
# File 'lib/ec2/right_ec2.rb', line 736

def describe_key_pairs(list=[])
  link = generate_request("DescribeKeyPairs", hash_params('KeyName',list.to_a))
  request_cache_or_info :describe_key_pairs, link,  QEc2DescribeKeyPairParser, list.blank?
rescue Exception
  on_exception
end

#describe_security_groups(list = []) ⇒ Object

Retrieve Security Group information. If list is omitted the returns the whole list of groups.

ec2.describe_security_groups #=>
  [{:aws_group_name  => "default-1",
    :aws_owner       => "000000000888",
    :aws_description => "Default allowing SSH, HTTP, and HTTPS ingress",
    :aws_perms       =>
      [{:owner => "000000000888", :group => "default"},
       {:owner => "000000000888", :group => "default-1"},
       {:to_port => "-1",  :protocol => "icmp", :from_port => "-1",  :cidr_ips => "0.0.0.0/0"},
       {:to_port => "22",  :protocol => "tcp",  :from_port => "22",  :cidr_ips => "0.0.0.0/0"},
       {:to_port => "80",  :protocol => "tcp",  :from_port => "80",  :cidr_ips => "0.0.0.0/0"},
       {:to_port => "443", :protocol => "tcp",  :from_port => "443", :cidr_ips => "0.0.0.0/0"}]},
  ..., {...}]



596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
 
# File 'lib/ec2/right_ec2.rb', line 596

def describe_security_groups(list=[])
  link = generate_request("DescribeSecurityGroups", hash_params('GroupName',list.to_a))
  request_cache_or_info( :describe_security_groups, link,  QEc2DescribeSecurityGroupsParser, list.blank?) do |parser|
    result = []     
    parser.result.each do |item|
      perms = []
      item.ipPermissions.each do |perm|
        perm.groups.each do |ngroup|
          perms << {:group => ngroup.groupName,
                    :owner => ngroup.userId}
        end
        perm.ipRanges.each do |cidr_ip|
          perms << {:from_port => perm.fromPort, 
                    :to_port   => perm.toPort, 
                    :protocol  => perm.ipProtocol,
                    :cidr_ips  => cidr_ip}
        end
      end

         # delete duplication
      perms.each_index do |i|
        (0...i).each do |j|
          if perms[i] == perms[j] then perms[i] = nil; break; end
        end
      end
      perms.compact!

      result << {:aws_owner       => item.ownerId, 
                 :aws_group_name  => item.groupName, 
                 :aws_description => item.groupDescription,
                 :aws_perms       => perms}
    
    end
    result
  end
rescue Exception
  on_exception
end

#describe_snapshots(list = []) ⇒ Object

Describe all EBS snapshots.

ec2.describe_snapshots #=> 

[ { :aws_progress   => "100%",
    :aws_status     => "completed",
    :aws_id         => "snap-72a5401b",
    :aws_volume_id  => "vol-5582673c",
    :aws_started_at => "2008-02-23T02:50:48.000Z"},
  { :aws_progress   => "100%",
    :aws_status     => "completed",
    :aws_id         => "snap-75a5401c",
    :aws_volume_id  => "vol-5582673c",
    :aws_started_at => "2008-02-23T16:23:19.000Z" },...]



989
990
991
992
993
994
995
 
# File 'lib/ec2/right_ec2.rb', line 989

def describe_snapshots(list=[])
  link = generate_request("DescribeSnapshots", 
                          hash_params('SnapshotId',list.to_a))
  request_cache_or_info :describe_snapshots, link,  QEc2DescribeSnapshotsParser, list.blank?
rescue Exception
  on_exception
end

#describe_volumes(list = []) ⇒ Object

Describe all EBS volumes.

ec2.describe_volumes #=> 
    [{:aws_size              => 94,
      :aws_device            => "/dev/sdc",
      :aws_attachment_status => "attached",
      :zone                  => "merlot",
      :snapshot_id           => nil,
      :aws_attached_at       => Wed Jun 18 08:19:28 UTC 2008,
      :aws_status            => "in-use",
      :aws_id                => "vol-60957009",
      :aws_created_at        => Wed Jun 18 08:19:20s UTC 2008,
      :aws_instance_id       => "i-c014c0a9"},
     {:aws_size       => 1,
      :zone           => "merlot",
      :snapshot_id    => nil,
      :aws_status     => "available",
      :aws_id         => "vol-58957031",
      :aws_created_at => Wed Jun 18 08:19:21 UTC 2008,}, ... ]



887
888
889
890
891
892
893
 
# File 'lib/ec2/right_ec2.rb', line 887

def describe_volumes(list=[])
  link = generate_request("DescribeVolumes", 
                          hash_params('VolumeId',list.to_a))
  request_cache_or_info :describe_volumes, link,  QEc2DescribeVolumesParser, list.blank?
rescue Exception
  on_exception
end

#detach_volume(volume_id, instance_id = nil, device = nil, force = nil) ⇒ Object

Detach the specified EBS volume from the instance to which it is attached.

ec2.detach_volume('vol-898a6fe0') #=> 
  { :aws_instance_id => "i-7c905415",
    :aws_device      => "/dev/sdh",
    :aws_status      => "detaching",
    :aws_attached_at => "2008-03-28T14:38:34.000Z",
    :aws_id          => "vol-898a6fe0"}



958
959
960
961
962
963
964
965
966
967
968
 
# File 'lib/ec2/right_ec2.rb', line 958

def detach_volume(volume_id, instance_id=nil, device=nil, force=nil)
  hash = { "VolumeId" => volume_id.to_s }
  hash["InstanceId"] = instance_id.to_s unless instance_id.blank?
  hash["Device"]     = device.to_s      unless device.blank?
  hash["Force"]      = 'true'           if     force
  #
  link = generate_request("DetachVolume", hash)
  request_info(link, QEc2AttachAndDetachVolumeParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#disassociate_address(public_ip) ⇒ Object

Disassociate the specified elastic IP address from the instance to which it is assigned. Returns true or an exception.

ec2.disassociate_address('75.101.154.140') #=> true



821
822
823
824
825
826
827
 
# File 'lib/ec2/right_ec2.rb', line 821

def disassociate_address(public_ip)
  link = generate_request("DisassociateAddress", 
                          "PublicIp" => public_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#ec2_describe_images(list, list_by = 'ImageId', image_type = nil) ⇒ Object 

Images



178
179
180
181
182
183
184
185
 
# File 'lib/ec2/right_ec2.rb', line 178

def ec2_describe_images(list, list_by='ImageId', image_type=nil) #:nodoc:
  request_hash = hash_params(list_by, list.to_a)
  request_hash['ImageType'] = image_type if image_type
  link = generate_request("DescribeImages", request_hash)
  request_cache_or_info :describe_images, link,  QEc2DescribeImagesParser, (list.blank? && list_by == 'ImageId' && image_type.blank?)
rescue Exception
  on_exception
end

#generate_request(action, params = {}) ⇒ Object

:nodoc:



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/ec2/right_ec2.rb', line 122

def generate_request(action, params={}) #:nodoc:
  service_hash = {"Action"            => action,
                  "AWSAccessKeyId"    => @aws_access_key_id,
                  "Version"           => @@api,
                  "Timestamp"         => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
                  "SignatureVersion"  => signature_version }
  service_hash.update(params)
  # prepare string to sight
  string_to_sign = case signature_version
                   when '0' then service_hash["Action"] + service_hash["Timestamp"]
                   when '1' then service_hash.sort{|a,b| (a[0].to_s.downcase)<=>(b[0].to_s.downcase)}.to_s
                   end
  service_hash.update('Signature' =>  AwsUtils::sign(@aws_secret_access_key, string_to_sign))
  request_params = service_hash.to_a.collect{|key,val| key + "=" + CGI::escape(val) }.join("&")
  request        = Net::HTTP::Get.new("#{@params[:service]}?#{request_params}")
    # prepare output hash
  { :request  => request, 
    :server   => @params[:server],
    :port     => @params[:port],
    :protocol => @params[:protocol] }
end

#get_console_output(instance_id) ⇒ Object

Retreive EC2 instance OS logs. Returns a hash of data or an exception.

ec2.get_console_output('i-f222222d') =>
  {:aws_instance_id => 'i-f222222d',
   :aws_timestamp   => "2007-05-23T14:36:07.000-07:00",
   :timestamp       => Wed May 23 21:36:07 UTC 2007,          # Time instance
   :aws_output      => "Linux version 2.6.16-xenU ([email protected]) (gcc version 4.0.1 20050727 ..."



559
560
561
562
563
564
 
# File 'lib/ec2/right_ec2.rb', line 559

def get_console_output(instance_id)
  link = generate_request("GetConsoleOutput", { 'InstanceId.1' => instance_id })
  request_info(link, QEc2GetConsoleOutputParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#get_desc_instances(instances) ⇒ Object 

Instances



359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
 
# File 'lib/ec2/right_ec2.rb', line 359

def get_desc_instances(instances)  # :nodoc:
  result = []
  instances.each do |reservation|
    reservation[:instances_set].each do |instance|
      # Parse and remove timestamp from the reason string. The timestamp is of
      # the request, not when EC2 took action, thus confusing & useless...
      instance[:aws_reason]         = instance[:aws_reason].sub(/\(\d[^)]*GMT\) */, '')
      instance[:aws_owner]          = reservation[:aws_owner]
      instance[:aws_reservation_id] = reservation[:aws_reservation_id]
      instance[:aws_groups]         = reservation[:aws_groups]
      result << instance
    end
  end
  result
rescue Exception
  on_exception
end

#hash_params(prefix, list) ⇒ Object

:nodoc:



168
169
170
171
172
 
# File 'lib/ec2/right_ec2.rb', line 168

def hash_params(prefix, list) #:nodoc:
  groups = {}
  list.each_index{|i| groups.update("#{prefix}.#{i+1}"=>list[i])} if list
  return groups
end

#launch_instances(image_id, lparams = {}) ⇒ Object

Launch new EC2 instances. Returns a list of launched instances or an exception.

lparams keys (default values in parenthesis):

:min_count              fixnum, (1)
:max_count              fixnum, (1)
:group_ids              array or string ([] == 'default')
:instance_type          string (DEFAULT_INSTACE_TYPE)
:addressing_type        string (DEFAULT_ADDRESSING_TYPE 
:key_name               string
:kernel_id              string
:ramdisk_id             string 
:availability_zone      string
:block_device_mappings  string
:user_data              string

ec2.launch_instances('ami-e444444d', :group_ids => 'my_awesome_group', 
                                     :user_data => "Woohoo!!!", 
                                     :addressing_type => "public", 
                                     :key_name => "my_awesome_key", 
                                     :availability_zone => "us-east-1c") #=> 
 [{:aws_image_id       => "ami-e444444d", 
   :aws_reason         => "", 
   :aws_state_code     => "0", 
   :aws_owner          => "000000000888", 
   :aws_instance_id    => "i-123f1234", 
   :aws_reservation_id => "r-aabbccdd", 
   :aws_state          => "pending", 
   :dns_name           => "", 
   :ssh_key_name       => "my_awesome_key", 
   :aws_groups         => ["my_awesome_group"], 
   :private_dns_name   => "", 
   :aws_instance_type  => "m1.small",
   :aws_launch_time    => "2008-1-1T00:00:00.000Z",
   :aws_ramdisk_id     => "ari-8605e0ef"
   :aws_kernel_id      => "aki-9905e0f0",
   :ami_launch_index   => "0",
   :aws_availability_zone => "us-east-1c"
   }]



499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
 
# File 'lib/ec2/right_ec2.rb', line 499

def launch_instances(image_id, lparams={}) 
  @logger.info("Launching instance of image #{image_id} for #{@aws_access_key_id}, " + 
               "key: #{lparams[:key_name]}, groups: #{(lparams[:group_ids]).to_a.join(',')}")
  # careful: keyName and securityGroups may be nil
  params = hash_params('SecurityGroup', lparams[:group_ids].to_a)
  params.update( {'ImageId'        => image_id,
                  'MinCount'       => (lparams[:min_count] || 1).to_s, 
                  'MaxCount'       => (lparams[:max_count] || 1).to_s, 
                  'AddressingType' => lparams[:addressing_type] || DEFAULT_ADDRESSING_TYPE, 
                  'InstanceType'   => lparams[:instance_type]   || DEFAULT_INSTANCE_TYPE })
  # optional params
  params['KeyName']                    = lparams[:key_name]              unless lparams[:key_name].blank? 
  params['KernelId']                   = lparams[:kernel_id]             unless lparams[:kernel_id].blank? 
  params['RamdiskId']                  = lparams[:ramdisk_id]            unless lparams[:ramdisk_id].blank? 
  params['Placement.AvailabilityZone'] = lparams[:availability_zone]     unless lparams[:availability_zone].blank? 
  params['BlockDeviceMappings']        = lparams[:block_device_mappings] unless lparams[:block_device_mappings].blank?
  unless lparams[:user_data].blank? 
    lparams[:user_data].strip! 
      # Do not use CGI::escape(encode64(...)) as it is done in Amazons EC2 library.
      # Amazon 169.254.169.254 does not like escaped symbols!
      # And it doesn't like "\n" inside of encoded string! Grrr....
      # Otherwise, some of UserData symbols will be lost...
    params['UserData'] = Base64.encode64(lparams[:user_data]).delete("\n") unless lparams[:user_data].blank?
  end
  link = generate_request("RunInstances", params)
    #debugger
  instances = request_info(link, QEc2DescribeInstancesParser.new(:logger => @logger))
  get_desc_instances(instances)
rescue Exception
  on_exception
end

#modify_image_attribute(image_id, attribute, operation_type = nil, vars = {}) ⇒ Object

Modify an image’s attributes. It is recommended that you use modify_image_launch_perm_add_users, modify_image_launch_perm_remove_users, etc. instead of modify_image_attribute because the signature of modify_image_attribute may change with EC2 service changes.

attribute      : currently, only 'launchPermission' is supported.
operation_type : currently, only 'add' & 'remove' are supported.
vars: 
  :user_group  : currently, only 'all' is supported.  
  :user_id
  :product_code



300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/ec2/right_ec2.rb', line 300

def modify_image_attribute(image_id, attribute, operation_type = nil, vars = {})
  params =  {'ImageId'   => image_id,
             'Attribute' => attribute}
  params['OperationType'] = operation_type if operation_type
  params.update(hash_params('UserId',      vars[:user_id].to_a))    if vars[:user_id]
  params.update(hash_params('UserGroup',   vars[:user_group].to_a)) if vars[:user_group]
  params.update(hash_params('ProductCode', vars[:product_code]))    if vars[:product_code]
  link = generate_request("ModifyImageAttribute", params)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#modify_image_launch_perm_add_groups(image_id, user_group = ['all']) ⇒ Object

Add image launch permissions for users groups (currently only ‘all’ is supported, which gives public launch permissions). Returns true or an exception.

ec2.modify_image_launch_perm_add_groups('ami-e444444d') #=> true



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

def modify_image_launch_perm_add_groups(image_id, user_group=['all'])
  modify_image_attribute(image_id, 'launchPermission', 'add', :user_group => user_group.to_a)
end

#modify_image_launch_perm_add_users(image_id, user_id = []) ⇒ Object

Grant image launch permissions to users. Parameter userId is a list of user AWS account ids. Returns true or an exception.

ec2.modify_image_launch_perm_add_users('ami-e444444d',['000000000777','000000000778']) #=> true



318
319
320
 
# File 'lib/ec2/right_ec2.rb', line 318

def modify_image_launch_perm_add_users(image_id, user_id=[])
  modify_image_attribute(image_id, 'launchPermission', 'add', :user_id => user_id.to_a)
end

#modify_image_launch_perm_remove_groups(image_id, user_group = ['all']) ⇒ Object

Remove image launch permissions for users groups (currently only ‘all’ is supported, which gives public launch permissions). 

ec2.modify_image_launch_perm_remove_groups('ami-e444444d') #=> true



343
344
345
 
# File 'lib/ec2/right_ec2.rb', line 343

def modify_image_launch_perm_remove_groups(image_id, user_group=['all'])
  modify_image_attribute(image_id, 'launchPermission', 'remove', :user_group => user_group.to_a)
end

#modify_image_launch_perm_remove_users(image_id, user_id = []) ⇒ Object

Revokes image launch permissions for users. userId is a list of users AWS accounts ids. Returns true or an exception.

ec2.modify_image_launch_perm_remove_users('ami-e444444d',['000000000777','000000000778']) #=> true



326
327
328
 
# File 'lib/ec2/right_ec2.rb', line 326

def modify_image_launch_perm_remove_users(image_id, user_id=[])
  modify_image_attribute(image_id, 'launchPermission', 'remove', :user_id => user_id.to_a)
end

#modify_image_product_code(image_id, product_code = []) ⇒ Object

Add product code to image

ec2.modify_image_product_code('ami-e444444d','0ABCDEF') #=> true



351
352
353
 
# File 'lib/ec2/right_ec2.rb', line 351

def modify_image_product_code(image_id, product_code=[])
  modify_image_attribute(image_id, 'productCodes', nil, :product_code => product_code.to_a)
end

#reboot_instances(list) ⇒ Object

Reboot an EC2 instance. Returns true or an exception.

ec2.reboot_instances(['i-f222222d','i-f222222e']) #=> true



570
571
572
573
574
575
 
# File 'lib/ec2/right_ec2.rb', line 570

def reboot_instances(list)
  link = generate_request("RebootInstances", hash_params('InstanceId', list.to_a))
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#register_image(image_location) ⇒ Object

Register new image at Amazon. Returns new image id or an exception.

ec2.register_image('bucket/key/manifest') #=> 'ami-e444444d'



242
243
244
245
246
247
248
 
# File 'lib/ec2/right_ec2.rb', line 242

def register_image(image_location)
  link = generate_request("RegisterImage", 
                          'ImageLocation' => image_location.to_s)
  request_info(link, QEc2RegisterImageParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#release_address(public_ip) ⇒ Object

Release an elastic IP address associated with your account. Returns true or an exception.

ec2.release_address('75.101.154.140') #=> true



834
835
836
837
838
839
840
 
# File 'lib/ec2/right_ec2.rb', line 834

def release_address(public_ip)
  link = generate_request("ReleaseAddress", 
                          "PublicIp" => public_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#request_cache_or_info(method, link, parser_class, use_cache = true) ⇒ Object

:nodoc:



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/ec2/right_ec2.rb', line 152

def request_cache_or_info(method, link, parser_class, use_cache=true) #:nodoc:
  # We do not want to break the logic of parsing hence will use a dummy parser to process all the standart 
  # steps (errors checking etc). The dummy parser does nothig - just returns back the params it received.
  # If the caching is enabled and hit then throw  AwsNoChange. 
  # P.S. caching works for the whole images list only! (when the list param is blank)      response, params = request_info(link, QEc2DummyParser.new)
  # check cache
  response, params = request_info(link, QEc2DummyParser.new)
  cache_hits?(method.to_sym, response.body) if use_cache
  parser = parser_class.new(:logger => @logger)
  @@bench.xml.add!{ parser.parse(response, params) }
  result = block_given? ? yield(parser) : parser.result
  # update parsed data
  update_cache(method.to_sym, :parsed => result) if use_cache
  result
end

#request_info(request, parser) ⇒ Object

Sends request to Amazon and parses the response Raises AwsError if any banana happened



146
147
148
149
150
 
# File 'lib/ec2/right_ec2.rb', line 146

def request_info(request, parser)  #:nodoc:
  thread = @params[:multi_thread] ? Thread.current : Thread.main
  thread[:ec2_connection] ||= Rightscale::HttpConnection.new(:exception => AwsError, :logger => @logger)
  request_info_impl(thread[:ec2_connection], @@bench, request, parser)
end

#reset_image_attribute(image_id, attribute = 'launchPermission') ⇒ Object

Reset image attribute. Currently, only ‘launchPermission’ is supported. Returns true or an exception.

ec2.reset_image_attribute('ami-e444444d') #=> true



280
281
282
283
284
285
286
287
 
# File 'lib/ec2/right_ec2.rb', line 280

def reset_image_attribute(image_id, attribute='launchPermission')
  link = generate_request("ResetImageAttribute", 
                          'ImageId'   => image_id,
                          'Attribute' => attribute)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#revoke_security_group_IP_ingress(name, from_port, to_port, protocol = 'tcp', cidr_ip = '0.0.0.0/0') ⇒ Object

Remove permission from a security group. Returns true or an exception. protocol is one of :‘tcp’|‘udp’|‘icmp’ (‘tcp’ is default). 

ec2.revoke_security_group_IP_ingress('my_awesome_group', 80, 82, 'udp', '192.168.1.0/8') #=> true



712
713
714
715
716
717
718
719
720
721
722
 
# File 'lib/ec2/right_ec2.rb', line 712

def revoke_security_group_IP_ingress(name, from_port, to_port, protocol='tcp', cidr_ip='0.0.0.0/0')
  link = generate_request("RevokeSecurityGroupIngress", 
                          'GroupName'  => name.to_s, 
                          'IpProtocol' => protocol.to_s, 
                          'FromPort'   => from_port.to_s, 
                          'ToPort'     => to_port.to_s, 
                          'CidrIp'     => cidr_ip.to_s)
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#revoke_security_group_named_ingress(name, owner, group) ⇒ Object

Revoke named ingress for security group.

ec2.revoke_security_group_named_ingress('my_awesome_group', aws_user_id, 'another_group_name') #=> true



681
682
683
684
685
686
687
688
689
 
# File 'lib/ec2/right_ec2.rb', line 681

def revoke_security_group_named_ingress(name, owner, group)
  link = generate_request("RevokeSecurityGroupIngress", 
                          'GroupName'                  => name.to_s, 
                          'SourceSecurityGroupName'    => group.to_s, 
                          'SourceSecurityGroupOwnerId' => owner.to_s.gsub(/-/,''))
  request_info(link, RightBoolResponseParser.new(:logger => @logger))
rescue Exception
  on_exception
end

#run_instances(image_id, min_count, max_count, group_ids, key_name, user_data = '', addressing_type = nil, instance_type = nil, kernel_id = nil, ramdisk_id = nil, availability_zone = nil, block_device_mappings = nil) ⇒ Object

Launch new EC2 instances. Returns a list of launched instances or an exception.

ec2.run_instances('ami-e444444d',1,1,['my_awesome_group'],'my_awesome_key', 'Woohoo!!!', 'public') #=>
 [{:aws_image_id       => "ami-e444444d",
   :aws_reason         => "",
   :aws_state_code     => "0",
   :aws_owner          => "000000000888",
   :aws_instance_id    => "i-123f1234",
   :aws_reservation_id => "r-aabbccdd",
   :aws_state          => "pending",
   :dns_name           => "",
   :ssh_key_name       => "my_awesome_key",
   :aws_groups         => ["my_awesome_group"],
   :private_dns_name   => "",
   :aws_instance_type  => "m1.small",
   :aws_launch_time    => "2008-1-1T00:00:00.000Z"
   :aws_ramdisk_id     => "ari-8605e0ef"
   :aws_kernel_id      => "aki-9905e0f0",
   :ami_launch_index   => "0",
   :aws_availability_zone => "us-east-1b"
   }]



441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
 
# File 'lib/ec2/right_ec2.rb', line 441

def run_instances(image_id, min_count, max_count, group_ids, key_name, user_data='',  
                  addressing_type = nil, instance_type = nil,
                  kernel_id = nil, ramdisk_id = nil, availability_zone = nil, 
                  block_device_mappings = nil) 
  launch_instances(image_id, { :min_count       => min_count, 
                               :max_count       => max_count, 
                               :user_data       => user_data, 
                               :group_ids       => group_ids, 
                               :key_name        => key_name, 
                               :instance_type   => instance_type, 
                               :addressing_type => addressing_type,
                               :kernel_id       => kernel_id,
                               :ramdisk_id      => ramdisk_id,
                               :availability_zone     => availability_zone,
                               :block_device_mappings => block_device_mappings
                             }) 
end

#terminate_instances(list = []) ⇒ Object

Terminates EC2 instances. Returns a list of termination params or an exception.

ec2.terminate_instances(['i-f222222d','i-f222222e']) #=>
  [{:aws_shutdown_state      => "shutting-down", 
    :aws_instance_id         => "i-f222222d", 
    :aws_shutdown_state_code => 32, 
    :aws_prev_state          => "running", 
    :aws_prev_state_code     => 16}, 
   {:aws_shutdown_state      => "shutting-down", 
    :aws_instance_id         => "i-f222222e", 
    :aws_shutdown_state_code => 32, 
    :aws_prev_state          => "running", 
    :aws_prev_state_code     => 16}]



545
546
547
548
549
550
 
# File 'lib/ec2/right_ec2.rb', line 545

def terminate_instances(list=[])
  link = generate_request("TerminateInstances", hash_params('InstanceId',list.to_a))
  request_info(link, QEc2TerminateInstancesParser.new(:logger => @logger))
rescue Exception
  on_exception
end