shu-san-scripts 0.2.2 → 0.2.3

data/lib/SANStore/cri/command.rb

@@ -0,0 +1,104 @@
+module Cri
+
+  # Cri::Command represents a command that can be executed on the commandline.
+  # It is an abstract superclass for all commands.
+  class Command
+
+    attr_accessor :base
+
+    # Returns a string containing the name of thi command. Subclasses must
+    # implement this method.
+    def name
+      raise NotImplementedError.new("Command subclasses should override #name")
+    end
+
+    # Returns an array of strings containing the aliases for this command.
+    # Subclasses must implement this method.
+    def aliases
+      raise NotImplementedError.new("Command subclasses should override #aliases")
+    end
+
+    # Returns a string containing this command's short description, which
+    # should not be longer than 50 characters. Subclasses must implement this
+    # method.
+    def short_desc
+      raise NotImplementedError.new("Command subclasses should override #short_desc")
+    end
+
+    # Returns a string containing this command's complete description, which
+    # should explain what this command does and how it works in detail.
+    # Subclasses must implement this method.
+    def long_desc
+      raise NotImplementedError.new("Command subclasses should override #long_desc")
+    end
+
+    # Returns a string containing this command's usage. Subclasses must
+    # implement this method.
+    def usage
+      raise NotImplementedError.new("Command subclasses should override #usage")
+    end
+
+    # Returns an array containing this command's option definitions. See the
+    # documentation for Cri::OptionParser for details on what option
+    # definitions look like. Subclasses may implement this method if the
+    # command has options.
+    def option_definitions
+      []
+    end
+
+    # Executes the command. Subclasses must implement this method
+    # (obviously... what's the point of a command that can't be run?).
+    #
+    # +options+:: A hash containing the parsed commandline options. For
+    #             example, '--foo=bar' will be converted into { :foo => 'bar'
+    #             }. See the Cri::OptionParser documentation for details.
+    #
+    # +arguments+:: An array of strings representing the commandline arguments
+    #               given to this command.
+    def run(options, arguments)
+      raise NotImplementedError.new("Command subclasses should override #run")
+    end
+
+    # Returns the help text for this command.
+    def help
+      text = ''
+
+      # Append usage
+      text << usage + "\n"
+
+      # Append aliases
+      unless aliases.empty?
+        text << "\n"
+        text << "aliases: #{aliases.join(' ')}\n"
+      end
+
+      # Append short description
+      text << "\n"
+      text << short_desc + "\n"
+
+      # Append long description
+      text << "\n"
+      text << long_desc.wrap_and_indent(78, 4) + "\n"
+
+      # Append options
+      unless option_definitions.empty?
+        text << "\n"
+        text << "options:\n"
+        text << "\n"
+        option_definitions.sort { |x,y| x[:long] <=> y[:long] }.each do |opt_def|
+          text << sprintf("    -%1s --%-10s %s\n\n", opt_def[:short], opt_def[:long], opt_def[:desc].wrap_and_indent(78, 20).lstrip)
+        end
+      end
+
+      # Return text
+      text
+    end
+
+    # Compares this command's name to the other given command's name.
+    def <=>(other)
+      self.name <=> other.name
+    end
+
+  end
+
+end

data/lib/SANStore/cri/core_ext.rb

@@ -0,0 +1,8 @@
+module Cri::CoreExtensions
+end
+
+require 'SANStore/cri/core_ext/string'
+
+class String
+  include Cri::CoreExtensions::String
+end

data/lib/SANStore/cri/core_ext/string.rb

@@ -0,0 +1,41 @@
+module Cri::CoreExtensions
+
+  module String
+
+    # Word-wraps and indents the string.
+    #
+    # +width+:: The maximal width of each line. This also includes indentation,
+    #           i.e. the actual maximal width of the text is width-indentation.
+    #
+    # +indentation+:: The number of spaces to indent each wrapped line.
+    def wrap_and_indent(width, indentation)
+      # Split into paragraphs
+      paragraphs = self.split("\n").map { |p| p.strip }.reject { |p| p == '' }
+
+      # Wrap and indent each paragraph
+      paragraphs.map do |paragraph|
+        # Initialize
+        lines = []
+        line = ''
+
+        # Split into words
+        paragraph.split(/\s/).each do |word|
+          # Begin new line if it's too long
+          if (line + ' ' + word).length >= width
+            lines << line
+            line = ''
+          end
+
+          # Add word to line
+          line += (line == '' ? '' : ' ' ) + word
+        end
+        lines << line
+
+        # Join lines
+        lines.map { |l| ' '*indentation + l }.join("\n")
+      end.join("\n\n")
+    end
+
+  end
+
+end

data/lib/SANStore/cri/option_parser.rb

@@ -0,0 +1,186 @@
+module Cri
+
+  # Cri::OptionParser is used for parsing commandline options.
+  class OptionParser
+
+    # Error that will be raised when an unknown option is encountered.
+    class IllegalOptionError < RuntimeError ; end
+
+    # Error that will be raised when an option without argument is
+    # encountered.
+    class OptionRequiresAnArgumentError < RuntimeError ; end
+
+    # Parses the commandline arguments in +arguments_and_options+, using the
+    # commandline option definitions in +definitions+.
+    #
+    # +arguments_and_options+ is an array of commandline arguments and
+    # options. This will usually be +ARGV+.
+    #
+    # +definitions+ contains a list of hashes defining which options are
+    # allowed and how they will be handled. Such a hash has three keys:
+    #
+    # :short:: The short name of the option, e.g. +a+. Do not include the '-'
+    #          prefix.
+    #
+    # :long:: The long name of the option, e.g. +all+. Do not include the '--'
+    #         prefix.
+    #
+    # :argument:: Whether this option's argument is required (:required),
+    #             optional (:optional) or forbidden (:forbidden).
+    #
+    # A sample array of definition hashes could look like this:
+    #
+    #     [
+    #       { :short => 'a', :long => 'all',  :argument => :forbidden },
+    #       { :short => 'p', :long => 'port', :argument => :required  },
+    #     ]
+    #
+    # During parsing, two errors can be raised:
+    #
+    # IllegalOptionError:: An unrecognised option was encountered, i.e. an
+    #                      option that is not present in the list of option
+    #                      definitions.
+    #
+    # OptionRequiresAnArgumentError:: An option was found that did not have a
+    #                                 value, even though this value was
+    #                                 required.
+    #
+    # What will be returned, is a hash with two keys, :arguments and :options.
+    # The :arguments value contains a list of arguments, and the :options
+    # value contains a hash with key-value pairs for each option. Options
+    # without values will have a +nil+ value instead.
+    #
+    # For example, the following commandline options (which should not be
+    # passed as a string, but as an array of strings):
+    #
+    #     foo -xyz -a hiss -s -m please --level 50 --father=ani -n luke squeak
+    #
+    # with the following option definitions:
+    #
+    #     [
+    #       { :short => 'x', :long => 'xxx',    :argument => :forbidden },
+    #       { :short => 'y', :long => 'yyy',    :argument => :forbidden },
+    #       { :short => 'z', :long => 'zzz',    :argument => :forbidden },
+    #       { :short => 'a', :long => 'all',    :argument => :forbidden },
+    #       { :short => 's', :long => 'stuff',  :argument => :optional  },
+    #       { :short => 'm', :long => 'more',   :argument => :optional  },
+    #       { :short => 'l', :long => 'level',  :argument => :required  },
+    #       { :short => 'f', :long => 'father', :argument => :required  },
+    #       { :short => 'n', :long => 'name',   :argument => :required  }
+    #     ]
+    #
+    # will be translated into:
+    #
+    #     {
+    #       :arguments => [ 'foo', 'hiss', 'squeak' ],
+    #       :options => {
+    #         :xxx    => true,
+    #         :yyy    => true,
+    #         :zzz    => true,
+    #         :all    => true,
+    #         :stuff  => true,
+    #         :more   => 'please',
+    #         :level  => '50',
+    #         :father => 'ani',
+    #         :name   => 'luke'
+    #       }
+    #     }
+    def self.parse(arguments_and_options, definitions)
+      # Don't touch original argument
+      unprocessed_arguments_and_options = arguments_and_options.dup
+
+      # Initialize
+      arguments = []
+      options   = {}
+
+      # Determines whether we've passed the '--' marker or not
+      no_more_options = false
+
+      loop do
+        # Get next item
+        e = unprocessed_arguments_and_options.shift
+        break if e.nil?
+
+        # Handle end-of-options marker
+        if e == '--'
+          no_more_options = true
+        # Handle incomplete options
+        elsif e =~ /^--./ and !no_more_options
+          # Get option key, and option value if included
+          if e =~ /^--([^=]+)=(.+)$/
+            option_key   = $1
+            option_value = $2
+          else
+            option_key    = e[2..-1]
+            option_value  = nil
+          end
+
+          # Find definition
+          definition = definitions.find { |d| d[:long] == option_key }
+          raise IllegalOptionError.new(option_key) if definition.nil?
+
+          if [ :required, :optional ].include?(definition[:argument])
+            # Get option value if necessary
+            if option_value.nil?
+              option_value = unprocessed_arguments_and_options.shift
+              if option_value.nil? || option_value =~ /^-/
+                if definition[:argument] == :required
+                  raise OptionRequiresAnArgumentError.new(option_key)
+                else
+                  unprocessed_arguments_and_options.unshift(option_value)
+                  option_value = true
+                end
+              end
+            end
+
+            # Store option
+            options[definition[:long].to_sym] = option_value
+          else
+            # Store option
+            options[definition[:long].to_sym] = true
+          end
+        # Handle -xyz options
+        elsif e =~ /^-./ and !no_more_options
+          # Get option keys
+          option_keys = e[1..-1].scan(/./)
+
+          # For each key
+          option_keys.each do |option_key|
+            # Find definition
+            definition = definitions.find { |d| d[:short] == option_key }
+            raise IllegalOptionError.new(option_key) if definition.nil?
+
+            if option_keys.length > 1 and definition[:argument] == :required
+              # This is a combined option and it requires an argument, so complain
+              raise OptionRequiresAnArgumentError.new(option_key)
+            elsif [ :required, :optional ].include?(definition[:argument])
+              # Get option value
+              option_value = unprocessed_arguments_and_options.shift
+              if option_value.nil? || option_value =~ /^-/
+                if definition[:argument] == :required
+                  raise OptionRequiresAnArgumentError.new(option_key)
+                else
+                  unprocessed_arguments_and_options.unshift(option_value)
+                  option_value = true
+                end
+              end
+
+              # Store option
+              options[definition[:long].to_sym] = option_value
+            else
+              # Store option
+              options[definition[:long].to_sym] = true
+            end
+          end
+        # Handle normal arguments
+        else
+          arguments << e
+        end
+      end
+
+      { :options => options, :arguments => arguments }
+    end
+
+  end
+
+end

data/lib/SANStore/helpers/uuid.rb

@@ -0,0 +1,35 @@
+# Copyright (c) 2010-2011 David Love
+#
+# Permission to use, copy, modify, and/or distribute this software for 
+# any purpose with or without fee is hereby granted, provided that the 
+# above copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+#
+
+# @author David Love
+
+require "uuidtools"
+
+# Extendes the {UUIDTools::UUID} class, adding the ability to
+# generate sequential UUID's
+class UUIDTools::UUID
+  
+  # Increments the internal UUID representation, returning a
+  # new UUID that is different from, but greater, than the 
+  # current sequence number
+  def next
+    next_uuid = self.to_i
+    next_uuid += 1
+    
+    # Return the newly created UUID
+    return UUIDTools::UUID::parse_int(next_uuid)
+  end
+  
+end

data/lib/SANStore/iSCSI/comstar.rb

@@ -0,0 +1,239 @@
+# Copyright (c) 2010-2011 David Love
+#
+# Permission to use, copy, modify, and/or distribute this software for 
+# any purpose with or without fee is hereby granted, provided that the 
+# above copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+#
+
+# @author David Love
+
+# Defines a class capable of creating iSCSI shares using the new
+# COMStar framework. This classes uses the various command line tools, 
+# not the C API.
+class COMStar
+  
+  # Create a new, ready to use, iSCSI target. Functionally this is command
+  # is equivalent to the old "shareiscsi=on" ZFS volume property.
+  def self.new_target(volume_path, volume_guid)
+    
+    # Create a new disk target for the ZFS volume
+    SANStore::CLI::Logger.instance.log_level(:low, :create, "New SCSI block device at /dev/zvol/rdsk/#{volume_path}")
+    disk_target = %x[sbdadm create-lu /dev/zvol/rdsk/#{volume_path}]
+
+    # Get the ID of the new disk target from the output of the
+    # target creation command
+    id = disk_target.split(/$/)[4].split[0]
+    SANStore::CLI::Logger.instance.log_level(:low, :info, "Using #{id} as the logical unit identifier")
+   
+    # Modify the just created logical unit to include the path of the
+    # volume backing it. This makes it much easier to get rid of the
+    # relevant volume later
+    SANStore::CLI::Logger.instance.log_level(:low, :update, "Storing the volume GUID as the logical unit alias")
+    modify_lu = %x[stmfadm modify-lu --lu-prop alias=#{volume_guid} #{id}]
+
+    # Link the new disk target to the iSCSI framework
+    SANStore::CLI::Logger.instance.log_level(:low, :update, "Attaching logical unit #{id} into the iSCSI framework")
+    vol_frame = %x[stmfadm add-view #{id}]
+
+    # Create the target...
+    SANStore::CLI::Logger.instance.log_level(:low, :create, "iSCSI block target")
+    target = %x[itadm create-target]
+    target_name = target.split[1]
+    
+    # Store the volume GUID as the alias so we can find it later
+    SANStore::CLI::Logger.instance.log_level(:low, :update, "Storing the volume GUID as the iSCSI target alias")
+    %x[itadm modify-target --alias #{volume_guid} #{target_name}]
+    
+    # Return the target name to the caller
+    return target_name
+  end
+  
+  # Delete an iSCSI target. This returns the name of the underlying ZFS store in case the
+  # caller wants to delete that as well
+  def self.delete_target(target_name)
+    
+    # Before we kill the target, get the store GUID so that we can clean up properly
+    target_map = self.TargetToGUIDMap
+    target_guid = target_map[target_name]
+    
+    # Get the maps of the LU identifers to the underlying stores
+    vol_map = self.LUToVolMap
+    
+    # Look for the store with the GUID of the target we want to delete
+    SANStore::CLI::Logger.instance.log_level(:low, :info, "Looking for the name of the volume #{target_guid} backing #{target_name}")
+    vol_name = ""
+    vol_store = ""
+    vol_map.each{|key, value|
+      if value[:guid] == target_guid then
+        # We have found the right entry, so update the name of the
+        # volume store and the name of the volume backing it
+        vol_name = key
+        vol_store = value[:data_file]
+        break
+      end
+    }
+    
+    # Abort if we can't find what we are looking for
+    if vol_name.empty? or vol_store.empty? then
+      SANStore::CLI::Logger.instance.log_level(:high, :error, "Could not delete the file system for the iSCSI target. The target has been removed, but the file system is still around!")
+      return ""
+    end
+    
+    # Delete the target (and force any clients off the soon to die share)
+    SANStore::CLI::Logger.instance.log_level(:low, :warning, "Closing all sessions for #{target_name}")
+    target = %x[itadm delete-target -f #{target_name}]
+    
+    # Now unlink the SCSI logical unit, so that we can free the underlying ZFS volume
+    SANStore::CLI::Logger.instance.log_level(:low, :delete, "Removing logical units associated with the deleted target")
+    disk_target = %x[sbdadm delete-lu #{vol_name}]
+    
+    # The file store is now ready for deletion. We will tell the caller what to remove, but we
+    # don't actually do this ourselves (file systems are someone elses problem)
+    return vol_store
+  end
+  
+  # List the current iSCSI targets defined on this host
+  def self.list_vols
+    raw_list = %x[itadm list-target]
+    
+    # Create a hash for the final list of targets
+    target_list = Array.new
+    
+    # Run through the raw list of targets
+    target_array = raw_list.split(/$/)
+    target_array.delete_at(0)
+    
+    target_array.each{|row|
+      row_fragments = row.split
+      row_hash = Hash.new
+      
+      row_hash[:name] = row_fragments[0]
+      row_hash[:state] = row_fragments[1]
+      row_hash[:sessions] = row_fragments[2]
+     
+      target_list << row_hash
+    }
+    
+    # return the list to the caller
+    return target_list
+  end
+  
+  # Walks over the list of iSCSI targets, looking for the store GUID (stored in the target alias field). 
+  # Returns a map of the target names and associated aliases
+  def self.TargetToGUIDMap
+    
+    # Get the raw map
+    SANStore::CLI::Logger.instance.log_level(:low, :info, "Finding the GUID's associated with iSCSI targets")
+    raw_list = %x[stmfadm list-target -v]
+    raw_map = raw_list.split(/$/)
+    
+    # Create a hash from this map
+    map_hash = Hash.new
+    map_index = nil
+    map_entry = nil
+    raw_index = 0
+    
+    while raw_index < raw_map.length do
+      # Is this line the start of a new target entry
+      if raw_map[raw_index].index(/Target\:/) then
+        
+        # Store the old entry
+        unless map_entry.nil? then
+          map_hash[map_index] = map_entry
+        end
+        
+        # Create a new map entry
+        map_entry = String.new        
+        map_index = raw_map[raw_index].partition(/Target\:/)[2].strip
+        
+      else
+        
+        # Split the line to find the key and value
+        entry = raw_map[raw_index].partition(/\s?\:\s/)
+        
+        case entry[0].strip
+          when "Alias"
+            map_entry = entry[2].strip
+        end
+        
+      end
+
+      raw_index += 1
+    end
+
+    # Add the last entry
+    unless map_entry.nil? then
+      map_hash[map_index] = map_entry
+    end
+    
+    # Return the hash map
+    return map_hash
+  
+  end
+  
+  # Walks over the list of Logical Units, working out where the ZFS volume
+  # backing the LU is. Returns a hash, giving the correct backing store for
+  # each LU
+  def self.LUToVolMap
+    
+    # Get the raw map
+    SANStore::CLI::Logger.instance.log_level(:low, :info, "Finding the backing stores for the logical units")
+    raw_list = %x[stmfadm list-lu -v]
+    raw_map = raw_list.split(/$/)
+    
+    # Create a hash from this map
+    map_hash = Hash.new
+    map_index = nil
+    map_entry = nil
+    raw_index = 0
+    
+    while raw_index < raw_map.length do
+      # Is this line the start of a new LU entry
+      if raw_map[raw_index].index(/LU Name\:/) then
+        
+        # Store the old entry
+        unless map_entry.nil? then
+          map_hash[map_index] = map_entry
+        end
+        
+        # Create a new map entry
+        map_entry = Hash.new        
+        map_index = raw_map[raw_index].partition(/LU Name\:/)[2].strip
+        
+      else
+        
+        # Split the line to find the key and value
+        entry = raw_map[raw_index].partition(/\s?\:\s/)
+        
+        case entry[0].strip
+          when "Alias"
+            map_entry[:guid] = entry[2].strip
+          when "Data File"
+            map_entry[:data_file] = entry[2].strip
+        end
+        
+      end
+
+      raw_index += 1
+    end
+    
+    # Add the last entry
+    unless map_entry.nil? then
+      map_hash[map_index] = map_entry
+    end
+    
+    # Return the hash map
+    return map_hash
+  
+  end
+  
+end
+