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

Exchanging Information with the NETCONF Server

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. The following sections describe the exchange of tagged data:

Sending a Request to the NETCONF Server

To initiate a request to the NETCONF server, a client application emits the opening <rpc> tag, followed by one or more tag elements that represent the particular request, and the closing </rpc> tag, in that order:


<rpc>
    <!- - tag elements representing a request - ->
</rpc>
]]>]]>

Each request is enclosed in its own separate pair of opening <rpc> and closing </rpc> tags and must constitute a well-formed XML document by including only compliant and correctly ordered tag elements. For information about the]]>]]> character sequence, see Generating Well-Formed XML Documents. For an example of emitting an <rpc> tag element in the context of a complete NETCONF session, see Example of a NETCONF Session.

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. For more information, see Spaces, Newline Characters, and Other White Space.

See the following sections for further information:

Request Classes

A client application can make three classes of requests:

Note: 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 element, so a client application can freely alternate operational and configuration requests.

Operational Requests

Operational requests are requests for information about C Series Controller status, and correspond to the CLI operational mode commands listed in the SRC software command references. The SRC XML API defines a request tag element for many CLI commands. For example, the <get-interfaces> tag element corresponds to the show interfaces command, and the <get-system-info> tag element requests the same information as the show system information command.

The following sample request is for information about the interface called eth0:


<rpc>
    <get-interfaces>
        <interface-name>eth0</interface-name>
    </get-interfaces>
</rpc>
]]>]]>

For more information, see Requesting Operational Information. For information about the XML request tag elements available in the current SRC software release, see the SRC XML API Operational Reference.

Configuration Information Requests

Requests for configuration information are requests for information about the current configuration, either candidate or committed (the one currently in active use on the C Series Controller). The candidate and committed configurations diverge when there are uncommitted changes to the candidate configuration.

The NETCONF API defines the <get-config> tag element for retrieving configuration information. The SRC XML API defines a tag element for every CLI configuration statement described in the SRC software documentation set.

The following example shows how to request information from the [edit system login] hierarchy level of the candidate configuration:


<rpc>
    <get-config>
        <source>
            <candidate/>
        </source>
        <filter type="subtree">
            <configuration>
                <system>
                    <login/>
                </system>
            </configuration>
        </filter>
    </get-config>
</rpc>
]]>]]>

For more information, see Requesting Configuration Information. For a summary of the available configuration tag elements, see the SRC XML API Configuration Reference.

Configuration Change Requests

Configuration change requests are requests to change the candidate configuration, or to commit those changes to put them into active use on the C Series Controller. The NETCONF API defines the <edit-config> and <copy-config> tag elements for changes to the configuration. The SRC XML API defines a tag element for every CLI configuration statement described in the SRC software documentation set.

The following example shows how to create a new user account called admin at the [edit system login] hierarchy level in the candidate configuration:


<rpc>
    <edit-config>
        <target>
            <candidate/>
        </target>
        <config>
            <configuration>
                <system>
                    <login>
                        <user>
                            <user-name>admin</user-name>
                            <full-name>Administrator</full-name>
                            <class>super-user</class>
                        </user>
                    </login>
                </system>
            </configuration>
        </config>
    </edit-config>
</rpc>
]]>]]>

For more information, see Changing Configuration Information. For a summary of SRC XML configuration tag elements, see the SRC XML API Configuration Reference.

Including Attributes in the Opening <rpc> Tag

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

This feature can be used to associate requests and responses if the value assigned to an attribute by the client application is unique in each opening <rpc> tag. Because the NETCONF server echoes the attribute unchanged, it is simple to map the response to the initiating request. The NETCONF specification specifies the name message-id for this attribute.

Parsing the NETCONF Server Response

The NETCONF server encloses its response to each client request in a separate pair of opening <rpc-reply> and closing </rpc-reply> tags, each of which constitutes a well-formed XML document. In the opening <rpc-reply> tag, it includes the xmlns and xmlns:sdx attributes (the opening tag appears here 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" \
                [echoed attributes]>
    <!- - tag elements representing a response - ->
</rpc-reply>
]]>]]>

The xmlns attribute defines the namespace for enclosed tag elements that do not have the sdx: prefix on their names and that are not enclosed in a child container tag that has the xmlns attribute with a different value.

The xmlns:sdx attribute defines the namespace for enclosed tag elements that have the sdx: prefix on their names.

For information about the ]]>]]> character sequence, see Generating Well-Formed XML Documents. For information about echoed attributes, see Including Attributes in the Opening <rpc> Tag.

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. See the following sections for further information:

NETCONF Server Response Classes

The NETCONF server returns three classes of responses:

Operational Responses

Operational responses are responses to requests for information about C Series Controller status. They correspond to the output from CLI operational commands as described in the SRC CLI command references.

The SRC 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-system-info> tag element in a response tag element called <system-info>.

The following sample response includes information about the C Series Controller. The namespace indicated by the xmlns attribute in the opening <system-info> tag is for system information. The opening tags appear on two lines here 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 sdx:style="normal"\
                xmlns="http://xml.juniper.net/sdx/system-info"\
                xmlns:sdx="http://xml.juniper.net/sdx">
        <cpu xmlns="http://xml.juniper.net/sdx/cpu">
            <number>4</number>
            <model>Dual Core AMD Opteron(tm) Processor 265</model>
            <speed>1804.108 MHz</speed>
        </cpu>
        <!- - other data tag elements for <system-info> - ->
    </system-info>
</rpc-reply>
]]>]]>

For more information about the xmlns attribute and the contents of operational response tag elements, see Requesting Operational Information. For a summary of operational response tag elements, see the SRC XML API Operational Reference.

Configuration Information Responses

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

The following sample response includes the information at the [edit system login] hierarchy level in the configuration hierarchy. For brevity, the sample shows only one user defined at this level. The opening <rpc-reply> tag appears on two lines for legibility only. For information about the attributes in the opening <configuration> tag, see Requesting Information from the Candidate Configuration.


<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"\
                xmlns:sdx="http://xml.juniper.net/junos/sdx/1.0">
    <data>
        <configurationattributes>
            <system>
                <login>
                    <user>
                        <user-name>admin</user-name>
                        <full-name>Administrator</full-name>
                        <!- - other data tag elements for the admin user - ->
                    </user>
                </login>
            </system>
        </configuration>
    </data>
</rpc-reply>
]]>]]>

Configuration Change Responses

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


<rpc-reply xmlns="URN "xmlns:sdx="URL”>
    <ok/>
</rpc-reply>
]]>]]>

If the operation fails, the <rpc-reply> tag element instead encloses an <rpc-error> tag element that describes the cause of the failure. For information about handling errors, see Handling an Error or Warning.

For information about changing C Series Controller configuration, see Changing Configuration Information. For a summary of the available configuration tag elements, see the SRC XML API Configuration Reference.

Using a Standard API to Parse Response Tag Elements

Client applications can handle incoming XML tag elements by feeding them to a parser that is based on a standard API such as the Document Object Model (DOM) or Simple API for XML (SAX). Describing how to implement and use a parser is beyond the scope of this document.

Routines in the DOM accept incoming XML and build a tag hierarchy in the client application’s memory. There are also DOM routines for manipulating an existing hierarchy. DOM implementations are available for several programming languages, including C, C++, Perl, and Java. For detailed information, see the Document Object Model (DOM) Level 1 Specification from the World Wide Web Consortium (W3C) at http://www.w3.org/TR/REC-DOM-Level-1. Additional information is available from the Comprehensive Perl Archive Network (CPAN) at http://search.cpan.org/~tjmather/XML-DOM/lib/XML/DOM.pm.

One potential drawback with DOM is that it always builds a hierarchy of tag elements, which can become very large. If a client application needs to handle only a subhierarchy at a time, it can use a parser that implements SAX instead. SAX accepts XML and feeds the tag elements directly to the client application, which must build its own tag hierarchy. For more information, see the official SAX website at http://sax.sourceforge.net.

Handling an Error or Warning

If the NETCONF server encounters an error condition, it emits an <rpc-error> tag element containing tag elements that describe the error:


<rpc-reply xmlns="URN "xmlns:sdx="URL”>
    <rpc-error>
        <error-severity>error-severity</error-severity>
        <error-path>error-path</error-path>
        <error-message>error-message</error-message>
        <error-info>
            <bad-element>command-or-statement</bad-element>
        </error-info>
    </rpc-error>
</rpc-reply>
]]>]]>
  • <bad-element> identifies the command or configuration statement that was being processed when the error or warning occurred. For a configuration statement, the <error-path> tag element enclosed in the <rpc-error> tag element specifies the statement’s parent hierarchy level.
  • <error-message> describes the error or warning in a natural-language text string.
  • <error-path> specifies the path to the configuration hierarchy level at which the error or warning occurred, in the form of the CLI configuration mode banner.
  • <error-severity> indicates the severity of the event that caused the NETCONF server to return the <rpc-error> tag element. The two possible values are error and warning.

An error can occur while the server is performing any of the following operations, and the server can send a different combination of child tag elements in each case:

  • Processing an operational request submitted by a client application
  • Changing, committing, or closing a configuration as requested by a client application
  • Parsing a configuration submitted by a client application in an <edit-config> tag element

Client applications must be prepared to receive and handle an <rpc-error> tag element at any time. The information in any response tag elements already received and related to the current request might be incomplete. The client application can include logic for deciding whether to discard or retain the information.

When the <error-severity> tag element has the value error, the usual response is for the client application to discard the information and terminate. When the <error-severity> tag element has the value warning, indicating that the problem is less serious, the usual response is for the client application to log the warning or pass it to the user, but to continue parsing the server’s response.

Modified: 2016-06-02