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> </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 XML and NETCONF XML Management Protocol Conventions Overview.

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 the status of a device running Junos OS. Operational requests correspond to the CLI operational mode commands listed in the Junos OS command references. The Junos XML API defines a request tag element for many CLI commands. For example, the <get-interface-information> tag element corresponds to the show interfaces command, and the <get-chassis-inventory> tag element requests the same information as the show chassis hardware command.

The following sample request is for detailed information about the interface ge-2/3/0:

For more information, see Requesting Operational Information. For information about the Junos XML request tag elements available in the current Junos OS Release, see the Junos XML API Operational Reference.

Configuration Information Requests

Configuration information requests are requests for information about the device’s candidate configuration, a private configuration, or the committed configuration (the one currently in active use on the switching, routing, or security platform). The candidate and committed configurations diverge when there are uncommitted changes to the candidate configuration.

The NETCONF protocol defines the <get-config> operation for retrieving configuration information. The Junos XML API defines a tag element for every container and leaf statement in the configuration hierarchy.

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

For more information, see Requesting Configuration Information. For a summary of the available configuration tag elements, see the Junos 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 device running Junos OS. The NETCONF protocol defines the <edit-config> and <copy-config> operations for changing configuration information. The Junos XML API defines a tag element for every CLI configuration statement described in the Junos OS configuration guides.

The following example shows how to create a new Junos OS 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><name>admin</name><full-name>Administrator</full-name><class>superuser</class></user></login><login/></system></configuration></config></edit-config></rpc>]]>]]>

For more information, see Changing Configuration Information. For a summary of Junos XML configuration tag elements, see the Junos 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 for each request. The NETCONF server echoes each attribute, unchanged, in the opening <rpc-reply> tag in which it encloses its response.

A client application can use this feature to associate requests and responses by including an attribute in each opening <rpc> request tag that assigns a unique identifier. The NETCONF server echoes the attribute in its opening <rpc-reply> tag, making it easy 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 response constitutes a well-formed XML document. The opening <rpc-reply> tag includes the xmlns and xmlns:junos 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:junos="http://xml.juniper.net/junos/release/junos" \
                [echoed attributes]>
    <!-- tag elements representing a response -->
</rpc-reply>
]]>]]>

The xmlns attribute defines the namespace for enclosed tag elements that do not have the junos: 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:junos attribute defines the namespace for enclosed Junos XML tag elements that have the junos: prefix on their names. The variable release is replaced by a code such as 10.3R1 for the initial version of Junos OS Release 10.3.

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 the status of a switching, routing, or security platform. They correspond to the output from CLI operational commands as described in the Junos command references.

The Junos 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-interface-information> tag element in a response tag element called <interface-information> and returns the information requested by the <get-chassis-inventory> tag element in a response tag element called <chassis-inventory>.

The following sample response includes information about the interface ge-2/3/0. The namespace indicated by the xmlns attribute in the opening <interface-information> tag is for interface information in the initial version of Junos OS Release 10.3. The opening tags appear on two lines here for legibility only:

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"\
                xmlns:junos="http://xml.juniper.net/junos/10.3R1/junos">
    <interface-information \
                xmlns="http://xml.juniper.net/junos/10.3R1/junos-interface">
        <physical-interface>
            <name>ge-2/3/0</name>
            <!-- other data tag elements for the ge-2/3/0 interface -  ->
        </physical-interface>
    </interface-information>
</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 Junos XML API Operational Reference.

Configuration Information Responses

Configuration information responses are responses to requests for information about the device’s current configuration. The Junos 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 Committed or Candidate Configuration.

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"\xmlns:junos="http://xml.juniper.net/junos/10.3R1/junos"><data><configuration attributes><system><login> <user><name>admin</name><full-name>Administrator</full-name></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 device 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:junos="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 the device configuration, see Changing Configuration Information. For a summary of the available configuration tag elements, see the Junos 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 one 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:junos="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 Junos OS 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
Locking, changing, committing, or closing a configuration as requested by a client application
Parsing configuration data 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 and to continue parsing the server’s response.