cisco_node_utils 1.0.1 → 1.1.0

data/cisco_node_utils.gemspec

@@ -16,15 +16,21 @@ Designed to work with Puppet and Chef.
 Currently supports NX-OS nodes.
   EOF
   spec.license       = 'Apache-2.0'
+  spec.homepage      = 'https://github.com/cisco/cisco-network-node-utils'
 
   spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  # Files in bin/git are not executables as far as the Gem is concerned
+  spec.executables   = []
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'minitest', '>= 2.5.1', '< 5.0.0'
+  spec.required_ruby_version     = '>= 2.0.0'
+  spec.required_rubygems_version = '>= 2.1.0'
+
+  spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rubocop', '>= 0.32'
+  spec.add_development_dependency 'rubocop', '= 0.34.2'
+  spec.add_development_dependency 'simplecov', '~> 0.9'
   spec.add_runtime_dependency 'cisco_nxapi', '~> 1.0'
 end

data/docs/README-develop-best-practices.md

@@ -0,0 +1,404 @@
+# Develoment Best Practices for cisco_node_utils APIs.
+
+* [Overview](#overview)
+* [YAML Development Best Practices](#ydbp)
+* [Common Object Development Best Practices](#odbp)
+* [MiniTest Development Best Practices](#mdbp)
+
+## <a name="overview">Overview</a>
+
+This document is intended to assist in developing cisco_node_utils API's that are consistent with current best practices.
+
+
+## <a name="ydbp">YAML Development Best Practices</a>
+
+* [Y1](#yaml1): All yaml feature entries should be kept in alphabetical order.
+* [Y2](#yaml2): Use *regexp* anchors where needed for `config_get` and `config_get_token` entries.
+* Y3: Avoid nested optional matches.
+* [Y4](#yaml4): Use the `_template` feature when getting/setting the same property value at multiple levels.
+* [Y5](#yaml5): When possible include a `default_value` that represents the system default value.
+* [Y6](#yaml6): When possible, use the same `config_get` show command for all properties and document any anomalies.
+* [Y7](#yaml7): Use Key-value wildcards instead of Printf-style wildcards.
+* [Y8](#yaml8): Selection of `show` commands for `config_get`.
+
+
+
+## <a name="odbp">Common Object Development Best Practices</a>
+
+* [CO1](#co1): Features that can be configured under the global and non-global vrfs need to account for this in the object design.
+* [CO2](#co2): Make use of the equality operator allowing proper `instance1 == instance2` checks in the minitests.
+* [CO3](#co3): Use `''` rather than `nil` to represent "property is absent entirely"
+* [CO4](#co4): Make sure all new properites have a `getter`, `setter` and `default_getter` method.
+* [CO5](#co5): Use singleton-like design for resources that cannot have multiple instances.
+
+## <a name="mdbp">MiniTest Development Best Practices</a>
+
+* [MT1](#mt1): Ensure that **all new API's** have minitest coverage.
+* [MT2](#mt2): Use appropriate `assert_foo` and `refute_foo` statements rather than `assert_equal`.
+* [MT3](#mt3): Do not hardcode interface names.
+* [MT4](#mt4): Make use of the `config` helper method for device configuration instead of `@device.cmd`.
+* [MT5](#mt5): Make use of the `assert_show_match` and `refute_show_match` helper methods to validate expected outcomes in the CLI instead of `@device.cmd("show...")`.
+
+
+
+## YAML Best Practices:
+
+### <a name="yaml1">Y1: All yaml feature entries should be kept in alphabetical order.
+
+Please keep all feature names in alphabetical order, and all options under a feature in alphabetical order as well. As YAML permits duplicate entries (in which case the last entry overrides any earlier entries), keeping a consistent order helps to prevent accidentally introducing such duplication.
+
+Top level features in alpabetical order:
+
+```
+aaa_authentication_login:
+...
+dnsclient:
+...
+interface:
+```
+
+Options under a feature:
+
+```
+interface:
+  access_vlan:
+    ...
+  all_interfaces:
+    ...
+  create:
+    ...
+  description:
+    ...  
+```
+
+### <a name="yaml2">Y2: Use *regexp* anchors where needed for `config_get` and `config_get_token` entries.
+
+Please use *regexp* anchors `^$` to ensure you match the correct feature information in the `show` output.
+
+```
+syslog_settings:
+  timestamp:
+    config_get: "show running-config all | include '^logging timestamp'"
+    config_get_token: '/^logging timestamp (.*)$/'
+    config_set: '<state> logging timestamp <units>'
+    default_value: 'seconds'
+```
+
+### <a name="yaml3">Y3: Avoid nested optional matches.
+
+### <a name="yaml4">Y4: Use the `_template` feature when getting/setting the same property value at multiple levels.
+
+Using the template below, `auto_cost` and `default_metric` can be set under `router ospf foo` and `router ospf foo; vrf blue`.
+
+```
+ospf:
+  _template:
+    config_get: "show running ospf all"
+    config_get_token: '/^router ospf <name>$/'
+    config_get_token_append:
+      - '/^vrf <vrf>$/'
+    config_set: "router ospf <name>"
+    config_set_append:
+      - "vrf <vrf>"
+
+  auto_cost:
+    config_get_token_append: '/^auto-cost reference-bandwidth (\d+)\s*(\S+)?$/'
+    config_set_append: "auto-cost reference-bandwidth <cost> <type>"
+    default_value: [40, "Gbps"]
+
+  default_metric:
+    config_get_token_append: '/^default-metric (\d+)?$/'
+    config_set_append: "<state> default-metric <metric>"
+    default_value: 0
+```
+
+### <a name="yaml5">Y5: When possible include a `default_value` that represents the system default value.
+
+Please make sure to specify a `default_value` and document properties that don't have a system default.  System defaults may differ between cisco platforms making it important to define for lookup in the cisco_node_utils common object methods.
+
+
+Default value for `message_digest_alg_type` is `md5`
+
+```
+message_digest_alg_type:
+    config_get: 'show running interface all'
+    config_get_token: ['/^interface %s$/i', '/^\s*ip ospf message-digest-key \d+ (\S+)/']
+    default_value: 'md5'
+```
+
+**NOTE1: Use strings rather then symbols when applicable**.
+
+If the `default_value` differs between cisco platforms, the more specific `command_reference_[platform].yaml` file should be used.
+
+For example, if the default value on all platforms except the n9k is `md5` then set the entry in `command_reference_common.yaml` to `md5` and set the entry in `command_reference_n9k.yaml` to it's default `sha2`.
+
+### <a name="yaml6">Y6: When possible, use the same `config_get` show command for all properties and document any anomalies.
+
+All properties below use the `show run tacacs all` command except `directed_request` which is documented.
+
+```
+tacacs_server:
+  deadtime:
+    config_get: "show run tacacs all"
+    config_get_token: '/^tacacs-server deadtime\s+(\d+)/'
+    config_set: "%s tacacs-server deadtime %d"
+    default_value: 0
+
+  directed_request:
+    # oddly, directed request must be retrieved from aaa output
+    config_get: "show running aaa all"
+    config_get_token: '/(?:no)?\s*tacacs-server directed-request/'
+    config_set: "%s tacacs-server directed-request"
+    default_value: false
+
+  encryption_type:
+    config_get: "show run tacacs all"
+    config_get_token: '/^tacacs-server key (\d+)\s+(\S+)/'
+    default_value: 0
+
+  encryption_password:
+    config_get: "show run tacacs all"
+    config_get_token: '/^tacacs-server key (\d+)\s+(\S+)/'
+    default_value: ""
+```
+
+### <a name="yaml7">Y7: Use Key-value wildcards instead of Printf-style wildcards.
+
+The following approach is moderately more complex to implement but is more readable in the ruby code and is flexible enough to handle significant platform differences in CLI. It is therefore the recommended approach for new development.
+
+**Key-value wildcards**
+
+```
+config_set_append: "<state> log-adjacency-changes <type>"
+```
+
+This following approach is quick to implement and concise, but less flexible - in particular it cannot handle a case where different platforms take parameters in a different order - and less readable in the ruby code.
+
+**Printf-style wildcards**
+
+```
+config_set_append: "%s log-adjacency-changes %s"
+```
+
+### <a name="yaml8">Y8: Selection of `show` commands for `config_get`.
+
+The following commands should be preferred over `show [feature]` commands since not all `show [feature]` commands behave in the same manner across cisco platforms.
+
+* `show running [feature] all` if available.
+* `show running all` if `show running [feature] all` is *not* available.
+
+
+## Common Object Best Practices:
+
+### <a name="co1">CO1: Features that can be configured under the global and non-global vrfs need to account for this in the object design.
+
+Many cisco features can be configured under the default or global vrf and also under *n* number of non-default vrfs.
+
+The following `initialize` and `self.vrfs` methods account for configuration under `default` and `non-default vrfs`.
+
+```
+    def initialize(router, name, instantiate=true)
+      fail TypeError if router.nil?
+      fail TypeError if name.nil?
+      fail ArgumentError unless router.length > 0
+      fail ArgumentError unless name.length > 0
+      @router = router
+      @name = name
+      @parent = {}
+      if @name == 'default'
+        @get_args = @set_args = { name: @router }
+      else
+        @get_args = @set_args = { name: @router, vrf: @name }
+      end
+
+      create if instantiate
+    end
+
+    # Create a hash of all router ospf vrf instances
+    def self.vrfs
+      hash_final = {}
+      RouterOspf.routers.each do |instance|
+        name = instance[0]
+        vrf_ids = config_get('ospf', 'vrf', name: name)
+        hash_tmp = { name =>
+          { 'default' => RouterOspfVrf.new(name, 'default', false) } }
+        unless vrf_ids.nil?
+          vrf_ids.each do |vrf|
+            hash_tmp[name][vrf] = RouterOspfVrf.new(name, vrf, false)
+          end
+        end
+        hash_final.merge!(hash_tmp)
+      end
+      hash_final
+    end
+```
+
+### <a name="co2">CO2: Make use of the equality operator allowing proper `instance1 == instance2` checks in the minitests.
+
+Having this logic defined in the common object lets the minitest easily check the specific instances.
+
+Without this equality operator `==` only passes if they are the same instance object.  With this equality operator `==` passes if they are different objects referring to the same configuration on the node.
+
+```
+  def ==(other)
+    (name == other.name) && (vrf == other.vrf)
+  end
+```
+
+Example Usage:
+
+```
+  def test_dnsdomain_create_destroy_multiple
+    id1 = 'aoeu.com'
+    id2 = 'asdf.com'
+    refute_includes(Cisco::DnsDomain.dnsdomains, id1)
+    refute_includes(Cisco::DnsDomain.dnsdomains, id2)
+
+    ns1 = Cisco::DnsDomain.new(id1)
+    ns2 = Cisco::DnsDomain.new(id2)
+    assert_includes(Cisco::DnsDomain.dnsdomains, id1)
+    assert_includes(Cisco::DnsDomain.dnsdomains, id2)
+    assert_equal(Cisco::DnsDomain.dnsdomains[id1], ns1)
+    assert_equal(Cisco::DnsDomain.dnsdomains[id2], ns2)
+
+    ns1.destroy
+    refute_includes(Cisco::DnsDomain.dnsdomains, id1)
+    assert_includes(Cisco::DnsDomain.dnsdomains, id2)
+    ns2.destroy
+    refute_includes(Cisco::DnsDomain.dnsdomains, id2)
+  end
+```
+### <a name="co3">CO3: Use `''` rather than `nil` to represent "property is absent entirely"
+
+Our convention is to let `''` represent 'not configured at all' rather than `nil`. For example, `interface.rb`:
+
+```
+def vrf
+  vrf = config_get('interface', 'vrf', @name)
+  return '' if vrf.nil?
+  vrf.shift.strip
+end
+
+def vrf=(vrf)
+  fail TypeError unless vrf.is_a?(String)
+  if vrf.empty?
+    config_set('interface', 'vrf', @name, 'no', '')
+  else
+    config_set('interface', 'vrf', @name, '', vrf)
+  end
+```
+
+However, if a property has a default value (it is never truly 'removed'), then we should do this instead:
+
+```
+def access_vlan
+  vlan = config_get('interface', 'access_vlan', @name)
+  return default_access_vlan if vlan.nil?
+  vlan.shift.to_i
+end
+
+def access_vlan=(vlan)
+  config_set('interface', 'access_vlan', @name, vlan)
+```
+
+### <a name="co4">CO4: Make sure all new properites have a `getter`, `setter` and `default_getter` method.
+
+In order to have a complete set of api's for each property it is important that all properties have a `getter`, `setter` and `default_getter` method.
+
+This can be seen in the following `router_id` property.
+
+```
+# Getter Method
+def router_id
+  match = config_get('ospf', 'router_id', @get_args)
+  match.nil? ? default_router_id : match.first
+end
+
+# Setter Method
+def router_id=(router_id)
+  if router_id == default_router_id
+    @set_args[:state] = 'no'
+    @set_args[:router_id] = ''
+  else
+    @set_args[:state] = ''
+    @set_args[:router_id] = router_id
+  end
+
+  config_set('ospf', 'router_id', @set_args)
+  delete_set_args_keys([:state, :router_id])
+end
+
+# Default Getter Method
+def default_router_id
+  config_get_default('ospf', 'router_id')
+end
+```
+
+### <a name="co5">CO5: Use singleton-like design for resources that cannot have multiple instances.
+
+See [TacacsServer](../lib/cisco_node_utils/tacacs_server.rb) and [SnmpServer](../lib/cisco_node_utils/snmpserver.rb) for examples.
+
+## MiniTest Best Practices:
+
+### <a name="mt1">MT1: Ensure that *all new API's* have minitest coverage.
+
+### <a name="mt2">MT2: Use appropriate `assert_foo` and `refute_foo` statements rather than `assert_equal`.
+
+
+Minitest has a bunch of different test methods that are more specific than assert_equal. See [test methods](http://docs.ruby-lang.org/en/2.1.0/MiniTest/Assertions.html) for a complete list, but here are some general guidelines:
+
+| Instead of ...                | Use ...           |
+| ------------------------------|:-----------------:|
+| assert_equal(true, foo.bar?)  | assert(foo.bar?)  |
+| assert_equal(false, foo.bar?) | refute(foo.bar?)  |
+| assert_equal(true, foo.nil?)  | assert_nil(foo)   |
+| assert_equal(false, foo.nil?) | refute_nil(foo)   |
+| assert_equal(true, foo.empty?)| assert_empty(foo) |
+
+The more specific assertions also produce more helpful failure messages if something is wrong.
+
+### <a name="mt3">MT3: Do not hardcode interface names.
+
+Rather then hardcode an interface name that may or may not exist, instead use 
+the `interfaces[]` array.
+
+```
+def create_interface(ifname=interfaces[0])
+  @default_show_command = show_cmd(ifname)
+  Interface.new(ifname)
+end
+```
+
+If additional interfaces are needed array index `1` and `2` may be used.
+
+### <a name="mt4">MT4: Make use of the `config` helper method for device configuration instead of `@device.cmd`.
+
+For conveninence the `config` helper method has been provided for device configuration within the minitests.
+
+```
+config('no feature ospf')
+```
+
+```
+config('feature ospf'; 'router ospf green')
+```
+
+### <a name="mt5">MT5: Make use of the `assert_show_match` and `refute_show_match` helper methods to validate expected outcomes in the CLI instead of `@device.cmd("show...")`.
+
+We have a very common pattern in minitest where we execute some show command over the telnet connection, match it against some regexp pattern, and succeed or fail based on the result. Helper methods `assert_show_match` and `refute_show_match` support this pattern.
+
+```
+assert_show_match(command: 'show run all | no-more',
+                  pattern: /interface port-channel 1/,
+                  msg:     'port-channel is not present but it should be')
+```
+
+If your `command` and/or `pattern` are the same throughout a test case or throughout a test suite, you can set the test case instance variables `@default_show_command` and/or `@default_output_pattern` which serve as defaults for these parameters:
+
+```
+@default_show_command = 'show run interface all | include "interface" | no-more'
+assert_output_match(pattern: /interface port-channel 10/)
+refute_output_match(pattern: /interface port-channel 11/)
+refute_output_match(pattern: /interface port-channel 12/)
+assert_output_match(pattern: /interface port-channel 13/)
+```

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

@@ -3,258 +3,86 @@
 #### Table of Contents
 
 * [Overview](#overview)
-* [Start here: Clone the Repo](#clone)
-* [Basic Example: feature bash-shell](#simple)
- * [Step 1. YAML Definitions: feature bash-shell](#yaml)
- * [Step 2. Create the node_utils API: feature bash-shell](#api)
- * [Step 3. Create the Minitest: feature bash-shell](#minitest)
- * [Step 4. rubocop / lint: feature bash-shell](#lint)
-* [Advanced Example: router eigrp](#complex)
+* [Before You Begin](#prerequisites)
+* [Start here: Fork and Clone the Repo](#clone)
+* [Example: router eigrp](#complex)
  * [Step 1. YAML Definitions: router eigrp](#comp_yaml)
  * [Step 2. Create the node_utils API: router eigrp](#comp_api)
  * [Step 3. Create the Minitest: router eigrp](#comp_minitest)
  * [Step 4. rubocop / lint: router eigrp](#comp_lint)
+ * [Step 5. Build and Install the gem](#comp_gem)
 
 ## <a name="overview">Overview</a>
 
-This document is a HowTo guide for writing new cisco node_utils APIs. The node_utils APIs act as an interface between the NX-OS CLI and an agent's resource/provider. If written properly the new API will work as a common framework for multiple providers (Puppet, Chef, etc).
+This document is a HowTo guide for writing new cisco_node_utils APIs. The APIs act as an interface between the NX-OS CLI and an agent's resource/provider. If written properly the new API will work as a common framework for multiple providers (Puppet, Chef, etc).  In addition to this guide, please reference the [cisco_node_utils development 'best practices' guide.](./README-develop-best-practices.md)
 
-There are multiple components involved when creating new resources. This document focuses on the cisco node_utils API, command reference YAML files, and minitests.
+There are multiple components involved when creating new resources. This document focuses on the cisco_node_utils API, command reference YAML files, and minitests.
 
 ![1](agent_files.png)
 
-## <a name="clone">Start here: Clone the Repo</a>
+## <a name="prerequisites">Before You Begin</a>
 
-First install the code base. Clone the cisco_node_utils repo into a workspace:
+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)
 
-```bash
-git clone https://github.com/cisco/cisco-network-node-utils.git
-```
-
-## <a name="simple">Basic Example: feature bash-shell</a>
-
-Writing a new node_utils API is often easier to understand through example code. The NX-OS CLI for `feature bash-shell` is a simple on / off style configuration and therefore a good candidate for a simple API:
-
-`[no] feature bash-shell`
-
-### <a name="yaml">Step 1. YAML Definitions: feature bash-shell</a>
-
-The new API will need some basic YAML definitions. These are used with the `CommandReference` module as a way to abstract away platform CLI differences.
-
-`command_reference_common.yaml` is used for settings that are common across all platforms while other files are used for settings that are unique to a given platform. Our `feature bash-shell` example uses the same cli syntax on all platforms, thus we only need to edit the common file:
-
-`cisco_network_node_utils/lib/cisco_node_utils/command_reference_common.yaml`
-
-Four 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.
- 4. `default_value:` This is typically the "factory" default state of the property, expressed as an actual value (true, 12, "off", etc)
-
-There are additional YAML command parameters available which are not covered by this document. Please see the [README_YAML.md](../lib/cisco_node_utils/README_YAML.md) document for more information on the structure and semantics of these files.
-
-#### Example: YAML Property Definitions for feature bash-shell
-
-The `feature bash-shell` configuration is displayed with the `show running-config` command. Anchor the config_get_token regexp pattern carefully as it may match on unwanted configurations.
-
-*Note: YAML syntax has strict indentation rules. Do not use TABs.*
-
-```
-bash_shell:
-  feature:
-    config_get: 'show running'                   # get current bash config state
-    config_get_token: '/^feature bash-shell$/'   # Match only 'feature bash-shell'
-    config_set: '<state> feature bash-shell'     # Config needed to enable/disable
-```
-
-### <a name="api">Step 2. cisco_node_utils API file: feature bash-shell</a>
-
-* Before creating the new API, first add a new entry: `require "cisco_node_utils/bash_shell"`  to the master list of resources in:
-
-```
-cisco_network_node_utils/lib/cisco_node_utils.rb
-```
-
-* There are template files in /docs that may help when writing new APIs. These templates provide most of the necessary code with just a few customizations required for a new resource. Copy the `template-feature.rb` file to use as the basis for `bash_shell.rb`:
+This development guide uses tools that are packaged as gems that need to be installed on your server.
 
 ```bash
-cp  docs/template-feature.rb  cisco_network_node_utils/bash_shell.rb
+gem install cisco_nxapi
+gem install rake
+gem install rubocop
+gem install simplecov
+gem install minitest
 ```
 
-* Edit `bash_shell.rb` and substitute the placeholder text as shown here:
+**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
-/X__CLASS_NAME__X/BashShell/
-
-/X__RESOURCE_NAME__X/bash_shell/
+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
 ```
 
-#### Example: bash_shell.rb API
-
-This is the completed bash_shell API based on `template-feature.rb`:
-
-```ruby
+## <a name="clone">Start here: Fork and Clone the Repo</a>
 
-require File.join(File.dirname(__FILE__), 'node')
-module Cisco
-# Class name syntax will typically be the resource name in camelCase
-# format; for example: 'tacacs server host' becomes TacacsServerHost.
-class BashShell
-  # Establish connection to node
-  @@node = Cisco::Node.instance
-
-  def feature_enable
-    @@node.config_set('bash_shell', 'feature', { :state => '' })
-  end
+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 
 
-  def feature_disable
-    @@node.config_set('bash_shell', 'feature', { :state => 'no' })
-  end
-
-  # Check current state of the configuration
-  def BashShell.feature_enabled
-    feat =  @@node.config_get('bash_shell', 'feature')
-    return (!feat.nil? and !feat.empty?)
-  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
-end
-end
-```
-
-### <a name="minitest">Step 3. Minitest: feature bash-shell</a>
-
-* A minitest should be created to validate the new APIs. Minitests are stored in the tests directory: `cisco_network_node_utils/tests/`
-
-* Tests may use `@device.cmd("show ...")` to access the CLI directly set up tests and validate expected outcomes. The tests directory contains many examples of how these are used.
-
-* Our minitest will be very basic since the API itself is very basic. Use `template-test_feature.rb` to create a minitest for the bash_shell resource:
+Next install the code base. Clone the cisco-network-node-utils repo from your fork into a workspace:
 
 ```bash
-cp  docs/template-test_feature.rb  cisco_network_node_utils/tests/test_bash_shell.rb
+git clone https://github.com/YOUR-USERNAME/cisco-network-node-utils.git
+cd cisco-network-node-utils/
 ```
 
-* As with the API code, edit `test_bash_shell.rb` and change the placeholder names as shown:
+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:
 
 ```bash
-/X__CLASS_NAME__X/BashShell/
-
-/X__RESOURCE_NAME__X/bash_shell/
-
-/X__CLI_NAME__X/bash-shell/
+git config --global user.name "John Doe"
+git config --global user.email johndoe@example.com
 ```
 
-#### Example: test_bash_shell.rb
-
-This is the completed `bash_shell` minitest based on `template-test_feature.rb`:
-
-```ruby
-#
-# Minitest for BashShell class
-#
-# 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 File.expand_path("../ciscotest", __FILE__)
-require File.expand_path("../../lib/cisco_node_utils/bash_shell", __FILE__)
-
-class TestBashShell < CiscoTestCase
-  def setup
-    # setup automatically runs at the beginning of each test
-    super
-    no_feature
-  end
-
-  def teardown
-    # teardown automatically runs at the end of each test
-    no_feature
-    super
-  end
-
-  def no_feature
-    # setup/teardown helper. Turn the feature off for a clean testbed.
-    @device.cmd('conf t ; no feature bash-shell ; end')
-    node.cache_flush()
-  end
-
-  def test_feature_on_off
-    feat = BashShell.new()
-    feat.feature_enable
-    assert(BashShell.feature_enabled)
-
-    feat.feature_disable
-    refute(BashShell.feature_enabled)
-  end
-
-end
-```
-
-
-We can now run the new minitest against our NX-OS device using this syntax:
-
-```bash
-ruby test_bash_shell.rb -- <node_ip_address> <user> <passwd>
-```
-*Note. The minitest requires that the NX-OS device have 'feature nxapi' enabled. This will typically be enabled by default.*
-
-#### Example: Running bash_shell minitest
+As a best practice create a topic/feature branch for your feature work using the `git branch feature/<feature_name>` command.
 
 ```bash
-% ruby  test_bash_shell.rb  -- 192.168.0.1 admin admin
-Run options: -v -- --seed 23392
-
-# Running tests:
-
-CiscoTestCase#test_placeholder =
-Ruby Version - 1.9.3
-Node in CiscoTestCase Class: 192.168.0.1
-Platform:
-  - name  - my_n9k
-  - type  - N9K-C9504
-  - image - bootflash:///n9000-dk9.7.0.3.I2.0.509.bin
-
-1.79 s = .
-TestBashShell#test_feature_on_off = 1.42 s = .
-TestBashShell#test_placeholder = 0.95 s = .
-TestCase#test_placeholder = 0.81 s = .
-
-Finished tests in 4.975186s, 0.8040 tests/s, 0.4020 assertions/s.
-
-4 tests, 2 assertions, 0 failures, 0 errors, 0 skips
+git branch feature/eigrp
+git branch
+* develop
+  feature/eigrp
 ```
 
-*Note. The minitest harness counts the helper methods as tests which is why the final tally shows 4 tests instead of just 2 tests.*
 
-### <a name="lint">Step 4. rubocop / lint: feature bash-shell</a>
+## <a name="complex">Example: router eigrp</a>
 
-rubocop is a Ruby static analysis tool. Run rubocop with the --lint option to validate the new API:
+Before you start working on the eigrp feature, checkout the feature branch you created earlier.
 
 ```bash
-% rubocop --lint bash_shell.rb
-Inspecting 1 file
-.
-
-1 file inspected, no offenses detected
+git checkout feature/eigrp
+git branch
+  develop
+* feature/eigrp
 ```
 
-## <a name="complex">Advanced Example: router eigrp</a>
-
-Now that we have a basic example working we can move on to a slightly more complex cli.
 `router eigrp` requires feature enablement and supports multiple eigrp instances. It also has multiple configuration levels for vrf and address-family.
 
 For the purposes of this example we will only implement the following properties:
@@ -274,10 +102,20 @@ Example:
 
 ### <a name="comp_yaml">Step 1. YAML Definitions: router eigrp</a>
 
-As with the earlier example, `router eigrp` will need YAML definitions in the common file:
+The new API for `router eigrp` will need some basic YAML definitions. 
 
-`cisco_network_node_utils/lib/cisco_node_utils/command_reference_common.yaml`
+`command_reference_common.yaml` is used for settings that are common across all platforms while other files are used for settings that are unique to a given platform. Our `router eigrp` example uses the same cli syntax on all platforms, thus we only need to edit the common file:
 
+`lib/cisco_node_utils/command_reference_common.yaml`
+
+Four 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.
+ 4. `default_value:` This is typically the "factory" default state of the property, expressed as an actual value (true, 12, "off", etc)
+
+There are additional YAML command parameters available which are not covered by this document. Please see the [README_YAML.md](../lib/cisco_node_utils/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.
 
 *Note: Eigrp also has vrf and address-family contexts. These contexts require additional coding and are beyond the scope of this document.*
@@ -317,16 +155,10 @@ eigrp:
 
 ### <a name="comp_api">Step 2. cisco_node_utils API: router eigrp</a>
 
-* Add a new entry: `require "cisco_node_utils/router_eigrp"` to the master list in:
-
-```
-cisco_network_node_utils/lib/cisco_node_utils.rb
-```
-
 * The `template-router.rb` file provides a basic router API that we will use as the basis for `router_eigrp.rb`:
 
 ```bash
-cp  docs/template-router.rb  cisco_network_node_utils/router_eigrp.rb
+cp  docs/template-router.rb  lib/cisco_node_utils/router_eigrp.rb
 ```
 
 * Our new `router_eigrp.rb` requires changes from the original template. Edit `router_eigrp.rb` and change the placeholder names as shown.
@@ -347,9 +179,6 @@ cp  docs/template-router.rb  cisco_network_node_utils/router_eigrp.rb
 This is the completed `router_eigrp` API based on `template-router.rb`:
 
 ```ruby
-#
-# NXAPI implementation of RouterEigrp class
-#
 # Copyright (c) 2014-2015 Cisco and/or its affiliates.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -364,114 +193,111 @@ This is the completed `router_eigrp` API based on `template-router.rb`:
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require File.join(File.dirname(__FILE__), 'node')
+require_relative 'node_util'
 
 module Cisco
-class RouterEigrp
-  attr_reader :name
-
-  # Establish connection to node
-  @@node = Cisco::Node.instance
-
-  # name: name of the router instance
-  # instantiate: true = create router instance
-  def initialize(name, instantiate=true)
-    raise ArgumentError unless name.length > 0
-    @name = name
-    create if instantiate
-  end
+  # RouterEigrp - node utility class for EIGRP config management.
+  class RouterEigrp < 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
 
-  # Create a hash of all current router instances.
-  def RouterEigrp.routers
-    instances = @@node.config_get('eigrp', 'router')
-    return {} if instances.nil?
-    hash = {}
-    instances.each do |name|
-      hash[name] = RouterEigrp.new(name, false)
+    # Create a hash of all current router instances.
+    def self.routers
+      instances = config_get('eigrp', 'router')
+      return {} if instances.nil?
+      hash = {}
+      instances.each do |name|
+        hash[name] = RouterEigrp.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
-    return hash
-  rescue Cisco::CliError => e
-    # cmd will syntax reject when feature is not enabled
-    raise unless e.clierror =~ /Syntax error/
-    return {}
-  end
 
-  def feature_enabled
-    feat =  @@node.config_get('eigrp', 'feature')
-    return (!feat.nil? and !feat.empty?)
-  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_enabled
+      feat =  config_get('eigrp', 'feature')
+      return !(feat.nil? || feat.empty?)
+    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
-    @@node.config_set('eigrp', 'feature', { :state => '' })
-  end
+    def feature_enable
+      config_set('eigrp', 'feature', state: '')
+    end
 
-  def feature_disable
-    @@node.config_set('eigrp', 'feature', { :state => 'no' })
-  end
+    def feature_disable
+      config_set('eigrp', 'feature', state: 'no')
+    end
 
-  # Enable feature and create router instance
-  def create
-    feature_enable unless feature_enabled
-    eigrp_router
-  end
+    # Enable feature and create router instance
+    def create
+      feature_enable unless feature_enabled
+      eigrp_router
+    end
 
-  # Destroy a router instance; disable feature on last instance
-  def destroy
-    ids = @@node.config_get('eigrp', 'router')
-    return if ids.nil?
-    if ids.size == 1
-      feature_disable
-    else
-      eigrp_router('no')
+    # Destroy a router instance; disable feature on last instance
+    def destroy
+      ids = config_get('eigrp', 'router')
+      return if ids.nil?
+      if ids.size == 1
+        feature_disable
+      else
+        eigrp_router('no')
+      end
+    rescue Cisco::CliError => e
+      # CLI will syntax reject when feature is not enabled
+      raise unless e.clierror =~ /Syntax error/
     end
-  rescue Cisco::CliError => e
-    # cmd will syntax reject when feature is not enabled
-    raise unless e.clierror =~ /Syntax error/
-  end
 
-  def eigrp_router(state='')
-    @@node.config_set('eigrp', 'router', { :name => @name, :state => state })
-  end
+    def eigrp_router(state='')
+      config_set('eigrp', 'router', name: @name, state: state)
+    end
 
-  # ----------
-  # PROPERTIES
-  # ----------
+    # ----------
+    # PROPERTIES
+    # ----------
 
-  # Property methods for boolean property
-  def default_shutdown
-    @@node.config_get_default('eigrp', 'shutdown')
-  end
+    # Property methods for boolean property
+    def default_shutdown
+      config_get_default('eigrp', 'shutdown')
+    end
 
-  def shutdown
-    state = @@node.config_get('eigrp', 'shutdown', { :name => @name })
-    state ? true : false
-  end
+    def shutdown
+      state = config_get('eigrp', 'shutdown', name: @name)
+      state ? true : false
+    end
 
-  def shutdown=(state)
-    state = (state ? '' : 'no')
-    @@node.config_set('eigrp', 'shutdown', { :name => @name, :state => state })
-  end
+    def shutdown=(state)
+      state = (state ? '' : 'no')
+      config_set('eigrp', 'shutdown', name: @name, state: state)
+    end
 
-  # Property methods for integer property
-  def default_maximum_paths
-    @@node.config_get_default('eigrp', 'maximum_paths')
-  end
+    # Property methods for integer property
+    def default_maximum_paths
+      config_get_default('eigrp', 'maximum_paths')
+    end
 
-  def maximum_paths
-    val = @@node.config_get('eigrp', 'maximum_paths', { :name => @name })
-    val.nil? ? default_maximum_paths : val.first.to_i
-  end
+    def maximum_paths
+      val = config_get('eigrp', 'maximum_paths', name: @name)
+      val.nil? ? default_maximum_paths : val.first.to_i
+    end
 
-  def maximum_paths=(val)
-    @@node.config_set('eigrp', 'maximum_paths', { :name => @name, :val => val })
+    def maximum_paths=(val)
+      config_set('eigrp', 'maximum_paths', name: @name, val: val)
+    end
   end
-
-end
 end
 ```
 
@@ -480,7 +306,7 @@ end
 * Use `template-test_router.rb` to build the minitest for `router_eigrp.rb`:
 
 ```
-cp  docs/template-test_router.rb  cisco_network_node_utils/tests/test_router_eigrp.rb
+cp  docs/template-test_router.rb  tests/test_router_eigrp.rb
 ```
 * As with the API code, edit `test_router_eigrp.rb` and change the placeholder names as shown:
 
@@ -504,9 +330,6 @@ cp  docs/template-test_router.rb  cisco_network_node_utils/tests/test_router_eig
 This is the completed `test_router_eigrp` minitest based on `template-test_router.rb`:
 
 ```ruby
-#
-# Minitest for RouterEigrp class
-#
 # Copyright (c) 2014-2015 Cisco and/or its affiliates.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -521,9 +344,10 @@ This is the completed `test_router_eigrp` minitest based on `template-test_route
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require File.expand_path("../ciscotest", __FILE__)
-require File.expand_path("../../lib/cisco_node_utils/router_eigrp", __FILE__)
+require_relative 'ciscotest'
+require_relative '../lib/cisco_node_utils/router_eigrp'
 
+# TestRouterEigrp - Minitest for RouterEigrp node utility class
 class TestRouterEigrp < CiscoTestCase
   def setup
     # setup runs at the beginning of each test
@@ -539,75 +363,75 @@ class TestRouterEigrp < CiscoTestCase
 
   def no_feature_eigrp
     # Turn the feature off for a clean test.
-    @device.cmd("conf t ; no feature eigrp ; end")
-    node.cache_flush()
+    config('no feature eigrp')
   end
 
   # TESTS
 
   def test_router_create_destroy_one
-    id = "blue"
+    id = 'blue'
     rtr = RouterEigrp.new(id)
-    s = @device.cmd("show runn | i 'router eigrp #{id}'")
-    assert_match(s, /^router eigrp #{id}$/,
-                 "Error: failed to create router eigrp #{id}")
+    @default_show_command = "show runn | i 'router eigrp #{id}'")
+    assert_show_match(pattern: /^router eigrp #{id}$/,
+                      msg:     "failed to create router eigrp #{id}")
 
     rtr.destroy
-    s = @device.cmd("show runn | i 'router eigrp #{id}'")
-    refute_match(s, /^router eigrp #{id}$/,
-                 "Error: failed to destroy router eigrp #{id}")
+    refute_show_match(pattern: /^router eigrp #{id}$/,
+                      msg:     "failed to destroy router eigrp #{id}")
 
-    s = @device.cmd("show runn | i 'feature eigrp'")
-    refute_match(s, /^feature eigrp$/,
-                 "Error: failed to disable feature eigrp")
+    refute_show_match(command: "show runn | i 'feature eigrp'",
+                      pattern: /^feature eigrp$/,
+                      msg:     "failed to disable feature eigrp")
   end
 
   def test_router_create_destroy_multiple
-    id1 = "blue"
+    id1 = 'blue'
     rtr1 = RouterEigrp.new(id1)
-    id2 = "red"
+    id2 = 'red'
     rtr2 = RouterEigrp.new(id2)
 
-    s = @device.cmd("show runn | i 'router eigrp'")
-    assert_match(s, /^router eigrp #{id1}$/)
-    assert_match(s, /^router eigrp #{id2}$/)
+    @default_show_command = "show runn | i 'router eigrp'"
+
+    assert_show_match(pattern: /^router eigrp #{id1}$/,
+                      msg:     "failed to create router eigrp #{id1}")
+
+    assert_show_match(pattern: /^router eigrp #{id2}$/,
+                      msg:     "failed to create router eigrp #{id2}")
 
     rtr1.destroy
-    s = @device.cmd("show runn | i 'router eigrp #{id1}'")
-    refute_match(s, /^router eigrp #{id1}$/,
-                 "Error: failed to destroy router eigrp #{id1}")
+    refute_show_match(pattern: /^router eigrp #{id1}$/,
+                      msg:     "failed to destroy router eigrp #{id1}")
 
     rtr2.destroy
-    s = @device.cmd("show runn | i 'router eigrp #{id2}'")
-    refute_match(s, /^router eigrp #{id2}$/,
-                 "Error: failed to destroy router eigrp #{id2}")
+    refute_show_match(pattern: /^router eigrp #{id2}$/,
+                      msg:     "failed to destroy router eigrp #{id2}")
 
-    s = @device.cmd("show runn | i 'feature eigrp'")
-    refute_match(s, /^feature eigrp$/,
-                 "Error: failed to disable feature eigrp")
+    refute_show_match(command: "show runn | i 'feature eigrp'",
+                      pattern: /^feature eigrp$/,
+                      msg:     "failed to disable feature eigrp")
   end
 
   def test_router_maximum_paths
-    id = "blue"
+    id = 'blue'
     rtr = RouterEigrp.new(id)
-    val = 5   # This value depends on property bounds
+    val = 5 # This value depends on property bounds
     rtr.maximum_paths = val
     assert_equal(rtr.maximum_paths, val, "maximum_paths is not #{val}")
 
     # Get default value from yaml
-    val = node.config_get_default("eigrp", "maximum_paths")
+    val = node.config_get_default('eigrp', 'maximum_paths')
     rtr.maximum_paths = val
     assert_equal(rtr.maximum_paths, val, "maximum_paths is not #{val}")
   end
 
   def test_router_shutdown
-    id = "blue"
+    id = 'blue'
     rtr = RouterEigrp.new(id)
     rtr.shutdown = true
-    assert(rtr.shutdown, "shutdown state is not true")
+    assert(rtr.shutdown, 'shutdown state is not true')
 
     rtr.shutdown = false
-    refute(rtr.shutdown, "shutdown state is not false")
+    refute(rtr.shutdown, 'shutdown state is not false')
   end
 end
 ```
@@ -615,22 +439,17 @@ end
 Now run the test:
 
 ```bash
-% ruby-1.9.3-p0 test_router_eigrp.rb -v -- 192.168.0.1 admin admin
+% ruby test_router_eigrp.rb -v -- 192.168.0.1 admin admin
 Run options: -v -- --seed 56593
 
-# Running tests:
+# Running:
 
-CiscoTestCase#test_placeholder =
-Ruby Version - 1.9.3
-Node in CiscoTestCase Class: 192.168.0.1
-Platform:
+Node under test:
   - name  - my_n3k
   - type  - N3K-C3132Q-40GX
   - image -
 
 2.90 s = .
-TestCase#test_placeholder = 0.92 s = .
-TestRouterEigrp#test_placeholder = 0.97 s = .
 TestRouterEigrp#test_router_create_destroy_multiple = 10.77 s = .
 TestRouterEigrp#test_router_create_destroy_one = 6.14 s = .
 TestRouterEigrp#test_router_maximum_paths = 9.41 s = .
@@ -639,19 +458,50 @@ TestRouterEigrp#test_router_shutdown = 6.40 s = .
 
 Finished tests in 37.512356s, 0.1866 tests/s, 0.3199 assertions/s.
 
-7 tests, 12 assertions, 0 failures, 0 errors, 0 skips
+5 tests, 12 assertions, 0 failures, 0 errors, 0 skips
 ```
 
-### <a name="comp_lint">Step 4. rubocop / lint: router eigrp</a>
+### <a name="comp_lint">Step 4. rubocop: router eigrp</a>
 
-rubocop is a Ruby static analysis tool. Run rubocop with the --lint option to validate the new API:
+rubocop is a Ruby static analysis tool. Run rubocop to validate the new code:
 
 ```bash
-% rubocop --lint router_eigrp.rb
-Inspecting 1 file
-.
+% rubocop lib/cisco_node_utils/router_eigrp.rb tests/test_router_eigrp.rb
+Inspecting 2 file
+..
+
+2 file inspected, no offenses detected
+```
+
+### <a name="comp_gem">Step 5. Build and Install the gem</a>
+
+The final step is to build and install the gem that contains the new APIs.
+
+Please note: `gem build` will only include files that are part of the repository. This means that new file `router_eigrp.rb` will be ignored by the build until it is added to the repo with `git add`:
 
-1 file inspected, no offenses detected
+```bash
+git add lib/cisco_node_utils/router_eigrp.rb
+```
+
+From the root of the cisco-network-node-utils repository issue the following command.
+
+```bash
+% gem build cisco_node_utils.gemspec
+  Successfully built RubyGem
+  Name: cisco_node_utils
+  Version: 1.0.1
+  File: cisco_node_utils-1.0.1.gem
+```
+
+Copy the new gem to your NX-OS device and then install it.
+
+```bash
+n9k#gem install --local /bootflash/cisco_node_utils-1.0.1.gem
+Successfully installed cisco_node_utils-1.0.1
+Parsing documentation for cisco_node_utils-1.0.1
+Installing ri documentation for cisco_node_utils-1.0.1
+Done installing documentation for cisco_node_utils after 2 seconds
+1 gem installed
 ```
 
 ## Conclusion