cisco_node_utils 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6396905732ac665cf55bb63e17792c399a95c41f
-  data.tar.gz: 0a007ab3337c8dfe52a35deabb9a7627ba539e0f
+  metadata.gz: 5972809d82dc9ad3991f11217e174556220418c6
+  data.tar.gz: abec7a2fbd8757cdf73bb5eb84c7e154e777ffbc
 SHA512:
-  metadata.gz: dd703cf0f14758739bc2382296af32c2b4c202884a3fc53132e0e3e69e1de5135035b2a98afd2b2632d21062d605779fdf3506d0210056c5542a747c05419ade
-  data.tar.gz: 4d52c817fd90803451306ab759de4b28b2dc17818291b2d14440299ded9d8fe5641c5e22e800508175ba20d5cb73bfc580044e920bcd3cdbb175a3c5c810965b
+  metadata.gz: f8d80e3c768ebbd436ce9d2d0f6e795941932c517834e5c644aa12bce22fddee6ee82efb545857900de5a0127bdfa58911d4e411bbf6dfc5dd887fbb52a1567c
+  data.tar.gz: 9a0ac0b2beb5cad046e28ba570f5afdf3c98543b1d11e76dadd1ca33fa3c57757d6e136e2fe55f984d3c6ed6e448f0f2e0cd07ba72088f024ab90a5ecd7033c3

data/.gitignore

@@ -3,4 +3,5 @@ pkg/*
 vendor/*
 coverage
 Gemfile.lock
-*.gem
+*.gem
+*.swp

data/CHANGELOG.md

@@ -1,6 +1,126 @@
 Changelog
 =========
 
+## [v1.2.0]
+
+### New feature support
+* ACL (platforms: Nexus 3k and Nexus 9k)
+  * acl (@saqibraza)
+  * ace (@yjyongz)
+  * remark ace (@bansalpradeep)
+* EVPN (platforms: Nexus 3k and Nexus 9k)
+  * evpn_vni (@andish)
+* Fabric Path (platforms: Nexus 7k)
+  * fabricpath_global (@dcheriancisco)
+  * fabricpath_topology (@dcheriancisco)
+* Feature
+  * feature (@robert-w-gries)
+* Interface (platforms: Nexus 3k, Nexus 5k, Nexus 6k, Nexus 7k and Nexus 9k)
+  * interface_channel_group (@chrisvanheuveln)
+  * interface_portchannel (@saichint)
+  * interface_service_vni (@chrisvanheuveln)
+* PIM (platforms: Nexus 3k and Nexus 9k)
+  * pim (@smigopal)
+  * pim_group_list (@smigopal)
+  * pim_rp_address (@smigopal)
+* Port Channel (platforms: Nexus 3k, Nexus 5k, Nexus 6k, Nexus 7k and Nexus 9k)
+  * interface_channel_group (@chrisvanheuveln)
+  * interface_portchannel (@saichint)
+  * portchannel_global (@saichint)
+* SNMP (platforms: Nexus 3k, Nexus 5k, Nexus 6k, Nexus 7k and Nexus 9k)
+  * snmpnotification (@tphoney)
+* VDC (platforms: Nexus 7k)
+  * vdc (@chrisvanheuveln)
+* VPC (platforms: Nexus 3k, Nexus 5k, Nexus 6k, Nexus 7k and Nexus 9k)
+  * vpc (@dcheriancisco)
+* VRF (platforms: Nexus 3k, Nexus 5k, Nexus 6k, Nexus 7k and Nexus 9k)
+  * vrf_af (@chrisvanheuveln)
+* VXLAN (platforms: Nexus 9k)
+  * overlay_global (@alok-aggarwal)
+  * vxlan_vtep (@dcheriancisco)
+  * vxlan_vtep_vni (@mikewiebe)
+
+  
+### Additional platform support added to existing classes
+#### Cisco Nexus 56xx, 60xx and 7xxx
+* AAA
+  * aaa_authentication_login
+  * aaa_authentication_login_service
+  * aaa_authentication_service
+* BGP
+  * bgp
+  * bgp_af
+  * bgp_af_neighobr
+  * bgp_neighbor_af
+* COMMAND_CONFIG
+  * command_config (config_parser)
+* DOMAIN
+  * dns_domain
+  * domain_name
+  * name_server
+* INTERFACE
+  * interface
+* NTP
+  * ntp_config
+  * ntp_server
+* OSPF
+  * interface_ospf
+  * ospf
+  * ospf_vrf
+* RADIUS
+  * radius_global
+* SNMP
+  * snmp_community
+  * snmp_group
+  * snmp_notification_receiver
+  * snmp_server
+  * snmp_user
+* SYSLOG
+  * syslog_server
+  * syslog_setting
+* TACACS
+  * tacacs_server
+  * tacacs_server_group
+  * tacacs_server_host
+* VLAN
+  * vlan
+
+### Added
+
+* `Cisco::UnsupportedError` exception class, raised when a command is explicitly marked as unsupported on a particular class of nodes.
+* Extend bgp with attributes:
+  * `disable_policy_batching`, `disable_policy_batching_ipv4`, `disable_policy_batching_ipv6`
+  * `event_history_cli`, `event_history_detail`, `event_history_events`, `event_history_periodic`
+  * `fast_external_fallover`
+  * `flush_routes`
+  * `isolate`
+  * `neighbor_down_fib_accelerate`
+  * `route_distinguisher`
+* Extend bgp_af with attributes:
+  * `default_metric`
+  * `distance_ebgp`, `distance_ibgp`, `distance_local`
+  * `inject_map`
+  * `suppress_inactive`
+  * `table_map`
+* Extend interface with attributes:
+  * `fabric_forwarding_anycast_gateway`
+  * `ipv4_acl_in`, `ipv4_acl_out`, `ipv6_acl_in`, `ipv6_acl_out`
+  * `ipv4_address_secondary`, `ipv4_arp_timeout`
+  * `vlan_mapping`
+  * `vpc_id`, `vpc_peer_link`
+  * switchport mode `fabricpath`
+* Extend vrf with attributes:
+  * `vni`
+* Extend vlan with attribute:
+  * `mode`
+
+### Changed
+
+* Major refactor and enhancement of `CommandReference` YAML files:
+  - Added support for `auto_default`, `default_only`, `kind`, and `multiple`
+  - Added filtering by product ID (`/N7K/`) and by client type (`cli_nexus`)
+  - `CommandReference` methods that do key-value style wildcard substitution now raise an `ArgumentError` if the result is empty (because not enough parameters were supplied). 
+
 ## [v1.1.0]
 
 ### New feature support
@@ -15,10 +135,12 @@ Changelog
 * RADIUS
   * radius_global (@jonnytpuppet)
   * radius_server (@jonnytpuppet)
+* SNMP
+  * snmp_notification_receiver (@jonnytpuppet)
 * SYSLOG
   * syslog_server (@jonnytpuppet)
   * syslog_setting (@jonnytpuppet)
-* Miscellaneous 
+* Miscellaneous
   * dns_domain (@hunner)
   * domain_name (@bmjen)
   * name_server (@hunner)
@@ -43,6 +165,8 @@ Changelog
   * 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.
+* Added support for radius_global (@jonnytpuppet)
+* Added support for radius_server_group (@jonnytpuppet)
 
 ### Fixed
 
@@ -92,6 +216,7 @@ Changelog
 [git-flow]: https://github.com/petervanderdoes/gitflow-avh
 [SimpleCov]: https://github.com/colszowka/simplecov
 
+[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
 [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/README.md

@@ -35,10 +35,23 @@ Please see [Learning Resources](#resources) for additional references.
 
 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.
+open source management tools.
 
-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)
+This CiscoNodeUtils gem release supports the following:
+
+Platform         | OS    | OS Version           |
+-----------------|-------|----------------------|
+Cisco Nexus 30xx | NX-OS | 7.0(3)I2(1) and later
+Cisco Nexus 31xx | NX-OS | 7.0(3)I2(1) and later
+Cisco Nexus 93xx | NX-OS | 7.0(3)I2(1) and later
+Cisco Nexus 95xx | NX-OS | 7.0(3)I2(1) and later
+Cisco N9kv       | NX-OS | 7.0(3)I2(1) and later
+Cisco Nexus 56xx | NX-OS | 7.3(0)N1(1) and later
+Cisco Nexus 60xx | NX-OS | 7.3(0)N1(1) and later
+Cisco Nexus 7xxx | NX-OS | 7.3(0)D1(1) and later
+
+
+Please note: For Cisco Nexus 3k and 9k platforms, 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>
 
@@ -97,15 +110,9 @@ network node. It provides the base APIs `config_set`, `config_get`, and
 
 ### 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`.
+The `CommandReference` class abstracts away the differences between various supported `Node` types, be that API differences (CLI vs. YANG), platform differences (NX-OS vs. IOS XR), or hardware differences (Nexus 9xxx vs. Nexus 3xxx). A series of YAML files describe various `feature` groupings. Each file describes a set of `attributes` of the given feature and the specifics of how to inspect and manage these attributes for any supported `Node` types.  When a `Node` is connected, the platform identification of the Node is used to construct a `CommandReference` instance containing a set of `CmdRef` objects specific to this `Node`. 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).
+See also [README_YAML](lib/cisco_node_utils/cmd_ref/README_YAML.md).
 
 ### Feature Providers
 
@@ -161,7 +168,7 @@ See [CHANGELOG](CHANGELOG.md) for a list of changes.
 ## <a name="license_info">License Information</a>
 
 
-Copyright (c) 2013-2015 Cisco and/or its affiliates.
+Copyright (c) 2013-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/Rakefile

@@ -18,4 +18,5 @@ Rake::TestTask.new do |t|
   t.pattern = 'tests/test_*.rb'
   t.warning = true
   t.verbose = true
+  t.options = '-v'
 end

data/bin/git/hooks/commit-msg/enforce_style

@@ -76,6 +76,14 @@ if $errors > 0 # rubocop:disable Style/GlobalVars
   puts '{'
   puts message_lines.join("\n")
   puts '}'
+
+  fd = IO.sysopen('/dev/tty', 'w+')
+  a = IO.new(fd, 'w+')
+  a.puts 'Continue anyway? [y/N] '
+  response = a.gets.chomp
+  # rubocop:disable Style/GlobalVars
+  $errors = 0 if response.downcase[0] == 'y'
+  # rubocop:enable Style/GlobalVars
 end
 
 exit $errors # rubocop:disable Style/GlobalVars

data/cisco_node_utils.gemspec

@@ -7,7 +7,8 @@ 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']
+                        'Chris Van Heuveln', 'Mike Wiebe', 'Jie Yang',
+                        'Rob Gries']
   spec.email         = 'cisco_agent_gem@cisco.com'
   spec.summary       = 'Utilities for management of Cisco network nodes'
   spec.description   = <<-EOF
@@ -30,7 +31,7 @@ Currently supports NX-OS nodes.
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rubocop', '= 0.34.2'
+  spec.add_development_dependency 'rubocop', '= 0.35.1'
   spec.add_development_dependency 'simplecov', '~> 0.9'
-  spec.add_runtime_dependency 'cisco_nxapi', '~> 1.0'
+  spec.add_runtime_dependency 'cisco_nxapi', '~> 1.0', '>= 1.0.1'
 end

data/docs/README-develop-best-practices.md

@@ -12,14 +12,16 @@ This document is intended to assist in developing cisco_node_utils API's that ar
 
 ## <a name="ydbp">YAML Development Best Practices</a>
 
-* [Y1](#yaml1): All yaml feature entries should be kept in alphabetical order.
-* [Y2](#yaml2): Use *regexp* anchors where needed for `config_get` and `config_get_token` entries.
-* Y3: Avoid nested optional matches.
-* [Y4](#yaml4): Use the `_template` feature when getting/setting the same property value at multiple levels.
-* [Y5](#yaml5): When possible include a `default_value` that represents the system default value.
-* [Y6](#yaml6): When possible, use the same `config_get` show command for all properties and document any anomalies.
-* [Y7](#yaml7): Use Key-value wildcards instead of Printf-style wildcards.
-* [Y8](#yaml8): Selection of `show` commands for `config_get`.
+* [Y1](#yaml1): One feature per YAML file
+* [Y2](#yaml2): All attribute entries must be kept in alphabetical order.
+* [Y3](#yaml3): Use *regexp* anchors where needed for `config_get` and `config_get_token` entries.
+* [Y4](#yaml4): Avoid nested optional matches.
+* [Y5](#yaml5): Use the `_template` feature when getting/setting the same property value at multiple levels.
+* [Y6](#yaml6): When possible include a `default_value` that represents the system default value.
+* [Y7](#yaml7): When possible, use the same `config_get` show command for all properties and document any anomalies.
+* [Y8](#yaml8): Use Key-value wildcards instead of Printf-style wildcards.
+* [Y9](#yaml9): Selection of `show` commands for `config_get`.
+* [Y10](#yaml10): Use `true` and `false` for boolean values.
 
 
 
@@ -43,132 +45,145 @@ This document is intended to assist in developing cisco_node_utils API's that ar
 
 ## YAML Best Practices:
 
-### <a name="yaml1">Y1: All yaml feature entries should be kept in alphabetical order.
+### <a name="yaml1">Y1: One feature per YAML file
 
-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.
+Each YAML file should define a single 'feature' (a closely related set of configuration properties). Don't create "one YAML file to rule them all".
 
-Top level features in alpabetical order:
+### <a name="yaml2">Y2: All attribute entries must be kept in alphabetical order.
 
-```
-aaa_authentication_login:
-...
-dnsclient:
-...
-interface:
-```
-
-Options under a feature:
+All attribute entries in a given YAML file must be kept in alphabetical order. 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.
 
-```
-interface:
-  access_vlan:
-    ...
-  all_interfaces:
-    ...
-  create:
-    ...
-  description:
-    ...  
-```
+This rule is enforced by the `Cisco::CommandReference` class itself - it will raise an exception if it detects any out-of-order entries.
 
-### <a name="yaml2">Y2: Use *regexp* anchors where needed for `config_get` and `config_get_token` entries.
+### <a name="yaml3">Y3: Use *regexp* anchors where needed for `config_get` and `config_get_token` entries.
 
 Please use *regexp* anchors `^$` to ensure you match the correct feature information in the `show` output.
 
+```yaml
+# syslog_settings.yaml
+timestamp:
+  config_get: "show running-config all | include '^logging timestamp'"
+  config_get_token: '/^logging timestamp (.*)$/'
+  config_set: '<state> logging timestamp <units>'
+  default_value: 'seconds'
 ```
-syslog_settings:
-  timestamp:
-    config_get: "show running-config all | include '^logging timestamp'"
-    config_get_token: '/^logging timestamp (.*)$/'
-    config_set: '<state> logging timestamp <units>'
-    default_value: 'seconds'
+
+### <a name="yaml4">Y4: Avoid nested optional matches.
+
+Regexps containing optional match strings inside other match strings become
+complex to work with and difficult to maintain.
+
+One case where this may crop up is in trying to match both affirmative and
+negative variants of a config command:
+
+```yaml
+config_get_token: ['/^interface <name>$/i', '/^((no )?switchport)$/']
+
+config_get_token: '/^(no)? ?ip tacacs source-interface ?(\S+)?$/'
 ```
 
-### <a name="yaml3">Y3: Avoid nested optional matches.
+Instead, match the affirmative form of a command and treat its absence as
+confirmation of the negative form:
 
-### <a name="yaml4">Y4: Use the `_template` feature when getting/setting the same property value at multiple levels.
+```yaml
+config_get_token: ['/^interface <name>$/i', '/^switchport$/']
+
+config_get_token: '/^tacacs-server source-interface (\S+)$/'
+```
+
+### <a name="yaml5">Y5: Use the `_template` feature when getting/setting the same property value at multiple levels.
 
 Using the template below, `auto_cost` and `default_metric` can be set under `router ospf foo` and `router ospf foo; vrf blue`.
 
-```
-ospf:
-  _template:
-    config_get: "show running ospf all"
-    config_get_token: '/^router ospf <name>$/'
-    config_get_token_append:
-      - '/^vrf <vrf>$/'
-    config_set: "router ospf <name>"
-    config_set_append:
-      - "vrf <vrf>"
-
-  auto_cost:
-    config_get_token_append: '/^auto-cost reference-bandwidth (\d+)\s*(\S+)?$/'
-    config_set_append: "auto-cost reference-bandwidth <cost> <type>"
-    default_value: [40, "Gbps"]
-
-  default_metric:
-    config_get_token_append: '/^default-metric (\d+)?$/'
-    config_set_append: "<state> default-metric <metric>"
-    default_value: 0
+```yaml
+# ospf.yaml
+_template:
+  config_get: "show running ospf all"
+  config_get_token: '/^router ospf <name>$/'
+  config_get_token_append:
+    - '/^vrf <vrf>$/'
+  config_set: "router ospf <name>"
+  config_set_append:
+    - "vrf <vrf>"
+
+auto_cost:
+  config_get_token_append: '/^auto-cost reference-bandwidth (\d+)\s*(\S+)?$/'
+  config_set_append: "auto-cost reference-bandwidth <cost> <type>"
+  default_value: [40, "Gbps"]
+
+default_metric:
+  config_get_token_append: '/^default-metric (\d+)?$/'
+  config_set_append: "<state> default-metric <metric>"
+  default_value: 0
 ```
 
-### <a name="yaml5">Y5: When possible include a `default_value` that represents the system default value.
+### <a name="yaml6">Y6: When possible include a `default_value` that represents the system default value.
 
 Please make sure to specify a `default_value` and document properties that don't have a system default.  System defaults may differ between cisco platforms making it important to define for lookup in the cisco_node_utils common object methods.
 
 
 Default value for `message_digest_alg_type` is `md5`
 
-```
+```yaml
 message_digest_alg_type:
-    config_get: 'show running interface all'
-    config_get_token: ['/^interface %s$/i', '/^\s*ip ospf message-digest-key \d+ (\S+)/']
-    default_value: 'md5'
+  config_get: 'show running interface all'
+  config_get_token: ['/^interface <name>$/i', '/^\s*ip ospf message-digest-key \d+ (\S+)/']
+  default_value: 'md5'
 ```
 
 **NOTE1: Use strings rather then symbols when applicable**.
 
-If the `default_value` differs between cisco platforms, the more specific `command_reference_[platform].yaml` file should be used.
+If the `default_value` differs between cisco platforms, use per-API or per-platform keys in the YAML as needed. For example, if the default value on all platforms except the N9K is `md5` then you might do something like this:
+
+```yaml
+message_digest_alg_type:
+  config_get: 'show running interface all'
+  config_get_token: ['/^interface <name>$/i', '/^\s*ip ospf message-digest-key \d+ (\S+)/']
+  /N9K/:
+    default_value: 'sha2'
+  else:
+    default_value: 'md5'
+```
 
-For example, if the default value on all platforms except the n9k is `md5` then set the entry in `command_reference_common.yaml` to `md5` and set the entry in `command_reference_n9k.yaml` to it's default `sha2`.
+See [README_YAML](../lib/cisco_node_utils/cmd_ref/README_YAML.md) for more details about this advanced feature.
 
-### <a name="yaml6">Y6: When possible, use the same `config_get` show command for all properties and document any anomalies.
+### <a name="yaml7">Y7: When possible, use the same `config_get` show command for all properties and document any anomalies.
 
 All properties below use the `show run tacacs all` command except `directed_request` which is documented.
 
-```
-tacacs_server:
-  deadtime:
-    config_get: "show run tacacs all"
-    config_get_token: '/^tacacs-server deadtime\s+(\d+)/'
-    config_set: "%s tacacs-server deadtime %d"
-    default_value: 0
-
-  directed_request:
-    # oddly, directed request must be retrieved from aaa output
-    config_get: "show running aaa all"
-    config_get_token: '/(?:no)?\s*tacacs-server directed-request/'
-    config_set: "%s tacacs-server directed-request"
-    default_value: false
-
-  encryption_type:
-    config_get: "show run tacacs all"
-    config_get_token: '/^tacacs-server key (\d+)\s+(\S+)/'
-    default_value: 0
-
-  encryption_password:
-    config_get: "show run tacacs all"
-    config_get_token: '/^tacacs-server key (\d+)\s+(\S+)/'
-    default_value: ""
+```yaml
+# tacacs_server.yaml
+deadtime:
+  config_get: "show run tacacs all"
+  config_get_token: '/^tacacs-server deadtime\s+(\d+)/'
+  config_set: "<state> tacacs-server deadtime <time>"
+  default_value: 0
+
+directed_request:
+  # oddly, directed request must be retrieved from aaa output
+  config_get: "show running aaa all"
+  config_get_token: '/(?:no)?\s*tacacs-server directed-request/'
+  config_set: "<state> tacacs-server directed-request"
+  default_value: false
+
+encryption_type:
+  config_get: "show run tacacs all"
+  config_get_token: '/^tacacs-server key (\d+)\s+(\S+)/'
+  default_value: 0
+
+encryption_password:
+  config_get: "show run tacacs all"
+  config_get_token: '/^tacacs-server key (\d+)\s+(\S+)/'
+  default_value: ""
 ```
 
-### <a name="yaml7">Y7: Use Key-value wildcards instead of Printf-style wildcards.
+### <a name="yaml8">Y8: Use Key-value wildcards instead of Printf-style wildcards.
 
-The following 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.
+Key-value wildcards are moderately more complex to implement than Printf-style wildcards but they are more readable in the Ruby code and are flexible enough to handle significant platform differences in CLI. Key-value wildcards are therefore the recommended approach for new development.
 
 **Key-value wildcards**
 
-```
+```yaml
 config_set_append: "<state> log-adjacency-changes <type>"
 ```
 
@@ -176,17 +191,20 @@ This following approach is quick to implement and concise, but less flexible - i
 
 **Printf-style wildcards**
 
-```
+```yaml
 config_set_append: "%s log-adjacency-changes %s"
 ```
 
-### <a name="yaml8">Y8: Selection of `show` commands for `config_get`.
+### <a name="yaml9">Y9: Selection of `show` commands for `config_get`.
 
 The following commands should be preferred over `show [feature]` commands since not all `show [feature]` commands behave in the same manner across cisco platforms.
 
 * `show running [feature] all` if available.
 * `show running all` if `show running [feature] all` is *not* available.
 
+### <a name="yaml10">Y10: Use `true` and `false` for boolean values.
+
+YAML allows various synonyms for `true` and `false` such as `yes` and `no`, but for consistency and readability (especially to users more familiar with Ruby than with YAML), we recommend using `true` and `false` rather than any of their synonyms.
 
 ## Common Object Best Practices:
 
@@ -196,7 +214,7 @@ Many cisco features can be configured under the default or global vrf and also u
 
 The following `initialize` and `self.vrfs` methods account for configuration under `default` and `non-default vrfs`.
 
-```
+```ruby
     def initialize(router, name, instantiate=true)
       fail TypeError if router.nil?
       fail TypeError if name.nil?
@@ -237,9 +255,9 @@ The following `initialize` and `self.vrfs` methods account for configuration und
 
 Having this logic defined in the common object lets the minitest easily check the specific instances.
 
-Without this equality operator `==` only passes if they are the same instance object.  With this equality operator `==` passes if they are different objects referring to the same configuration on the node.
+The built-in equality operator `==` returns true only if they are the same instance object. The `==` method below is used to override the built-in equality operator and return true even if they are different objects referring to the same configuration on the node.
 
-```
+```ruby
   def ==(other)
     (name == other.name) && (vrf == other.vrf)
   end
@@ -247,7 +265,7 @@ Without this equality operator `==` only passes if they are the same instance ob
 
 Example Usage:
 
-```
+```ruby
   def test_dnsdomain_create_destroy_multiple
     id1 = 'aoeu.com'
     id2 = 'asdf.com'
@@ -272,7 +290,7 @@ Example Usage:
 
 Our convention is to let `''` represent 'not configured at all' rather than `nil`. For example, `interface.rb`:
 
-```
+```ruby
 def vrf
   vrf = config_get('interface', 'vrf', @name)
   return '' if vrf.nil?
@@ -290,7 +308,7 @@ def vrf=(vrf)
 
 However, if a property has a default value (it is never truly 'removed'), then we should do this instead:
 
-```
+```ruby
 def access_vlan
   vlan = config_get('interface', 'access_vlan', @name)
   return default_access_vlan if vlan.nil?
@@ -307,7 +325,7 @@ In order to have a complete set of api's for each property it is important that
 
 This can be seen in the following `router_id` property.
 
-```
+```ruby
 # Getter Method
 def router_id
   match = config_get('ospf', 'router_id', @get_args)
@@ -362,7 +380,7 @@ The more specific assertions also produce more helpful failure messages if somet
 Rather then hardcode an interface name that may or may not exist, instead use 
 the `interfaces[]` array.
 
-```
+```ruby
 def create_interface(ifname=interfaces[0])
   @default_show_command = show_cmd(ifname)
   Interface.new(ifname)
@@ -375,11 +393,11 @@ If additional interfaces are needed array index `1` and `2` may be used.
 
 For conveninence the `config` helper method has been provided for device configuration within the minitests.
 
-```
+```ruby
 config('no feature ospf')
 ```
 
-```
+```ruby
 config('feature ospf'; 'router ospf green')
 ```
 
@@ -387,7 +405,7 @@ config('feature ospf'; 'router ospf green')
 
 We have a very common pattern in minitest where we execute some show command over the telnet connection, match it against some regexp pattern, and succeed or fail based on the result. Helper methods `assert_show_match` and `refute_show_match` support this pattern.
 
-```
+```ruby
 assert_show_match(command: 'show run all | no-more',
                   pattern: /interface port-channel 1/,
                   msg:     'port-channel is not present but it should be')
@@ -395,7 +413,7 @@ assert_show_match(command: 'show run all | no-more',
 
 If your `command` and/or `pattern` are the same throughout a test case or throughout a test suite, you can set the test case instance variables `@default_show_command` and/or `@default_output_pattern` which serve as defaults for these parameters:
 
-```
+```ruby
 @default_show_command = 'show run interface all | include "interface" | no-more'
 assert_output_match(pattern: /interface port-channel 10/)
 refute_output_match(pattern: /interface port-channel 11/)