Theoretical foundations and architecture

Modern operator network management relies on programmatic interfaces (APIs) instead of typing CLI commands by hand and parsing text output (screen scraping). The protocols used are NETCONF (RFC 6241) and gNMI (gRPC Network Management Interface). 1. NETCONF runs over SSH (port 830 per IANA, RFC 6242) and carries XML RPC messages: <get-config>, <edit-config>, <lock>, <validate>, <commit>, <discard-changes>. Transactional behaviour depends on the device capabilities: on platforms with a candidate datastore changes accumulate and are applied by <commit> (and <commit><confirmed/> reverts them on a timer), while with :writable-running and no :rollback-on-error part of the changes can stay applied. The claim that a router "always rolls back by itself" is wrong. 2. Data modelling: both NETCONF and gNMI use the YANG language (RFC 7950 for version 1.1). Models are standard (IETF, OpenConfig) or vendor-specific (native); PE configuration is usually written against the native model of a verified platform, while state is read through OpenConfig. 3. gNMI was developed by the OpenConfig community on top of gRPC/HTTP/2 with Protocol Buffers encoding and offers the RPCs Capabilities, Get, Set and Subscribe. Set is applied as a single transaction (all or nothing) and Subscribe provides streaming telemetry; IANA registered port 9339 for gNMI, but vendor-specific ports are common in practice, so take the port from the device configuration.

What is standardized and what is not

A programmable interface consists of three independent layers: transport (SSH, or HTTP/2 with TLS), the operations protocol (NETCONF RPC or gNMI RPC) and the data model written in YANG. Each layer can be replaced separately: the same YANG model is served over both NETCONF and gNMI, and the same NETCONF works with models from different vendors. This matters for L3VPN: transport and operations are portable, but the content (the VRF, RD, RT and BGP vpnv4 tree) looks different on Cisco, Huawei and Juniper as long as you use native models.

NETCONF: session, capabilities, datastores

NETCONF (RFC 6241) runs as an SSH subsystem. Port 830 is assigned by IANA to netconf-ssh (RFC 6242), and many platforms additionally accept the netconf subsystem on port 22. After the SSH session is up, each side sends a <hello> with its list of capabilities and the base version: urn:ietf:params:netconf:base:1.0 or base:1.1. If both sides support 1.1, chunked framing is used; in 1.0 messages are delimited by the sequence ]]>]]>. This is why home-made clients on a raw socket break, while ncclient, the Ansible NETCONF clients and scrapli-netconf work.

Capabilities define what you can do with the device:

  • :candidate - a separate candidate datastore exists; changes accumulate and are applied by <commit>.
  • :writable-running - <edit-config> is allowed directly on running; no commit is needed and every operation takes effect immediately.
  • :confirmed-commit - <commit><confirmed/> with a timeout (600 seconds by default): if a second <commit> does not arrive in time, the device rolls back by itself.
  • :validate - the <validate> operation checks the candidate without applying it.
  • :rollback-on-error - if one element of an <edit-config> fails, the whole request is rolled back.
  • :startup, :xpath, :url - startup datastore, XPath filters, configuration from a URL.

Cisco IOS-XE exposes only running by default, and candidate is enabled with netconf-yang feature candidate-datastore (after that, CLI configuration is blocked until the feature is disabled). Junos always works with a candidate. On Huawei VRP the set depends on the software version; read the capabilities in <hello> rather than the documentation.

Operations and edit-config semantics

  • <get> reads configuration and operational state, <get-config> reads only the configuration of the selected datastore. A filter is given as a subtree or as XPath.
  • <edit-config> changes a datastore. The operation attribute on an element accepts merge (default), replace, create (error if it exists), delete (error if it is absent) and remove (no error). The default-operation element sets the behavior for the whole request. A classic mistake is replace on a top-level container: it removes every sibling you did not list.
  • <lock>/<unlock> lock a datastore for the duration of a transaction; a foreign session gets lock-denied. <kill-session> removes a stuck session.
  • <validate>, <commit> and <discard-changes> work on the candidate. <copy-config> and <delete-config> operate on whole datastores.

Atomicity is not always guaranteed. <edit-config> is atomic for a single request if :rollback-on-error exists or the candidate commit itself rolls back a failure. The claim that the router "always rolls back by itself" is wrong: with :writable-running and no rollback-on-error, half of the changes stay.

A minimal safe cycle on a candidate platform:

xml
<!-- lock, edit candidate, validate, confirmed commit, final commit -->
<lock><target><candidate/></target></lock>
<edit-config><target><candidate/></target><config>...</config></edit-config>
<validate><source><candidate/></source></validate>
<commit><confirmed/><confirm-timeout>120</confirm-timeout></commit>
<commit/>
<unlock><target><candidate/></target></unlock>

If connectivity to the controller is lost after the confirmed commit, the final <commit> never arrives and after 120 seconds the PE restores the previous configuration.

YANG: native, IETF, OpenConfig

YANG (RFC 7950 for version 1.1, RFC 6020 for 1.0) describes a tree of container, list with keys, leaf, leaf-list, choice, types, must/when constraints and identity. A module is versioned by a revision (revision 2023-07-01), extended with augment and adjusted by the vendor with deviation. Three families of models:

  • Native (Cisco-IOS-XE-native, huawei-*, junos-conf-root) mirror the vendor CLI, cover everything, but are not portable between platforms.
  • IETF (ietf-interfaces RFC 8343, ietf-routing, ietf-bgp) are standardized, but vendor coverage is partial.
  • OpenConfig (openconfig-interfaces, openconfig-network-instance, openconfig-bgp) are written by operators. VRFs and L3VPN are described in network-instance with type L3VRF, the RD lives in config/route-distinguisher, and RTs are set through inter-instance-policies and import policies. L3VPN coverage is uneven across vendors, so for a PE the native model is usually used for configuration and OpenConfig only for telemetry (interfaces, BGP neighbors).

A practical rule: write PE configuration with the native model of the platform you have verified, and read state with OpenConfig.