Node.JS module to access Cisco IOS XR XML interface

Post Syndicated from Delian Delchev original http://deliantech.blogspot.com/2015/03/nodejs-module-to-access-cisco-ios-xr.html

Hello to all,This is the early version of my module for Node.JS that allows configuring routers and retrieving information over Cisco IOS XR’s XML interface.The module is in its early phases – it still does not read IOS XR schema files and therefore decode the data (in JSON) in a little ugly way (too much arrays). I am planning to fix it, so there may be changes in the responses.Please see bellow the first version of the documentation I’ve set in the github:Module for Cisco XML API interface IOS XRThis is a small module that implements interface to Cisco IOS XR XML Interface.This module open an maintain TCP session to the router, sends requests and receive responses.InstallationTo install the module do something like that:npm install node-ciscoxmlUsageIt is very easy to use this module. See the methods bellow:Load the moduleTo load and use the module, you have to use a code similar to this:var cxml = require(‘node-ciscoxml’);var c = cxml( { …connect options.. });Module init and connect optionshost (default 127.0.0.1) – the hostname of the router where we’ll connectport (default 38751) – the port of the router where XML API is listeningusername (default guest) – the username used for authentication, if username is requested by the remote sidepassword (default guest) – the password used for authentication, if password is requested by the remote sideconnectErrCnt (default 3) – how many times it will retry to connect in case of an errorautoConnect (default true) – should it try to auto connect to the remote side if a request is dispatched and there is no open session alreadyautoDisconnect (default 60000) – how much milliseconds we will wait for another request before the tcp session to the remote side is closed. If the value is 0, it will wait forever (or until the remote side disconnects). Bear in mind autoConnect set to false does not assume autoDisconnect set to 0/false as well.userPromptRegex (default (Username|Login)) – the rule used to identify that the remote side requests for a usernamepassPromptRegex (default Password) – the rule used to identify that the remote side requests for a passwordxmlPromptRegex (default XML>) – the rule used to identify successful login/connectionnoDelay (default true) – disables the Nagle algorithm (true)keepAlive (default 30000) – enabled or disables (value of 0) TCP keepalive for the socketssl (default false) – if it is set to true or an object, then SSL session will be opened. Node.js TLS module is used for that so if the ssl points to an object, the tls options are taken from it. Be careful – enabling SSL does not change the default port from 38751 to 38752. You have to set it explicitly!Example:var cxml = require(‘node-ciscoxml’);var c = cxml( { host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’});connect methodThis method forces explicitly a connection. It could accept any options of the above.Example:var cxml = require(‘node-ciscoxml’);var c = cxml();c.connect( { host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’});The connect method is not necessary to be used. If autoConnect is enabled (default) the module will automatically open and close tcp connections when needed.Connect supports callback. Example:var cxml = require(‘node-ciscoxml’);cxml().connect( { host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’}, function(err) { if (!err) console.log(‘Successful connection’);});The callback may be the only parameter as well. Example:var cxml = require(‘node-ciscoxml’);cxml({ host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’}).connect(function(err) { if (!err) console.log(‘Successful connection’);});Example with SSL:var cxml = require(‘node-ciscoxml’);var fs = require(‘fs’);cxml({ host: ‘10.10.1.1’, port: 38752, username: ‘xmlapi’, password: ‘xmlpass’, ssl: { // These are necessary only if using the client certificate authentication key: fs.readFileSync(‘client-key.pem’), cert: fs.readFileSync(‘client-cert.pem’), // This is necessary only if the server uses the self-signed certificate ca: [ fs.readFileSync(‘server-cert.pem’) ] }}).connect(function(err) { if (!err) console.log(‘Successful connection’);});disconnect methodThis method explicitly disconnects a connection.sendRaw method.sendRaw(data,callback)Parameters:data – a string containing valid Cisco XML request to be sentcallback – function that will be called when a valid Cisco XML response is receivedExample:var cxml = require(‘node-ciscoxml’);var c = cxml({ host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’});c.sendRaw(‘<Request><GetDataSpaceInfo/></Request>’,function(err,data) { console.log(‘Received’,err,data);});sendRawObj method.sendRawObj(data,callback)Parameters:data – a javascript object that will be converted to a Cisco XML requestcallback – function that will be called with valid Cisco XML response converted to javascript objectExample:var cxml = require(‘node-ciscoxml’);var c = cxml({ host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’});c.sendRawObj({ GetDataSpaceInfo: ” },function(err,data) { console.log(‘Received’,err,data);});rootGetDataSpaceInfo method.rootGetDataSpaceInfo(callback)Equivalent to .sendRawObj for GetDataSpaceInfo commandgetNextSends getNext request with a specific id, so we can retrieve the rest of the previous operation if it has been truncated.id – the ID callback – the callback with the data (in js object format)Keep in mind next response may be truncated as well, so you have to check for IteratorID all the time.Example:var cxml = require(‘node-ciscoxml’);var c = cxml({ host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’});c.sendRawObj({ Get: { Configuration: {} } },function(err,data) { console.log(‘Received’,err,data); if ((!err) && data && data.Response.$.IteratorID) { return c.getNext(data.Response.$.IteratorID,function(err,nextData) { // .. code to merge data with nextData }); } // .. code});sendRequest methodThis method is equivalent to sendRawObj but it can automatically detect the need and resupply GetNext requests so the response is absolutley full. Therefore this method should be the preferred method for sending requests that expect very large replies.Example:var cxml = require(‘node-ciscoxml’);var c = cxml({ host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’});c.sendRequest({ GetDataSpaceInfo: ” },function(err,data) { console.log(‘Received’,err,data);});requestPath methodThis is a method equivalent to sendRequest but instead of an object, the request may be formatted in a simple path string. This metod is not very useful for complex requests. But its value is in the ability to simplify very much the simple requests. The response is in JavaScript objectExample:var cxml = require(‘node-ciscoxml’);var c = cxml({ host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’});c.requestPath(‘Get.Configuration.Hostname’,function(err,data) { console.log(‘Received’,err,data);});reqPathPath methodThis is the same method as requestPath, but the response is not an object, but a path array. The method supports optional filter, which has to be a RegExp object and all paths and values will be tested against it Only those returning true will be included in the response array.Example:var cxml = require(‘node-ciscoxml’);var c = cxml({ host: ‘10.10.1.1’, port: 5000, username: ‘xmlapi’, password: ‘xmlpass’});c.reqPathPath(‘Get.Configuration.Hostname’,/Hostname/,function(err,data) { console.log(‘Received’,data[0]); // The output should be something like // [ ‘Response(“MajorVersion”=”1″,”MinorVersion”=”0”).Get.Configuration.Hostname(“MajorVersion”=”1″,”MinorVersion”=”0”)’, ‘asr9k-router’ ] });This method could be very useful for getting simple responses and configurations.getConfig methodThis method requests the whole configuration of the remote device and return it as objectExample:c.getConfig(function(err,config) { console.log(err,config);});cliConfig methodThis method is quite simple, it executes a command(s) in CLI Configuration mode and return the response in JS Object. You have to know that any configuration change in IOS XR is not effective unless it is committed!Example:c.cliConfig(‘username testuserngroup operatorn’,function(err,data) { console.log(err,data); c.commit();});cliExec methodExecutes a command(s) in CLI Exec mode and return the response in JS Object.c.cliExec(‘show interfaces’,function(err,data) { console.log(err,data?data.Response.CLI[0].Exec[0]);});commit methodCommit the current configuration.Example:c.commit(function(err,data) { console.log(err,data);});lock methodLocks the configuration mode.Example:c.lock(function(err,data) { console.log(err,data);});unlock methodUnlocks the configuration mode.Example:c.unlock(function(err,data) { console.log(err,data);});Configure Cisco IOS XR for XML agentTo configure IOS XR for remote XML configuration you have to:Ensure you have *mgbl*** package installed and activated! Without it you will have no xml agentcommands!Enable the XML agent with a similar configuration:xml agent vrf default ipv4 access-list SECUREACCESS ! ipv6 enable session timeout 10 iteration on size 100000!You can enable tty and/or ssl agents as well!(Keep in mind – full filtering of the XML access has to be done by the control-plane management-plane command! The XML interface does not use VTYs!)You have to ensure you have correctly configured aaa as the xml agent uses default method for both authentication and authorization and that cannot be changed (last verified with IOS XR 5.3).You have to have both aaa authentication and authorization. If authorization is not set (aaa authorization default local or none), you may not be able to log in. And you shall ensure that both the authentication and authorization share the same source (tacacs+ or local).The default agent port is 38751 for the default agent and 38752 for SSL.DebuggingThe module uses “debug” module to log its outputs. You can enable the debugging by having in your code something like:require(‘debug’).enable(‘ciscoxml’);Or setting DEBUG environment to ciscoxml before starting the Node.JS