cisco_node_utils 0.9.0 → 1.0.0

data/docs/README-maintainers.md

@@ -0,0 +1,78 @@
+# Maintainers Guide
+
+Guidelines for the core maintainers of the cisco-network-node-utils project - above and beyond the [general developer guidelines](https://github.com/cisco/cisco-network-node-utils/blob/master/CONTRIBUTING.md).
+
+## Accepting Pull Requests
+
+* Is the pull request correctly submitted against `develop`?
+* Does `rubocop` pass? (TODO - this will be part of our CI integration to run automatically)
+* Is `CHANGELOG.md` updated appropriately?
+* Are new minitests added? Do they provide sufficient coverage and consistent results?
+* Do minitests pass on both N9K and N3K?
+
+## Setting up git-flow
+
+If you don't already have [`git-flow`](https://github.com/petervanderdoes/gitflow/) installed, install it.
+
+Either run `git flow init` from the repository root directory, or manually edit your `.git/config` file. Either way, when done, you should have the following in your config:
+
+```ini
+[gitflow "branch"]
+        master = master
+        develop = develop
+[gitflow "prefix"]
+        feature = feature/
+        release = release/
+        hotfix = hotfix/
+        support = support/
+        versiontag = v
+```
+
+Most of these are default for git-flow except for the `versiontag` setting.
+
+## Release Process
+
+When we agree as a team that a new release should be published, the process is as follows:
+
+1. Create a release branch. Follow [semantic versioning](http://semver.org) - a bugfix release is a 0.0.x version bump, a new feature is a 0.x.0 bump, and a backward-incompatible change is a new x.0.0 version. 
+
+    ```
+    git flow release start 1.0.1
+    ```
+
+2. In the newly created release branch, update `CHANGELOG.md`:
+
+    ```diff
+     Changelog
+     =========
+ 
+    -(unreleased)
+    -------------
+    +1.0.1
+    +-----
+    ```
+    
+    and also update `version.rb`:
+    
+    ```diff
+    -  VERSION = '1.0.0'
+    +  VERSION = '1.0.1'
+    ```
+
+3. Finish the release and push it to GitHub:
+
+    ```
+    git flow release finish 1.0.1
+    git push origin master
+    git push origin develop
+    git push --tags
+    ```
+
+4. Add release notes on GitHub, for example `https://github.com/cisco/cisco-network-node-utils/releases/new?tag=v1.0.1`. Usually this will just be a copy-and-paste of the relevant section of the `CHANGELOG.md`.
+
+5. Publish the new gem version to rubygems.org:
+
+    ```
+    gem build cisco_node_utils.gemspec
+    gem push cisco_node_utils-0.9.0.gem
+    ```

data/docs/template-feature.rb

@@ -0,0 +1,45 @@
+#
+# NXAPI implementation of X__CLASS_NAME__X 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.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 X__CLASS_NAME__X
+  # Establish connection to node
+  @@node = Cisco::Node.instance
+
+  def feature_enable
+    @@node.config_set('X__RESOURCE_NAME__X', 'feature', { :state => '' })
+  end
+
+  def feature_disable
+    @@node.config_set('X__RESOURCE_NAME__X', 'feature', { :state => 'no' })
+  end
+
+  # Check current state of the configuration
+  def X__CLASS_NAME__X.feature_enabled
+    feat =  @@node.config_get('X__RESOURCE_NAME__X', '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

data/docs/template-router.rb

@@ -0,0 +1,125 @@
+#
+# NXAPI implementation of X__CLASS_NAME__X 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.join(File.dirname(__FILE__), 'node')
+
+module Cisco
+class X__CLASS_NAME__X
+  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
+
+  # Create a hash of all current router instances.
+  def X__CLASS_NAME__X.routers
+    instances = @@node.config_get('X__RESOURCE_NAME__X', 'router')
+    return {} if instances.nil?
+    hash = {}
+    instances.each do |name|
+      hash[name] = X__CLASS_NAME__X.new(name, false)
+    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('X__RESOURCE_NAME__X', '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_enable
+    @@node.config_set('X__RESOURCE_NAME__X', 'feature', { :state => '' })
+  end
+
+  def feature_disable
+    @@node.config_set('X__RESOURCE_NAME__X', 'feature', { :state => 'no' })
+  end
+
+  # Enable feature and create router instance
+  def create
+    feature_enable unless feature_enabled
+    X__RESOURCE_NAME__X_router
+  end
+
+  # Destroy a router instance; disable feature on last instance
+  def destroy
+    ids = @@node.config_get('X__RESOURCE_NAME__X', 'router')
+    return if ids.nil?
+    if ids.size == 1
+      feature_disable
+    else
+      X__RESOURCE_NAME__X_router('no')
+    end
+  rescue Cisco::CliError => e
+    # cmd will syntax reject when feature is not enabled
+    raise unless e.clierror =~ /Syntax error/
+  end
+
+  def X__RESOURCE_NAME__X_router(state='')
+    @@node.config_set('X__RESOURCE_NAME__X', 'router', { :name => @name, :state => state })
+  end
+
+  # ----------
+  # PROPERTIES
+  # ----------
+
+  # Property methods for boolean property
+  def default_X__PROPERTY_BOOL__X
+    @@node.config_get_default('X__RESOURCE_NAME__X', 'X__PROPERTY_BOOL__X')
+  end
+
+  def X__PROPERTY_BOOL__X
+    state = @@node.config_get('X__RESOURCE_NAME__X', 'X__PROPERTY_BOOL__X', { :name => @name })
+    state ? true : false
+  end
+
+  def X__PROPERTY_BOOL__X=(state)
+    state = (state ? '' : 'no')
+    @@node.config_set('X__RESOURCE_NAME__X', 'X__PROPERTY_BOOL__X', { :name => @name, :state => state })
+  end
+
+  # Property methods for integer property
+  def default_X__PROPERTY_INT__X
+    @@node.config_get_default('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X')
+  end
+
+  def X__PROPERTY_INT__X
+    val = @@node.config_get('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X', { :name => @name })
+    val.nil? ? default_X__PROPERTY_INT__X : val.first.to_i
+  end
+
+  def X__PROPERTY_INT__X=(val)
+    @@node.config_set('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X', { :name => @name, :val => val })
+  end
+end
+end

data/docs/template-test_feature.rb

@@ -0,0 +1,51 @@
+#
+# Minitest for X__CLASS_NAME__X 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/X__RESOURCE_NAME__X", __FILE__)
+
+class TestX__CLASS_NAME__X < 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 X__CLI_NAME__X ; end')
+    # Flush the cache since we've modified the device outside of the node_utils APIs
+    node.cache_flush()
+  end
+
+  # TESTS
+
+  def test_feature_on_off
+    feat = X__CLASS_NAME__X.new()
+    feat.feature_enable
+    assert(BashShell.feature_enabled)
+
+    feat.feature_disable
+    refute(BashShell.feature_enabled)
+  end
+end

data/docs/template-test_router.rb

@@ -0,0 +1,107 @@
+#
+# Minitest for __CLASS_NAME__ 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/router___RESOURCE_NAME__", __FILE__)
+
+class Test__CLASS_NAME__ < CiscoTestCase
+  def setup
+    # setup runs at the beginning of each test
+    super
+    no_feature___RESOURCE_NAME__
+  end
+
+  def teardown
+    # teardown runs at the end of each test
+    no_feature___RESOURCE_NAME__
+    super
+  end
+
+  def no_feature___RESOURCE_NAME__
+    # Turn the feature off for a clean test.
+    @device.cmd("conf t ; no feature __RESOURCE_NAME__ ; end")
+    # Flush the cache since we've modified the device outside of the node_utils APIs
+    node.cache_flush()
+  end
+
+  # TESTS
+
+  def test_router_create_destroy_one
+    id = "blue"
+    rtr = __CLASS_NAME__.new(id)
+    s = @device.cmd("show runn | i 'router __RESOURCE_NAME__ #{id}'")
+    assert_match(s, /^router __RESOURCE_NAME__ #{id}$/,
+                 "Error: failed to create router __RESOURCE_NAME__ #{id}")
+
+    rtr.destroy
+    s = @device.cmd("show runn | i 'router __RESOURCE_NAME__ #{id}'")
+    refute_match(s, /^router __RESOURCE_NAME__ #{id}$/,
+                 "Error: failed to destroy router __RESOURCE_NAME__ #{id}")
+
+    s = @device.cmd("show runn | i 'feature __RESOURCE_NAME__'")
+    refute_match(s, /^feature __RESOURCE_NAME__$/,
+                 "Error: failed to disable feature __RESOURCE_NAME__")
+  end
+
+  def test_router_create_destroy_multiple
+    id1 = "blue"
+    rtr1 = __CLASS_NAME__.new(id1)
+    id2 = "red"
+    rtr2 = __CLASS_NAME__.new(id2)
+
+    s = @device.cmd("show runn | i 'router __RESOURCE_NAME__'")
+    assert_match(s, /^router __RESOURCE_NAME__ #{id1}$/)
+    assert_match(s, /^router __RESOURCE_NAME__ #{id2}$/)
+
+    rtr1.destroy
+    s = @device.cmd("show runn | i 'router __RESOURCE_NAME__ #{id1}'")
+    refute_match(s, /^router __RESOURCE_NAME__ #{id1}$/,
+                 "Error: failed to destroy router __RESOURCE_NAME__ #{id1}")
+
+    rtr2.destroy
+    s = @device.cmd("show runn | i 'router __RESOURCE_NAME__ #{id2}'")
+    refute_match(s, /^router __RESOURCE_NAME__ #{id2}$/,
+                 "Error: failed to destroy router __RESOURCE_NAME__ #{id2}")
+
+    s = @device.cmd("show runn | i 'feature __RESOURCE_NAME__'")
+    refute_match(s, /^feature __RESOURCE_NAME__$/,
+                 "Error: failed to disable feature __RESOURCE_NAME__")
+  end
+
+  def test_router___PROPERTY_INT__
+    id = "blue"
+    rtr = __CLASS_NAME__.new(id)
+    val = 5   # This value depends on property bounds
+    rtr.__PROPERTY_INT__ = val
+    assert_equal(rtr.__PROPERTY_INT__, val, "__PROPERTY_INT__ is not #{val}")
+
+    # Get default value from yaml
+    val = node.config_get_default("__RESOURCE_NAME__", "__PROPERTY_INT__")
+    rtr.__PROPERTY_INT__ = val
+    assert_equal(rtr.__PROPERTY_INT__, val, "__PROPERTY_INT__ is not #{val}")
+  end
+
+  def test_router___PROPERTY_BOOL__
+    id = "blue"
+    rtr = __CLASS_NAME__.new(id)
+    rtr.__PROPERTY_BOOL__ = true
+    assert(rtr.__PROPERTY_BOOL__, "__PROPERTY_BOOL__ state is not true")
+
+    rtr.__PROPERTY_BOOL__ = false
+    refute(rtr.__PROPERTY_BOOL__, "__PROPERTY_BOOL__ state is not false")
+  end
+end

data/lib/cisco_node_utils/command_reference_common.yaml

@@ -142,6 +142,17 @@ interface:
   destroy:
     config_set: "no interface %s"
 
+  encapsulation_dot1q:
+    config_get: "show running interface all"
+    config_get_token: ['/^interface %s$/i', '/^encapsulation dot1q (.*)/']
+    config_set: ["interface %s", "%s encapsulation dot1q %s"]
+    default_value: ""
+
+  feature_lacp:
+    config_get: "show running | i ^feature"
+    config_get_token: '/^feature lacp$/'
+    config_set: "%s feature lacp"
+
   feature_vlan:
     config_get: "show running | i ^feature"
     config_get_token: '/^feature interface-vlan$/'
@@ -196,6 +207,12 @@ interface:
       false: false
       true: true
 
+  mtu:
+    config_get: "show running interface all"
+    config_get_token: ['/^interface %s$/i', '/^mtu (.*)$/']
+    config_set: ["interface %s", "%s mtu %s"]
+    default_value: ""
+
   negotiate_auto_ethernet:
     config_get: "show running interface all"
     config_get_token: [
@@ -303,6 +320,24 @@ interface:
     test_config_result:
       false: RuntimeError
 
+  switchport_trunk_allowed_vlan:
+    config_get: "show running interface all"
+    config_get_token: [
+      '/^interface %s$/i',
+      '/^switchport trunk allowed vlan (.*)$/'
+    ]
+    config_set: ["interface %s", "%s switchport trunk allowed vlan %s"]
+    default_value: "all"
+
+  switchport_trunk_native_vlan:
+    config_get: "show running interface all"
+    config_get_token: [
+      '/^interface %s$/i',
+      '/^switchport trunk native vlan (.*)$/'
+    ]
+    config_set: ["interface %s", "%s switchport trunk native vlan %s"]
+    default_value: 1
+
   svi_autostate:
     config_get: "show running interface all"
     config_get_token: ['/^interface %s$/i', '/^autostate$/']
@@ -318,6 +353,12 @@ interface:
     config_set: ["interface %s", "%s management"]
     default_value: false
 
+  vrf:
+    config_get: "show running interface all"
+    config_get_token: ['/^interface %s$/i', '/^vrf member (.*)/']
+    config_set: ["interface %s", "%s vrf member %s"]
+    default_value: ""
+
   vtp:
     config_get: "show running interface all"
     config_get_token: ['/^interface %s$/i', '/^vtp *$/']
@@ -835,7 +876,7 @@ vtp:
 
 yum:
   install:
-    config_set: "install add %s activate"
+    config_set: "install add %s %s activate"
   query:
     config_get: "show install packages"
     # pass in the pkg name, retrieve version