Automating and Programming Cisco Enterprise Solutions: ENAUTO 300-435 v2.0 Mastery

A comprehensive 20-chapter advanced textbook covering all five domains of the Cisco ENAUTO 300-435 v2.0 exam — YANG models, device-level and controller-based automation, operations, and AI in automation — with hands-on Python code, Ansible playbooks, and real-world enterprise scenarios.

Table of Contents

• Chapter 1: YANG Data Models: OpenConfig, IETF, and Native Models
• Chapter 2: NETCONF, RESTCONF, and Building YANG Payloads
• Chapter 3: Python Network Automation with Netmiko
• Chapter 4: Python Network Automation with ncclient
• Chapter 5: Python Network Automation with RESTCONF
• Chapter 6: Ansible for Device-Level Network Automation
• Chapter 7: Day 0 Provisioning and Zero-Touch Deployment
• Chapter 8: On-Box Automation: EEM, Guest Shell, and Python
• Chapter 9: Cisco Catalyst Center: Architecture and Day 0 Provisioning
• Chapter 10: Catalyst Center: Python API Automation
• Chapter 11: Cisco Meraki Dashboard API Automation
• Chapter 12: Cisco SD-WAN (Catalyst SD-WAN) API Automation
• Chapter 13: Advanced Jinja2 Templating for Network Configuration
• Chapter 14: Controller-Based Ansible Automation
• Chapter 15: Security Automation: Policy Enforcement, Compliance, and Segmentation
• Chapter 16: Troubleshooting Controller-Based Network Automation
• Chapter 17: Testing, Validation, and Network Simulation
• Chapter 18: Software Management and Network Health Monitoring
• Chapter 19: Model-Driven Telemetry and Webhook Monitoring
• Chapter 20: AI in Network Automation and MCP Server Development

Chapter 1: YANG Data Models: OpenConfig, IETF, and Native Models

Learning Objectives

• Differentiate between OpenConfig, IETF, and Cisco native YANG models and explain when to use each
• Navigate and interpret a YANG module tree generated per RFC 8340
• Identify YANG constructs including containers, lists, leaves, leaf-lists, augmentations, and deviations
• Use pyang and YANG Suite to explore and validate YANG modules

Introduction to Data Modeling with YANG

Why Data Models Matter for Network Automation

Imagine two engineers each trying to configure a BGP neighbor on different vendors’ routers. Without a shared vocabulary, one writes a Python script that knows every quirk of Cisco IOS XE CLI syntax, while the other codes a separate script for Juniper JunOS. The two scripts are incompatible, unmaintainable, and brittle — each one breaks the moment the vendor changes a command keyword. Data models solve this problem by establishing a precise, machine-readable contract that says: “here is the structure of network configuration data, independent of how any particular vendor exposes it.”

This is the core promise of model-driven programmability: automation code written against a well-defined data model can be vendor-agnostic, self-documenting, and verifiable before it ever touches a device. For the CCIE Automation exam, understanding how data models are structured — and which model family to use for which job — is foundational to everything from NETCONF payloads to gNMI telemetry subscriptions.

YANG Language Overview and RFC 7950

YANG (Yet Another Next Generation) is the data modeling language used to describe the configuration and operational state of network devices. It was first standardized in RFC 6020 (YANG 1.0, 2010), then significantly revised and extended in RFC 7950 (YANG 1.1, 2016), which is the version in use today [Source: https://www.rfc-editor.org/rfc/rfc7950.txt].

Think of YANG as a schema language — similar in spirit to XML Schema Definition (XSD) or JSON Schema, but purpose-built for networking. Just as XSD defines what elements may appear in an XML document and what types they must hold, a YANG module defines what configuration leaves exist on a device, what types they accept, which are mandatory, and how they relate to one another hierarchically.

YANG is transport-agnostic: the same YANG module can describe data carried over NETCONF (as XML), RESTCONF (as JSON or XML), or gRPC/gNMI (as protocol buffers or JSON). The model defines the structure; the protocol carries the data.

Key properties of YANG as defined in RFC 7950 [Source: https://datatracker.ietf.org/doc/html/rfc7950]:

• Hierarchical: Data is organized as a tree of nodes, mirroring the nested structure of configuration.
• Typed: Every leaf has a type (string, uint32, boolean, enumeration, identityref, etc.).
• Constrained: must expressions (XPath predicates), when conditions, and cardinality constraints (min-elements, max-elements) enforce valid data.
• Extensible: Modules can augment or deviate from other modules without modifying the originals.
• Self-documenting: description statements are part of the language itself, not comments.

YANG Module Structure: module, submodule, revision, namespace

Every YANG model is organized as a module — a single file with a .yang extension that contains a top-level module statement. Larger models can split content into submodules, which belong to a parent module and are included with the include statement.

The essential anatomy of a YANG module:

module ietf-interfaces {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces";
  prefix if;

  import ietf-yang-types {
    prefix yang;
    reference "RFC 6991";
  }

  revision 2018-02-20 {
    description "Updated to RFC 8343.";
    reference "RFC 8343";
  }

  container interfaces {
    list interface {
      key "name";
      leaf name { type string; }
      leaf enabled { type boolean; default "true"; }
    }
  }
}

The namespace is critically important for automation: every schema node is uniquely identified by the combination of its module namespace and its local name. When sending a NETCONF <edit-config> or RESTCONF PATCH, the namespace must appear in the XML prefix or JSON key to tell the device which model family the data belongs to.

Figure 1.1: YANG Module Anatomy — Key Components and Their Relationships

graph TD
    A["YANG Module (.yang file)"]
    A --> B["module declaration\n(top-level name + yang-version)"]
    A --> C["namespace\n(globally unique URI)"]
    A --> D["prefix\n(short alias for references)"]
    A --> E["import / include\n(external modules and submodules)"]
    A --> F["revision\n(dated changelog — newest = version)"]
    A --> G["Data Nodes"]

    G --> H["container\n(groups child nodes; holds no value)"]
    G --> I["list\n(keyed collection of entries)"]
    G --> J["leaf\n(single typed scalar value)"]
    G --> K["leaf-list\n(ordered sequence of scalars)"]

    H --> I
    H --> J
    I --> J

    style A fill:#1a3a5c,color:#fff
    style G fill:#1a3a5c,color:#fff

Key Takeaway: YANG is a hierarchical data modeling language standardized in RFC 7950 that provides a transport-agnostic, typed, and self-documenting schema for network device configuration and state. Every YANG module is identified by a globally unique namespace, which must appear in NETCONF and RESTCONF payloads to route data to the correct model implementation.

OpenConfig YANG Models

OpenConfig Project Goals and Vendor-Neutral Design

OpenConfig is an industry consortium of large network operators — originally including Google, AT&T, British Telecom, Microsoft, and others — who joined forces to produce YANG models that reflect the operator’s perspective rather than any single vendor’s implementation [Source: https://www.openconfig.net/projects/models/]. The fundamental insight driving OpenConfig was that most network operators configure and monitor the same set of protocols across multiple vendors, and they were tired of maintaining separate automation code for each one.

A useful analogy: think of OpenConfig models like metric measurements in science. Celsius and meters are defined once and applied universally — no matter which thermometer or ruler you buy. If every vendor implements openconfig-interfaces, an automation script that configures an interface using OpenConfig works identically on Cisco, Arista, Juniper, or Nokia hardware. The vendor’s job is to implement the model and map it to their internal data structures.

OpenConfig models are developed publicly on GitHub at github.com/openconfig/public [Source: https://github.com/openconfig/public] and evolve faster than IETF RFCs because they follow a collaborative community development process rather than a formal standards body review.

Key design principles of OpenConfig [Source: https://blogs.cisco.com/developer/which-yang-model-to-use]:

• Vendor-neutral by design: No model node mirrors any specific vendor’s CLI keyword or data structure.
• Operator-driven scope: Models cover the features operators need most — BGP, interfaces, routing policy, MPLS, QoS — without trying to expose every protocol knob.
• Telemetry-first: Every OpenConfig model is designed with streaming telemetry in mind, providing operational state paths suitable for gNMI subscriptions alongside configuration paths.
• Consistent structure across all models: All OpenConfig models follow the same overall style guide, making them predictable once you learn the pattern.

OpenConfig Model Hierarchy and Naming Conventions

The defining structural characteristic of OpenConfig models is the config/state container pattern. Instead of mixing configuration leaves and operational state leaves in the same container, OpenConfig places configuration data in a config sub-container and operational state data in a state sub-container at every level of the hierarchy [Source: https://www.openconfig.net/docs/guides/style_guide/].

This means:

• config containers hold nodes that are read-write (rw) — they represent the intended configuration.
• state containers hold nodes that are read-only (ro) — they represent what the device has actually applied or observed, including operational counters and protocol state.

This pattern enables a single model to serve both configuration management (write to config) and telemetry collection (subscribe to state) in a unified schema.

Figure 1.2: OpenConfig config/state Container Pattern Applied to an Interface

graph TD
    ROOT["openconfig-interfaces\ninterfaces"]
    ROOT --> IFACE["interface* [name]\n(list, keyed by name)"]

    IFACE --> CFG["config\n(rw — intended configuration)"]
    IFACE --> STATE["state\n(ro — applied + observed data)"]

    CFG --> C1["name : string"]
    CFG --> C2["type : identityref"]
    CFG --> C3["mtu? : uint16"]
    CFG --> C4["description? : string"]
    CFG --> C5["enabled? : boolean"]

    STATE --> S1["name : string"]
    STATE --> S2["type : identityref"]
    STATE --> S3["mtu? : uint16"]
    STATE --> S4["description? : string"]
    STATE --> S5["enabled? : boolean"]
    STATE --> S6["oper-status : enumeration\n(operational state only)"]
    STATE --> S7["counters\n(in-octets, out-octets, ...)"]

    style CFG fill:#1a5c2a,color:#fff
    style STATE fill:#5c1a1a,color:#fff
    style ROOT fill:#1a3a5c,color:#fff

OpenConfig module names follow the pattern openconfig-<feature> (e.g., openconfig-interfaces, openconfig-bgp, openconfig-routing-policy). Namespace URIs follow http://openconfig.net/yang/<model-name>.

Practical Examples: openconfig-interfaces and openconfig-bgp

openconfig-interfaces defines a model for managing network interfaces across vendors. A simplified tree for an interface entry looks like:

module: openconfig-interfaces
  +--rw interfaces
     +--rw interface* [name]
        +--rw name      -> ../config/name
        +--rw config
        |  +--rw name          string
        |  +--rw type          identityref
        |  +--rw mtu?          uint16
        |  +--rw description?  string
        |  +--rw enabled?      boolean
        +--ro state
           +--ro name          string
           +--ro type          identityref
           +--ro mtu?          uint16
           +--ro description?  string
           +--ro enabled?      boolean
           +--ro oper-status   enumeration
           +--ro counters
              +--ro in-octets?    yang:counter64
              +--ro out-octets?   yang:counter64

Notice that config and state mirror each other’s configurable leaves, but state also adds read-only operational leaves (oper-status, counters) that have no config counterpart.

openconfig-bgp applies the same pattern to BGP configuration. The model organizes BGP data as a global section plus peer-groups and neighbors:

+--rw bgp
   +--rw global
   |  +--rw config
   |  |  +--rw as        inet:as-number
   |  |  +--rw router-id? inet:ipv4-address
   |  +--ro state
   +--rw neighbors
      +--rw neighbor* [neighbor-address]
         +--rw neighbor-address  -> ../config/neighbor-address
         +--rw config
         |  +--rw peer-as        inet:as-number
         |  +--rw description?   string
         +--ro state
            +--ro session-state  enumeration

The operator configures peer-as and description under config; the device reports back the live session-state under state [Source: https://www.openconfig.net/projects/models/].

Augmentations and Deviations for Vendor-Specific Features

No vendor-neutral model can cover every vendor-specific feature. OpenConfig solves this with two mechanisms:

Augmentation: A vendor adds new schema nodes to an existing OpenConfig model without modifying the original. For example, Cisco might augment openconfig-interfaces to add a Cisco-specific input-policy leaf. In NETCONF/RESTCONF payloads, augmented nodes from a different namespace require that namespace’s prefix to disambiguate them from the base model [Source: https://datatracker.ietf.org/doc/html/rfc7950].

Deviation: A vendor declares where their implementation does not fully conform to an OpenConfig model. If Cisco’s IOS XE does not support a particular optional leaf, a deviation module marks it not-supported. This lets automation tools understand the actual capability of a specific device rather than assuming full model compliance [Source: https://www.cbtnuggets.com/blog/technology/networking/native-yang-models-ietf-vs-openconfig-vs-cisco].

Key Takeaway: OpenConfig models are operator-driven, vendor-neutral YANG modules that apply a consistent config/state container pattern to co-locate intended configuration and operational state in every schema. They evolve through community collaboration on GitHub and are the recommended first choice for multi-vendor automation, with vendor-specific gaps addressed through augmentation and deviation.

IETF YANG Models

IETF Standardization Process for YANG Models

IETF YANG models are produced by the IETF NETMOD (Network Modeling) working group and published as RFCs after a formal review process involving technical experts, working group consensus, and IESG approval [Source: https://datatracker.ietf.org/doc/rfc7223/]. This rigor is both a strength and a constraint: IETF models represent broad multi-vendor consensus, but the RFC process is slow by design. Updates to a widely-deployed model like ietf-interfaces can take years.

The IETF’s goal for YANG models is standards-minimal interoperability: every vendor implementing the RFC must support the same baseline schema, ensuring that automation code written against the RFC works identically across all conformant implementations. This makes IETF models ideal as a compliance baseline for auditing and for environments where strict multi-vendor interoperability guarantees are required.

IETF module namespaces follow the pattern urn:ietf:params:xml:ns:yang:ietf-<module-name>.

Key IETF Models: ietf-interfaces, ietf-routing, ietf-access-control-list

ietf-interfaces (RFC 7223, updated by RFC 8343)

The ietf-interfaces model provides a baseline schema for managing network interfaces [Source: https://datatracker.ietf.org/doc/rfc7223/]. It deliberately defines only the common denominator of interface management — name, type, enabled state, and basic statistics. Interface-type-specific or vendor-specific attributes are expected to be added via augmentation. For example, ietf-ip (RFC 7277) augments ietf-interfaces to add IP address configuration.

A minimal interface configuration using ietf-interfaces in NETCONF XML:

<config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
    <interface>
      <name>GigabitEthernet1</name>
      <type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">
        ianaift:ethernetCsmacd
      </type>
      <enabled>true</enabled>
    </interface>
  </interfaces>
</config>

ietf-routing (RFC 8022, updated by RFC 8349)

The ietf-routing model provides three modules forming a core routing data model [Source: https://datatracker.ietf.org/doc/rfc8022/]. The base ietf-routing module defines generic routing instance and RIB concepts, while ietf-ipv4-unicast-routing and ietf-ipv6-unicast-routing augment it with protocol-specific components. Like ietf-interfaces, the base model is intentionally sparse — routing protocol modules (such as ietf-ospf or ietf-bgp) augment it further.

ietf-access-control-list

The ietf-access-control-list model (RFC 8519) defines a schema for ACL configuration — acl-sets, acl-entries, and their matches and actions. It provides a portable model for firewall-style rules that can be augmented with platform-specific match criteria.

Comparing IETF and OpenConfig Model Coverage

The two model families are often complementary rather than competing. An enterprise might use ietf-interfaces as the authoritative baseline for interface compliance checking (because every vendor supports it) while using openconfig-bgp for day-to-day BGP automation (because it provides richer operational state paths for telemetry). The key rule from Cisco: never use both an IETF/OpenConfig model and a Cisco-native model to configure the same parameter on the same device simultaneously, as this creates conflicting state [Source: https://blogs.cisco.com/developer/which-yang-model-to-use].

Figure 1.3: Decision Flowchart — Selecting the Right YANG Model Family

flowchart TD
    START([Start: Identify the automation task]) --> Q1{Is the target\nenvironment\nmulti-vendor?}

    Q1 -->|Yes| Q2{Is strong telemetry\nand gNMI support\nrequired?}
    Q1 -->|No — Cisco IOS XE only| Q3{Is strict RFC\ncompliance / auditing\nthe primary goal?}

    Q2 -->|Yes or No| OC["Use OpenConfig\nopenconfig-interfaces\nopenconfig-bgp\nopenconfig-routing-policy\netc."]

    Q3 -->|Yes| IETF["Use IETF Model\nietf-interfaces\nietf-routing\nietf-access-control-list\netc."]
    Q3 -->|No| Q4{Does OpenConfig or\nIETF cover the\nrequired feature?}

    Q4 -->|Yes| OC
    Q4 -->|No — feature gap| NATIVE["Use Cisco Native Model\nCisco-IOS-XE-native\nCisco-IOS-XE-bgp\nCisco-IOS-XE-qos\netc."]

    OC --> WARN["Do NOT mix OpenConfig/IETF\nand Cisco native for the\nsame configuration parameter"]
    NATIVE --> WARN

    style OC fill:#1a5c2a,color:#fff
    style IETF fill:#1a3a5c,color:#fff
    style NATIVE fill:#5c3a1a,color:#fff
    style WARN fill:#5c1a1a,color:#fff
    style START fill:#2a2a2a,color:#fff

Key Takeaway: IETF YANG models are formally standardized through the RFC process and provide a conservative, broadly interoperable baseline. They are best suited for compliance enforcement across any RFC-conformant vendor, and they are designed to be extended via augmentation. OpenConfig complements IETF models by providing richer, more opinionated schemas with built-in telemetry support and faster evolution.

Cisco Native YANG Models

IOS XE Native Model Structure (Cisco-IOS-XE-native)

When OpenConfig and IETF models don’t provide access to a feature — and Cisco IOS XE has thousands of features those standard models don’t cover — Cisco native YANG models fill the gap. These are proprietary models that map closely to IOS XE’s internal data structures and, by extension, to the IOS XE CLI command hierarchy [Source: https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1715/b_1715_programmability_cg/m_1715_prog_yang_netconf.html].

Think of Cisco native models as the “translation layer” between IOS XE’s CLI configuration space and the YANG data model world. If you can configure something with a CLI command, there is almost certainly a path in the native YANG model that maps to it. This makes native models simultaneously powerful (full feature coverage) and less portable (Cisco-only).

Cisco native models are organized into a family of modules:

The namespace pattern for Cisco native models is http://cisco.com/ns/yang/<module-name>. The -oper suffix marks operational state modules that provide read-only data (similar to the state containers in OpenConfig, but as separate modules rather than co-located containers).

A NETCONF get-config using the Cisco native model looks like:

<filter>
  <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
    <hostname/>
    <ip>
      <domain>
        <name/>
      </domain>
    </ip>
  </native>
</filter>

When to Use Native Models vs OpenConfig/IETF

The decision tree for choosing a model family is straightforward, and Cisco documents it explicitly [Source: https://blogs.cisco.com/developer/which-yang-model-to-use]:

1. Prefer OpenConfig when automating multi-vendor environments or when strong telemetry support is required. Use OpenConfig models as the default starting point.
2. Use IETF models when strict standards compliance and maximum multi-vendor baseline interoperability are required (e.g., compliance auditing tools that must run unchanged across any RFC-conformant device).
3. Fall back to Cisco native models when a required feature is not covered by OpenConfig or IETF models. Platform-specific features like Cisco-specific QoS classification, IOS XE-specific NAT configurations, or proprietary MPLS extensions typically require native models.
4. Never mix OpenConfig and Cisco native to configure the same parameter. If you configure BGP peer-as via openconfig-bgp, do not also configure it via Cisco-IOS-XE-bgp. Mixed configuration causes unpredictable state [Source: https://www.cbtnuggets.com/blog/technology/networking/native-yang-models-ietf-vs-openconfig-vs-cisco].

Exploring Available Models on Cisco IOS XE Devices

All Cisco IOS XE native YANG models are published per release in the GitHub repository at github.com/YangModels/yang under vendor/cisco/xe/<version>/ [Source: https://github.com/YangModels/yang/blob/main/vendor/cisco/xe/1691/README.md]. For example, IOS XE 17.15 models live under vendor/cisco/xe/1715/.

On a live device, available YANG models can be discovered in two ways:

Method 1: NETCONF get-schema (RFC 6022)

The NETCONF get-schema RPC retrieves the YANG source for a specific module directly from the device:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-schema xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
    <identifier>Cisco-IOS-XE-native</identifier>
    <version>2023-07-01</version>
    <format>yang</format>
  </get-schema>
</rpc>

Method 2: Query ietf-yang-library via RESTCONF

The ietf-yang-library model (RFC 7895) provides a machine-readable inventory of all modules a device supports. Via RESTCONF:

GET https://<device>/restconf/data/ietf-yang-library:modules-state

The response lists every module name, revision, namespace, and feature set the device has loaded — effectively the device’s model capability advertisement.

Key Takeaway: Cisco native YANG models provide the deepest and most granular access to IOS XE features, closely mirroring the CLI hierarchy. They are indispensable for Cisco-specific advanced configuration but sacrifice portability. The recommended approach is to prefer OpenConfig and IETF models where possible, and fall back to native models only for features those standard models do not cover — never using both simultaneously for the same configuration parameter.

Interpreting YANG Module Trees (RFC 8340)

Tree Diagram Notation and Symbols

RFC 8340 (published March 2018, designated BCP 215) is the authoritative standard for YANG tree diagram notation [Source: https://datatracker.ietf.org/doc/html/rfc8340]. It defines a text-based format for representing YANG module hierarchies that is compact enough to fit in an RFC or a terminal window, yet expressive enough to convey node types, access permissions, cardinality, and relationships.

The analogy here is a Unix ls -l output: just as ls -l uses a compact column-based format to convey file type, permissions, owner, and size in a single line per file, a YANG tree uses a compact prefix notation to convey access mode, node type, cardinality, and data type in a single line per schema node.

The general structure of a tree line is:

<indent>+--<flags> <status><name><opts> [<keys>]  <type>

Access Flags appear immediately after +--:

Status Indicators prefix the node name when the node is not current:

Cardinality and Node-Type Symbols follow the node name:

Running pyang --tree-help in a terminal displays this full legend — an essential quick-reference during lab or exam work [Source: https://github.com/mbj4668/pyang/wiki/TreeOutput].

Figure 1.4: RFC 8340 YANG Tree Notation — Node Types and Symbol Reference

graph TD
    ROOT["module: example-model\n(tree root)"]

    ROOT --> CONT["+--rw interfaces\ncontainer (rw, no ?, no *)\nGroups children; always present"]
    CONT --> LIST["+--rw interface* [name]\nlist (rw, * = multiple entries)\n[name] = key leaf"]

    LIST --> LEAF_M["+--rw name   string\nleaf — mandatory (no ?)\nMust be present in every entry"]
    LIST --> LEAF_O["+--rw description?   string\nleaf — optional (?)\nMay be omitted"]
    LIST --> LEAF_RO["+--ro oper-status   enumeration\nleaf — read-only (ro)\nDevice writes; operator reads only"]
    LIST --> CHOICE["+--rw (af-choice)\nchoice node — mutually exclusive cases"]

    CHOICE --> CASE1["+--:(ipv4):\ncase — only one case active at a time"]
    CHOICE --> CASE2["+--:(ipv6):\ncase — mutually exclusive with ipv4"]

    LIST --> OPER_CONT["+--ro statistics\ncontainer — read-only subtree\nHolds counters and state data"]

    style ROOT fill:#1a3a5c,color:#fff
    style CONT fill:#1a3a5c,color:#cce
    style LIST fill:#1a3a5c,color:#cce
    style LEAF_RO fill:#5c1a1a,color:#fff
    style OPER_CONT fill:#5c1a1a,color:#fff

Reading Container, List, Leaf, and Choice Nodes

To make the notation concrete, consider the following annotated tree for a simplified ietf-interfaces model:

module: ietf-interfaces
  +--rw interfaces                        <-- container (rw, no ?, no *)
     +--rw interface* [name]              <-- list (rw, *, keyed by [name])
        +--rw name           string       <-- leaf, mandatory (no ?)
        +--rw description?   string       <-- leaf, optional (?)
        +--rw type           identityref  <-- leaf, mandatory
        +--rw enabled?       boolean      <-- leaf, optional
        +--ro oper-status    enumeration  <-- leaf, read-only (ro)
        +--ro statistics                  <-- container, read-only
           +--ro in-octets     yang:counter64
           +--ro out-octets    yang:counter64

Reading this tree line by line:

• interfaces has no * or ?, which means it is a mandatory container — it is always present and holds exactly one set of children.
• interface* [name] — the * means this is a list (multiple instances allowed), and [name] tells you the key leaf. To uniquely address a specific interface entry, you provide its name value.
• name and type have no ?, meaning they are mandatory leaves — any interface entry must include them.
• description? and enabled? carry ?, making them optional.
• oper-status is ro — you cannot write to it. It reflects what the device has observed.
• statistics is a ro container — an entire subtree of read-only counters.

Choice nodes appear when a model offers mutually exclusive alternatives. For example, an address family configuration might offer:

+--rw address-family
   +--rw (af-choice)
      +--:(ipv4):
      |  +--rw ipv4
      +--:(ipv6):
         +--rw ipv6

The (af-choice) is the choice node; :(ipv4): and :(ipv6): are its mutually exclusive cases. Only one case’s children can be present at a time.

Using pyang to Generate Tree Output

pyang is the standard open-source CLI tool for working with YANG modules [Source: https://github.com/mbj4668/pyang]. Install it with:

pip install pyang

The most common workflow is generating a tree diagram to understand a model’s structure before writing automation code:

# Generate a complete tree for a module
pyang -f tree ietf-interfaces.yang

# Focus on a specific subtree path
pyang -f tree --tree-path /interfaces/interface ietf-interfaces.yang

# Limit tree depth (useful for large models)
pyang -f tree --tree-depth 3 Cisco-IOS-XE-native.yang

# Apply a deviation module to show what a specific device supports
pyang -f tree --deviation-module Cisco-IOS-XE-native-devs.yang \
      Cisco-IOS-XE-native.yang

# Generate an interactive HTML tree (useful for exploration)
pyang -f jstree openconfig-interfaces.yang > oc-interfaces.html

# Print groupings expanded in-line
pyang -f tree --tree-print-groupings ietf-interfaces.yang

[Source: https://developer.cisco.com/learning/labs/intro-yang/exploring-yang-models-with-pyang/]

When working with models that import other modules, pyang needs those imported modules on its search path. Use the -p or --path option to specify directories:

pyang -f tree -p /path/to/yang/modules openconfig-bgp.yang

pyang validates the module against RFC 7950 as it processes it, printing errors and warnings before generating output. This dual role — validator and visualizer — makes it the go-to tool for both model development and exam-level exploration [Source: https://github.com/mbj4668/pyang].

Supported output formats include: tree, jstree, yin, uml, sample-xml-skeleton, flatten, identifiers, and more. The sample-xml-skeleton format is particularly useful for generating a template XML document showing all mandatory nodes — a head start for writing NETCONF payloads.

YANG Suite for Visual Model Exploration

Cisco YANG Suite is a free, graphical web application for exploring YANG models and interacting with live Cisco devices over NETCONF, RESTCONF, gRPC, and gNMI [Source: https://developer.cisco.com/yangsuite/]. Where pyang excels at quick terminal-based inspection and scripting, YANG Suite provides a visual interface suited for hands-on learning and constructing RPC payloads interactively.

Deployment is most easily done via Docker [Source: https://github.com/CiscoDevNet/yangsuite]:

git clone https://github.com/CiscoDevNet/yangsuite
cd yangsuite
./start_yang_suite.sh

The script creates credentials, builds a Docker environment file, and runs docker-compose up. YANG Suite is then accessible at https://localhost in a browser.

Alternatively, it can be installed as a Python package:

pip install yangsuite

YANG Suite organizes models into two tiers [Source: https://developer.cisco.com/docs/yangsuite/constructing-and-populating-a-yang-module-repository/]:

1. YANG Repository: A collection of related YANG modules for a specific OS version or device class (e.g., “IOS XE 17.9” or “IOS XR 7.5”). One repository per OS release is the recommended practice.
2. YANG Set (module set): A curated subset of a repository containing only the modules relevant to a specific task and their transitive dependencies. Working with a YANG set rather than a full repository dramatically narrows the scope of the model tree and speeds up exploration [Source: https://developer.cisco.com/docs/yangsuite/defining-a-yang-module-set/].

Workflow in YANG Suite [Source: https://0x2142.com/getting-started-with-cisco-yang-suite/]:

YANG Suite also includes an XPath tester — invaluable when constructing gNMI subscription paths — and a gRPC Dial-Out telemetry collector for testing model-driven streaming telemetry subscriptions [Source: https://www.cisco.com/c/en/us/support/docs/wireless/catalyst-9800-series-wireless-controllers/224944-deploy-yang-suite-and-test-xpath-on.html].

Figure 1.5: YANG Suite Workflow — From Model Repository to Live Device RPC

sequenceDiagram
    actor Engineer
    participant YS as YANG Suite (Web GUI)
    participant Repo as YANG Repository
    participant Device as Cisco IOS XE Device

    Engineer->>YS: Upload YANG files or connect device
    YS->>Device: NETCONF get-schema (RFC 6022)
    Device-->>YS: Return YANG module source files
    YS->>Repo: Store modules in YANG Repository\n(e.g., "IOS XE 17.15")

    Engineer->>YS: Define YANG Set\n(select modules + resolve dependencies)
    YS-->>Engineer: Curated module subset ready

    Engineer->>YS: Explore → YANG\n(browse model tree graphically)
    YS-->>Engineer: Interactive tree: containers, lists, leaves, descriptions

    Engineer->>YS: Protocols → NETCONF\n(select path, fill values, build RPC)
    YS-->>Engineer: Generated RPC payload preview

    Engineer->>YS: Define device profile\n(IP, credentials, port 830)
    Engineer->>YS: Execute RPC
    YS->>Device: NETCONF <edit-config> or <get>
    Device-->>YS: NETCONF <rpc-reply>
    YS-->>Engineer: Display response / diff

The following table compares pyang and YANG Suite to help you choose the right tool for the task:

Key Takeaway: RFC 8340 defines a standardized text notation for YANG tree diagrams, where rw/ro flags indicate read-write vs. read-only access, * marks list nodes, ? marks optional leaves, and bracketed keys identify list keys. pyang generates these trees from the command line and validates models against RFC 7950, while YANG Suite provides a graphical interface for visual exploration, RPC construction, and live device interaction.

Chapter Summary

YANG is the foundational data modeling language for model-driven network automation, defined in RFC 7950 and used by three distinct families of models on Cisco IOS XE. IETF models (such as ietf-interfaces and ietf-routing) prioritize broad multi-vendor interoperability through the formal RFC standards process, but evolve slowly and cover only common-denominator features. OpenConfig models are designed by a consortium of large network operators to reflect real-world automation needs, applying a consistent config/state container pattern and placing strong emphasis on streaming telemetry — they are the recommended default for multi-vendor environments. Cisco native models (such as Cisco-IOS-XE-native and the feature-specific Cisco-IOS-XE-<feature> modules) provide comprehensive coverage of every IOS XE feature at the cost of portability, making them the necessary fallback when standard models fall short.

Reading YANG models efficiently requires mastery of the RFC 8340 tree diagram notation, which uses compact symbols to convey node type (container, list, leaf), access mode (rw/ro), and cardinality (* for lists, ? for optional nodes). The augment statement extends models without modifying originals — Cisco uses it to add IOS XE-specific nodes to IETF and OpenConfig schemas — while the deviation statement documents where a device’s implementation diverges from the specification. Both constructs appear in namespace-qualified form in NETCONF and RESTCONF payloads.

Two tools make YANG exploration practical at the exam and in the field. pyang is the command-line standard for generating tree diagrams, validating model syntax, and applying deviations to understand a device’s actual capability; pyang -f tree <file.yang> and pyang --tree-help are the two most essential commands. Cisco YANG Suite extends this with a graphical web interface that supports visual model browsing, interactive RPC construction, and live device testing over NETCONF, RESTCONF, gRPC, and gNMI — making it the preferred environment for hands-on learning and automation prototyping.

Key Terms

Chapter 2: NETCONF, RESTCONF, and Building YANG Payloads

Learning Objectives

After completing this chapter, you will be able to:

• Describe the NETCONF protocol architecture including its layered model, RPC operations, capabilities exchange, and datastore model
• Describe the RESTCONF protocol and explain how it maps YANG models to RESTful URIs using HTTP methods
• Construct valid JSON payloads from YANG models using YANG Suite and pyang
• Construct valid XML payloads from YANG models using YANG Suite and pyang

Introduction

In Chapter 1 you learned that YANG is the data modeling language that describes the structure and semantics of network device configuration. YANG alone, however, is like a blueprint sitting in a drawer — it only becomes useful when you have a protocol that carries payloads shaped by those blueprints to and from devices.

Think of YANG as the schema of a relational database. NETCONF and RESTCONF are the database drivers — the mechanisms that let your application read and write records according to that schema. NETCONF is the original, full-featured driver: stateful, transactional, and precise. RESTCONF is the lightweight web API driver: stateless, familiar to any developer who has consumed a REST API, and simple enough to drive from a browser’s address bar or a single curl command.

This chapter is the keystone of the ENAUTO 300-435 automation track. Every hands-on automation task — whether written in Python with ncclient, Ansible with cisco.ios.ios_config, or direct HTTPS calls — depends on the concepts here: how sessions are established, how datastores work, how URIs are constructed, and how you translate a YANG tree into a payload the device will accept.

Section 1: NETCONF Protocol Deep Dive

1.1 The Four-Layer NETCONF Architecture

NETCONF (Network Configuration Protocol) is defined by RFC 6241 and is built on a clean four-layer model. Understanding the layers demystifies what happens during every interaction with a NETCONF-capable device.

The separation of concerns is intentional. The transport layer (SSH) provides encryption and authentication without the protocol needing to define its own security mechanisms. The message layer wraps every operation in a consistent <rpc> envelope, giving each message a unique message-id for correlation. The operations layer defines a small, precise set of verbs. The content layer is where YANG lives — the device accepts any valid XML document that conforms to the loaded YANG models.

Figure 2.1: NETCONF Four-Layer Architecture

graph TD
    L4["Layer 4: Content\nYANG-modeled configuration XML\n(What data is exchanged)"]
    L3["Layer 3: Operations\n<get-config>, <edit-config>, <commit>\n(How data is manipulated)"]
    L2["Layer 2: Messages\n<rpc> / <rpc-reply> XML envelopes\nwith message-id correlation\n(How operations are framed)"]
    L1["Layer 1: Transport\nSSH — TCP port 830\nEncryption + Authentication\n(How bytes are delivered)"]

    L4 --> L3
    L3 --> L2
    L2 --> L1

    style L4 fill:#d4edda,stroke:#28a745,color:#000
    style L3 fill:#cce5ff,stroke:#004085,color:#000
    style L2 fill:#fff3cd,stroke:#856404,color:#000
    style L1 fill:#f8d7da,stroke:#721c24,color:#000

1.2 Transport: SSH on Port 830

NETCONF runs exclusively over SSH, connecting to TCP port 830 by default on Cisco IOS XE. This is not the same SSH channel used for CLI management (port 22). The dedicated port signals to both the device and any firewall along the path that this is programmatic management traffic, not interactive terminal traffic.

Message framing in NETCONF depends on the negotiated version:

• NETCONF 1.0 (RFC 4742): Messages are terminated with the end-of-message marker ]]>]]>. The device and client each send their full XML document followed by this marker on a line by itself.
• NETCONF 1.1 (RFC 6242): Uses chunked framing, where each chunk is preceded by \n#<chunk-size>\n and the message ends with \n##\n. Chunked framing is more reliable for large payloads.

Both peers advertise which framing they support during the capabilities exchange, and the highest common version is used.

1.3 Capabilities Exchange: The Hello Handshake

The very first thing that happens after the SSH session is established is that both sides send a <hello> message simultaneously. This message contains a list of URNs advertising every NETCONF feature the sender supports.

A typical Cisco IOS XE <hello> includes capabilities such as:

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:confirmed-commit:1.1
urn:ietf:params:netconf:capability:rollback-on-error:1.0
urn:ietf:params:netconf:capability:validate:1.1

These capabilities tell the client what datastores are available (the candidate:1.0 capability means the device supports a candidate datastore), what safety features are available (confirmed-commit:1.1), and whether the client can validate a proposed configuration before committing it (validate:1.1).

Beyond built-in capabilities, the device also advertises every loaded YANG module by its namespace URI and revision date. This turns capabilities exchange into a machine-readable software bill of materials for the device’s management API. Clients can use the <get-schema> RPC (defined in ietf-netconf-monitoring) to download the actual .yang files directly from the device, ensuring the client always has the correct, device-specific version of each model.

[Source: https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1715/b_1715_programmability_cg/m_1715_prog_yang_netconf.html]

1.4 NETCONF Datastores

A datastore is a conceptual repository of configuration data. RFC 6241 defines three standard datastores, and understanding the difference between them is critical for both the exam and real-world operations.

The candidate datastore is the most important concept for transactional safety. Imagine you need to make 15 interdependent changes to a BGP configuration. With only the running datastore, each <edit-config> is immediately applied — a failure midway through leaves the device in a half-configured, potentially unstable state. With the candidate datastore, all 15 edits are staged, validated as a unit, and then either committed atomically (all or nothing) or discarded if anything is wrong.

On Cisco IOS XE, the candidate datastore must be explicitly enabled:

netconf-yang
netconf-yang feature candidate-datastore

[Source: https://pynet.twb-tech.com/blog/netconf/iosxe-candidate-cfg1.html]

Figure 2.2: NETCONF Datastore Model and Relationships

graph TD
    subgraph Device["Cisco IOS XE Device"]
        STARTUP["<startup> Datastore\nBoot configuration\n(NVRAM equivalent)"]
        RUNNING["<running> Datastore\nActive configuration\n(controls device behavior)"]
        CANDIDATE["<candidate> Datastore\nStaging area for changes\n(requires capability)"]
    end

    CLIENT["Automation Client\n(Python / Ansible / YANG Suite)"]

    CLIENT -- "edit-config" --> CANDIDATE
    CLIENT -- "edit-config (direct)" --> RUNNING
    CANDIDATE -- "commit / confirmed-commit" --> RUNNING
    CANDIDATE -- "discard-changes" --> RUNNING
    RUNNING -- "copy-config" --> STARTUP
    STARTUP -- "loaded at boot" --> RUNNING

    style RUNNING fill:#cce5ff,stroke:#004085,color:#000
    style CANDIDATE fill:#fff3cd,stroke:#856404,color:#000
    style STARTUP fill:#f8d7da,stroke:#721c24,color:#000
    style CLIENT fill:#d4edda,stroke:#28a745,color:#000

1.5 Core NETCONF RPC Operations

Every NETCONF message is an RPC (Remote Procedure Call) wrapped in the standard <rpc> envelope. The following table covers every operation you need to know for the ENAUTO exam.

The <edit-config> operation attribute values deserve special attention because they map directly to RESTCONF HTTP methods later in this chapter:

1.6 Confirmed Commit: Your Safety Net

The confirmed commit capability (advertised as urn:ietf:params:netconf:capability:confirmed-commit:1.1) is one of NETCONF’s most powerful operational safety features and a guaranteed exam topic.

When you issue a <confirmed-commit> with a <confirm-timeout> value, the following sequence occurs:

1. The candidate configuration is committed to running (the change takes effect immediately).
2. A countdown timer starts (default: 600 seconds / 10 minutes).
3. If a confirming <commit> is sent before the timer expires, the change is permanent.
4. If the timer expires without a confirming <commit>, the device automatically rolls back to the configuration that was running before the confirmed commit.

The rollback scenario is the key use case: you push a change that inadvertently breaks the management path. Your SSH/NETCONF session drops. You cannot send a confirming commit. Ten minutes later, the device rolls itself back and you regain access. Without confirmed commit, the change would be permanent and you would need console access to recover.

[Source: https://www.cisco.com/c/en/us/support/docs/storage-networking/management/200933-YANG-NETCONF-Configuration-Validation.html]

Figure 2.3: Confirmed Commit Sequence — Normal Path vs. Rollback Path

sequenceDiagram
    participant Client as Automation Client
    participant Device as Cisco IOS XE Device

    Note over Client,Device: Normal Path (confirming commit received in time)
    Client->>Device: <confirmed-commit> confirm-timeout=600
    Device-->>Client: <rpc-reply> OK
    Note over Device: Change applied to running config
    Note over Device: Countdown timer starts (600s)
    Client->>Device: <commit> (confirming commit)
    Device-->>Client: <rpc-reply> OK
    Note over Device: Change is permanent — timer cancelled

    Note over Client,Device: Rollback Path (session lost, no confirming commit)
    Client->>Device: <confirmed-commit> confirm-timeout=600
    Device-->>Client: <rpc-reply> OK
    Note over Device: Change applied to running config
    Note over Device: Countdown timer starts (600s)
    Note over Client: SSH/NETCONF session drops\n(e.g., change breaks mgmt path)
    Note over Device: Timer expires after 600 seconds
    Note over Device: Automatic rollback to pre-commit config
    Note over Client: Management access restored

1.7 Best Practice: The Candidate Datastore Workflow

The following seven-step workflow represents the gold standard for making changes via NETCONF on a production device. Memorize this sequence — it appears in exam scenarios and is the correct answer whenever the question involves “safe” or “atomic” configuration changes.

Step 1: <lock> <running>        — Prevent other sessions from changing running config
Step 2: <lock> <candidate>      — Prevent other sessions from staging conflicting changes
Step 3: <edit-config> → <candidate>   — Stage your changes (repeat as needed)
Step 4: <validate> <candidate>  — Confirm the staged config is syntactically valid
Step 5: <commit> (or <confirmed-commit>)  — Atomically apply candidate to running
Step 6: <unlock> <candidate>    — Release the candidate lock
Step 7: <unlock> <running>      — Release the running lock

If anything fails between steps 3 and 5, issue <discard-changes> to reset the candidate to match running before unlocking.

1.8 A Complete edit-config Example

The following XML shows a complete NETCONF RPC that configures an IP address on GigabitEthernet1, targeting the candidate datastore using the Cisco IOS XE native YANG model:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <candidate/>
    </target>
    <config>
      <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
        <interface>
          <GigabitEthernet>
            <name>1</name>
            <description>Uplink to Core</description>
            <ip>
              <address>
                <primary>
                  <address>192.168.1.1</address>
                  <mask>255.255.255.0</mask>
                </primary>
              </address>
            </ip>
          </GigabitEthernet>
        </interface>
      </native>
    </config>
  </edit-config>
</rpc>

Key observations about this payload:

• The <rpc> element carries the NETCONF base namespace and a message-id for correlation.
• The <target> specifies <candidate/> — changes are staged, not immediately applied.
• The <native> element carries xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native" — the XML namespace that identifies which YANG module this data belongs to. Without this namespace, the device cannot parse the payload correctly.
• The structure (interface > GigabitEthernet > name, description, ip > address) mirrors the YANG model hierarchy exactly.

[Source: https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1715/b_1715_programmability_cg/m_1715_prog_yang_netconf.html]

Key Takeaway: NETCONF is a stateful, XML-only protocol running over SSH on port 830. Its defining advantage over CLI automation is the candidate datastore: changes are staged, validated, and committed atomically. The confirmed commit feature provides automatic rollback if the management session is lost after a disruptive change. The capabilities exchange hello handshake advertises every supported feature and YANG model before a single configuration operation is sent.

Section 2: RESTCONF Protocol Deep Dive

2.1 What is RESTCONF?

RESTCONF (RFC 8040) is, in the words of the RFC itself, a protocol that “provides a programmatic interface based on standard mechanisms to access data defined in YANG.” The key phrase is “based on standard mechanisms” — RESTCONF takes the YANG data model concepts from NETCONF and exposes them as a conventional HTTP/HTTPS REST API.

If NETCONF is a specialized surgical tool designed for precision and transactional safety, RESTCONF is a Swiss Army knife designed for broad accessibility. Any developer who has ever called a REST API — a Stripe payment endpoint, a GitHub API, a Salesforce connector — can apply those same skills to RESTCONF on a Cisco device.

RESTCONF implements a subset of NETCONF’s capabilities. RFC 8040 is explicit about this: RESTCONF omits datastores, explicit locking, and confirmed commits. What it gains is universal accessibility via HTTPS and native support for JSON encoding.

[Source: https://datatracker.ietf.org/doc/rfc8040/]

2.2 RESTCONF Architecture Overview

RESTCONF maps YANG data to an HTTP resource hierarchy. Each YANG container, list, and leaf becomes an addressable URI. HTTP methods (GET, POST, PUT, PATCH, DELETE) replace NETCONF RPC operations. Content negotiation via Accept and Content-Type headers selects XML or JSON encoding.

The protocol stacks as follows:

+-----------------+
|   YANG Models   |  (Content — same models as NETCONF)
+-----------------+
| HTTP Methods    |  (Operations — GET/POST/PUT/PATCH/DELETE)
+-----------------+
|   HTTP/HTTPS    |  (Messages — standard HTTP request/response)
+-----------------+
|   TLS + TCP     |  (Transport — HTTPS port 443)
+-----------------+

2.3 Enabling RESTCONF on Cisco IOS XE

RESTCONF requires both the NETCONF YANG subsystem and the HTTPS server to be active:

netconf-yang
restconf
ip http secure-server

The netconf-yang command must be configured first because RESTCONF reuses the YANG model infrastructure that NETCONF initializes. Without it, the YANG subsystem is not loaded and RESTCONF has nothing to serve.

2.4 Discovering the API Root

Before constructing any RESTCONF URIs, you need to know the API root path. RFC 8040 specifies that the API root is discoverable via the well-known host metadata URL:

GET https://{device}/.well-known/host-meta

This returns an XML document (or JSON with the appropriate Accept header) containing a link with rel="restconf" pointing to the API root. On Cisco IOS XE, the response points to /restconf, giving a full API root of:

https://{device}/restconf

The data resources live under /restconf/data/. Operations (RPCs/actions) live under /restconf/operations/.

2.5 URI Construction

URI construction is one of the highest-frequency topics on the ENAUTO 300-435 exam. The pattern is:

https://{device}/restconf/data/{module-name}:{top-container}/{child-node}/{list-name}={key-value}

Breaking this down with a concrete example — retrieving the configuration of GigabitEthernet interface number 1 using the Cisco IOS XE native model:

https://192.168.1.1/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=1

Additional URI construction rules to memorize:

• Module boundary prefix: Any time a node comes from a different YANG module than its parent (an augmentation), the augmenting module’s name must prefix that node: openconfig-if-ip:ipv4
• Multiple list keys: Separate with commas: /BGPNeighbor={address},{vrf}
• Encoded characters: Spaces and special characters in key values must be percent-encoded

[Source: https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1717/b_1717_programmability_cg/restconf-protocol.html]

Figure 2.4: RESTCONF URI Structure Anatomy

graph TD
    URI["https://192.168.1.1/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=1"]

    HOST["Host\n192.168.1.1\n(Device IP / hostname)"]
    ROOT["API Root\n/restconf/data/\n(Fixed prefix for all data resources)"]
    MODULE["Module + Container\nCisco-IOS-XE-native:native\n(YANG module name : top-level container)"]
    PATH["Intermediate Path\n/interface\n(Child container within native)"]
    LIST["List + Key\n/GigabitEthernet=1\n(List name = key value)"]

    URI --> HOST
    URI --> ROOT
    URI --> MODULE
    URI --> PATH
    URI --> LIST

    style HOST fill:#f8d7da,stroke:#721c24,color:#000
    style ROOT fill:#d4edda,stroke:#28a745,color:#000
    style MODULE fill:#cce5ff,stroke:#004085,color:#000
    style PATH fill:#fff3cd,stroke:#856404,color:#000
    style LIST fill:#e2d9f3,stroke:#6f42c1,color:#000

2.6 HTTP Methods and Their NETCONF Equivalents

The distinction between POST (create-only) and PUT (create-or-replace) is frequently tested. If you PUT to a URI that already has a resource, it is completely replaced. If you POST to the same URI, you receive a 409 Conflict error.

2.7 Content Negotiation: XML vs. JSON

RESTCONF supports both XML and JSON encoding. The encoding is selected using standard HTTP headers:

Content-Type tells the server the format of the request body. Accept tells the server the preferred format for the response body. Both can be set independently — you can send JSON and request an XML response, though in practice both are usually set to the same format.

JSON is significantly preferred in modern enterprise automation because it is natively parsed by Python, JavaScript, and most automation tooling without needing an XML parser. XML remains important for organizations with existing NETCONF tooling or when working with operators who prefer its explicit namespace model.

2.8 RESTCONF Query Parameters

RESTCONF supports a rich set of URI query parameters that refine what data is returned. These are appended after a ? in the URI:

Example combining parameters:

GET https://192.168.1.1/restconf/data/Cisco-IOS-XE-native:native/interface?content=config&depth=3

[Source: https://algoderedes.com/en/restconf-practical-guide/]

2.9 YANG Patch: Bridging the Transaction Gap

RFC 8072 defines YANG Patch, a special RESTCONF operation that allows multiple named, ordered edit operations in a single PATCH request. A YANG Patch body contains an ietf-yang-patch:yang-patch wrapper with a list of edit objects, each with its own edit-id, operation, target, and optional value.

This partially addresses RESTCONF’s lack of multi-step transactions by allowing, for example, creating an interface, assigning it to a VRF, and configuring its IP address in a single atomic HTTP request. However, YANG Patch still does not provide candidate datastore semantics or confirmed commit rollback.

Key Takeaway: RESTCONF maps YANG data models to REST resources using HTTP methods over HTTPS (port 443). URI construction follows the pattern /restconf/data/{module}:{container}/{path}, with the YANG module name serving as the namespace prefix at module boundaries. RESTCONF is stateless — there is no candidate datastore, no locking, and changes take effect immediately. JSON (RFC 7951) is the preferred encoding format for enterprise automation. YANG Patch (RFC 8072) adds limited multi-step operations in a single request.

Section 3: Constructing JSON Payloads from YANG Models

3.1 Why Payload Construction Matters

Every failed NETCONF or RESTCONF call fails for the same root cause: the payload does not match what the YANG model expects. The device validates every incoming payload against its loaded YANG models. A missing namespace, a misplaced element, an incorrect key value, or a wrong data type produces an <rpc-error> or an HTTP 400 response with no configuration change applied.

The ability to construct correct payloads from scratch — without trial and error — is what separates an automation engineer from someone who copies snippets from Stack Overflow. This section teaches you to read a YANG tree and produce a correct JSON payload methodically.

3.2 JSON Encoding for YANG: RFC 7951

RFC 7951 defines how YANG data is encoded in JSON for use with RESTCONF. The core rules are:

1. Module name as namespace prefix: At every point where data from a YANG module appears at the top of a JSON object, the module name is prefixed to the key with a colon: "Cisco-IOS-XE-native:native". This is required at the top-level container and at any augmentation boundary.

2. Lists become JSON arrays: YANG lists map to JSON arrays. Each list entry is a JSON object. The list key is a regular field within the object.

3. Containers become JSON objects: YANG containers map to JSON objects (key-value maps).

4. Leaf-lists become JSON arrays of primitives: A YANG leaf-list containing strings maps to a JSON array of string values.

5. Empty type leaves: A YANG leaf of type empty is represented as [null] in JSON.

3.3 Mapping the YANG Tree to JSON

The best way to understand the mapping is to trace a specific YANG path. Consider the goal: configure interface GigabitEthernet1 with a description using the Cisco-IOS-XE-native YANG model.

First, use pyang to visualize the relevant section of the tree:

pyang -f tree --tree-path /native/interface/GigabitEthernet Cisco-IOS-XE-native.yang

The tree output would show:

module: Cisco-IOS-XE-native
  +--rw native
     +--rw interface
        +--rw GigabitEthernet* [name]      <-- list, key=name
           +--rw name       string         <-- key leaf
           +--rw description?  string      <-- optional leaf
           +--rw ip
              +--rw address
                 +--rw primary
                    +--rw address  inet:ipv4-address
                    +--rw mask     inet:ipv4-address

Reading the tree symbols:

• +--rw = read-write configuration node
• * [name] = this is a list with key field name
• ? = optional node

Now translate this to JSON for a RESTCONF PATCH request:

{
  "Cisco-IOS-XE-native:GigabitEthernet": [
    {
      "name": "1",
      "description": "Uplink to Core",
      "ip": {
        "address": {
          "primary": {
            "address": "192.168.1.1",
            "mask": "255.255.255.0"
          }
        }
      }
    }
  ]
}

When targeting the list directly in the URI (/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=1), the top-level key in the body uses the module prefix only at the module boundary. For a PATCH to the full interface container, the full body wraps in the module prefix:

{
  "Cisco-IOS-XE-native:native": {
    "interface": {
      "GigabitEthernet": [
        {
          "name": "1",
          "description": "Uplink to Core"
        }
      ]
    }
  }
}

[Source: https://networktocode.com/blog/using-cisco-yang-suite-to-build-restconf-requests/]

3.4 Using pyang to Generate JSON Payloads

pyang is an open-source Python tool (installable via pip install pyang) that validates YANG modules and converts them into multiple output formats. For JSON payload construction, the most useful pyang workflows are:

Step 1: Render the tree to understand the structure

pyang -f tree Cisco-IOS-XE-native.yang 2>/dev/null | head -60

Step 2: Generate an XML skeleton as a starting point

pyang -f sample-xml-skeleton Cisco-IOS-XE-native.yang > skeleton.xml

The sample-xml-skeleton output produces a valid XML document with placeholder values (YOUR_STRING, YOUR_UINT32, etc.) for every leaf. Edit the skeleton to keep only the nodes you need and fill in real values. This XML can then serve as the source for JSON conversion.

Step 3: Convert XML instance to JSON using the jsonxsl plugin

# Generate the XSLT stylesheet from the YANG model
pyang -f jsonxsl -o native.xsl Cisco-IOS-XE-native.yang

# Use the stylesheet to convert your XML instance to JSON
xsltproc native.xsl my_interface_config.xml

The jsonxsl plugin generates an XSLT 1.0 stylesheet from the YANG model. When that stylesheet processes any valid XML instance document for that model, it produces RFC 7951-compliant JSON output.

Step 4: Reverse direction — JSON to XML using the jtox plugin

# Generate the jtox driver file
pyang -f jtox -o native.jtox Cisco-IOS-XE-native.yang

# Convert JSON to XML
python json2xml.py -t native.jtox my_config.json > my_config.xml

The json2xml.py script ships with pyang and performs the reverse conversion. This is useful when you have a JSON payload that needs to be sent via NETCONF (which requires XML).

[Source: https://github.com/mbj4668/pyang/wiki/XmlJson]

3.5 Using Cisco YANG Suite to Generate JSON Payloads

Cisco YANG Suite is the GUI-based approach to payload construction and is faster for exploration and one-off payload generation. It is available as a Docker container:

docker run -it --name yangsuite -p 8480:8480 \
  -v ~/yang-suite-data:/root/yang-suite \
  xscvrs/yangsuite:latest

Access the UI at http://localhost:8480.

Workflow for generating a JSON RESTCONF payload:

1. Create a YANG Set: In the YANG Suite UI, create a named YANG Set and upload or point to the YANG modules for your device (Cisco IOS XE, OpenConfig, IETF standard modules). YANG Suite resolves all module dependencies automatically.

2. Navigate the YANG Tree: Select the YANG module (Cisco-IOS-XE-native) and the YANG Set. YANG Suite renders a visual tree with checkboxes next to every node.

3. Select nodes and enter values: Check the nodes you want to include in your payload (e.g., native > interface > GigabitEthernet > name, description). Enter the specific values (e.g., name=1, description=Uplink to Core).

4. Select RESTCONF and JSON encoding: In the RESTCONF plugin, choose the HTTP method (PUT, PATCH, POST) and select JSON as the encoding.

5. Review the generated payload: YANG Suite shows the constructed URI and the JSON body. Both include the correct module namespace prefix and properly structured arrays/objects.

6. Execute or export: Click “Run RPC” to send the request directly to a configured device, or copy the generated payload for use in your Python script, Ansible playbook, or Postman collection.

[Source: https://developer.cisco.com/docs/yangsuite/restconf-in-yang-suite/]

3.6 Validating JSON Payloads with yanglint

yanglint (from the libyang library) can validate a JSON instance document against a YANG model before sending it to a device:

yanglint --format json Cisco-IOS-XE-native.yang my_payload.json

If the JSON is valid against the model, yanglint exits silently. If there are errors (missing required fields, wrong data types, invalid enum values), it reports them precisely, saving you the round-trip to the device.

Key Takeaway: JSON payloads for RESTCONF follow RFC 7951 encoding rules: YANG lists become JSON arrays, containers become JSON objects, and module names serve as namespace prefixes at module boundaries (module-name:container-name). Use pyang with -f tree to visualize the YANG structure, -f sample-xml-skeleton to generate a starting template, and the jsonxsl plugin to convert XML instances to JSON. Cisco YANG Suite provides a GUI workflow that constructs URIs and JSON payloads interactively and can export to Python or Ansible code.

Section 4: Constructing XML Payloads from YANG Models

4.1 XML’s Role in NETCONF Payloads

XML is the exclusive data format for NETCONF. Every <rpc> message, every <config> block, every filter is XML. Unlike JSON — which is essentially schema-less in its native form — XML carries explicit namespace information that the device uses to route data to the correct YANG model parser. Getting the namespace wrong is the most common cause of NETCONF payload failures.

4.2 XML Namespace Rules

Every top-level container element in a NETCONF <config> block must carry an xmlns attribute declaring the XML namespace of the YANG module it belongs to. The namespace URI is defined by the namespace statement at the top of the YANG module file.

Finding the correct namespace using pyang:

pyang -f tree Cisco-IOS-XE-native.yang 2>/dev/null | head -3

Output:

module: Cisco-IOS-XE-native
  namespace: "http://cisco.com/ns/yang/Cisco-IOS-XE-native"

This namespace URI (http://cisco.com/ns/yang/Cisco-IOS-XE-native) must appear as the xmlns attribute on the <native> element in every NETCONF payload that uses this model.

Common namespace URIs for models you will encounter on the exam:

When a payload spans multiple YANG modules (for example, the interface container is from the native model but IP address details are augmented by a separate module), each element at a module boundary must carry its own xmlns declaration.

4.3 Translating the YANG Tree to XML

Using the same GigabitEthernet1 example, the YANG tree path is:

native (Cisco-IOS-XE-native) > interface > GigabitEthernet[name=1] > ip > address > primary

The XML payload for a full <edit-config> targeting candidate:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <candidate/>
    </target>
    <config>
      <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
        <interface>
          <GigabitEthernet>
            <name>1</name>
            <description>Uplink to Core</description>
            <ip>
              <address>
                <primary>
                  <address>192.168.1.1</address>
                  <mask>255.255.255.0</mask>
                </primary>
              </address>
            </ip>
          </GigabitEthernet>
        </interface>
      </native>
    </config>
  </edit-config>
</rpc>

Notice that the namespace declaration appears once on the <native> element and is inherited by all child elements. Child elements within the same module do not need to repeat the namespace.

To delete the interface description, add the nc:operation="delete" attribute to the target element:

<description nc:operation="delete"
  xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"/>

[Source: https://www.cisco.com/c/en/us/support/docs/storage-networking/management/200933-YANG-NETCONF-Configuration-Validation.html]

4.4 Using pyang to Generate XML Skeletons

pyang’s sample-xml-skeleton output format is the fastest way to generate a starting XML template:

pyang -f sample-xml-skeleton \
  --sample-xml-skeleton-path /native/interface/GigabitEthernet \
  Cisco-IOS-XE-native.yang > interface_skeleton.xml

The --sample-xml-skeleton-path option (available in newer pyang versions) limits the skeleton output to a specific subtree, preventing the generation of a massive file containing the entire module. The output will contain placeholder values (YOUR_STRING) for each leaf that you replace with actual configuration data.

For a full module skeleton without path restriction:

pyang -f sample-xml-skeleton Cisco-IOS-XE-native.yang > full_skeleton.xml

Then edit the skeleton, removing elements you do not need, and fill in the actual values.

[Source: https://github.com/mbj4668/pyang]

4.5 Using YANG Suite to Generate XML NETCONF Payloads

YANG Suite’s NETCONF plugin provides a point-and-click workflow for building XML payloads:

Workflow for generating an XML NETCONF edit-config payload:

1. Open the NETCONF plugin in YANG Suite and select your YANG Set.

2. Select the RPC type: Choose edit-config from the operation dropdown.

3. Select the target datastore: Choose candidate to stage changes safely.

4. Navigate the YANG tree and check nodes: Check native > interface > GigabitEthernet. A form appears with input fields for name, description, and nested IP address fields.

5. Fill in values and set the operation: For each container or leaf, you can set the nc:operation attribute (merge, replace, create, delete, remove) via a dropdown.

6. Preview the generated XML: YANG Suite renders the complete <rpc> XML in a preview pane, including all namespace declarations, properly nested elements, and operation attributes.

7. Execute or export: Click “Run RPC” to send directly to the device (requires a device profile with credentials configured in YANG Suite), or click “Generate Code” to export as a Python script using the ncclient library, or as an Ansible YAML playbook using the ansible.netcommon.netconf_config module.

The exported Python (ncclient) code looks like:

from ncclient import manager

with manager.connect(
    host="192.168.1.1",
    port=830,
    username="admin",
    password="cisco123",
    hostkey_verify=False
) as m:
    config = """
    <config>
      <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
        <interface>
          <GigabitEthernet>
            <name>1</name>
            <description>Uplink to Core</description>
          </GigabitEthernet>
        </interface>
      </native>
    </config>
    """
    m.edit_config(target="candidate", config=config)
    m.commit()

[Source: https://developer.cisco.com/yangsuite/]

4.6 XPath and Subtree Filters for get-config

When retrieving configuration data with <get-config>, you rarely want the entire running configuration. NETCONF supports two filtering mechanisms to narrow the response:

Subtree filter: Uses XML element matching. Only nodes that match the filter structure are returned. An empty element acts as a selector (return everything under this container). A leaf with a value acts as a value match (return only if this leaf equals this value).

<rpc message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-config>
    <source><running/></source>
    <filter type="subtree">
      <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
        <interface>
          <GigabitEthernet>
            <name>1</name>
          </GigabitEthernet>
        </interface>
      </native>
    </filter>
  </get-config>
</rpc>

XPath filter: Uses an XPath expression string. More powerful than subtree filters but requires XPath capability to be advertised by the device.

<filter type="xpath"
  select="/native/interface/GigabitEthernet[name='1']"
  xmlns:ios="http://cisco.com/ns/yang/Cisco-IOS-XE-native"/>

Key Takeaway: XML payloads for NETCONF require correct namespace declarations (xmlns) on every top-level YANG module container — this is the most common source of payload errors. Use pyang’s -f sample-xml-skeleton to generate a starting template and edit it to retain only the nodes you need. YANG Suite’s NETCONF plugin provides a visual point-and-click interface that generates properly namespaced XML and can export complete Python (ncclient) or Ansible code. Subtree and XPath filters narrow <get-config> responses to the specific data you need.

Section 5: Comparing NETCONF and RESTCONF

5.1 Protocol Architecture Side-by-Side

The following table is the single most important reference for exam questions that ask you to select the appropriate protocol for a given scenario:

Figure 2.5: Protocol Selection Decision Tree — NETCONF vs. RESTCONF

flowchart TD
    START([New automation task])

    Q1{Does the task involve\nmulti-step config changes?}
    Q2{Is automatic rollback\nrequired if session drops?}
    Q3{Does it require\ncandidate staging / locking?}
    Q4{Is the team HTTP-native\nor using REST tooling?}
    Q5{Is it a read-only\nor lightweight update?}

    NETCONF(["Use NETCONF\n(RFC 6241 / SSH port 830)\nCandidate datastore + confirmed commit\nncclient / Ansible netconf_config"])
    RESTCONF(["Use RESTCONF\n(RFC 8040 / HTTPS port 443)\nStateless HTTP, JSON preferred\nrequests / curl / Ansible uri"])
    EITHER(["Either protocol\n(RESTCONF simpler for\nsingle-resource ops)"])

    START --> Q1
    Q1 -- Yes --> Q2
    Q1 -- No --> Q4
    Q2 -- Yes --> NETCONF
    Q2 -- No --> Q3
    Q3 -- Yes --> NETCONF
    Q3 -- No --> Q4
    Q4 -- Yes --> RESTCONF
    Q4 -- No --> Q5
    Q5 -- Yes --> RESTCONF
    Q5 -- No --> EITHER

    style NETCONF fill:#cce5ff,stroke:#004085,color:#000
    style RESTCONF fill:#d4edda,stroke:#28a745,color:#000
    style EITHER fill:#fff3cd,stroke:#856404,color:#000

5.2 The Transactional Safety Divide

This is the most consequential practical difference and deserves a direct analogy.

Imagine you are moving funds between bank accounts. NETCONF with the candidate datastore is like a database transaction: you stage the debit and credit, verify both are correct, and then commit — or roll back if anything is wrong. The accounts never show an intermediate state where money has left one account but not arrived in another.

RESTCONF is like sending two separate wire transfers with no coordination. The first transfer (debit) succeeds immediately. If the second transfer (credit) fails, the money is gone. There is no rollback.

This is why NETCONF is mandatory for:

• Multi-step changes where intermediate states would cause outages
• Service provider environments where configuration errors affect customers
• Any scenario where automatic rollback (confirmed commit) is required

And why RESTCONF is preferred for:

• Read operations (GET) — reading config or state data with no transactional risk
• Simple single-resource updates where immediate apply is acceptable
• CI/CD pipelines where HTTP-native tooling is standard
• Dashboard integrations and monitoring systems

5.3 Operations Equivalence Mapping

5.4 When to Choose Each Protocol

[Source: https://networkjourney.com/netconf-vs-restconf-choosing-the-right-protocol-for-network-automation-ccnp-enterprise/]

5.5 Coexistence and Complementary Use

NETCONF and RESTCONF are not mutually exclusive. In production automation platforms, both protocols are commonly used simultaneously:

• NETCONF handles large-scale configuration deployments, provisioning workflows, and any operation requiring rollback safety
• RESTCONF handles real-time reads, operational data polling, and lightweight configuration updates from web-based interfaces

NSO (Cisco Network Services Orchestrator) exposes both protocols to northbound systems simultaneously and uses NETCONF southbound to devices. Ansible’s cisco.ios collection uses NETCONF for configuration and can use RESTCONF for data retrieval. Both protocols reading from the same YANG models ensures consistency — a GET via RESTCONF returns the same data model structure as a <get-config> via NETCONF.

5.6 Performance Considerations

XML verbosity is often cited as a concern with NETCONF. A simple BGP neighbor configuration in XML is several times larger in bytes than the equivalent CLI command. In practice, SSH compression is typically enabled in NETCONF sessions, significantly reducing the overhead. For very large configurations (tens of thousands of BGP prefixes), binary encoding alternatives like gNMI/gRPC (Chapter 3) offer superior throughput.

RESTCONF with JSON encoding is more compact than XML. However, JSON parsing carries its own computational cost, and HTTPS connection establishment (TLS handshake) adds latency for every stateless request compared to NETCONF’s persistent SSH session.

For high-frequency polling of operational data (streaming telemetry use cases), neither NETCONF nor RESTCONF is the right tool — that is the domain of model-driven streaming telemetry covered in Chapter 4.

[Source: https://blog.ipspace.net/kb/CiscoAutomation/070-netconf/]

Key Takeaway: NETCONF and RESTCONF implement the same YANG data model but serve different operational needs. NETCONF provides transactional safety via the candidate datastore, confirmed commit rollback, and session locking — essential for mission-critical bulk configuration. RESTCONF provides universal accessibility via HTTPS and JSON — ideal for HTTP-native tooling, monitoring, and simple updates. Both protocols are enabled simultaneously on Cisco IOS XE, and both are required knowledge for the ENAUTO 300-435 exam. The most exam-tested distinction is that RESTCONF has no candidate datastore, no locking, and no confirmed commit.

Chapter Summary

This chapter built a complete understanding of the two primary programmatic management protocols used in Cisco network automation.

NETCONF (RFC 6241) operates over SSH on port 830, uses XML exclusively, and provides a stateful, session-based management model. Its four layers — Content (YANG), Operations (RPCs), Messages (RPC envelopes), and Transport (SSH) — cleanly separate concerns. The candidate datastore enables atomic, transactional configuration changes: stage changes in candidate, validate, commit, or discard. The confirmed commit feature provides automatic rollback if the management session is lost after applying a potentially disruptive change. The best-practice workflow — lock running, lock candidate, edit-config, validate, commit, unlock — is the canonical safe-change procedure for production NETCONF automation.

RESTCONF (RFC 8040) maps the same YANG models to a REST API over HTTPS. URIs follow the pattern /restconf/data/{module}:{container}/{path}, HTTP methods replace RPC verbs, and JSON (RFC 7951) is the preferred encoding. RESTCONF is stateless — no candidate datastore, no locking, no confirmed commit — making it ideal for read operations, simple updates, and integration with HTTP-native tooling.

Constructing valid payloads requires understanding the YANG tree structure and applying the correct encoding rules. pyang provides command-line tools: -f tree for visualization, -f sample-xml-skeleton for XML templates, and the jsonxsl/jtox plugins for XML-JSON conversion. Cisco YANG Suite provides a GUI workflow that constructs URIs, XML NETCONF payloads, and JSON RESTCONF payloads interactively and exports to Python (ncclient) or Ansible code. XML payloads require correct xmlns namespace declarations; JSON payloads require the YANG module name as a prefix at module boundaries.

Key Terms

Chapter 3: Python Network Automation with Netmiko

Learning Objectives

By the end of this chapter, you will be able to:

• Build Python scripts using Netmiko to connect to and manage Cisco IOS XE devices over SSH
• Automate configuration deployment and running-configuration backups with Netmiko
• Implement structured output parsing using TextFSM and Genie parsers to convert CLI text into Python data structures
• Handle multi-device automation at scale using concurrent.futures, robust exception handling, and structured logging

Introduction

Imagine you are the network engineer responsible for 200 Cisco IOS XE switches spread across a campus. A new NTP server needs to be configured on every device before midnight. Doing this manually — launching PuTTY, logging in, typing the same four commands, saving, disconnecting, repeating — would take the better part of a night shift and invite at least a dozen typos. With Netmiko and about 30 lines of Python, you finish in under two minutes, every device gets identical configuration, and you have a log file proving it.

This chapter is your guide to that transformation. We start from first principles — how Netmiko works and why it exists — then build progressively through configuration management, structured output parsing, and finally production-grade multi-device automation with concurrency and error handling. Every section includes working code you can run in a lab today.

Section 1: Netmiko Fundamentals

1.1 What Is Netmiko and Why Does It Exist?

SSH was designed for human operators. When you SSH into a Cisco device manually, the router sends you a login banner, waits for your credentials, presents a privilege-level prompt, and then accepts your commands one at a time. Every one of those interactions involves arbitrary timing — banners can be long or short, devices can be slow, prompts change depending on mode.

The underlying Python SSH library Paramiko can establish these connections, but it was built for generic Unix server automation. It has no knowledge of Cisco CLI state machines, prompt patterns, or the difference between user EXEC mode (Router>) and global configuration mode (Router(config)#). Writing Paramiko code for network devices requires hand-crafting prompt detection, managing mode transitions, and handling the quirks of dozens of different vendor CLIs — a significant engineering effort.

Netmiko — created by Kirk Byers in 2014 and open-source ever since — solves this exactly. It wraps Paramiko with a higher-level interface that understands network device CLI behavior. Netmiko ships with built-in support for over 80 device types, including every major Cisco platform: IOS, IOS XE, IOS XR, NX-OS, ASA, and more. [Source: https://pynet.twb-tech.com/blog/netmiko-python-library.html]

The analogy: if Paramiko is a raw electrical current, Netmiko is a power outlet — same energy, but shaped for the devices you actually plug in.

1.2 The ConnectHandler: Your Entry Point

Every Netmiko session begins with ConnectHandler. You pass it a dictionary describing the device — its type, address, and credentials — and Netmiko handles the SSH handshake, login, and prompt negotiation automatically.

Installation:

pip install netmiko

Basic connection to a Cisco IOS XE device:

from netmiko import ConnectHandler

device = {
    "device_type": "cisco_xe",      # IOS XE (Catalyst 9K, ASR, CSR)
    "host": "192.168.1.1",
    "username": "admin",
    "password": "cisco123",
    "secret": "enable_secret",      # For privilege escalation (optional)
    "port": 22,                     # Default; can be omitted
}

connection = ConnectHandler(**device)
print(connection.find_prompt())     # Confirms successful login
connection.disconnect()

The device_type parameter is critical. It tells Netmiko which prompt patterns to expect and how to handle mode transitions. For IOS XE devices (Catalyst 9000 series, newer ASR routers, CSR 1000v), use "cisco_xe". For classic IOS, "cisco_ios" also works and behaves identically in most cases. [Source: https://ciscolearning.github.io/cisco-learning-codelabs/posts/netmiko-ios/]

Figure 3.1: Netmiko SSH Connection Sequence

sequenceDiagram
    participant Script as Python Script
    participant Netmiko as Netmiko (ConnectHandler)
    participant Device as Cisco IOS XE Device

    Script->>Netmiko: ConnectHandler(**device)
    Netmiko->>Device: TCP connect (port 22)
    Device-->>Netmiko: TCP ACK
    Netmiko->>Device: SSH handshake
    Device-->>Netmiko: SSH session established
    Netmiko->>Device: Send username
    Device-->>Netmiko: Password prompt
    Netmiko->>Device: Send password
    Device-->>Netmiko: Login banner + prompt (Router>)
    Netmiko->>Netmiko: Detect prompt pattern via device_type
    Netmiko-->>Script: Connection object ready

    Script->>Netmiko: send_command("show version")
    Netmiko->>Device: "show version\n"
    Device-->>Netmiko: Output + prompt
    Netmiko-->>Script: Output string

    Script->>Netmiko: disconnect()
    Netmiko->>Device: SSH close
    Device-->>Netmiko: Connection closed

Common device_type values for Cisco platforms:

1.3 send_command vs. send_config_set

These two methods are the workhorses of every Netmiko script. Understanding when to use each is fundamental.

send_command() is for operational (read-only) commands: show, ping, traceroute, debug. It sends a single command, waits for the device prompt to return, and gives you back the output as a string. Netmiko automatically detects when the output is complete by watching for the prompt pattern — you never need to add sleep timers.

output = connection.send_command("show ip interface brief")
print(output)

send_config_set() is for pushing configuration changes. It accepts a Python list of configuration commands, automatically issues configure terminal to enter global configuration mode, sends each command in sequence, and then exits configuration mode with end. The entire transaction is atomic from Netmiko’s perspective.

config_commands = [
    "interface GigabitEthernet1",
    "description Uplink to Core Switch",
    "ip address 10.0.0.1 255.255.255.0",
    "no shutdown",
]
output = connection.send_config_set(config_commands)
print(output)  # Shows the config session transcript

Think of send_command as asking a question and send_config_set as giving instructions. One reads state; the other changes it. [Source: https://networkjourney.com/cisco-netmiko-scripting-with-examples-a-comprehensive-guide/]

Figure 3.2: Choosing Between send_command and send_config_set

flowchart TD
    A([Start: Need to interact with device]) --> B{Read or Write?}
    B -->|Read operational state| C[send_command]
    B -->|Change configuration| D[send_config_set]

    C --> C1[Stays in EXEC mode]
    C --> C2[Single command string]
    C --> C3[Returns raw string or structured data]
    C3 --> C4{Need structured data?}
    C4 -->|Yes| C5[Add use_textfsm=True or use_genie=True]
    C4 -->|No| C6[Use raw string directly]

    D --> D1[Auto-issues 'configure terminal']
    D --> D2[Sends list of config commands]
    D --> D3[Auto-issues 'end' on completion]
    D3 --> D4[Call save_config to persist]

    C6 --> E([Done])
    C5 --> E
    D4 --> E

Comparison table:

1.4 Session Management and the Context Manager Pattern

Always close SSH connections when done. An unclosed connection holds a VTY line on the device — Cisco devices typically have only 5 to 16 VTY lines, and exhausting them locks out all remote access.

The explicit pattern uses disconnect():

connection = ConnectHandler(**device)
# ... do work ...
connection.disconnect()

The preferred production pattern uses Netmiko as a context manager, which guarantees disconnection even if an exception occurs mid-script:

with ConnectHandler(**device) as connection:
    output = connection.send_command("show version")
    print(output)
# disconnect() is called automatically here

This mirrors the Python file-handling idiom (with open(...) as f:) and is the pattern you should use in all production code. [Source: https://pyneng.readthedocs.io/en/latest/book/18_ssh_telnet/netmiko.html]

1.5 Privilege Mode and Enable

Some commands and all configuration changes require privilege EXEC mode (the # prompt). If your device requires enable to elevate privileges, include "secret" in the device dictionary and call enable() after connecting:

device = {
    "device_type": "cisco_xe",
    "host": "192.168.1.1",
    "username": "admin",
    "password": "cisco123",
    "secret": "my_enable_secret",
}

with ConnectHandler(**device) as conn:
    conn.enable()                        # Enters privilege EXEC mode
    output = conn.send_command("show running-config")
    print(output)

If your user account is already granted privilege 15 by the AAA policy (common in modern IOS XE deployments with RADIUS/TACACS+), enable() may not be needed.

Key Takeaway: Netmiko abstracts SSH complexity for network devices through ConnectHandler. The device_type parameter is essential — it controls prompt detection and mode transitions. Use send_command() for read operations and send_config_set() for configuration pushes. Always close connections via context managers or explicit disconnect() calls to preserve VTY lines.

Section 2: Configuration Management with Netmiko

2.1 Deploying Configuration at Scale

Configuration management is one of the highest-value use cases for Netmiko. Instead of maintaining ad-hoc change scripts or relying on individual engineers to manually configure devices, you can encode your intended state in Python and deploy it consistently to every device in scope.

Worked Example: Deploying a standardized NTP and logging configuration

from netmiko import ConnectHandler

# Standardized configuration to push to all access switches
standard_config = [
    "ntp server 10.0.1.100",
    "ntp server 10.0.1.101 prefer",
    "logging buffered 16384 informational",
    "logging host 10.0.2.50",
    "no logging console",
    "service timestamps log datetime msec localtime show-timezone",
]

device = {
    "device_type": "cisco_xe",
    "host": "192.168.10.5",
    "username": "netops",
    "password": "S3cur3P@ss",
}

with ConnectHandler(**device) as conn:
    print(f"[{device['host']}] Pushing standard config...")
    output = conn.send_config_set(standard_config)
    conn.save_config()
    print(f"[{device['host']}] Config saved. Output:\n{output}")

The call to conn.save_config() issues write memory (or copy running-config startup-config on platforms that require it), persisting the changes across a reload. Never skip this step in production — a device reload without saving will revert your changes. [Source: https://developer.cisco.com/learning/labs/intro-netmiko/]

2.2 Configuration Backup Automation

Regulatory requirements and change management best practices demand regular configuration backups. Manual backups are inconsistent and error-prone. With Netmiko, you can automate timestamped backups for your entire device inventory.

Worked Example: Automated backup with timestamp

from netmiko import ConnectHandler
from datetime import datetime
import os

def backup_device_config(device: dict, backup_dir: str = "./backups") -> str:
    """
    Connect to a device, retrieve running-config, and save to a
    timestamped file. Returns the backup file path.
    """
    os.makedirs(backup_dir, exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    filename = f"{backup_dir}/backup_{device['host']}_{timestamp}.txt"

    with ConnectHandler(**device) as conn:
        running_config = conn.send_command("show running-config")

    with open(filename, "w") as f:
        f.write(f"! Backup of {device['host']} at {timestamp}\n")
        f.write(running_config)

    print(f"Backup saved: {filename}")
    return filename

device = {
    "device_type": "cisco_xe",
    "host": "10.0.0.1",
    "username": "admin",
    "password": "cisco",
}

backup_device_config(device)

This function is intentionally modular — it takes a device dictionary and a backup directory, which makes it easy to call from a multi-device loop or concurrent executor later in this chapter. [Source: https://blog.cloudmylab.com/netmiko-python-for-network-automation]

2.3 Verifying Configuration After Push

A critical practice in network automation is verify after change. Push the configuration, then immediately read back the relevant section of running-config to confirm it took effect:

with ConnectHandler(**device) as conn:
    # Push
    conn.send_config_set(["ntp server 10.0.1.100"])
    conn.save_config()

    # Verify
    output = conn.send_command("show ntp associations")
    if "10.0.1.100" in output:
        print(f"[{device['host']}] NTP server confirmed in associations.")
    else:
        print(f"[{device['host']}] WARNING: NTP server not yet visible.")

This pattern — push, then pull and assert — is the foundation of idempotent automation. Over time, it becomes the basis for drift detection: you can run the verification step alone (without the push) to audit whether a device matches your intended state.

Figure 3.3: Configuration Push and Verify Workflow

flowchart TD
    A([Start]) --> B[Connect via ConnectHandler]
    B --> C[Build config command list]
    C --> D[send_config_set with commands]
    D --> E[call save_config]
    E --> F[send_command to verify]
    F --> G{Expected value\npresent in output?}
    G -->|Yes| H[Log success]
    G -->|No| I[Log WARNING: config not confirmed]
    I --> J{Retry?}
    J -->|Yes| D
    J -->|No| K[Alert operator]
    H --> L[disconnect]
    K --> L
    L --> M([End])

2.4 Sending Commands That Require Confirmation

Some IOS XE commands prompt for confirmation ([confirm] or [yes/no]). By default, send_command() would hang waiting for a prompt that never matches. Netmiko provides expect_string to handle this:

# Reload the device after a delay — requires confirmation
output = conn.send_command(
    "reload in 10",
    expect_string=r"Proceed with reload\?",
)
output += conn.send_command(
    "yes",
    expect_string=r"#",
)

Alternatively, send_command_timing() uses a fixed time delay instead of prompt matching — useful for commands with unpredictable output patterns.

Key Takeaway: send_config_set() handles the full configuration session lifecycle — entering config mode, sending commands, and exiting — so you only need to supply the actual configuration lines. Always call save_config() to persist changes. Pair every configuration push with an immediate verification step to detect failures fast.

Section 3: Structured Output Parsing

3.1 The Problem with Raw CLI Text

When Netmiko returns output from send_command("show ip interface brief"), you get a multi-line string that looks exactly like what you would see in a terminal:

Interface              IP-Address      OK? Method Status                Protocol
GigabitEthernet1       10.0.0.1        YES NVRAM  up                    up
GigabitEthernet2       unassigned      YES unset  administratively down down
GigabitEthernet3       192.168.1.1     YES manual up                    up

This is human-readable, but machine-hostile. To check whether any interfaces are down, you would need to split lines, parse column offsets, handle variable-width fields, and account for platform-specific variations. Writing and maintaining that code for dozens of different commands across multiple Cisco platforms is unsustainable.

Structured parsing converts this text into Python data structures — lists of dictionaries or nested dictionaries — so you can access fields by name:

output[0]["intf"]   # "GigabitEthernet1"
output[0]["status"] # "up"

Netmiko supports two primary structured parsing backends: TextFSM (via ntc-templates) and Genie (via Cisco pyATS). [Source: https://deepwiki.com/ktbyers/netmiko/7.2-structured-data-parsing]

3.2 TextFSM with ntc-templates

TextFSM is a Python library by Google that uses template files to extract fields from semi-structured text using regular expressions. The ntc-templates project maintains a large community library of TextFSM templates covering hundreds of Cisco and multi-vendor commands.

Setup:

pip install ntc-templates

The NET_TEXTFSM environment variable should point to your ntc-templates directory, but when you pip install ntc-templates, Netmiko finds the templates automatically.

Using TextFSM parsing in Netmiko:

Pass use_textfsm=True to send_command(). When a matching template exists, the return value changes from a raw string to a list of dictionaries:

from netmiko import ConnectHandler

conn = ConnectHandler(
    device_type="cisco_xe",
    host="192.168.1.1",
    username="admin",
    password="cisco123",
)

# Without TextFSM: returns a raw string
raw = conn.send_command("show ip interface brief")

# With TextFSM: returns list of dicts
parsed = conn.send_command("show ip interface brief", use_textfsm=True)

for intf in parsed:
    status = intf["status"]
    proto  = intf["proto"]
    name   = intf["intf"]
    ip     = intf["ipaddr"]
    if status != "up" or proto != "up":
        print(f"ALERT: {name} ({ip}) is {status}/{proto}")

conn.disconnect()

[Source: https://www.packetswitch.co.uk/netmiko-and-textfsm-example/]

Worked Example: Auditing routes with TextFSM

routes = conn.send_command("show ip route", use_textfsm=True)

# Find all OSPF routes
ospf_routes = [r for r in routes if r.get("protocol") == "O"]
print(f"Total OSPF routes: {len(ospf_routes)}")
for route in ospf_routes:
    print(f"  {route['network']}/{route['mask']} via {route['nexthop']}")

3.3 Genie Parser Integration

Cisco Genie is the official Cisco parser library, part of the pyATS test framework. Where TextFSM returns flat dictionaries, Genie returns deeply nested dictionaries following a rich, officially documented schema. This makes Genie ideal for complex Cisco-specific use cases like BGP state analysis, OSPF topology extraction, or interface statistics processing.

Setup:

pip install genie
# For the full pyATS framework (recommended for lab use):
pip install pyats[full]

Using Genie with Netmiko:

# BGP summary parsed with Genie
bgp_data = conn.send_command("show ip bgp summary", use_genie=True)

# Navigate the nested schema
neighbors = (
    bgp_data
    .get("vrf", {})
    .get("default", {})
    .get("neighbor", {})
)

for neighbor_ip, data in neighbors.items():
    state = data.get("session_state", "unknown")
    prefixes = data.get("address_family", {}).get("ipv4 unicast", {}).get("prefixes_received", 0)
    print(f"BGP Neighbor: {neighbor_ip} | State: {state} | Prefixes: {prefixes}")

[Source: https://networkautomationlane.in/how-to-install-and-parse-data-with-netmiko-genie-plugin/]

Worked Example: Extracting interface counters with Genie

interfaces = conn.send_command("show interfaces", use_genie=True)

for intf_name, data in interfaces.items():
    counters = data.get("counters", {})
    in_errors  = counters.get("in_errors", 0)
    out_errors = counters.get("out_errors", 0)
    if in_errors > 0 or out_errors > 0:
        print(f"ERRORS on {intf_name}: IN={in_errors}, OUT={out_errors}")

3.4 TextFSM vs. Genie: Choosing the Right Tool

The decision rule is straightforward: use TextFSM when you need quick, multi-vendor coverage with simple flat data. Use Genie when you need the official Cisco schema, particularly for complex protocols (BGP, OSPF, EIGRP) where the nested structure reveals relationships that flat dicts cannot represent. [Source: https://www.jcc.sh/network-automation-text-parsing-landscape/]

Figure 3.4: Structured Output Parsing Pipeline

graph TD
    A[Raw CLI Text from send_command] --> B{Parser selection}

    B -->|use_textfsm=True| C[TextFSM Engine]
    B -->|use_genie=True| D[Genie / pyATS Engine]
    B -->|No parser flag| E[Raw string returned]

    C --> F[ntc-templates library]
    F --> G{Template found\nfor command?}
    G -->|Yes| H[List of flat dicts\ne.g. intf, ipaddr, status]
    G -->|No| I[Raw string fallback]

    D --> J[Cisco official schema]
    J --> K{Parser\nsupports command?}
    K -->|Yes| L[Nested dict\ne.g. vrf > neighbor > state]
    K -->|No| M[Raw string fallback]

    H --> N{Use case}
    L --> N
    N -->|Quick audit, multi-vendor| O[Use TextFSM result]
    N -->|BGP/OSPF/EIGRP deep analysis| P[Use Genie result]
    N -->|Fallback / unknown platform| Q[Parse raw string manually]

3.5 The structured_data_converter Utility

For scripts that need to be robust across environments where template coverage may be incomplete, Netmiko provides a structured_data_converter() utility that tries parsers in priority order — TextFSM first, then TTP, then Genie — returning the first successful structured result, or falling back to the raw string:

from netmiko.utilities import structured_data_converter

raw_output = conn.send_command("show interfaces")

structured = structured_data_converter(
    command="show interfaces",
    raw_data=raw_output,
    platform="cisco_ios",
)

if isinstance(structured, list):
    print(f"Parsed {len(structured)} interface entries.")
else:
    print("Parsing failed — raw text returned.")
    print(structured)

[Source: https://ktbyers.github.io/netmiko/docs/netmiko/utilities.html]

3.6 Writing Reusable Parsing Libraries

As your automation codebase grows, avoid scattering use_textfsm=True calls throughout ad-hoc scripts. Instead, build a thin parsing layer that centralizes your parsing logic:

# netops/parsers.py

from netmiko import ConnectHandler
from typing import Union

def get_interfaces(conn) -> list[dict]:
    """Return interface status as a list of dicts via TextFSM."""
    return conn.send_command("show ip interface brief", use_textfsm=True)

def get_bgp_summary(conn) -> dict:
    """Return BGP summary as a Genie-parsed nested dict."""
    return conn.send_command("show ip bgp summary", use_genie=True)

def get_routes(conn, prefix_filter: str = None) -> list[dict]:
    """Return routing table entries, optionally filtered by network prefix."""
    routes = conn.send_command("show ip route", use_textfsm=True)
    if prefix_filter:
        return [r for r in routes if r.get("network", "").startswith(prefix_filter)]
    return routes

Centralizing parsing makes it easy to swap the underlying parser (TextFSM → Genie), add caching, or add unit tests using recorded CLI output — without touching every script that consumes the data.

Key Takeaway: Never build report or audit logic on raw CLI strings. Use use_textfsm=True for quick multi-vendor access to flat data and use_genie=True for deep, schema-rich Cisco-specific parsing. Wrap your parsing calls in a dedicated module to isolate parser changes from business logic.

Section 4: Multi-Device Automation and Error Handling

4.1 Sequential vs. Concurrent Execution

The simplest multi-device approach is a sequential loop: iterate over a device list, connect, execute, disconnect, repeat. This works fine for 5–10 devices, but becomes impractical at scale. Connecting to a device over SSH takes 2–5 seconds for the handshake alone. Running a show command may take another 1–3 seconds. At 3 seconds per device, 100 devices takes 5 minutes. At 5 seconds per device, 500 devices takes over 40 minutes.

Netmiko SSH operations are I/O-bound — the script spends most of its time waiting for the network, not computing. This makes them ideal candidates for threading: while one thread waits for a slow device to respond, other threads are actively working on other devices. Python’s concurrent.futures.ThreadPoolExecutor makes this pattern clean and safe. [Source: https://networkevolution.in/blogpost106-speed-up-network-automation-tasks-with-netmiko-and-concurrent-futures-multithreading/]

I/O-bound vs. CPU-bound: Why threading (not multiprocessing)?

4.2 Loading Device Inventories from YAML

Hardcoding device lists in scripts is a maintenance antipattern. Instead, store your inventory in a YAML file that can be version-controlled and updated independently of code:

inventory.yaml:

devices:
  - device_type: cisco_xe
    host: 10.0.1.1
    username: netops
    password: "{{ DEVICE_PASSWORD }}"   # placeholder — use env var in code

  - device_type: cisco_xe
    host: 10.0.1.2
    username: netops
    password: "{{ DEVICE_PASSWORD }}"

  - device_type: cisco_xe
    host: 10.0.1.3
    username: netops
    password: "{{ DEVICE_PASSWORD }}"

Loading the inventory and injecting credentials from environment variables:

import yaml
import os

def load_inventory(path: str) -> list[dict]:
    """Load device inventory from YAML and inject credentials from env vars."""
    password = os.environ.get("DEVICE_PASSWORD")
    if not password:
        raise EnvironmentError("DEVICE_PASSWORD environment variable not set.")

    with open(path) as f:
        data = yaml.safe_load(f)

    devices = data["devices"]
    for device in devices:
        device["password"] = password  # Overwrite placeholder

    return devices

devices = load_inventory("inventory.yaml")

Never store credentials in YAML, CSV, or any version-controlled file. Use environment variables, python-dotenv, or a secrets manager like HashiCorp Vault. [Source: https://codezup.com/python-network-automation-tutorial-netmiko-nornir/]

4.3 Concurrent Execution with ThreadPoolExecutor

The pattern below is the production-standard approach for parallel Netmiko operations. Study it carefully — it will appear in variations throughout your ENAUTO career.

from netmiko import ConnectHandler
from netmiko.exceptions import NetmikoTimeoutException, NetmikoAuthenticationException
from concurrent.futures import ThreadPoolExecutor, as_completed
import logging

# Configure structured logging
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[
        logging.FileHandler("automation.log"),
        logging.StreamHandler(),
    ]
)
log = logging.getLogger(__name__)

def collect_show_version(device: dict) -> dict:
    """
    Connect to a single device and collect 'show version'.
    Returns a result dict suitable for reporting.
    """
    host = device["host"]
    conn = None
    try:
        conn = ConnectHandler(**device)
        output = conn.send_command("show version")
        log.info(f"[{host}] Collection successful.")
        return {"host": host, "output": output, "status": "success"}

    except NetmikoTimeoutException:
        log.error(f"[{host}] Connection timed out.")
        return {"host": host, "output": None, "status": "timeout"}

    except NetmikoAuthenticationException:
        log.error(f"[{host}] Authentication failed.")
        return {"host": host, "output": None, "status": "auth_failed"}

    except Exception as e:
        log.exception(f"[{host}] Unexpected error: {e}")
        return {"host": host, "output": None, "status": f"error: {e}"}

    finally:
        if conn:
            conn.disconnect()


# Run up to 10 SSH sessions in parallel
devices = load_inventory("inventory.yaml")

results = []
with ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(collect_show_version, dev): dev for dev in devices}
    for future in as_completed(futures):
        result = future.result()
        results.append(result)

# Summarize
success = [r for r in results if r["status"] == "success"]
failed  = [r for r in results if r["status"] != "success"]
print(f"\nCompleted: {len(success)} success, {len(failed)} failed.")
for r in failed:
    print(f"  FAILED: {r['host']} — {r['status']}")

[Source: https://www.packetswitch.co.uk/python-concurrent/]

Figure 3.5: Concurrent Multi-Device Automation with ThreadPoolExecutor

flowchart TD
    A([Start]) --> B[Load inventory.yaml]
    B --> C[Inject credentials from env vars]
    C --> D[Create ThreadPoolExecutor\nmax_workers = N]

    D --> E[Submit worker function\nfor each device]

    E --> F1[Thread 1: Device 10.0.1.1]
    E --> F2[Thread 2: Device 10.0.1.2]
    E --> F3[Thread 3: Device 10.0.1.3]
    E --> F4[Thread N: Device 10.0.1.N]

    F1 --> G1{Connect OK?}
    F2 --> G2{Connect OK?}
    F3 --> G3{Connect OK?}
    F4 --> G4{Connect OK?}

    G1 -->|Yes| H1[Run command / push config]
    G1 -->|Timeout| I1[Log error, return status=timeout]
    G1 -->|Auth fail| J1[Log error, return status=auth_failed]

    G2 -->|Yes| H2[Run command / push config]
    G2 -->|Timeout| I2[Log error, return status=timeout]

    H1 --> K1[disconnect in finally block]
    H2 --> K2[disconnect in finally block]
    I1 --> K1
    I2 --> K2
    J1 --> K1

    K1 --> L[Collect results via as_completed]
    K2 --> L
    G3 --> L
    G4 --> L

    L --> M[Summarize: success / failed counts]
    M --> N([End])

4.4 Tuning max_workers

Choosing the right max_workers value requires balancing two constraints:

1. Your machine: each thread consumes memory and a file descriptor. Most modern workstations handle 50–100 threads comfortably.
2. The devices: Cisco IOS XE devices typically allow 5 to 16 concurrent VTY lines (line vty 0 15). Exceeding the device’s VTY limit causes new connections to be refused.

Practical guidance:

Always test with a single device first, then a small batch, before scaling to your full inventory. [Source: https://devangnp.github.io/blog/netmiko-multithreading/]

4.5 Concurrent Configuration Push

The same ThreadPoolExecutor pattern applies to configuration pushes. The only differences are calling send_config_set() instead of send_command(), and calling save_config() before disconnecting:

def push_standard_config(device: dict, commands: list) -> dict:
    """Push a list of configuration commands to a device."""
    host = device["host"]
    conn = None
    try:
        conn = ConnectHandler(**device)
        output = conn.send_config_set(commands)
        conn.save_config()
        log.info(f"[{host}] Config pushed and saved.")
        return {"host": host, "output": output, "status": "success"}
    except NetmikoTimeoutException:
        log.error(f"[{host}] Timeout during config push.")
        return {"host": host, "output": None, "status": "timeout"}
    except Exception as e:
        log.exception(f"[{host}] Config push failed: {e}")
        return {"host": host, "output": None, "status": str(e)}
    finally:
        if conn:
            conn.disconnect()

# Commands to standardize across the fleet
ntp_commands = [
    "ntp server 10.0.1.100",
    "ntp server 10.0.1.101 prefer",
    "ntp update-calendar",
]

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = [executor.submit(push_standard_config, dev, ntp_commands) for dev in devices]
    results = [f.result() for f in as_completed(futures)]

Important: Be cautious about pushing configuration concurrently to devices that have dependencies on each other (e.g., pushing BGP configuration to both ends of a peer relationship simultaneously). When order matters, use sequential execution or ordered batching. [Source: https://gist.github.com/tyler-8/f8d768f64e0ffcf6ae8eefa6502d3fec]

4.6 Complete Exception Handling Reference

Netmiko’s exception hierarchy is shallow but covers the most common failure modes. Always import and handle these explicitly:

from netmiko.exceptions import (
    NetmikoTimeoutException,        # TCP connect timeout
    NetmikoAuthenticationException, # Bad credentials
    ReadTimeout,                    # Command output took too long
    NetmikoBaseException,           # Parent class for all Netmiko exceptions
)
from paramiko.ssh_exception import SSHException  # SSH-layer errors

Exception reference table:

4.7 Tuning Connection Parameters for Slow Devices

Older Cisco hardware, high-latency WAN links, or devices under load can cause timeout errors on otherwise healthy connections. Fine-tune these ConnectHandler parameters:

device = {
    "device_type": "cisco_xe",
    "host": "10.0.0.1",
    "username": "admin",
    "password": "cisco",
    "conn_timeout": 15,        # TCP connection timeout (default: 10s)
    "banner_timeout": 20,      # SSH banner wait (default: 15s)
    "auth_timeout": 15,        # Authentication wait (default: 10s)
    "global_delay_factor": 2,  # Multiplier for all internal wait timers
    "read_timeout": 30,        # Max wait for show command output (default: 10s)
}

global_delay_factor is a multiplier applied to all of Netmiko’s internal timing estimates. Setting it to 2 effectively doubles all waits — useful for slow console servers or heavily loaded devices. [Source: https://widewiki.com/posts/python/geek-pie/python-for-network-automation-a-comprehensive-guide-to-netmiko/]

4.8 Production Logging Best Practices

Avoid print() statements in production scripts. Use Python’s logging module with a structured format that includes timestamps, log levels, and the originating module:

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
    handlers=[
        logging.FileHandler("netops_automation.log"),
        logging.StreamHandler(),  # Also print to console
    ]
)

log = logging.getLogger(__name__)

# Use appropriate levels:
log.debug("Entering config mode...")    # Verbose, for troubleshooting
log.info("Config pushed successfully.") # Normal operation
log.warning("Device responded slowly.") # Noteworthy but not breaking
log.error("Connection failed.")         # Error, script continues
log.exception("Unexpected exception.")  # Error + full traceback

A log file with structured output gives you an audit trail for every automation run — critical for compliance, post-incident review, and debugging failures that only occur at 2am. [Source: https://oneuptime.com/blog/post/2026-03-20-netmiko-ssh-cisco-show-commands/view]

Key Takeaway: Multi-device Netmiko automation at scale requires three pillars: external inventory management (YAML/CSV with credentials from environment variables), concurrent execution (ThreadPoolExecutor with tuned max_workers), and comprehensive error handling (explicit exception classes with a finally disconnect). Logging to file with timestamps is not optional in production — it is your audit trail.

Chapter Summary

This chapter built a complete picture of Python network automation with Netmiko, from a single SSH connection to a production-grade concurrent multi-device pipeline.

We started with ConnectHandler — the entry point for all Netmiko sessions — and learned that device_type is the critical parameter that shapes how Netmiko interprets the CLI. We distinguished send_command() (for operational reads) from send_config_set() (for configuration writes) and established the context manager pattern as the correct way to manage SSH sessions.

In configuration management, we built modular functions for deploying standard configurations and automating timestamped backups, always pairing each push with a verification step and a save_config() call.

Structured parsing transformed raw CLI text into programmable Python data structures. TextFSM with ntc-templates provides lightweight, multi-vendor flat dictionaries. Genie with pyATS provides rich, officially schematized nested dictionaries for deep Cisco analysis. The choice depends on your data complexity requirements.

Finally, we scaled to production with ThreadPoolExecutor, exploiting the I/O-bound nature of SSH connections to run parallel sessions. Robust exception handling — with explicit Netmiko exception classes and finally disconnects — ensures that failures in one device never cascade to others, and structured logging creates the audit trail every production environment requires.

Key Terms

Chapter 4: Python Network Automation with ncclient

Learning Objectives

By the end of this chapter, you will be able to:

• Build Python scripts using ncclient to manage Cisco IOS XE devices via NETCONF
• Construct and send NETCONF RPC operations including get, get-config, and edit-config
• Use XML filters — subtree and XPath — to retrieve targeted configuration and state data
• Implement configuration validation and commit workflows, including confirmed commits and rollback

Introduction

Imagine you are a librarian managing a vast archive. Rather than walking the stacks every time someone asks for a book, you have a structured catalog system: patrons submit requests in a defined format, the system retrieves exactly what they need, and changes are checked in through an approval process before they affect the permanent record. That is precisely how NETCONF works on a network device — and ncclient is the Python toolkit that lets you speak that language fluently.

NETCONF (Network Configuration Protocol), defined in RFC 6241, is an XML-based RPC protocol that communicates over SSH on TCP port 830 by default. It gives automation scripts a vendor-neutral, schema-validated interface to device configuration and operational state. Unlike CLI scraping (which is brittle and fragile) or SNMP (which is largely read-only and cumbersome to configure with), NETCONF offers structured reads, transactional writes, rollback capability, and support for candidate datastores.

ncclient is the de facto standard Python library for NETCONF client development. It abstracts the raw SSH and XML wire protocol behind a clean Python API, handles session lifecycle management, and provides utilities for building and parsing XML payloads. On the Cisco ENAUTO 300-435 exam, ncclient is the expected tool for NETCONF-based Python automation tasks.

[Source: https://ncclient.readthedocs.io/en/latest/] [Source: https://www.rfc-editor.org/rfc/rfc6241]

Section 1: ncclient Fundamentals

Installing ncclient and Preparing the Device

Install ncclient from PyPI using pip. It is recommended to use a virtual environment to isolate dependencies:

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

lxml is installed alongside ncclient because it is the primary library used to parse and navigate the XML responses NETCONF returns. xmltodict is a convenience library that converts XML structures into Python dictionaries, useful for quick data extraction.

[Source: https://pypi.org/project/ncclient/]

Before you can connect, NETCONF must be enabled on the Cisco IOS XE device. In a lab environment, this requires the following IOS XE configuration:

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

The first command enables the NETCONF/YANG subsystem. The second enables the candidate datastore, which is the staging area for safe configuration changes (covered in depth in Section 4). After enabling NETCONF, verify the process is running:

show platform software yang-management process

You should see ncsshd (the NETCONF SSH daemon) listed as running. NETCONF listens on TCP port 830.

[Source: https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/175/b_175_programmability_cg/m_175_prog_yang_netconf.html]

Establishing a Connection with manager.connect()

The entry point into ncclient is the manager.connect() function. It establishes an SSH connection to the device, negotiates the NETCONF session (exchanging <hello> messages with capability lists), and returns a Manager object representing the active session.

Think of manager.connect() as dialing into the device’s structured management interface — once connected, the Manager object is your handle for all subsequent NETCONF operations.

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}")

The with statement is the preferred usage pattern. It guarantees that m.close_session() is called automatically when the block exits — even if an exception is raised. This prevents orphaned NETCONF sessions on the device, which can consume resources and cause lock contention.

Key manager.connect() parameters:

Important: In production, set hostkey_verify=True and populate ~/.ssh/known_hosts with device host keys. Setting it to False bypasses SSH host key validation and is only acceptable in controlled lab environments.

[Source: https://ncclient.readthedocs.io/en/latest/] [Source: https://ciscolearning.github.io/cisco-learning-codelabs/posts/netconf-ios/]

Checking Server Capabilities

During the NETCONF session establishment, both client and server exchange <hello> messages that advertise their supported capabilities. These capabilities are URN strings that tell you exactly what the device supports: which datastores are available, which operations are valid, and which YANG modules are loaded.

Always inspect capabilities before attempting advanced operations — attempting a confirmed commit on a device that does not advertise the confirmed-commit capability will result in an RPC error.

with manager.connect(**device) as m:
    for cap in sorted(m.server_capabilities):
        print(cap)

Critical capabilities to check for IOS XE automation:

A practical pattern for checking specific capabilities before using them:

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)

    print(f"Candidate datastore : {has_candidate}")
    print(f"Validate operation  : {has_validate}")
    print(f"XPath filtering     : {has_xpath}")
    print(f"Confirmed commit    : {has_conf_cmmt}")

[Source: https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1715/b_1715_programmability_cg/netconf_protocol.html]

Session Lifecycle

A NETCONF session has a well-defined lifecycle:

SSH Connect → <hello> exchange → Operations → <close-session> → SSH Disconnect

Using manager.connect() as a context manager handles the full lifecycle automatically. If you need to manage the connection manually (for example, in a long-running service process), you can use explicit open/close calls:

m = manager.connect(**device)
# ... perform operations ...
m.close_session()   # sends <close-session> RPC, then closes SSH

If the session is interrupted abnormally (network failure, process kill), any locks held by the session are automatically released by the device when it detects the SSH connection has closed.

Figure 4.1: NETCONF Session Lifecycle

sequenceDiagram
    participant Script as Python Script (ncclient)
    participant Device as IOS XE Device (port 830)

    Script->>Device: TCP SYN → SSH Handshake
    Device-->>Script: SSH Session Established

    Script->>Device: NETCONF <hello> (client capabilities)
    Device-->>Script: NETCONF <hello> (server capabilities list)
    Note over Script,Device: Session negotiated — Manager object ready

    loop NETCONF Operations
        Script->>Device: <rpc> get / get-config / edit-config / etc.
        Device-->>Script: <rpc-reply> with <data> or <ok/> or <rpc-error>
    end

    alt Normal teardown (context manager __exit__)
        Script->>Device: <close-session/>
        Device-->>Script: <ok/>
        Device->>Device: Release all locks held by this session
    else Abnormal termination (exception / network failure)
        Note over Device: SSH keepalive timeout detected
        Device->>Device: Auto-release all session locks
    end

    Device-->>Script: SSH Disconnect

Key Takeaway: manager.connect() is the gateway to all NETCONF operations. Always use it as a context manager (with statement) to ensure clean session teardown. Check server capabilities after connecting to confirm the device supports the operations your script requires before attempting them.

Section 2: NETCONF Operations with ncclient

The get_config Operation

get_config(source, filter=None) issues a <get-config> RPC and retrieves configuration data from the specified datastore. The source argument specifies which datastore to read: "running", "candidate", or "startup".

The reply is a GetReply object. Its most useful attributes are:

Retrieve the full running configuration:

from lxml import etree
from ncclient import manager

with manager.connect(**device) as m:
    reply = m.get_config(source="running")
    # Pretty-print the XML
    xml_str = etree.tostring(reply.data_ele, pretty_print=True).decode()
    print(xml_str)

Without a filter, get_config returns the entire datastore as XML — which on a production device can be tens of thousands of lines. Always apply a filter in production code to retrieve only what you need. Filters are covered in detail in Section 3.

The get Operation

get(filter=None) issues a <get> RPC that returns both configuration data and operational (state) data in a single response. This is the right operation when you need live statistics, interface counters, routing table state, or any data that only exists at runtime and is not stored in the configuration datastore.

iface_filter = """
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface>
    <name>GigabitEthernet1</name>
  </interface>
</interfaces>
"""

with manager.connect(**device) as m:
    reply = m.get(filter=("subtree", iface_filter))
    print(reply.data_xml)

Unlike get_config, get does not accept a source parameter — it always queries the current device state.

Figure 4.2: NETCONF Operations — Scope and Data Flow

graph TD
    OPS([ncclient Manager\nOperations]) --> READ[Read Operations]
    OPS --> WRITE[Write Operations]
    OPS --> CTRL[Control Operations]
    OPS --> CUSTOM[Custom RPCs]

    READ --> GC["get_config(source, filter)\nRetrieves configuration only\nsource: running / candidate / startup"]
    READ --> G["get(filter)\nRetrieves config + operational state\nRuntime statistics, counters, routes"]

    WRITE --> EC["edit_config(target, config)\nModifies target datastore\ndefault_operation: merge / replace / none"]
    WRITE --> CC["copy_config(source, target)\nCopies one datastore to another\ne.g. running → startup"]
    WRITE --> DC["delete_config(target)\nDeletes a datastore\ne.g. wipes startup config"]

    CTRL --> LK["lock(target) / unlock(target)\nExclusive write lock on datastore\nPrevents concurrent modification"]
    CTRL --> CM["commit()\nPromotes candidate → running\nconfirmed=True adds auto-rollback"]
    CTRL --> VL["validate(source)\nYANG constraint check\nbefore commit"]
    CTRL --> DS["discard_changes()\nResets candidate from running\nAbandons staged edits"]

    CUSTOM --> DI["dispatch(rpc_element)\nVendor-specific operations\ne.g. save-config, clear-counters"]

    style OPS fill:#023047,color:#fff
    style READ fill:#219ebc,color:#fff
    style WRITE fill:#e76f51,color:#fff
    style CTRL fill:#2a9d8f,color:#fff
    style CUSTOM fill:#6d6875,color:#fff

The edit_config Operation

edit_config(target, config, default_operation=None, error_option=None, test_option=None) sends an <edit-config> RPC to modify a datastore. The config argument must be a string or lxml Element wrapped in a <config> root element (not <data>, which is used in replies).

Minimum viable edit_config call:

config_payload = """
<config>
  <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
    <hostname>EDGE-RTR-01</hostname>
  </native>
</config>
"""

with manager.connect(**device) as m:
    reply = m.edit_config(target="running", config=config_payload)
    print(reply)   # <ok/> on success

The default_operation parameter controls how the merge is performed when no explicit operation attribute is present on an element:

For fine-grained control, embed operation attributes directly in the XML payload:

<config>
  <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
    <interface>
      <GigabitEthernet>
        <name>2</name>
        <description operation="replace">WAN Uplink to ISP</description>
        <shutdown operation="delete"/>
      </GigabitEthernet>
    </interface>
  </native>
</config>

The operation attribute accepts: merge, replace, create, delete, and remove. The difference between delete and remove is that delete raises an error if the node does not exist, while remove silently succeeds.

[Source: https://www.rfc-editor.org/rfc/rfc6241]

Lock and Unlock

The lock(target) and unlock(target) operations acquire and release an exclusive write lock on a datastore. A locked datastore rejects modification attempts from all other sessions — including CLI users on IOS XE.

with manager.connect(**device) as m:
    m.lock("candidate")
    try:
        # safe to make changes — no other session can modify candidate
        m.edit_config(target="candidate", config=config_payload)
        m.commit()
    finally:
        m.unlock("candidate")   # always release the lock

Lock both candidate and running in high-stakes environments to ensure nothing changes between your staged edit and the commit:

m.lock("candidate")
m.lock("running")
# ... change pipeline ...
m.unlock("running")
m.unlock("candidate")

If a lock is unavailable, ncclient raises an RPCError with error-tag set to in-use. The error-info field includes the session ID of the current lock holder, which helps with troubleshooting.

Commit

commit() promotes the candidate datastore to the running configuration. It is only valid when the candidate datastore capability is advertised and enabled.

m.commit()

A successful commit returns an <ok/> reply. A failed commit returns an <rpc-error> and raises RPCError. On IOS XE, after a successful commit, the running configuration reflects your changes but the startup configuration is not updated. To persist changes across a 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)

[Source: https://pynet.twb-tech.com/blog/netconf/iosxe-candidate-cfg1.html]

copy_config and delete_config

These operations are less frequently used but available:

# Copy running to startup (equivalent to 'write memory')
m.copy_config(source="running", target="startup")

# Wipe the candidate datastore and reset it from running
m.copy_config(source="running", target="candidate")

# Delete the startup configuration
m.delete_config(target="startup")

Loading Config from an External File

Keeping XML payloads in separate files promotes reusability and version control. A common pattern is to load the XML at runtime:

with manager.connect(**device) as m:
    with open("loopback_cfg.xml") as f:
        config_xml = f.read()
    reply = m.edit_config(target="candidate", config=config_xml)
    m.commit()

This makes it easy to manage device configurations as code — each XML file represents a desired state fragment that can be tested, reviewed, and committed in version control independently of the Python scripts that apply it.

[Source: https://github.com/CiscoDevNet/netconf-examples/blob/master/netconf-103/get_interfaces_csr1000V.py]

Key Takeaway: The five core NETCONF operations — get, get_config, edit_config, commit, and lock/unlock — form the complete toolkit for reading and writing device state. Always wrap locking in a try/finally block to ensure the lock is released even if an error occurs mid-operation.

Section 3: XML Filtering and Data Retrieval

Why Filtering Matters

Requesting the full configuration from a production IOS XE device can return an XML document exceeding 50,000 lines. Parsing that volume of data is slow, consumes memory, and puts unnecessary load on the device’s NETCONF subsystem. Filters allow you to tell the server precisely which data you want — the server does the work of extracting just that subtree before sending the reply.

ncclient accepts filters as a two-element tuple: (filter_type, criteria) where filter_type is either "subtree" or "xpath".

# Subtree filter
m.get_config(source="running", filter=("subtree", xml_string))

# XPath filter
m.get_config(source="running", filter=("xpath", "/ios:native/ios:hostname"))

Subtree Filtering

RFC 6241 mandates subtree filtering support on every conformant NETCONF implementation — it is universally supported and the safest choice for production code. A subtree filter is an XML document that mirrors the structure of the YANG data model; the server returns only the portions of the datastore whose structure matches the filter.

Think of a subtree filter as a stencil you press against the full configuration document — only the data that shows through the cutouts in the stencil is returned.

There are five types of filter components, each serving a distinct role:

1. Namespace Selection

Including an XML namespace URI (xmlns=) constrains matching to the specific YANG module that owns that namespace. This is always required — without it, the server may not know which module’s interface element you mean.

<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
  <!-- selects data from the Cisco IOS XE native YANG module -->
</native>

2. Containment Nodes

Intermediate elements used to navigate down the YANG tree to the target. They have child elements but no text content. They tell the server “I want data inside here, keep looking deeper.”

<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
  <interface>
    <!-- navigate into interface subtree -->
  </interface>
</native>

3. Selection Nodes

Empty leaf or container elements (self-closing tags). They mean “return this node and everything beneath it.” An empty <interface/> inside an <interfaces> container returns all interfaces with all their attributes.

<!-- Return ALL interfaces and all their sub-elements -->
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface/>
</interfaces>

4. Content Match Nodes

Leaf elements containing a text value. They act as a WHERE clause — only list entries where the specified leaf equals this value are returned. This is how you request a specific interface by name.

<!-- Return ONLY GigabitEthernet1 -->
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface>
    <name>GigabitEthernet1</name>
  </interface>
</interfaces>

5. Combining Content Match and Selection Nodes

Content match nodes and selection nodes can be mixed within the same parent to filter to a specific list entry and then select only certain attributes from that entry:

<!-- Find Loopback0, return only its description and IP address -->
<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
  <interface>
    <Loopback>
      <name>0</name>        <!-- content match: only Loopback0 -->
      <description/>        <!-- selection: return description -->
      <ip/>                 <!-- selection: return all IP sub-elements -->
    </Loopback>
  </interface>
</native>

Complete subtree filter example:

from lxml import etree
from ncclient import manager

interface_filter = """
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface>
    <name>GigabitEthernet1</name>
    <enabled/>
    <ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
  </interface>
</interfaces>
"""

with manager.connect(**device) as m:
    reply = m.get_config(source="running", filter=("subtree", interface_filter))
    root = reply.data_ele
    print(etree.tostring(root, pretty_print=True).decode())

Summary of subtree filter component types:

[Source: https://netdevops.me/2020/netconf-subtree-filtering-by-example/] [Source: https://www.rfc-editor.org/rfc/rfc6241]

Figure 4.3: Subtree Filter Component Types — Decision Logic

flowchart TD
    A([XML filter element\nencountered]) --> B{Has xmlns\nattribute?}
    B -->|Yes| C[Namespace Selection\nConstrains to specific\nYANG module]
    B -->|No| D{Has child\nelements?}
    C --> D
    D -->|Yes, with no text content| E[Containment Node\nNavigates deeper\ninto YANG tree]
    D -->|No — self-closing tag| F[Selection Node\nReturn this node\nand all descendants]
    D -->|Yes, with text value| G[Content Match Node\nEquality predicate:\nfilter list entries]
    E --> H{Children contain\nboth text and\nself-closing siblings?}
    H -->|Yes| I[Combined Filter\nContent match identifies entry\nSelection picks specific leaves]
    H -->|No| D

    style C fill:#1d3557,color:#fff
    style E fill:#457b9d,color:#fff
    style F fill:#2a9d8f,color:#fff
    style G fill:#e76f51,color:#fff
    style I fill:#6d6875,color:#fff

XPath Filtering

XPath filtering is more expressive than subtree filtering — it supports predicates, logical operators, string functions, and relative paths. However, it requires the device to advertise the urn:ietf:params:netconf:capability:xpath:1.0 capability and is not universally supported across all vendors and platforms.

The simplest form passes an XPath expression string as the criteria:

with manager.connect(**device) as m:
    reply = m.get(
        filter=("xpath",
                "//interfaces-state/interface[name='GigabitEthernet1']/oper-status")
    )
    print(reply.data_xml)

When working with YANG data (which uses XML namespaces), XPath expressions must be namespace-aware. ncclient supports a tuple form where you pass a namespace prefix dictionary alongside the expression:

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:
    reply = m.get_config(
        source="running",
        filter=("xpath", (ns_map, xpath_expr))
    )
    print(reply.data_xml)

Always check XPath capability before using it:

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")
    # ... XPath operations ...

[Source: https://learningnetwork.cisco.com/s/blogs/a0D6e000015LntKEAS/level-up-your-netconf-skills-smart-filtering-with-xpath-expressions] [Source: https://rayka-co.com/lesson/netconf-xpath-filter-example-for-get-command/]

Parsing RPC Replies with lxml

The data_ele attribute of a GetReply is a parsed lxml Element object — the root of the XML tree returned by the device. You can navigate it using standard lxml methods.

Using .find() with namespace maps:

ns = {"ios": "http://cisco.com/ns/yang/Cisco-IOS-XE-native"}

with manager.connect(**device) as m:
    filter_xml = """
<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
  <hostname/>
  <version/>
</native>"""
    reply = m.get_config(source="running", filter=("subtree", filter_xml))

hostname = reply.data.find(".//ios:hostname", namespaces=ns).text
version  = reply.data.find(".//ios:version",  namespaces=ns).text
print(f"Hostname : {hostname}")
print(f"Version  : {version}")

Using .xpath() to collect multiple values:

from lxml import etree

ns = {"if": "urn:ietf:params:xml:ns:yang:ietf-interfaces"}

with manager.connect(**device) as m:
    reply = m.get_config(source="running")

root = reply.data_ele
# Returns a list of text strings — all interface names
names = root.xpath("//if:interface/if:name/text()", namespaces=ns)
print(names)

Stripping namespaces for simpler ad-hoc queries (use with caution):

When prototyping or building exploratory scripts, stripping namespaces lets you write shorter XPath expressions without namespace prefixes. This is convenient but can return incorrect results if multiple YANG modules define elements with the same name:

from ncclient.xml_ import remove_namespaces

clean = remove_namespaces(reply.data_ele)
names = clean.xpath("//interface/name/text()")

Converting to a Python dictionary with xmltodict:

For teams more comfortable working with Python dicts than lxml trees, xmltodict provides a quick conversion:

import xmltodict

with manager.connect(**device) as m:
    reply = m.get_config(source="running", filter=("subtree", filter_xml))

conf_dict = xmltodict.parse(str(reply))
hostname = conf_dict['rpc-reply']['data']['native']['hostname']

[Source: https://deepwiki.com/ncclient/ncclient/3.4-xml-processing] [Source: https://github.com/ksator/python-training-for-network-engineers/blob/master/rpc-netconf-lxml-ncclient/ncclient.md]

Building Reusable Filter Templates

Rather than embedding XML strings directly in Python code, define filter templates as module-level constants or load them from files. This promotes reuse across scripts and makes filters easy to review and test in isolation:

# filters.py — reusable NETCONF filter definitions

HOSTNAME_FILTER = """
<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
  <hostname/>
</native>"""

INTERFACE_ALL_FILTER = """
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface/>
</interfaces>"""

def interface_by_name_filter(ifname: str) -> str:
    return f"""
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface>
    <name>{ifname}</name>
  </interface>
</interfaces>"""

Use these in your main scripts:

from filters import interface_by_name_filter

with manager.connect(**device) as m:
    reply = m.get_config(
        source="running",
        filter=("subtree", interface_by_name_filter("GigabitEthernet1"))
    )

[Source: https://github.com/CiscoDevNet/netconf-examples/blob/master/netconf-103/get_interfaces_csr1000V.py]

Key Takeaway: Always apply filters when retrieving configuration data — unfiltered get_config is a performance anti-pattern for production devices. Subtree filtering is universally supported and sufficient for most tasks; use XPath only when you need its advanced predicate logic and have verified the capability is available on the target device.

Section 4: Advanced ncclient Patterns

The Candidate Datastore Workflow

The candidate datastore is the recommended mechanism for all production NETCONF configuration changes on Cisco IOS XE. Think of it as a scratch pad: you make changes in isolation, verify them, and only promote them to the live running configuration when you are satisfied they are correct.

The analogy is a document editor’s “track changes” mode: edits accumulate without affecting the published version until you explicitly accept and apply them.

When the candidate datastore is enabled on IOS XE, the writable-running capability is automatically disabled. All configuration changes must go through the candidate workflow — you cannot edit_config directly to running while candidate is enabled.

Enable: netconf-yang feature candidate-datastore
Effect: writable-running disabled; all writes must use candidate → commit

The minimal candidate workflow is:

edit_config(candidate) → commit()

The production-grade workflow adds locking and validation:

lock(candidate) → edit_config(candidate) → validate(candidate) → commit() → unlock(candidate)

[Source: https://pynet.twb-tech.com/blog/netconf/iosxe-candidate-cfg1.html] [Source: https://www.cisco.com/c/en/us/support/docs/storage-networking/management/200933-YANG-NETCONF-Configuration-Validation.html]

Figure 4.4: Candidate Datastore Workflow — Minimal vs. Production-Grade

flowchart TD
    A([Start]) --> B[lock candidate datastore]
    B --> C[edit_config to candidate]
    C --> D{validate candidate\nagainst YANG models}
    D -->|Validation fails| E[discard_changes\nrestore candidate from running]
    E --> F([Unlock & Abort])
    D -->|Validation passes| G[commit confirmed=True\napply to running\nstart rollback timer]
    G --> H{Verify running config\nmatches intent}
    H -->|Verification fails| I[Let timer expire\nor discard_changes]
    I --> J([Auto-rollback restores\nprevious running config])
    H -->|Verification passes| K[commit confirming\ncancels rollback timer]
    K --> L[dispatch save-config\npersist to startup]
    L --> M[unlock candidate]
    M --> N([Success])

    style A fill:#2d6a4f,color:#fff
    style N fill:#2d6a4f,color:#fff
    style F fill:#9b2226,color:#fff
    style J fill:#9b2226,color:#fff
    style E fill:#ae2012,color:#fff
    style I fill:#ae2012,color:#fff

Pre-commit Validation

validate(source) sends a <validate> RPC that instructs the device to check the specified datastore against all loaded YANG models. Validation catches problems before they affect the running configuration:

• XML schema conformance (correct element names, hierarchy, data types)
• YANG semantic constraints (must and when statements)
• Cross-reference consistency (references to non-existent objects)

reply = m.validate(source="candidate")
# <ok/> reply: validation passed
# RPCError raised: validation failed, inspect e.tag and e.message

If validation fails, the candidate is left intact — you can correct the error and re-validate without starting over. Only call discard_changes() if you want to abandon the staged edits entirely.

Discard Changes

discard_changes() sends a <discard-changes> RPC that resets the candidate datastore to an exact copy of the current running configuration. This is the NETCONF equivalent of “undo all changes” — it abandons everything staged in the candidate without touching running.

try:
    m.edit_config(target="candidate", config=config_xml)
    m.validate(source="candidate")
    m.commit()
except Exception:
    m.discard_changes()   # abandon staged changes, restore candidate from running
    raise

Confirmed Commit

A confirmed commit is a safety mechanism designed for remote configuration changes. When you use commit(confirmed=True, confirm_timeout=N), the device applies the candidate to running but starts a countdown timer. If you do not send a second unconditional commit() before the timer expires, the device automatically rolls back to the pre-commit running configuration.

This is invaluable when making changes to remote devices over the network being configured. If your change accidentally disrupts connectivity and you can no longer reach the device, the automatic rollback restores access after the timeout.

# Stage the change
m.edit_config(target="candidate", config=config_xml)
m.validate(source="candidate")

# Apply with 120-second auto-rollback window
m.commit(confirmed=True, confirm_timeout=120)

# --- Verify the change is working correctly ---
reply = m.get_config(source="running", filter=("subtree", verify_filter))
# ... inspect reply ...

# Confirm: cancels the rollback timer and makes the change permanent
m.commit()