Establishing a NETCONF Session

The NETCONF server communicates with client applications within the context of a NETCONF session. The server and client explicitly establish a connection and session before exchanging data, and close the session and connection when they are finished.

Client applications access the NETCONF server using the SSH protocol and use the standard SSH authentication mechanism. After authentication, the NETCONF server uses the login usernames and classes already configured on the C Series Controller to determine whether a client application is authorized to make each request.

For information about establishing a connection and NETCONF session, see the following sections:

• Generating Well-Formed XML Documents
• Prerequisites for Establishing a Connection
• Connecting to the NETCONF Server
• Starting the NETCONF Session

For an example of a complete NETCONF session, see Example of a NETCONF Session.

Generating Well-Formed XML Documents

Each set of NETCONF and XML tag elements emitted by the NETCONF server and a client application within a <hello>, <rpc>, or <rpc-reply> tag element must constitute a well-formed XML document by obeying the structural rules defined in the document type definition (DTD) for the kind of information being sent. The client application must emit tag elements in the required order and only in the allowed contexts.

The NETCONF server and client applications must also comply with RFC 4742, Using the NETCONF Configuration Protocol over Secure Shell (SSH), available at http://www.ietf.org/rfc/rfc4742.txt. In particular, the server and applications must send the character sequence ]]>]]> after each XML document. This sequence is not legal within an XML document and so unambiguously signals the end of a document. In practice, the client application sends the sequence after the closing </hello> tag and each closing </rpc> tag, and the NETCONF server sends it after the closing </hello> tag and each closing </rpc-reply> tag.

Note: In the following example (and in all examples in this document of tag elements emitted by a client application), bold font is used to highlight the part of the tag sequence that is discussed in the text.

Prerequisites for Establishing a Connection

To enable a client application to establish an SSH connection to the NETCONF server, you must satisfy the requirements discussed in the following sections:

• Client Application Can Access SSH Software
• Client Application Can Log In on C Series Controllers
• Login Account Has Public/Private Key Pair or Password
• Client Application Can Access the Keys or Password
• NETCONF Service over SSH Is Enabled

Client Application Can Access SSH Software

The client application must be able to access the SSH software on the computer where it runs.

If the application uses the NETCONF Perl module provided by Juniper Networks, no further action is necessary. As part of the installation procedure for the Perl module, you install a prerequisites package that includes the necessary SSH software.

If the application does not use the NETCONF Perl module, obtain the SSH software and install it on the computer where the application runs. For information about obtaining and installing SSH software, see http://www.ssh.com and http://www.openssh.com.

Client Application Can Log In on C Series Controllers

The client application must be able to log in to each C Series Controller on which it establishes NETCONF sessions. The following instructions explain how to create a login account for the application. Alternatively, you can skip this section and enable authentication through RADIUS or TACACS+. For instructions, see SRC PE Getting Started Guide.

To determine if a login account exists, enter SRC command-line interface (CLI) configuration mode on the C Series Controller and issue the following commands:

If the appropriate account does not exist, perform the following steps:

1. Include the user statement at the [edit system login] hierarchy level. Specify a login class that has the permissions required for all actions to be performed by the application. You can also include the optional full-name and uid statements. For detailed information about creating user accounts, see SRC PE Getting Started Guide.

   [edit system login]

   user@host# set user user-name class class

2. (Optional) Commit the configuration. Alternatively, you can wait until you have added the statements that satisfy all prerequisites (see NETCONF Service over SSH Is Enabled).

   [edit system login]

   user@host# commit

3. Repeat the preceding steps on each C Series Controller where the client application establishes NETCONF sessions.

Login Account Has Public/Private Key Pair or Password

For a client application to authenticate with the NETCONF server, the login account that you created in Client Application Can Log In on C Series Controllers must have an SSH public/private key pair, a text-based password, or both. A public/private key pair is sufficient if the account is used only to connect to the NETCONF server through SSH. If the account is also used to access the C Series Controller in other ways (for login on the console, for example), it must have a text-based password. The password is also used (the SSH server prompts for it) if key-based authentication is configured but fails.

Note: You can skip this section if you have chosen to enable authentication through RADIUS or TACACS+, as described in SRC PE Getting Started Guide.

Follow the instructions in the appropriate section:

• Creating a Text-Based Password
• Creating a Public/Private Key Pair

Creating a Text-Based Password

To create a text-based password, perform the following steps:

1. Include either the plain-text-password or encrypted-password statement at the [edit system login user user-name authentication] hierarchy level. First, move to that hierarchy level:
   

   [edit system login]

   user@host# edit user user-name authentication

   To enter a password as text, issue the following command. You are prompted for the password, which is encrypted before being stored.

   [edit system login user user-name authentication]

   user@host# set plain-text-password

   New password: password

   Retype new password: password

   To store a password that you have previously created and hashed using Message Digest 5 (MD5) or Secure Hash Algorithm 1 (SHA-1), issue the following command:

   [edit system login user user-name authentication]

   user@host# set encrypted-password "password"

2. (Optional) Commit the configuration. Alternatively, you can wait until you have added the statements that satisfy all prerequisites (see NETCONF Service over SSH Is Enabled).

   [edit system login user user-name authentication]

   user@host# commit

3. Repeat the preceding steps on each C Series Controller where the client application establishes NETCONF sessions.

Creating a Public/Private Key Pair

To create an SSH public/private key pair, perform the following steps:

1. Issue the ssh-keygen command in the standard command shell (not the SRC CLI) on the computer where the client application runs. By providing the appropriate arguments, you encode the public key with either RSA (supported by SSH versions 1 and 2) or the Digital Signature Algorithm (DSA, supported by SSH version 2). For more information, see the manual page for the ssh-keygen command. The SRC software uses SSH version 2 by default, but also supports version 1.

   % ssh-keygen options

2. Associate the public keys with the login account by including the ssh-authorized-keys statement at the [edit system login user user-name authentication] hierarchy level. The SRC software copies the public keys onto the C Series Controller:

   [edit system login user user-name authentication]

   user@host# set ssh-authorized-keys [ssh-authorized-keys...]

   The ssh-keygen command by default stores each public key in a file in the ssh subdirectory of the user home directory; the filename depends on the encoding (DSA or RSA) and SSH version. For more information about configuring SSH authentication, see SRC PE Getting Started Guide.

3. (Optional) Commit the configuration. Alternatively, you can wait until you have added the statements that satisfy all prerequisites (see NETCONF Service over SSH Is Enabled).

   [edit system login user user-name authentication]

   user@host# commit

4. Repeat Steps 2 and 3 on each C Series Controller where the client application establishes NETCONF sessions.

Client Application Can Access the Keys or Password

The client application must be able to access the public/private keys or password you created in Login Account Has Public/Private Key Pair or Password and provide it when the NETCONF server prompts for it.

There are several methods for enabling the application to access the key or password:

• If public/private keys are used, the ssh-agent program runs on the computer where the client application runs, and handles the private key.

• When a user starts the application, the application prompts the user for the password and stores it temporarily in a secure manner.

• The password is stored in encrypted form in a secure local-disk location or in a secured database.

NETCONF Service over SSH Is Enabled

The IETF draft titled Using the NETCONF Configuration Protocol over Secure Shell (SSH) requires that the NETCONF server by default provide SSH access to client machines over a devoted Transmission Control Protocol (TCP) port, to make it easy to identify and filter NETCONF traffic. The port for the SRC NETCONF server is 32000. In addition, you can enable client applications to access the NETCONF server over the default SSH port (22). (For more information about the IETF draft, see Generating Well-Formed XML Documents.)

Perform the following steps:

1. Include one or both of the following statements at the indicated hierarchy level:
   • To enable SSH access over the devoted port (32000) as specified by the IETF specification, include the ssh statement at the [edit system services netconf] hierarchy level:

     [edit system login user user-name authentication]

     user@host# top

     [edit]

     user@host# set system services netconf ssh

   • To enable access over the default SSH port (22), include the ssh statement at the [edit system services] hierarchy level. This configuration also enables SSH access to the C Series Controller for all users and applications.

     [edit]

     user@host# set system services ssh

2. Commit the configuration:

   [edit]

   user@host# commit

3. Repeat the preceding steps on each C Series Controller where the client application establishes NETCONF sessions.

Connecting to the NETCONF Server

Before a client application can connect to the NETCONF server, you must satisfy the requirements described in Prerequisites for Establishing a Connection.

When the prerequisites are satisfied, applications written in Perl use the NETCONF Perl module to connect to the NETCONF server. A client application that does not use the NETCONF Perl module uses one of two methods:

• It uses SSH library routines to establish an SSH connection to the NETCONF server, provide the username and password or passphrase, 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.
• It issues the following ssh command to create a NETCONF session as an SSH subsystem:

  ssh -p 32000 -s user@hostname netconf

  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 in NETCONF Service over SSH Is Enabled.

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

  The application must include code to intercept the NETCONF server’s prompt for the password or passphrase. Perhaps the most straightforward method is for the application to use a utility such as the expect command. The NETCONF Perl client uses this method, for example.

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
• Verifying Compatibility

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 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 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 API for SRC 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 Information from the Candidate Configuration and Committing Configurations.
• 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 Providing Configuration Data in a File.
• http://xml.juniper.net/netconf/junos/1.0—The NETCONF server supports the operations defined in the SRC XML API for requesting and changing operational information (the tag elements in the SRC XML API Operational Reference).
• http://xml.juniper.net/netconf/junos/sdx/1.0—The NETCONF server supports the operations defined in the SRC XML API for requesting and changing operational information (the tag elements in the SRC XML API Operational Reference). The NETCONF server also supports operations for requesting or changing configuration information (the tag elements in the SRC XML API Configuration Reference).

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:

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 SRC software running on the NETCONF server. After emitting its<hello> tag element, it emits the <get-system-info> tag element in an <rpc> tag element:

The NETCONF server returns the <system-info> tag element, which encloses the <system-identification> and <software-version> tag elements. (For information about the <rpc-reply> tag element, see Parsing the NETCONF Server Response.) Some tag elements appear on multiple lines, for legibility only:

Normally, the version is the same for all SRC software components running on the C Series Controller. (We recommend this configuration for predictable performance.) The client application can determine the version of the SRC software components running on the NETCONF server by emitting the <get-component-all> tag element in an<rpc> tag element:

The NETCONF server returns the <sdx-component-list> tag element, which encloses the <sdx-component> tag elements plus a <version> tag element for each installed SRC software component. (For information about the <rpc-reply> tag element, see Parsing the NETCONF Server Response.) The <version> tag element within the <sdx-component> tag element specifies the SRC release number (in the following example, 2.0 for SRC Release 2.0) and the build information. Some tag elements appear on multiple lines, for legibility only:

In the NETCONF API for SRC, it is the responsibility of the client application to determine 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 SRC 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 SRC version, and do not alter the client application’s behavior to accommodate the NETCONF server. A difference in SRC 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 SRC software, for example, it can choose to emit only NETCONF and SRC XML tag elements that represent the software features available in the NETCONF server’s version of the software.
• End the NETCONF session and terminate the connection. This is appropriate if you decide that it is not practical to make the client application accommodate the SRC version or capabilities supported by the NETCONF server. For instructions, see Ending a NETCONF Session and Closing the Connection.

Copyright © 2009, Juniper Networks, Inc. All rights reserved. Trademark Notice.