cloud_stack_client 0.0.1

data/bin/cloud-stack.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require "cloud_stack_client/cli"
+cli = CloudStackClient::CLI.new
+result = cli.run $0, ARGV
+exit 1 unless result

data/cloud_stack_client.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cloud_stack_client/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "cloud_stack_client"
+  gem.version       = CloudStackClient::VERSION
+  gem.authors       = ["Roman Messer"]
+  gem.email         = ["roman.messer@ict-cloud.com"]
+  gem.description   = %q{Execute any command against a CloudStack Infrastructure. Also contains a commandline utility with auto paging and support to read credentials from a config file.}
+  gem.summary       = %q{A simple library to work with the CloudStack API.}
+  # gem.homepage      = ""
+
+  if File.exist? '.git'
+    gem.files         = `git ls-files`.split($/)
+  elsif File.exist? '.hg'
+    gem.files         = `hg manifest`.split($/)
+  end
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/lib/cloud_stack_client.rb

@@ -0,0 +1,8 @@
+require "cloud_stack_client/version"
+require "cloud_stack_client/definitions"
+require "cloud_stack_client/api"
+require "cloud_stack_client/connector"
+
+# Execute queries against the CloudStack API
+module CloudStackClient
+end

data/lib/cloud_stack_client/api.rb

@@ -0,0 +1,325 @@
+# An API to interact with the Citrix CloudStack Platform
+
+require "cloud_stack_client/helpers"
+require "cloud_stack_client/definitions"
+require "digest/md5"
+autoload :URI, "uri"
+autoload :OpenSSL, "openssl"
+autoload :Base64, "base64"
+autoload :JSON, "json"
+# Autoloading Net submodules
+# @private
+module Net
+  autoload :HTTP, "net/http"
+end
+# Autoloading REXML submodules
+# @private
+module REXML
+  autoload :Document, "rexml/document"
+  autoload :QuickPath, "rexml/quickpath"
+end
+
+module CloudStackClient
+  # Collection of functions to work with the API
+  module API
+    
+    # Login with username, password hash and domain to get session credentials
+    # 
+    # @param api_uri [String] HTTP URL of the CloudStack API
+    # @param username [String] CloudStack login user
+    # @param hashed_password [String] CloudStack login password (use {CloudStackClient::Helpers::hash_password}) 
+    # @param domain [String] CloudStack login domain
+    # @param http_method [Symbol] The HTTP method to submit the query (:post or :get)
+    # @param ssl_check [Boolean] Check Server SSL certificate?
+    # @return [Hash] Credentials for subsequent queries
+    # @see CloudStackClient::Helpers::hash_password
+    def self.get_credentials(api_uri, username, hashed_password, domain = "", http_method = nil , ssl_check = nil)
+      http_method ||= API_DEFAULTS[:http_method]
+      ssl_check ||= API_DEFAULTS[:ssl_check]
+      parameters = {:command => "login", :response => "json", :username => username, :password => hashed_password, :domain => parse_domain(domain)}
+      headers, body = execute_query(api_uri, generate_query(parameters), [], http_method, ssl_check)
+      credentials = {}
+      if headers.has_key? "set-cookie" # Expect lowercase names from Net::HTTPHeader 
+        credentials[:session_cookies] = headers["set-cookie"].map {|raw| raw.split(";").first}
+      end
+      json = JSON.parse body
+      return nil unless CloudStackClient::API::response_is_success? json
+      credentials[:session_key] = json["loginresponse"]["sessionkey"]
+      credentials[:user_id] = json["loginresponse"]["userid"]
+      credentials
+    end
+    
+    # Test connection with supplied Secret key and API key
+    # 
+    # @param api_uri [String] HTTP URL of the CloudStack API
+    # @param api_key [String] CloudStack API Key
+    # @param secret_key [String] Cloudstack Secret Key
+    # @param http_method [Symbol] The HTTP method to submit the query (:post or :get)
+    # @param ssl_check [Boolean] Check Server SSL certificate?
+    # @return [Boolean]
+    def self.verify_keys(api_uri, api_key, secret_key, http_method = nil, ssl_check = nil)
+      http_method ||= API_DEFAULTS[:http_method]
+      ssl_check ||= API_DEFAULTS[:ssl_check]
+      CloudStackClient::API::response_is_success? query(api_uri, {:command => "listCapabilities"}, {:api_key => api_key, :secret_key => secret_key}, http_method, ssl_check)
+    end
+    
+    # Execute a query
+    # 
+    # @param api_uri [String] HTTP URL of the CloudStack API
+    # @param parameters [Hash] A Hash containing all query parameters. The keys can be specified as Symbol or String
+    # @param credentials [Hash] Contains either :api_key and :secret_key or :session_key and :session_cookies as obtained from {get_credentials}
+    # @param http_method [Symbol] The HTTP method to submit the query (:post or :get)
+    # @param ssl_check [Boolean] Check Server SSL certificate?
+    # @return [REXML::Document, Hash] An XML Document or the parsed JSON (commonly a Hash)
+    def self.query(api_uri, parameters, credentials, http_method = nil, ssl_check = nil)
+      http_method ||= API_DEFAULTS[:http_method]
+      ssl_check ||= API_DEFAULTS[:ssl_check]
+      if credentials.is_a?(Hash) && credentials.has_key?(:api_key) && credentials.has_key?(:secret_key)
+        parameters[:apiKey] = credentials[:api_key]
+        parameters[:secret] = credentials[:secret_key]
+        parameters[:timestamp] = Time.new.to_i
+        headers, body = self.execute_query(api_uri, generate_query(parameters), [], http_method, ssl_check)
+      elsif credentials.is_a? Hash
+        parameters[:sessionkey] = credentials[:session_key] if credentials.has_key? :session_key
+        headers, body = self.execute_query(api_uri, generate_query(parameters), credentials[:session_cookies], http_method, ssl_check)
+      end
+      
+      format = nil
+      if headers["content-type"]
+        format = headers["content-type"][0].split(";").first
+      end
+      
+      case format
+      when "text/javascript"
+        JSON.parse body
+      when "text/xml"
+        REXML::Document.new body
+      else
+        body
+      end
+    end
+    
+    # Executes the query like query() but merges all result pages into one
+    # 
+    # @param api_uri [String] HTTP URL of the CloudStack API
+    # @param parameters [Hash] A Hash containing all query parameters. The keys can be specified as Symbol or String
+    # @param credentials [Hash] Contains either :api_key and :secret_key or :session_key and :session_cookies as obtained from {get_credentials}
+    # @param http_method [Symbol] The HTTP method to submit the query (:post or :get)
+    # @param ssl_check [Boolean] Check Server SSL certificate?
+    # @return [REXML::Document, Hash] An XML Document or the parsed JSON (commonly a Hash)
+    def self.query_with_auto_paging(api_uri, parameters, credentials, page_size = nil, http_method = nil, ssl_check = nil)
+      page_size ||= API_DEFAULTS[:page_size]
+      http_method ||= API_DEFAULTS[:http_method]
+      ssl_check ||= API_DEFAULTS[:ssl_check]
+      output = nil
+      parameters[:page] = 0
+      parameters[:pageSize] = page_size
+      has_count = false
+      
+      begin
+        parameters[:page] += 1
+        data = self.query api_uri, parameters, credentials, http_method, ssl_check
+        return nil unless data
+        format = :json
+        format = :xml if data.is_a? REXML::Document
+        
+        # Remove count attribute from result data
+        if format == :xml
+          count_data = REXML::QuickPath.first(data.root, "//count")
+          if count_data
+            count = count_data.text.to_i
+            count_data.remove
+            has_count = true
+          else
+            count = 0
+          end
+        elsif format == :json
+          if data.first[1].has_key? "count"
+            count = data.first[1]["count"]
+            data.first[1].delete "count"
+            has_count = true
+          else
+            count = 0
+          end
+        end
+        
+        # Copy first page in total
+        if !output
+          output = data
+          loop_done = count < parameters[:pageSize]
+          next
+        end
+        
+        if count <= 0
+          # No elements
+          loop_done = true
+        elsif count >= parameters[:pageSize]
+          # Copy all elements if page is full
+          if format == :xml
+            data.root.elements.each {|record| output.root << record}
+          elsif format == :json
+            data.first[1].first[1].each {|record| output.first[1].first[1] << record}
+          end
+        else
+          # Handle last page
+          loop_done = true
+          # Detect and ignore duplicates that have already been extracted.
+          # E.g. guest-utilities during listIsos command 
+          if format == :xml
+            pos_output = output.root.elements.size - count + 1
+            end_output = output.root.elements.size + 1
+            while pos_output < end_output
+              if output.root.elements[pos_output].to_s != data.root.elements[1].to_s
+                output.root << data.root.elements[1] # Move node to output tree
+              end
+              pos_output += 1
+            end
+          elsif format == :json
+            pos_data = 0
+            pos_output = output.first[1].first[1].size - count
+            end_output = output.first[1].first[1].size
+            while pos_output < end_output
+              if output.first[1].first[1][pos_output] != data.first[1].first[1][pos_data]
+                output.first[1].first[1] << data.first[1].first[1][pos_data]
+              end
+              pos_data += 1
+              pos_output += 1
+            end
+          end
+        end
+      end until loop_done
+      
+      # Recalculate count attribute
+      if has_count && CloudStackClient::API::response_is_success?(output)
+        if format == :xml && output.root && output.root.has_elements?
+          new_count = REXML::Element.new "count"
+          new_count.add_text output.root.elements.count.to_s
+          output.root << new_count
+        elsif format == :json && output.first && output.first[1].any?
+          output.first[1]["count"] = output.first[1].first[1].count
+        end
+      end
+      output
+    end
+    
+    # Generate a single sign on link for the management console
+    # 
+    # @param web_uri [String] The base URL of Webinterface
+    # @param username [String] CloudStack login user
+    # @param hashed_password [String] CloudStack login password (use {CloudStackClient::Helpers::hash_password}) 
+    # @param domain [String] CloudStack login domain
+    # @param login_parameter [String] The name of the CloudStack URL parameter that has been specified in scripts/cloud.core.callbacks.js to contain the login credentials
+    # @param timestamp_offset [Fixnum] Custom scripts/cloud.core.callbacks.js parameter to invalidate the login link after the specified number of seconds 
+    # @return [String] A complete URL
+    # @see CloudStackClient::Helpers::hash_password 
+    def self.generate_management_console_link(web_uri, username, hashed_password, domain = "", login_parameter = nil, timestamp_offset = nil)
+      login_parameter ||= API_DEFAULTS[:login_parameter]
+      timestamp_offset ||= API_DEFAULTS[:timestamp_offset]
+      uri = "#{web_uri}?#{login_parameter}="
+      uri += escape(generate_query({:command => "login", :response => "json", :username => username, :password => hashed_password, :domain => parse_domain(domain)}))
+      uri += "&timestamp=#{Time.new.to_i + timestamp_offset}" if timestamp_offset
+      return uri
+    end
+    
+    private
+    
+    # Sanitize the domain
+    def self.parse_domain(domain = "")
+      domain = domain.to_s
+      if domain.start_with? "/"
+        domain
+      else
+        "/" + domain
+      end
+    end
+    
+    # Make string URL safe
+    def self.escape(string)
+      URI.escape(string, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
+    end
+    
+    # Construct a query from a Hash of parameters or an Array of [key, value] Arrays
+    def self.generate_query(parameters = {})
+      if parameters.is_a? Enumerable
+        # Escape the key / value pairs
+        parameters = parameters.map {|param| [escape(param[0].to_s), escape(param[1].to_s)]}
+      else
+        parameters = [[escape(parameters.to_s), ""]]
+      end
+      secret = nil
+      parameters.delete_if {|key, value| secret = value if key == "secret"}
+      
+      # Sign the query if secret is available
+      if secret
+        # Sort the parameters
+        parameters.sort!
+        # Generate query string
+        query = parameters.map {|param| param.join "="}.join("&")
+        # Generate signature by calculating SHA1 HMAC
+        hmac = OpenSSL::HMAC.digest("sha1", secret, query.downcase)
+        # Base64 encode 8 bit data and discard newline
+        base64 = Base64.encode64(hmac).strip
+        # Make signature URL safe
+        signature = escape(base64)
+        # Append signature to query
+        query += "&signature=" + signature
+      else
+        query = parameters.map {|param| param.join "="}.join("&")
+      end
+      query
+    end
+    
+    # Submit the query to the server
+    def self.execute_query(api_uri, query, cookies = [], http_method = API_DEFAULTS[:http_method], ssl_check = API_DEFAULTS[:ssl_check])
+      uri = URI.parse api_uri
+      http = Net::HTTP.new uri.host, uri.port
+      if uri.scheme == "https"
+        http.use_ssl = true
+        # Verify server SSL certificate
+        if ssl_check
+          # On Ruby before 1.9 a local CA store is needed to verify SSL certificates.
+          ruby_version = RUBY_VERSION.split(".").map{|num| num.to_i}
+          if ruby_version[0] == 1 && ruby_version[1] < 9 || ruby_version[0] < 1
+            http.ca_file = File.join(File.dirname(__FILE__), "../../assets/cacert.pem")
+          end
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        end
+      end
+      request_cookies = nil
+      request_cookies = cookies.join(';') if cookies.is_a?(Array) && cookies.any?
+      if http_method == :post
+        request = Net::HTTP::Post.new uri.path
+        request["Cookie"] = request_cookies if request_cookies
+        response = http.request request, query
+      elsif http_method == :get
+        request = Net::HTTP::Get.new "#{uri.path}?#{query}"
+        request["Cookie"] = request_cookies if request_cookies
+        response = http.request request
+      else
+        raise "Only HTTP methods :post and :get are implemented."
+      end
+      return response.to_hash, response.body # Hash of HTTP Response header and HTTP Body
+    end
+    
+    # Returns the format of a given reponse. Eigther :xml or :json
+    def self.response_format(response)
+      if response.is_a?(REXML::Document)
+        :xml
+      else
+        :json
+      end
+    end
+    
+    # Checks the given response whether the command was successful
+    def self.response_is_success?(response)
+      if response.is_a? REXML::Document
+        !(response.root.elements["errorcode"] || response.root.name == "errorresponse") 
+      elsif response.is_a?(Hash) && response.any?
+        !(response.first[1]["errorcode"] || response.first[0] == "errorresponse")
+      else
+        false
+      end
+    end
+
+  end
+end

data/lib/cloud_stack_client/cli.rb

@@ -0,0 +1,239 @@
+require "cloud_stack_client"
+require "yaml"
+
+module CloudStackClient
+  # The commandline client 'cloud-stack.rb'
+  # 
+  # Plesae run +cloud-stack.rb --help+ for additional info.
+  class CLI
+    # Default options for the command line. Can be overridden by parameters and a config file
+    DEFAULT_OPTIONS = {
+        :api_uri => nil,
+        :api_key => nil,
+        :secret_key => nil,
+        :username => nil,
+        :password => nil,
+        :domain => nil,
+        :response => "json",
+        :output => nil,
+        :debug => false,
+        :auto_paging => true,
+        :page_size => 500
+      }.freeze
+    
+    # Create new commandline instance
+    def initialize
+      @options = DEFAULT_OPTIONS.dup
+      @parameters = {}
+    end
+    
+    # Execute the command
+    # 
+    # @param command [String] The name of the executable ($0) 
+    # @param arguments [Array] Commandline parameters (ARGV)
+    # @return [Boolean] true if successful
+    def run(command, arguments)
+      # Parse commandline
+      pos = arguments.find_index("--config")
+      if pos
+        arguments.delete_at pos
+        raise "Path to config file missing" unless arguments[pos]
+        filename = arguments.delete_at pos
+        yaml = YAML.load_file filename
+        yaml["default"].each {|key, value| @options[key.to_sym] = value}
+      end
+      if arguments.empty?
+        print_help File.basename(command), DEFAULT_OPTIONS
+        return false
+      end
+      while arguments.any? do
+        arg = arguments.shift
+        raise "Unknown parameter #{arg}" unless arg.start_with? '--'
+        key = arg.slice(2, arg.length - 2)
+        case key
+        when 'debug', 'ignore-ssl', 'auto-paging', 'no-auto-paging'
+          # Single parameter options
+          if key.start_with? 'no-'
+            key = key.slice(3, arg.length - 3)
+            @options[key.gsub('-', '_').to_sym] = false
+          else
+            @options[key.gsub('-', '_').to_sym] = true
+          end
+        when 'api-key', 'secret-key', 'username', 'password', 'domain', 'api-uri', 'response', 'output', 'pagesize', 'config'
+          # Second parameter options
+          raise "Missing value for #{arg}" if arguments.empty?
+          value = arguments.shift
+          if key == 'pagesize'
+            value = value.to_i
+          end
+          @options[key.gsub('-', '_').to_sym] = value
+        when 'help'
+          print_help File.basename(command), DEFAULT_OPTIONS
+          return false
+        when 'config-stub'
+          print_config DEFAULT_OPTIONS
+          return false
+        else
+          raise "Missing value for #{arg}" if arguments.empty?
+          @parameters[key] = arguments.shift
+        end
+      end
+      
+      # Check existence of base URL
+      unless @options[:api_uri] && !@options[:api_uri].empty?
+        raise "Server API URL is missing. Specify with --api-uri parameter."
+      end
+      
+      # Check existence of a command
+      unless @parameters['command']
+        warn "No command specified. Use --command COMMAND to specify a remote command."
+      end
+      
+      # Check that auto paging is only used on list* commands
+      unless @parameters['command'] && @parameters['command'].downcase.start_with?("list")
+        @options[:auto_paging] = false
+        warn "Auto Paging disabled because command does not start with 'list'." if @options[:debug]
+      end
+      
+      # Set response format if specified
+      if @options[:response]
+        warn "Unknown response format #{@options[:response]}." unless ['xml', 'json'].include? @options[:response]
+        @parameters['response'] = @options[:response]
+      end
+      
+      # Login to CloudStack API
+      api = CloudStackClient::Connector.new({:api_uri => @options[:api_uri], :page_size => @options[:page_size], :ssl_check => !@options[:ignore_ssl]})
+      if @options[:api_key] && @options[:secret_key]
+        unless api.login_with_keys @options[:api_key], @options[:secret_key]
+          raise "Login using API key and secret key (--api-key KEY --secret-key SECRET) failed."
+        end
+      elsif @options[:username] && @options[:password]
+        unless api.login @options[:username], @options[:password], @options[:domain] 
+          raise "Login using username and password failed."
+        end
+      else
+        warn "No credentials specified." if @options[:debug]
+      end
+      
+      # Execute query
+      warn "Parameters:\n#{@parameters.inspect}\n" if @options[:debug]
+      if @options[:auto_paging]
+        output = api.query_all_pages @parameters
+      else
+        output = api.query @parameters
+      end
+      
+      # Verify result
+      errorcode = nil
+      message = "Unrecognizable Result"
+      unless CloudStackClient::API::response_is_success? output
+        case CloudStackClient::API::response_format(output)
+        when :xml
+          errorcode = REXML::XPath.first(output.root, "//errorcode").text.to_i
+          message = REXML::XPath.first(output.root, "//errortext").text
+        when :json
+          errorcode = output.first[1]["errorcode"]
+          message = output.first[1]["errortext"]
+        else
+          message = "Unknown format #{CloudStackClient::API::response_format(output)}"
+        end
+        warn "Error #{errorcode} occured: #{message}\n"
+      end
+      
+      # Output result
+      if not @options[:output]
+        # If no output is specified show formatted result on STDOUT
+        case CloudStackClient::API::response_format(output)
+        when :xml
+          puts "XML Response:"
+          puts output
+        when :json
+          puts "JSON Response:"
+          puts output.to_yaml
+        else
+          warn "Unknown format #{CloudStackClient::API::response_format(output)}" if @options[:debug]
+        end
+      elsif @options[:output] == '-'
+        # Pipe to STDOUT
+        STDOUT << output
+        puts # Fix missing newline
+      else
+        # Write to file
+        file = File.new(@options[:output], 'w')
+        file << output
+        file.close
+      end
+      
+      !!errorcode
+    end
+    
+    private
+    
+    # Show help
+    def print_help(command, options)
+      puts "CloudStack API Commandline Interface (version #{CloudStackClient::VERSION})"
+      puts "Usage: #{command} [options]"
+      puts "Options:"
+      puts "\t--api-key api-key       Your unique API key"
+      puts "\t--secret-key secret-key Your secret signature key"
+      puts "\t--username              Your login username"
+      puts "\t--password              Your login password"
+      puts "\t--domain                Your login domain"
+      puts "\t--config yaml-file      A YAML configuration file"
+      puts "\t--api-uri url           The URL of the API. Example:"
+      puts "\t                        https://example.com/client/api"
+      puts "\t--response format       Specify eighter json or xml (default: #{options[:response]})"
+      puts "\t--output filename       Execute command and save the response"
+      puts "\t--[no-]auto-paging      Aggregate all output pages (default: #{options[:auto_paging] ? "on" : "off"})"
+      puts "\t--pagesize num          Server's maximum page size (default: #{options[:page_size]})"
+      puts "\t--ignore-ssl            Ignore SSL certificate errors"
+      puts "\t--debug                 Additional output"
+      puts "\t--config-stub           Prints a skeleton for the configuration file"  
+      puts "\t--help                  This help"
+      puts
+      puts "Any API parameter can be passed as additional parameter:"
+      puts "\t--parameter value       Adds 'parameter=value' to the query"
+      puts
+      puts "You can authenticate wit secret and API keys or using username, password and domain."
+      puts
+      puts "Examples:"
+      puts "#{command} --api-uri https://example.com/client/api \\"
+      puts "\t--api-key mYaPiKeY --secret-key MySeCrEt --command listTemplates \\"
+      puts "\t--templatefilter executable"
+      puts "#{command} --api-uri http://example.com/api --username Me --password \\"
+      puts "\tMyPass --domain My/Domain --command deployVirtualMachine --zoneid 123 \\"
+      puts "\t--serviceofferingid 234 --templateid 456"
+      puts "#{command} --config credentials.yml --command queryAsyncJobResult \\"
+      puts "\t--jobid 567"
+      puts "#{command} --config credentials.yml --command createPortForwardingRule \\"
+      puts "\t--ipaddressid 678 --protocol TCP --publicport 443 --privateport 443 \\"
+      puts "\t--virtualmachineid 789"
+    end
+    
+    # Print config file skeleton
+    def print_config(options)
+      puts <<-YAML
+# Specify default options for cloud-stack.rb.
+#
+# CloudStack Authentiction can eighter be API key and Secret key or username, 
+# password and domain.
+# 
+# api_uri is the URL of the API e.g. https://www.example.com/client/api
+# 
+# The supported response formats are json and xml.
+
+default:
+  api_uri: 
+  api_key: 
+  secret_key: 
+  username: 
+  password: 
+  domain: 
+  # response: xml
+  # debug: true
+  # auto_paging: false
+  # page_size: 100
+      YAML
+    end
+  end
+end