Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation  Back up to About Overview 
ContentIndex
  
[+] Expand All
[-] Collapse All

Symbols  A  C  D  E  I  J  K  L  M  N  O  P  R  S  T  W  X

 

Symbols

<bad-element> tag (NETCONF)    
usage guidelines
<candidate/> tag (NETCONF)    
usage guidelines    
changing configuration
locking configuration
replacing entire configuration
requesting configuration
unlocking configuration
<capabilities> tag (NETCONF)    
usage guidelines
<capability> tag (NETCONF)    
usage guidelines
<close-session/> tag (NETCONF)    
usage guidelines
<commit> tag (NETCONF)    
usage guidelines    
regular commit
<config> tag (NETCONF)    
usage guidelines
<configuration> tag (SRC XML)
<copy-config> tag (NETCONF)    
usage guidelines
<data> tag (NETCONF)    
usage guidelines
<default-operation> tag (NETCONF)    
usage guidelines    
deleting configuration
general
replacing configuration
<discard-changes> tag (NETCONF)    
usage guidelines
<edit-config> tag (NETCONF)    
usage guidelines
<error-info> tag (NETCONF)    
usage guidelines
<error-message> tag (NETCONF)    
usage guidelines
<error-path> tag (NETCONF)    
usage guidelines
<error-severity> tag (NETCONF)    
usage guidelines
<filter> tag (NETCONF)    
usage guidelines
<get-config> tag (NETCONF)    
usage guidelines    
all objects of type
complete configuration
hierarchy level
identifiers only
multiple elements
overview
single object
specific children
<hello> tag (NETCONF)    
usage guidelines
<kill-session> tag (NETCONF)    
usage guidelines
<lock> tag (NETCONF)    
usage guidelines
<ok/> tag (NETCONF)    
usage guidelines
<output> tag (SRC XML)
<rpc-error> tag (NETCONF)    
usage guidelines
<rpc-reply> tag (NETCONF)    
usage guidelines
<rpc> tag (NETCONF)    
usage guidelines
<session-id> tag (NETCONF)    
usage guidelines    
initializing session
terminating session
<source> tag (NETCONF)    
usage guidelines    
replacing entire configuration
requesting configuration
<target> tag (NETCONF)    
usage guidelines    
changing configuration
locking configuration
replacing entire configuration
unlocking configuration
<unlock> tag (NETCONF)    
usage guidelines
<url> tag (NETCONF)    
usage guidelines    
changing configuration
replacing entire configuration
]]>]]> character sequence (NETCONF)    
usage guidelines
 

A

access    
protocols for NETCONF
attributes    
NETCONF tags    
For usage guidelines, see names of individual attributes
in <rpc> echoed in <rpc-reply>
SRC XML tags    
For usage guidelines, see names of individual attributes
authentication    
NETCONF
 

C

child tags (XML).     See tags (XML)    
commands    
mapping options to SRC XML tags    
fixed-form
variable-form
comments    
NETCONF and XML
compatibility    
between NETCONF server and application
configuration    
changing    
NETCONF (overview)
committing    
immediately (NETCONF)
creating    
element only if new (NETCONF)
deleting    
hierarchy level (NETCONF)
multiple values from leaf (NETCONF)
object (NETCONF)
overview (NETCONF)
single option (NETCONF)
discarding changes    
NETCONF
displaying    
candidate (NETCONF)
entire (NETCONF)
hierarchy level (NETCONF)
identifiers (NETCONF)
multiple elements at once (NETCONF)
objects of specific type (NETCONF)
overview (NETCONF)
single object (NETCONF)
specific children of object (NETCONF)
loading    
as a data stream (NETCONF)
as data in a file (NETCONF)
default mode for NETCONF
locking    
NETCONF
merging current and new    
NETCONF
modifying    
NETCONF
NETCONF operations on
replacing    
entire (NETCONF)
single element (NETCONF)
rolling back to previous    
NETCONF
statements.     See configuration statements    
unlocking    
NETCONF
verifying    
NETCONF
configuration statements    
deleting    
NETCONF
mapping to Junos XML tags    
multiple options on one line
mapping to SRC XML tags    
hierarchy level or container tag
identifiers
keywords
leaf statements
multiple values for an option
conventions    
NETCONF    
for client to comply with
notice icons
text
create (NETCONF 'operation' attribute)    1
usage guidelines
customer support    1
contacting JTAC
 

D

default mode for NETCONF configuration changes
delete (NETCONF 'operation' attribute)    1
usage guidelines
display xml command    
usage guidelines
Document Object Model.     See DOM    
document type definition.     See DTD    
documentation    
comments on
DOM
DTD    
defined
separate for each SRC software module
 

E

entity references, predefined (SRC XML)
error messages    
from NETCONF server
examples, Junos XML    
mapping of configuration statement to tag    
multiple options on multiple lines
multiple options on single line
examples, NETCONF    
creating configuration elements
deleting    
fixed-form option
hierarchy level
single configuration object
value from list of multiple values
merging in new configuration data
providing configuration data    
in a file
in a stream
replacing configuration elements
requesting    
all objects of a type
identifiers only
one configuration level
one configuration object
specific children of object
session
terminating session
examples, SRC XML    
mapping of configuration statement to tag    
hierarchy levels
identifier
leaf statement with keyword and value
leaf statement with keyword only
multiple predefined values for option
multiple user-defined values for option
Extensible Markup Language.     See XML    
 

I

identifiers    
SRC XML mapping
 

J

Junos XML tags    
mapping    
configuration, multiple multioption lines
 

K

keyword in configuration statement, SRC XML mapping
 

L

leaf statement    
SRC XML mapping
 

M

manuals    
comments on
 

N

namespaces.     See XML, namespaces    
NETCONF API    
comments, treatment of
conventions
overview
server.     See NETCONF server    
session.     See NETCONF session    
tags    
For usage guidelines, see names of individual tags
white space, treatment of
NETCONF server    
classes of responses emitted
closing connection to
connecting to
error message from
establishing session with
overview
parsing output from
sending request to
verifying compatibility with application
warning from
NETCONF session    
authentication and security
brief overview
ending
establishing
example
terminating another
NETCONF tags    
For usage guidelines, see names of individual tags
notational conventions
newline character in XML tag sequences
no-change mode (NETCONF)
notice icons
 

O

operation attribute (SRC XML with NETCONF)    1
usage guidelines    
creating element
deleting element
replacing element
operational mode, CLI    
SRC XML mapping    
for requests
for responses
options in configuration statements, SRC XML mapping
output from NETCONF server, parsing
 

P

predefined entity references (SRC XML)
prerequisites    
NETCONF API
 

R

replace (NETCONF 'operation' attribute)    1
usage guidelines
replace mode (NETCONF)
request tags (XML).     See tags (XML)    
response tags (XML).     See tags (XML)    
routers    
configuration.     See configuration    
 

S

SAX (Simple API for XML)
sdx:changed-localtime attribute (SRC XML)    
usage guidelines
sdx:changed-seconds attribute (SRC XML)    
usage guidelines
security    
NETCONF session
session, NETCONF.     See NETCONF session    
Simple API for XML.     See SAX    
software versions    
compatibility between NETCONF client and server
space character in XML tag sequences
SRC XML API    
overview
predefined entity references
tags.     See SRC XML tags    
SRC XML tags    
<configuration>    1
attributes in
<output>
displaying CLI output as
mapping    
command options, fixed-form
command options, variable
configuration, hierarchy level
configuration, identifier
configuration, multivalue leaf
configuration, single-value leaf
notational conventions
ssh service    
NETCONF access protocol
support, technical     See technical support    
 

T

tags (XML)    
NETCONF    
For usage guidelines, see names of individual tags
request    
children of
defined
NETCONF
SRC XML
response    
<rpc-reply> as container for
children of
defined
NETCONF
SRC XML
SRC XML     See SRC XML tags    
white space in and around
technical support    
contacting JTAC
text conventions defined
 

W

warning    
from NETCONF server
white space in XML tag sequences
 

X

XML    
namespaces    1
defined for operational response tags
overview
tags.     See tags (XML)    
xmlns attribute    
<configuration> tag    
usage guidelines
NETCONF    
usage guidelines
SRC XML operational responses    
usage guidelines

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:

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.


<!- - 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 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

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:

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

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

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

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):


<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:url:1.0?protocol=http,ftp,file
        </capability>
        <capability>http://xml.juniper.net/netconf/junos/1.0</capability>
        <capability>http://xml.juniper.net/netconf/junos/sdx/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:

  • 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:


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


<rpc>
    <get-system-info/>
</rpc>
]]>]]>

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:


<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" \
                xmlns:sdx="http://xml.juniper.net/junos/sdx/1.0">
    <system-info>
        <system-identification>
            <software-version>SRC Release 2.0.0</software-version>
            <!- - other <system-identification> child tag elements - ->
        </system-identification>
        <!- - other <system-info> child tag elements - ->
    </system-info>
</rpc-reply>
]]>]]>

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:


<rpc>
    <get-component-all/>
</rpc>
]]>]]>

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:


<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" \
                xmlns:sdx="http://xml.juniper.net/junos/sdx/1.0">
    <sdx-component-list>
        <sdx-component>
            <status>stopped</status>
            <version>Release: 2.0 Build: ACP.B.2.0.0.001</version>
            <name>acp</name>
        </sdx-component>
        <!- - other <sdx-component> tag elements - ->
        <sdx-component>
            <status>running</status>
            <version>Release: 2.0 Build: WEBADM.B.2.0.0.001</version>
            <name>webadm</name>
        </sdx-component>
    </sdx-component-list>
</rpc-reply>
]]>]]>

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.

Modified: 2016-06-02