CloudyScripts 0.0.2 → 0.0.3

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Matthias Jung
+Copyright (c) 2010 Matthias Jung
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

data/README.rdoc

@@ -0,0 +1,22 @@
+# =About
+# CloudyScripts is a library that implements tasks that support common
+# usecases on Cloud Computing Infrastructures (such as Amazon EC2 or Rackspace).
+# It aims to facilitate the implementation of usecases that are not directly
+# available via the providers' API (e.g. like encrypting storage,
+# migrating instances betweem accounts, activating HTTPS). The scripts typically
+# use the provider APIs plus remote access to command-line tools installed on
+# the instances themselves.
+#
+# =Installation and Usage
+# ==Installation
+# <tt>gem install CloudyScripts</tt>
+#
+# ==Usage
+# All scripts are available under /lib/scripts/<provider>
+# They are initialized with a set of parameters and return a well-define
+# set of return values.
+#
+# =Scripts
+# Here are the scripts implemented so far:
+# * #DmEncrypt (encrypt Amazon EBS Storage using dm-encrypt)
+#

data/Rakefile

@@ -12,9 +12,9 @@ require 'rake/testtask'
 
 spec = Gem::Specification.new do |s|
   s.name = 'CloudyScripts'
-  s.version = '0.0.2'
+  s.version = '0.0.3'
   s.has_rdoc = true
-  s.extra_rdoc_files = ['README', 'LICENSE']
+  s.extra_rdoc_files = ['README.rdoc', 'LICENSE']
   s.summary = 'Scripts to facilitate programming for infrastructure clouds.'
   s.description = s.summary
   s.homepage = "http://elastic-security.com"
@@ -22,7 +22,7 @@ spec = Gem::Specification.new do |s|
   s.author = 'Matthias Jung'
   s.email = 'matthias.jung@gmail.com'
   # s.executables = ['your_executable_here']
-  s.files = %w(LICENSE README Rakefile) + Dir.glob("{bin,lib,spec}/**/*")
+  s.files = %w(LICENSE README.rdoc Rakefile) + Dir.glob("{bin,lib,spec}/**/*")
   s.require_path = "lib"
   s.bindir = "bin"
   s.has_rdoc = true

data/lib/cloudyscripts.rb

@@ -2,6 +2,25 @@ require 'rubygems'
 require 'net/ssh'
 require 'AWS'
 
+# =About
+# CloudyScripts is a library that implements tasks that support common
+# usecases on Cloud Computing Infrastructures (such as Amazon EC2 or Rackspace).
+# It aims to facilitate the implementation of usecases that are not directly
+# available via the providers' API (e.g. like encrypting storage,
+# migrating instances betweem accounts, activating HTTPS). The scripts typically
+# use the provider APIs plus remote access to command-line tools installed on
+# the instances themselves.
 #
-# 
-#
+# =Installation and Usage
+# ===Installation
+# <tt>gem install CloudyScripts</tt>
+#
+# ===Usage
+# All scripts are available under /lib/scripts/<em>provider</em>>
+#
+# ===Scripts
+# Here are the scripts implemented so far:
+# * #Scripts::EC2::DmEncrypt (encrypt Amazon EBS Storage using dm-encrypt)
+#
+class CloudyScripts
+end

data/lib/help/dm_crypt_helper.rb

@@ -1,16 +1,23 @@
-require 'lib/ssh_api'
+require 'help/remote_command_handler'
+
+# This class implements helper methods for Dm Encryption
+# (see #Scripts::EC2::DmEncrypt)
 
 class DmCryptHelper
 
+  # Passes an remote command handler object
+  # (see #Help::RemoteCommandHandler)
   def set_ssh(ssh_session)
     @ssh_session = ssh_session
   end
 
+  # Installs the dm-crypt tools (if not yet done)
   def install()
     #TODO: dm-crypt seems to be installed automatically
     true
   end
 
+  # Checks if the dm-crypt tool is installed (true/false)
   def tools_installed?()
     @ssh_session.exec! "which dmsetup" do |ch, stream, data|
       if stream == :stderr
@@ -26,9 +33,15 @@ class DmCryptHelper
     true
   end
 
+  # Encrypts the device and mounting it using dm-crypt tools.
+  # Params
+  # * name: name of the virtual volume
+  # * password: paraphrase to be used for encryption
+  # * device: device to be encrypted
+  # * path: path to which the encrypted device is mounted
   def encrypt_storage(name, password, device, path)
     # first: check if a file in /dev/mapper exists
-    if SshApi.file_exists?(@ssh_session, "/dev/mapper/dm-#{name}")
+    if RemoteCommandHandler.file_exists?(@ssh_session, "/dev/mapper/dm-#{name}")
       mapper_exists = true
     else
       mapper_exists = false
@@ -95,7 +108,7 @@ class DmCryptHelper
       exec_string = "vgcreate vg-#{name} /dev/mapper/dm-#{name}"
       puts "vg_exists == false; execute #{exec_string}"
       @ssh_session.exec! exec_string do |ch, stream, data|
-        if stream == :stderr && !data.blank?
+        if stream == :stderr && data != nil
           err = "Failed during creation of volume group"
           puts "#{err}: #{data}"
           raise Exception.new(err)
@@ -105,7 +118,7 @@ class DmCryptHelper
       exec_string = "lvcreate -n lv-#{name} -l100%FREE vg-#{name}"
       puts "execute #{exec_string}"
       @ssh_session.exec! exec_string do |ch, stream, data|
-        if stream == :stderr && !data.blank?
+        if stream == :stderr && data != nil
           err = "Failed during creation of logical volume"
           puts "#{err}: #{data}"
           raise Exception.new(err)
@@ -114,13 +127,13 @@ class DmCryptHelper
       exec_string = "mkfs -t ext3 /dev/vg-#{name}/lv-#{name}"
       puts "execute #{exec_string}"
       @ssh_session.exec! exec_string #do |ch, stream, data|
-        #if stream == :stderr && !data.blank?
+        #if stream == :stderr && data != nil
         #err = "Failed during creation of file-system"
         #puts "#{err}: #{data}"
         #raise Exception.new(err)
         #end
       #end
-      if !SshApi.file_exists?(@ssh_session,"/dev/vg-#{name}/lv-#{name}")
+      if !RemoteCommandHandler.file_exists?(@ssh_session,"/dev/vg-#{name}/lv-#{name}")
         err = "Missing file: /dev/vg-#{name}/lv-#{name}"
         raise Exception.new(err)
       end
@@ -128,7 +141,7 @@ class DmCryptHelper
       exec_string = "/sbin/vgchange -a y vg-#{name}"
       puts "vg_exists == true; execute #{exec_string}"
       @ssh_session.exec! exec_string do |ch, stream, data| #TODO: the right size instead L2G!
-        if stream == :stderr && !data.blank?
+        if stream == :stderr && data != nil
           err = "Failed during re-activation of volume group"
           puts "#{err}: #{data}"
           raise Exception.new(err)
@@ -137,10 +150,12 @@ class DmCryptHelper
     end
   end
 
+  # Check if the storage is encrypted (not yet implemented).
   def test_storage_encryption(password, mount_point, path)
     raise Exception.new("not yet implemented")
   end
 
+  # Undo encryption for the volume specified by name and path
   def undo_encryption(name, path)
     exec_string = "umount #{path}"
     puts "going to execute #{exec_string}"

data/lib/help/remote_command_handler.rb

@@ -1,11 +1,13 @@
 require 'rubygems'
 require 'net/ssh'
 
+# Provides methods to be executed via ssh to remote instances.
 class RemoteCommandHandler
   def initialize
     @crypto = DmCryptHelper.new #TODO: instantiate helpers for different tools
   end
 
+  # Check if the path/file specified exists
   def self.file_exists?(ssh_session, path)
     result = true
     ssh_session.exec!("ls #{path}") do |ch, stream, data|
@@ -15,28 +17,37 @@ class RemoteCommandHandler
     end
     result
   end
-  
+
+  # Connect to the machine as root using a keyfile.
+  # Params:
+  # * ip: ip address of the machine to connect to
+  # * keyfile: path of the keyfile to be used for authentication
   def connect(ip, keyfile)
     @ssh_session = Net::SSH.start(ip, 'root', :keys => [keyfile])
     @crypto.set_ssh(@ssh_session)
   end
 
+  # Disconnect the current handler
   def disconnect
     @ssh_session.close
   end
 
+  # Installs the software package specified.
   def install(software_package)
     @crypto.install()
   end
 
+  # Checks if the software package specified is installed.
   def tools_installed?(software_package)
     @crypto.tools_installed?
   end
 
+  # Encrypt the storage (using the crypto-helper used, e.g. #Help::DmCryptHelper)
   def encrypt_storage(name, password, device, path)
     @crypto.encrypt_storage(name, password, device, path)
   end
 
+  # Check if the storage is encrypted (using the crypto-helper used, e.g. #Help::DmCryptHelper)
   def storage_encrypted?(password, device, path)
     drive_mounted?(path) #TODO: must at least also check the name
   end
@@ -79,6 +90,7 @@ class RemoteCommandHandler
     drive_mounted
   end
 
+  # Activates the encrypted volume, i.e. mounts it if not yet done.
   def activate_encrypted_volume(name, path)
     drive_mounted = drive_mounted?(path)
     puts "drive #{path} mounted? #{drive_mounted}"
@@ -87,7 +99,7 @@ class RemoteCommandHandler
       exec_string = "mount /dev/vg-#{name}/lv-#{name} #{path}"
       puts "drive not mounted; execute: #{exec_string}"
       @ssh_session.exec! "mount /dev/vg-#{name}/lv-#{name} #{path}" do |ch, stream, data|
-        if stream == :stderr && !data.blank?
+        if stream == :stderr && data != nil
           err = "Failed during mounting encrypted device"
           puts "#{err}: #{data}"
           puts "mount /dev/vg-#{name}/lv-#{name} #{path}"
@@ -97,10 +109,12 @@ class RemoteCommandHandler
     end
   end
 
+  # Unconfigure the storage (using the crypto-helper used, e.g. #Help::DmCryptHelper)
   def undo_encryption(name, path)
     @crypto.undo_encryption(name, path)
   end
 
+  # Unmount the specified path.
   def umount(path)
     exec_string = "umount #{path}"
     puts "going to execute #{exec_string}"

data/lib/help/script_execution_state.rb

@@ -51,6 +51,7 @@ class ScriptExecutionState
     s.sub(/.*\:\:/,'')
   end
 
+  # Standard state reached when an exception occurs.
   class FailedState < ScriptExecutionState
     attr_accessor :failure_reason, :from_state
     def initialize(context, failure_reason, from_state)

data/lib/scripts/ec2/dm_encrypt.rb

@@ -1,23 +1,28 @@
 require "help/script_execution_state"
 require "scripts/ec2/ec2_script"
+require "help/remote_command_handler"
+require "help/dm_crypt_helper"
+require "AWS"
 
-# Encrypts an EC2 Storage
+# Script to Encrypt an EC2 Storage (aka Elastic Block Storage)
+# 
 class DmEncrypt < Ec2Script
   def initialize(input_params)
     super(input_params)
   end
 
   # Input parameters
-  # aws_access_key => the Amazon AWS Access Key (see Your Account -> Security Credentials)
-  # aws_secret_key => the Amazon AWS Secret Key
-  # ip_address => IP Address of the machine to connect to
-  # ssh_key_file => Path of the keyfile used to connect to the machine
-  # device => Path of the device to encrypt
-  # device_name => Name of the Device to encrypt
-  # storage_path => Path on which the encrypted device is mounted
-  # remote_command_handler => object that allows to connect via ssh and execute commands
-  # ec2_api_handler => object that allows to access the EC2 API
-  # password => password used for encryption
+  # * aws_access_key => the Amazon AWS Access Key (see Your Account -> Security Credentials)
+  # * aws_secret_key => the Amazon AWS Secret Key
+  # * ip_address => IP Address of the machine to connect to
+  # * ssh_key_file => Path of the keyfile used to connect to the machine
+  # * device => Path of the device to encrypt
+  # * device_name => Name of the Device to encrypt
+  # * storage_path => Path on which the encrypted device is mounted
+  # * paraphrase => paraphrase used for encryption
+  # * remote_command_handler => object that allows to connect via ssh and execute commands (optional)
+  # * ec2_api_handler => object that allows to access the EC2 API (optional)
+  # * ec2_api_server => server to connect to (option, default is us-east-1.ec2.amazonaws.com)
   #
   def initialize(input_params)
     super(input_params)
@@ -27,6 +32,18 @@ class DmEncrypt < Ec2Script
   # Executes the script.
   def start_script
     begin
+      # optional parameters and initialization
+      if @input_params[:ec2_api_server] == nil
+        @input_params[:ec2_api_server] = "us-east-1.ec2.amazonaws.com"
+      end
+      if @input_params[:remote_command_handler] == nil
+        @input_params[:remote_command_handler] = RemoteCommandHandler.new
+      end
+      if @input_params[:ec2_api_handler] == nil
+        @input_params[:ec2_api_handler] = AWS::EC2::Base.new(:access_key_id => @input_params[:aws_access_key],
+        :secret_access_key => @input_params[:aws_secret_key], :server => @input_params[:ec2_api_server])
+      end
+      # start state machine
       current_state = DmEncryptState.load_state(@input_params)
       end_state = current_state.start_state_machine()
       if end_state.failed?
@@ -40,10 +57,10 @@ class DmEncrypt < Ec2Script
       puts "exception during encryption: #{e}"
       puts e.backtrace.join("\n")
       err = e.to_s
-      err += " (in #{current_state.end_state.to_s})" unless current_state.blank?
+      err += " (in #{current_state.end_state.to_s})" unless current_state == nil
       @result[:failed] = true
       @result[:failure_reason] = err
-      @result[:end_state] = current_state.end_state unless current_state.blank?
+      @result[:end_state] = current_state.end_state unless current_state == nil
     ensure
       begin
       @input_params[:remote_command_handler].disconnect
@@ -66,7 +83,6 @@ class DmEncrypt < Ec2Script
   private
 
   # Here begins the state machine implementation
-
   class DmEncryptState < ScriptExecutionState
 
     def self.load_state(context)
@@ -135,7 +151,7 @@ class DmEncrypt < Ec2Script
       end
       #
       @context[:remote_command_handler].encrypt_storage(@context[:device_name],
-      @context[:password], @context[:device], @context[:storage_path])
+      @context[:paraphrase], @context[:device], @context[:storage_path])
       VolumeCreatedState.new(@context)
     end
 
@@ -146,6 +162,7 @@ class DmEncrypt < Ec2Script
 
   end
 
+  # The encrypted Volume is created. Going to mount it.
   class VolumeCreatedState < DmEncryptState
     def enter
       mount_and_activate()
@@ -159,6 +176,7 @@ class DmEncrypt < Ec2Script
     end
   end
 
+  # The encrypted storages is mounted. Cleanup and done.
   class MountedAndActivatedState < DmEncryptState
     def enter
       cleanup()

data/lib/scripts/ec2/ec2_script.rb

@@ -1,12 +1,23 @@
 # Base class for any script on EC2.
 class Ec2Script
-  # Input parameters
-  # aws_access_key => the Amazon AWS Access Key (see Your Account -> Security Credentials)
-  # aws_secret_key => the Amazon AWS Secret Key
-  #
+  # Initialization. Common Input parameters:
+  # * aws_access_key => the Amazon AWS Access Key (see Your Account -> Security Credentials)
+  # * aws_secret_key => the Amazon AWS Secret Key
+  # Scripts may add specific key/value pairs.
   def initialize(input_params)
     @input_params = input_params
   end
 
+  # Return a hash of results. Common values are:
+  # * :done => is true when the script has terminated, otherwise false
+  # * :failed => is false when the script succeeded
+  # * :failure_reason => returns a failure reason (string)
+  # * :end_state => returns the state, in which the script terminated (#Help::ScriptExecutionState)
+  # Scripts may add specific key/value pairs.
+  # * 
+  def get_execution_result
+    raise Exception.new("must be implemented")
+  end
+
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: CloudyScripts
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Matthias Jung
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-12 00:00:00 +01:00
+date: 2009-12-18 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -39,11 +39,11 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.rdoc
 - LICENSE
 files: 
 - LICENSE
-- README
+- README.rdoc
 - Rakefile
 - lib/cloudyscripts.rb
 - lib/help/dm_crypt_helper.rb

data/README

@@ -1 +0,0 @@
-Scripts to facilitate programming for infrastructure clouds