brocadesan 0.4.0

data/README

@@ -0,0 +1,113 @@
+= BrocadeSAN
+
+== What is BrocadeSAN?
+
+BrocadeSAN provides a simple wrapper API to communicate with Brocade SAN switches using SSH connection.
+You have option to either run the command manualy or query the switch with pre-defined set of methods.
+
+Additionally you can use Brocade::SAN::Provisioning::Agent for zoning provisioning tasks.
+
+== Basic Usage
+
+You can use BrocadeSAN in 2 different ways:
+
+=== 1. Query the SAN switch directly using 1 connection per command query 
+
+  # this will query the switch name and version and open connection to switch twice
+  
+  switch=Brocade::SAN::Switch.new("address","user","password")
+  
+  switch.name
+  switch.firmware
+  
+=== 2. Query the SAN switch in session block using 1 connection per session
+  
+  # this will query the switch name and version and open connection to switch only once
+  
+  switch=Brocade::SAN::Switch.new("address","user","password")
+  
+  switch.session do 
+	switch.name
+	switch.firmare
+  end
+  
+== Special Usage
+
+If the API is not sufficient for your need you can always utilize the Brocade::SAN::Switch#query method to execute arbitrary commands
+  
+  # sends command to switch
+  response=switch.query("portshow | grep Online ")
+  
+  # sends several commands to switch
+  response=switch.query("switchshow","cfgshow")
+  
+  # calls interactive command and sends response along the way
+  # the mode has to be set to interactive
+  # the mode will persist across queries
+  # change it back to :script when you want to run non-interactive command
+  switch.set_mode :interactive 
+  response=switch.query("cfgsave","y")
+  
+Response is type of Brocade::SAN::Switch::Response. You can get the data by calling +data+ and errors by calling +errors+.
+The data will be raw output from the switch with each cmd prefixed by defined/default prompt.
+
+== Provisioning
+
+This is wrapper API for provisioning tasks with added control. This wrapper expects some basic understanding of zoning provisioning tasks and should be used to build
+specialized provisioning clients.
+
+  # creates a agent, user must have provisioning rights
+  agent=Brocade::SAN::Provisoning::Agent.create("address","user","password")
+  
+  # create a zone instance with aliases
+  zone = Brocade::SAN::Zone.new("host_array_zone")
+  zone.add_member "host_alias"
+  zone.add_member "array_alias"
+  
+  # gets effecive configuration (false gets name only without members)
+  cfg=agent.effective_configuration(false)
+  
+  # creates zone and adds it to the configuration in transaction
+  # transaction saves configuration at the end, it does not enable effective configuration
+  # agent methods outside of transaction will save configuration immediately
+  agent.transaction do
+  	agent.zone_create zone
+  	agent.cfg_add cfg, zone
+  end
+  
+  # enable effective configuration
+  agent.cfg_enable cfg
+  
+== Download and Installation
+
+Installation *with* RubyGems:
+  # gem install brocadesan
+    
+== Author
+
+Written 2015 by Tomas Trnecka <mailto:trnecka@gmail.com>.
+
+== License
+
+Copyright (c) 2015 Tomas Trnecka
+
+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:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rake/testtask'
+require 'rake/notes/rake_task'
+require 'rdoc/task'
+require 'yaml'
+
+  Rake::TestTask.new do |t|
+    t.libs = ["lib","test"]
+    t.warning = false
+    t.verbose = true
+    t.test_files = FileList['test/**/*_test.rb']
+  end
+ 
+  Rake::RDocTask.new do |rd|
+    rd.main = "README"
+    rd.title    = "BrocadeSAN"
+    rd.rdoc_files.include("README","lib/**/*.rb")
+    
+    rd.before_running_rdoc do 
+      Rake::Task["generate_meta"].invoke
+    end
+  end
+  
+  task :generate_meta do
+    files=Dir.glob("lib/brocadesan/config/brocade/san/*cmd_mapping.yml")
+    doc=""
+    files.each do |file|
+      doc+="class Brocade::SAN::#{File.basename(file.gsub("_cmd_mapping.yml","")).split('_').map{|e| e.capitalize}.join}\n"
+      hash=YAML.load(File.read(file))
+      hash.each do |method,v|
+        doc+="##\n"
+        doc+="# :method: #{method.to_s}\n"
+        doc+="# :call-seq:\n"
+        doc+="#   #{method.to_s}(forced=true)\n"
+        doc+="#\n"
+        doc+="# If called with +true+ argument it will get the #{v[:attr]} from the switch instead of cache\n"
+        doc+="#\n"
+        doc+="# Returns value in (#{v[:format]}) format\n"
+        doc+="\n"
+      end
+      doc+="end\n"
+      File.open("lib/meta_methods.rb", 'w') {|f| f.write(doc) }
+    end
+  end
+
+desc "Run tests"
+task :default => :test

data/brocadesan.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name        = 'brocadesan'
+  s.version     = '0.4.0'
+  s.date        = '2015-02-05'
+  s.summary     = "Brocade SAN library"
+  s.description = "Gem to manipulate FABOS based devices"
+  s.authors     = ["Tomas Trnecka"]
+  s.email       = 'trnecka@gmail.com'
+  s.files       = `git ls-files`.split("\n") 
+  s.homepage    = 'http://rubygems.org/gems/brocadesan'
+  s.add_runtime_dependency "net-ssh", ">= 2.9.2"
+  s.add_development_dependency "minitest",[">= 5.0.0"]
+  s.add_development_dependency "rake-notes",[">= 0.2.0"]
+end

data/lib/brocadesan.rb

@@ -0,0 +1,8 @@
+require 'brocadesan/monkey/string'
+require 'brocadesan/device'
+require 'brocadesan/switch'
+require 'brocadesan/zone_configuration'
+require 'brocadesan/zone'
+require 'brocadesan/alias'
+require 'brocadesan/wwn'
+require 'brocadesan/provisioning'

data/lib/brocadesan/alias.rb

@@ -0,0 +1,64 @@
+module Brocade module SAN
+  
+# Alias model
+class Alias
+  # returns name of the alias
+  attr_reader :name
+  
+  # alias member naming rule (regular expresion)
+  #
+  # member can be WWN or Domain,Index port notation
+  #
+  # allowed examples:
+  #
+  # 50:00:10:20:30:40:50:60
+  #
+  # 2,61
+  
+  MEMBER_RULE='([\da-f]{2}:){7}[\da-f]{2}|\d{1,3},\d{1,3}'
+  
+  # inititialize new alias with +name+
+  #
+  # +opts+ reserved for future use
+  def initialize(name,opts={})
+    # checked against alias name rule - not alias member
+    Switch::verify_name(name)
+    @name=name 
+    @members=[]
+  end
+  
+  # returns array of members  
+  
+  def members
+    @members
+  end
+  
+  # add new member to the alias
+  #
+  # members of aliases are WWNs or Domain,Index port notation
+  #
+  # +member+ is name of the zone
+  #
+  # return all members, otherwises raises error
+  
+  def add_member(member)
+    Alias::verify_member_name(member)
+    @members<<member
+  end
+  
+  # verifies if +str+ matches convetion defined in Alias::MEMBER_RULE
+  #
+  # raises Switch::Error: Incorrect name format "+str+" if not
+  #
+  # this method is used mostly internally
+    
+  def self.verify_member_name(str)
+    raise Switch::Error.incorrect(str) if !str.match(/#{MEMBER_RULE}/i)
+  end
+  
+  def to_s
+    @name
+  end
+end
+
+end; end

data/lib/brocadesan/config/brocade/san/switch_cmd_mapping.yml

@@ -0,0 +1,116 @@
+:name: 
+    :cmd: switchshow
+    :attr: switch_name
+    :format: string
+:state: 
+    :cmd: switchshow
+    :attr: switch_state
+    :format: string
+:mode: 
+    :cmd: switchshow
+    :attr: switch_mode
+    :format: string
+:role: 
+    :cmd: switchshow
+    :attr: switch_role
+    :format: string
+:domain: 
+    :cmd: switchshow
+    :attr: switch_domain
+    :format: integer
+:id: 
+    :cmd: switchshow
+    :attr: switch_id
+    :format: string
+:wwn: 
+    :cmd: switchshow
+    :attr: switch_wwn
+    :format: string
+:zoning_enabled: 
+    :cmd: switchshow
+    :attr: zoning_enabled
+    :format: boolean
+:active_config: 
+    :cmd: switchshow
+    :attr: active_config
+    :format: string
+:switch_beacon: 
+    :cmd: switchshow
+    :attr: switch_beacon
+    :format: string
+:fc_router: 
+    :cmd: switchshow
+    :attr: fc_router
+    :format: string
+:allow_xisl_use: 
+    :cmd: switchshow
+    :attr: allow_xisl_use
+    :format: string
+:ls_attributes: 
+    :cmd: switchshow
+    :attr: ls_attributes
+    :format: string
+:kernel: 
+    :cmd: version
+    :attr: kernel  
+    :format: string  
+:firmware: 
+    :cmd: version
+    :attr: fabric_os
+    :format: string
+:logical_switches:
+    :cmd: "lscfg --show"
+    :attr: created_switches
+    :format: array
+:ports:
+    :cmd: "switchshow"
+    :attr: ports
+    :format: array
+:aptpolicy:
+    :cmd: "aptpolicy"
+    :attr: current_policy
+    :format: integer
+:chassisname:
+    :cmd: "chassisname"
+    :attr: chassisname
+    :format: string
+:dls:
+    :cmd: "dlsshow"
+    :attr: dlsshow
+    :format: string
+:iod:
+    :cmd: "iodshow"
+    :attr: iodshow
+    :format: string
+:status:
+    :cmd: "switchstatusshow"
+    :attr: switch_state
+    :format: string
+:status_details:
+    :cmd: "switchstatusshow"
+    :attr: switchstatusshow
+    :format: string
+:ip:
+    :cmd: "switchstatusshow"
+    :attr: ip_address
+    :format: string
+:supportshow:
+    :cmd: "supportshow"
+    :attr: supportshow
+    :format: string
+:isls:
+    :cmd: "islshow"
+    :attr: isl_links
+    :format: array
+:trunks:
+    :cmd: "trunkshow"
+    :attr: trunk_links
+    :format: array
+:access_gateways:
+    :cmd: "agshow"
+    :attr: ag
+    :format: array
+:cfg_transaction:
+    :cmd: "cfgtransshow"
+    :attr: cfg_transaction
+    :format: hash

data/lib/brocadesan/config/parser_mapping.yml

@@ -0,0 +1,21 @@
+:switchshow: simple
+:version: simple
+:fosconfig: simple
+:lscfg: simple
+:aptpolicy: simple
+:chassisname: oneline
+:dlsshow: oneline
+:iodshow: oneline
+:switchstatusshow: multiline
+:supportshow: multiline
+:cfgshow: cfgshow
+:nsshow: ns
+:nscamshow: ns
+:fabricshow: simple
+:agshow: simple
+:configshow: simple
+:islshow: simple
+:trunkshow: trunk
+:cfgtransshow: multiline
+:zoneshow: cfgshow
+:alishow: cfgshow

data/lib/brocadesan/device.rb

@@ -0,0 +1,296 @@
+require 'net/ssh'
+
+# Basic wrapper class that runs SSH queries on the device and returns Response
+#
+# It is used to extend further classes with SSH query mechanism
+ 
+module SshDevice
+  
+  # default query prompt that will preceed each command started by +query+ in the Response +data+
+  #
+  # value is "> "
+  #
+  # This way the parser can separate from commands and data. The default will work everwhere where the retunned data is not prepended by "> "
+  #
+  # Ignore the ssh prompt like this:
+  # super_server(admin)> cmd
+  # super_server(admin)> data
+  #
+  # This on the other hand would be problem. In this case override the prompt
+  # super_server(admin)> cmd
+  # super_server(admin)>> data
+  
+  DEFAULT_QUERY_PROMPT="> "
+  
+  attr_reader :prompt
+  
+  # Initialization method
+  # 
+  # +opts+ can be:
+  #
+  # [:interactive] +true+ / +false+
+  #                will use interactive query
+  #                can be set later
+  # [:prompt]      +prompt+
+  #                will override the DEFAULT_QUERY_PROMPT
+  def initialize(address,user,password,opts={}) 
+      @address=address
+      @user=user
+      @password=password
+      @opts=opts
+      @session=nil
+      @session_level=0
+      @prompt = opts[:prompt] ? opts[:prompt].to_s : DEFAULT_QUERY_PROMPT
+  end
+  
+  # get current query mode
+  #
+  # returns either +interactive+ or +script+
+  #
+  # default mode is +script+
+  def get_mode
+    [true,false].include?(@opts[:interactive]) ? (@opts[:interactive]==true ? "interactive" : "script") : "script"
+  end
+  
+  # sets current query mode
+  #
+  # +mode+: interactive or script
+  #
+  # interactive - used to do interactive queries in scripted manner by providing all responses in advance, see #query
+  
+  def set_mode(mode)
+    @opts[:interactive] = mode.to_s == "interactive" ? true : false
+    get_mode
+  end
+  
+  # Queries +cmds+ commands directly. 
+  # This method is to be used to implement higlevel API 
+  # or 
+  # to do more difficult queries that have to be parsed separately and for which there is now highlevel API
+  #
+  # When started in interactive mode be sure the command is followed by inputs for that command.
+  # If command will require additional input and there is not one provided the prompt will receive +enter+.
+  # It will do this maximum of 100 times, then it gives up and returns whatever it got until then.
+  #
+  # Query command will open connection to device if called outside session block
+  # or use existing session if called within session block.
+  #
+  # Example:
+  #   >> class Test
+  #   >>   include SshDevice
+  #   >> end
+  #   >> device = Test.new("address","user","password")
+  #   >> device.query("switchname")
+  #   => #<Test::Response:0x2bb1e00 @errors="", @data="> switchname\nsanswitchA\n", @parsed={:parsing_position=>"end"}>
+  #
+  # 
+  # Returns instance of Response or raises Error if the connection cannot be opened
+  #
+  # Raises Error if SSH returns error. SSH error will be available in the exception message
+  def query(*cmds)
+    output=nil
+    if session_exist?
+      output=exec(@session,cmds)
+    else
+      Net::SSH.start @address, @user, :password=>@password do |ssh|
+        output=exec(ssh,cmds)
+      end
+    end
+    
+    raise self.class::Error.new(output.errors) if !output.errors.empty?
+    
+    return output
+  end
+  
+  # Opens a session block
+  # 
+  # All queries within the session block use the same connection. This speeds up the query processing.
+  # 
+  # The connection is closed at the end of the block
+  # 
+  # The command supports session blocks within session blocks. Session will be closed only at the last block
+  #
+  # Example:
+  #   device.session do 
+  #     device.query("switchname")
+  #     device.version
+  #   end
+  # 
+  # Must receive block, raises SshDevice::Error otherwise
+  def session(&block)
+    raise Error.no_block if !block_given?
+    begin 
+      @session_level+=1 
+      if !session_exist?
+        @session=Net::SSH.start @address, @user, :password=>@password
+      end
+      yield
+    rescue => e
+      raise e
+    ensure
+      @session_level-=1
+      @session.close if @session && @session_level==0 && !@session.closed?
+    end
+  end
+  
+  # Defines a block of code to run in script mode
+  #
+  # the mode will be reverted back to initial mode after leaving the block
+  def script_mode(&block)
+    run_in_mode :script, &block
+  end
+  
+  # Defines a block of code to run in interactive mode
+  #
+  # the mode will be reverted back to initial mode after leaving the block
+  def interactive_mode(&block)
+    run_in_mode :interactive, &block
+  end
+  
+  private
+  
+  def run_in_mode(mode,&block)
+    old_mode = get_mode
+    set_mode mode
+    begin
+      yield
+    rescue => e
+      raise e  
+    ensure
+      set_mode old_mode
+    end
+  end
+  
+  def session_exist?
+    @session && !@session.closed?
+  end
+  
+  def exec(ssh_session,cmds)
+    
+    @opts[:interactive]||=false
+
+    if @opts[:interactive]==true
+      interactive_exec(ssh_session,cmds)
+    else
+      standard_exec(ssh_session,cmds)
+    end
+  end
+  
+  def standard_exec(ssh_session,cmds)
+    output=new_output
+    cmds.each do |cmd|
+      output.data+=@prompt+cmd+"\n"
+      ssh_session.exec! cmd do |ch, stream, data|
+        if stream == :stderr
+          output.errors+=data
+        else
+          output.data+=data
+        end
+      end
+      output.errors+="\n" if !output.errors.empty?
+      output.data+="\n"
+    end
+    return output
+  end
+  
+  # interactive exec considers cmds as inputs, only first item is considered as command
+  
+  def interactive_exec(ssh_session,cmds)
+    output=new_output
+    # instance variable is used for pure testability, this could do with local variable otherwise
+    @retries = 0
+    cmd=cmds.shift
+    output.data+=@prompt+cmd+"\n"
+    ssh_session.open_channel do |channel|
+      channel.request_pty
+      channel.exec cmd do |ch, success|
+        abort "could not execute #{cmd}" unless success
+        ch.on_data do |ch1, data|
+          output.data+=data
+          # data is multiline, if the very last character is not newline then the command expects response
+          
+          if !data.match(/\n$/)
+            @retries+=1 if cmds.empty?
+            stdin = cmds.empty? ? "\n" : cmds.shift+"\n"
+            ch1.send_data stdin
+            output.data+=stdin
+          end
+          # we do not want to send newline to infinity so we exit
+          # if we are still getting response after 100 empty command
+          # if the command is newline explicitely this will not increase the @retriy          
+          ch.close if @retries==100
+        end
+
+        ch.on_extended_data do |ch1, type, data|
+          output.errors+=data
+        end      
+      end
+    end  
+    ssh_session.loop
+    return output
+  end
+  
+  def new_output
+    # this approach is used to use Response of the calling class
+    self.class::Response.new(@prompt)
+  end
+end
+
+
+module SshDevice
+  # This class defines the device response and it should not be manipulated directly
+  # Only exception is direct usage of query method which returns instance of this class
+
+  class Response
+    # contains output of the command
+    attr_accessor :data
+    # contains errors raised by SSH exec
+    attr_accessor :errors
+    # contains parsed information after the parse method ran
+    attr_accessor :parsed # :nodoc:
+  
+    #initialization method
+    def initialize(prompt) # :nodoc:
+      @errors=""
+      @data=""
+      @parsed = {
+       :parsing_position=>nil
+      }
+      @prompt=prompt
+    end
+    
+    # Resets all parsed data
+    #
+    def reset # :nodoc:
+      @parsed = {
+       :parsing_position=>nil
+      }
+    end
+    
+    # Parse the current data and stores result to +parsed+.
+    #
+    # Any class that inherits from this class should override the private parse_line method and store results into +parsed+ hash
+    def parse # :nodoc:
+      reset if !@parsed.kind_of? Hash
+      
+      @data.split("\n").each do |line|
+        parse_line line
+      end
+      
+      @parsed[:parsing_position]="end"
+    end
+    
+    private 
+    
+    def parse_line(line)
+    end
+  end
+  
+  # Class using for raising specific errors
+  class Error < StandardError; 
+    SESSION_WTIHOUT_BLOCK = "Error: Session can run only with block" 
+    def self.no_block
+      self.new(SESSION_WTIHOUT_BLOCK)
+    end
+  end
+end