cisco_node_utils 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04e705a28917168a277c351451f63491ff3c1177
-  data.tar.gz: 4e2be35191668158a0b757b831cd1ee135ae7525
+  metadata.gz: e72699d560ddb617cfe0a637565d0313ba7ba9f6
+  data.tar.gz: a25d1820c2a7bc3bf28ef1fdc79c2124bbb51b49
 SHA512:
-  metadata.gz: 734d65543eeedb4f766a74c8d56f397e638f5fe446846bc4196ec3facfd1f5378f1eefe11364a67089f67a6851f2101438b87526536ab44477df6181281fb39b
-  data.tar.gz: a0d7aaebf7dd5d00a432f4a6c4067860750dd61df4e1fa73da11e6c8440f859f32d1155a412a5a00791a15a1ed024d5e3a08129b6ce74abed9a326ef55cdddfc
+  metadata.gz: a5a0cbafbb485e2c47fa4ab9bab300c713ecaba4609fc23f8f8bcf940019d74c5cd054e7e637fd50ab381bdb1cf2a7d27eb7326ca236ccab6537f66a2e6494aa
+  data.tar.gz: 7ed873f928991caf6088cf48753af8bb0ec9afc5e1c005aa5da49f82cea8c3cfea52843fb7673173ffac940eb1c846b09100018a8f12a5bcd8bcdf59e3da2635

data/.gitignore

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

data/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

data/Gemfile

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

data/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,49 +122,38 @@ 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
@@ -169,14 +161,23 @@ client.set(values: 'vtp domain mycompany.com')
 ```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>
 
 

data/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

data/bin/show_running_yang.rb

@@ -0,0 +1,233 @@
+#!/usr/bin/env ruby
+#
+# June 2016, Charles Burkett
+#
+# Copyright (c) 2016 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This is a utility to output the current state of an XR configuration.
+# In order to run, this utility needs access to one or more *.yang files
+# (found in the /pkg/yang directory on the XR box, as well as from other
+# sources).
+
+require 'cisco_node_utils'
+require 'optparse'
+
+module Cisco
+  # Utility class to output the current state of an XR configuration.
+  class YangViewer
+    def process(options)
+      @options = options
+
+      client # initialize the client
+
+      dir_or_file = options[:path]
+
+      file = nil
+      dir = nil
+
+      if File.exist?(dir_or_file)
+        if File.directory?(dir_or_file)
+          dir = dir_or_file
+        else
+          file = dir_or_file
+        end
+      else
+        puts "Directory or file not found: #{dir_or_file}"
+        exit(-1)
+      end
+
+      puts "File found: #{file}" if file
+      puts "Directory found: #{dir}" if dir
+      puts 'Searching for configuration data...' unless @options[:oper]
+      puts 'Searching for operational data...' if @options[:oper]
+
+      t1 = Time.now
+
+      @files = 0
+      @cnrs = 0
+      @errors = 0
+      if file
+        process_file(file)
+        @files += 1
+      else
+        Dir.glob(dir + '/*.yang').sort.each do |item|
+          process_file(item)
+          @files += 1
+        end
+      end
+
+      delta = Time.now - t1
+      puts '---------------------------------------------'
+      puts "Files Processed: #{@files}"
+      puts "Containers Processed: #{@cnrs}"
+      puts "Errors: #{@errors}"
+      puts "Time: #{delta.round(2)} seconds"
+      puts # spacer
+    end
+
+    def process_file(file)
+      @module = nil
+      @containers = {}
+      puts "[ Processing file #{file} ]" if @options[:verbose]
+
+      File.open(file) do |f|
+        loop do
+          break if (line = f.gets).nil?
+          process_line(line, f)
+        end
+      end
+    end
+
+    def process_line(line, file)
+      if @module.nil?
+        @module = Regexp.last_match(1) if line =~ /^module (.+) {/
+      elsif line =~ /^  container (.+) {/
+        process_root_container(@module, Regexp.last_match(1), file)
+      end
+    end
+
+    def process_root_container(module_name, container, file)
+      operation = :get_config
+      loop do
+        line = file.gets
+        break if !line || line.strip == ''
+        if line =~ /^    config false;/ # abort cnr if not config
+          operation = :get_oper
+          break
+        end
+      end
+
+      # only output config or operational data, depending on options
+      if @options[:oper]
+        return if operation == :get_config
+      else
+        return if operation != :get_config
+      end
+
+      # guard against duplicate containers
+      if @containers.key?(container)
+        puts "[   Duplicate container #{container} ]" if @options[:verbose]
+        return
+      end
+
+      yang_path = "{\"#{module_name}:#{container}\": [null]}"
+
+      @containers[container] = true
+      @cnrs += 1
+
+      begin
+        data = client.get(data_format: :yang_json,
+                          command:     yang_path,
+                          mode:        operation)
+        if data && data.strip.length > 0
+          puts "[   Processing container #{container} ]"\
+              if @options[:verbose]
+          output_data(yang_path, data)
+        else
+          puts "[   Processing container #{container}: no data returned ]"\
+              if @options[:verbose]
+        end
+      rescue Cisco::ClientError, Cisco::YangError => e
+        puts "[   Processing container #{container} ]" if @options[:verbose]
+        @errors += 1
+        puts "!!Error on '#{yang_path}': #{e}"
+        debug e.backtrace
+        puts # spacer
+      end
+    end
+
+    def output_data(yang_path, data)
+      if @options[:manifest]
+        puts "  cisco_yang { '#{yang_path}':\n"\
+            "    ensure => present,\n"\
+            "    source => '#{data.chomp.gsub(/\n/, "\n    ")}'\n"\
+            '  }'
+      else
+        puts data
+      end
+      puts # spacer
+    end
+
+    def client
+      unless @client
+        puts "[ Connecting to client environment: #{@options[:environment]} ]"\
+            if @options[:verbose]
+
+        @client = Cisco::Client.create(@options[:environment])
+
+        puts "[ Connected to client: #{@client} ]"\
+            if @options[:verbose]
+      end
+      @client
+    rescue Cisco::AuthenticationFailed
+      abort 'Unauthorized to connect'
+    rescue Cisco::ClientError, TypeError, ArgumentError => e
+      abort "Error in establishing connection: #{e}"
+    end
+  end # YangViewer
+end # Cisco
+
+options = { path: '/pkg/yang', environment: 'default' }
+optparse = OptionParser.new do |opts|
+  opts.banner = 'Usage: ruby show_running_yang.rb '\
+      '[options] [file_or_directory_path]'
+
+  opts.on('-m', '--manifest', 'Output config in a form suitable '\
+          'for inclusion in a Puppet manifest') do |_arg|
+    options[:manifest] = true
+  end
+
+  opts.on('-o', '--oper',
+          'Retrieve operational data instead of configuration '\
+          '(warning: possibly returns a lot of data; use at own risk)') do
+    options[:oper] = true
+  end
+
+  opts.on('-e', '--environment node', 'The node in cisco_node_utils.yaml '\
+          'from which to retrieve data') do |env|
+    options[:environment] = env
+  end
+
+  opts.on('-d', '--debug', 'Enable debug-level logging') do
+    Cisco::Logger.level = Logger::DEBUG
+  end
+
+  opts.on('-v', '--verbose', 'Enable verbose messages') do
+    options[:verbose] = true
+  end
+
+  opts.on('-h', '--help', 'Print this help') do
+    puts optparse
+    exit(0)
+  end
+end
+optparse.parse!
+
+if options[:oper] && options[:manifest]
+  STDERR.puts '!! Operational data cannot be set in a manifest, '\
+      'so option -m does not make sense in conjunction with -o.'
+  exit(-1)
+end
+
+# If there is a single ARGV left, use is as the file/dir path
+if ARGV.length == 1
+  options[:path] = ARGV[0]
+elsif ARGV.length > 1
+  puts optparse
+  exit(-1)
+end
+
+ycv = Cisco::YangViewer.new
+ycv.process(options)