Starting the NETCONF Session
Each NETCONF session begins with a handshake in which the NETCONF server and the client application specify the NETCONF capabilities they support. The following sections describe how to start a NETCONF session:
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 <hello> tag element encloses the <capabilities> tag element and the <session-id> tag element, which specifies the UNIX process ID (PID) of the NETCONF server for the session. Within the <capabilities> tag element, a <capability> tag element specifies each supported function.
The client application must emit the <hello> tag element before any other tag element during the NETCONF session, and must not emit it more than once.
Each capability defined in the NETCONF specification is represented in a <capability> tag 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 XML management protocol for Junos OS Release 13.2 emits the following <hello> tag element (each <capability> tag element appears on three lines for legibility only):
(For information about the ]]>]]> character sequence, see Generating Well-Formed XML Documents.)
The URIs in the <hello> tag element indicate the following supported capabilities:
- urn:ietf:params:xml:ns:netconf:base:1.0—The NETCONF server supports the basic NETCONF operations and tag elements defined in this namespace.
- urn:ietf:params:xml:ns:netconf:capability:candidate:1.0—The NETCONF server supports operations on a candidate configuration. For more information, see Requesting Committed or Candidate Configuration Information Using NETCONF, Locking and Unlocking the Candidate Configuration Using NETCONF, Editing the Candidate Configuration Using NETCONF, Rolling Back a Configuration Using NETCONF, Verifying the Configuration Syntax Using NETCONF, and Committing the Candidate Configuration Using NETCONF.
- urn:ietf:params:xml:ns:netconf:capability:confirmed-commit:1.0—The NETCONF server supports confirmed commit operations. For more information, see Committing the Candidate Configuration Only After Confirmation Using NETCONF.
- urn:ietf:params:xml:ns: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 Verifying the Configuration Syntax Using NETCONF.
- urn:ietf:params:xml:ns: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 (indicated by the file option in the URN) and from remote machines by using Hypertext Transfer Protocol (HTTP) or FTP (indicated by the http and ftp options in the URN). For more information, see Uploading and Formatting Configuration Data in a NETCONF Session.
- http://xml.juniper.net/netconf/junos/1.0—The
NETCONF server supports the operations defined in the Junos XML API
for requesting and changing operational information (the tag elements
in the Junos XML API Operational Reference). The NETCONF server also supports
operations in the Junos XML management protocol for requesting or
changing configuration information.
NETCONF client applications should use only native NETCONF XML management protocol operations and supported extensions available in the Junos XML management protocol 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.
To comply with the NETCONF specification, the client application also emits a <hello> tag element to define the capabilities it supports. It does not include the <session-id> tag element:
The session continues when the client application sends a request to the NETCONF server. The NETCONF server does not emit any tag elements after session initialization except in response to the client application’s requests.
Verifying Compatibility
Exchanging <hello> tag elements enables a client application and the NETCONF server to determine if they support the same capabilities. In addition, we recommend that the client application determine the version of the Junos OS running on the NETCONF server. After emitting its <hello> tag, the client application emits the <get-software-information> tag element in an <rpc> tag element:
The NETCONF server returns the <software-information> tag element, which encloses the <host-name> and <product-name> tag elements plus a <package-information> tag element for each Junos OS module. The <comment> tag element within the <package-information> tag element specifies the Junos OS Release number (in the following example, 8.2 for Junos OS Release 8.2) and the build date in the format YYYYMMDD (year, month, day—12 January 2007 in the following example). Some tag elements appear on multiple lines, for legibility only:
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" \
xmlns:junos="http://xml.juniper.net/junos/8.2R1/junos">
<software-information>
<host-name>router1</host-name>
<product-name>m20</product-name>
<package-information>
<name>junos</name>
<comment>JUNOS Base OS boot [8.2-20070112.0]</comment>
</package-information>
<package-information>
<name>jbase</name>
<comment>JUNOS Base OS Software Suite \
[8.2-20070112.0]</comment>
</package-information>
<!-- <package-information> tag elements for additional modules -->
</software-information>
</capabilities>
</rpc-reply>
]]>]]>
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. Decide which of the following options is appropriate when there are differences, and implement the corresponding response:
- Ignore differences in capabilities and Junos version, and do not alter the client application’s behavior to accommodate the NETCONF server. A difference in Junos 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 the Junos OS.
- End the NETCONF session and terminate the connection. This is appropriate if you decide that it is not practical to accommodate the NETCONF server’s version or capabilities. For instructions, see Ending a NETCONF Session and Closing the Connection.
