NETCONF Sessions

SSH Library Routines

A NETCONF client uses SSH library routines to establish an SSH connection to the NETCONF server, provide authentication, and create a channel that acts as an SSH subsystem for the NETCONF session. Providing instructions for using library routines is beyond the scope of this document.

ssh Command

You can establish a NETCONF session as an SSH subsystem with a dedicated port. Alternatively, you can establish a NETCONF session over the default SSH port and use pseudo-tty allocation. Using an SSH subsystem over a dedicated port enables the device to easily identify and filter NETCONF traffic. However, using the default SSH port with pseudo-tty allocation can provide visibility to the session, for example, when issuing the show system users operational command.

The application must include code to intercept the NETCONF server’s prompt for the password or passphrase. For example, the application can use a utility such as the expect command.

• To establish a NETCONF session as an SSH subsystem over the default NETCONF port (830), the client application issues the following command:

  The -p option defines the port number on which the NETCONF server listens. This option can be omitted if you enabled access to SSH over the default port.

  The -s option establishes the NETCONF session as an SSH subsystem.

• To establish a NETCONF session over the default SSH port (22) and use pseudo-tty allocation, the client application issues the following command:

  Note:

  Using multiple -t options forces pseudo-tty allocation even if SSH has no local tty.

Exchanging <hello> Tag Elements

The NETCONF server and client application each begin by emitting a <hello> tag element to specify which operations, or capabilities, they support from among those defined in the NETCONF specification. The client application must emit the <hello> element before any other element and must only emit it once.

The <hello> tag encloses the following elements:

• <capabilities>—List of <capability> elements, which each define a supported function.

• <session-id>—UNIX process ID (PID) of the NETCONF server for the session.

Each capability defined in the NETCONF specification is represented in a <capability> element by a uniform resource name (URN). Capabilities defined by individual vendors are represented by uniform resource identifiers (URIs), which can be URNs or URLs. The NETCONF server emits a <hello> element similar to the following output:

The URIs in the <hello> element indicate the supported capabilities. Table 1 lists some common capabilities.

Table 1: Common Capabilities

Capability	Description
urn:ietf:params:netconf:base:1.0	The NETCONF server supports the basic operations and elements defined in the base NETCONF specification.
urn:ietf:params:netconf:base:1.1	The NETCONF session is compliant with RFC 6242, which supports the chunked framing mechanism for message framing.
urn:ietf:params:netconf:capability:candidate:1.0	The NETCONF server supports operations on a candidate configuration.
urn:ietf:params:netconf:capability:confirmed-commit:1.0	The NETCONF server supports confirmed commit operations. For more information, see Commit the Candidate Configuration Only After Confirmation Using NETCONF
urn:ietf:params:netconf:capability:validate:1.0	The NETCONF server supports the validation operation, which verifies the syntactic correctness of a configuration without actually committing it. For more information, see Verify the Candidate Configuration Syntax Using NETCONF.
urn:ietf:params:netconf:capability:url:1.0?protocol=http,ftp,file	The NETCONF server accepts configuration data stored in a file. It can retrieve files both from its local filesystem and from remote machines by using HTTP or FTP. For more information, see Upload and Format Configuration Data in a NETCONF Session.
http://xml.juniper.net/netconf/junos/1.0	The NETCONF server supports: Operations defined in the Junos XML API for requesting and changing operational information. Junos XML protocol operations for requesting or changing configuration information. NETCONF client applications should use only native NETCONF operations and supported Junos XML protocol extensions for configuration functions. The semantics of corresponding Junos XML protocol operations and NETCONF XML protocol operations are not necessarily identical, so using Junos XML protocol configuration operations other than the documented supported extensions can lead to unexpected results.
http://xml.juniper.net/dmi/system/1.0	The NETCONF server supports the operations defined in the Device Management Interface (DMI) specification.

By default, the NETCONF server does not advertise supported YANG modules in the NETCONF capabilities exchange. To advertise supported YANG modules, configure one or more of the following statements at the [edit system services netconf hello-message yang-module-capabilities] hierarchy level:

• advertise-custom-yang-modules—Advertise third-party YANG modules installed on the device.
• advertise-native-yang-modules—Advertise Junos OS native YANG modules.
• advertise-standard-yang-modules—Advertise standard YANG modules supported by the device, for example, OpenConfig modules.

To comply with the NETCONF specification, the client application also emits a <hello> element to define the capabilities it supports. It does not include the <session-id> element:

NETCONF sessions use a framing mechanism to separate the messages that the NETCONF server and client send within the session. By default, a NETCONF session with a Junos device uses the character sequence ]]>]]> as a message separator. However, if you configure RFC 6242-compliant NETCONF sessions, and both peers advertise the :base:1.1 capability in the capabilities exchange, the NETCONF session uses chunked framing for the remainder of the session. Chunked framing is a standardized framing mechanism that ensures that character sequences within XML elements are not misinterpreted as message boundaries. For more information, see Configure RFC-Compliant NETCONF Sessions.

The session continues when the client application sends a request to the NETCONF server. The NETCONF server does not emit any elements after session initialization except in response to the client application’s requests.

Verifying Compatibility

Exchanging <hello> tag elements enables the NETCONF server and client to determine if they support the same capabilities. In addition, we recommend that the client application determine the Junos OS version running on the NETCONF server. After emitting its <hello> tag, the client application can emit the <get-software-information> request.

The NETCONF server returns the <software-information> element, which encloses different tags depending on the Junos OS variant. Junos OS returns the <host-name> and <product-name> tag elements plus a <package-information> element for each software module. The <comment> elements specify the Junos OS release and the build date in the format YYYYMMDD. In the following example, the release is 8.2 for Junos OS Release 8.2 and the build date is 20070112 (12 January 2007).

Normally, the version is the same for all Junos OS modules running on the device (we recommend this configuration for predictable routing performance). Therefore, verifying the version number of just one module is usually sufficient.

The client application is responsible for determining how to handle any differences in version or capabilities. For fully automated performance, include code in the client application that determines whether it supports the same capabilities and Junos OS version as the NETCONF server. When there are differences, determine which of the following options is appropriate, and implement the corresponding response:

• Ignore differences—Ignore differences in capabilities and Junos OS version, and do not alter the client application’s behavior to accommodate the NETCONF server. A difference in Junos OS versions does not necessarily make the server and client incompatible, so this is often a valid approach. Similarly, it is a valid approach if the capabilities that the client application does not support are operations that are always initiated by a client, such as validation of a configuration and confirmed commit. In that case, the client maintains compatibility by not initiating the operation.

• Alter standard behavior to be compatible with the NETCONF server—If the client application is running a later version of the Junos OS, for example, it can choose to emit only NETCONF and Junos XML tag elements that represent the software features available in the NETCONF server’s version of Junos OS.

• End the NETCONF session and terminate the connection—Use this option if you decide that it is not practical to accommodate the NETCONF server’s version or capabilities.

How to Send Requests

To initiate a request to the NETCONF server, a client application emits the following:

• Opening <rpc> tag

• One or more tag elements that represent the particular request

• Closing </rpc> tag

The application encloses each request in its own separate pair of opening <rpc> and closing </rpc> tags. Each request must constitute a well-formed XML document by including only compliant and correctly ordered tag elements. The NETCONF server ignores any newline characters, spaces, or other white space characters that occur between tag elements in the tag stream, but it preserves white space within tag elements.

Optionally, a client application can include one or more attributes of the form attribute-name="value" in the opening <rpc> tag for each request. The NETCONF server echoes each attribute, unchanged, in the opening <rpc-reply> tag in which it encloses its response.

A client application can use this feature to associate requests and responses by including an attribute in each opening <rpc> request tag that assigns a unique identifier. The NETCONF server echoes the attribute in its opening <rpc-reply> tag, making it easy to map the response to the initiating request. The NETCONF specification specifies the name message-id for this attribute.

Although operational and configuration requests conceptually belong to separate classes, a NETCONF session does not have distinct modes that correspond to CLI operational and configuration modes. Each request tag element is enclosed within its own <rpc> tag, so a client application can freely alternate operational and configuration requests. A client application can make three classes of requests: operational requests, configuration information requests, and configuration change requests.

Operational Requests

Operational requests are requests for information about the status of a device. Operational requests correspond to the Junos OS CLI operational mode commands. The Junos XML API defines a request tag element for many CLI commands. For example, the <get-interface-information> tag element corresponds to the show interfaces command, and the <get-chassis-inventory> tag element requests the same information as the show chassis hardware command.

The following RPC requests detailed information about interface ge-2/3/0:

For more information about operational requests, see Request Operational Information Using NETCONF.

For information about Junos XML request tags, see the XML API Explorer.

Configuration Information Requests

Configuration information requests are requests for information about the device’s candidate configuration, a private configuration, the ephemeral configuration, or the committed (active) configuration. The candidate and committed configurations diverge when there are uncommitted changes to the candidate configuration.

The NETCONF protocol defines the <get-config> operation for retrieving configuration information. The Junos XML API defines a tag element for every container and leaf statement in the configuration hierarchy.

The following example requests information from the [edit system login] hierarchy level of the candidate configuration:

For more information about configuration information requests, see Request Configuration Data Using NETCONF.

For a summary of the available configuration tag elements, see the XML API Explorer .

Configuration Change Requests

Configuration change requests are requests to change the configuration, or to commit those changes to put them into active use on the device running Junos OS. The NETCONF protocol defines the <edit-config> and <copy-config> operations for changing configuration information. The Junos XML API defines a tag element for every container and leaf statement in the configuration hierarchy.

The following example creates a new Junos OS user account called admin at the [edit system login] hierarchy level in the candidate configuration:

For more information about configuration change requests, see Edit the Configuration Using NETCONF.

For a summary of the available configuration tag elements, see the XML API Explorer .

NETCONF Server Response Overview

In a NETCONF session, a client application sends RPCs to the NETCONF server to request information and manage the device configuration. The NETCONF server encloses its response to each client request in a separate pair of opening <rpc-reply> and closing </rpc-reply> tags. Each response constitutes a well-formed XML document.

The xmlns attribute in the opening <rpc-reply> tag defines the namespace for enclosed tag elements that do not have the junos: prefix in their names and that are not enclosed in a child container tag that has the xmlns attribute with a different value.

Note:

If you configure the rfc-compliant statement on the device, the NETCONF server explicitly declares the NETCONF namespace, which is bound to the nc prefix, and qualifies all NETCONF tags in its replies with the prefix.

The xmlns:junos attribute defines the default namespace for enclosed Junos XML tag elements that are qualified by the junos: prefix. The release variable in the URI represents the Junos OS release that is running on the NETCONF server device, for example 20.4R1.

Client applications must include code for parsing the stream of response tag elements coming from the NETCONF server, either processing them as they arrive or storing them until the response is complete. The NETCONF server returns three classes of responses: operational responses, configuration information responses, and configuration change responses.

Operational Responses

Operational responses are responses to requests for information about the status of a switching, routing, or security platform. They correspond to the output from CLI operational commands.

The Junos XML API defines response tag elements for all defined operational request tag elements. For example, the NETCONF server returns the information requested by the <get-interface-information> tag in a response tag called <interface-information>. Similarly, the server returns the information requested by the <get-chassis-inventory> tag in a response tag called <chassis-inventory>.

By default, the server returns operational responses in XML format. The client application can also request that the server return responses in formatted ASCII, which is enclosed within an output element, or in JSON format. For more information about formatting operational responses, see Specify the Output Format for Operational Information Requests in a NETCONF Session.

The following sample operational response includes information about the interface ge-2/3/0:

For more information about the xmlns attribute and the contents of operational response tag elements, see Request Operational Information Using NETCONF.

Configuration Information Responses

Configuration information responses are responses to requests for information about the device’s current configuration. The Junos XML API defines a tag element for every container and leaf statement in the configuration hierarchy.

The following sample response includes configuration data at the [edit system login] hierarchy level:

For information about the attributes in the opening <configuration> tag, see Specify the Source for Configuration Information Requests Using NETCONF.

Configuration Change Responses

Configuration change responses are responses to requests that change the state or contents of the device configuration. The NETCONF server indicates successful execution of a request by returning the <ok/> tag within the <rpc-reply> tag element.

If the operation fails, the <rpc-reply> tag element instead encloses an <rpc-error> element that describes the cause of the failure.

Locking the Candidate Configuration

Locking the candidate configuration prevents other users or applications from changing the candidate configuration until the lock is released. This is equivalent to the CLI configure exclusive command. Locking the configuration before making changes is recommended, particularly on devices where multiple users are authorized to change the configuration. A commit operation applies to all changes in the candidate configuration, not just those made by the user or application that requests the commit. Allowing multiple users or applications to make changes simultaneously can lead to unexpected results.

To lock the candidate configuration, a client application executes the <lock> operation with <target> set to <candidate/> as follows:

The NETCONF server confirms that it has locked the candidate by returning the <ok/> tag.

If the NETCONF server cannot lock the configuration, the <rpc-reply> instead encloses an <rpc-error> element explaining the reason for the failure. Reasons for the failure can include the following:

• Another user or application has already locked the candidate configuration. The error message reports the NETCONF session identifier of the user or application.

• The candidate configuration already includes changes that have not yet been committed.

Only one application can hold the lock on the candidate configuration at a time. Other users and applications can read the candidate configuration while it is locked. The lock persists until either the client application unlocks the configuration by emitting the <unlock> tag element or the NETCONF session ends.

If the client application unlocks the candidate configuration before committing the changes, or if the NETCONF session ends for any reason before the changes are committed, the changes are automatically discarded. The candidate and committed configurations remain unchanged.

Unlocking the Candidate Configuration

As long as a client application holds a lock on the candidate configuration, other applications and users cannot change the candidate. To unlock the candidate configuration, the client application executes the <unlock> operation.

The NETCONF server confirms that it has unlocked the candidate by returning the <ok/> tag.

If the NETCONF server cannot unlock the configuration, the <rpc-reply> instead encloses an <rpc-error> element explaining the reason for the failure.