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.

The streams of NETCONF and Junos XML tag elements emitted by the NETCONF server and the client application must each constitute well-formed XML by obeying the structural rules defined in the document type definition (DTD) for the kind of information they are exchanging. The client application must emit tag elements in the required order and only in the allowed contexts.

Client applications access the NETCONF server using the SSH protocol and use the standard SSH authentication mechanism. After authentication, the NETCONF server uses the Junos login usernames and classes already configured on the device 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:

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

Generating Well-Formed XML Documents

Each set of NETCONF and Junos 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. Because this sequence is not legal within an XML document, it 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.

<!-- generated by a client application -->
<hello | rpc>
    <!-- contents of top-level tag element  -->
</hello | /rpc>
]]>]]>
   
<!-- generated by the NETCONF server -->
<hello | rpc-reply attributes>
    <!-- contents of top-level tag element  -->
</hello | /rpc-reply>
]]>]]>

Prerequisites for Establishing an SSH Connection

You use the SSH protocol to establish connections between a configuration management server and a device running Junos OS. A configuration management server, as the name implies, is used to configure the device running Junos OS remotely. This server typically manages the configurations using Perl scripts.

There are two options available when establishing a connection between the configuration management server and a device running Junos OS: SSH and outbound SSH. With SSH, the configuration management server initiates an SSH session with the device running Junos OS. Outbound SSH is used when the configuration management server cannot initiate an SSH connection because of network restrictions (such as a firewall). In this situation, the device running Junos OS is configured to initiate, establish, and maintain an SSH connection with a predefined set of configuration management servers. For a complete discussion of outbound SSH, see “Configuring Outbound SSH Service” in the Junos System Basics Configuration Guide.

Establishing an SSH Connection

Before the configuration management server establishes an SSH connection with a device running Junos OS, you must satisfy the requirements discussed in the following sections.

SSH Software Is Installed on the Configuration Management Server

The configuration management server handles the SSH connection between the configuration management server and the device running Junos OS. Therefore, the SSH software must be installed locally on the configuration management server. If the client application accessing the NETCONF server 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 client application does not use the NETCONF Perl module, obtain the SSH software and install it on the configuration management server where the client 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 Devices Running Junos OS

When establishing a NETCONF session, the configuration management server must log in to the device running the Junos OS. Thus, each configuration management server needs a user account on each device where a NETCONF session will be established. The following instructions explain how to create a Junos OS login account for the configuration management server. Alternatively, you can skip this section and enable authentication through RADIUS or TACACS+; for instructions, see the chapter about system authentication in the Junos System Basics Configuration Guide.

To determine whether a login account exists on a device running Junos OS, enter CLI configuration mode on the device and issue the following commands:

[edit]user@host# edit system login [edit system login]user@host# show user account-name

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

  1. Include the user statement at the [edit system login] hierarchy level and specify a username. Also include the class statement at the [edit system login user username] hierarchy level, and specify a login class that has the permissions required for all actions to be performed by the application. Optionally, include the full-name and uid statements.
    [edit system login]user@host# set user user-name class class-name

    Note: For detailed information about creating user accounts, see the chapter about configuring user access in the Junos System Basics Configuration Guide.

  2. Commit the configuration to activate the user account on the device. If you are going to make more changes to the configuration file, you can wait to commit the file until you have completed making all of the changes to the file. However, the user account is not activated on the device until you commit the configuration.
    [edit system login]user@host# commit
  3. Repeat the preceding steps on each device where the client application will establish a NETCONF session.

Junos Login Account Has Public/Private Key Pair or Password

The configuration management server needs an SSH public/private key pair, a text-based password, or both before it can authenticate with the NETCONF server. 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 device 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 the chapter about system authentication in the Junos System Basics Configuration Guide.

Follow the instructions in the appropriate section:

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 account-name authentication] hierarchy level. First, move to that hierarchy level:
    [edit system login]user@host# edit user account-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 account-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 account-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 account-name authentication]user@host# commit
  3. Repeat the preceding steps on each device running Junos OS 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 Junos OS CLI) on the configuration management server 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 Junos OS uses SSH version 2 by default, but also supports version 1.
    % ssh-keygen options
  2. Associate the public key with the Junos login account by including the load-key-file statement at the [edit system login user account-name authentication] hierarchy level. The Junos OS copies the contents of the specified file onto the device running Junos OS.
    [edit system login user account-name authentication]user@host# set load-key-file URL

    URL is the path to the file that contains one or more public 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 information about specifying URLs, see the Junos CLI User Guide.

    Alternatively, you can include one or both of the ssh-dsa and ssh-rsa statements at the [edit system login user account-name authentication] hierarchy level. We recommend using the load-key-file statement, however, because it eliminates the need to type or cut-and-paste the public key on the command line. For more information about the ssh-dsa and ssh-rsa statements, see the Junos System Basics Configuration 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 account-name authentication]user@host# commit
  4. Repeat Step 2 and Step 3 on each device running Junos OS 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 Junos 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:

NETCONF Service over SSH Is Enabled

RFC 4742, Using the NETCONF Configuration Protocol over Secure SHell (SSH), requires that the NETCONF server, by default, provide the client device with SSH access to the server over a dedicated TCP port. Use of a dedicated port makes it easy to identify and filter NETCONF traffic. The Internet Assigned Numbers Authority (IANA) port for NETCONF-over-SSH sessions is 830.

You also can enable access to the NETCONF server either over the default SSH port (22) or over a port number that is explicitly configured on the device running Junos OS. If you specify the NETCONF-over-SSH port number in the device configuration, the configured port accepts only NETCONF-over-SSH sessions and rejects regular SSH session requests. The default SSH port (22) continues to accept NETCONF sessions even when an alternate NETCONF-over-SSH port is configured. For added security, you can configure event policies that utilize UI_LOGIN_EVENT information to effectively disable the default port or further restrict NETCONF server access on a port.

To enable NETCONF service over SSH, perform the following steps:

  1. Include one of the following statements at the indicated hierarchy level:
    • To enable SSH access over the default NETCONF-over-SSH port (830) as specified by RFC 4742, include the ssh statement at the [edit system services netconf] hierarchy level:
      [edit system services]user@host# set netconf ssh
    • To enable SSH access over a specified port number, configure the port statement with the desired port number at the [edit system services netconf ssh] hierarchy level.
      [edit system services]user@host# set netconf ssh port port-number

      The port-number can range from 1 through 65535. The configured port accepts only NETCONF-over-SSH sessions and rejects regular SSH session requests.

      Note: Although NETCONF-over-SSH can be configured on any port from 1 through 65535, you should avoid configuring access on a port that is normally assigned for another service. This practice avoids potential resource conflicts. If you configure NETCONF-over-SSH on a port assigned for another service, such as FTP, and that service is enabled, a commit check does not reveal a resource conflict or issue any warning message to that effect.

    • To enable access over the default SSH port (22), include the ssh statement at the [edit system services] hierarchy level. This configuration enables SSH access to the device for all users and applications. The ssh statement can be included in the configuration in addition to the NETCONF-over-SSH configuration statements listed above.
      [edit system services]user@host# set ssh
  2. Commit the configuration:
    [edit]user@host# commit
  3. Repeat the preceding steps on each device running Junos OS where the client application will establish NETCONF sessions.

Establishing an Outbound SSH Connection

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

Configuring the Device Running Junos OS for Outbound SSH

To configure the device running Junos OS for outbound SSH:

  1. At the [edit system services ssh] hierarchy level, set the SSH protocol-version to v2:
    [edit system services ssh]user@host# set protocol-version v2
  2. Generate or obtain a public/private key pair for the device running Junos OS. This key pair will be used to encrypt the data transferred across the SSH connection. For more information on generating key pairs, see the Junos System Basics Configuration Guide.
  3. If the public key will be installed on the configuration management server manually, transfer the public key to the configuration management server.
  4. Add the following outbound-ssh statement at the [edit system services] hierarchy level:
    [edit system services]outbound-ssh {client client-id {device-id device-id;secret secret;keep-alive {retry numbertimeout number;}reconnect-strategy (sticky | in-order);services netconf;[ address ] {port destination-port;retry number;timeout number;}}traceoptions {file filename {files files;size size;match match;(world-readable | no-world-readable);}flag (all | configuration | connectivity );no-remote-trace;}}

    The attributes are as follows:

    • client client-id—outbound-ssh configuration stanza on the device. Each outbound-ssh stanza represents a single outbound SSH connection. This attribute is not sent to the client.

      device-id device-id—Unique ID identifying the device running Junos OS to the configuration management server during the initiation process.

    • secret secret—(Optional) Public SSH host key of the device. If this statement is added to the outbound-ssh configuration hierarchy, the device will pass its public key to the configuration management server during the initialization of the outbound SSH service. This is the recommended method of maintaining a current copy of the device's public key on the configuration management server.
    • keep-alive—(Optional) Specify that keepalive messages be sent from the device running Junos OS to the configuration management server. To configure the keepalive message, you must set both the timeout and retry attributes.
      • retry number—Number of keepalive messages the device running Junos OS sends without receiving a response from the configuration management server before the current SSH connection is terminated. The default is three tries.
      • timeout seconds—Amount of time, in seconds, that the server waits for data before sending a keepalive signal. The default is 15 seconds.
    • reconnect-strategy (sticky | in-order)—(Optional) Method that the device running Junos OS uses to reestablish a disconnected outbound SSH connection. Two methods are available:
      • sticky—The device attempts to reconnect to the configuration management server to which it was last connected. If the connection is unavailable, the device attempts to establish a connection with the next configuration management server on the list and so forth until a connection is established.
      • in-order—The device attempts to reestablish an outbound SSH session based on the configuration management server address list. The device attempts to establish a session with the first server on the list. If this connection is not available, the device attempts to establish a session with the next server, and so on down the list until a connection is established.

      When reconnecting to a client, the device running Junos OS attempts to reconnect to the client based on the retry and timeout values for each client listed in the configuration management server list.

    • services netconf—(Required) Specifies the services available for the session. Currently, NETCONF is the only service available.
    • address—(Required) The host name or the IPv4 address of the configuration management server. You can list multiple clients by adding each client's IP address or host name along with the connection parameters listed below:
      • port destination-port—Outbound SSH port for the client. The default is port 22.
      • retry number– Number of times the device running Junos OS attempts to establish an outbound SSH connection before gving up. The default is three tries.
      • timeout seconds—Amount of time, in seconds, that the device running Junos OS attempts to establish an outbound SSH connection before giving up. The default is 15 seconds.
    • file filename—(Optional) Filename of the log file used to record the trace options. By default it is the name of the traced process (for example mib2d or snmpd). Use this option to override the default value.
    • files files—(Optional) Maximum number of trace files generated. By default, the maximum number of trace files is 10. Use this option to override the default value.

      When a trace file reaches its maximum size, the system archives the file and starts a new file. The system archives trace files by appending a number to the filename in sequential order from 1 to the maximum value (specified by the default value or the options value set here). Once the maximum value is reached, the numbering sequence is restarted at 1, overwriting the older file.

    • size size—(Optional) The maximum size of the trace file in kilobytes (KB). Once the maximum file size is reached, the system will archive the file. The default value is 1 MB. Use this option to override the default value.
    • match match—(Optional) Add lines to the trace file that match the the regular expression specified. For example, if the match value is set to =error, the system will only record lines to the trace file that include the string error.
    • (world-readable | no-world-readable)—(Optional) This option specifies whether the files are accessible by the originator of the trace operation only or by any user. By default, log files are only accessible by the user that started the trace operation (no-world-readable). Use this option to override the default value.
    • (all | configuration | connectivity)—(Optional) Flag specifying the type of tracing operation to perform.
      • all—Log all events.
      • configuration—Log all events pertaining to the configuration of the device running Junos OS.
      • connectivity—Log all events pertaining to the establishment of a connection between the client server and the device running Junos OS.
    • no-remote-trace—(Optional) Disables remote tracing.
  5. Commit the configuration:
    [edit]user@host# commit

Installing SSH Software on the Client

Once the device establishes the SSH connection to the configuration management server, the configuration management server takes control of the SSH session. Therefore, the SSH client software must be installed locally on the configuration management server.

If the client application accessing the NETCONF server 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 client application does not use theNETCONF Perl module, obtain the SSH client software and install it on the configuration management server where the application runs. For information about obtaining and installing SSH software, see http://www.ssh.com/ and http://www.openssh.com/ .

Receiving and Managing the Outbound SSH Initiation Sequence on the Client

When configured for outbound SSH, the device running Junos OS attempts to maintain a constant connection with a configuration management server. Whenever an outbound SSH session is not established, the device sends an outbound SSH initiation sequence to a configuration management server listed within the device’s configuration management server list. Prior to establishing a connection with the device, each configuration management server must be set up to receive this initiation sequence, establish a TCP connection with the device, and transmit the device identity back to the device.

The initiation sequence takes one of two forms, depending on how you chose to handle the Junos server's public key.

If the public key is installed manually on the configuration management server, the initiation sequence takes the following form:

MSG-ID: DEVICE-CONN-INFO\r\n
MSG-VER: V1\r\n
DEVICE-ID: <device-id>\r\n

If the public key is forwarded to the configuration management server by the device during the initialization sequence, the sequence takes the following form:

MSG-ID: DEVICE-CONN-INFO\r\n
MSG-VER: V1\r\n
DEVICE-ID: : <device-id>\r\n
HOST-KEY: <pub-host-key>\r\n
HMAC: <HMAC(pub-SSH-host-key,<secret>)>\r\n

Enabling NETCONF Service over SSH

RFC 4742, Using the NETCONF Configuration Protocol over Secure SHell (SSH), requires that the NETCONF server, by default, provide the client device with SSH access to the server over a dedicated TCP port. Use of a dedicated port makes it easy to identify and filter NETCONF traffic. The Internet Assigned Numbers Authority (IANA) port for NETCONF-over-SSH sessions is 830.

You also can enable access to the NETCONF server either over the default SSH port (22) or over a port number that is explicitly configured on the device running Junos OS. If you specify the NETCONF-over-SSH port number in the device configuration, the configured port accepts only NETCONF-over-SSH sessions and rejects regular SSH session requests. The default SSH port (22) continues to accept NETCONF sessions even when an alternate NETCONF-over-SSH port is configured. For added security, you can configure event policies that utilize UI_LOGIN_EVENT information to effectively disable the default port or further restrict NETCONF server access on a port.

To enable NETCONF service over SSH, perform the following steps:

  1. Include one of the following statements at the indicated hierarchy level:
    • To enable SSH access over the default NETCONF-over-SSH port (830) as specified by RFC 4742, include the ssh statement at the [edit system services netconf] hierarchy level:
      [edit system services]user@host# set netconf ssh
    • To enable SSH access over a specified port number, configure the port statement with the desired port number at the [edit system services netconf ssh] hierarchy level.
      [edit system services]user@host# set netconf ssh port port-number

      The port-number can range from 1 through 65535. The configured port accepts only NETCONF-over-SSH sessions and rejects regular SSH session requests.

      Note: Although NETCONF-over-SSH can be configured on any port from 1 through 65535, you should avoid configuring access on a port that is normally assigned for another service. This practice avoids potential resource conflicts. If you configure NETCONF-over-SSH on a port assigned for another service, such as FTP, and that service is enabled, a commit check does not reveal a resource conflict or issue any warning message to that effect.

    • To enable access over the default SSH port (22), include the ssh statement at the [edit system services] hierarchy level. This configuration enables SSH access to the device for all users and applications. The ssh statement can be included in the configuration in addition to the NETCONF-over-SSH configuration statements listed above.
      [edit system services]user@host# set ssh
  2. Commit the configuration:
    [edit]user@host# commit
  3. Repeat the preceding steps on each device where the client application will establish a NETCONF session.

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 an SSH 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:

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 10.3 emits the following <hello> tag element (each <capability> tag element appears on three lines for legibility only):

<hello><capabilities><capability>urn:ietf:params:xml:ns:netconf:base:1.0</capability><capability>urn:ietf:params:xml:ns:netconf:capability:candidate:1.0</capability><capability>urn:ietf:params:xml:ns:netconf:capability:confirmed-commit:1.0</capability><capability>urn:ietf:params:xml:ns:netconf:capability:validate:1.0</capability><capability>urn:itf:params:xml:ns:netconf:capability:url:1.0?protocol=http,ftp,file</capability><capability>http://xml.juniper.net/netconf/junos/1.0</capability></capabilities><session-id>3911</session-id></hello>]]>]]>

(For information about the ]]>]]> character sequence, see Generating Well-Formed XML Documents.)

The URIs in the <hello> tag element indicate the following supported capabilities:

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:

<hello><capabilities><capability>first-capability</capability> <!-- tag elements for additional capabilities --></capabilities></hello>]]>]]>

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:

<rpc><get-software-information/></rpc>]]>]]>

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. (For information about the <rpc-reply> tag element, see Parsing the NETCONF Server Response.) 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 form 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:

Copyright© 1999-2010 Juniper Networks, Inc. All rights reserved.