cisco_node_utils 1.1.0 → 1.2.0

data/docs/README-develop-node-utils-APIs.md

@@ -102,20 +102,23 @@ Example:
 
 ### <a name="comp_yaml">Step 1. YAML Definitions: router eigrp</a>
 
-The new API for `router eigrp` will need some basic YAML definitions. 
+The new API for `router eigrp` will need some basic YAML definitions. By convention we create a new YAML file to handle a new feature set, so we will create
+the following file:
 
-`command_reference_common.yaml` is used for settings that are common across all platforms while other files are used for settings that are unique to a given platform. Our `router eigrp` example uses the same cli syntax on all platforms, thus we only need to edit the common file:
+`lib/cisco_node_utils/cmd_ref/eigrp.yaml`
 
-`lib/cisco_node_utils/command_reference_common.yaml`
+YAML files in the `/cmd_ref/` subdirectory are automatically discovered at runtime, so we don't need to do anything special once we have created this file
 
-Four basic command_reference parameters will be defined for each resource property:
+The following basic command_reference parameters will be defined for each resource property:
 
  1. `config_get:` This defines the NX-OS CLI command (usually a 'show...' command) used to retrieve the property's current configuration state. Note that some commands may not be present until a feature is enabled.
  2. `config_get_token:` A regexp pattern for extracting state values from the config_get output.
  3. `config_set:` The NX-OS CLI configuration command(s) used to set the property configuration. May contain wildcards for variable parameters.
  4. `default_value:` This is typically the "factory" default state of the property, expressed as an actual value (true, 12, "off", etc)
+ 5. `kind:` The data type of this property. If omitted, the property will be a string by default. Commonly used values for this property are `int` and `boolean`.
+ 6. `multiple:` By default a property is assumed to be found once or not at all by the `config_get`/`config_get_token` lookup, and an error will be raised if multiple matches are found. If multiple matches are valid and expected, you must set `multiple: true` for this property.
 
-There are additional YAML command parameters available which are not covered by this document. Please see the [README_YAML.md](../lib/cisco_node_utils/README_YAML.md) document for more information on the structure and semantics of these files.
+There are additional YAML command parameters available which are not covered by this document. Please see the [README_YAML.md](../lib/cisco_node_utils/cmd_ref/README_YAML.md) document for more information on the structure and semantics of these files.
 The properties in this example require additional context for their config_get_token values because they need to differentiate between different eigrp instances. Most properties will also have a default value.
 
 *Note: Eigrp also has vrf and address-family contexts. These contexts require additional coding and are beyond the scope of this document.*
@@ -124,33 +127,40 @@ The properties in this example require additional context for their config_get_t
 
 *Note: The basic token definitions for multi-level commands can become long and complicated. A better solution for these commands is to use a command_reference _template: definition to simplify the configuration. The example below will use the basic syntax; see the ospf definitions in the YAML file for an example of _template: usage.*
 
+*Note: Property definitions in the YAML must be given in alphabetical order. Parameters under a property can be given in any order.*
+
 ```yaml
-eigrp:
-  feature:
-    # feature eigrp must be enabled before configuring router eigrp
-    config_get: 'show running eigrp all'
-    config_get_token: '/^feature eigrp$/'
-    config_set: '<state> feature eigrp'
-
-  router:
-    # There can be multiple eigrp instances
-    config_get: 'show running eigrp all'         # all eigrp-related configs
-    config_get_token: '/^router eigrp (\S+)$/'   # Match instance name
-    config_set: '<state> router eigrp <name>'    # config to add or remove
-
-  maximum_paths:
-    # This is an integer property
-    config_get: 'show running eigrp all'
-    config_get_token: ['/^router eigrp <name>$/', '/^maximum-paths (\d+)/']
-    config_set: ['router eigrp <name>', 'maximum-paths <val>']
-    default_value: 8
-
-  shutdown:
-    # This is a boolean property
-    config_get: 'show running eigrp all'
-    config_get_token: ['/^router eigrp <name>$/', '/^shutdown$/']
-    config_set: ['router eigrp <name>', '<state> shutdown']
-    default_value: false
+# eigrp.yaml
+---
+feature:
+  # feature eigrp must be enabled before configuring router eigrp
+  kind: boolean
+  config_get: 'show running eigrp all'
+  config_get_token: '/^feature eigrp$/'
+  config_set: '<state> feature eigrp'
+
+maximum_paths:
+  # This is an integer property
+  kind: int
+  config_get: 'show running eigrp all'
+  config_get_token: ['/^router eigrp <name>$/', '/^maximum-paths (\d+)/']
+  config_set: ['router eigrp <name>', 'maximum-paths <val>']
+  default_value: 8
+
+router:
+  # There can be multiple eigrp instances
+  multiple: true
+  config_get: 'show running eigrp all'         # all eigrp-related configs
+  config_get_token: '/^router eigrp (\S+)$/'   # Match instance name
+  config_set: '<state> router eigrp <name>'    # config to add or remove
+
+shutdown:
+  # This is a boolean property
+  kind: boolean
+  config_get: 'show running eigrp all'
+  config_get_token: ['/^router eigrp <name>$/', '/^shutdown$/']
+  config_set: ['router eigrp <name>', '<state> shutdown']
+  default_value: false
 ```
 
 ### <a name="comp_api">Step 2. cisco_node_utils API: router eigrp</a>
@@ -224,8 +234,7 @@ module Cisco
     end
 
     def feature_enabled
-      feat =  config_get('eigrp', 'feature')
-      return !(feat.nil? || feat.empty?)
+      config_get('eigrp', 'feature')
     rescue Cisco::CliError => e
       # This cmd will syntax reject if feature is not
       # enabled. Just catch the reject and return false.
@@ -275,8 +284,7 @@ module Cisco
     end
 
     def shutdown
-      state = config_get('eigrp', 'shutdown', name: @name)
-      state ? true : false
+      config_get('eigrp', 'shutdown', name: @name)
     end
 
     def shutdown=(state)
@@ -290,8 +298,7 @@ module Cisco
     end
 
     def maximum_paths
-      val = config_get('eigrp', 'maximum_paths', name: @name)
-      val.nil? ? default_maximum_paths : val.first.to_i
+      config_get('eigrp', 'maximum_paths', name: @name)
     end
 
     def maximum_paths=(val)
@@ -477,10 +484,11 @@ Inspecting 2 file
 
 The final step is to build and install the gem that contains the new APIs.
 
-Please note: `gem build` will only include files that are part of the repository. This means that new file `router_eigrp.rb` will be ignored by the build until it is added to the repo with `git add`:
+Please note: `gem build` will only include files that are part of the repository. This means that new files `router_eigrp.rb` and `eigrp.yaml` will be ignored by the build until they are added to the repo with `git add`:
 
 ```bash
-git add lib/cisco_node_utils/router_eigrp.rb
+git add lib/cisco_node_utils/router_eigrp.rb \
+        lib/cisco_node_utils/cmd_ref/eigrp.yaml
 ```
 
 From the root of the cisco-network-node-utils repository issue the following command.

data/docs/template-router.rb

@@ -43,8 +43,7 @@ module Cisco
     end
 
     def feature_enabled
-      feat = config_get('X__RESOURCE_NAME__X', 'feature')
-      return !(feat.nil? || feat.empty?)
+      config_get('X__RESOURCE_NAME__X', 'feature')
     rescue Cisco::CliError => e
       # This cmd will syntax reject if feature is not
       # enabled. Just catch the reject and return false.
@@ -94,9 +93,7 @@ module Cisco
     end
 
     def X__PROPERTY_BOOL__X
-      state = config_get('X__RESOURCE_NAME__X', 'X__PROPERTY_BOOL__X',
-                         name: @name)
-      state ? true : false
+      config_get('X__RESOURCE_NAME__X', 'X__PROPERTY_BOOL__X', name: @name)
     end
 
     def X__PROPERTY_BOOL__X=(state)
@@ -111,8 +108,7 @@ module Cisco
     end
 
     def X__PROPERTY_INT__X
-      val = config_get('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X', name: @name)
-      val.nil? ? default_X__PROPERTY_INT__X : val.first.to_i
+      config_get('X__RESOURCE_NAME__X', 'X__PROPERTY_INT__X', name: @name)
     end
 
     def X__PROPERTY_INT__X=(val)

data/lib/.rubocop.yml

@@ -3,16 +3,16 @@ inherit_from: ../.rubocop.yml
 # Baseline code complexity metrics for the lib/ subdirectory:
 
 Metrics/AbcSize:
-  Max: 47
+  Max: 45
 
 Metrics/CyclomaticComplexity:
-  Max: 17
+  Max: 23
 
 Metrics/MethodLength:
-  Max: 39
+  Max: 48
 
 Metrics/ParameterLists:
   Max: 9
 
 Metrics/PerceivedComplexity:
-  Max: 19
+  Max: 24

data/lib/cisco_node_utils.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2014-2015 Cisco and/or its affiliates.
+# Copyright (c) 2014-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.

data/lib/cisco_node_utils/aaa_authentication_login.rb

@@ -0,0 +1,96 @@
+#
+# NXAPI implementation of AaaAuthenticationLogin class
+#
+# April 2015, Alex Hunsberger
+#
+# Copyright (c) 2015-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.
+#
+
+require_relative 'node_util'
+
+module Cisco
+  # NXAPI implementation of AAA Authentication Login class
+  class AaaAuthenticationLogin < NodeUtil
+    # rubocop:disable DoubleNegation
+    # There is no "feature aaa" or "aaa new-model" on nxos, and only one
+    # instance which is always available
+    def self.ascii_authentication
+      !!config_get('aaa_authentication_login', 'ascii_authentication')
+    end
+
+    def self.ascii_authentication=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login',
+                 'ascii_authentication', no_cmd)
+    end
+
+    def self.default_ascii_authentication
+      config_get_default('aaa_authentication_login',
+                         'ascii_authentication')
+    end
+
+    def self.chap
+      !!config_get('aaa_authentication_login', 'chap')
+    end
+
+    def self.chap=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login', 'chap', no_cmd)
+    end
+
+    def self.default_chap
+      config_get_default('aaa_authentication_login', 'chap')
+    end
+
+    def self.error_display
+      !!config_get('aaa_authentication_login', 'error_display')
+    end
+
+    def self.error_display=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login', 'error_display', no_cmd)
+    end
+
+    def self.default_error_display
+      config_get_default('aaa_authentication_login', 'error_display')
+    end
+
+    def self.mschap
+      !!config_get('aaa_authentication_login', 'mschap')
+    end
+
+    def self.mschap=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login', 'mschap', no_cmd)
+    end
+
+    def self.default_mschap
+      config_get_default('aaa_authentication_login', 'mschap')
+    end
+
+    def self.mschapv2
+      !!config_get('aaa_authentication_login', 'mschapv2')
+    end
+
+    def self.mschapv2=(val)
+      no_cmd = val ? '' : 'no'
+      config_set('aaa_authentication_login', 'mschapv2', no_cmd)
+    end
+
+    def self.default_mschapv2
+      config_get_default('aaa_authentication_login', 'mschapv2')
+    end
+  end
+end

data/lib/cisco_node_utils/aaa_authentication_login_service.rb

@@ -0,0 +1,133 @@
+#
+# NXAPI implementation of AaaAuthenticationLoginService class
+#
+# May 2015, Alex Hunsberger
+#
+# Copyright (c) 2015-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.
+
+require_relative 'node_util'
+
+module Cisco
+  # NXAPI implementation of AAA Authentication Login Service class
+  class AaaAuthenticationLoginService < NodeUtil
+    attr_reader :name
+
+    def initialize(name, create=true)
+      fail TypeError unless name.is_a? String
+      # only console and default are supported currently
+      fail ArgumentError unless %w(console default).include? name
+      @name = name
+
+      # console needs to be explicitly created before it appears in
+      # "show run aaa all" but oddly not before it shows up in
+      # "show aaa authentication"
+      return unless create
+      m = default_method.to_s
+      config_set('aaa_auth_login_service', 'method', '', name, m)
+    end
+
+    def self.services
+      servs = {}
+      servs_arr = config_get('aaa_auth_login_service', 'services')
+      unless servs_arr.nil?
+        servs_arr.each do |s|
+          servs[s] = AaaAuthenticationLoginService.new(s, false)
+        end
+      end
+      servs
+    end
+
+    def destroy
+      # must specify exact current config string to unconfigure
+      m = method
+      m_str = m == :unselected ? '' : m.to_s
+      g_str = groups.join(' ')
+
+      if g_str.empty?
+        # cannot remove default local, so do nothing in this case
+        unless m == :local && @name == 'default'
+          config_set('aaa_auth_login_service', 'method',
+                     'no', @name, m_str)
+        end
+      else
+        config_set('aaa_auth_login_service', 'groups',
+                   'no', @name, g_str, m_str)
+      end
+    end
+
+    # groups aren't retrieved via the usual CLI regex memory method because
+    # there can be an arbitrary number of groups and specifying a repeating
+    # memory regex only captures the last match
+    # ex: aaa authentication login default group group1 group2 group3 none
+    def groups
+      # config_get returns the following format:
+      # [{service:"default",method:"group group1 none "},
+      #  {service:"console",method:"local "}]
+      hsh_arr = config_get('aaa_auth_login_service', 'groups')
+      fail 'unable to retrieve aaa groups information' if hsh_arr.empty?
+      hsh = hsh_arr.find { |x| x['service'] == @name }
+      # this should never happen unless @name is invalid
+      fail "no aaa info found for service #{@name}" if hsh.nil?
+      fail "no method found for #{@name} - api or feature change?" unless
+        hsh.key? 'method'
+      # ex: ["group", "group1", "local"] or maybe ["none"]
+      grps = hsh['method'].strip.split
+      return [] if grps.size == 1
+      # remove local, none, group keywords
+      grps -= %w(none local group)
+      grps
+    end
+
+    # default is []
+    def default_groups
+      config_get_default('aaa_auth_login_service', 'groups')
+    end
+
+    def method
+      m = config_get('aaa_auth_login_service', 'method', @name)
+      m.nil? ? :unselected : m.to_sym
+    end
+
+    # default is :local
+    def default_method
+      config_get_default('aaa_auth_login_service', 'method')
+    end
+
+    # groups and method must be set in the same CLI string
+    # aaa authentication login { console | default } /
+    #   none | local | group <group1 [group2, ...]> [none]
+    def groups_method_set(grps, m)
+      fail TypeError unless grps.is_a? Array
+      fail TypeError unless grps.all? { |x| x.is_a? String }
+      fail TypeError unless m.is_a? Symbol
+      # only the following 3 are supported (unselected = blank)
+      fail ArgumentError unless [:none, :local, :unselected].include? m
+
+      fail "method 'local' not allowed when groups are configured" if
+        m == :local && !grps.empty?
+      m_str = m == :unselected ? '' : m.to_s
+      g_str = grps.join(' ')
+
+      # config_set depends on whether we're setting groups or not
+      if g_str.empty?
+        config_set('aaa_auth_login_service', 'method',
+                   '', @name, m_str)
+      else
+        config_set('aaa_auth_login_service', 'groups',
+                   '', @name, g_str, m_str)
+      end
+    end
+  end
+end

data/lib/cisco_node_utils/aaa_authorization_service.rb

@@ -0,0 +1,150 @@
+# NXAPI implementation of AaaAuthorizationService class
+#
+# May 2015, Alex Hunsberger
+#
+# Copyright (c) 2015-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.
+
+require_relative 'node_util'
+
+module Cisco
+  # AaaAuthorizationService - node util class for aaa authorization management
+  class AaaAuthorizationService < NodeUtil
+    attr_reader :name, :type
+
+    def initialize(type, name, create=true)
+      fail TypeError unless name.is_a? String
+      fail TypeError unless type.is_a? Symbol
+      # only console and default are supported currently
+      fail ArgumentError unless %w(console default).include? name
+      fail ArgumentError unless
+        %i(commands config_commands ssh_certificate ssh_publickey).include? type
+      @name = name
+      @type = type
+      type_str = AaaAuthorizationService.auth_type_sym_to_str(type)
+
+      return unless create
+
+      config_set('aaa_authorization_service', 'method', '', type_str, name)
+    end
+
+    def self.services
+      servs = {}
+      servs_arr = config_get('aaa_authorization_service', 'services')
+      unless servs_arr.nil?
+        servs_arr.each do |type, name|
+          type = auth_type_str_to_sym(type)
+          servs[type] ||= {}
+          servs[type][name] = AaaAuthorizationService.new(type, name, false)
+        end
+      end
+      servs
+    end
+
+    def destroy
+      # must specify exact current config string to unconfigure
+      m = method
+      m_str = m == :unselected ? '' : m.to_s
+      g_str = groups.join(' ')
+      t_str = AaaAuthorizationService.auth_type_sym_to_str(@type)
+
+      if g_str.empty?
+        # cannot remove no groups + local, so do nothing in this case
+        unless m == :local
+          config_set('aaa_authorization_service', 'method',
+                     'no', t_str, @name)
+        end
+      else
+        config_set('aaa_authorization_service', 'groups',
+                   'no', t_str, @name, g_str, m_str)
+      end
+    end
+
+    # groups aren't retrieved via the usual CLI regex memory type because
+    # there can be an arbitrary number of groups and specifying a repeating
+    # memory regex only captures the last match
+    # ex: aaa authorization console group group1 group2 group3 local
+    def groups
+      # config_get returns the following format:
+      # [{"appl_subtype": "console",
+      #   "cmd_type": "config-commands",
+      #   "methods": "group foo bar local "}], ...
+      hsh_arr = config_get('aaa_authorization_service', 'groups')
+      fail 'unable to retrieve aaa groups information' if hsh_arr.empty?
+      type_s = AaaAuthorizationService.auth_type_sym_to_str(@type)
+      hsh = hsh_arr.find do |x|
+        x['appl_subtype'] == @name && x['cmd_type'] == type_s
+      end
+      fail "no aaa info for #{@type},#{@name}" if hsh.nil?
+      fail "no aaa info for #{@type},#{@name}. api/feature change?" unless
+        hsh.key? 'methods'
+      # ex: ["group", "group1", "local"]
+      grps = hsh['methods'].strip.split
+      # return [] if grps.size == 1
+      # remove local, group keywords
+      grps -= %w(local group)
+      grps
+    end
+
+    # default is []
+    def default_groups
+      config_get_default('aaa_authorization_service', 'groups')
+    end
+
+    def method
+      t_str = AaaAuthorizationService.auth_type_sym_to_str(@type)
+      m = config_get('aaa_authorization_service', 'method', @name, t_str)
+      m.nil? ? :unselected : m.to_sym
+    end
+
+    # default is :local
+    def default_method
+      config_get_default('aaa_authorization_service', 'method')
+    end
+
+    # groups and method must be set in the same CLI string
+    # aaa authorization login <type> <name> /
+    #   local | group <group1 [group2, ...]> [local]
+    def groups_method_set(grps, m)
+      fail TypeError unless grps.is_a? Array
+      fail TypeError unless grps.all? { |x| x.is_a? String }
+      fail TypeError unless m.is_a? Symbol
+      # only the following are supported (unselected = blank)
+      fail ArgumentError unless [:local, :unselected].include? m
+
+      # raise "type 'local' not allowed when groups are configured" if
+      #  m == :local and not grps.empty?
+      m_str = m == :unselected ? '' : m.to_s
+      g_str = grps.join(' ')
+      t_str = AaaAuthorizationService.auth_type_sym_to_str(@type)
+
+      # config_set depends on whether we're setting groups or not
+      if g_str.empty?
+        config_set('aaa_authorization_service', 'method',
+                   '', t_str, @name)
+      else
+        config_set('aaa_authorization_service', 'groups',
+                   '', t_str, @name, g_str, m_str)
+      end
+    end
+
+    def self.auth_type_sym_to_str(sym)
+      sym.to_s.sub('_', '-')
+    end
+
+    def self.auth_type_str_to_sym(str)
+      str.sub('-', '_').to_sym
+    end
+  end
+end