--
This workflow map aids users, developers and maintainers of the CiscoNodeUtils project in selecting the appropriate document(s) for their task.
- User Guides - the remainder of this document is aimed at end users
- Developer Guides
- CONTRIBUTING.md : Contribution guidelines
- README-develop-node-utils-APIs.md : Developing new CiscoNodeUtils APIs
- README-develop-best-practices.md : Development best practices
- Maintainers Guides
- README-maintainers.md : Guidelines for core maintainers of the CiscoNodeUtils project
- All developer guides apply to maintainers as well
Please see Learning Resources for additional references.
--
- Overview
- Installation
- Configuration
- Documentation
- Examples
- Changelog
- Learning Resources
- License Information
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 CiscoNodeUtils gem release supports the following:
Platform | OS | OS Version |
---|---|---|
Cisco Nexus N9k | NX-OS | 7.0(3)I2(1) and later |
Cisco Nexus N3k | NX-OS | 7.0(3)I2(1) and later |
Cisco Nexus N5k | NX-OS | 7.3(0)N1(1) and later |
Cisco Nexus N6k | NX-OS | 7.3(0)N1(1) and later |
Cisco Nexus N7k | NX-OS | 7.3(0)D1(1) and later |
Cisco XRv9k | IOS-XR | 6.0.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 user ID can obtain a copy of a virtual Nexus N9000/N3000 by sending their cisco.com user ID in an email to [email protected]. If you do not have a cisco.com user ID please register for one at https://tools.cisco.com/IDREG/guestRegistration
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.
Depending on the installation environment (Linux, NX-OS, or IOS XR), 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)
If both files exist and are readable, configuration in the user-specific file will take precedence over the system configuration.
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:
- When installing this gem on IOS XR nodes, this file needs to specify an IOS XR administrator
username
andpassword
for the local (default
) node. Additionally, if the gRPC server is configured to listen on a port other than its default of 57400, theport
number must be specified in this file. For security purposes, it is highly recommended that access to this file be restricted to only the owning user (chmod 0600
). - When developing for or testing this gem, this file can specify one or more NX-OS and/or IOS XR 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
, andpassword
. - IOS XR nodes must be defined with a
host
,username
, andpassword
, plus aport
if the gRPC server is listening on a non-default port.
- A node labeled as
An example configuration file (illustrating each of the above scenarios) is provided with this gem at docs/cisco_node_utils.yaml.example
.
The Client
class provides a low-level interface for communicating with the Cisco network node. It provides the base APIs create
, get
, and set
. Currently there are two subclasses:
Cisco::Client::NXAPI
- client for communicating with NX-OS 7.0(3)I2(1) and later, using NX-API.Cisco::Client::GRPC
- client for communicating with IOS XR 6.0.1 and later, using gRPC.
For a greater level of abstraction, the Node
class is generally used, but the Client
classes can be invoked directly if desired.
The Node
class is a singleton which wraps around the Client
class to provide for management of a given Cisco network node. It provides the base APIs config_set
, config_get
, and config_get_default
.
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 N9k vs. Nexus N3k). 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.
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
.
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
.
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). The Client and Node APIs will read connection information (host, username, etc.) from a configuration file. 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.
Note: Entries in the configuration file can specify local or remote devices.
require 'cisco_node_utils'
# 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')
puts client2.get(command: 'show version')
require 'cisco_node_utils'
# 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')
require 'cisco_node_utils'
# Create a connection to the following nodes:
# - 'default' device defined in the cisco_node_utils.yaml file
# - 'xrv9k' device defined in the cisco_node_utils.yaml file
client1 = Cisco::Client.create()
client2 = Cisco::Client.create('xrv9k')
# 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.
# via CLI
client1.set(values: 'vrf blue')
puts client1.get(command: 'show run vrf')
# via YANG
client2.set(data_format: :yang_json,
values: '{"Cisco-IOS-XR-infra-rsi-cfg:vrfs":{"vrf":[{"vrf-name":"red", "create":[null]}]}}')
puts client2.get(data_format: :yang_json, command: '{"Cisco-IOS-XR-infra-rsi-cfg:vrfs": [null]}')
require 'cisco_node_utils'
# Create a connection to the following:
# - 'default' device defined in the cisco_node_utils.yaml
node = Cisco::Node.instance()
# OR:
# - 'xrv9k' device defined in the cisco_node_utils.yaml file
# Cisco::Environment.default_environment_name = 'xrv9k'
# 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.
# via CLI
node.config_set('vrf', 'create', vrf: 'blue')
puts node.config_get('vrf', 'all_vrfs')
# via yang
node.merge_yang('{"Cisco-IOS-XR-infra-rsi-cfg:vrfs":{"vrf":[{"vrf-name":"red", "create":[null]}]}}')
puts node.get_yang('{"Cisco-IOS-XR-infra-rsi-cfg:vrfs": [null]}')
See CHANGELOG for a list of changes.
- Chef
- Puppet
- Markdown (for editing documentation)
- Ruby
- Ruby Gems
- YAML
- Yum
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. 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.