Release 1.4.0 (#485)

Merge Release 1.4.0 --> Master

Author: mikewiebe

.gitignore

@@ -3,6 +3,7 @@ pkg/*
 vendor/*
 coverage
 ext/Rakefile
+tests/tacacs_server.yaml
 Gemfile.lock
 *.gem
 *.swp

CHANGELOG.md

@@ -1,6 +1,71 @@
 Changelog
 =========
 
+## [v1.4.0]
+
+### New feature support
+
+#### Cisco Resources
+* Bidirectional Forwarding Detection
+  * bfd (@saichint)
+* Dynamic Host Configuration Protocol
+  * dhcp_relay_global (@saichint)
+* OSPF
+  * ospf_area (@saichint)
+  * ospf_area_vlink (@saichint)
+
+### Added
+
+* Extend interface with attributes:
+   * `bfd_echo`
+   * `ipv4_dhcp_relay_addr`
+   * `ipv4_dhcp_relay_info_trust`
+   * `ipv4_dhcp_relay_src_addr_hsrp`
+   * `ipv4_dhcp_relay_src_intf`
+   * `ipv4_dhcp_relay_subnet_broadcast`
+   * `ipv4_dhcp_smart_relay`
+   * `ipv6_dhcp_relay_addr`
+   * `ipv6_dhcp_relay_src_intf`
+   * `storm_control_broadcast`
+   * `storm_control_multicast`
+   * `storm_control_unicast`
+* Extend interface_ospf with attributes:
+   * `bfd`
+   * `mtu_ignore`
+   * `network_type`
+   * `priority`
+   * `shutdown`
+   * `transmit_delay`
+* Extend interface_portchannel with attributes:
+   * `bfd_per_link`
+* Extend router_ospf_vrf with attributes:
+   * `bfd`
+* Extend bgp_neighbor with attributes:
+   * `bfd`
+
+### Changed
+* Deprecated `vlan` private-vlan properties and replaced with new methods. New file `vlan_DEPRECATED.rb` has been created to store the deprecated methods. The old -> new properties are:
+
+| Old Name | New Name(s) |
+|:---|:---:|
+| `private_vlan_association`                      | `pvlan_association`
+| `private_vlan_type`                             | `pvlan_type`
+
+* Deprecated `interface` private-vlan properties and replaced with new methods. New files `interface_DEPRECATED.rb` and `DEPRECATED.yaml` have been created to store the deprecated methods. The old -> new properties are:
+
+| Old Name | New Name(s) |
+|:---|:---:|
+| `private_vlan_mapping`                          | `pvlan_mapping`
+| `switchport_mode_private_vlan_host`             | `switchport_pvlan_host`, `switchport_pvlan_promiscuous`,
+| `switchport_mode_private_vlan_host_association` | `switchport_pvlan_host_association`
+| `switchport_mode_private_vlan_host_promiscous`  | `switchport_pvlan_mapping`
+| `switchport_mode_private_vlan_trunk_promiscuous`| `switchport_pvlan_trunk_promiscuous`
+| `switchport_mode_private_vlan_trunk_secondary`  | `switchport_pvlan_trunk_secondary`
+| `switchport_private_vlan_association_trunk`     | `switchport_pvlan_trunk_association`
+| `switchport_private_vlan_mapping_trunk`         | `switchport_pvlan_mapping_trunk`
+| `switchport_private_vlan_trunk_allowed_vlan`    | `switchport_pvlan_trunk_allowed_vlan`
+| `switchport_private_vlan_trunk_native_vlan`     | `switchport_pvlan_trunk_native_vlan`
+
 ## [v1.3.0]
 
 ### New feature support
@@ -294,6 +359,7 @@ Changelog
 [git-flow]: https://github.com/petervanderdoes/gitflow-avh
 [SimpleCov]: https://github.com/colszowka/simplecov
 
+[v1.4.0]: https://github.com/cisco/cisco-network-node-utils/compare/v1.3.0...v1.4.0
 [v1.3.0]: https://github.com/cisco/cisco-network-node-utils/compare/v1.2.0...v1.3.0
 [v1.2.0]: https://github.com/cisco/cisco-network-node-utils/compare/v1.1.0...v1.2.0
 [v1.1.0]: https://github.com/cisco/cisco-network-node-utils/compare/v1.0.1...v1.1.0

Gemfile

@@ -7,3 +7,4 @@ gemspec
 # but we need them for Bundler to use.
 gem 'net_http_unix'
 gem 'grpc'
+gem 'pry'

README.md

@@ -61,9 +61,9 @@ To install the CiscoNodeUtils, use the following command:
 Alternatively, if you've checked the source out directly, you can call
 `rake install` from the root project directory.
 
-## Configuration
+## <a name="configuration">Configuration</a>
 
-This gem may require configuration in order to be used. Two configuration file locations are supported:
+Depending on the installation environment (Linux, NX-OS), this gem may require configuration in order to be used. Two configuration file locations are supported:
 
 * `/etc/cisco_node_utils.yaml` (system and/or root user configuration)
 * `~/cisco_node_utils.yaml` (per-user configuration)
@@ -72,13 +72,16 @@ If both files exist and are readable, configuration in the user-specific file wi
 
 This file specifies the host, port, username, and/or password to be used to connect to one or more nodes.
 
+* When installing this gem on NX-OS nodes, this file is generally not needed, as the default client behavior is sufficient.
 * When developing for or testing this gem, this file can specify one or more NX-OS nodes to run tests against. In this case:
-  - A node labeled as `default` will be the default node to test against.
-  - Nodes with other names can be selected at test execution time.
-  - NX-OS nodes must be defined with a `host` (hostname or IP address), `username`, and `password`.
+    - A node labeled as `default` will be the default node to test against.
+    - Nodes with other names can be selected at test execution time.
+    - NX-OS nodes must be defined with a `host` (hostname or IP address), `username`, and `password`.
 
 An example configuration file (illustrating each of the above scenarios) is provided with this gem at [`docs/cisco_node_utils.yaml.example`](docs/cisco_node_utils.yaml.example).
 
+*For security purposes, it is highly recommended that access to this file be restricted to only the owning user (`chmod 0600`).*
+
 ## <a name="documentation">Documentation</a>
 
 ### Client
@@ -119,64 +122,62 @@ provider classes, and not directly call into `CommandReference` or `Node`.
 
 ## <a name="examples">Examples</a>
 
-
 These utilities can be used directly on a Cisco device (as used by Puppet
 and Chef) or can run on a workstation and point to a Cisco device (as used
-by the included minitest suite).
+by the included minitest suite).  The Client and Node APIs will read
+connection information (host, username, etc.) from a
+[configuration file](#configuration). When creating a Client
+you can choose which device in the config file to connect to by specifying a label
+(if no label is specified, "default" is assumed). If a configuration file cannot be
+found, the Client or Node will attempt to connect to the local device.
 
-### Usage on a Cisco device
-
-#### Low-level Client API
-
-```ruby
-require 'cisco_node_utils'
+*Note: Entries in the configuration file can specify local or remote devices.*
 
-# get a connection to the local device
-client = Cisco::Client.create()
-
-client.get(command: 'show version')
-client.set(values: 'vtp domain mycompany.com')
-```
-
-#### High-level Node API
-
-```ruby
-require 'cisco_node_utils'
-
-# get a connection to the local device
-node = Cisco::Node.instance()
-
-version = node.config_get("show_version", "system_image")
-
-node.config_set("vtp", "domain", "mycompany.com")
-```
-
-### Remote usage
+### Cisco Nexus Device (supports CLI configuration)
 
 #### Low-level Client API
 
 ```ruby
 require 'cisco_node_utils'
 
-client = Cisco::Client.create('n3k.mycompany.com', 'username', 'password')
+# Create a connection to the following nodes:
+# - 'default' device defined in the cisco_node_utils.yaml file
+# - 'n9k' device defined in the cisco_node_utils.yaml file
+client1 = Cisco::Client.create()
+client2 = Cisco::Client.create('n9k')
+# Warning: Make sure to exclude devices using the 'no_proxy' environment variable
+# to ensure successful remote connections.
+
+# Use connections to get and set device state.
+client1.set(values: 'feature vtp')
+client1.set(values: 'vtp domain mycompany.com')
+puts client1.get(command: 'show vtp status | inc Domain')
 
-client.get(command: 'show version')
-client.set(values: 'vtp domain mycompany.com')
+puts client2.get(command: 'show version')
 ```
 
 #### High-level Node API
 
 ```ruby
 require 'cisco_node_utils'
 
-node = Cisco::Node.new("n3k.mycompany.com", "username", "password")
-
-version = node.config_get("show_version", "system_image")
-
-node.config_set("vtp", "domain", "mycompany.com")
+# Create a connection to the following:
+# - 'default' device defined in the cisco_node_utils.yaml
+node = Cisco::Node.instance()
+# OR:
+# - 'n9k' device defined in the cisco_node_utils.yaml file
+# Cisco::Environment.default_environment_name = 'n9k'
+# node = Cisco::Node.instance()
+
+# Warning: Make sure to exclude devices using the 'no_proxy' environment variable
+# to ensure successful remote connections.
+
+# Use connection to get and set device state.
+node.config_set('feature', 'vtp', state: '')
+node.config_set('vtp', 'domain', domain: 'mycompany.com')
+puts node.config_get('vtp', 'domain')
 ```
 
-
 ## <a name="changelog">Changelog</a>
 
 

bin/.rubocop.yml

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