Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

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

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:

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

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:

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:

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:

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

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

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

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

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:

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.

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:

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

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

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:

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