shu-san-scripts 0.2.0 → 0.2.1

data/README.rdoc

@@ -1,9 +1,9 @@
 = SHU SAN Scripts
 
-Together these scripts define a +store+ command, used to simplify the
-task of creating iSCSI targets on OpenSolaris (Solaris > 11) based
-hosts. It has been tested on Nexenta NCP and Open Indiana, but with some
-modification it could be made to work on FreeBSD as well. 
+Together these scripts define a +store+ command, used to simplify the task of
+creating, deleting and managing iSCSI targets on OpenSolaris (Solaris > 11) 
+based hosts. It has been tested on Nexenta NCP and Open Indiana, but with 
+some modification it could be made to work on FreeBSD as well.
 
 The user interface is deliberately as simple as possible: we assume the
 user has no underlying knowledge of (Open)Solaris, ZFS and not all that
@@ -47,7 +47,9 @@ arguments
 
   Available commands:
 
+      delete_vol           Remove the specified target from the iSCSI volume store.
       help                 Show help for a command
+      list_vols            Show the currently defined iSCSI targets on this host.
       new_vol              Create a new iSCSI volume in the SAN volume store.
 
   Global options:

data/lib/SANStore.rb

@@ -0,0 +1,24 @@
+### Copyright (c) 2010, 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.
+###
+
+module SANStore
+
+  ## Define Application Global constants
+
+  # The current SANStore client version.
+  VERSION = '0.1'
+
+end
+

data/lib/SANStore/cli.rb

@@ -0,0 +1,29 @@
+### Copyright (c) 2009 Denis Defreyne, 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.
+###
+
+require 'rubygems'
+
+# Load command line handling library
+require 'cri'
+
+# Install module for command line
+# interface
+module SANStore:CLI
+end
+
+# Load the command line handling modules
+require 'SANStore/cli/logger'
+require 'SANStore/cli/commands'
+require 'SANStore/cli/base'

data/lib/SANStore/cli/base.rb

@@ -0,0 +1,103 @@
+# Copyright (c) 2009 Denis Defreyne, 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 Denis Defreyne
+# @author David Love
+#
+# The +CLI+ module acts as the gathering place for all the gloabl options
+# and the sub-commands which the +SANStore+ command can deal with. 
+# Sub-commands are themselves defined in the {SANStore::CLI::Commands} 
+# module 
+module SANStore::CLI
+
+  # @author Denis Defreyne
+  # @author David Love
+  #
+  # Details the global options applicable to all commands, and the code necessary
+  # to process those options. Each sub-command also needs to be registered with 
+  # this class for it to work: strange things will happen if the sub-command is
+  # not set-up here!
+  #
+  # When creating a new sub-command, the constructor for that sub-command needs
+  # to be added to the {Base#initialize} function of *this* class as well. Be sure to 
+  # also add the path to the file where the sub-command is defined to the file 
+  # +lib/SANStore/cli/commands.rb+, otherwise you will get warnings of unknown
+  # classes.
+  class Base < Cri::Base
+
+    # Instantiates the sub-commands by creating a single reference to each
+    # known sub-command.
+    # 
+    # @note This means that if your sub-command is not in this constructor
+    #   it *will not* be found, and *will not* appear as a valid sub-command.
+    #   If something is missing from the 'help' command, check this method! 
+    def initialize
+      super('SANStore')
+
+      # Add help command
+      self.help_command = SANStore::CLI::Commands::Help.new
+      add_command(self.help_command)
+
+      # Add other commands
+      add_command(SANStore::CLI::Commands::DeleteVol.new)
+      add_command(SANStore::CLI::Commands::ListVols.new)
+      add_command(SANStore::CLI::Commands::NewVol.new)
+    end
+
+    # Returns the list of global option definitionss.
+    def global_option_definitions
+      [
+        {
+          :long => 'help', :short => 'h', :argument => :forbidden,
+          :desc => 'show this help message and quit'
+        },
+        {
+          :long => 'no-color', :short => 'C', :argument => :forbidden,
+          :desc => 'disable color'
+        },
+        {
+          :long => 'version', :short => 'v', :argument => :forbidden,
+          :desc => 'show version information and quit'
+        },
+        {
+          :long => 'verbose', :short => 'V', :argument => :forbidden,
+          :desc => 'make store command output more detailed'
+        }
+      ]
+    end
+
+    # Process the global options, and set/change the application state from them
+    def handle_option(option)
+      # Handle version option
+      if option == :version
+        puts "SANStore Bootstrap Client #{SANStore::VERSION} (c) 2011 David Love."
+        puts "Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) running on #{RUBY_PLATFORM}"
+        exit 0
+      # Handle verbose option
+      elsif option == :verbose
+        SANStore::CLI::Logger.instance.level = :low
+      # Handle no-color option
+      elsif option == :'no-color'
+        SANStore::CLI::Logger.instance.color = false
+      # Handle help option
+      elsif option == :help
+        show_help
+        exit 0
+      end
+    end
+
+  end
+
+end

data/lib/SANStore/cli/commands.rb

@@ -0,0 +1,31 @@
+# Copyright (c) 2009 Denis Defreyne, 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
+#
+# The +Commands+ module acts as the gathering place for all the sub-commands 
+# which the +store+ command can deal with. Each sub-command defines both 
+# the command action, options, and associated help text.
+#
+# All commands should live under +lib/SANStore/cli/commands+, with the 
+# file-name named after the sub-command defined within it. 
+
+module SANStore::CLI::Commands
+end
+
+require 'SANStore/cli/commands/help'
+
+require 'SANStore/cli/commands/delete_vol'
+require 'SANStore/cli/commands/list_vols'
+require 'SANStore/cli/commands/new_vol'

data/lib/SANStore/cli/commands/delete_vol.rb

@@ -0,0 +1,113 @@
+# Copyright (c) 2009 Denis Defreyne, 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.
+
+# Volume names are based on RFC 4122 UUIDs
+require "uuidtools"
+
+# Use the ANSI library to report the status to the user
+require "ansi/code"
+
+# Use the ZFS library
+require "SANStore/zfs/zfs"
+
+# Use the COMStar iSCSI library
+require "SANStore/iSCSI/comstar.rb"
+
+module SANStore::CLI::Commands
+
+  # @author David Love
+  #
+  # The +new_vol+ command adds a new ZFS volume to the specified volume
+  # store, and sets it up as an iSCSI target. Defaults are supplied to
+  # all arguments, but can be overridden by the user for slightly
+  # customised set-up of the volume store. However, the user interface
+  # should be kept as simple as possible. 
+  class DeleteVol < Cri::Command
+
+    # The name of the sub-command (as it appears in the command line app)
+    def name
+      'delete_vol'
+    end
+
+    # The aliases this sub-command is known by
+    def aliases
+      [
+        "rm", "delete", "rm_vol"
+      ]
+    end
+
+    # A short help text describing the purpose of this command
+    def short_desc
+      'Remove the specified target from the iSCSI volume store.'
+    end
+
+    # A longer description, detailing both the purpose and the
+    # use of this command
+    def long_desc
+      'This command deletes the specified target from the pool, and ' +
+      'unlinks the volume store backing the target. Since the underlying ' +
+      'volume store is destroyed, this action is ' + ANSI.bold{ "irreversible" } +
+      'and so this command should be used with ' + ANSI.bold{ "great" } + 'care.' +
+      "\n\n" +
+      'NOTE: Any clients attached to the volume will have their ' +
+      'iSCSI session forcibly closed. This may result in the premature ' +
+      'death of the client if care is not taken.'
+    end
+
+    # Show the user the basic syntax of this command
+    def usage
+      "store delete_vol SHARE_NAME"
+    end
+    
+    # Define the options for this command
+    def option_definitions
+      [
+        { :short => 'v', :long => 'volume_store', :argument => :optional,
+          :desc => 'specifify the ZFS root of the new iSCSI volume. Defaults to "store/volumes".'
+        },
+        { :short => 'n', :long => 'name', :argument => :optional,
+          :desc => 'the name of the new volume. This must be a valid ZFS volume name, and defaults to ' +
+            'an RFC 4122 GUID.'
+        },
+        { :short => 's', :long => 'size', :argument => :optional,
+          :desc => 'the size of the new iSCSI volume. Note that while ZFS allows you to change the size ' +
+            'of the new volume relatively easily, because the iSCSI initiator sees this volume as a raw ' +
+            'device changing the size later may be very easy or very difficult depending on the initiators ' +
+            'operating system (and the specific file system being used). In other words, choose with care: ' +
+            'by default this command uses a size of 20G, which should be enough for most tasks in the labs.'  
+        },
+      ]
+    end
+
+    # Execute the command
+    def run(options, arguments)
+
+      # Check that we have been given a name
+      if arguments.size > 1
+        SANStore::CLI::Logger.instance.log_level(:high, :error, "You must specify the name of the target to remove")
+        exit 1
+      end
+
+      # Delete the iSCSI target
+      SANStore::CLI::Logger.instance.log_level(:high, :delete, "Removing target #{arguments[0]}")
+      zfs_volume = COMStar.delete_target(arguments[0])
+      
+      # Remove the underlying ZFS store
+      SANStore::CLI::Logger.instance.log_level(:low, :delete, "Removing ZFS store for #{arguments[0]}")
+      ZFS.delete_volume(zfs_volume)    
+    end
+
+  end
+
+end

data/lib/SANStore/cli/commands/help.rb

@@ -0,0 +1,106 @@
+### Copyright (c) 2009 Denis Defreyne, 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.
+###
+
+module SANStore::CLI::Commands
+
+  # @author Denis Defreyne
+  # @author David Love
+  #
+  # The +help+ command show the user a brief summary of the available
+  # sub-commands, and the short description of each of those commands.
+  #
+  # Further help is available to the user, if one of the sub-commands
+  # is named as an argument to this command. In that case, the longer
+  # help for the command is displayed.
+  #
+  # @note This class is merely a helper class: the actual text, options
+  #   and other details are drawn directly from the source code of those
+  #   commands. In the execution of this command, we rely on the +cri+
+  #   and +cli+ libraries to do the hard work of actually processing the
+  #   sub-commands.
+  class Help < Cri::Command
+
+    # The name of the sub-command (as it appears in the command line app)
+    def name
+      'help'
+    end
+
+    # The aliases this sub-command is known by
+    def aliases
+      []
+    end
+
+    # A short help text describing the purpose of this command
+    def short_desc
+      'Show help for a command'
+    end
+
+    # A longer description, detailing both the purpose and the
+    # use of this command
+    def long_desc
+      'Show help for the given command, or show general help. When no ' +
+      'command is given, a list of available commands is displayed, as ' +
+      'well as a list of global command-line options. When a command is ' +
+      'given, a command description as well as command-specific ' +
+      'command-line options are shown.'
+    end
+
+    # Show the user the basic syntax of this command
+    def usage
+      "store help [command]"
+    end
+
+    # Execute the command
+    def run(options, arguments)
+      # Check arguments
+      if arguments.size > 1
+        $stderr.puts "usage: #{usage}"
+        exit 1
+      end
+
+      if arguments.length == 0
+        # Build help text
+        text = ''
+
+        # Add title
+        text << "A command-line tool for managing iSCSI targets on OpenSolaris.\n"
+
+        # Add available commands
+        text << "\n"
+        text << "Available commands:\n"
+        text << "\n"
+        @base.commands.sort.each do |command|
+          text << sprintf("    %-20s %s\n", command.name, command.short_desc)
+        end
+
+        # Add global options
+        text << "\n"
+        text << "Global options:\n"
+        text << "\n"
+        @base.global_option_definitions.sort { |x,y| x[:long] <=> y[:long] }.each do |opt_def|
+          text << sprintf("    -%1s --%-15s %s\n", opt_def[:short], opt_def[:long], opt_def[:desc])
+        end
+
+        # Display text
+        puts text
+      elsif arguments.length == 1
+        command = @base.command_named(arguments[0])
+        puts command.help
+      end
+    end
+
+  end
+
+end

data/lib/SANStore/cli/commands/list_vols.rb

@@ -0,0 +1,103 @@
+# Copyright (c) 2009 Denis Defreyne, 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.
+
+# Volume names are based on RFC 4122 UUIDs
+require "uuidtools"
+
+# Use the ZFS library
+require "SANStore/zfs/zfs"
+
+# Use the COMStar iSCSI library
+require "SANStore/iSCSI/comstar.rb"
+
+module SANStore::CLI::Commands
+
+  # @author David Love
+  #
+  # The +list_vols+ command show the current iSCSI targets available
+  # on this host 
+  class ListVols < Cri::Command
+
+    # The name of the sub-command (as it appears in the command line app)
+    def name
+      'list_vols'
+    end
+
+    # The aliases this sub-command is known by
+    def aliases
+      [
+        "list_vol", "list", "ls"
+      ]
+    end
+
+    # A short help text describing the purpose of this command
+    def short_desc
+      'Show the currently defined iSCSI targets on this host.'
+    end
+
+    # A longer description, detailing both the purpose and the
+    # use of this command
+    def long_desc
+      'Displays a list of valid iSCSI targets, all of which ' +
+      'should be available on the local network' + "\n\n"
+      'NOTE: Because of the way iSCSI works, this host has no ' +
+      'way of knowing what is actually '+ ANSI.bold{ "in" } + ' the volume. So even ' +
+      'if a target is defined, this host has no way of knowing if ' +
+      'a given initiator can actually ' + ANSI.bold{ "use" } +
+      'the contents of this volume. If something appears to be '
+      'wrong, check the set-up of the host to make sure it can '
+      'actually connect to the targets defined here.' 
+    end
+
+    # Show the user the basic syntax of this command
+    def usage
+      "store list_vols"
+    end
+    
+    # Define the options for this command
+    def option_definitions
+      [
+      ]
+    end
+
+    # Execute the command
+    def run(options, arguments)
+
+      # Get the list of defined volumes
+      volumes = COMStar.list_vols
+      
+      # Show the list to the caller
+      text = String.new
+      volumes.each{|target|
+        text << sprintf("%-60s ", target[:name])
+        
+        if target[:state] == "online" then
+          text << sprintf("%-20s ", ANSI.green{ target[:state] })
+        else
+          text << sprintf("%-20s ", ANSI.black{ target[:state] })
+        end
+        
+        if target[:sessions].to_i > 0 then
+          text << sprintf("%-10s\n", ANSI.white{ target[:sessions] })
+        else
+          text << sprintf("%-10s\n", ANSI.black{ target[:sessions] })
+        end
+      }
+      puts sprintf("%-68s %-19s %-10s\n", ANSI.bold{ "Target Name"}, ANSI.bold{ "Status" }, ANSI.bold{ "Open Sessions" })
+      puts text
+    end
+
+  end
+
+end