NETCONF with ncclient (Python)

1. NETCONF Architecture — Core Concepts

NETCONF Protocol Stack

  ┌──────────────────────────────────────────────────────┐
  │  Management Application  (Python + ncclient)         │
  ├──────────────────────────────────────────────────────┤
  │  NETCONF Protocol Layer  (RFC 6241)                  │
  │  Operations: get, get-config, edit-config, commit... │
  ├──────────────────────────────────────────────────────┤
  │  XML Encoding + YANG Data Models                     │
  │  (Cisco-IOS-XE-native, OpenConfig, IETF)             │
  ├──────────────────────────────────────────────────────┤
  │  SSH Transport  (TCP port 830)                       │
  └──────────────────────────────────────────────────────┘

  NETCONF Datastores:
  ┌──────────────┬────────────────────────────────────────────┐
  │  running     │ The active configuration (always present)  │
  │  startup     │ Config saved to NVRAM (loaded at boot)     │
  │  candidate   │ Staging area — edit here, then commit      │
  │              │ to running. Requires :candidate capability │
  └──────────────┴────────────────────────────────────────────┘

  IOS-XE supports all three datastores.
  Most operations in this lab use the running datastore directly.
  

NETCONF Operations Reference

YANG Data Model Types on IOS-XE

edit-config Operation Attributes

2. Lab Topology & Environment

  Python Workstation                  NetsTuts_R1 (IOS-XE 17.x)
  192.168.1.100                       Management: 192.168.1.1
       |                              GigabitEthernet1: 192.168.1.1/24
       |   SSH / NETCONF              GigabitEthernet2: 10.0.0.1/24
       └──── TCP 830 ────────────────► GigabitEthernet3: 10.0.1.1/24
                                       Loopback0: 1.1.1.1/32

  Python environment:
    Python 3.10+
    ncclient 0.6.13+
    lxml 4.9+           (XML parsing)
    xmltodict 0.13+     (XML to Python dict conversion)

  IOS-XE Requirements:
    NETCONF enabled (netconf-yang)
    SSH version 2
    Local user with privilege 15
    NETCONF port 830 reachable from workstation
  

3. Step 1 — Enable NETCONF on IOS-XE

NETCONF requires SSH to be configured first. The netconf-yang command enables the NETCONF agent and opens port 830. A dedicated NETCONF user with privilege 15 is required for edit-config write operations.

NetsTuts_R1>en
NetsTuts_R1#conf t

! ── Step 1: Configure hostname and domain (required for SSH keys)
NetsTuts_R1(config)#hostname NetsTuts_R1
NetsTuts_R1(config)#ip domain-name netstuts.lab

! ── Step 2: Generate RSA keys for SSH ─────────────────────
NetsTuts_R1(config)#crypto key generate rsa modulus 2048
% Generating 2048 bit RSA keys, keys will be non-exportable...
[OK] (elapsed time was 4 seconds)

! ── Step 3: Enable SSH version 2 ─────────────────────────
NetsTuts_R1(config)#ip ssh version 2
NetsTuts_R1(config)#ip ssh time-out 60
NetsTuts_R1(config)#ip ssh authentication-retries 3

! ── Step 4: Create NETCONF management user ────────────────
NetsTuts_R1(config)#username netconf privilege 15 secret NetC0nf$ecret

! ── Step 5: Enable local AAA authentication ───────────────
NetsTuts_R1(config)#aaa new-model
NetsTuts_R1(config)#aaa authentication login default local
NetsTuts_R1(config)#aaa authorization exec default local

! ── Step 6: Enable NETCONF-YANG agent ─────────────────────
NetsTuts_R1(config)#netconf-yang

! ── Step 7: Confirm NETCONF is listening on port 830 ──────
NetsTuts_R1(config)#end

NetsTuts_R1#show netconf-yang status

netconf-yang: enabled
netconf-yang candidate-datastore: disabled
netconf-yang side-effect-sync: enabled
netconf-yang SSH port: 830

! ── Step 8: Verify from workstation (optional quick check) ─
! ── (run from Linux/Mac terminal on workstation) ──────────
! nc -zv 192.168.1.1 830
! Connection to 192.168.1.1 830 port [tcp] succeeded!
  

Optional: Enable Candidate Datastore

! ── Enable candidate datastore for staged config workflow ─
NetsTuts_R1(config)#netconf-yang feature candidate-datastore

NetsTuts_R1#show netconf-yang status
netconf-yang: enabled
netconf-yang candidate-datastore: enabled   ← now available
netconf-yang SSH port: 830
  

4. Step 2 — Install ncclient and Connect

Install Python Dependencies

# ── Run on the Python workstation ─────────────────────────
# ── Create and activate a virtual environment (recommended)
python3 -m venv netconf-lab
source netconf-lab/bin/activate          # Linux/Mac
# netconf-lab\Scripts\activate           # Windows

# ── Install required packages ─────────────────────────────
pip install ncclient lxml xmltodict

# ── Verify installation ───────────────────────────────────
python3 -c "import ncclient; print(ncclient.__version__)"
0.6.13
  

Script 1 — Connect and Inspect Device Capabilities

#!/usr/bin/env python3
"""
netconf_01_connect.py
Connect to IOS-XE via NETCONF and display device capabilities.
Capabilities describe which YANG models and NETCONF features
the device supports.
"""

from ncclient import manager
import xml.dom.minidom

# ── Device connection parameters ──────────────────────────
DEVICE = {
    "host":             "192.168.1.1",
    "port":             830,
    "username":         "netconf",
    "password":         "NetC0nf$ecret",
    "hostkey_verify":   False,     # Set True in production with known_hosts
    "device_params":    {"name": "iosxe"},   # Enables IOS-XE specific handling
    "manager_params":   {"timeout": 60},
}

def main():
    print(f"Connecting to {DEVICE['host']}:{DEVICE['port']} via NETCONF...")

    with manager.connect(**DEVICE) as m:
        print(f"\nConnected successfully.")
        print(f"Session ID : {m.session_id}")
        print(f"\n{'='*60}")
        print("DEVICE CAPABILITIES (YANG models supported):")
        print('='*60)

        # ── Print all capabilities advertised by the device ──
        for cap in sorted(m.server_capabilities):
            print(f"  {cap}")

        # ── Check for key capabilities ────────────────────────
        print(f"\n{'='*60}")
        print("KEY CAPABILITY CHECKS:")
        print('='*60)

        checks = {
            ":candidate":    "Candidate datastore",
            ":rollback-on-error": "Auto rollback on error",
            ":validate":     "Config validation",
            ":confirmed-commit": "Confirmed commit (auto-rollback)",
            "Cisco-IOS-XE-native": "Cisco IOS-XE native YANG models",
            "openconfig-interfaces": "OpenConfig interfaces model",
            "ietf-interfaces": "IETF interfaces model",
        }

        for cap_fragment, label in checks.items():
            found = any(cap_fragment in c for c in m.server_capabilities)
            status = "✓ Supported" if found else "✗ Not found"
            print(f"  {label:<40} {status}")

if __name__ == "__main__":
    main()
  

Expected Output

Connecting to 192.168.1.1:830 via NETCONF...

Connected successfully.
Session ID : 47

============================================================
DEVICE CAPABILITIES (YANG models supported):
============================================================
  urn:ietf:params:netconf:base:1.0
  urn:ietf:params:netconf:base:1.1
  urn:ietf:params:netconf:capability:candidate:1.0
  urn:ietf:params:netconf:capability:rollback-on-error:1.0
  urn:ietf:params:netconf:capability:validate:1.1
  urn:ietf:params:netconf:capability:confirmed-commit:1.1
  http://cisco.com/ns/yang/Cisco-IOS-XE-native?module=...
  http://openconfig.net/yang/interfaces?module=...
  urn:ietf:params:xml:ns:yang:ietf-interfaces?module=...
  ... (50+ more capability URIs)

============================================================
KEY CAPABILITY CHECKS:
============================================================
  Candidate datastore                      ✓ Supported
  Auto rollback on error                   ✓ Supported
  Config validation                        ✓ Supported
  Confirmed commit (auto-rollback)         ✓ Supported
  Cisco IOS-XE native YANG models          ✓ Supported
  OpenConfig interfaces model              ✓ Supported
  IETF interfaces model                    ✓ Supported
  

5. Step 3 — Retrieve Configuration with get-config

The get-config operation retrieves configuration data from a datastore. A subtree filter narrows the response to a specific section of the configuration tree, avoiding the overhead of retrieving the entire running configuration for every query.

Script 2 — Retrieve All Interface Configuration

#!/usr/bin/env python3
"""
netconf_02_get_interfaces.py
Retrieve all interface configuration using the Cisco-IOS-XE-native
YANG model with a subtree filter, then parse the XML response.
"""

from ncclient import manager
from lxml import etree
import xmltodict, json

DEVICE = {
    "host": "192.168.1.1", "port": 830,
    "username": "netconf", "password": "NetC0nf$ecret",
    "hostkey_verify": False, "device_params": {"name": "iosxe"},
}

# ── Subtree filter: retrieve only the  section ─
# ── from the Cisco-IOS-XE-native model ───────────────────
INTERFACE_FILTER = """

  
    
  

"""

def main():
    with manager.connect(**DEVICE) as m:

        # ── Send get-config with the subtree filter ────────
        response = m.get_config(source="running", filter=INTERFACE_FILTER)

        # ── response.xml is the raw XML string ────────────
        # ── response.data_ele is the parsed lxml element ──

        # ── Pretty-print the raw XML response ─────────────
        print("=== RAW XML RESPONSE ===")
        pretty_xml = etree.tostring(
            response.data_ele,
            pretty_print=True
        ).decode()
        print(pretty_xml[:3000])      # Truncate for display

        # ── Convert to Python dict for easier processing ──
        print("\n=== PARSED AS PYTHON DICT ===")
        response_dict = xmltodict.parse(response.xml)

        # ── Navigate to the interface list ────────────────
        try:
            native = response_dict["rpc-reply"]["data"]["native"]
            interfaces = native.get("interface", {})

            # ── Print GigabitEthernet interfaces ──────────
            gi_list = interfaces.get("GigabitEthernet", [])
            if isinstance(gi_list, dict):
                gi_list = [gi_list]    # Single interface — wrap in list

            print("\nGigabitEthernet Interfaces:")
            print("-" * 50)
            for gi in gi_list:
                name   = gi.get("name", "unknown")
                desc   = gi.get("description", "(no description)")
                ip_cfg = gi.get("ip", {})
                addr   = ip_cfg.get("address", {})
                pri    = addr.get("primary", {})
                ip     = pri.get("address", "not set")
                mask   = pri.get("mask", "")
                shut   = gi.get("shutdown")
                status = "shutdown" if shut is not None else "no shutdown"
                print(f"  Gi{name}: {ip}/{mask}  [{desc}]  {status}")

        except KeyError as e:
            print(f"Parse error — key not found: {e}")
            print("Full dict structure:")
            print(json.dumps(response_dict, indent=2)[:2000])

if __name__ == "__main__":
    main()
  

Expected Output

=== RAW XML RESPONSE ===
<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
      xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
  <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
    <interface>
      <GigabitEthernet>
        <name>1</name>
        <description>Management Interface</description>
        <ip>
          <address>
            <primary>
              <address>192.168.1.1</address>
              <mask>255.255.255.0</mask>
            </primary>
          </address>
        </ip>
        <negotiation>
          <auto>true</auto>
        </negotiation>
      </GigabitEthernet>
      <GigabitEthernet>
        <name>2</name>
        <ip>...</ip>
      </GigabitEthernet>
      ...

=== PARSED AS PYTHON DICT ===

GigabitEthernet Interfaces:
--------------------------------------------------
  Gi1: 192.168.1.1/255.255.255.0  [Management Interface]  no shutdown
  Gi2: 10.0.0.1/255.255.255.0  [(no description)]  no shutdown
  Gi3: 10.0.1.1/255.255.255.0  [(no description)]  no shutdown
  

Script 3 — Retrieve Specific Interface by Name (Precise Filter)

#!/usr/bin/env python3
"""
netconf_03_get_one_interface.py
Use a precise subtree filter to retrieve only GigabitEthernet2.
Adding a value inside a filter element makes it an exact-match key.
"""

from ncclient import manager
import xmltodict

DEVICE = {
    "host": "192.168.1.1", "port": 830,
    "username": "netconf", "password": "NetC0nf$ecret",
    "hostkey_verify": False, "device_params": {"name": "iosxe"},
}

# ── Filter: match only GigabitEthernet with name = "2" ────
# ── The 2 inside  is a key ──
# ── selector — it returns ONLY that interface ─────────────
SINGLE_INTF_FILTER = """

  
    
      
        2
      
    
  

"""

def main():
    with manager.connect(**DEVICE) as m:
        response = m.get_config(source="running", filter=SINGLE_INTF_FILTER)
        data = xmltodict.parse(response.xml)

        try:
            gi = (data["rpc-reply"]["data"]["native"]
                     ["interface"]["GigabitEthernet"])

            print(f"Interface: GigabitEthernet{gi['name']}")
            print(f"  Description : {gi.get('description', '(none)')}")
            ip_addr = (gi.get("ip", {})
                          .get("address", {})
                          .get("primary", {})
                          .get("address", "not configured"))
            ip_mask = (gi.get("ip", {})
                          .get("address", {})
                          .get("primary", {})
                          .get("mask", ""))
            print(f"  IP Address  : {ip_addr} {ip_mask}")
            print(f"  Shutdown    : {'yes' if gi.get('shutdown') is not None else 'no'}")

        except (KeyError, TypeError) as e:
            print(f"Interface not found or parse error: {e}")

if __name__ == "__main__":
    main()
  

Script 4 — Retrieve Operational State with get (not get-config)

#!/usr/bin/env python3
"""
netconf_04_get_oper.py
Use <get> (not <get-config>) to retrieve OPERATIONAL state data —
interface counters, line protocol status, input/output rates.
Operational data is NOT in the running config datastore.
Uses the IETF interfaces operational YANG model.
"""

from ncclient import manager
from lxml import etree

DEVICE = {
    "host": "192.168.1.1", "port": 830,
    "username": "netconf", "password": "NetC0nf$ecret",
    "hostkey_verify": False, "device_params": {"name": "iosxe"},
}

# ── Filter: operational state of GigabitEthernet interfaces
# ── Uses ietf-interfaces-state (RFC 7223) ─────────────────
OPER_FILTER = """

  
    
      GigabitEthernet2
    
  

"""

def main():
    with manager.connect(**DEVICE) as m:

        # ── Use get() for operational data ────────────────
        # ── (get-config only returns config, not oper state)
        response = m.get(filter=("subtree", OPER_FILTER))

        print("=== OPERATIONAL STATE (IETF model) ===")
        print(etree.tostring(
            response.data_ele,
            pretty_print=True
        ).decode())

if __name__ == "__main__":
    main()
  

6. Step 4 — Push Configuration with edit-config

The edit-config operation modifies the device configuration by sending an XML payload that follows the YANG model structure. The payload specifies the target datastore, the default operation (merge, replace), and the configuration tree to apply.

Script 5 — Configure Interface Description and IP Address

#!/usr/bin/env python3
"""
netconf_05_edit_interface.py
Configure GigabitEthernet2 description and IP address using
the Cisco-IOS-XE-native YANG model with edit-config merge.
"""

from ncclient import manager
from ncclient.operations import RPCError

DEVICE = {
    "host": "192.168.1.1", "port": 830,
    "username": "netconf", "password": "NetC0nf$ecret",
    "hostkey_verify": False, "device_params": {"name": "iosxe"},
}

# ── XML payload: configure GigabitEthernet2 ───────────────
# ── operation="merge" adds/updates without removing other config
# ── The namespace must match the YANG model exactly ────────
INTF_CONFIG = """

  
    
      
        2
        WAN-Link-to-ISP-A
        
          

            
              
10.0.0.1
              255.255.255.0
            
          
        
        
          true
        
      
    
  

"""

def main():
    with manager.connect(**DEVICE) as m:
        print(f"Configuring GigabitEthernet2 on {DEVICE['host']}...")

        try:
            # ── Send edit-config to the running datastore ──
            response = m.edit_config(
                target="running",
                config=INTF_CONFIG
            )

            # ── Check response status ──────────────────────
            if response.ok:
                print("✓ edit-config succeeded — GigabitEthernet2 configured")
            else:
                print(f"✗ edit-config returned errors: {response.errors}")

        except RPCError as e:
            # ── NETCONF server returned an <rpc-error> ──────
            print(f"✗ RPC Error: {e}")
            print(f"  Error type    : {e.type}")
            print(f"  Error tag     : {e.tag}")
            print(f"  Error severity: {e.severity}")
            print(f"  Error message : {e.message}")

        # ── Verify: read back the config we just pushed ───
        print("\nVerifying by reading back GigabitEthernet2...")
        verify_filter = """
        
          
            
              
                2
              
            
          
        
        """
        verify_resp = m.get_config(source="running", filter=verify_filter)
        import xmltodict
        data = xmltodict.parse(verify_resp.xml)
        gi = (data["rpc-reply"]["data"]["native"]
                 ["interface"]["GigabitEthernet"])
        desc = gi.get("description", "(none)")
        addr = (gi.get("ip", {}).get("address", {})
                   .get("primary", {}).get("address", "not set"))
        mask = (gi.get("ip", {}).get("address", {})
                   .get("primary", {}).get("mask", ""))
        print(f"  Description : {desc}")
        print(f"  IP Address  : {addr} {mask}")

if __name__ == "__main__":
    main()
  

Script 6 — Configure a Loopback Interface (Create)

#!/usr/bin/env python3
"""
netconf_06_create_loopback.py
Create Loopback99 with an IP address.
Uses nc:operation="create" — returns an error if it already exists.
Use nc:operation="merge" for idempotent create/update.
"""

from ncclient import manager
from ncclient.operations import RPCError

DEVICE = {
    "host": "192.168.1.1", "port": 830,
    "username": "netconf", "password": "NetC0nf$ecret",
    "hostkey_verify": False, "device_params": {"name": "iosxe"},
}

# ── nc: namespace prefix must be declared for operation attr
LOOPBACK_CREATE = """

  
    
      
        99
        NETCONF-Lab-Loopback
        
          

            
              
99.99.99.99
              255.255.255.255
            
          
        
      
    
  

"""

def main():
    with manager.connect(**DEVICE) as m:
        print("Creating Loopback99...")

        try:
            resp = m.edit_config(target="running", config=LOOPBACK_CREATE)
            if resp.ok:
                print("✓ Loopback99 created: 99.99.99.99/32")
            else:
                print(f"✗ Errors: {resp.errors}")

        except RPCError as e:
            if e.tag == "data-exists":
                print("ℹ Loopback99 already exists — use merge to update")
            else:
                print(f"✗ RPC Error [{e.tag}]: {e.message}")

if __name__ == "__main__":
    main()
  

Script 7 — Delete a Configuration Element

#!/usr/bin/env python3
"""
netconf_07_delete_loopback.py
Delete Loopback99 using nc:operation="remove"
(idempotent — no error if the interface does not exist).
"""

from ncclient import manager
from ncclient.operations import RPCError

DEVICE = {
    "host": "192.168.1.1", "port": 830,
    "username": "netconf", "password": "NetC0nf$ecret",
    "hostkey_verify": False, "device_params": {"name": "iosxe"},
}

# ── operation="remove" is idempotent: no error if not present
# ── operation="delete" raises data-missing error if not present
LOOPBACK_DELETE = """

  
    
      
        99
      
    
  

"""

def main():
    with manager.connect(**DEVICE) as m:
        print("Removing Loopback99...")
        try:
            resp = m.edit_config(target="running", config=LOOPBACK_DELETE)
            if resp.ok:
                print("✓ Loopback99 removed (or did not exist)")
        except RPCError as e:
            print(f"✗ RPC Error [{e.tag}]: {e.message}")

if __name__ == "__main__":
    main()
  

7. Step 5 — Practical YANG Model Payloads

This section provides ready-to-use XML payloads for common configuration tasks, covering both Cisco-IOS-XE-native and OpenConfig models. Each can be used directly as the config argument to m.edit_config().

Configure a Static Route (Cisco-IOS-XE-native)

STATIC_ROUTE = """

  
    
      
        
          0.0.0.0
          0.0.0.0
          
            10.0.0.254
          
        
      
    
  

"""

# ── Usage ──────────────────────────────────────────────────
# with manager.connect(**DEVICE) as m:
#     m.edit_config(target="running", config=STATIC_ROUTE)
  

Configure NTP Server (Cisco-IOS-XE-native)

NTP_CONFIG = """

  
    
      
        
          216.239.35.0
        
      
    
  

"""
  

Configure a VLAN (Cisco-IOS-XE-native)

VLAN_CONFIG = """

  
    
      
        100
        NETCONF-VLAN
      
    
  

"""
  

Configure Interface Using OpenConfig Model

#!/usr/bin/env python3
"""
netconf_08_openconfig_interface.py
Configure interface description using the OpenConfig interfaces
YANG model instead of the Cisco-native model.
OpenConfig payloads work across Cisco, Juniper, and Arista.
"""

from ncclient import manager
from ncclient.operations import RPCError

DEVICE = {
    "host": "192.168.1.1", "port": 830,
    "username": "netconf", "password": "NetC0nf$ecret",
    "hostkey_verify": False, "device_params": {"name": "iosxe"},
}

# ── OpenConfig namespace: http://openconfig.net/yang/interfaces ─
# ── Interface name format for IOS-XE in OpenConfig: ────────────
# ── "GigabitEthernet2" (full name, not just "2") ───────────────
OC_INTF_CONFIG = """

  
    
      GigabitEthernet2
      
        GigabitEthernet2
        WAN-to-ISP-OpenConfig
        true
      
    
  

"""

def main():
    with manager.connect(**DEVICE) as m:
        # ── Verify device supports OpenConfig interfaces ───
        oc_supported = any(
            "openconfig-interfaces" in c
            for c in m.server_capabilities
        )
        if not oc_supported:
            print("✗ OpenConfig interfaces model not supported on this device")
            return

        print("Configuring GigabitEthernet2 via OpenConfig model...")
        try:
            resp = m.edit_config(target="running", config=OC_INTF_CONFIG)
            if resp.ok:
                print("✓ Interface configured via OpenConfig")
        except RPCError as e:
            print(f"✗ RPC Error [{e.tag}]: {e.message}")

if __name__ == "__main__":
    main()
  

Candidate Datastore Workflow — Staged Configuration

#!/usr/bin/env python3
"""
netconf_09_candidate_workflow.py
Best-practice production workflow using the candidate datastore:
1. Lock candidate datastore
2. Push multiple edit-config operations to candidate
3. Validate the candidate
4. Commit atomically to running
5. Unlock
If any step fails, discard changes — running config unchanged.
"""

from ncclient import manager
from ncclient.operations import RPCError

DEVICE = {
    "host": "192.168.1.1", "port": 830,
    "username": "netconf", "password": "NetC0nf$ecret",
    "hostkey_verify": False, "device_params": {"name": "iosxe"},
}

CHANGE_1 = """

  
    
      
        2
        WAN-Primary-Configured-via-NETCONF
      
    
  

"""

CHANGE_2 = """

  
    
      
        0
        Router-ID-Loopback
      
    
  

"""

def main():
    with manager.connect(**DEVICE) as m:

        # ── Verify candidate datastore is supported ────────
        if not any(":candidate" in c for c in m.server_capabilities):
            print("✗ Candidate datastore not supported — use running directly")
            return

        print("Starting candidate datastore workflow...")

        try:
            # ── Step 1: Lock the candidate datastore ──────
            print("  1. Locking candidate datastore...")
            m.lock(target="candidate")

            # ── Step 2: Push changes to candidate ─────────
            print("  2. Pushing change 1 to candidate...")
            resp1 = m.edit_config(target="candidate", config=CHANGE_1)
            if not resp1.ok:
                raise Exception(f"Change 1 failed: {resp1.errors}")

            print("  3. Pushing change 2 to candidate...")
            resp2 = m.edit_config(target="candidate", config=CHANGE_2)
            if not resp2.ok:
                raise Exception(f"Change 2 failed: {resp2.errors}")

            # ── Step 3: Validate before committing ────────
            print("  4. Validating candidate configuration...")
            m.validate(source="candidate")
            print("     ✓ Validation passed")

            # ── Step 4: Commit to running ──────────────────
            print("  5. Committing to running datastore...")
            m.commit()
            print("     ✓ Commit successful — changes are now live")

        except (RPCError, Exception) as e:
            # ── Rollback: discard candidate changes ────────
            print(f"\n✗ Error: {e}")
            print("  Rolling back — discarding candidate changes...")
            try:
                m.discard_changes()
                print("  ✓ Candidate discarded — running config unchanged")
            except RPCError as discard_err:
                print(f"  ✗ Discard failed: {discard_err}")

        finally:
            # ── Always unlock regardless of outcome ────────
            try:
                m.unlock(target="candidate")
                print("  Candidate datastore unlocked")
            except RPCError:
                pass    # May already be unlocked if lock failed

if __name__ == "__main__":
    main()
  

8. Step 6 — Verification and Troubleshooting NETCONF Sessions

Verify NETCONF on IOS-XE

! ── Check NETCONF agent status ───────────────────────────
NetsTuts_R1#show netconf-yang status

netconf-yang: enabled
netconf-yang candidate-datastore: enabled
netconf-yang side-effect-sync: enabled
netconf-yang SSH port: 830

! ── List active NETCONF sessions ─────────────────────────
NetsTuts_R1#show netconf-yang sessions

R: global-lock
S: SID     Username    Transport    Source              Elapsed time
----------------------------------------------------------------------
S: 47      netconf     netconf-ssh  192.168.1.100:52413  00:00:15

! ── Show session details including YANG capabilities ──────
NetsTuts_R1#show netconf-yang sessions detail

session-id: 47
  transport:     netconf-ssh
  username:      netconf
  source-host:   192.168.1.100
  login-time:    2024-10-16T14:22:01+00:00
  in-rpcs:       12
  in-bad-rpcs:   0
  out-rpc-errors:0
  out-notifications: 0

! ── View NETCONF statistics ───────────────────────────────
NetsTuts_R1#show netconf-yang statistics

netconf-yang server statistics:
  in-sessions        : 8
  in-bad-hellos      : 0
  in-rpcs            : 47
  in-bad-rpcs        : 2
  out-rpc-errors     : 2
  out-notifications  : 0
  dropped-sessions   : 0

! ── Check NETCONF debug logs ─────────────────────────────
NetsTuts_R1#show logging | include NETCONF\|netconf\|yang

! ── Enable NETCONF debug (use only in lab — very verbose) ─
! NetsTuts_R1#debug netconf all
! NetsTuts_R1#undebug all
  

NETCONF Troubleshooting Reference

9. Reusable NETCONF Helper Class

The following class wraps the most common NETCONF operations into a reusable, production-ready interface for building larger automation scripts and pipelines.

#!/usr/bin/env python3
"""
netconf_helper.py
Reusable NETCONF helper class for IOS-XE automation.
Wraps ncclient with error handling, logging, and convenience methods.
"""

from ncclient import manager
from ncclient.operations import RPCError
from lxml import etree
import xmltodict
import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)
log = logging.getLogger(__name__)


class NetconfDevice:
    """
    Context-manager wrapper around ncclient.manager for IOS-XE.
    Usage:
        with NetconfDevice("192.168.1.1", "netconf", "pass") as dev:
            data = dev.get_config_subtree(FILTER)
            dev.edit_running(PAYLOAD)
    """

    def __init__(self, host, username, password, port=830,
                 hostkey_verify=False):
        self.host     = host
        self.port     = port
        self.username = username
        self.password = password
        self.hostkey_verify = hostkey_verify
        self._manager = None

    # ── Context manager entry ──────────────────────────────
    def __enter__(self):
        log.info(f"Connecting to {self.host}:{self.port} via NETCONF")
        self._manager = manager.connect(
            host=self.host, port=self.port,
            username=self.username, password=self.password,
            hostkey_verify=self.hostkey_verify,
            device_params={"name": "iosxe"},
            manager_params={"timeout": 60},
        )
        log.info(f"Connected — session ID {self._manager.session_id}")
        return self

    # ── Context manager exit ───────────────────────────────
    def __exit__(self, exc_type, exc_val, exc_tb):
        if self._manager and self._manager.connected:
            self._manager.close_session()
            log.info("NETCONF session closed")
        return False    # Do not suppress exceptions

    # ── get-config with subtree filter ────────────────────
    def get_config_subtree(self, filter_xml: str,
                           source: str = "running") -> dict:
        """
        Retrieve config data using a subtree filter.
        Returns parsed Python dict.
        """
        log.debug(f"get-config from {source}")
        resp = self._manager.get_config(
            source=source, filter=filter_xml
        )
        return xmltodict.parse(resp.xml)

    # ── get with subtree filter (config + oper state) ──────
    def get_oper(self, filter_xml: str) -> dict:
        """Retrieve operational state data using get()."""
        resp = self._manager.get(filter=("subtree", filter_xml))
        return xmltodict.parse(resp.xml)

    # ── edit-config to running ────────────────────────────
    def edit_running(self, config_xml: str) -> bool:
        """
        Push config to running datastore.
        Returns True on success, raises RPCError on failure.
        """
        log.info("Sending edit-config to running datastore")
        try:
            resp = self._manager.edit_config(
                target="running", config=config_xml
            )
            if resp.ok:
                log.info("edit-config succeeded")
                return True
            else:
                log.error(f"edit-config errors: {resp.errors}")
                return False
        except RPCError as e:
            log.error(f"RPCError [{e.tag}]: {e.message}")
            raise

    # ── Candidate datastore workflow ───────────────────────
    def push_candidate(self, *config_payloads: str,
                       validate: bool = True) -> bool:
        """
        Push one or more config payloads via candidate datastore.
        Validates and commits atomically. Discards on any error.
        Returns True on successful commit.
        """
        m = self._manager

        if not any(":candidate" in c for c in m.server_capabilities):
            log.warning("Candidate not supported — falling back to running")
            for payload in config_payloads:
                self.edit_running(payload)
            return True

        log.info("Starting candidate datastore workflow")
        try:
            m.lock(target="candidate")
            log.debug("Candidate locked")

            for i, payload in enumerate(config_payloads, 1):
                log.info(f"  Applying change {i}/{len(config_payloads)}")
                resp = m.edit_config(target="candidate", config=payload)
                if not resp.ok:
                    raise Exception(f"Change {i} failed: {resp.errors}")

            if validate:
                m.validate(source="candidate")
                log.info("Validation passed")

            m.commit()
            log.info("Committed to running successfully")
            return True

        except (RPCError, Exception) as e:
            log.error(f"Workflow failed: {e} — discarding candidate")
            try:
                m.discard_changes()
                log.info("Candidate discarded")
            except RPCError:
                pass
            raise

        finally:
            try:
                m.unlock(target="candidate")
                log.debug("Candidate unlocked")
            except RPCError:
                pass

    # ── Save running to startup ────────────────────────────
    def save_config(self) -> bool:
        """Copy running-config to startup-config (NVRAM)."""
        log.info("Saving running-config to startup-config")
        try:
            self._manager.copy_config(
                source="running", target="startup"
            )
            log.info("Config saved to NVRAM")
            return True
        except RPCError as e:
            log.error(f"Save failed [{e.tag}]: {e.message}")
            return False

    # ── Get server capabilities ────────────────────────────
    def capabilities(self) -> list:
        return list(self._manager.server_capabilities)

    # ── Pretty-print XML ───────────────────────────────────
    @staticmethod
    def pretty(xml_str: str) -> str:
        return etree.tostring(
            etree.fromstring(xml_str.encode()),
            pretty_print=True
        ).decode()


# ── Example usage ──────────────────────────────────────────
if __name__ == "__main__":

    LOOPBACK_PAYLOAD = """
    
      
        
          
            10
            Automation-Test
            
              

                
                  
10.10.10.10
                  255.255.255.255
                
              
            
          
        
      
    
    """

    INTF_FILTER = """
    
      
        10
      
    
    """

    with NetconfDevice("192.168.1.1", "netconf", "NetC0nf$ecret") as dev:

        # ── Push config via candidate workflow ─────────────
        dev.push_candidate(LOOPBACK_PAYLOAD)

        # ── Read back and display ──────────────────────────
        data = dev.get_config_subtree(INTF_FILTER)
        lo = (data.get("rpc-reply", {}).get("data", {})
                  .get("native", {}).get("interface", {})
                  .get("Loopback", {}))
        print(f"Loopback{lo.get('name')}: "
              f"{lo.get('ip',{}).get('address',{}).get('primary',{}).get('address','?')}")

        # ── Save to NVRAM ──────────────────────────────────
        dev.save_config()
  

Key Points & Exam Tips

• NETCONF (RFC 6241) is a structured configuration management protocol that runs over SSH on TCP port 830. It uses XML-encoded payloads and YANG data models to read and write device configuration in a structured, transactional way — replacing fragile CLI text parsing for network automation.
• YANG (RFC 6020/7950) defines the schema (data types, hierarchy, constraints) for configuration and operational data. YANG models tell NETCONF what the XML payload structure must look like. The three main model families on IOS-XE are Cisco-IOS-XE-native (full feature coverage, IOS-specific), OpenConfig (vendor-neutral, portable across Cisco/Juniper/Arista), and IETF (standards-defined, interfaces and routing).
• The four most important NETCONF operations: get-config (retrieve configuration from a datastore), get (retrieve configuration AND operational state), edit-config (modify a datastore), and commit (apply candidate to running). Know the difference between get-config (config only) and get (config + oper state).
• The three datastores are running (active config), startup (NVRAM/boot config), and candidate (staging area). The candidate datastore enables staged, atomic, transactional changes: edit candidate → validate → commit to running → all changes apply or none do. edit-config target="running" changes take effect immediately but are not saved to NVRAM automatically.
• Subtree filters in get-config and get narrow the XML response to only the requested portion of the configuration tree. Adding a value inside a filter element (e.g., <name>2</name>) makes it a key selector that returns only that specific entry. Without filters, get-config(source="running") returns the entire config tree.
• The nc:operation attribute controls how edit-config handles existing data: merge (add/update, default), replace (replace entire subtree), create (only if not exists), delete (must exist, errors if absent), remove (delete if exists, idempotent). Use remove for idempotent deletion in automation scripts.
• The XML namespace (xmlns) in NETCONF payloads must match the YANG model exactly. The most common cause of bad-element RPC errors is a wrong namespace, a misspelled element name, or using Cisco-native path structure with an OpenConfig namespace (or vice versa). Always verify the namespace against the device's capability list.
• Always use a try/except RPCError block around edit-config operations and always place unlock() in a finally block when using locks. An uncaught exception that leaves a candidate lock held will block all subsequent NETCONF sessions until the lock is manually cleared.
• For production automation: use the candidate datastore workflow (lock → edit → validate → commit → unlock), always verify changes by reading them back with get-config, and save to startup with copy_config(source="running", target="startup") after successful commits. Changes to running are lost on reload if not saved.
• On the exam: know NETCONF's port (TCP 830), the three datastores, the key operations (get/get-config/edit-config/commit), the difference between Cisco-native and OpenConfig models, the role of YANG, and the IOS-XE prerequisites (netconf-yang, AAA, SSH v2). Compare NETCONF against RESTCONF (HTTPS/JSON alternative, RFC 8040) and CLI automation (Netmiko/screen-scraping).