NETCONF Protocol

Objective

In this lesson you will learn how to enable and use the NETCONF protocol on an IOS XE device over SSH, and how to perform the core NETCONF operations: <get>, <get-config>, <edit-config>, <lock>, and <commit>. This matters in production because NETCONF provides a standardized, transactional mechanism to automate device configuration and retrieval — critical for consistent, auditable changes across many devices. In the real world, NETCONF is used by orchestration tools (or ad-hoc scripts) to push configuration changes safely (using candidate/commit) and to retrieve structured running or startup configuration for verification.

Quick Recap

Refer to the topology used in Lesson 1 for the physical/logical layout and IP addressing. This lesson does not add any new routers or interfaces to the topology; we will use the existing management plane to configure NETCONF on the IOS XE device and demonstrate client connections from a management host.

Tip: All examples use the domain lab.nhprep.com and the password Lab@123 for local accounts, per lab rules.

Key Concepts (theory and behavior)

• NETCONF over SSH (transport): NETCONF typically runs over SSH (default port 830). SSH provides secure authentication and an encrypted channel. NETCONF exchanges XML RPC messages in this SSH session. In IOS XE the NETCONF agent uses the netconf-yang agent/SSH transport to accept NETCONF sessions.
  • In production: this ensures encryption and uses existing management-plane access controls.
• Datastores and operations: NETCONF exposes datastores such as running, startup and (on supporting devices) candidate. Typical operations:
  • <get>: read operational/state data
  • <get-config>: read configuration data from a specified datastore
  • <edit-config>: modify a configuration (can be against running or candidate)
  • <lock> / <unlock> and <commit>: when using a candidate datastore, you lock it, edit-config the candidate, then commit to make changes active — this provides transactional safety.
  • In IOS XE: using candidate + commit prevents partial changes from applying unless explicitly committed.
• Session behavior and lifecycle: NETCONF sessions are stateful. A client opens a session (SSH subsystem netconf), exchanges capabilities, and then issues RPCs. Tools (YANG Suite, Ansible NETCONF modules) often keep sessions open to perform multiple RPCs — closing the session terminates the interaction.
• Atomicity and safety: Using candidate and commit (with lock) gives you the ability to stage multiple edits and apply them atomically. Failing to use candidate mode risks partial configuration if an edit partially succeeds.

Step-by-step configuration

Step 1: Create a local management account and enable SSH

What we are doing: Create a local user for NETCONF clients and ensure SSH v2 is available for NETCONF transport. NETCONF uses SSH for secure connections, so the device must have SSH and a user that can authenticate.

configure terminal
 username netconf privilege 15 secret Lab@123
 ip domain-name lab.nhprep.com
 crypto key generate rsa modulus 2048
 ip ssh version 2
 line vty 0 4
  transport input ssh
  login local
 exit
end

What just happened:

• username netconf ... creates a local administrative user used by NETCONF clients to authenticate.
• ip domain-name and crypto key generate rsa create the host keys necessary for SSH public-key operations; without keys, SSH will not start securely.
• ip ssh version 2 forces SSHv2 (required by many NETCONF clients).
• The line vty stanza restricts VTY access to SSH and uses local authentication. This ensures NETCONF sessions that rely on SSH authentication will be able to log in.

Real-world note: In production you would normally integrate with an AAA server (TACACS+/RADIUS) rather than using local accounts, but local accounts are fine for lab and small deployments.

Verify:

show running-config | section username
username netconf privilege 15 secret 5 $1$abc$EXAMPLEHASH

show ip ssh
SSH Enabled - version 2.0
Authentication timeout: 120 secs; Authentication retries: 3

Step 2: Enable the NETCONF agent over SSH

What we are doing: Enable the device's NETCONF-YANG agent to accept NETCONF sessions over SSH. This advertises NETCONF capabilities and opens the NETCONF subsystem (default port 830) for clients.

configure terminal
 netconf-yang agent ssh
end

What just happened:

• netconf-yang agent ssh starts the NETCONF agent and binds the NETCONF subsystem over SSH. Clients connecting to the device using NETCONF over SSH will now be able to open a NETCONF session and exchange capabilities (YANG models and operational capabilities).

Real-world note: The netconf-yang phrasing emphasizes YANG-based NETCONF data models — in production this is how model-driven management is performed.

Verify:

show netconf-yang sessions
Session ID : 101
User       : netconf
Transport  : SSH
Client IP  : 192.0.2.10
Mode       : <running,candidate,base:1.0>

show running-config | include netconf-yang
 netconf-yang agent ssh

Step 3: Establish a NETCONF session (client-side example) and perform a RPC

What we are doing: From a management host, open a NETCONF-over-SSH session and perform a <get> to retrieve device state. This demonstrates how NETCONF returns structured device data (XML) over an SSH session.

Client-side (management host) example — open NETCONF subsystem over SSH. Replace 192.0.2.1 with your device management IP if different:

ssh -p 830 -s netconf@192.0.2.1

When connected, the client sends an XML <hello/> and the server replies with capabilities. Then the client sends a <get> RPC:

Example <get> RPC (send over the SSH NETCONF session):

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get>
    <filter type="subtree">
      <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
        <hostname/>
        <interface/>
      </native>
    </filter>
  </get>
</rpc>

Expected server reply (abridged to show format — full replies are XML with the requested data):

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <data>
    <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
      <hostname>rtr1</hostname>
      <interface>
        <GigabitEthernet>
          <name>0/0/0</name>
          <description>Uplink</description>
          <ip>
            <address>
              <primary>
                <address>10.0.0.1</address>
                <mask>255.255.255.0</mask>
              </primary>
            </address>
          </ip>
        </GigabitEthernet>
      </interface>
    </native>
  </data>
</rpc-reply>

What just happened:

• The SSH command with subsystem netconf opened a NETCONF session on port 830.
• The <get> RPC requested the native YANG subtree for hostname and interfaces; the device responded with an XML <rpc-reply> containing the requested data. This structured response is easy for programmatic parsers to consume.

Real-world note: Tools like YANG Suite or orchestration systems will send similar RPCs programmatically; the XML structure maps to YANG models which drives automation workflows.

Verify (device-side):

show netconf-yang sessions
Session ID : 101
User       : netconf
Transport  : SSH
Client IP  : 192.0.2.10
Last RPC   : <get>

Step 4: Edit configuration safely using candidate, lock, edit-config, commit

What we are doing: Demonstrate a safe configuration change using the candidate datastore: lock candidate, push an <edit-config> to change the hostname, and then <commit> to apply. This sequence prevents partial or accidental changes.

Client-side RPC sequence (over NETCONF session):

1. Lock the candidate datastore:

<rpc message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <lock><target><candidate/></target></lock>
</rpc>

Expected reply:

<rpc-reply message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

2. Edit the candidate with new hostname:

<rpc message-id="103" 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">
        <hostname>rtr1-netconf</hostname>
      </native>
    </config>
  </edit-config>
</rpc>

Expected reply:

<rpc-reply message-id="103" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

3. Commit the candidate to make changes active:

<rpc message-id="104" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <commit/>
</rpc>

Expected reply:

<rpc-reply message-id="104" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

What just happened:

• lock reserved the candidate datastore so no other client could modify it concurrently.
• edit-config changed the candidate copy but did not affect running state yet.
• commit applied the candidate changes atomically to the running configuration — ensuring either the full change is applied or it is not applied at all.

Real-world note: This pattern is critical for multi-step configuration changes (for example, introducing a new routing protocol or changing interface addressing) where partial application could cause outages.

Verify:

show running-config | include hostname
hostname rtr1-netconf

show netconf-yang sessions
Session ID : 101
User       : netconf
Transport  : SSH
Client IP  : 192.0.2.10
Last RPC   : <commit>

Step 5: Unlock and gracefully close the NETCONF session

What we are doing: Unlock the candidate datastore (if still locked) and close the NETCONF session correctly. Proper session teardown avoids stale locks and ensures other management processes can proceed.

Client RPC to unlock:

<rpc message-id="105" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <unlock><target><candidate/></target></unlock>
</rpc>

Expected reply:

<rpc-reply message-id="105" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

Then exit the SSH netconf subsystem:

# On the client shell that opened NETCONF via SSH, type EOF or close the SSH session
exit

What just happened:

• Unlock removes the lock on candidate so other management sessions can edit.
• Closing the SSH session terminates the NETCONF session and cleans up server-side session state.

Warning: Leaving candidate locked (or leaving stale NETCONF sessions) can block other automation workflows — always unlock or ensure session termination.

Verify:

show netconf-yang sessions
No NETCONF-YANG sessions found

Verification Checklist

• Check 1: NETCONF agent enabled — verify show running-config | include netconf-yang shows netconf-yang agent ssh.
• Check 2: Able to open NETCONF-over-SSH session — verify show netconf-yang sessions lists the client and last RPC.
• Check 3: Configuration changes applied via candidate+commit — verify show running-config | include hostname reflects the new hostname.
• Check 4: No stale locks or sessions — verify show netconf-yang sessions returns no stuck sessions once client closed and unlock completed.

Common Mistakes

Symptom	Cause	Fix
NETCONF client cannot connect on port 830	NETCONF agent not enabled or SSH not configured	Enable SSH (ip ssh version 2, generate RSA key) and netconf-yang agent ssh
NETCONF session shows as authenticated but <get> RPC fails	Incorrect XML filter or unsupported YANG model name	Verify the correct YANG model namespace and test a broad <get> before using filters
Edits not visible in running-config after edit-config	Edits were applied to candidate but not committed	Perform <commit/> to apply candidate to running, or target running directly (less safe)
Other clients cannot edit while you edit	Candidate datastore locked by another NETCONF session	unlock the candidate or close the session that holds the lock; use show netconf-yang sessions to find the lock holder

Key Takeaways

• NETCONF runs over SSH (default port 830) and exchanges XML RPCs that map to YANG datastores — enabling structured, programmatic device management.
• Use candidate + lock + edit-config + commit to make atomic, safe changes; this avoids partial-change problems in production.
• Always ensure SSH, domain name, and keys exist before enabling NETCONF; without SSH transport, NETCONF cannot operate.
• In production, integrate NETCONF authentication with AAA and use proper tooling (YANG Suite, Ansible modules) to manage sessions and handle capabilities negotiation.

Final real-world insight: NETCONF is a building block for automation. In small labs you might run single RPCs manually, but in data centers and enterprise deployments NETCONF sessions are orchestrated by controllers and CI/CD pipelines that rely on the transactional safety NETCONF provides.