NETCONF XML Management Protocol

Traditional network device configuration management methods, such as CLI (Command Line Interface) and SNMP (Simple Network Management Protocol), have various limitations in handling complex network environments. To address these challenges, the IETF standardized NETCONF (Network Configuration Protocol) based on RFC 3535.

NETCONF is a network configuration management protocol defined by IETF RFC standards, designed to replace SNMP. It provides a standardized mechanism for installing, manipulating, and deleting network device configurations, offering more powerful capabilities and flexibility than traditional methods. NETCONF uses XML-based data encoding and supports structured configuration operations, making network management more efficient and reliable.

The core advantages of NETCONF include: clear separation between configuration data and operational state data, support for transaction-based configuration operations with rollback capabilities, use of XML as the data encoding format, and support for YANG (Yet Another Next Generation) data modeling language. YANG models define the structure and constraints of NETCONF protocol data, providing a standardized way to describe network device configurations and state information.

Additionally, NETCONF supports event notification mechanisms defined in RFC 5277, allowing network devices to actively push status change events to management systems, enabling real-time network monitoring and management.

This white paper provides a detailed introduction to the working principles, protocol structure, and typical application scenarios of NETCONF, helping readers comprehensively understand and apply this important network management technology.

NETCONF uses XML-based encoding, with four basic components: tags, elements, content, and attributes.

Key Terminology:

• Client: Initiates operation requests to the Server, or subscribes to messages and receives notifications from the Server. This may be a script or part of a network management application.
• Server: Executes the operation requests initiated by the Client or sends notifications to the Client. This is typically a network device.
• Capability: Optional features that supplement the basic NETCONF specification. The protocol defines various standard capabilities, and the table below lists some common ones:

Table 1: NETCONF Capability List

The Server may or may not support these Capabilities, and the Client can query the Server’s supported Capabilities before initiating business requests.

• Session: The Client and Server exchange messages via a secure, connection-oriented session.
• Message: An XML document defined by the protocol standard and transmitted within a Session.
• RPC (Remote Procedure Call): In NETCONF, an RPC is realized by exchanging the <rpc> request and <rpc-reply> response messages.
• Configuration: Data Data required to adjust the device state from its initial condition to the desired operational state. The core characteristic is that this data is writable.
• State Data: Data on the device that is readable but not configurable, such as read-only system status information and statistics.
• Datastore: A conceptual repository for storing and accessing information. The specific carrier may be a file, database, memory, or a combination thereof.
• Configuration Datastore: A datastore that holds a complete set of configuration data. The protocol defines multiple Configuration Datastores and allows devices to support them to varying extents, including but not limited to:

• • Running Configuration Datastore (<running>): The datastore that holds the device’s currently active and complete configuration. <running> always exists. If <running> is writable, the device must declare support for the Writable-Running Capability.
    
  • Startup Configuration Datastore (<startup>): Stores the configuration that will be loaded when the device boots. Some devices may integrate <startup> with <running>. If a device has an independent <startup>, it must declare support for the Distinct Startup Capability.
    
  • Candidate Configuration Datastore (<candidate>): An optional configuration datastore where the stored configuration data does not affect the device’s current running state and can be committed to <running>. If a device supports <candidate>, it must declare support for the Candidate Configuration Capability.

Corresponding to the Configuration Datastores is the Operational State Datastore (abbreviated as <operational>), which stores the device’s complete run-time state data.
RFC 8342 provides a complete description of this, and the relationship between these datastores is shown in the figure below:

NETCONF follows a client-server architecture with a typical workflow as illustrated below:

The NETCONF protocol is logically divided into four distinct layers: Content Layer, Operations Layer, Message Layer, and Secure Transport Layer.

Data above the Secure Transport Layer is XML-encoded, which is why many NETCONF elements are concisely referred to by their XML start tags.
The Content Layer refers to the specific data and models manipulated by the Operations Layer. This content is outside the scope of the NETCONF protocol standard; readers should consult relevant standards, particularly RFC 7950, for the YANG data modeling language.
YANG (Yet Another Next Generation) is a standardized modeling language used to define network device data and operations.

• Function: It provides a strict schema (data hierarchy, constraints, and operations) for a network device’s configuration and state data.
• Significance: It is the core foundation for achieving network configuration automation and programmability.
• Encoding: YANG models are machine-readable and human-friendly, and the resulting data can be encoded in XML or JSON.

The NETCONF protocol does not strictly mandate a specific transport layer protocol between the Client and the Server; any transport protocol meeting the following requirements may be used:

• Mandatory authentication, data integrity verification, confidentiality, and replay attack protection mechanisms.
• Mandatory authentication mechanisms supporting both automated management tools and interactive CLI-like tools.

Currently, NETCONF primarily uses SSH (Secure Shell) and TLS (Transport Layer Security) as transport protocols, as defined in RFC 6242 and RFC 7589.

NETCONF over SSH is the most commonly used transport method.

The Message Layer defines fundamental XML elements used as message envelopes, including the message boundaries: <hello>, <rpc>, and <rpc-reply>, as well as the specially purposed <ok> and <rpc-error> elements.
<hello>: A special message used by the Client and Server, exchanged immediately after connection establishment, to negotiate and exchange capabilities (e.g., supported NETCONF version). The Server’s <hello> must include the unique identifier session-id assigned to the session, which the Client can subsequently use for <lock> and <kill-session> operations. Conversely, the Client’s <hello> must not contain a session-id.
<rpc>: The Client’s request message sent to the Server, used to encapsulate a specific operation command, including the operation name and its parameters. This element must carry an attribute named message-id, which is a message identifier generated by the Client used to correlate the Server’s reply with the request.
<rpc-reply>: The Server’s response to an <rpc> request. It must also include the message-id attribute, and its value must match the message-id of the corresponding <rpc>. Furthermore, the <rpc-reply> must contain all attributes and attribute values present in the corresponding <rpc>, regardless of whether they are relevant to the reply.

Depending on the request and the processing result, the <rpc-reply> may encapsulate three different types of content:

• Specific Data Elements (<data>): When the operation is successful and the operation returns data (e.g., a retrieval operation).
• The <ok> Element: When the operation is successful but does not return data (e.g., a configuration modification).
• The <rpc-error> Element (Implicit): (Implied by standard) When the operation fails or encounters an exception.

When the server encounters an exceptional condition while processing a request, an <rpc-error> element MUST be returned. Some servers may support detecting and reporting multiple exceptions, which are organized into several <rpc-error> elements; these elements are order-independent.
An <rpc-error> element MAY contain the following sub-elements:

• error-type: The layer where the error occurred, an enumerated value, which MUST be one of: transport, rpc, protocol, or message.
• error-tag: A concise string identifying the error type, specifically defined by the protocol.
• error-severity: A string identifying the error level, which MUST be error or warning.
  
• error-app-tag: An OPTIONAL string identifying data-model-specific or implementation-specific errors.
  
• error-path: An OPTIONAL XPath expression identifying the data node that triggered the error.
  
• error-message: An OPTIONAL human-readable error description.
  
• error-info: An OPTIONAL element providing additional, more detailed error information, which MAY contain server application-defined structures.

NETCONF defines a set of fundamental operations used for managing device configurations and querying device state. There are also additional operations defined as capabilities; device support for these extra operations MUST be determined during the capability exchange phase.
The following sections introduce the basic NETCONF operations, categorized by: Data Operations, Datastore Operations, Session Operations, and Extension Operations.

3.3.1 <get-config>
The <get-config> operation is used to retrieve configuration data from a specified configuration datastore.
<get-config> supports two input parameters:
source: Specifies the name of the configuration datastore, e.g., running.
filter: An OPTIONAL parameter used to specify the configuration data filtering criteria. If this parameter is not provided, all configuration data from the entire configuration datastore MUST be returned. It has an OPTIONAL attribute, type, used to specify the filter type, which defaults to subtree.
If the request is successful, the server returns an <rpc-reply> containing a <data> element. The specific configuration data is encapsulated within the <data> element.

3.3.1.1 Subtree Filter
A subtree filter is a data filtering mechanism used for both the <get-config> and <get> operations. It allows the client to provide an XML snippet that describes the filtering criteria, instructing the server to return only the data that satisfies the criteria, rather than returning all configuration and state data from the entire datastore.
Specifically, a subtree filter appears as elements inside the <filter> element, and it is either empty or a data tree enclosed by a <top> element. An empty filter indicates that no data is selected, and the server SHOULD return an empty result (i.e., an empty <data> element). The <top> element is a virtual root node of the data model and does not exist in the actual data model.

The subtree nodes within the <filter> can be categorized as follows:

• Containment Node: A non-leaf node in the <filter> subtree that expresses the path leading to a leaf node.
  
• Selection Node: An empty leaf node in the <filter> subtree, expressing the meaning of “select this node and all child nodes.” For instance, an empty <top> element is a selection node, which means “return all data,” and has the same effect as providing no filtering criteria.
  
• Content Match Node: A non-empty leaf node in the <filter> subtree, expressing the meaning of “select this node and its siblings with the same value,” which implements exact matching.
  These node categories can be combined to form complex filtering criteria.

Additionally, the subtree filter also defines rules for namespace selection (precise matching on namespaces) and attribute match. These can be combined with the aforementioned node types to enhance the filtering conditions. The latter (attribute match) has almost no application scenario when a YANG model is used as the data model, as the XML encoding of the YANG model uses element names and content to convey data information, and elements can only use XML standard attributes such as namespaces.

3.3.3 <edit-config>
The <edit-config> operation is used to load the specified configuration data into a designated configuration datastore.
<edit-config> supports the following input parameters:

• config: The configuration data to be loaded, formatted as a <config> element containing the specific configuration data. If the server supports the URL Capability, a <url> element MAY be used instead of the <config> element. Elements within the <config> subtree MAY include an operation attribute to explicitly define the specific operational semantics. The possible values for the operation attribute are:
  
  • merge: Merges the configuration data. This is the default value for the operation attribute.
  • replace: Replaces the configuration data. If the configuration already exists, it is overwritten; if it does not exist, it is created.
  • create: Creates the configuration data. If the configuration already exists, an <rpc-error> with an error-tag of data-exists MUST be returned.
  • delete: Deletes the configuration data. If the configuration does not exist, an <rpc-error> with an error-tag of data-missing MUST be returned.
  • remove: Deletes the configuration data. If the configuration does not exist, the operation is silently ignored.
• target: The name of the configuration datastore to be modified, such as running.
• default-operation: Sets the default operation for the entire <edit-config> request. When a sub-element in the <config> does not explicitly specify an operation attribute, the server follows the behavior corresponding to this parameter’s value. The possible values are:
  
  • merge: As above, the configuration data is merged into the existing configuration. This is the default value for default-operation.
  • replace: As above, the configuration data replaces the existing configuration.
  • none: Does not affect configuration data already existing in the target datastore, unless the given configuration data explicitly specifies an operation attribute. Unlike merge, if the configuration data does not exist, the server SHOULD return an <rpc-error> with an error-tag of data-missing. This mode allows the server to avoid creating parent elements for the elements being deleted when processing a delete operation.
• error-option: Specifies the server’s strategy when encountering an error during request processing. The possible values are:
  
  • stop-on-error: Terminates the request processing upon encountering the first error. This is the default value for error-option.
  • continue-on-error: Logs the error and continues processing when an error is encountered, potentially resulting in multiple <rpc-error> elements being returned eventually.
  • rollback-on-error: Terminates processing upon encountering an error and reverts any configurations that were successfully applied within this <edit-config> operation. This enables the server to treat the configuration changes within <edit-config> as a transaction, ensuring they are either all applied or none are applied. This requires the server to support the Rollback-on-Error Capability.

3.3.4 <copy-config>
The <copy-config> operation is used to create or replace a configuration datastore using another configuration datastore or a complete configuration dataset.
<copy-config> has two MANDATORY input parameters:

• target: The name of the configuration datastore to be created or overwritten.
• source: The name of the configuration datastore acting as the source, or a <config> element containing the complete configuration data.

If the server supports the URL Capability, the content of both target and source MAY be a <url> element.

It should be noted that even if the server supports the Writable-Running Capability, it does not necessarily support using running as the value for target. Similarly, even if the server supports the URL Capability, it does not necessarily support using <url> elements for both source and target, i.e., remote-to-remote copy is not guaranteed. If the values of source and target are the same, the server SHOULD return an <rpc-error> with an error-tag of invalid-value.

3.3.5 <delete-config>
The <delete-config> operation is used to delete a specified configuration datastore. The <running> datastore MUST NOT be deleted.
<delete-config> has one MANDATORY input parameter, target, which is the name of the configuration datastore to be deleted. If the server supports the URL Capability, the target MAY contain a <url> element.

3.3.6 <lock> and <unlock>
The <lock> operation is used to lock a configuration datastore. A configuration datastore locked by one NETCONF session CANNOT be modified by other NETCONF sessions or other management plane interfaces (such as SNMP or CLI). This ensures that the locking session can modify the configuration without concerns about race conditions or data conflicts. These locks are expected to be short-lived.
<lock> has one MANDATORY input parameter, target, used to specify the name of the configuration datastore to be locked.
The <lock> request WILL fail if the lock on the target configuration datastore has already been acquired by another NETCONF session or another management plane interface.
The server MUST release any locks held by the session if the session closes for any reason, whether due to <close-session>, <kill-session>, a transport layer error, timeout, or detection of abnormal peer behavior.
The client MAY also explicitly release the lock via the <unlock> request. The parameters for <unlock> are the same as for <lock>. The <unlock> request WILL fail if the lock does not exist, or if the session holding the lock is not the current session.

3.3.7 <close-session>
The <close-session> operation is used to gracefully terminate a session.
When the server receives a <close-session> request, it MUST ignore all subsequent requests received for that session, release all locks and resources associated with the session, and then close the connection.

3.3.8 <kill-session>
The <kill-session> operation is used to forcibly terminate a session.
When the server receives a <kill-session> request, it MUST immediately terminate the request currently being processed by that session, release associated locks and resources, and close the connection.
<kill-session> has one MANDATORY input parameter, session-id, used to specify the session to be forcibly terminated. The session-id is obtained from the <hello> message sent by the server at the beginning of the session establishment. This operation MUST NOT be used to terminate the current session. If the session-id is equal to the session-id of the current session, the server SHOULD return an invalid-value error.

As the latest standardized network management protocol, NETCONF provides a unified, precise, and convenient method for bulk management of network devices. The following illustrates a typical out-of-band (OOB) management network topology used for managing data center equipment. 

A management server is deployed within the OOB management network, enabling network communication with all switches. This setup allows for centralized management of all switches, including configuration changes and state checks.

Switches in a data center may originate from multiple vendors. NETCONF and YANG offer a relatively unified operational interface to manage cross-vendor equipment, which simplifies operations and maintenance (O&M) to a certain extent. Although the specific YANG models supported by different vendors may vary, the management application can be built on the same foundation, executing the same operations (e.g., <edit-config>) across all devices. The only difference lies in the specific operational data, which may require network administrators to write different configuration data templates for various vendor devices. Crucially, the syntax of the configuration data remains consistent, as it is always the XML encoding corresponding to the YANG model.
The precision of device management through NETCONF is embodied in the YANG model. The YANG model allows for the modeling of every configuration node and state node, enabling the client to precisely modify and query specific nodes.
Furthermore, NETCONF supports batch configuration with a single request. For any given device, the management server can encapsulate the required configuration changes within one or several <edit-config> requests. Specifically, the Xingrongyuan (Xingrong Yuan) data center series switches support the Rollback-on-Error Capability, which guarantees the atomicity of a single <edit-config> operation—meaning the configuration changes within an <edit-config> either all take effect or none take effect. This feature prevents the device from entering an undesirable intermediate state upon encountering an error, thereby simplifying subsequent retry attempts.

The table below lists several current, valid, and relatively important RFC documents that constitute the NETCONF protocol standard: