Package: ncpeek
ncpeekncpeek(short fornetconf peek) is a netconf client that retrieves data using thencclientlibrary.It parses the rpc-reply into json format by default, removing any namespaces.[^1] Additional data as such asip,deviceandfieldare also included in the output.Here's an example on howncpeekworks, using the following xml filter:<filter><systemxmlns="http://openconfig.net/yang/system"><state><hostname/></state></system></filter>It will yield this result.[{"ip":"sandbox-iosxr-1.cisco.com","device":"sandbox-iosxr-1.cisco.com","field":"generic","data":{"system":{"state":{"hostname":"sandbox-iosxr"}}}}]For more complex data manipulation or logic, you can add a custom parser for your xml filter or xpath. SeeAdding a Parserfor instructions.Use casesI developed originallyncpeekto be used withinTelegrafto gather telemetry data from network devices and print the metrics. This was showcased in ademo presented at Cisco Impact 2023.In this scenario, a CLI client with a simple interface was what I needed.For an upcoming talk I will deliver at Cisco Live Amsterdam 2024, I improved the netconf client and added an API layer. This allows other systems, such as AI, to callncpeekand fetch data from network devices. For this use case, I needed a simple API for the AI to use.StateIt's important to note upfront thatncpeekis a pet project primarily used for demos. So far, testing has been limited to C8000V 17.09.02a and IOSXR 7.3.2 running on the DevNet always-on sandbox.PRs are welcome, but the support provided might be limited due to the nature of the project. If you have specific requirements or need extensive modifications, you might find it more efficient to fork the project.See the fileContributingfor more information.InstallationFor CLI or API you can installncpeekvia pip.See Details on pypi.pipinstallncpeekTo add a custom parser or work directly with the codesee Development.ncpeekwas developed on Python 3.11, consider using a virtual or dedicated environment when use it.UsageThere are two ways to usencpeek; via the command-line interface (CLI) or through the API. Note that filters can be eitherxmlorxpath, but only one type can be used at a time.CLI❯python-mncpeek
usage:__main__.py[-h][-dDEVICE_SETTINGS](-xXML_FILTER|-pXPATH_FILTER)'ncpeek'isanetconfclientdesignedtofetchdatafromvariousdevices.
Theclientcanbeutilizedintwodistinctways,
eitherviaCommandLineInterface(CLI)orApplicationProgrammingInterface(API).
ThedataretrievalcanbefilteredthrougheitherXMLorXPath,
however,onlyonefiltertypecanbeappliedatagiventime.
NotethatinCLImode,onlyfilenamescanbetreatedasarguments.
Sourcecode:https://github.com/jillesca/ncpeek

options:-h,--helpshowthishelpmessageandexit-dDEVICE_SETTINGS,--device-settingsDEVICE_SETTINGSSpecifyJSONfilenamecontainingdevicesettings.Visithttps://github.com/jillesca/ncpeek/tree/main/ncpeek/devicesforexamples.-xXML_FILTER,--xml-filterXML_FILTERSpecifyXMLfilenamecontainingXMLfilter.Visithttps://github.com/jillesca/ncpeek/tree/main/ncpeek/filtersformoredetails.-pXPATH_FILTER,--xpath-filterXPATH_FILTERFormats:<xpath>OR<namespace>:<xpath>Example:'interfaces/interface'OR'http://cisco.com/ns/yang/Cisco-IOS-XE-interfaces-oper:interfaces/interface'Here's an example of how to usencpeekwith a specific device setting and xml filter:python-mncpeek--device-settings=devnet_xe_sandbox.json--xml-filter=Cisco-IOS-XE-memory-oper.xmlOr with a specific device setting and xpath filter:python-mncpeek--device-settings=devnet_xe_sandbox.json--xpath-filter=http://cisco.com/ns/yang/Cisco-IOS-XE-native:/native/hostnamencpeekwill print the data retrieved from the network device to stdout.APIfromncpeek.clientimportNetconfClientdefapi_call()->None:"""Example NetconfClient API"""client=NetconfClient()client.set_devices_settings(xr_device_settings)client.set_xml_filter(xml_filter)try:result=client.fetch()exceptExceptionaserr:result=[{"error":f"{err=}"}]print(result)ncpeekwill return the data as json. Seeapi_example.pyfor the full example.Device SettingsThe device settings should follow a specific structure.CLI:json filename containing the device settings.--device-settings=devnet_xe_sandbox.jsonAPI:json filename, valid json string or a python dictionary with the same structure. Use theset_devices_settingsmethod.defset_devices_settings(self,device_settings:Union[list,str])->None:Therequiredfields are:hostusernamepasswordThe rest of the fields take defaults onnetconf_deviceHere, you can find an example of the device settings.[{"host":"sandbox-iosxe-latest-1.cisco.com","port":830,"username":"admin","password":"C1sco12345","hostkey_verify":"False","timeout":10,"device_params":{"name":"iosxe"}}]You can add multiple devices in a single json array. However, please note that the data is retrieved sequencially.See examples onncpeek/devicesFiltersXMLCLI.filename with the xml filter.--xml-filter=cisco_xe_ietf-interfaces.xmlSee examples onncpeek/filtersAPI.filename or xml string. Use theset_xml_filtermethod.defset_xml_filter(self,xml_filter:str)->None:xpathThe following formats are accepted:<xpath>
<namespace>:<xpath>CLI.xpathstring.Examples:--xpath-filter=interfaces/interface--xpath-filter=http://cisco.com/ns/yang/Cisco-IOS-XE-interfaces-oper:interfaces/interfaceAPI.xpathstring. Use theset_xpath_filtermethod.defset_xpath_filter(self,xpath_filter:str)->None:OperationsCurrently,ncpeekonly uses theGET operationto retrieve data. More operations may be added in future versions.Built-in filters and parsersYou can call directly any of these filters by its name, without specifying their path.Use thedevnet sandboxfor testing.xml filters built-in:cisco_xe_ietf-interfaces.xml(custom parser added)Cisco-IOS-XE-interfaces-oper.xml(custom parser added)Cisco-IOS-XE-memory-oper.xml(custom parser added)Cisco-IOS-XR-facts.xmlCisco-IOS-XR-hostname.xmlxpath parser built-inhttp://cisco.com/ns/yang/Cisco-IOS-XE-isis-oper:/isis-oper-data/isis-instance(custom parser added)DevelopmentTo Install the dependencies needed, use these commands.poetryinstallpeotryshellIf you usevscode, startpoetry shelland then start vscode withcode .In case you don't have poetry, install it withcurl -sSL https://install.python-poetry.org | python3 -If you want to use pip, install the dependencies manually. The only requirement isparamiko <=2.8.1for working with older XR and Junos versions.If you ran into module import problems, add the root project to yourPYHTONPATHexportPYTHONPATH=.Default directoriesDevice Settings default directory isncpeek/devices.XML Filters default directory isncpeek/filters.Adding a ParserTo add a custom parser follow the steps below:Clone this repository.Create a parser underthe parsers directoryYour custom parser must implement theParserclass. See anexisting parser for an exampletheparsefunction must take three arguments and return a list with a dictionary inside.defparse(self,data_to_parse:dict,device:NetconfDevice,netconf_filter_id:str,)->list[dict]:The variabledata_to_parseholds a dictionary withdataas key, and the rpc-reply as the value.{"data":{"@xmlns":"urn:ietf:params:xml:ns:netconf:base:1.0","@xmlns:nc":"urn:ietf:params:xml:ns:netconf:base:1.0","memory-statistics":{"@xmlns":"http://cisco.com/ns/yang/Cisco-IOS-XE-memory-oper","memory-statistic":[{"name":"Processor","total-memory":"2028113884","used-memory":"192040880",},],},}}Review thetests for the parsersto get more familiar.Is recommended to return the following fields beside the data on your parser"field":self.netconf_filter_id,"device":self.device.hostname,"ip":self.device.host,Add your new parser tothe factory mapping.This way,ncpeekknows which parser to use for which filter.Follow the dictionary structure, where the first keys are the name of the filter you are using.If using axmlfile, use the filename as ID, including the.xmlextension.If usingxpath, use the whole xpath expression.On the second level of the dictionary, add the module that has your parser and the class to import.PARSER_MAPPING:Dict[str,Dict[str,str]]={"cisco_xe_ietf-interfaces.xml":{"module":"ncpeek.parsers.cisco_xe_ietf_interfaces","class":"InterfaceStatsIETF_IOSXEParser",},"http://cisco.com/ns/yang/Cisco-IOS-XE-isis-oper:/isis-oper-data/isis-instance":{"module":"ncpeek.parsers.cisco_ios_xe_isis_oper","class":"ISISStatsIOSXEParser",},}FAQWhy I see a deprecation message?Unfortunately, paramiko >=2.9 and IOS-XR 7.3.2 don't go well together, so I had to use an old paramiko <=2.8.1 which has this deprecation message. Seencclient/issues/526for more info.[^1]: Up to a maximum of 10 nested dictionaries. After that, all remaining nested directionaries will be return as they are. Thislimit can be configuredper custom parser.