NETCONF Client for Python

Warnings

• breaking Version 0.7.0 introduced `ssh-python` as an optional SSH transport, which means the `manager.connect` call is NOT 100% backwards compatible with all possible parameters that may have been passed when only `Paramiko` was used. Code relying on specific `Paramiko` nuances might break.
  Fix: Review `manager.connect` parameters and test connectivity thoroughly after upgrading. If encountering issues, ensure parameters are compatible with the chosen transport (`Paramiko` or `ssh-python`).
• breaking Support for Python 2 was officially removed in version 0.6.17. Users on Python 2.x will encounter errors and should upgrade their Python environment.
  Fix: Upgrade Python to 3.7 or newer. The library's `requires_python` is `>=3.7`.
• gotcha By default, `ncclient` uses Paramiko for its SSH transport. As of v0.7.0, an alternative `ssh-python` transport can be used by installing `ncclient[libssh]`. This choice can affect behavior and dependency requirements, as `ssh-python` typically depends on the system's `libssh` library.
  Fix: Decide which SSH transport is preferred. If `ssh-python` is desired, install with `pip install ncclient[libssh]` and ensure `libssh` is installed on the system. Otherwise, `pip install ncclient` will use Paramiko.
• gotcha Using `hostkey_verify=False` in `manager.connect` disables SSH host key checking, which is insecure and not recommended for production environments. This is often seen in examples for simplicity.
  Fix: Implement proper host key verification in production. This usually involves setting `hostkey_verify=True` and managing `known_hosts` files or providing host keys explicitly.
• gotcha The `async_mode` attribute, which was previously a direct attribute of the `Manager` instance for asynchronous RPC requests, had changes in its implementation/usage around version 0.6.0 for compatibility with Python 3.7+.
  Fix: Review asynchronous code, especially if migrating from older versions. Check official documentation or examples for the correct `async_mode` usage with recent Python versions.
• gotcha For vendor-specific NETCONF operations and capabilities, `ncclient` relies on device handlers specified via `device_params={'name': '<vendor_alias>'}`. Failing to set this correctly for a specific device type (e.g., 'junos', 'nexus') might lead to unexpected behavior or missing functionality.
  Fix: Always specify the correct `device_params` name for the target device vendor (e.g., `{'name': 'junos'}` for Juniper, `{'name': 'nexus'}` for Cisco Nexus, `{'name': 'huawei'}` for Huawei). Refer to documentation for a full list of supported handlers.

Install

• pip install ncclient Default installation with Paramiko
• pip install ncclient[libssh] Install with libssh transport (alternative to Paramiko)

Imports

• Manager

  from ncclient import manager

• connect

  from ncclient import manager

  While `connect_ssh` exists, the primary entry point is `manager.connect` which handles SSH by default and offers more flexibility with `device_params`.

Quickstart

This quickstart connects to a NETCONF-enabled device, retrieves its capabilities, and then fetches a filtered portion of the running configuration. It uses environment variables for connection details for security and flexibility. The `hostkey_verify=False` is used here for simplicity, but should be replaced with proper host key verification in production environments.

import os
from ncclient import manager
from ncclient.transport import SSHError

HOST = os.environ.get('NETCONF_HOST', 'your_netconf_device_ip')
PORT = int(os.environ.get('NETCONF_PORT', 830))
USER = os.environ.get('NETCONF_USER', 'admin')
PASSWORD = os.environ.get('NETCONF_PASSWORD', 'password')

def get_device_capabilities():
    try:
        with manager.connect(host=HOST, port=PORT, 
                             username=USER, password=PASSWORD, 
                             hostkey_verify=False, 
                             device_params={'name': 'default'}) as m:
            print(f"Connected to {HOST} (Session ID: {m.session_id})")
            print("\n--- Server Capabilities ---")
            for capability in m.server_capabilities:
                print(f"  - {capability}")
            print("\n--- Get Running Configuration (filtered) ---")
            config_filter = '''
                <filter type="subtree">
                    <system xmlns="urn:ietf:params:xml:ns:yang:ietf-system"/>
                </filter>
            '''
            result = m.get_config(source='running', filter=config_filter).data_xml
            print(result)
            m.close_session()
    except SSHError as e:
        print(f"SSH Connection Error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == '__main__':
    get_device_capabilities()