cisco_node_utils 1.2.0 → 1.3.0

data/docs/README-develop-node-utils-APIs.md

@@ -22,47 +22,92 @@ There are multiple components involved when creating new resources. This documen
 
 ## <a name="prerequisites">Before You Begin</a>
 
-Please note: A virtual Nexus N9000/N3000 may be helpful for development and testing. Users with a valid [cisco.com](http://cisco.com) user ID can obtain a copy of a virtual Nexus N9000/N3000 by sending their [cisco.com](http://cisco.com) user ID in an email to <get-n9kv@cisco.com>. If you do not have a [cisco.com](http://cisco.com) user ID please register for one at [https://tools.cisco.com/IDREG/guestRegistration](https://tools.cisco.com/IDREG/guestRegistration)
+### <a name="prereq_git">Git Configuration</a>
 
-This development guide uses tools that are packaged as gems that need to be installed on your server.
+Any code commits must be associated with your github account and email address.  If you intend to commit code to this repository then you must configure `git` with your identity.  If you have not already done so, use the following commands to configure the default identity that `git` will use for all projects on your system:
 
 ```bash
-gem install cisco_nxapi
-gem install rake
-gem install rubocop
-gem install simplecov
-gem install minitest
+git config --global user.name "John Doe"
+git config --global user.email johndoe@example.com
+```
+If you do not wish to change the global configuration on your system, you can set your identity for a single local repository by using the above commands without the ``--global`` flag.
+
+### <a name="prereq_ruby">Ruby Prerequisites</a>
+
+This project requires Ruby 2.0 or later.
+
+This development guide uses tools that are packaged as gems that need to be installed in your development environment. You can install the gems manually but it's recommended to use [Bundler](https://rubygems.org/gems/bundler) to guarantee the dependencies are all present.
+
+```bash
+gem install bundler
+```
+At present the following gems are needed to work on this code base - if you wish to install them all manually instead of through Bundler, you can run:
+
+```bash
+gem install grpc kwalify minitest net_http_unix rake rspec simplecov
+gem install rubocop --version 0.35.1
+```
+
+**NOTE:** If you are working from a server where you don't have admin/root privileges, use the following commands to install the gems:
+
+```bash
+gem install --user-install bundler
+gem install --user-install grpc kwalify minitest net_http_unix rake rspec simplecov
+gem install --user-install rubocop --version 0.35.1
 ```
+or add `--user-install` to your `.gemrc` to make this the default behavior:
 
-**NOTE:** If you are working from a server where you don't have admin/root privilages, use the following commands to install the gems and then update the `PATH` to include `~/.gem/ruby/x.x.x/bin`
+```bash
+echo 'gem: --user-install' >> ~/.gemrc
+```
+and then update the `PATH` to include `~/.gem/ruby/x.x.x/bin`.  For example, you could add this to your `.bashrc` or `.profile`:
 
 ```bash
-gem install --user-install cisco_nxapi
-gem install --user-install rake
-gem install --user-install rubocop
-gem install --user-install simplecov
-gem install --user-install minitest
+if which ruby >/dev/null && which gem >/dev/null; then
+    PATH="$(ruby -rubygems -e 'puts Gem.user_dir')/bin:$PATH"
+fi
 ```
 
+### <a name="prereq_vm">Nexus VM (optional)</a>
+
+A virtual Nexus N9000/N3000 may be helpful for development and testing. Users with a valid [cisco.com](http://cisco.com) user ID can obtain a copy of a virtual Nexus N9000/N3000 by sending their [cisco.com](http://cisco.com) user ID in an email to <get-n9kv@cisco.com>. If you do not have a [cisco.com](http://cisco.com) user ID please register for one at [https://tools.cisco.com/IDREG/guestRegistration](https://tools.cisco.com/IDREG/guestRegistration)
+
+
 ## <a name="clone">Start here: Fork and Clone the Repo</a>
 
-First [fork](https://help.github.com/articles/fork-a-repo) the [cisco-network-node-utils](https://github.com/cisco/cisco-network-node-utils) git repository 
+First [fork](https://help.github.com/articles/fork-a-repo) the [cisco-network-node-utils](https://github.com/cisco/cisco-network-node-utils) repository on GitHub.
 
-Next install the code base. Clone the cisco-network-node-utils repo from your fork into a workspace:
+Next create your local repository. Clone the cisco-network-node-utils repo from your fork into a workspace:
 
 ```bash
 git clone https://github.com/YOUR-USERNAME/cisco-network-node-utils.git
 cd cisco-network-node-utils/
 ```
 
-Please note that any code commits must be associated with your github account and email address. If you intend to commit code to this repository then use the following commands to update your workspace with your credentials:
+If you're using Bundler, invoke it to ensure all of the development dependencies are installed on your system:
 
 ```bash
-git config --global user.name "John Doe"
-git config --global user.email johndoe@example.com
+bundle install
+```
+
+or (if you don't have admin/root privileges and have used `--user-install` to install Bundler):
+
+```bash
+~/.gem/ruby/$RUBY_VERSION/bin/bundle install --path ~/.gem
 ```
 
-As a best practice create a topic/feature branch for your feature work using the `git branch feature/<feature_name>` command.
+Optionally create the file `~/cisco_node_utils.yaml` to specify how the test scripts will connect to your Nexus VM or other node under test. Refer to the project [README](../README.md#configuration) for details.
+
+If you intend to contribute your code back to the project then you should install the git hooks that are checked in with the project source code.  These hooks check your commits for conformance with various style guidelines.  To install them in your local repository (or to update them to match the files currently in the repository, in case they are out of sync), simply run the `update-hooks` script:
+
+```bash
+bin/git/update-hooks
+```
+
+
+## <a name="complex">Example: router eigrp</a>
+
+As a best practice, create a topic branch (also sometimes called a feature branch) for your feature work using the `git branch feature/<feature_name>` command.
 
 ```bash
 git branch feature/eigrp
@@ -71,10 +116,7 @@ git branch
   feature/eigrp
 ```
 
-
-## <a name="complex">Example: router eigrp</a>
-
-Before you start working on the eigrp feature, checkout the feature branch you created earlier.
+Before you start working on the eigrp feature, checkout its topic branch, `feature/eigrp`.
 
 ```bash
 git checkout feature/eigrp
@@ -111,15 +153,15 @@ YAML files in the `/cmd_ref/` subdirectory are automatically discovered at runti
 
 The following basic command_reference parameters will be defined for each resource property:
 
- 1. `config_get:` This defines the NX-OS CLI command (usually a 'show...' command) used to retrieve the property's current configuration state. Note that some commands may not be present until a feature is enabled.
- 2. `config_get_token:` A regexp pattern for extracting state values from the config_get output.
- 3. `config_set:` The NX-OS CLI configuration command(s) used to set the property configuration. May contain wildcards for variable parameters.
+ 1. `get_command:` This defines the CLI command (usually a 'show...' command) or similar request string used to retrieve the property's current configuration state. Note that some commands may not be present on NX-OS until a pre-requisite feature is enabled.
+ 2. `get_value:` A regexp pattern for extracting state values from the get_command output.
+ 3. `set_value:` The configuration command(s) used to set the property configuration. May contain wildcards for variable parameters.
  4. `default_value:` This is typically the "factory" default state of the property, expressed as an actual value (true, 12, "off", etc)
  5. `kind:` The data type of this property. If omitted, the property will be a string by default. Commonly used values for this property are `int` and `boolean`.
- 6. `multiple:` By default a property is assumed to be found once or not at all by the `config_get`/`config_get_token` lookup, and an error will be raised if multiple matches are found. If multiple matches are valid and expected, you must set `multiple: true` for this property.
+ 6. `multiple:` By default a property is assumed to be found once or not at all by the `get_command`/`get_value` lookup, and an error will be raised if multiple matches are found. If multiple matches are valid and expected, you must set `multiple: true` for this property.
 
 There are additional YAML command parameters available which are not covered by this document. Please see the [README_YAML.md](../lib/cisco_node_utils/cmd_ref/README_YAML.md) document for more information on the structure and semantics of these files.
-The properties in this example require additional context for their config_get_token values because they need to differentiate between different eigrp instances. Most properties will also have a default value.
+The properties in this example require additional context for their `get_value` and `set_value` because they need to differentiate between different eigrp instances. This is done with the `context` parameter. (For more complex properties, you can define `get_context` and `set_context` separately if needed.) Most properties will also have a default value.
 
 *Note: Eigrp also has vrf and address-family contexts. These contexts require additional coding and are beyond the scope of this document.*
 
@@ -135,31 +177,35 @@ The properties in this example require additional context for their config_get_t
 feature:
   # feature eigrp must be enabled before configuring router eigrp
   kind: boolean
-  config_get: 'show running eigrp all'
-  config_get_token: '/^feature eigrp$/'
-  config_set: '<state> feature eigrp'
+  get_command: 'show running eigrp all'
+  get_value: 'feature eigrp'
+  set_value: '<state> feature eigrp'
 
 maximum_paths:
   # This is an integer property
   kind: int
-  config_get: 'show running eigrp all'
-  config_get_token: ['/^router eigrp <name>$/', '/^maximum-paths (\d+)/']
-  config_set: ['router eigrp <name>', 'maximum-paths <val>']
+  context:
+    - 'router eigrp <name>'
+  get_command: 'show running eigrp all'
+  get_value: 'maximum-paths (\d+)'
+  set_value: 'maximum-paths <val>'
   default_value: 8
 
 router:
   # There can be multiple eigrp instances
   multiple: true
-  config_get: 'show running eigrp all'         # all eigrp-related configs
-  config_get_token: '/^router eigrp (\S+)$/'   # Match instance name
-  config_set: '<state> router eigrp <name>'    # config to add or remove
+  get_command: 'show running eigrp all'         # all eigrp-related configs
+  get_value: 'router eigrp (\S+)'   # Match instance name
+  set_value: '<state> router eigrp <name>'    # config to add or remove
 
 shutdown:
   # This is a boolean property
   kind: boolean
-  config_get: 'show running eigrp all'
-  config_get_token: ['/^router eigrp <name>$/', '/^shutdown$/']
-  config_set: ['router eigrp <name>', '<state> shutdown']
+  context:
+    - 'router eigrp <name>'
+  get_command: 'show running eigrp all'
+  get_value: 'shutdown'
+  set_value: '<state> shutdown'
   default_value: false
 ```
 
@@ -218,6 +264,10 @@ module Cisco
       create if instantiate
     end
 
+    def to_s
+      "RouterEigrp '#{name}'"
+    end
+
     # Create a hash of all current router instances.
     def self.routers
       instances = config_get('eigrp', 'router')
@@ -443,10 +493,10 @@ class TestRouterEigrp < CiscoTestCase
 end
 ```
 
-Now run the test:
+Now run the test (see [README-test-execution](README-test-execution.md) for detailed instructions):
 
 ```bash
-% ruby test_router_eigrp.rb -v -- 192.168.0.1 admin admin
+% ruby test_router_eigrp.rb -v --environment my_nexus_vm
 Run options: -v -- --seed 56593
 
 # Running:

data/docs/README-maintainers.md

@@ -8,7 +8,7 @@ Guidelines for the core maintainers of the cisco-network-node-utils project - ab
 * Does `rubocop` pass? (TODO - this will be part of our CI integration to run automatically)
 * Is `CHANGELOG.md` updated appropriately?
 * Are new minitests added? Do they provide sufficient coverage and consistent results?
-* Do minitests pass on both N9K and N3K?
+* Do minitests pass on all supported platforms
 
 ## Setting up git-flow
 
@@ -45,6 +45,9 @@ When we are considering publishing a new release, all of the following steps mus
   * Platforms (all with latest released software or release candidate)
     - N30xx
     - N31xx
+    - N56xx
+    - N6xxx
+    - N7xxx
     - N9xxx
 
 3. Triage any minitest failures.
@@ -75,15 +78,15 @@ When the release checklist above has been fully completed, the process for publi
     ```diff
      Changelog
      =========
- 
+
     -(unreleased)
     -------------
     +1.0.1
     +-----
     ```
-    
+
     and also update `version.rb`:
-    
+
     ```diff
     -  VERSION = '1.0.0'
     +  VERSION = '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/cisco_node_utils.yaml.example

@@ -0,0 +1,30 @@
+# 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 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

@@ -27,6 +27,10 @@ module Cisco
       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')

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', '~> 0.12')
+
+  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

@@ -3,13 +3,13 @@ inherit_from: ../.rubocop.yml
 # Baseline code complexity metrics for the lib/ subdirectory:
 
 Metrics/AbcSize:
-  Max: 45
+  Max: 49
 
 Metrics/CyclomaticComplexity:
   Max: 23
 
 Metrics/MethodLength:
-  Max: 48
+  Max: 50
 
 Metrics/ParameterLists:
   Max: 9

data/lib/cisco_node_utils.rb

@@ -12,5 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Declare module here as files referenced in glob-order below may assume
+# module already exists.
+module Cisco
+end
+
 # Automatically load all Ruby files in the cisco_node_utils subdirectory
 Dir.glob(__dir__ + '/cisco_node_utils/*.rb') { |file| require file }

data/lib/cisco_node_utils/aaa_authentication_login.rb

@@ -23,11 +23,10 @@ require_relative 'node_util'
 module Cisco
   # NXAPI implementation of AAA Authentication Login class
   class AaaAuthenticationLogin < NodeUtil
-    # rubocop:disable DoubleNegation
     # 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')
+      config_get('aaa_authentication_login', 'ascii_authentication')
     end
 
     def self.ascii_authentication=(val)
@@ -42,7 +41,7 @@ module Cisco
     end
 
     def self.chap
-      !!config_get('aaa_authentication_login', 'chap')
+      config_get('aaa_authentication_login', 'chap')
     end
 
     def self.chap=(val)
@@ -55,7 +54,7 @@ module Cisco
     end
 
     def self.error_display
-      !!config_get('aaa_authentication_login', 'error_display')
+      config_get('aaa_authentication_login', 'error_display')
     end
 
     def self.error_display=(val)
@@ -68,7 +67,7 @@ module Cisco
     end
 
     def self.mschap
-      !!config_get('aaa_authentication_login', 'mschap')
+      config_get('aaa_authentication_login', 'mschap')
     end
 
     def self.mschap=(val)
@@ -81,7 +80,7 @@ module Cisco
     end
 
     def self.mschapv2
-      !!config_get('aaa_authentication_login', 'mschapv2')
+      config_get('aaa_authentication_login', 'mschapv2')
     end
 
     def self.mschapv2=(val)