cisco_node_utils_mgx 2.1.0.1

data/lib/cisco_node_utils/client/grpc.rb

@@ -0,0 +1,33 @@
+# Copyright (c) 2015 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 'client'
+
+# Fail gracefully if submodule dependencies are not met
+begin
+  Cisco::Client.silence_warnings do
+    require 'grpc'
+  end
+rescue LoadError => e
+  raise unless e.message =~ /-- grpc/
+  # If grpc is not installed, raise an error that client understands.
+  raise LoadError, "Unable to load client/grpc -- #{e}"
+end
+
+# Namespace for Cisco EMS gRPC-specific code
+class Cisco::Client::GRPC < Cisco::Client
+end
+
+# Auto-load all Ruby files in the subdirectory
+Dir.glob(__dir__ + '/grpc/*.rb') { |file| require file }

data/lib/cisco_node_utils/client/nxapi/client.rb

@@ -0,0 +1,368 @@
+# NXAPI client library.
+#
+# November 2014, Glenn F. Matthews
+#
+# Copyright (c) 2014-2019 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 '../client'
+require 'json'
+require 'net/http'
+
+include Cisco::Logger
+
+# Class representing an HTTP client connecting to a NXAPI server.
+class Cisco::Client::NXAPI < Cisco::Client
+  # Location of unix domain socket for NXAPI localhost
+  NXAPI_UDS = '/tmp/nginx_local/nginx_1_be_nxapi.sock'
+  # NXAPI listens for remote connections to "http://<switch IP>/ins"
+  # NXAPI listens for local connections to "http://<UDS>/ins_local"
+  NXAPI_REMOTE_URI_PATH = '/ins'
+  NXAPI_UDS_URI_PATH = '/ins_local'
+  # Latest supported version is 1.0
+  NXAPI_VERSION = '1.0'
+
+  register_client(self)
+
+  # Constructor for Client. By default this connects to the local
+  # unix domain socket. If you need to connect to a remote device,
+  # you must provide the host/username/password parameters.
+  def initialize(**kwargs)
+    # rubocop:disable Style/HashSyntax
+    super(data_formats: [:nxapi_structured, :cli],
+          platform:     :nexus,
+          **kwargs)
+    # rubocop:enable Style/HashSyntax
+    # Default: connect to unix domain socket on localhost, if available
+    if @host.nil?
+      unless File.socket?(NXAPI_UDS)
+        fail Cisco::ConnectionRefused, \
+             "No host specified but no UDS found at #{NXAPI_UDS} either"
+      end
+      # net_http_unix provides NetX::HTTPUnix, a small subclass of Net::HTTP
+      # which supports connection to local unix domain sockets. We need this
+      # in order to run natively under NX-OS but it's not needed for off-box
+      # unit testing where the base Net::HTTP will meet our needs.
+      require 'net_http_unix'
+      @http = NetX::HTTPUnix.new('unix://' + NXAPI_UDS)
+      @cookie = kwargs[:cookie]
+    else
+      # Remote connection. This is primarily expected
+      # when running e.g. from a Unix server as part of Minitest.
+      @transport = kwargs[:transport] || 'http'
+      @verify_mode = kwargs[:verify_mode] || 'none'
+      @port.nil? ? @port = '' : @port = ":#{@port}"
+      uri = URI.parse("#{@transport}://#{@host}#{@port}")
+      @http = Net::HTTP.new(uri.host, uri.port)
+    end
+    # The default read time out is 60 seconds, which may be too short for
+    # scaled configuration to apply. Change it to 300 seconds, which is
+    # also used as the default config by firefox.
+    @http.read_timeout = 300
+    @address = @http.address
+  end
+
+  def self.validate_args(**kwargs)
+    super
+    if kwargs[:host].nil?
+      # Connection to UDS - no username or password either
+      fail ArgumentError unless kwargs[:username].nil? && kwargs[:password].nil?
+      validate_cookie(**kwargs)
+    else
+      # Connection to remote system - username and password are required
+      fail TypeError, 'username is required' if kwargs[:username].nil?
+      fail TypeError, 'password is required' if kwargs[:password].nil?
+    end
+  end
+
+  def self.validate_cookie(**kwargs)
+    return if kwargs[:cookie].nil?
+    format = 'Cookie format must match: <username>:local'
+    msg = "Invalid cookie: [#{kwargs[:cookie]}]. : #{format}"
+
+    fail TypeError, msg unless kwargs[:cookie].is_a?(String)
+    fail TypeError, msg unless /\S+:local/.match(kwargs[:cookie])
+    fail ArgumentError, 'empty cookie' if kwargs[:cookie].empty?
+  end
+
+  # 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
+    @cache_hash = {
+      'cli_conf'       => {},
+      'cli_show'       => {},
+      'cli_show_ascii' => {},
+    }
+  end
+
+  # Configure the given CLI command(s) on the device.
+  #
+  # @raise [RequestNotSupported] if this client doesn't support CLI config
+  #
+  # @param data_format one of Cisco::DATA_FORMATS. Default is :cli
+  # @param context [String, Array<String>] Zero or more configuration commands
+  #   used to enter the desired CLI sub-mode
+  # @param values [String, Array<String>] One or more commands
+  #   to enter within the CLI sub-mode.
+  # @param kwargs data-format-specific args
+  def set(data_format: :cli,
+          context: nil,
+          values: nil,
+          **_kwargs)
+    # we don't currently support nxapi_structured for configuration
+    fail Cisco::RequestNotSupported if data_format == :nxapi_structured
+    context = munge_to_array(context)
+    values = munge_to_array(values)
+    super
+    req('cli_conf', context + values)
+  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 [Cisco::RequestNotSupported] if
+  #   structured output is requested but the given command can't provide it.
+  # @raise [Cisco::CliError] if the command is rejected by the device
+  #
+  # @param data_format one of Cisco::DATA_FORMATS. Default is :cli
+  # @param command [String] the show command to execute
+  # @param context [String, Array<String>] Context to refine the results
+  # @param value [String] Specific key to look up
+  # @param kwargs data-format-specific args
+  # @return [String, Hash]
+  def get(data_format: :cli,
+          command:     nil,
+          context:     nil,
+          value:       nil,
+          **_kwargs)
+    context = munge_to_array(context)
+    super
+    if data_format == :cli
+      output = req('cli_show_ascii', command)
+      return self.class.filter_cli(cli_output: output,
+                                   context:    context,
+                                   value:      value)
+    elsif data_format == :nxapi_structured
+      output = req('cli_show', command)
+      return self.class.filter_data(data: output,
+                                    keys: context + munge_to_array(value))
+    else
+      fail TypeError
+    end
+  end
+
+  # Helper method to increase the default @http.read_timeout value from
+  # the default value of 300 to accomodate commands that are known to
+  # require more time to complete.
+  def read_timeout_check(request)
+    return unless request.body[/install all|install force-all/]
+    debug("Increasing http read_timeout to 1000 for 'install all' command")
+    @http.read_timeout = 1000
+  end
+
+  # Sends a request to the NX API and returns the body of the request or
+  # handles errors that happen.
+  # @raise Cisco::ConnectionRefused if NXAPI is disabled
+  # @raise Cisco::AuthenticationFailed if username/password are invalid
+  # @raise Cisco::ClientError (should never occur)
+  # @raise Cisco::RequestNotSupported
+  # @raise Cisco::RequestFailed if any command is rejected as invalid
+  #
+  # @param type ["cli_show", "cli_show_ascii"] Specifies the type of command
+  #             to be executed.
+  # @param command_or_list [String, Array<String>] The command or array of
+  #                        commands which should be run.
+  # @return [Hash, Array<Hash>] output when type == "cli_show"
+  # @return [String, Array<String>] output when type == "cli_show_ascii"
+  def req(type, command_or_list)
+    if command_or_list.is_a?(Array)
+      # NXAPI wants config lines to be separated by ' ; '
+      command = command_or_list.join(' ; ')
+    else
+      command = command_or_list
+      command_or_list = [command]
+    end
+
+    debug("Input (#{type}): \'#{command}\'")
+    if cache_enable? && @cache_hash[type] && @cache_hash[type][command]
+      return @cache_hash[type][command]
+    end
+
+    # form the request
+    request = build_http_request(type, command)
+
+    # send the request and get the response
+    debug("Sending #{@transport} request to NX-API at #{@http.address}:\n" \
+          "#{request.to_hash}\n#{request.body}")
+    read_timeout_check(request)
+    tries = 2
+    begin
+      if @transport == 'https'
+        debug('Setting use_ssl to true')
+        @http.use_ssl = true
+        @http.verify_mode = handle_verify_mode(@verify_mode)
+      else
+        @http.use_ssl = false
+      end
+      response = @http.request(request)
+    rescue Errno::ECONNREFUSED, Errno::ECONNRESET
+      emsg = 'Connection refused or reset. Is the NX-API feature enabled?'
+      raise Cisco::ConnectionRefused, emsg
+    rescue EOFError
+      tries -= 1
+      retry if tries > 0
+      raise
+    end
+    handle_http_response(response)
+    output = parse_response(response)
+
+    prev_cmds = []
+    if output.is_a?(Array)
+      output.zip(command_or_list) do |o, cmd|
+        handle_output(prev_cmds, cmd, o)
+        prev_cmds << cmd
+      end
+      output = output.each { |o| o['body'] }
+    else
+      handle_output(prev_cmds, command, output)
+      output = output['body']
+    end
+
+    output = '' if type == 'cli_show_ascii' && output.empty?
+
+    @cache_hash[type][command] = output if cache_enable?
+    output
+  end
+  private :req
+
+  def build_http_request(type, command_string)
+    if @username.nil? || @password.nil?
+      cookie = @cookie.nil? ? 'admin:local' : @cookie
+      request = Net::HTTP::Post.new(NXAPI_UDS_URI_PATH)
+      request['Cookie'] = "nxapi_auth=#{cookie}"
+    else
+      request = Net::HTTP::Post.new(NXAPI_REMOTE_URI_PATH)
+      request.basic_auth("#{@username}", "#{@password}")
+    end
+    request.content_type = 'application/json'
+    request.body = {
+      'ins_api' => {
+        'version'       => NXAPI_VERSION,
+        'type'          => "#{type}",
+        'chunk'         => '0',
+        'sid'           => '1',
+        'input'         => "#{command_string}",
+        'output_format' => 'json',
+      }
+    }.to_json
+    request
+  end
+  private :build_http_request
+
+  # Returns the OpenSSL verify mode based on the verify_mode arguments
+  #
+  # @raise if verify_mode param is not `peer`, `client-once`, `fail-no-peer`
+  #        or `none`
+  #
+  # @param String verify mode to use
+  #
+  # @return OpenSSL::SSL verification mode
+  def handle_verify_mode(verify_mode)
+    case verify_mode
+    when 'peer'
+      OpenSSL::SSL::VERIFY_PEER
+    when 'client-once'
+      OpenSSL::SSL::VERIFY_CLIENT_ONCE
+    when 'fail-no-peer'
+      OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT
+    when 'none'
+      OpenSSL::SSL::VERIFY_NONE
+    else
+      fail "#{verify_mode} is not a valid mode, " \
+            'valid modes are: "none", "peer", ' \
+            '"client-once", "fail-no-peer"'
+    end
+  end
+  private :handle_verify_mode
+
+  def handle_http_response(response)
+    debug("HTTP Response: #{response.message}\n#{response.body}")
+    case response
+    when Net::HTTPUnauthorized
+      emsg = 'HTTP 401 Unauthorized. Are your NX-API credentials correct?'
+      fail Cisco::AuthenticationFailed, emsg
+    when Net::HTTPBadRequest
+      emsg = "HTTP 400 Bad Request\n#{response.body}"
+      fail Cisco::ClientError, emsg
+    end
+  end
+  private :handle_http_response
+
+  def parse_response(response)
+    body = JSON.parse(response.body)
+
+    # In case of an error the JSON may not be complete, so we need to
+    # proceed carefully, as blindly doing body["ins_api"]["outputs"]["output"]
+    # could throw an error otherwise.
+    output = body['ins_api']
+    fail Cisco::ClientError, "unexpected JSON output:\n#{body}" if output.nil?
+    output = output['outputs'] if output['outputs']
+    output = output['output'] if output['output']
+
+    output
+  rescue JSON::ParserError
+    raise Cisco::ClientError, "response is not JSON:\n#{response.body}"
+  end
+  private :parse_response
+
+  def handle_output(prev_cmds, command, output)
+    if output['code'] == '400'
+      # CLI error.
+      # Examples: "Invalid input", "Incomplete command", etc.
+      fail Cisco::CliError.new( # rubocop:disable Style/RaiseArgs
+        rejected_input:   command,
+        clierror:         output['clierror'],
+        msg:              output['msg'],
+        code:             output['code'],
+        successful_input: prev_cmds,
+      )
+    elsif output['code'] == '413'
+      # Request too large
+      fail Cisco::RequestNotSupported, "Error 413: #{output['msg']}"
+    elsif output['code'] == '501'
+      # if structured output is not supported for this command,
+      # raise an exception so that the calling function can
+      # handle accordingly
+      fail Cisco::RequestNotSupported, \
+           "Structured output not supported for #{command}"
+    # Error 432: Requested object does not exist
+    # Ignore 432 errors because it means that a property is not configured
+    elsif output['code'] =~ /[45]\d\d/ && output['code'] != '432'
+      fail Cisco::RequestFailed, \
+           "#{output['code']} Error: #{output['msg']}"
+    else
+      debug("Result for '#{command}': #{output['msg']}")
+      if output['body'] && !output['body'].empty?
+        debug("Output: #{output['body']}")
+      end
+    end
+  end
+  private :handle_output
+end

data/lib/cisco_node_utils/client/nxapi.rb

@@ -0,0 +1,31 @@
+# Copyright (c) 2015 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 'client'
+
+# Fail gracefully if submodule dependencies are not met
+begin
+  require 'net_http_unix'
+rescue LoadError => e
+  raise unless e.message =~ /-- net_http_unix/
+  # If net_http_unix is not installed, raise an error that client understands.
+  raise LoadError, "Unable to load client/nxapi -- #{e}"
+end
+
+# Namespace for Cisco NXAPI-specific code
+class Cisco::Client::NXAPI < Cisco::Client
+end
+
+# Auto-load all Ruby files in the subdirectory
+Dir.glob(__dir__ + '/nxapi/*.rb') { |file| require file }

data/lib/cisco_node_utils/client/utils.rb

@@ -0,0 +1,180 @@
+#!/usr/bin/env ruby
+#
+# January 2016, 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 '../constants'
+require_relative '../logger'
+
+# Utility methods for clients of various RPC formats
+class Cisco::Client
+  # Make a best effort to convert a given input value to an Array.
+  # Strings are split by newlines, and nil becomes an empty Array.
+  def self.munge_to_array(val)
+    val = [] if val.nil?
+    val = val.split("\n") if val.is_a?(String)
+    val
+  end
+
+  def munge_to_array(val)
+    self.class.munge_to_array(val)
+  end
+
+  # Helper function that subclasses may use with get(data_format: :cli)
+  # Method for working with hierarchical show command output such as
+  # "show running-config". Searches the given multi-line string
+  # for all matches to the given value query. If context is provided,
+  # the matches will be filtered to only those that are located "under"
+  # the given context sequence (as determined by indentation).
+  #
+  # @param cli_output [String] The body of text to search
+  # @param context [*Regex] zero or more regular expressions defining
+  #                the parent configs to filter by.
+  # @param value [Regex] The regular expression to match
+  # @return [[String], nil] array of matching (sub)strings, else nil.
+  #
+  # @example Find all OSPF router names in the running-config
+  #   ospf_names = filter_cli(cli_output: running_cfg,
+  #                           value:      /^router ospf (\d+)/)
+  #
+  # @example Find all address-family types under the given BGP router
+  #   bgp_afs = filter_cli(cli_output: show_run_bgp,
+  #                        context:    [/^router bgp #{ASN}/],
+  #                        value:      /^address-family (.*)/)
+  def self.filter_cli(cli_output: nil,
+                      context:    nil,
+                      value:      nil)
+    return cli_output if cli_output.nil?
+    context ||= []
+    context.each { |filter| cli_output = find_subconfig(cli_output, filter) }
+    return nil if cli_output.nil? || cli_output.empty?
+    return cli_output if value.nil?
+    value = to_regexp(value)
+    match = cli_output.scan(value)
+    return nil if match.empty?
+    # find matches and return as array of String if it only does one match.
+    # Otherwise return array of array.
+    match.flatten! if match[0].is_a?(Array) && match[0].length == 1
+    match
+  end
+
+  # Returns the subsection associated with the given
+  # line of config
+  # @param [String] the body of text to search
+  # @param [Regex] the regex key of the config for which
+  # to retrieve the subsection
+  # @return [String, nil] the subsection of body, de-indented
+  # appropriately, or nil if no such subsection exists.
+  def self.find_subconfig(body, regexp_query)
+    return nil if body.nil? || regexp_query.nil?
+    regexp_query = to_regexp(regexp_query)
+
+    rows = body.split("\n")
+    match_row_index = rows.index { |row| regexp_query =~ row }
+    return nil if match_row_index.nil?
+
+    cur = match_row_index + 1
+    subconfig = []
+
+    until (/\A\s+.*/ =~ rows[cur]).nil? || cur == rows.length
+      subconfig << rows[cur]
+      cur += 1
+    end
+    return nil if subconfig.empty?
+    # Strip an appropriate minimal amount of leading whitespace from
+    # all lines in the subconfig
+    min_leading = subconfig.map { |line| line[/\A */].size }.min
+    subconfig = subconfig.map { |line| line[min_leading..-1] }
+    subconfig.join("\n")
+  end
+
+  # Helper method for CLI getters
+  #
+  # Convert a string or array of strings to a Regexp or array thereof
+  def self.to_regexp(input)
+    if input.is_a?(Regexp)
+      return input
+    elsif input.is_a?(Array)
+      return input.map { |item| to_regexp(item) }
+    else
+      # The string might be explicitly formatted as a regexp
+      # Dynamically handle modifiers
+      input.match(%r{(?<regex>^\/.*\/)(?<options>[imx]*)?}) do |m|
+        options = []
+        m['options'].each_char do |c|
+          case c
+          when 'i'
+            options << Regexp::IGNORECASE
+          when 'm'
+            options << Regexp::MULTILINE
+          when 'x'
+            options << Regexp::EXTENDED
+          end
+        end
+        return Regexp.new(m['regex'][1..-2], options.reduce(:|))
+      end
+      # otherwise this value is a regular string
+      # convert to case insensitive regex
+      # 'foo' => %r{^foo$}i
+      return Regexp.new("^#{input}$", Regexp::IGNORECASE)
+
+    end
+  end
+
+  # Helper method for get(data_format: :nxapi_structured).
+  #
+  # @param data [Array, Hash] structured output from node
+  # @param keys [Array] lookup sequence
+  def self.filter_data(data: nil,
+                       keys: nil)
+    return nil if data.nil? || data.empty?
+    keys ||= []
+    keys.each do |filter|
+      # if filter is a Hash and data is an array, check each
+      # array index (which should return another hash) to see if
+      # it contains the matching key/value pairs specified in token,
+      # and return the first match (or nil)
+      if filter.kind_of?(Hash)
+        fail "Expected Array, got #{data.class}" unless data.is_a? Array
+        data = data.select { |x| filter.all? { |k, v| x[k] == v } }
+        fail "Multiple matches found for #{filter}" if data.length > 1
+        fail "No match found for #{filter}" if data.length == 0
+        data = data[0]
+      else # data is array or hash
+        if data.is_a? Array
+          final = []
+          data.each do |row|
+            final << row[filter]
+          end
+          return final
+        end
+        fail "No key \"#{filter}\" in #{data}" unless data.key?(filter)
+        data = data[filter]
+      end
+    end
+    data
+  end
+
+  # Helper method for calls into third-party code - suppresses Ruby warnings
+  # for the given block since we have no control over that code.
+  def self.silence_warnings(&block)
+    warn_level = $VERBOSE
+    $VERBOSE = nil
+    result = block.call
+    $VERBOSE = warn_level
+    result
+  end
+end

data/lib/cisco_node_utils/client.rb

@@ -0,0 +1,35 @@
+# Copyright (c) 2015 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.
+
+# Namespace for Cisco-specific code
+module Cisco
+  # Namespace for Cisco Client shim
+  class Client
+  end
+end
+
+require_relative 'client/client'
+
+# Try to load known extensions
+extensions = ['client/nxapi',
+              'client/grpc',
+             ]
+extensions.each do |ext|
+  begin
+    require_relative ext
+  rescue LoadError => e
+    # ignore missing client-(grpc|nxapi), they're not always required
+    raise unless e.message =~ /#{Regexp.escape(ext)}/
+  end
+end