11.2 NETCONF Protocol & Cisco IOS-XE Wireless YANG Data Models
Key Takeaways
- YANG defines the schema, data types, constraints, and operations; NETCONF is the protocol that manipulates YANG-modeled data over a secure transport, normally SSH TCP 830.
- NETCONF exchanges XML RPC messages and begins with a capabilities exchange so clients can discover supported base versions, models, datastores, and optional features.
- Base 1.0 uses an end-of-message delimiter, while Base 1.1 uses chunked framing; negotiated framing is a transport boundary mechanism, not permission to place illegal XML text in a field.
- Candidate and startup datastores are capability-dependent; automation must inspect server capabilities instead of assuming every datastore and operation exists.
- A safe edit workflow locks where appropriate, retrieves current configuration, applies a validated edit, checks RPC errors, commits if required, verifies, and unlocks.
11.2 NETCONF and Cisco IOS XE Wireless YANG Models
NETCONF and YANG solve different parts of automation. YANG is a modeling language: it defines containers, lists, leaves, types, keys, constraints, configuration data, operational state, notifications, and RPCs. NETCONF is a protocol: it carries operations such as get, get-config, edit-config, lock, commit, and action/RPC requests between client and server.
On Catalyst 9800, NETCONF normally runs over SSH on TCP 830. SSH supplies confidentiality, integrity, user authentication, and server host-key authentication. The XML payload is structured according to IETF and Cisco YANG modules.
Session establishment and capabilities
After SSH authentication, client and server exchange hello messages. Each advertises capabilities. The client must read them before choosing operations. Important examples include:
- NETCONF base 1.0 or 1.1
- writable-running support
- candidate datastore support
- confirmed-commit support
- startup datastore support
- XPath filtering support
- YANG module names, namespaces, and revisions
Capabilities prevent assumptions. A candidate workflow is valid only when the server advertises candidate. A startup copy is meaningful only when the relevant datastore and capability exist on that release and platform.
Message framing
NETCONF base 1.0 terminates a message with the delimiter ]]>]]>. Base 1.1 uses chunked framing, in which length markers delimit one or more chunks followed by an end marker. Peers select behavior through the hello negotiation.
The benefit of base 1.1 is unambiguous protocol framing and efficient handling of message streams. It is misleading to say that an ordinary AP description containing the literal delimiter is the expected cause: well-formed XML character data cannot legally contain the sequence ]]> as normal text. A client should use a conforming XML library and the framing negotiated for the session, not concatenate raw strings.
Read operations and filters
A get-config operation reads configuration from a named datastore. A get operation can retrieve configuration and operational state. A subtree or XPath filter limits the reply and reduces controller work and network transfer.
<filter xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" type="subtree">
<wlan-cfg-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-wireless-wlan-cfg"/>
</filter>
Namespaces are not decorative. The same local element name in two modules can mean different data. Always use the namespace and structure defined by the module revision supported on the device.
Edit operations
An edit-config request selects a target datastore and supplies configuration. The default operation may merge data, while per-element operations can create, merge, replace, or delete. Their semantics matter:
- merge changes supplied nodes and preserves unspecified siblings.
- replace replaces the target node’s configuration with the supplied content.
- create fails if the target already exists.
- delete fails if the target does not exist; remove is tolerant of absence where supported by the base semantics.
Do not use replace when the intent is to change one leaf unless the complete replacement object is deliberate and validated.
A candidate-capable workflow can isolate changes:
- Confirm the candidate and commit capabilities.
- Lock the target datastore if the operational policy permits it.
- Copy or otherwise synchronize the candidate with the intended baseline as required by the platform workflow.
- Apply a small edit to candidate.
- Validate if the capability is available.
- Commit, or use confirmed commit with a safe confirmation and rollback plan when supported.
- Read the state back and unlock.
On a writable-running-only device, target running and account for the fact that the change can take effect immediately. NETCONF is transactional at the protocol/datastore level; it does not make a service-impacting configuration harmless.
Interpreting replies
A successful request returns an OK element or requested data. A failure returns one or more RPC error elements. Inspect error type, tag, severity, path, and message. Common causes include a wrong namespace, missing list key, invalid value, unsupported operation, lock conflict, or authorization failure.
The message ID correlates each reply to its RPC. An asynchronous client must not assume replies arrive in the same order as application requests without using that identifier.
YANG tooling and data validation
Retrieve or obtain the exact module revision supported by the controller. Tools such as YANG Suite, pyang, and model-driven API explorers help identify paths and constraints. Native models usually expose Cisco features in more detail; OpenConfig models can improve portability when the required function is represented. “Standards-based” does not mean two models have identical paths or behavior.
Before a write, validate required list keys, leaf types, ranges, enumerations, and dependencies. After a write, query both configuration and relevant operational state. A WLAN may exist in configuration yet fail to advertise because its policy, tag assignment, radio state, or security dependency is wrong.
Security and operations
Use SSH host-key verification and least-privilege accounts. Limit NETCONF reachability to management networks. Do not log credentials or complete sensitive XML. Coordinate locks to avoid blocking other automation. Keep a change record and a recovery path. The strongest NETCONF workflow is capability-driven, namespace-correct, minimally scoped, and verified after commit.
Why does NETCONF base 1.1 use chunked framing?
A script wants to edit candidate and issue commit. What must it do first?
Which operation is safest for changing one modeled leaf while preserving unspecified siblings?
What does an RPC error path help identify?