cisco_node_utils_mgx 2.1.0.1

data/docs/README-test-execution.md

@@ -0,0 +1,57 @@
+# Executing the tests provided for this gem
+
+## RSpec tests
+
+The test files located in the `spec/` directory use [RSpec](http://rspec.info/) as their test framework. These tests are generally standalone and do not generally require any actual Cisco hardware or virtual machines to test against.
+
+### Running a single RSpec test
+
+You can execute a single spec file by name:
+
+```bash
+rspec spec/environment_spec.rb
+```
+
+### Running all RSpec tests
+
+
+```bash
+rake spec
+```
+
+## Minitest tests
+
+The test files located in the `tests/` directory use [minitest](https://github.com/seattlerb/minitest/) as their test framework. These tests generally require one or more Cisco routers, switches, or virtual machines to test against.
+
+It is recommended that you create a `cisco_node_utils.yaml` file (as described in [README.md](../README.md#configuration) to specify the node(s) under test, but if you do not create such a file, the test will prompt you to enter the required information at runtime:
+
+```bash
+$ rake test
+Enter address or hostname of node under test: 192.168.100.1
+Enter username for node under test:           user
+Enter password for node under test:           password
+```
+
+### Running a single minitest test
+
+You can execute a single test file by name. If you do not specify the `-e` / `--environment` option, the node labeled as `default` in `cisco_node_utils.yaml` will be used (or, if no such entry exists, you will be prompted to enter the required information as shown above):
+
+```bash
+# Run test against the 'default' node:
+$ ruby tests/test_node.rb
+# Run test against node 'n7k':
+$ ruby tests/test_node.rb --environment n7k
+# Run test against node 'n9k':
+$ ruby tests/test_node.rb -e n9k
+```
+
+### Running all minitest tests
+
+As above, if you do not specify the `--environment` option, the `default` node will be used or you will be prompted if necessary.
+
+```bash
+# Run all tests against the 'default' node:
+$ rake test
+# Run all tests against 'n7k':
+$ rake test TEST_OPTS='--environment=n7k'
+```

data/docs/README-utilities.md

@@ -0,0 +1,14 @@
+# Executable utilities included in this gem
+
+## check_metric_limits.rb
+
+This is a helper script for developers. If you're doing refactoring work to
+reduce the code complexity metrics, you can run this script to report the
+worst offenders for each metric and whether you've managed to improve any
+metrics compared to the baseline.  Run this script from the base
+cisco-network-node-utils directory to report metrics of code in the
+./lib and ./tests directories.
+
+```bash
+[cisco-network-node-utils]$ ruby bin/check_metric_limits.rb
+```

data/docs/cisco_node_utils.yaml.example

@@ -0,0 +1,36 @@
+# The entry labeled 'default' will be used by default.
+# The user can select a different entry by name if desired.
+#
+# default:
+#   host: foo
+
+# Example config for running NXAPI remotely:
+nxapi_remote:
+  host: 192.168.1.100
+  username: devops
+  password: devops
+
+# Example config for running NXAPI on a node:
+nxapi_local:
+  # (none needed)
+
+# Example config for running NXAPI on a node with default cookie override:
+# User 'nxapi' must be configured with requisite privilages to configure the device.
+# This will override the default 'admin:local' cookie and use 'nxapi:local' instead.
+default:
+  cookie: 'nxapi:local'
+
+# Example config for running gRPC remotely:
+grpc_remote:
+  host: 192.168.1.100
+  # gRPC port defaults to 57400 if unset
+  # port: 57400
+  username: admin
+  password: admin
+
+# Example config for running gRPC on a node:
+grpc_local:
+  port: 57999
+  username: admin
+  password: admin
+

data/docs/template-router.rb

@@ -0,0 +1,123 @@
+# Copyright (c) 2014-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 'node_util'
+
+module Cisco
+  # X__CLASS_NAME__X - node utility class for X__CLASS_NAME__X config mgmt.
+  class X__CLASS_NAME__X < NodeUtil
+    attr_reader :name
+
+    # name: name of the router instance
+    # instantiate: true = create router instance
+    def initialize(name, instantiate=true)
+      fail ArgumentError unless name.length > 0
+      @name = name
+      create if instantiate
+    end
+
+    def to_s
+      "X__CLASS_NAME__X '#{name}'"
+    end
+
+    # Create a hash of all current router instances.
+    def self.routers
+      instances = config_get('X__RESOURCE_NAME__X', 'router')
+      return {} if instances.nil?
+      hash = {}
+      instances.each do |name|
+        hash[name] = X__CLASS_NAME__X.new(name, false)
+      end
+      return hash
+    rescue Cisco::CliError => e
+      # CLI will syntax reject when feature is not enabled
+      raise unless e.clierror =~ /Syntax error/
+      return {}
+    end
+
+    def feature_enabled
+      config_get('X__RESOURCE_NAME__X', 'feature')
+    rescue Cisco::CliError => e
+      # This cmd will syntax reject if feature is not
+      # enabled. Just catch the reject and return false.
+      return false if e.clierror =~ /Syntax error/
+      raise
+    end
+
+    def feature_enable
+      config_set('X__RESOURCE_NAME__X', 'feature', state: '')
+    end
+
+    def feature_disable
+      config_set('X__RESOURCE_NAME__X', 'feature', state: 'no')
+    end
+
+    # Enable feature and create router instance
+    def create
+      feature_enable unless feature_enabled
+      X__RESOURCE_NAME__X_router
+    end
+
+    # Destroy a router instance; disable feature on last instance
+    def destroy
+      ids = config_get('X__RESOURCE_NAME__X', 'router')
+      return if ids.nil?
+      if ids.size == 1
+        feature_disable
+      else
+        X__RESOURCE_NAME__X_router('no')
+      end
+    rescue Cisco::CliError => e
+      # CLI will syntax reject when feature is not enabled
+      raise unless e.clierror =~ /Syntax error/
+    end
+
+    def X__RESOURCE_NAME__X_router(state='')
+      config_set('X__RESOURCE_NAME__X', 'router', name: @name, state: state)
+    end
+
+    # ----------
+    # PROPERTIES
+    # ----------
+
+    # Property methods for boolean property
+    def default_X__PROPERTY_BOOL__X
+      config_get_default('X__RESOURCE_NAME__X', 'X__PROPERTY_BOOL__X')
+    end
+
+    def X__PROPERTY_BOOL__X
+      config_get('X__RESOURCE_NAME__X', 'X__PROPERTY_BOOL__X', name: @name)
+    end
+
+    def X__PROPERTY_BOOL__X=(state)
+      state = (state ? '' : 'no')
+      config_set('X__RESOURCE_NAME__X', 'X__PROPERTY_BOOL__X',
+                 name: @name, state: state)
+    end
+
+    # Property methods for integer property
+    def default_X__PROPERTY_INT__X
+      config_get_default('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X')
+    end
+
+    def X__PROPERTY_INT__X
+      config_get('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X', name: @name)
+    end
+
+    def X__PROPERTY_INT__X=(val)
+      config_set('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X',
+                 name: @name, val: val)
+    end
+  end
+end

data/docs/template-test_router.rb

@@ -0,0 +1,104 @@
+# Copyright (c) 2014-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 'ciscotest'
+require_relative '../lib/cisco_node_utils/router_X__RESOURCE_NAME__X'
+
+# TestX__CLASS_NAME__X - Minitest for X__CLASS_NAME__X node utility class
+class TestX__CLASS_NAME__X < CiscoTestCase
+  def setup
+    # setup runs at the beginning of each test
+    super
+    no_feature_X__RESOURCE_NAME__X
+  end
+
+  def teardown
+    # teardown runs at the end of each test
+    no_feature_X__RESOURCE_NAME__X
+    super
+  end
+
+  def no_feature_X__RESOURCE_NAME__X
+    # Turn the feature off for a clean test.
+    config('no feature X__RESOURCE_NAME__X')
+  end
+
+  # TESTS
+
+  def test_router_create_destroy_one
+    id = 'blue'
+    rtr = X__CLASS_NAME__X.new(id)
+    @default_show_command = "show runn | i 'router X__RESOURCE_NAME__X #{id}'"
+    assert_show_match(pattern: /^router X__RESOURCE_NAME__X #{id}$/,
+                      msg:     "failed to create router X__RESOURCE_NAME__X #{id}")
+
+    rtr.destroy
+    refute_show_match(pattern: /^router X__RESOURCE_NAME__X #{id}$/,
+                      msg:     "failed to destroy router X__RESOURCE_NAME__X #{id}")
+
+    refute_show_match(command: "show runn | i 'feature X__RESOURCE_NAME__X'",
+                      pattern: /^feature X__RESOURCE_NAME__X$/,
+                      msg:     'failed to disable feature X__RESOURCE_NAME__X')
+  end
+
+  def test_router_create_destroy_multiple
+    id1 = 'blue'
+    rtr1 = X__CLASS_NAME__X.new(id1)
+    id2 = 'red'
+    rtr2 = X__CLASS_NAME__X.new(id2)
+
+    @default_show_command = "show runn | i 'router X__RESOURCE_NAME__X'"
+
+    assert_show_match(pattern: /^router X__RESOURCE_NAME__X #{id1}$/,
+                      msg:     "failed to create router X__RESOURCE_NAME__X #{id1}")
+
+    assert_show_match(pattern: /^router X__RESOURCE_NAME__X #{id2}$/,
+                      msg:     "failed to create router X__RESOURCE_NAME__X #{id2}")
+
+    rtr1.destroy
+    refute_show_match(pattern: /^router X__RESOURCE_NAME__X #{id1}$/,
+                      msg:     "failed to destroy router X__RESOURCE_NAME__X #{id1}")
+
+    rtr2.destroy
+    refute_show_match(pattern: /^router X__RESOURCE_NAME__X #{id2}$/,
+                      msg:     "failed to destroy router X__RESOURCE_NAME__X #{id2}")
+
+    refute_show_match(command: "show runn | i 'feature X__RESOURCE_NAME__X'",
+                      pattern: /^feature X__RESOURCE_NAME__X$/,
+                      msg:     'failed to disable feature X__RESOURCE_NAME__X')
+  end
+
+  def test_router_X__PROPERTY_INT__X
+    id = 'blue'
+    rtr = X__CLASS_NAME__X.new(id)
+    val = 5 # This value depends on property bounds
+    rtr.X__PROPERTY_INT__X = val
+    assert_equal(rtr.X__PROPERTY_INT__X, val, "X__PROPERTY_INT__X is not #{val}")
+
+    # Get default value from yaml
+    val = node.config_get_default('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X')
+    rtr.X__PROPERTY_INT__X = val
+    assert_equal(rtr.X__PROPERTY_INT__X, val, "X__PROPERTY_INT__X is not #{val}")
+  end
+
+  def test_router_X__PROPERTY_BOOL__X
+    id = 'blue'
+    rtr = X__CLASS_NAME__X.new(id)
+    rtr.X__PROPERTY_BOOL__X = true
+    assert(rtr.X__PROPERTY_BOOL__X, 'X__PROPERTY_BOOL__X state is not true')
+
+    rtr.X__PROPERTY_BOOL__X = false
+    refute(rtr.X__PROPERTY_BOOL__X, 'X__PROPERTY_BOOL__X state is not false')
+  end
+end

data/ext/mkrf_conf.rb

@@ -0,0 +1,63 @@
+# Inspired by:
+# https://github.com/ruby-debug/ruby-debug-ide/blob/master/ext/mkrf_conf.rb
+
+# This file needs to be named mkrf_conf.rb
+# so that rubygems will recognize it as a ruby extension
+# file and not think it is a C extension file
+
+require 'rubygems/specification'
+require 'rubygems/dependency'
+require 'rubygems/dependency_installer'
+
+# Load up the rubygems dependency installer to install the dependencies
+# we need based on the platform we are running under.
+installer = Gem::DependencyInstaller.new
+deps = []
+begin
+  # Try to detect Cisco NX-OS and IOS XR environments
+  os = nil
+  if File.exist?('/etc/os-release')
+    cisco_release_file = nil
+    File.foreach('/etc/os-release') do |line|
+      next unless line[/^CISCO_RELEASE_INFO=/]
+      cisco_release_file = line[/^CISCO_RELEASE_INFO=(.*)$/, 1]
+      break
+    end
+    unless cisco_release_file.nil?
+      File.foreach(cisco_release_file) do |line|
+        next unless line[/^ID=/]
+        os = line[/^ID=(.*)$/, 1]
+        break
+      end
+    end
+  end
+  puts "Detected client OS as '#{os}'" unless os.nil?
+
+  # IOS XR doesn't need net_http_unix
+  os == 'ios_xr' || deps << Gem::Dependency.new('net_http_unix',
+                                                '~> 0.2', '>= 0.2.1')
+  # NX-OS doesn't need gRPC
+  os == 'nexus' || deps << Gem::Dependency.new('grpc', '~> 1.30.0')
+
+  deps.each do |dep|
+    installed = dep.matching_specs
+    if installed.empty?
+      puts "Installing #{dep}"
+      installed = installer.install dep
+      fail installer.errors[0] unless installer.errors.empty?
+      fail "Did not install #{dep}" if installed.empty?
+    else
+      puts "Found installed gems matching #{dep}:"
+      installed.each { |i| puts "  #{i.name} (#{i.version})" }
+    end
+  end
+rescue StandardError => e
+  puts e
+  puts e.backtrace.join("\n  ")
+  exit(1)
+end
+
+# Create a dummy Rakefile to report successful 'compilation'
+f = File.open(File.join(File.dirname(__FILE__), 'Rakefile'), 'w')
+f.write("task :default\n")
+f.close

data/lib/.rubocop.yml

@@ -0,0 +1,18 @@
+inherit_from: ../.rubocop.yml
+
+# Baseline code complexity metrics for the lib/ subdirectory:
+
+Metrics/AbcSize:
+  Max: 49
+
+Metrics/CyclomaticComplexity:
+  Max: 23
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ParameterLists:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 24

data/lib/cisco_node_utils/aaa_authentication_login.rb

@@ -0,0 +1,95 @@
+#
+# NXAPI implementation of AaaAuthenticationLogin class
+#
+# April 2015, Alex Hunsberger
+#
+# 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 'node_util'
+
+module Cisco
+  # NXAPI implementation of AAA Authentication Login class
+  class AaaAuthenticationLogin < NodeUtil
+    # There is no "feature aaa" or "aaa new-model" on nxos, and only one
+    # instance which is always available
+    def self.ascii_authentication
+      config_get('aaa_authentication_login', 'ascii_authentication')
+    end
+
+    def self.ascii_authentication=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login',
+                 'ascii_authentication', no_cmd)
+    end
+
+    def self.default_ascii_authentication
+      config_get_default('aaa_authentication_login',
+                         'ascii_authentication')
+    end
+
+    def self.chap
+      config_get('aaa_authentication_login', 'chap')
+    end
+
+    def self.chap=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login', 'chap', no_cmd)
+    end
+
+    def self.default_chap
+      config_get_default('aaa_authentication_login', 'chap')
+    end
+
+    def self.error_display
+      config_get('aaa_authentication_login', 'error_display')
+    end
+
+    def self.error_display=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login', 'error_display', no_cmd)
+    end
+
+    def self.default_error_display
+      config_get_default('aaa_authentication_login', 'error_display')
+    end
+
+    def self.mschap
+      config_get('aaa_authentication_login', 'mschap')
+    end
+
+    def self.mschap=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login', 'mschap', no_cmd)
+    end
+
+    def self.default_mschap
+      config_get_default('aaa_authentication_login', 'mschap')
+    end
+
+    def self.mschapv2
+      config_get('aaa_authentication_login', 'mschapv2')
+    end
+
+    def self.mschapv2=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login', 'mschapv2', no_cmd)
+    end
+
+    def self.default_mschapv2
+      config_get_default('aaa_authentication_login', 'mschapv2')
+    end
+  end
+end

data/lib/cisco_node_utils/aaa_authentication_login_service.rb

@@ -0,0 +1,138 @@
+#
+# NXAPI implementation of AaaAuthenticationLoginService class
+#
+# May 2015, Alex Hunsberger
+#
+# 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 'node_util'
+
+module Cisco
+  # NXAPI implementation of AAA Authentication Login Service class
+  class AaaAuthenticationLoginService < NodeUtil
+    attr_reader :name
+
+    def initialize(name, create=true)
+      fail TypeError unless name.is_a? String
+      # only console and default are supported currently
+      fail ArgumentError unless %w(console default).include? name
+      @name = name
+
+      # console needs to be explicitly created before it appears in
+      # "show run aaa all" but oddly not before it shows up in
+      # "show aaa authentication"
+      return unless create
+      m = default_method.to_s
+      config_set('aaa_auth_login_service', 'method', '', name, m)
+    end
+
+    def self.services
+      servs = {}
+      servs_arr = config_get('aaa_auth_login_service', 'services')
+      unless servs_arr.nil?
+        servs_arr.each do |s|
+          servs[s] = AaaAuthenticationLoginService.new(s, false)
+        end
+      end
+      servs
+    end
+
+    def destroy
+      # must specify exact current config string to unconfigure
+      m = method
+      m_str = m == :unselected ? '' : m.to_s
+      g_str = groups.join(' ')
+
+      if g_str.empty?
+        # cannot remove default local, so do nothing in this case
+        unless m == :local
+          unless node.product_id[/N(3|9)K-F/]
+            # TBD: These 'no' commands currently error on N(3|9)K-F
+            #   no aaa authentication login console local
+            #   no aaa authentication login console none
+            config_set('aaa_auth_login_service', 'method',
+                       'no', @name, m_str)
+          end
+        end
+      else
+        config_set('aaa_auth_login_service', 'groups',
+                   'no', @name, g_str, m_str)
+      end
+    end
+
+    # groups aren't retrieved via the usual CLI regex memory method because
+    # there can be an arbitrary number of groups and specifying a repeating
+    # memory regex only captures the last match
+    # ex: aaa authentication login default group group1 group2 group3 none
+    def groups
+      # config_get returns the following format:
+      # [{service:"default",method:"group group1 none "},
+      #  {service:"console",method:"local "}]
+      hsh_arr = config_get('aaa_auth_login_service', 'groups')
+      fail 'unable to retrieve aaa groups information' if hsh_arr.empty?
+      hsh = hsh_arr.find { |x| x['service'] == @name }
+      # this should never happen unless @name is invalid
+      fail "no aaa info found for service #{@name}" if hsh.nil?
+      fail "no method found for #{@name} - api or feature change?" unless
+        hsh.key? 'method'
+      # ex: ["group", "group1", "local"] or maybe ["none"]
+      grps = hsh['method'].strip.split
+      return [] if grps.size == 1
+      # remove local, none, group keywords
+      grps -= %w(none local group)
+      grps
+    end
+
+    # default is []
+    def default_groups
+      config_get_default('aaa_auth_login_service', 'groups')
+    end
+
+    def method
+      m = config_get('aaa_auth_login_service', 'method', @name)
+      m.nil? ? :unselected : m.to_sym
+    end
+
+    # default is :local
+    def default_method
+      config_get_default('aaa_auth_login_service', 'method')
+    end
+
+    # groups and method must be set in the same CLI string
+    # aaa authentication login { console | default } /
+    #   none | local | group <group1 [group2, ...]> [none]
+    def groups_method_set(grps, m)
+      fail TypeError unless grps.is_a? Array
+      fail TypeError unless grps.all? { |x| x.is_a? String }
+      fail TypeError unless m.is_a? Symbol
+      # only the following 3 are supported (unselected = blank)
+      fail ArgumentError unless [:none, :local, :unselected].include? m
+
+      fail "method 'local' not allowed when groups are configured" if
+        m == :local && !grps.empty?
+      m_str = m == :unselected ? '' : m.to_s
+      g_str = grps.join(' ')
+
+      # config_set depends on whether we're setting groups or not
+      if g_str.empty?
+        config_set('aaa_auth_login_service', 'method',
+                   '', @name, m_str)
+      else
+        config_set('aaa_auth_login_service', 'groups',
+                   '', @name, g_str, m_str)
+      end
+    end
+  end
+end