Chapter 4: Python Network Automation with ncclient

NETCONF (Network Configuration Protocol, RFC 6241) is an XML-based RPC protocol that communicates over SSH on TCP port 830. It gives automation scripts a vendor-neutral, schema-validated interface to device configuration and operational state. ncclient is the de facto standard Python library for NETCONF client development on the Cisco ENAUTO 300-435 exam.

Installing ncclient

python3 -m venv venv
source venv/bin/activate
pip install ncclient lxml xmltodict

Before connecting, enable NETCONF on IOS XE:

configure terminal
 netconf-yang
 netconf-yang feature candidate-datastore
end

Verify with: show platform software yang-management process — the ncsshd daemon should be listed as running.

Establishing a Connection

from ncclient import manager

device = {
    "host":           "sandbox-iosxe-recomm-1.cisco.com",
    "port":           830,
    "username":       "developer",
    "password":       "C1sco12345",
    "hostkey_verify": False,
    "device_params":  {"name": "iosxe"},
    "allow_agent":    False,
    "look_for_keys":  False,
}

with manager.connect(**device) as m:
    print(f"Connected: {m.connected}")

Checking Server Capabilities

During session setup both sides exchange <hello> messages advertising capability URNs. Always check capabilities before using advanced features:

with manager.connect(**device) as m:
    caps = list(m.server_capabilities)
    has_candidate  = any("candidate:1.0"       in c for c in caps)
    has_validate   = any("validate:1.1"         in c for c in caps)
    has_xpath      = any("xpath:1.0"            in c for c in caps)
    has_conf_cmmt  = any("confirmed-commit:1.1" in c for c in caps)

NETCONF Session Lifecycle

get_config vs. get

get_config(source, filter=None) retrieves configuration from a named datastore ("running", "candidate", or "startup"). get(filter=None) returns both configuration and live operational state — interface counters, routing table entries, runtime statistics.

edit_config

edit_config(target, config) sends an <edit-config> RPC. The config payload must be wrapped in a <config> root element (not <data>). The default_operation parameter controls merge behavior:

Per-element operation attributes: merge, replace, create, delete, remove. Note that delete raises an error if the node does not exist; remove silently succeeds.

Lock / Unlock Pattern

with manager.connect(**device) as m:
    m.lock("candidate")
    try:
        m.edit_config(target="candidate", config=config_payload)
        m.commit()
    finally:
        m.unlock("candidate")   # always release

Committing and Saving to Startup

After commit(), IOS XE updates running config but not startup. To persist across reload, dispatch the vendor-specific save-config RPC:

from ncclient.xml_ import to_ele
save_rpc = to_ele('<save-config xmlns="http://cisco.com/yang/cisco-ia"/>')
m.dispatch(save_rpc)

Requesting the full configuration from a production device can return 50,000+ lines of XML. Filters let the server extract only what you need before sending the reply, saving bandwidth, memory, and device CPU.

ncclient accepts filters as a two-element tuple: ("subtree", xml_string) or ("xpath", expression).

Subtree Filter Component Types

# Content match: return ONLY GigabitEthernet1 and its enabled/ipv4 leaves
interface_filter = """
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface>
    <name>GigabitEthernet1</name>  <!-- content match -->
    <enabled/>                        <!-- selection node -->
    <ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
  </interface>
</interfaces>
"""
reply = m.get_config(source="running", filter=("subtree", interface_filter))

XPath Filtering

XPath offers richer predicate logic but requires the xpath:1.0 capability. Always verify before use:

ns_map = {
    "ios": "http://cisco.com/ns/yang/Cisco-IOS-XE-native",
    "if":  "urn:ietf:params:xml:ns:yang:ietf-interfaces",
}
xpath_expr = "/if:interfaces/if:interface[if:name='GigabitEthernet1']/if:enabled"

with manager.connect(**device) as m:
    if not any("xpath:1.0" in c for c in m.server_capabilities):
        raise RuntimeError("Device does not support XPath filtering")
    reply = m.get_config(source="running", filter=("xpath", (ns_map, xpath_expr)))

Parsing Replies with lxml

ns = {"ios": "http://cisco.com/ns/yang/Cisco-IOS-XE-native"}
hostname = reply.data.find(".//ios:hostname", namespaces=ns).text

# Collect all interface names via xpath()
names = reply.data_ele.xpath("//if:interface/if:name/text()", namespaces=ns)

The Candidate Datastore Workflow

The candidate datastore is a staging area for changes. When enabled on IOS XE, writable-running is automatically disabled — all writes must go through candidate → commit.

Production-grade workflow:

lock(candidate) → edit_config(candidate) → validate(candidate) → commit(confirmed=True) → verify → commit() → save-config → unlock(candidate)

Confirmed Commit

commit(confirmed=True, confirm_timeout=120) applies the change but starts a countdown. If your script cannot send the confirming commit() within 120 seconds — because the change broke connectivity — the device auto-rolls back.

Structured Error Handling

from ncclient.operations import RPCError

try:
    m.commit()
except RPCError as e:
    print(f"Error tag      : {e.tag}")      # 'in-use', 'invalid-value', etc.
    print(f"Error message  : {e.message}")
    print(f"Error info     : {e.info}")     # e.g. lock holder session ID
    m.discard_changes()
finally:
    m.unlock("candidate")