Introduction to ncclient

In this module we will explore the usefulness of ncclient, a Python based library for working with NETCONF. As seen in the previous lab section, Ansible actually uses this library as part of their NETCONF plugin and module. Ncclient has support for various operating systems that support NETCONF.

In referring to the developer's readthedocs page (feel free to click and explore), ncclient easily facilitates the following:

• Supports all operations and capabilities defined in RFC 4741.
• Request pipelining.
• Asynchronous RPC requests.
• Extensible. New transport mappings and capabilities/operations can be easily added.

Sometime prior to ncclient version 0.4.1, network vendors forked the ncclient repository and made contributions for their platforms; this included Cisco. Starting in version 0.4.1, the main ncclient repository integrates these contributions from vendors. The framework does this by using device handlers (shown below). The current version of ncclient is 0.5.3.

• Juniper: device_params={'name':'junos'}
• Cisco CSR: device_params={'name':'csr'}
• Cisco Nexus: device_params={'name':'nexus'}
• Cisco IOS XR: device_params={'name':'iosxr'}
• Cisco IOS XE: device_params={'name':'iosxe'}
• Huawei: device_params={'name':'huawei'}
• Alcatel Lucent: device_params={'name':'alu'}
• H3C: device_params={'name':'h3c'}
• HP Comware: device_params={'name':'hpcomware'}
• Server or anything not in above: device_params={'name':'default'}

About the ncclient Installation

As part of the lab environment, ncclient should already be installed in your container. This was done using pip, the Python package manager, in your Dockerfile when you built your Docker image. In a new environment where the tooling hasn't already been installed, you would install ncclient by performing the following:

NOTE: You do not need to do perform this action as you've actually already done it.

        
        pip install ncclient
        
    

Further, you could specify an == after ncclient to ensure you install a specific version of ncclient if needed. For example, pip install ncclient==0.5.3. This is important for library version controller within your development environment.

ncclient Basics

The most common object you will use and see with ncclient is the Manager class. After instantiating the Manager class, ncclient opens the door to sending and receiving NETCONF XML RPCs to and from devices. Below is a generic example of the Manager class instantiation that you will be using in the next couple sections of the lab. The Manager class contains a number of built-in methods that correlate to NETCONF operations, such as server_capabilities, get, get_config, edit_config, amongst others.

        
        from ncclient import manager
        # Context manager keeping ncclient connection alive for the duration of
        # the context.
        with manager.connect(
            host='a.b.c.d',                 # IP address of device
            port=830,                       # Port to connect to
            username='user',                # SSH Username
            password='pass',                # SSH Password
            hostkey_verify=False            # Allow unknown hostkeys not in local store
            device_params={'name':'iosxe'}  # Device connection parameters
        ) as m:                             # Context manager reference, i.e. instance of connected manager
            # Print out the NETCONF XML capabilities as reported by the device
            print(m.server_capabilities)
        
    

The above server_capabilities method is just one of the simple examples of creating a ncclient manager object and using it to interact with a device. In the next module you will use code similar to this to get device capabilities. Feel free to spend a few minutes browsing the manager class High-Level API reference. to see the set of operations that manager exposes to developers that correlate to NETCONF operations. This list is provided below for your convenience:

Manager Functions

• get_config(source, filter=None)
• edit_config(target, config, default_operation=None, test_option=None, error_option=None)
• copy_config(source, target)
• delete_config(target)
• dispatch(rpc_command, source=None, filter=None)
• lock(target)
• unlock(target)
• locked(target)
• get()
• close_session()
• kill_session(session_id)
• commit(confirmed=False, timeout=None, persist=None)
• discard_changes()
• validate(source)
• async_mode
• timeout
• raise_mode
• client_capabilities
• server_capabilities
• session_id
• connected

You will not use all of these in this lab, but will explore getting and comparing capabilities, getting and verifying configuration, and modifying configuration. After the ncclient lab sections, you will explore using higher-level tooling like the YANG Development Kit (YDK) that doesn't require you to work with raw NETCONF XML RPCs as many of the YANG elements that make up an RPC are handled behind the scenes for us as objects.