Releases: Juniper/py-junos-eznc
Release 1.1.2
Bugs Fixed:
- onbox Device()
Release 1.1.1
Bugs Fixed:
- Device _auth_user overwritten after device open.
- This was breaking SCP
Release 1.1.0
New Features
Enhanced Exception Handling
- Default exception
- Look for ncclient RPCError to process XML (ncclient 0.4.3 exception handling improved)
- Otherwise will raise a generic
- CommitError
- Added information as to why the commit failed
- ConfigLoadError
- New exception – gives information on why loading a config failed.
- RpcTimeoutError
- New exception – displays device, rpc, and timeout value.
Per execution timeout
-
New feature adds the keyword argument dev_timeout with the value of seconds to the RPC on demand function. This will set the timeout for only that operation. (The device timeout is still globally updated automatically before and after execution).
Example
dev.rpc.get_route_information(table='inet.0', dev_timeout=55)
Serialization of Junos facts
-
Custom encoders added for the object in both YAML and JSON. Default encoders set to this custom version by default in the library.
Example
import yaml print yaml.dump(dev.facts['version_info']) build: 6 major: !!python/tuple [14, 2] minor: '1' type: R import json print json.dumps(dev.facts['version_info']) {"major": [14, 2], "type": "R", "build": 6, "minor": "1"}
Composite table key support for missing XPATH
-
Table items are defined by a key, that is either a single element (such as name), or as a list of multiple XPATHs ('FPC 0', 'MIC 0', 'PIC 0'). In 1.0 if one of the XPATH elements was missing, an uncaught exception was thrown.
-
Updated the code to replace missing elements with None.
Example
PicHwTable: rpc: get-chassis-inventory item: .//name[starts-with(.,'PIC')]/parent::* key: - ancestor::*[starts-with(name,'FPC')]/name - ancestor::*[starts-with(name,'MIC')]/name - name view: _pic_hw_view
pic.name: ('FPC 2', 'MIC 0', 'PIC 1') pic.pn: BUILTIN pic.sn: XXXX pic.desc: 10x 1GE(LAN) SFP pic.name: ('FPC 3', None, 'PIC 0') pic.pn: BUILTIN pic.sn: XXXX
Regex support for View boolean values
-
Values in views can be set to a Boolean based on the presence of a field.
-
Regex support was added to allow for easier matching and multiple values. This is done by setting the format to True/False=regex():
Example
no_absorb: { no-absorb: True=regex(no-absorb) } no_refresh: { no-refresh: True=regex(\dx\d) } no_refresh: { no-refresh: 'True=regex(Session ID: 0x0|no-refresh)' }
OS Install force-host
-
Added force_host to support QFX OS Install
Example
SW.install('file', no_copy=True, force_host=True)
Added display_xml_rpc command
-
To support the limiting of cli() a new function display_xml_rpc is introduced. By default it will return the XML element and text format is also supported.
Example
dev.display_xml_rpc('show system login lockout') <Element get-system-login-lockout-information at 0x37b4b48> dev.display_xml_rpc('show system login lockout', format='text') '<get-system-login-lockout-information>\n</get-system-login-lockout-information>\n'
ncclient proxycommand support
-
Updated to be compatible with the enhancements in ncclient 0.4.2 and added optional path variable for sshconfig file (by default ~/.ssh/config is queried).
Example
[rsherman@localhost ~]$ cat .ssh/config Host 192.168.74.31 User juniper ProxyCommand ssh -l juniper 192.168.74.128 nc %h 22 2>/dev/null >>> dev = Device('192.168.74.31') >>> dev.open() Device(192.168.74.31)
Added support for pipe (union) operator in Table keys
-
Added the ability to use an XPATH pipe (union) operator for Table keys. This feature was already supported with View fields.
-
The syntax is ' | ' (space + pipe + space) between the values. The table will automatically append the item value + / to each element specified in the piped key.
-
The most common use case for this is the implicit "or"; there are situations where keys may have a different name between releases or types of configuration (as is the case with LLDP on ELS and non-ELS switches).
-
If there are multiple keys (of fields) listed with pipes that are found in the RPC reply they will be added to the list.
Example
key: lldp-local-interface | lldp-local-port-id lldp.keys() ['me0.0', 'me0.0', 'me0.0', 'me0.0', 'xe-0/1/0.0']
Format optional for configuration strings
-
When passing configuration data in as a string the library will attempt to automatically determine the format.
Example
config_string = "set interfaces ge-0/0/1 unit 10 family inet address 10.10.10.10/24" cu.load(config_string)
Bugs Fixed
JSON Output
-
Views that had compound keys failed to dump.
-
RPC command output failed to dump.
Example
pic = PicHwTable(dev) pic.get() PicHwTable:sprite.englab.juniper.net: 1 items pic.to_json() '{"(\'FPC 2\', \'MIC 0\', \'PIC 0\')": {"pn": "BUILTIN", "sn": "BUILTIN", "name": ["FPC 2", "MIC 0", "PIC 0"], "desc": "4x 10GE(LAN) SFP+"}}' import json json.dumps(dev.rpc.get_system_uptime_information()) '{"system-booted-time": {"time-length": "3w3d 01:44", "date-time": "2014-11-11 13:47:28 PST"}, "uptime-information": {"active-user-count": "\\n1\\n", "load-average-5": "\\n0.03\\n", "load-average-15": "\\n0.03\\n", "up-time": "\\n24 days, 1:44\\n", "load-average-1": "\\n0.00\\n", "date-time": "\\n3:31PM\\n"}, "protocols-started-time": {"time-length": "2d 04:10", "date-time": "2014-12-03 11:21:27 PST"}, "last-configured-time": {"time-length": "2d 00:58", "user": "regress", "date-time": "2014-12-03 14:33:27 PST"}, "current-time": {"date-time": "2014-12-05 15:31:35 PST"}}'
FutureWarning
- Config utility would output a FutureWarning
Release 1.0.2
Bugs fixed:
- XML Templates not properly loading
- Templates without a file extension no longer assumed to be XML
Release 1.0.1
Bugs fixed:
- VMX personality
- to_json for Python 2.6
- tag option in single hierarchy XML
- XML configuration can be loaded as string with format='xml'
New features:
- Reboot At now supported
- Support for IdentityFile from .ssh/config
- Users default keys will now be searched if no key or password is provided.
Release 1.0.0
Junos PyEZ Overview
The Junos PyEZ project is an open-source Apache 2.0 library for the Python programming language. The purpose of this "micro-framework" library is to enable the networking professional community to effectively utilize the Junos OS NETCONF and XML APIs.
The Junos PyEZ library can be used on any number of server environments supporting Python 2.6 and 2.7.
At the time of this writing, Junos PyEZ is not distributed on devices running Junos OS.
For feature documentation and community support, refer to the following URLs:
- Project Page hosted on the Juniper Networks TechWiki:
http://techwiki.juniper.net/Automation_Scripting/Junos_PyEZ - Source code hosted on Github:
https://github.com/Juniper/py-junos-eznc - Support forum hosted using Google Groups:
https://groups.google.com/forum/#!forum/junos-python-ez
Installing Junos PyEZ
Junos PyEZ can be installed directly from the PyPi repository by typing pip install junos-eznc
at the system command line.
The "pip" installation process also installs any related dependent Python modules and libraries. Depending on your specific system, you might need to have the prerequisite build tools installed as well.
For the complete set of installation instructions for various platforms, see the Junos PyEZ project documentation at https://techwiki.juniper.net/Automation_Scripting/Junos_PyEZ/Installation.
Recommended Junos Release
Junos PyEZ can be used with any device running Junos OS, because they all support the NETCONF and Junos XML APIs. To take full advantage of the Junos PyEZ features, we recommend using Junos OS Release 11.4 or later release - see "Known Limitations and Restrictions" section for details. For more information about Junos OS releases, refer to the Juniper Networks technical documentation site at https://www.juniper.net/techpubs/en_US/release-independent/junos/information-products/pathway-pages/junos/product/index.html .
Supported Python Releases
The Junos PyEZ library has been tested with Python versions 2.6 and 2.7.
At the time of this writing PyEZ is not supported in Python 3.x environments. This restriction is due to dependencies on other Python modules, such as ncclient, that do not support Python 3.x.
Known Limitations and Restrictions
General
- Junos PyEZ maintains a "timeout" mechanism for each executed command and response pair. The default timeout is 30 seconds. You can override the default by using the Device.timeout property. If a timeout does occur, a timeout exception is raised.
- Some devices running Junos OS might disconnect the NETCONF session due to inactivity. This behavior has been observed on SRX Series Services Gateways. In such cases, an exception is raised upon execution of the next command. The Junos PyEZ library does not reconnect to the device in these inactivity scenarios. However, you can call Device.open() to reconnect.
- Command execution is synchronous and blocking. The underlying NETCONF transport library is the ncclient module. If your application requires asynchronous or nonblocking execution logic, you should investigate other libraries to wrap around the PyEZ framework such as Twisted or Python Threads.
- The
Device.cli()
method is intended to be used with interactive python, and as a means to facilitate the interactive experience as needed. Please do not use this for "screen-scraping" the CLI output for automation purposes.
Version-Specific Limitations
A couple software version-dependent limitations that must be noted:
- 11.4 - This is the first release where the Junos XML API supports the ability to retrieve the command output in text (CLI) format. Prior to Junos OS Release 11.4, the response output was in XML. If you use the Device.cli() feature, note that this only works with Junos OS Release 11.4 and later releases.
- 11.4 - This is the first release where the Junos XML API supports the ability to load configuration changes using Junos OS set commands.
Restrictions
Primary Routing Engine
For devices with multiple Routing Engines, you can only connect to the primary Routing Engine. If you attempt to connect to the backup Routing Engine, the Device.open() method fails with an exception.
Junos OS Software Upgrade
The primary restriction is on software-install functionality provided by the jnpr.junos.utils.sw module. The software-install process is currently designed to support simple deployment scenarios. The expected use case for this software is deploying new equipment. The following scenarios are supported:
- Standalone devices with a single Routing Engine, for example EX4200 switches
- Standalone devices equipped with dual Routing Engines, for example MX960 routers
- EX Series Virtual Chassis in non-mixed-mode configurations (all devices use the same Junos OS software package)
- Deployment configurations that do not have any form of "in-service" features enabled, such as unified ISSU and NSSU.
The following scenarios are known not to be supported:
- SRX Series chassis clusters
- EX Series Virtual Chassis in mixed-mode configurations (devices use different Junos OS software packages)
- Virtual Chassis Fabric (VCF)
- MX Series Virtual Chassis
- Any deployments with "in-service" configurations enabled (such as unified ISSU or NSSU)
Beta 0.4.0
General bug fixes and minor enhancements per community feedback.
Beta 0.3.1
Various bug fixes
Removed SRX structured resources
Moved examples to dedicated branch
FpcHwTable added
Pkgadd now returns False on error - Handling to be added soon.
Beta 0.2.0
Framework now supports Python 2.6 and 2.7
Documentation support via Sphinx
Timeout for sw.install
add gather_facts option to device.open()
added auto_probe feature to Device
support for stringification of ConnectError expections
Tag to mark prior to decoupling the cfg/srx directory
To mark the repo before we remove the cfg/srx into a separate repository.