cisco_node_utils 0.9.0

data/README.md

@@ -0,0 +1,113 @@
+# CiscoNodeUtils - Cisco Node Utilities
+
+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
+
+To install the CiscoNodeUtils, use the following command:
+
+    $ gem install cisco_node_utils
+
+(Add `sudo` if you're installing under a POSIX system as root)
+
+Alternatively, if you've checked the source out directly, you can call
+`rake install` from the root project directory.
+
+## Examples
+
+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).
+
+### Usage on a Cisco device
+
+```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
+
+```ruby
+require 'cisco_node_utils'
+
+Cisco::Node.lazy_connect = true
+
+node = Cisco::Node.instance()
+node.connect("n3k.mycompany.com", "username", "password")
+
+version = node.config_get("show_version", "system_image")
+
+node.config_set("vtp", "domain", "mycompany.com")
+```
+
+## Documentation
+
+### Node
+
+The `Node` class is a singleton which provides for management of a given Cisco
+network node. It provides the base APIs `config_set`, `config_get`, and
+`config_get_default`.
+
+### CommandReference
+
+The `CommandReference` module provides for the abstraction of NX-OS CLI,
+especially to handle its variance between hardware platforms.
+A series of YAML files are used to describe the CLI corresponding to a given
+`(feature, attribute)` tuple for any given platform. When a `Node` is
+connected, the platform identification of the Node is used to construct a
+`CmdRef` object that corresponds to this platform. The `Node` APIs
+`config_set`, `config_get`, and `config_get_default` all rely on the `CmdRef`.
+
+See also [README_YAML](lib/cisco_node_utils/README_YAML.md).
+
+### Feature Providers
+
+Each feature supported by CiscoNodeUtils has its own class. For example,
+`Cisco::RouterOspf` is the class used to manage OSPF router configuration on
+a `Node`. Each feature class has getters and setters which are wrappers around
+the Node APIs `config_set`, `config_get`, and `config_get_default`.
+
+### Puppet and Chef
+
+This library is designed as a shared backend between Puppet and Chef for the
+management of Cisco nodes. Puppet providers and Chef providers alike can use
+the feature provider classes from this module to do the majority of work in
+actually managing device configuration and state. This reduces the amount of
+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
+
+See [CHANGELOG](CHANGELOG.md) for a list of changes.
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md) for developer and contributor guidelines.
+
+## License
+
+Copyright (c) 2013-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.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new

data/cisco_node_utils.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cisco_node_utils/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'cisco_node_utils'
+  spec.version       = CiscoNodeUtils::VERSION
+  spec.authors       = ['Alex Hunsberger', 'Glenn Matthews',
+                        'Chris Van Heuveln', 'Mike Wiebe', 'Jie Yang']
+  spec.email         = 'cisco_agent_gem@cisco.com'
+  spec.summary       = 'Utilities for management of Cisco network nodes'
+  spec.description   = <<-EOF
+Utilities for management of Cisco network nodes.
+Designed to work with Puppet and Chef.
+Currently supports NX-OS nodes.
+  EOF
+  spec.license       = 'Apache-2.0'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  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.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rubocop', '>= 0.32'
+  spec.add_runtime_dependency 'cisco_nxapi', '>= 0.9'
+end

data/lib/cisco_node_utils.rb

@@ -0,0 +1,33 @@
+# 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 "cisco_node_utils/cisco_cmn_utils"
+require "cisco_node_utils/command_reference"
+require "cisco_node_utils/configparser_lib"
+require "cisco_node_utils/interface"
+require "cisco_node_utils/interface_ospf"
+require "cisco_node_utils/node"
+require "cisco_node_utils/platform"
+require "cisco_node_utils/router_ospf"
+require "cisco_node_utils/router_ospf_vrf"
+require "cisco_node_utils/snmpcommunity"
+require "cisco_node_utils/snmpgroup"
+require "cisco_node_utils/snmpserver"
+require "cisco_node_utils/snmpuser"
+require "cisco_node_utils/tacacs_server"
+require "cisco_node_utils/tacacs_server_host"
+require "cisco_node_utils/version"
+require "cisco_node_utils/vlan"
+require "cisco_node_utils/vtp"
+require "cisco_node_utils/yum"

data/lib/cisco_node_utils/README_YAML.md

@@ -0,0 +1,333 @@
+# Command Reference YAML
+
+The `command_reference_*.yaml` files in this directory are used with the
+`CommandReference` module as a way to abstract away platform CLI differences.
+
+This document describes the structure and semantics of these files.
+
+## Structure
+
+```yaml
+FEATURE_1:
+  _template:
+    # base parameters for all attributes of this feature go here
+
+  ATTRIBUTE_1:
+    config_get: 'string'
+    config_get_token: 'string'
+    config_get_token_append: 'string'
+    config_set: 'string'
+    config_set_append: 'string'
+    default_value: string, boolean, integer, or constant
+    test_config_get: 'string'
+    test_config_get_regexp: '/regexp/'
+    test_config_result:
+      input_1: output_1
+      input_2: output_2
+
+  ATTRIBUTE_2:
+    ...
+
+  ATTRIBUTE_3:
+    ...
+
+FEATURE_2:
+  ...
+```
+
+All parameters are optional and may be omitted if not needed.
+
+### Wildcard substitution
+
+The `config_get_token` and `config_set` (and their associated `_append`
+variants) all support two forms of wildcarding - printf-style and key-value.
+
+#### Printf-style wildcards
+
+```yaml
+tacacs_server_host:
+  encryption:
+    config_set: '%s tacacs-server host %s key %s %s'
+```
+
+This permits parameter values to be passed as a simple sequence:
+
+```ruby
+config_set('tacacs_server_host', 'encryption', 'no', 'user', 'md5', 'password')
+
+# this becomes 'no tacacs-server host user key md5 password'
+#               ^^                    ^^^^     ^^^ ^^^^^^^^
+```
+
+This 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.
+
+#### Key-value wildcards
+
+```yaml
+ospf:
+  auto_cost:
+    config_set: ['router ospf <name>', 'auto-cost reference-bandwidth <cost> <type>']
+```
+
+This requires parameter values to be passed as a hash:
+
+```ruby
+config_set('ospf', 'auto_cost', {:name => 'red',
+                                 :cost => '40',
+                                 :type => 'Gbps'})
+
+# this becomes the config sequence:
+#   router ospf red
+#    auto-cost reference-bandwidth 40 Gbps
+```
+
+This 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.
+
+### `_template`
+
+The optional `_template` section can be used to define base parameters for all
+attributes of a given feature. For example, all interface attributes might be
+checked with the `show running-config interface all` command, and all
+attributes might be set by first entering the interface configuration submode
+with the `interface <name>` configuration command. Thus, you might have:
+
+```yaml
+interface:
+  _template:
+    config_get: 'show running-config interface all'
+    config_get_token: '/^interface <name>$/'
+    config_set: 'interface <name>'
+
+  access_vlan:
+    config_get_token_append: '/^switchport access vlan (.*)$/'
+    config_set_append: 'switchport access vlan <number>'
+
+  description:
+    config_get_token_append: '/^description (.*)$/'
+    config_set_append: 'description <desc>'
+
+  ...
+```
+
+instead of the more repetitive (but equally valid):
+
+```yaml
+interface:
+  access_vlan:
+    config_get: 'show running interface all'
+    config_get_token: ['/^interface %s$/i', '/^switchport access vlan (.*)$/']
+    config_set: ['interface %s', 'switchport access vlan %s']
+
+  description:
+    config_get: 'show running-config interface all'
+    config_get_token: ['/^interface <name>$/i', '/^description (.*)$/']
+    config_set: ['interface <name>', 'description <desc>']
+
+  ...
+```
+
+### `config_get`
+
+`config_get` must be a single string representing the CLI command (usually a
+`show` command) to be used to display the information needed to get the
+current value of this attribute.
+
+```yaml
+    config_get: 'show running-config interface <name> all'
+```
+
+### `config_get_token`
+
+`config_get_token` can be a single string, a single regex, an array of strings,
+or an array of regexs.
+
+If this value is a string or array of strings, then the `config_get` command
+will be executed to produce _structured_ output and the string(s) will be
+used as lookup keys.
+
+```yaml
+show_version
+  cpu:
+    config_get: 'show version'
+    config_get_token: 'cpu_name'
+    # config_get('show_version', 'cpu') returns structured_output['cpu_name']
+```
+
+```yaml
+inventory:
+  productid:
+    config_get: 'show inventory'
+    config_get_token: ['TABLE_inv', 'ROW_inv', 0, 'productid']
+    # config_get('inventory', 'productid') returns
+    # structured_output['TABLE_inv']['ROW_inv'][0]['productid']
+```
+
+If this value is a regex or array or regexs, then the `config_get` command
+will be executed to produce _plaintext_ output.
+
+For a single regex, it will be used to match against the plaintext.
+
+```yaml
+memory:
+  total:
+    config_get: 'show system resources'
+    config_get_token: '/Memory.* (\S+) total/'
+    # config_get('memory', 'total') returns
+    # plaintext_output.scan(/Memory.* (\S+) total/)
+```
+
+For an array of regex, then the plaintext is assumed to be hierarchical in
+nature (like `show running-config`) and the regexs are used to filter down
+through the hierarchy.
+
+```yaml
+interface:
+  description:
+    config_get: 'show running interface all'
+    config_get_token: ['/^interface %s$/i', '/^description (.*)/']
+    # config_get('interface', 'description', 'Ethernet1/1') gets the plaintext
+    # output, finds the subsection under /^interface Ethernet1/1$/i, then finds
+    # the line matching /^description (.*)$/ in that subsection
+```
+
+### `config_get_token_append`
+
+When using a `_template` section, an attribute can use
+`config_get_token_append` to extend the `config_get_token` value provided by
+the template instead of replacing it:
+
+```yaml
+interface:
+  _template:
+    config_get: 'show running-config interface all'
+    config_get_token: '/^interface <name>$/'
+
+  description:
+    config_get_token_append: '/^description (.*)$/'
+    # config_get_token value for 'description' is now:
+    # ['/^interface %s$/i', '/^description (.*)$/']
+```
+
+This can also be used to specify conditional tokens which may or may not be
+used depending on the set of parameters passed into `config_get()`:
+
+```yaml
+bgp:
+  _template:
+    config_get: 'show running bgp all'
+    config_get_token: '/^router bgp <asnum>$/'
+    config_get_token_append:
+      - '/^vrf <vrf>$/'
+
+  router_id:
+    config_get_token_append: '/^router-id (\S+)$/'
+```
+
+In this example, both `config_get('bgp', 'router_id', {:asnum => '1'})` and
+`config_get('bgp', 'router_id', {:asnum => '1', :vrf => 'red'})` are valid -
+the former will match 'router bgp 1' followed by 'router-id', while the latter
+will match 'router bgp 1' followed by 'vrf red' followed by 'router-id'.
+
+### `config_set`
+
+The `config_set` parameter is a string or array of strings representing the
+configuration CLI command(s) used to set the value of the attribute.
+
+```yaml
+interface:
+  create:
+    config_set: 'interface <name>'
+
+  description:
+    config_set: ['interface <name>', 'description <desc>']
+```
+
+### `config_set_append`
+
+When using a `_template` section, an attribute can use `config_set_append` to
+extend the `config_set` value provided by the template instead of replacing it:
+
+```yaml
+interface:
+  _template:
+    config_set: 'interface <name>'
+
+  access_vlan:
+    config_set_append: 'switchport access vlan <number>'
+    # config_set value for 'access_vlan' is now:
+    # ['interface <name>', 'switchport access vlan <number>']
+```
+
+Much like `config_get_token_append`, this can also be used to specify optional
+commands that can be included or omitted as needed:
+
+```yaml
+bgp:
+  _template:
+    config_set: 'router bgp <asnum>'
+    config_set_append:
+      - 'vrf <vrf>'
+```
+
+### `default_value`
+
+If there is a default value for this attribute when not otherwise specified by
+the user, the `default_value` parameter describes it. This can be a string,
+boolean, integer, or array.
+
+```yaml
+interface:
+  description:
+    default_value: ''
+
+interface_ospf:
+  hello_interval:
+    default_value: 10
+
+ospf:
+  auto_cost:
+    default_value: [40, 'Gbps']
+```
+
+### `test_config_get` and `test_config_get_regex`
+
+Test-only equivalents to `config_get` and `config_get_token` - a show command
+to be executed over telnet by the minitest unit test scripts, and a regex
+(or array thereof) to match in the resulting plaintext output.
+Should only be referenced by test scripts, never by a feature provider itself.
+
+```yaml
+show_version:
+  boot_image:
+    test_config_get: 'show version | no-more'
+    test_config_get_regex: '/NXOS image file is: (.*)$/'
+```
+
+### `test_config_result`
+
+Test-only container for input-result pairs that might differ by platform.
+Should only be referenced by test scripts, never by a feature provider itself.
+
+```yaml
+vtp:
+  version:
+    test_config_result:
+      3: 'Cisco::CliError'
+```
+
+## Style Guide
+
+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.
+
+Note that `~` is the YAML syntax that corresponds to Ruby's `nil`.
+
+Use the key-value wildcarding style wherever possible, as it's more flexible
+than the printf-style wildcarding.