cisco_node_utils_mgx 2.1.0.1

data/lib/cisco_node_utils/cisco_cmn_utils.rb

@@ -0,0 +1,444 @@
+# Common Utilities for Puppet Resources.
+#
+# Copyright (c) 2014-2016 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Add some general-purpose constants and APIs to the Cisco namespace
+module Cisco
+  # global constants
+  DEFAULT_INSTANCE_NAME = 'default'
+
+  # Encryption - helper class for translating encryption type CLI
+  class Encryption
+    # password encryption types
+    def self.cli_to_symbol(cli)
+      case cli
+      when '0', 0, 'clear'
+        :cleartext
+      when '3', 3
+        :"3des" # yuck :-(
+      when '5', 5, 'encrypted'
+        :md5
+      when '6', 6
+        :aes
+      when '7', 7
+        :cisco_type_7
+      else
+        fail KeyError
+      end
+    end
+
+    def self.symbol_to_cli(symbol)
+      symbol = symbol.downcase if symbol.is_a? String
+      case symbol
+      when :cleartext, :none, 'cleartext', 'none', '0', 0
+        '0'
+      when :"3des", '3des', '3', 3
+        '3'
+      when :md5, 'md5', '5', 5
+        '5'
+      when :aes, 'aes', '6', 6
+        '6'
+      when :cisco_type_7, :type_7, 'cisco_type_7', 'type_7', '7', 7
+        '7'
+      else
+        fail KeyError
+      end
+    end
+  end
+
+  # ChefUtils - helper class for Chef code generation
+  class ChefUtils
+    def self.generic_prop_set(klass, rlbname, props)
+      props.each do |prop|
+        klass.instance_eval do
+          # Helper Chef setter method, e.g.:
+          #   if @new_resource.foo.nil?
+          #     def_prop = @rlb.default_foo
+          #     @new_resource.foo(def_prop)
+          #   end
+          #   current = @rlb.foo
+          #   if current != @new_resource.foo
+          #     converge_by("update foo '#{current}' => " +
+          #                 "'#{@new_resource.foo}'") do
+          #       @rlb.foo=(@new_resource.foo)
+          #     end
+          #   end
+          if @new_resource.send(prop).nil?
+            def_prop = instance_variable_get(rlbname).send("default_#{prop}")
+            # Set resource to default if recipe property is not specified
+            @new_resource.send(prop, def_prop)
+          end
+          current = instance_variable_get(rlbname).send(prop)
+          if current != @new_resource.send(prop)
+            converge_by("update #{prop} '#{current}' => " \
+                        "'#{@new_resource.send(prop)}'") do
+              instance_variable_get(rlbname).send("#{prop}=",
+                                                  @new_resource.send(prop))
+            end
+          end
+        end
+      end
+    end
+  end # class ChefUtils
+
+  # General utility class
+  class Utils
+    require 'ipaddr'
+
+    # Helper utility to check for older Nexus I2 images
+    def self.nexus_i2_image
+      require_relative 'platform'
+      true if Platform.image_version[/7.0.3.I2/]
+    end
+
+    def self.image_version?(ver_regexp)
+      require_relative 'platform'
+      return true if Platform.image_version[ver_regexp]
+    end
+
+    def self.chassis_pid?(ver_regexp)
+      require_relative 'platform'
+      return true if Platform.chassis['pid'][ver_regexp]
+    end
+
+    def self.fretta?
+      require_relative 'platform'
+      Platform.slots.each do |_x, row|
+        return true if row['pid'][/-R/]
+      end
+      false
+    end
+
+    # Helper utility method for ip/prefix format networks.
+    # For ip/prefix format '1.1.1.1/24' or '2000:123:38::34/64',
+    # we need to mask the address using the prefix length so that they
+    # are converted to '1.1.1.0/24' or '2000:123:38::/64'
+    def self.process_network_mask(network)
+      mask = network.split('/')[1]
+      address = IPAddr.new(network).to_s
+      network = address + '/' + mask unless mask.nil?
+      network
+    end
+
+    # Helper to build a hash of add/remove commands for a nested array.
+    # Useful for network, redistribute, etc.
+    #   should: an array of expected cmds (manifest/recipe)
+    #  current: an array of existing cmds on the device
+    def self.depth(a)
+      return 0 unless a.is_a?(Array)
+      1 + depth(a[0])
+    end
+
+    def self.delta_add_remove(should, current=[], opt=nil)
+      current = [] if current.nil?
+      should = [] if should.nil?
+
+      # Remove nil entries from array
+      should.each(&:compact!) if depth(should) > 1
+      delta = { add: should - current, remove: current - should }
+
+      # Some cli properties cannot be updated, thus must be removed first
+      return delta if opt == :updates_not_allowed
+
+      # Delete entries from :remove if f1 is an update to an existing command
+      delta[:add].each do |id, _|
+        # Differentiate between comparing nested and unnested arrays by
+        # checking the depth of the array.
+        if depth(should) == 1
+          delta[:remove].delete_if { |f1| [f1] if f1.to_s == id.to_s }
+        else
+          delta[:remove].delete_if { |f1, f2| [f1, f2] if f1.to_s == id.to_s }
+        end
+      end
+      delta
+    end # delta_add_remove
+
+    def self.length_to_bitmask(length)
+      IPAddr.new('255.255.255.255').mask(length).to_s
+    end
+
+    def self.bitmask_to_length(bitmask)
+      # Convert bitmask to a 32-bit integer,
+      # convert that to binary, and count the 1s
+      IPAddr.new(bitmask).to_i.to_s(2).count('1')
+    rescue IPAddr::InvalidAddressError => e
+      raise ArgumentError, "bitmask '#{bitmask}' is not valid: #{e}"
+    end
+
+    # Helper to 0-pad a mac address.
+    def self.zero_pad_macaddr(mac)
+      return nil if mac.nil? || mac.empty?
+      o1, o2, o3 = mac.split('.').map { |o| o.to_i(16).to_s(10) }
+      sprintf('%04x.%04x.%04x', o1, o2, o3)
+    end
+
+    # For spanning tree range based parameters, the range
+    # is very dynamic and so before the parameters are set,
+    # the rest of the range needs to be reset
+    # For ex: if the ranges 2-42 and 83-200 are getting set,
+    # and the total range of the given parameter is 1-4000
+    # then 1,43-82,201-4000 needs to be reset. This method
+    # takes the set ranges and gives back the range to be reset
+    def self.get_reset_range(total_range, remove_ranges)
+      fail 'invalid range' unless total_range.include?('-')
+      return total_range if remove_ranges.empty?
+
+      trs = total_range.gsub('-', '..')
+      tra = trs.split('..').map { |d| Integer(d) }
+      tr = tra[0]..tra[1]
+      tarray = tr.to_a
+      remove_ranges.each do |rr, _val|
+        rarray = rr.gsub('-', '..').split(',')
+        rarray.each do |elem|
+          if elem.include?('..')
+            elema = elem.split('..').map { |d| Integer(d) }
+            ele = elema[0]..elema[1]
+            tarray -= ele.to_a
+          else
+            tarray.delete(elem.to_i)
+          end
+        end
+      end
+      Utils.array_to_str(tarray)
+    end
+
+    # This method converts an array to string form
+    # for ex: if the array has 1, 2 to 10, 83 to 2014, 3022
+    # and the string will be "1,2-10,83-2014,3022"
+    def self.array_to_str(array, sort=true)
+      farray = sort ? array.compact.uniq.sort : array.compact
+      lranges = []
+      unless farray.empty?
+        l = array.first
+        r = nil
+        farray.each do |aelem|
+          if r && aelem != r.succ
+            if l == r
+              lranges << l
+            else
+              lranges << Range.new(l, r)
+            end
+            l = aelem
+          end
+          r = aelem
+        end
+        if l == r
+          lranges << l
+        else
+          lranges << Range.new(l, r)
+        end
+      end
+      lranges.to_s.gsub('..', '-').delete('[').delete(']').delete(' ')
+    end
+
+    # normalize_range_array
+    #
+    # Given a list of ranges, merge any overlapping ranges and sort them.
+    #
+    # Note: The ranges are converted to ruby ranges for easy merging,
+    # then converted back to a cli-syntax range.
+    #
+    # Accepts an array or string:
+    #   ["2-5", "9", "4-6"]  -or-  '2-5, 9, 4-6'  -or-  ["2-5, 9, 4-6"]
+    # Returns a merged and ordered range as an array or string:
+    #   ["2-6", "9"] -or- '2-6,9'
+    #
+    def self.normalize_range_array(range, fmt=:array)
+      return range if range.nil? || range.empty?
+      range = range.clone
+
+      # Handle string within an array: ["2-5, 9, 4-6"] to '2-5, 9, 4-6'
+      range = range.shift if range.is_a?(Array) && range.length == 1
+
+      # Handle string only: '2-5, 9, 4-6' to ["2-5", "9", "4-6"]
+      range = range.split(',') if range.is_a?(String)
+
+      # Convert to ruby-syntax ranges
+      range = dash_range_to_ruby_range(range)
+
+      # Sort & Merge
+      merged = merge_range(range)
+
+      # Convert back to cli dash-syntax
+      merged_array = ruby_range_to_dash_range(merged)
+
+      return merged_array.join(',') if fmt == :string
+      merged_array
+    end
+
+    # Convert a cli-dash-syntax range to ruby-range. This is useful for
+    # preparing inputs to merge_range().
+    #
+    # Inputs an array or string of dash-syntax ranges -> returns an array
+    # of ruby ranges.
+    #
+    # Accepts an array or string: ["2-5", "9", "4-6"] or '2-5, 9, 4-6'
+    # Returns an array of ranges: [2..5, 9..9, 4..6]
+    #
+    def self.dash_range_to_ruby_range(range)
+      range = range.split(',') if range.is_a?(String)
+      range.map! do |rng|
+        if rng[/-/]
+          # '2-5' -> 2..5
+          rng.split('-').inject { |a, e| a.to_i..e.to_i }
+        else
+          # '9' -> 9..9
+          rng.to_i..rng.to_i
+        end
+      end
+      range
+    end
+
+    # Convert a ruby-range to cli-dash-syntax.
+    #
+    # Inputs an array of ruby ranges -> returns an array or string of
+    # dash-syntax ranges.
+    #
+    # when (:array)  [2..6, 9..9]  ->  ['2-6', '9']
+    #
+    # when (:string)  [2..6, 9..9]  ->  '2-6, 9'
+    #
+    def self.ruby_range_to_dash_range(range, type=:array)
+      fail unless range.is_a?(Array)
+      range.map! do |r|
+        if r.first == r.last
+          # 9..9 -> '9'
+          r.first.to_s
+        else
+          # 2..6 -> '2-6'
+          r.first.to_s + '-' + r.last.to_s
+        end
+      end
+      return range.join(', ') if type == :string
+      range
+    end
+
+    # Convert a dash-range set into individual elements.
+    # This is useful for preparing inputs to delta_add_remove().
+    #
+    # Inputs an array or string of dash-ranges:
+    #  ["2-5", "9", "4-6"] or '2-5, 9, 4-6' or ['2-5, 9, 4-6']
+    # Returns an array of range elements:
+    #  ["2", "3", "4", "5", "6", "9"]
+    #
+    def self.dash_range_to_elements(range)
+      return [] if range.nil?
+      range = range.shift if range.is_a?(Array) && range.length == 1
+      range = range.split(',') if range.is_a?(String)
+
+      final = []
+      range = dash_range_to_ruby_range(range)
+      range.each do |rng|
+        # 2..5 maps to ["2", "3", "4", "5"]
+        final << rng.map(&:to_s)
+      end
+      final.flatten.uniq.sort
+    end
+
+    # Merge overlapping ranges.
+    #
+    # Inputs an array of ruby ranges:         [2..5, 9..9, 4..6]
+    # Returns an array of merged ruby ranges: [2..6, 9..9]
+    #
+    def self.merge_range(range)
+      # sort to lowest range 'first' values:
+      #    [2..5, 9..9, 4..6]  ->  [2..5, 4..6, 9..9]
+      range = range.sort_by(&:first)
+
+      *merged = range.shift
+      range.each do |r|
+        lastr = merged[-1]
+        if lastr.last >= r.first - 1
+          merged[-1] = lastr.first..[r.last, lastr.last].max
+        else
+          merged.push(r)
+        end
+      end
+      merged
+    end # merge_range
+
+    def self.add_quotes(value)
+      return value if image_version?(/7.3.[0-1]/) || value.nil?
+      value = "'#{value}'" unless
+        value.start_with?('"', "'") && value.end_with?('"', "'")
+      value
+    end # add_quotes
+
+    # This method is used in config_get for CLIs which
+    # have multiple properties in the same output
+    # Given a match_method which defines regex pattern and the
+    # match criteria, this method, extracts the value of
+    # a property with or without a prefix.
+    # For ex. if the regex pattern is something like:
+    # (?<action>\S+)?
+    # the property to extract is action and prefix is nil
+    # for (?<src_port>range \S+)
+    # the property to extract is src_port and prefix is range
+    def self.extract_value(match_method, prop, prefix=nil)
+      prefix = prop if prefix.nil?
+      mm = match_method
+
+      return nil if mm.nil?
+
+      return nil unless mm.names.include?(prop)
+
+      # extract and return value that follows prefix + <space>
+      regexp = Regexp.new("#{Regexp.escape(prefix)} (?<extracted>.*)")
+      value_match = regexp.match(mm[prop])
+      return nil if value_match.nil?
+      value_match[:extracted]
+    end
+
+    # This method is used in config_set for CLIs which
+    # can set multiple properties using the same CLI.
+    # This method attaches prefix to the given property
+    # when the prefix is different from the property name
+    # else it attaches property name itself. It also
+    # appends the value to be set.
+    # For ex. if the set_value is <precedence> <time_range>
+    # the prop for precedence could be 'precedence', and
+    # for time_range, the prop and prefix could be 'time_range'
+    # and 'time-range'
+    def self.attach_prefix(val, prop, prefix=nil)
+      prefix = prop.to_s if prefix.nil?
+      val.to_s.empty? ? val : "#{prefix} #{val}"
+    end
+
+    # Helper utility to normalize the interface name pattern to be filtered.
+    # This is only a problem on N7k which has to use a section filter
+    # due to a show run int bug (no 'all' keyword for some interfaces).
+    def self.normalize_intf_pattern(show_name)
+      return '' if show_name.nil? || show_name.empty?
+      require_relative 'platform'
+      return show_name unless Platform.hardware_type[/Nexus7/]
+      return show_name if show_name[-1] == '$' #  already normalized
+      pat = show_name.downcase + '$'
+      case pat
+      when /ethernet/
+        pat.sub!(/ethernet/, 'Ethernet')
+      when /loopback/
+        pat.sub!(/loopback/, 'loopback')
+      when /port-channel/
+        pat.sub!(/port-channel/, 'port-channel')
+      when /vlan/
+        pat.sub!(/vlan/, 'Vlan')
+      else
+        # wildcard the first char of the name
+        pat.sub!(/./, '.')
+      end
+      pat
+    end
+  end # class Utils
+end   # module Cisco

data/lib/cisco_node_utils/client/client.rb

@@ -0,0 +1,238 @@
+#!/usr/bin/env ruby
+#
+# October 2015, Glenn F. Matthews
+#
+# Copyright (c) 2015-2016 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative '../environment'
+require_relative '../exceptions'
+require_relative 'utils'
+require_relative '../constants'
+require_relative '../logger'
+
+include Cisco::Logger
+
+# Base class for clients of various RPC formats
+class Cisco::Client
+  @@clients = [] # rubocop:disable Style/ClassVars
+
+  def self.clients
+    @@clients
+  end
+
+  # Each subclass should call this method to register itself.
+  def self.register_client(client)
+    @@clients << client
+  end
+
+  attr_reader :data_formats, :platform
+
+  def initialize(data_formats: [],
+                 platform:     nil,
+                 **kwargs)
+    if self.class == Cisco::Client
+      fail NotImplementedError, 'Cisco::Client is an abstract class. ' \
+        "Instantiate one of #{@@clients} or use Cisco::Client.create() instead"
+    end
+    self.class.validate_args(**kwargs)
+    @host = kwargs[:host]
+    @port = kwargs[:port]
+    @address = @port.nil? ? @host : "#{@host}:#{@port}"
+    @username = kwargs[:username]
+    @password = kwargs[:password]
+    self.data_formats = data_formats
+    self.platform = platform
+    @cache_enable = true
+    @cache_auto = true
+    cache_flush
+  end
+
+  def self.validate_args(**kwargs)
+    host = kwargs[:host]
+    unless host.nil?
+      fail TypeError, 'invalid address' unless host.is_a?(String)
+      fail ArgumentError, 'empty address' if host.empty?
+    end
+    username = kwargs[:username]
+    unless username.nil?
+      fail TypeError, 'invalid username' unless username.is_a?(String)
+      fail ArgumentError, 'empty username' if username.empty?
+    end
+    password = kwargs[:password]
+    unless password.nil?
+      fail TypeError, 'invalid password' unless password.is_a?(String)
+      fail ArgumentError, 'empty password' if password.empty?
+    end
+  end
+
+  def supports?(data_format)
+    data_formats.include?(data_format)
+  end
+
+  # Try to create an instance of an appropriate subclass
+  def self.create(environment_name=nil)
+    fail 'No client implementations available!' if clients.empty?
+    debug "Trying to establish client connection. clients = #{clients}"
+    environment = Cisco::Environment.environment(environment_name)
+    host = environment[:host]
+    errors = []
+    clients.each do |client_class|
+      begin
+        debug "Trying to connect to #{host} as #{client_class}"
+        client = client_class.new(**environment)
+        debug "#{client_class} connected successfully"
+        return client
+      rescue Cisco::ClientError, TypeError, ArgumentError => e
+        debug "Unable to connect to #{host} as #{client_class}: #{e.message}"
+        debug e.backtrace.join("\n  ")
+        errors << e
+      end
+    end
+    handle_errors(errors)
+  end
+
+  def self.handle_errors(errors)
+    # ClientError means we tried to connect but failed,
+    # so it's 'more significant' than input validation errors.
+    client_errors = errors.select { |e| e.kind_of? Cisco::ClientError }
+    if !client_errors.empty?
+      # Reraise the specific error if just one
+      fail client_errors[0] if client_errors.length == 1
+      # Otherwise clump them together into a new error
+      e_cls = client_errors[0].class
+      unless client_errors.all? { |e| e.class == e_cls }
+        e_cls = Cisco::ClientError
+      end
+      fail e_cls, ("Unable to establish any client connection:\n" +
+                   errors.each(&:message).join("\n"))
+    elsif errors.any? { |e| e.kind_of? ArgumentError }
+      fail ArgumentError, ("Invalid arguments:\n" +
+                           errors.each(&:message).join("\n"))
+    elsif errors.any? { |e| e.kind_of? TypeError }
+      fail TypeError, ("Invalid arguments:\n" +
+                       errors.each(&:message).join("\n"))
+    end
+    fail Cisco::ClientError, 'No client connected, but no errors were reported?'
+  end
+
+  def to_s
+    @address.to_s
+  end
+
+  def inspect
+    "<#{self.class} of #{@address}>"
+  end
+
+  def cache_enable?
+    @cache_enable
+  end
+
+  def cache_enable=(enable)
+    @cache_enable = enable
+    cache_flush unless enable
+  end
+
+  def cache_auto?
+    @cache_auto
+  end
+
+  attr_writer :cache_auto
+
+  # Clear the cache of CLI output results.
+  #
+  # If cache_auto is true (default) then this will be performed automatically
+  # whenever a set() is called, but providers may also call this
+  # to explicitly force the cache to be cleared.
+  def cache_flush
+    # to be implemented by subclasses
+  end
+
+  # Configure the given state on the device.
+  #
+  # @raise [RequestNotSupported] if this client doesn't support the given
+  #   data_format
+  #
+  # @param data_format one of Cisco::DATA_FORMATS. Default is :cli
+  # @param context [String, Array<String>] Context for the configuration
+  # @param values [String, Array<String>] Actual configuration to set
+  # @param kwargs data-format-specific args
+  def set(data_format: :cli,
+          context:     nil,
+          values:      nil,
+          **_kwargs)
+    # subclasses will generally want to call Client.munge_to_array()
+    # on context and/or values before calling super()
+    fail Cisco::RequestNotSupported unless self.supports?(data_format)
+    cache_flush if cache_auto?
+    Cisco::Logger.debug("Set state using data format '#{data_format}'")
+    Cisco::Logger.debug("  with context:\n    #{context.join("\n    ")}") \
+      unless context.nil? || context.empty?
+    Cisco::Logger.debug("  to value(s):\n    #{values.join("\n    ")}") \
+      unless values.nil? || values.empty?
+    # to be implemented by subclasses
+  end
+
+  # Get the given state from the device.
+  #
+  # Unlike set() this will not clear the CLI cache;
+  # multiple calls with the same parameters may return cached data
+  # rather than querying the device repeatedly.
+  #
+  # @raise [RequestNotSupported] if the client doesn't support the data_format
+  # @raise [RequestFailed] if the command is rejected by the device
+  #
+  # @param data_format one of Cisco::DATA_FORMATS. Default is :cli
+  # @param command [String] the get command to execute
+  # @param context [String, Array<String>] Context to refine/filter the results
+  # @param value [String, Regexp] Specific key or regexp to look up
+  # @param kwargs data-format-specific args
+  # @return [String, Hash, nil] The state found, or nil if not found.
+  def get(data_format: :cli,
+          command:     nil,
+          context:     nil,
+          value:       nil,
+          **_kwargs)
+    # subclasses will generally want to call Client.munge_to_array()
+    # on context and/or value before calling super()
+    fail Cisco::RequestNotSupported unless self.supports?(data_format)
+    Cisco::Logger.debug("Get state using data format '#{data_format}'")
+    Cisco::Logger.debug("  executing command:\n    #{command}") \
+      unless command.nil? || command.empty?
+    Cisco::Logger.debug("  with context:\n    #{context.join("\n    ")}") \
+      unless context.nil? || context.empty?
+    Cisco::Logger.debug("  to get value:     #{value}") \
+      unless value.nil?
+    # to be implemented by subclasses
+  end
+
+  private
+
+  # Set the list of data formats supported by this client.
+  # If the client supports multiple formats, and a given feature or property
+  # can be managed by multiple formats, the list order indicates preference.
+  def data_formats=(data_formats)
+    data_formats = [data_formats] unless data_formats.is_a?(Array)
+    unknown = data_formats - Cisco::DATA_FORMATS
+    fail ArgumentError, "unknown data formats: #{unknown}" unless unknown.empty?
+    @data_formats = data_formats
+  end
+
+  # Set the platform of the node managed by this client.
+  def platform=(platform)
+    fail ArgumentError, "unknown platform #{platform}" \
+      unless Cisco::PLATFORMS.include?(platform)
+    @platform = platform
+  end
+end