cisco_node_utils 1.0.1 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6396905732ac665cf55bb63e17792c399a95c41f
+  data.tar.gz: 0a007ab3337c8dfe52a35deabb9a7627ba539e0f
+SHA512:
+  metadata.gz: dd703cf0f14758739bc2382296af32c2b4c202884a3fc53132e0e3e69e1de5135035b2a98afd2b2632d21062d605779fdf3506d0210056c5542a747c05419ade
+  data.tar.gz: 4d52c817fd90803451306ab759de4b28b2dc17818291b2d14440299ded9d8fe5641c5e22e800508175ba20d5cb73bfc580044e920bcd3cdbb175a3c5c810965b

data/.gitignore

@@ -1,2 +1,6 @@
+.bundle/*
 pkg/*
+vendor/*
+coverage
+Gemfile.lock
 *.gem

data/.rubocop.yml

@@ -1,3 +1,83 @@
 # Rubocop configuration
 
-inherit_from: .rubocop_todo.yml
+# Code complexity metrics are tracked separately for lib/ vs. tests/
+# See lib/.rubocop.yml and tests/.rubocop.yml
+Metrics/AbcSize:
+  Enabled: true
+
+Metrics/CyclomaticComplexity:
+  Enabled: true
+
+Metrics/MethodLength:
+  Enabled: true
+  Exclude:
+    - docs/*.rb
+
+Metrics/ParameterLists:
+  Enabled: true
+
+Metrics/PerceivedComplexity:
+  Enabled: true
+
+# Template files have long lines before tag replacement
+Metrics/LineLength:
+  Exclude:
+    - docs/*.rb
+
+#
+# Team preferences different from Rubocop defaults:
+#
+
+# We don't find either of these to be useful:
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+# We like table alignment for readability
+Style/AlignHash:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+# Template files have wildcard strings in class names
+Style/ClassAndModuleCamelCase:
+  Exclude:
+    - docs/*.rb
+
+# Permit is_a? and kind_of? interchangeably
+Style/ClassCheck:
+  Enabled: false
+
+# Template files have atypical file names on purpose
+Style/FileName:
+  Exclude:
+    - docs/*.rb
+
+# As a team we like 'sprintf' rather than 'format'
+Style/FormatString:
+  EnforcedStyle: sprintf
+
+# Mixed keys are ugly. Use one or the other as needed
+Style/HashSyntax:
+  EnforcedStyle: ruby19_no_mixed_keys
+
+# Template files have wildcard strings in method names
+Style/MethodName:
+  Exclude:
+    - docs/*.rb
+
+# "def foo(bar=baz)" not "def foo(bar = baz)"
+Style/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: no_space
+
+# Make it neater to extend multi-line arrays and hashes
+Style/TrailingComma:
+  EnforcedStyleForMultiline: comma
+
+# Because an SnmpServer cannot be destroyed, we end most of the SnmpServer
+# test cases by explicitly returning the configuration to default.
+# Rubocop thinks this is a no-op but it isn't.
+Lint/UselessSetterCall:
+  Exclude:
+    - 'tests/test_snmpserver.rb'

data/.travis.yml

@@ -0,0 +1,9 @@
+# Use Docker infrastructure
+sudo: false
+
+language: ruby
+cache: bundler
+rvm:
+  - 2.2.2
+  - 2.1.6
+  - 2.0.0

data/CHANGELOG.md

@@ -1,13 +1,72 @@
 Changelog
 =========
 
-1.0.1
------
+## [v1.1.0]
+
+### New feature support
+* BGP
+  * bgp (@mikewiebe)
+  * bgp_af (@richwellum)
+  * bgp_neighbor (@jyang09)
+  * bgp_neighbor_af (@chrisvanheuveln)
+* NTP
+  * ntp_config (@jonnytpuppet)
+  * ntp_server (@jonnytpuppet)
+* RADIUS
+  * radius_global (@jonnytpuppet)
+  * radius_server (@jonnytpuppet)
+* SYSLOG
+  * syslog_server (@jonnytpuppet)
+  * syslog_setting (@jonnytpuppet)
+* Miscellaneous 
+  * dns_domain (@hunner)
+  * domain_name (@bmjen)
+  * name_server (@hunner)
+  * network_snmp (@jonnytpuppet)
+
+### Added
+
+* Enabled [Travis-CI](https://travis-ci.org) integration to automatically run [rubocop](https://github.com/bbatsov/rubocop). Fixed all baseline rubocop warnings.
+* Added git hooks to streamline certain processes:
+  * Validate commit message format for consistency
+  * Don't allow commit of code failing RuboCop `--lint` checks
+  * If RuboCop is failing any check, warn on commit (but don't fail), and fail on push.
+  * Don't allow push without updating CHANGELOG.md
+  * Once git hooks are installed, automatically update them on pull/merge (if possible).
+  * If using [git-flow]:
+    * `git flow release start` and `git flow hotfix start` will automatically update `CHANGELOG.md` and `version.rb` for the new release version
+    * `git flow release finish` will automatically bump the version number for the develop branch.
+* Minitest enhancements:
+  * Code coverage calculation using [SimpleCov]
+  * Full Minitest suite can be run by `rake test`
+  * UUT can be specified by the `NODE` environment variable or at runtime, in addition to the classic method of command line arguments to `ruby test_my_file.rb`
+  * Added `config` and `(assert|refute)_show_match` helper methods for testing.
+* Added `bin/check_metric_limits.rb` helper script in support of refactoring.
+* Added best practices development guide.
+
+### Fixed
+
+* Fixed several bugs in `SnmpUser.(auth|priv)_password_equal?`
+* Fixed a bug in `test_interface.rb` that was keeping it from properly exercising the `negotiate_auto` functionality.
+* Added a cache_flush call in `Platform.chassis` to work around an infrequent issue.
+
+### Changed
+
+* Added missing steps to CONTRIBUTING.md and README-develop-node-utils-APIs.md
+* Added git config comments
+* Moved `platform_info.(rb|yaml)` from `lib/` to `tests/` as it is test-only code.
+* Now requires Minitest ~> 5.0 instead of Minitest < 5.0.
+
+### Removed
+
+* Dropped support for Ruby 1.9.3 as it is end-of-life.
+* Removed `test_all_cisco.rb` as `rake test` can auto-discover all tests.
+
+## [v1.0.1]
 
 * Updated to fix broken documentation links.
 
-1.0.0
------
+## [v1.0.0]
 
 * Improved logic in Vtp class to handle the presence or absence of
   'feature vtp' and 'vtp domain' configuration.
@@ -25,8 +84,15 @@ Changelog
   * vrf member
 * Move misc READMEs into /docs
 
-0.9.0
------
+## 0.9.0
 
 * First public release, corresponding to Early Field Trial (EFT) of
   Cisco NX-OS 7.0(3)I2(1).
+
+[git-flow]: https://github.com/petervanderdoes/gitflow-avh
+[SimpleCov]: https://github.com/colszowka/simplecov
+
+[v1.1.0]: https://github.com/cisco/cisco-network-node-utils/compare/v1.0.1...v1.1.0
+[v1.0.1]: https://github.com/cisco/cisco-network-node-utils/compare/v1.0.0...v1.0.1
+[v1.0.0]: https://github.com/cisco/cisco-network-node-utils/compare/v0.9.0...v1.0.0
+

data/CONTRIBUTING.md

@@ -4,28 +4,53 @@ Cisco Network Elements support a rich set of features to make networks robust, e
 ## Getting Started
 
 * Create a [GitHub account](https://github.com/signup/free)
-* Create a [cisco.com](http://cisco.com) account if you need access to a Network Simulator to test your code.
+* 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)
 
 ## Making Changes
 
-* Fork the repository
+* Fork and clone the repository
+  * Run the `bin/git/update-hooks` script to install our recommended Git hooks into your local repository.
   * Pull a branch under the "develop" branch for your changes.
   * Follow all guidelines documented in [README-develop-node_utils-APIs](docs/README-develop-node-utils-APIs.md)
   * Make changes in your branch.
 * Testing
-  * Create a minitest for new APIs or new functionality
-  * Run all the tests to ensure there was no collateral damage to existing code
+  * Create a minitest script for any new APIs or new functionality
+  * Run all the tests to ensure there was no collateral damage to existing code. There are two ways you can specify the Nexus switch (virtual or physical) to test against when running the full test suite:
+    1. Use the NODE environment variable to specify the address, username, and password:
+
+        ```bash
+        export NODE="192.168.100.1 user password"
+        rake test
+        ```
+
+    2. Enter the connection information at runtime:
+
+        ```
+        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
+        ```
+
 * Committing
   * Check for unnecessary whitespace with `git diff --check` before committing.
-  * Run `rubocop --lint` against all changed files. See [https://rubygems.org/gems/rubocop](https://rubygems.org/gems/rubocop)
+  * Run `rubocop` against all changed files. See [https://rubygems.org/gems/rubocop](https://rubygems.org/gems/rubocop)
   * Make sure your commit messages clearly describe the problem you are trying to solve and the proposed solution.
+  * Be sure to update `CHANGELOG.md` with a note about what you have added or fixed.
 
 ## Submitting Changes
 
-* All contributions you submit to this project are voluntary and subject to the terms of the Apache 2.0 license
+ All contributions submitted to this project are voluntary and subject to the terms of the Apache 2.0 license
 * Submit a pull request to the repository
-* A core team consisting of Cisco and Cisco-Partner employees will looks at Pull Request and provide feedback.
+  * Include output of all added or modified minitest scripts.
+* A core team consisting of Cisco and Cisco-Partner employees will review the Pull Request and provide feedback.
 * After feedback has been given we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.
+* All code commits must be associated with your github account and email address. Before committing any code use the following commands to update your workspace with your credentials:
+
+```bash
+git config --global user.name "John Doe"
+git config --global user.email johndoe@example.com
+```
 
 # Additional Resources
 

data/README.md

@@ -1,11 +1,46 @@
 # CiscoNodeUtils - Cisco Node Utilities
 
+[![Gem Version](https://badge.fury.io/rb/cisco_node_utils.svg)](http://badge.fury.io/rb/cisco_node_utils)
+[![Build Status](https://travis-ci.org/cisco/cisco-network-node-utils.svg?branch=develop)](https://travis-ci.org/cisco/cisco-network-node-utils)
+
+--
+##### Documentation Workflow Map
+
+This workflow map aids *users*, *developers* and *maintainers* of the CiscoNodeUtils project in selecting the appropriate document(s) for their task.
+
+* User Guides - the remainder of this document is aimed at end users
+* Developer Guides
+  * [CONTRIBUTING.md](CONTRIBUTING.md) : Contribution guidelines
+  * [README-develop-node-utils-APIs.md](docs/README-develop-node-utils-APIs.md) : Developing new CiscoNodeUtils APIs
+  * [README-develop-best-practices.md](docs/README-develop-best-practices.md) : Development best practices
+* Maintainers Guides
+  * [README-maintainers.md](docs/README-maintainers.md) : Guidelines for core maintainers of the CiscoNodeUtils project
+  * All developer guides apply to maintainers as well
+
+Please see [Learning Resources](#resources) for additional references.
+
+--
+#### Table of Contents
+
+1. [Overview](#overview)
+2. [Installation](#installation)
+3. [Examples](#examples)
+4. [Documentation](#documentation)
+5. [Changelog](#changelog)
+6. [Learning Resources](#resources)
+7. [License Information](#license_info)
+
+
+## <a name="overview">Overview</a>
+
 The CiscoNodeUtils gem provides utilities for management of Cisco network
 nodes. It is designed to work with Puppet and Chef as well as other
 open source management tools. This release supports Cisco NX-OS nodes
 running NX-OS 7.0(3)I2(1) and later.
 
-## Installation
+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="installation">Installation</a>
 
 To install the CiscoNodeUtils, use the following command:
 
@@ -16,7 +51,8 @@ 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.
 
-## Examples
+## <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
@@ -50,7 +86,8 @@ version = node.config_get("show_version", "system_image")
 node.config_set("vtp", "domain", "mycompany.com")
 ```
 
-## Documentation
+## <a name="documentation">Documentation</a>
+
 
 ### Node
 
@@ -88,15 +125,41 @@ code duplication between the Cisco Puppet modules and the Cisco Chef cookbooks.
 Generally speaking, Puppet and Chef should only interact with the feature
 provider classes, and not directly call into `CommandReference` or `Node`.
 
-## Changelog
+## <a name="changelog">Changelog</a>
+
 
 See [CHANGELOG](CHANGELOG.md) for a list of changes.
 
-## Contributing
 
-See [CONTRIBUTING](CONTRIBUTING.md) for developer and contributor guidelines.
+## <a name="resources">Learning Resources</a>
+
+
+* Chef
+  * [https://learn.chef.io/](https://learn.chef.io/)
+  * [https://en.wikipedia.org/wiki/Chef_(software)](https://en.wikipedia.org/wiki/Chef_(software))
+* Puppet
+  * [https://learn.puppetlabs.com/](https://learn.puppetlabs.com/)
+  * [https://en.wikipedia.org/wiki/Puppet_(software)](https://en.wikipedia.org/wiki/Puppet_(software))
+* Markdown (for editing documentation)
+  * [https://help.github.com/articles/markdown-basics/](https://help.github.com/articles/markdown-basics/)
+* Ruby
+  * [https://en.wikipedia.org/wiki/Ruby_(programming_language)](https://en.wikipedia.org/wiki/Ruby_(programming_language))
+  * [https://www.codecademy.com/tracks/ruby](https://www.codecademy.com/tracks/ruby)
+  * [https://rubymonk.com/](https://rubymonk.com/)
+  * [https://www.codeschool.com/paths/ruby](https://www.codeschool.com/paths/ruby)
+* Ruby Gems
+  * [http://guides.rubygems.org/](http://guides.rubygems.org/)
+  * [https://en.wikipedia.org/wiki/RubyGems](https://en.wikipedia.org/wiki/RubyGems)
+* YAML
+  * [https://en.wikipedia.org/wiki/YAML](https://en.wikipedia.org/wiki/YAML)
+  * [http://www.yaml.org/start.html](http://www.yaml.org/start.html)
+* Yum
+  * [https://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified](https://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified)
+  * [https://www.centos.org/docs/5/html/yum/](https://www.centos.org/docs/5/html/yum/)
+  * [http://www.linuxcommand.org/man_pages](http://www.linuxcommand.org/man_pages/yum8.html)
+
+## <a name="license_info">License Information</a>
 
-## License
 
 Copyright (c) 2013-2015 Cisco and/or its affiliates.
 

data/Rakefile

@@ -1,4 +1,21 @@
 require 'bundler/gem_tasks'
 require 'rubocop/rake_task'
+require 'rake/testtask'
+
+# test task is not part of default task list,
+# because it requires a node to test against
+task default: %w(rubocop build)
 
 RuboCop::RakeTask.new
+
+task :build do
+  system 'gem build cisco_node_utils.gemspec'
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.libs << 'tests'
+  t.pattern = 'tests/test_*.rb'
+  t.warning = true
+  t.verbose = true
+end

data/bin/check_metric_limits.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+#
+# October 2015, Glenn F. Matthews
+#
+# Copyright (c) 2015 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# 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.
+
+require 'pathname'
+require 'yaml'
+
+base = Pathname.new(File.expand_path('../..', __FILE__))
+
+['lib/', 'tests/'].each do |subdir|
+  # Read in the base config file:
+  base_config = {}
+  File.open(base + subdir + '.rubocop.yml', 'r') do |f|
+    base_config = YAML.parse(f).transform
+  end
+
+  # Create a fake config file that's identical to baseline except for the
+  # metric Max limits:
+
+  new_config = {}
+  base_config.each do |cop, options|
+    next unless options.is_a?(Hash)
+    new_config[cop] = {}
+    options.each do |option, value|
+      new_config[cop][option] = value unless option == 'Max'
+    end
+  end
+
+  tempfile = base + '.rubocop_temp.yml'
+
+  File.open(tempfile, 'w') do |f|
+    f.write new_config.to_yaml
+  end
+
+  output = `rubocop -c #{tempfile} --only Metrics -f emacs \
+-D #{subdir} 2>/dev/null`
+  `rm -f #{tempfile}`
+
+  results = {}
+  output.split("\n").each do |line|
+    # emacs output format:
+    # foo/bar.rb:92:81: C: Metrics/LineLength: Line is too long. [81/80]
+    file, row, col, _err, cop, msg = line.split(':')
+    file = Pathname.new(file).relative_path_from(base).to_s
+    cop.strip!
+    value = msg[/\[([0-9.]+)/, 1].to_f.ceil
+    results[cop] ||= {}
+    results[cop][value] ||= []
+    results[cop][value] << {
+      file: file,
+      row:  row.to_i,
+      col:  col.to_i,
+    }
+  end
+
+  # Print each failing cop in alphabetical order...
+  results.keys.sort.each do |cop|
+    puts "\n#{cop}"
+    offenses = results[cop]
+    # List the two highest failing values...
+    offenses.keys.sort.reverse[0..1].each do |value|
+      puts "  #{value}:"
+      offenses[value].each do |offender|
+        # and list the file and line where each failure was seen
+        puts "    #{offender[:file]}:#{offender[:row]}"
+      end
+    end
+  end
+
+  puts "\n"
+
+  base_config.keys.sort.each do |cop|
+    next unless cop =~ /Metrics/
+    base_val = base_config[cop]['Max']
+    base_val ||= 0
+    actual_val = results[cop].keys.sort.last if results[cop]
+    actual_val ||= 0
+    if base_val == actual_val
+      if base_val == 0
+        puts "#{cop}: still passing in full"
+      else
+        puts "#{cop}: value unchanged (#{base_val})"
+      end
+    elsif base_val > actual_val
+      puts "#{cop}: value improved! (#{base_val} -> #{actual_val})"
+    else
+      puts "#{cop}: value WORSENED (#{base_val} -> #{actual_val})"
+    end
+  end
+end