Protocol Atlas

MGMT · management · draft

NETCONF

Network Configuration Protocol

RPC operations over a secure session against configuration datastores — candidate, running, and optional startup — with locks and confirmed commit.

Presenter modeEmbed this figure

IntroductionRFC 6241 · PROPOSED STANDARD · June 2011Configuration DatastoresRFC 6241 · PROPOSED STANDARD · June 2011Protocol OperationsRFC 6241 · PROPOSED STANDARD · June 2011Confirmed Commit CapabilityRFC 6241 · PROPOSED STANDARD · June 2011

Why it exists

CLI scraping does not give transactional, machine-readable configuration across vendors. NETCONF standardizes datastore RPCs over a secure session. IntroductionRFC 6241 · PROPOSED STANDARD · June 2011

NETCONF is the write (and read) path for configuration. Streaming telemetry is a separate subscription model that often reuses YANG but is not a substitute for <edit-config>. Protocol OperationsRFC 6241 · PROPOSED STANDARD · June 2011

Edit candidate, then commit to running

With :candidate, edits land in the candidate datastore. <commit> copies validated candidate into running. Skipping the commit leaves running unchanged.

NETCONF clientDevice · datastoresAdvertise capabilities
  • Link
  • Blocking
  • Packet in flight
  • Discarded
  • Emphasis
Select a device to read its state. Arrow keys walk the topology.
Text equivalent of this diagram
Devices and links at this step
ElementKindState
NETCONF clienthost—
Device · datastoresrouter—
NETCONF client — Device · datastoreslinkup
1 / 3

Session starts with <hello> exchanging capabilities. The client learns whether :candidate, :confirmed-commit, and specific YANG modules are advertised.

What changed

  • <hello>: NETCONF client → Device · datastores
  • <hello> · caps: Device · datastores → NETCONF client
  • Advertise capabilities

How it works

A session begins with capability exchange. Each side advertises protocol features and YANG modules it supports. Capabilities ExchangeRFC 6241 · PROPOSED STANDARD · June 2011

Configuration lives in datastores. :candidate stages edits; <commit> applies them to running. :writable-running edits running directly when advertised. Configuration DatastoresRFC 6241 · PROPOSED STANDARD · June 2011

Locks serialize conflicting editors. Confirmed commit applies with an automatic revert unless confirmed — useful when a change can sever management access. Confirmed Commit CapabilityRFC 6241 · PROPOSED STANDARD · June 2011

Content is modeled in YANG; NETCONF carries the RPC framing and datastore semantics. Wrong module revisions look like “NETCONF is broken.” TerminologyRFC 6241 · PROPOSED STANDARD · June 2011

On the wire

Constructed examples, encoded from the field table below them — not captured traffic.

A BGP session’s first segment: SYN set, ACK clear, data offset 5, destination port 179.

TCP
Options, if any, follow this header and are covered by the data offset. RFC 9293

Configure it

Enable NETCONF/YANG with AAA so clients can edit candidate and commit.

Cisco IOS-XE 17.12 · Catalyst 9300, Catalyst 8000draft

  1. netconf-yang
netconf-yang feature candidate-datastore

    Enable NETCONF and advertise candidate where supported so <edit-config> can stage before <commit>.

    Common mistake: Assuming :candidate without checking server <hello> capabilities on the session.

    RFC 6241 §5.1

  2. aaa new-model
aaa authentication login default local
aaa authorization exec default local
username netconf privilege 15 secret <configured out of band>
ip ssh version 2

    NETCONF over SSH needs an authorized operator. Use out-of-band secrets — never commit real passwords.

    Common mistake: Leaving a shared lab password in the repository or golden configs.

    Cisco IOS XE — NETCONF and RESTCONF §NETCONF

Verify

show netconf-yang status
NETCONF enabled; listen sockets present.
show netconf-yang sessions
Active client sessions after connect.

Caveats

  • Marked draft: feature names and candidate support differ by IOS-XE train.
  • Placeholder secrets only — never commit real credentials.

When it breaks

Symptom first, because that is what you have when it happens.

  1. Client reports edit success but the box still has old behavior.

    Narrow it down

    1. Check whether the edit targeted candidate without a subsequent <commit>.
    2. Compare <get-config> of candidate versus running.

    Cause

    Edits remained in candidate and were never committed.

    Fix

    Commit (or discard) explicitly; verify running after apply.

    <commit>RFC 6241 · PROPOSED STANDARD · June 2011

  2. A change appears then silently reverts minutes later.

    Narrow it down

    1. Look for a confirmed commit without a confirming commit.
    2. Check the configured confirm timeout.

    Cause

    Confirmed commit timer expired and restored prior configuration.

    Fix

    Issue the confirming commit while reachable, or use confirmed commit intentionally for risky changes.

    Confirmed Commit CapabilityRFC 6241 · PROPOSED STANDARD · June 2011

  3. RPCs fail with operation-not-supported or unknown-element.

    Narrow it down

    1. Diff client assumptions against server <hello> capabilities.
    2. Confirm YANG module revisions on both sides.

    Cause

    Client invoked an optional capability or module the server did not advertise.

    Fix

    Adapt the workflow to advertised capabilities; upgrade platform or models if required.

    Capabilities ExchangeRFC 6241 · PROPOSED STANDARD · June 2011

  4. Edits fail because the datastore is locked.

    Narrow it down

    1. Identify which session holds <lock>.
    2. Check for abandoned automation sessions.

    Cause

    Another client holds a lock on the target datastore.

    Fix

    Wait, unlock from the owning session, or use partial-lock patterns where supported.

    <lock>RFC 6241 · PROPOSED STANDARD · June 2011

  5. TCP connects but the NETCONF session never starts.

    Narrow it down

    1. Verify SSH/user credentials and subsystem configuration.
    2. Confirm NETCONF is enabled on the management VRF/source.

    Cause

    Secure transport or subsystem setup failed before <hello>.

    Fix

    Fix AAA and NETCONF enablement; match source interface and ACL.

    Cisco IOS XE — NETCONF and RESTCONF §NETCONF

Design notes

Never assume :candidate or :confirmed-commit. Branch on hello capabilities every session.

Transport is typically SSH (RFC 6242) or another secure stream. TCP alone is not the NETCONF security story. Transport Protocol RequirementsRFC 6241 · PROPOSED STANDARD · June 2011

Misconceptions

“<edit-config> always changes the live device immediately.”
When using :candidate, edits stage until <commit>. Running changes only after a successful apply path. Configuration DatastoresRFC 6241 · PROPOSED STANDARD · June 2011
“Streaming telemetry replaces NETCONF for configuration.”
Telemetry subscriptions observe state. Configuration writes remain NETCONF/RESTCONF (or vendor equivalents), not YANG-Push alone. Protocol OperationsRFC 6241 · PROPOSED STANDARD · June 2011
“Capability exchange is informational only.”
Optional features such as :candidate and :confirmed-commit are valid only when advertised. Ignoring hello causes hard failures. Capabilities ExchangeRFC 6241 · PROPOSED STANDARD · June 2011

More walkthroughs

Confirmed commit rolls back without confirmationdesign-choice

A confirmed commit applies changes but reverts unless a confirming commit arrives before the timeout — a safety rail for remote changes that can cut management reachability.

OperatorDeviceRevert timer armedrunning: provisionalMgmt path at risk
  • Link
  • Blocking
  • Packet in flight
  • Discarded
  • Emphasis
Select a device to read its state. Arrow keys walk the topology.
Text equivalent of this diagram
Devices and links at this step
ElementKindState
Operatorhost—
Devicerouterrunning: provisional
Mgmt path at riskzone—
Operator — Devicelinkup
Device — Mgmt path at risklinkup
1 / 3

The client issues <commit> with a confirmed parameter and timeout. The server applies the candidate but arms an automatic revert timer.

What changed

  • <commit confirmed>: Operator → Device
  • Revert timer armed
  • Device: running → provisional

Client assumes a capability the server did not advertisefailure

Operations such as :candidate or :confirmed-commit are optional capabilities. Invoking them without a matching hello advertisement fails or falls back incorrectly.

Client · assumes candidateIgnores helloServer · running-only
  • Link
  • Blocking
  • Packet in flight
  • Discarded
  • Emphasis
Select a device to read its state. Arrow keys walk the topology.
Text equivalent of this diagram
Devices and links at this step
ElementKindState
Client · assumes candidatehost—
Server · running-onlyrouter—
Client · assumes candidate — Server · running-onlylinkup
1 / 3

Server hello omits :candidate. The client still targets candidate in <edit-config> because its library defaults to that workflow.

What changed

  • <hello> · no :candidate: Server · running-only → Client · assumes candidate
  • Ignores hello

Check yourself

  • What does editing the candidate datastore require before forwarding changes?
  • What does a confirmed commit do if never confirmed?
  • Where does a client learn whether :candidate is available?
  • What is the purpose of <lock>?
  • How does YANG relate to NETCONF?
  • Why prefer NETCONF over CLI scraping for automation?
  • Which operation stages configuration into the candidate?
  • What does RFC 6241 require of the NETCONF transport?