H3C Comware 7 NETCONF API
Developers Guide

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Preface

This guide is intended for network administrators and operators to configure and manage Comware-based devices from a NETCONF client.

This preface includes the following topics about the documentation:

·     Audience

·     Conventions

·     Documentation feedback

Audience

This documentation is intended for:

·     Network planners that have knowledge of XML and NETCONF.

·     Network administrators that manage Comware-based devices from a NETCONF client.

Conventions

Command conventions

Convention	Description
Boldface	Bold text represents commands and keywords that you enter literally as shown.
Italic	Italic text represents arguments that you replace with actual values.
[ ]	Square brackets enclose syntax choices (keywords or arguments) that are optional.
{ x | y | ... }	Braces enclose a set of required syntax choices separated by vertical bars, from which you select one.
[ x | y | ... ]	Square brackets enclose a set of optional syntax choices separated by vertical bars, from which you select one or none.
{ x | y | ... } *	Asterisk marked braces enclose a set of required syntax choices separated by vertical bars, from which you select a minimum of one.
[ x | y | ... ] *	Asterisk marked square brackets enclose optional syntax choices separated by vertical bars, from which you select one choice, multiple choices, or none.
&<1-n>	The argument or keyword and argument combination before the ampersand (&) sign can be entered 1 to n times.
#	A line that starts with a pound (#) sign is comments.

 

Symbols

Convention	Description
WARNING!	An alert that calls attention to important information that if not understood or followed can result in personal injury.
CAUTION:	An alert that calls attention to important information that if not understood or followed can result in data loss, data corruption, or damage to hardware or software.
IMPORTANT:	An alert that calls attention to essential information.
NOTE:	An alert that contains additional or supplementary information.
TIP:	An alert that provides helpful information.

 

Network topology icons

	Represents a generic network device, such as a router, switch, or firewall.
	Represents a routing-capable device, such as a router or Layer 3 switch.
	Represents a generic switch, such as a Layer 2 or Layer 3 switch, or a router that supports Layer 2 forwarding and other Layer 2 features.
	Represents an access controller, a unified wired-WLAN module, or the access controller engine on a unified wired-WLAN switch.
	Represents an access point.
	Represents a wireless terminator unit.
	Represents a wireless terminator.
	Represents a mesh access point.
	Represents omnidirectional signals.
	Represents directional signals.
	Represents a security product, such as a firewall, UTM, multiservice security gateway, or load balancing device.
	Represents a security module, such as a firewall, load balancing, NetStream, SSL VPN, IPS, or ACG module.

 

Examples provided in this document

Examples in this document might use devices that differ from your device in hardware model, configuration, or software version. It is normal that the port numbers, sample output, screenshots, and other information in the examples differ from what you have on your device.

Documentation feedback

You can e-mail your comments about product documentation to info@h3c.com.

We appreciate your comments.

 

Contents

About NETCONF· 1

NETCONF protocol stack· 1

Basic NETCONF architecture· 1

NETCONF message formats· 2

NETCONF· 2

NETCONF over SOAP· 4

Additional NETCONF message format conventions· 5

Protocols and standards· 6

Supported capability sets· 7

Supported protocol operations· 8

Using NETCONF to configure and manage the device· 9

Summary procedure· 9

Choosing a NETCONF client and session type· 10

NETCONF-based configuration methods· 10

NETCONF access methods· 11

Assigning access permissions to a NETCONF user on the device· 11

About NETCONF user access permissions· 11

Configuring user role rules for the NETCONF client 13

Configuring a user account for the NETCONF client 14

Configuring NETCONF session establishment settings· 15

Configuring settings for NETCONF over SSH· 15

Configuring NETCONF over SOAP over HTTP (or HTTPS) service· 16

Constructing XML NETCONF requests· 16

About NETCONF API references· 16

Using NETCONF API references to construct NETCONF requests· 18

Using XSD schema files to construct NETCONF requests· 19

Using YANG module files to construct NETCONF requests· 19

Connecting the NETCONF client to the target device· 19

Selecting a NETCONF access method· 19

Establishing a NETCONF over SOAP over HTTP (or HTTPS) session to the target device· 20

Establishing a NETCONF over SSH session to the target device· 24

Establishing a NETCONF over Telnet, SSH, or console to access the CLI of the target device· 24

Verifying that the NETCONF session has been established· 24

Testing the connectivity between the NETCONF client and the target device· 25

Exchanging capability sets· 25

Disconnecting a NETCONFsession· 26

Validating a NETCONF XML request file· 26

Integrating the validated XML request into the NETCONF client script or program·· 27

Best practices· 27

Fault tolerance· 27

Massive data retrieval 27

Session concurrency· 28

Termination of NETCONF over SOAP over HTTP or HTTPS sessions· 28

Event notification suppression· 28

Mixed use of HTTP and HTTPS· 28

FAQ·· 29

What should I do when no response is received to a NETCONF XML request in CLI?· 29

What should I do when I receive a request timeout error message on a SOAP-based NETCONF client such as SoapUI?  29

Device-supplied test commands· 29

About Comware NETCONF sessions· 30

Lifecycle of NETCONF sessions· 30

Lifecycle of NETCONF over SOAP sessions· 30

Lifecycle of NETCONF over console, Telnet or SSH sessions· 31

Request concurrency over one session· 31

RBAC-based access control 31

Configuration lock· 32

Maximum number of NETCONF sessions· 32

Executing Comware NETCONF requests· 32

Supported NETCONF operations· 32

Standard NETCONF operations· 34

get-config· 34

edit-config· 35

lock· 41

unlock· 42

get 43

close-session· 44

kill-session· 45

create-subscription· 46

validate· 52

get-schema· 52

netconf-state· 53

commit (immediate commit) 58

commit (confirmed commit) 58

commit (confirming commit) 59

cancel-commit 60

copy-config· 60

delete-config· 61

discard-changes· 61

Comware-extended protocol operations· 61

get-bulk· 61

get-bulk-config· 63

action· 64

load· 65

save· 66

rollback· 68

CLI 68

get-sessions· 73

save-point 75

Name-to-index conversion· 80

edit-config:incremental 81

cancel-subscription· 82

createDot1qFlow· 83

deleteDot1qFlow· 84

sortByName (for data retrieval operations) 85

xml2cli 86

Summary of NETCONF data operations· 96

About responses to data retrieval requests· 102

Returning data in tables, rows, or columns· 102

Returning empty data to a data retrieval request 104

Impact of RBAC on data retrieval results· 104

Impact of module-specific filters on data retrieval 104

Comware NETCONF data filtering· 105

Data filtering methods· 105

Exact match· 105

Regular expression match· 106

About regular expressions· 106

Example: Using a regular expression to filter data· 108

Conditional match· 110

About conditional match· 110

Example: Performing conditional match to filter data· 112

Filtering instances of a column· 113

Filtering instances of a group (data structure) 113

Example: Using ncclient for NETCONF-based device configuration and management 1

Setting up ncclient 1

About ncclient 1

Setting up the environment 1

Installing ncclient 1

Executing the script 2

Establishing a NETCONF session· 2

Configuring the target device for NETCONF session establishment 2

Running a script to establish a NETCONF session· 2

Basic device management with ncclient 4

Constructing an <edit-config> request 5

Constructing a <get> or <get-config> request for data retrieval 8

Constructing a <get-bulk> or <get-bulk-config> request for configuration and state data retrieval 10

Constructing an <action> request to perform a non-configuration operation· 13

Constructing a subscription request 14

Constructing an <xml2cli> request for XML-to-CLI conversion· 16

Appendixes· 1

Appendix A  Comware NETCONF operation error messages· 1

Error handling mechanism·· 1

Common schema errors· 1

Common NETCONF operation errors· 10

Appendix B  Comware schema built-in data types· 25

Appendix C  Treatment of Boolean or boolean values in Comware· 26

Appendix D  Common issues and recommendations· 26

Scenario-dependent columns· 26

IP and mask as indexes· 26

Order of same-level elements in a request 27

 

About NETCONF

Network Configuration Protocol (NETCONF) is an XML-based network management protocol. It provides a programmable mechanism to manage and configure network devices. Network administrators can use NETCONF to configure network devices and retrieve their configuration and operational data. On a network that has devices from different vendors, you can develop a NETCONF-based management system to configure and manage devices in a simple and effective way.

NETCONF protocol stack

The NETCONF protocol stack contains a content layer, operations layer, remote procedure call (RPC) layer, and transport protocol layer.

Table 1 NETCONF layer and XML layer mappings

NETCONF layer	XML layer	Description
Content	Configuration data, operational state data, and statistics	Contains a set of managed objects, which can be configuration data, operational state data, and statistics. For information about permission of access to the data nodes, see the NETCONF XML API references for the device.
Operations	<get>, <get-config>, <edit-config>…	Defines a set of base operations invoked as RPC methods with XML-encoded parameters. NETCONF base operations include data retrieval operations, configuration operations, lock operations, and session operations. For information about operations supported on the device, see "Supported protocol operations."
RPC	<rpc> and <rpc-reply>	Provides a simple, transport-independent framing mechanism for encoding RPCs. NETCONF uses <rpc> and <rpc-reply> elements to enclose requests and responses (data at the operations layer and the content layer).
Transport protocol	In non-FIPS mode: Console, Telnet, SSH, HTTP, HTTPS, and TLS In FIPS mode: Console, SSH, HTTPS, and TLS	Provides reliable, connection-oriented, serial data links. The following transport layer sessions are supported in non-FIPS mode: ·     CLI sessions, including NETCONF over Telnet, NETCONF over SSH, and NETCONF over console sessions. ·     NETCONF over HTTP and NETCONF over HTTPS sessions. ·     NETCONF over SOAP sessions, including NETCONF over SOAP over HTTP and NETCONF over SOAP over HTTPS sessions. The following transport layer sessions are supported in FIPS mode: ·     CLI sessions, including NETCONF over SSH and NETCONF over console sessions. ·     NETCONF over HTTPS sessions. ·     NETCONF over SOAP over HTTPS sessions.

 

Basic NETCONF architecture

As shown in Figure 1, NETCONF architecture is based on the client-server model.

·     A NETCONF client can be a script or application typically running as part of a network manager to manage or configure NETCONF servers. It can be NETCONF software such as ncclient or NetConf Browser or a script or program based on SOAP requests. The client invokes protocol operations on the servers for the following purposes:

¡     Configures or manages the network devices that act as NETCONF servers.

¡     Retrieves the state data from the network devices.

¡     Subscribes to notifications about events and alarms from the network devices.

·     A managed network device acts as a NETCONF server to execute protocol operations invoked by the client and sends event notifications to the client.

Figure 1 Basic NETCONF architecture

 

NETCONF message formats

NETCONF

All NETCONF messages are XML-encoded and comply with the formats defined in RFC 4741.

NETCONF requests and replies use different message formats.

The server checks every request against the XML schema before it processes them. If a request passes XML schema check, the server continues to process the request. If a request fails XML schema check, the server sends an error message to the client.

Request format (Base 1.0 capability set)

Comware supports the following generic NETCONF request message format:

<rpc message-id =”101” xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

  <operation>

</rpc>

The <operation> argument represents any operation elements listed in "Supported protocol operations."

·     A get request contains H3C-defined module information elements in the <top> subelement under the <filter> element. The following information takes the <get-config> request format for example:

<rpc message-id=”101” xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

  <get-config>

    <source>

      <running/>

    </source>

    <filter type=”subtree”>

      <top xmlns=”http://www.h3c.com/netconf/config:1.0”>

        Module information

      </top>

    </filter>

  </get-config>

</rpc>

·     An edit-config request contains H3C-defined module information elements in the <top> subelement under the <config> element, as shown below:

<rpc message-id =”101” xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

  <edit-config>

    <target>

      <running/>

    </target>

    <config xmlns:xc=”urn:ietf:params:xml:ns:netconf:base:1.0”>

      <top xmlns=”http://www.h3c.com/netconf/config:1.0”>

        Module information

      </top>

    </config>

  </edit-config>

</rpc>

For more information about the XML structures defined by H3C for the accessible data items, see the H3C Comware 7 NETCONF XML API reference for the module of interest.

The following example shows a NETCONF request that retrieves all data from all interfaces on the target device:

<?xml version="1.0" encoding="utf-8"?>

<rpc message-id ="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-bulk>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        <Ifmgr>

          <Interfaces>

             <Interface/>

          </Interfaces>

        </Ifmgr>

      </top>

    </filter>

  </get-bulk>

</rpc>

]]>]]>

 

IMPORTANT: In the XML view of the device, you must add the ]]>]]> end delimiter string at the end of every NETCONF message for the device to identify the messages. For simplicity, this document omits the ]]>]]> end delimiter string in all sample NETCONF messages except the previous one.

 

Response format (Base 1.0 capability set)

The response format is compliant with the <rpc-reply> message defined in RFC 4741. The following example shows the response to a successful NETCONF operation:

<rpc-reply xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0” message-id=”101”>

  <ok/>

</rpc-reply>

NETCONF over SOAP

All NETCONF over SOAP messages are contained in the <Body> element of SOAP messages. NETCONF over SOAP messages also comply with the following rules:

·     The SOAP messages must be XML encoded.

·     SOAP messages must use the SOAP Envelope namespaces and SOAP Encoding namespaces.

·     The SOAP messages cannot contain the following information:

¡     DTD references.

¡     XML processing instructions.

NETCONF over SOAP requests and replies use different message formats.

NETCONF over SOAP request format

The following example shows a NETCONF over SOAP request that retrieves all data from all interfaces on the target device:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">

  <env:Header>

    <auth:Authentication env:mustUnderstand="1" xmlns:auth="http://www.h3c.com/netconf/base:1.0">

      <auth:AuthInfo>100002ea7bd8f3bbb727c5eff9b246d85be6</auth:AuthInfo>

    </auth:Authentication>

  </env:Header>

  <env:Body>

    <rpc message-id ="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

      <get>

        <filter type="subtree">

          <top xmlns="http://www.h3c.com/netconf/data:1.0">

            <Ifmgr>

              <Interfaces>

                <Interface/>

              </Interfaces>

            </Ifmgr>

          </top>

        </filter>

      </get>

    </rpc>

  </env:Body>

</env:Envelope>

NETCONF over SOAP reply format

<env:Envelope xmlns:env=”http://schemas.xmlsoap.org/soap/envelope/”>

  <env:Header>

    <auth:Authentication env:mustUnderstand=”true” xmlns:auth=”http://www.h3c.com/netconf/base:1.0”>

      <auth:AuthInfo>10027c2abebdb482633f847102fbc890d22a</auth:AuthInfo>

    </auth:Authentication>

  </env:Header>

  <env:Body>

    <rpc-reply message-id=”101” xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

      <data>

        <top xmlns=”http://www.h3c.com/netconf/config:1.0”>

          <Syslog>

            <LogBuffer>

              <BufferSize>527</BufferSize>

            </LogBuffer>

            <LogHosts>

              <Host>

                <Address>1.1.1.1</Address>

                <VRF/>

                <Port>123</Port>

                <Facility>152</Facility>

              </Host>

              <Host>

                <Address>1.1.1.1</Address>

                <VRF>a</VRF>

                <Port>123</Port>

                <Facility>152</Facility>

              </Host>

              <Host>

                <Address>1.1.1.1</Address>

                <VRF>b</VRF>

                <Port>123</Port>

                <Facility>152</Facility>

              </Host>

              <Host>

                <Address>1.1.1.1</Address>

                <VRF>c</VRF>

                <Port>123</Port>

                <Facility>152</Facility>

              </Host>

            </LogHosts>

          </Syslog>

        </top>

      </data>

    </rpc-reply>

  </env:Body>

</env:Envelope>

Additional NETCONF message format conventions

CDATA nodes

The NETCONF server in Comware encloses the raw data output from CLI commands in CDATA tags to prevent misinterpretation of some data as XML markups. When the NETCONF client receives the response to a CLI operation, the NETCONF client must extract data from the CDATA tag.

Comments

You can add any valid XML comments in the NETCONF requests sent to a Comware-based device. The XML-encoded responses do not contain XML comments.

Spaces

To retain the leading or trailing spaces of a string in a request, you must escape the first leading space or the last trailing space, respectively. The escape rules are in compliance with the W3C XML specification. The NETCONF server will ignore the space sequences at the two ends of a string if they are not escaped.

In responses sent by the NETCONF server in Comware, the leading and trailing spaces in a string are automatically escaped.

Escaping XML data

Escape special characters or characters not available in the used encoding, in compliance with the W3C XML specification. For example, use the &#x09; string to escape the Tab character.

XML encoding

The Comware NETCONF server supports GB2312, GB18030, UTF-8, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, and UTF-32LE for XML data encoding. If a request does not specify an encoding format, UTF-8 encoding applies. The server uses the question mark (?) to replace any characters that are not convertible during character set conversion.

Protocols and standards

Table 2 shows the support of the Comware NETCONF implementation for NETCONF protocols and standards.

Table 2 Support of Comware for NETCONF protocols and standards

Protocol number	Protocol title	Support status
RFC 4741	NETCONF Configuration Protocol	Supported
RFC 4742	Using the NETCONF Configuration Protocol over Secure Shell (SSH)	Supported
RFC 4743	Using NETCONF over the Simple Object Access Protocol (SOAP)	Supported
RFC 4744	Using the NETCONF Protocol over the Blocks Extensible Exchange Protocol (BEEP)	Not supported
RFC 5277	NETCONF Event Notifications	Supported
RFC 5381	Experience of Implementing NETCONF over SOAP	Supported
RFC 5539	NETCONF over Transport Layer Security (TLS)	Not supported
RFC 5717	Partial Lock Remote Procedure Call (RPC) for NETCONF	Not supported
RFC 6020	YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)	Supported
RFC 6021	Common YANG Data Types	Supported
RFC 6022	YANG Module for NETCONF Monitoring	Supported
RFC 6087	Guidelines for Authors and Reviewers of YANG Data Model Documents	Supported
RFC 6241	Network Configuration Protocol	Supported
RFC 6242	Using the NETCONF Protocol over Secure Shell (SSH)	Supported
RFC 6243	With-defaults Capability for NETCONF	Not supported
RFC 7950	The YANG 1.1 Data Modeling Language	Supported

 

Supported capability sets

Table 3 presents the availability of standard and vendor-defined private capability sets with Comware at the time of this writing. The Protocol column displays a hyphen (‑) for private capability sets.

Table 3 NETCONF capability set implementation of Comware

RFC	Capability set	Status
RFC 4741	Base 1.0 urn:ietf:params:netconf:base:1.0	Supported
RFC 4741	Writable-Running urn:ietf:params:netconf:capability:writable-running:1.0	Supported
RFC 4741	Candidate Configuration urn:ietf:params:netconf:capability:candidate:1.0	Supported
RFC 4741	Confirmed Commit 1.0 urn:ietf:params:netconf:capability:confirmed-commit:1.0	Supported
RFC 4741	Rollback on Error urn:ietf:params:netconf:capability:rollback-on-error:1.0	Supported
RFC 4741	Validate 1.0 urn:ietf:params:netconf:capability:validate:1.0	Supported
RFC 4741	Distinct Startup urn:ietf:params:netconf:capability:startup:1.0	Not supported
RFC 4741	URL urn:ietf:params:netconf:capability:url:1.0?scheme={name,...}	Not supported
RFC 4741	XPATH urn:ietf:params:netconf:capability:xpath:1.0	Not supported
RFC 5277	Interleave urn:ietf:params:netconf:capability:interleave:1.0	Supported
RFC 6022	Yang urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring	Supported
RFC 6241	Validate 1.1 urn:ietf:params:netconf:capability:validate:1.1	Supported
RFC 6241	Confirmed Commit 1.1 urn:ietf:params:netconf:capability:confirmed-commit:1.1	Supported
RFC 6242	Base 1.1 urn:ietf:params:netconf:base:1.1	Supported
-	h3c-netconf-ext:1.0 urn:h3c:params:netconf:capability:h3c-netconf-ext:1.0	Supported
-	h3c-save-point:1.0 urn:h3c:params:netconf:capability:h3c-save-point:1.0	Supported
-	h3c-name2index:1.1 urn:h3c:params:netconf:capability:h3c-name2index:1.1	Supported
-	not-need-top:1.0 urn:h3c:params:netconf:capability:not-need-top:1.0	Supported
-	module-specified-namespace:1.0 urn:h3c:params:netconf:capability:module-specified-namespace:1.0	Supported
-	h3c-lightrollback:1.0 urn:h3c:params:netconf:capability:h3c-lightrollback:1.0	Supported
-	full-replace:1.0 urn:h3c:params:netconf:capability:full-replace:1.0	Supported
-	save-safely:1.0 urn:h3c:params:netconf:capability:h3c-save-safely:1.0	Supported
-	xml2cli:1.0 urn:h3c:params:netconf:capability:h3c-xml2cli:1.0	Supported

 

Supported protocol operations

Table 4 lists the availability of NETCONF operations with Comware.

Table 4 NETCONF operations available with Comware

RPC operation	Description	Status
action	Executes a non-configuration action, for example, an action to clear or obtain operational statistics.	Supported
CLI	Executes CLI commands that are not available in NETCONF API form.	Supported
commit	Commits the configuration in the candidate datastore to the running datastore.	Supported
cancel-commit	Cancels an ongoing confirmed commit and rolls back the running configuration to the previously committed configuration.	Supported
close-session	Closes the current NETCONF session.	Supported
copy-config	Creates or replaces an entire configuration datastore with the content of another complete configuration datastore.	Supported
create-subscription	Subscribes to events.	Supported
delete-config	Deletes configuration data.	Supported
discard-changes	Discards uncommitted changes.	Supported
edit-config	Edits the configuration in a datastore.	Supported
get	Retrieves running configuration and state data.	Supported
get/filter/netconf	Retrieves the event streams supported by the target device.	Supported
get/filter/netconf-state	Retrieves NETCONF state data.	Supported
get-bulk	Retrieves device data in bulk.	Supported
get-bulk-config	Retrieves configuration data in bulk.	Supported
get-config	Retrieves configuration data from a datastore.	Supported
get-sessions	Retrieves NETCONF session information.	Supported
kill-session	Forces termination of any other NETCONF sessions than the current one.	Supported
load	Loads the configuration from a file.	Supported
lock	Locks a configuration datastore.	Supported
rollback	Rolls back configuration.	Supported
save	Saves configuration.	Supported
unlock	Unlocks a locked configuration datastore.	Supported
validate	Examines NETCONF requests for XML syntax errors.	Supported
get-schema	Retrieves YANG/Schema model files.	Partial support. YANG files are available only for some of the feature modules.
cancel-subscription	Unsubscribes from events.	Supported

 

NOTE: The action, CLI, get-bulk, get-bulk-config, get-sessions, load, save, rollback and cancel-subscription operations are Comware specific. Comware also adds the count attribute to the <get> and <get-config> operations. For more information about these operations, see "Executing Comware NETCONF requests."

 

Using NETCONF to configure and manage the device

Summary procedure

To configure and manage the device:

1.     Choosing a NETCONF client and session type

Comware supports the following NETCONF access methods:

¡     NETCONF over Telnet

¡     NETCONF over Console

¡     NETCONF over SSH

¡     NETCONF over SOAP over HTTP

¡     NETCONF over SOAP over HTTPS

Select a method depending on the network environment.

2.     Assigning access permissions to a NETCONF user on the device

Authorizes the NETCONF client to use the required network service:

¡     To establish NETCONF over SOAP over HTTP sessions, authorize the client to use the HTTP service.

¡     To establish NETCONF over SOAP over HTTPS sessions, authorize the client to use the HTTPS service.

¡     To establish NETCONF over SSH sessions, authorize the client to use the SSH service.

3.     Configuring NETCONF session establishment settings

Configure parameters for NETCONF session establishment.

4.     Constructing XML NETCONF requests

Use the API documents for the modules of interest to construct NETCONF XML requests.

5.     Setting up the NETCONF client

Set up the NETCONF client. Verify that it can send hello and close-session messages to the target device successfully. The client can be an RFC 4741-compliant network management software or SOAP-based scripting tool or utility. For more information about NETCONF client setup, see the documentation for the client.

6.     Connecting the NETCONF client to the target device

Establish a NETCONF session from the NETCONF client to the target device.

7.     Testing the connectivity between the NETCONF client and the target device

Verify that the client can establish a session to the target device and close the session by sending a hello and close-session message, respectively.

8.     Validating a NETCONF XML request file

Use a validation tool or access the XML view of the target device to verify that the NETCONF XML request files are valid and correct.

9.     Integrating the validated XML request into the NETCONF client script or program

Build the request files into the client software.

10.     (Optional.) Best practices

Use the best practices to optimize the NETCONF configuration and client setup. The best practices provide recommendations regarding fault tolerance, massive data processing, concurrency, and other important issues.

11.     (Optional.) FAQ

Access the target device from the NETCONF client to operate and manage the device. For more information about the operations supported in Comware, see "Executing Comware NETCONF requests."

Choosing a NETCONF client and session type

NETCONF-based configuration methods

To configure and manage the device from a NETCONF client, use one of the following methods:

·     Access the CLI of the device through a Telnet, SSH, or console session. In XML view, copy and paste NETCONF messages to operate and configure the device. For more information about NETCONF message formats, see “NETCONF.” Typically, you use this method for development or test purposes.

·     Use a configuration tool to issue NETCONF RPC messages to operate or configure the device. The configuration tool can use SSH or SOAP as the transport protocol for NETCONF.

¡     NETCONF over SSH—The configuration tool establishes an SSH connection with the device and then transport NETCONF RPC messages over the connection. For more information about NETCONF message formats, see "NETCONF."

¡     NETCONF over SOAP—Establishes an HTTP or HTTPS connection with the device and then transport SOAP-encapsulated NETCONF RPC messages over the connection. For more information about NETCONF over SOAP message formats, see "NETCONF over SOAP." To use this method, you must enable NETCONF over SOAP on the device.

You can develop custom NETCONF-based configuration applications or use a third-party configuration tool depending on the choice of transport protocol. For example, to run NETCONF over SSH, choose NetConf Browser. To run NETCONF over SOAP, choose SoupUI.

For more information about a configuration tool, see its documentation.

NETCONF access methods

H3C devices support different NETCONF access methods in non-FIPS mode and FIPS mode.

·     In non-FIPS mode:

¡     NETCONF over SSH.

¡     NETCONF over Telnet.

¡     NETCONF over console.

¡     NETCONF over SOAP over HTTP.

¡     NETCONF over SOAP over HTTPS.

·     In FIPS mode:

¡     NETCONF over SSH.

¡     NETCONF over console.

¡     NETCONF over SOAP over HTTPS.

Select an access method depending on the configuration method, as shown in Table 5.

Table 5 Configuration methods and NETCONF access methods matrix

Configuration method	Login method	NETCONF access method
CLI in XML view	Telnet	NETCONF over Telnet
	Console port	NETCONF over console
	SSH	NETCONF over SSH
SSH-based configuration tool (for example, NETCONF Browser)	SSH	NETCONF over SSH
SOAP-based configuration tool	HTTP or HTTPS	NETCONF over SOAP over HTTP/HTTPS

 

Assigning access permissions to a NETCONF user on the device

To have a NETCONF client establish a NETCONF session with the target device, make sure the user account used by the NETCONF client has the required access permissions.

About NETCONF user access permissions

Comware uses the role-based access control (RBAC) model to control access to the system by user role. A user role is assigned access permissions based on user role rules and resource access policies.

·     A user role rule controls access to a system functionality or feature. For example, you can define a user role rule to permit or deny access to feature A.

·     A resource access policy controls access to system resources. For example, you can define a resource access policy to permit access to VLAN 10.

User role rules for a NETCONF user role must include the following access permissions:

·     Access to the <rpc> element and the elements required for the NETCONF operations to be performed. Table 7 shows the NETCONF operations and their required access permissions.

·     Access to the XML elements for the feature modules and tables in the modules, at their XPaths. For example, to assign the NETCONF client read, write, and execute access to the XML elements for the interface module, execute the rule number permit read write execute xml-element ifmgr/ command.

Every user role has one interface policy, VLAN policy, VPN instance policy, and security zone policy. By default, these policies permit a user role to access any system resources.

Comware 7 predefines a set of user roles. The following are the most commonly used predefined user roles:

Table 6 Predefined user roles in most common use and their access permissions

Predefined user roles	Permissions	Remarks
network-admin, mdc-admin, and context-admin	Have full access to all features and resources on the device, administered MDC, and administered context, respectively, except for the following commands for security log file management: ·     display security-logfile summary ·     info-center security-logfile directory ·     security-logfile save	You assign the network-admin, mdc-admin, or context-admin user role to an administrator without having to do additional configuration.
network-operator, context-operator and mdc-operator	Have only read access to all features and execute access to some of the features on the device, administered MDC, and administered context, respectively.	N/A

 

You can also use other predefined user roles and configure custom user roles for granular functionality and resource access control. For more information about RBAC, see the fundamentals configuration guide for the target device.

When you assign access permissions to NETCONF users, use Table 7.

Table 7 NETCONF operations and required access permissions

NETCONF operation	XML element path	Required access to the path
Establish a NETCONF session	N/A	Execute access to the xml command is required for NETCONF over Telnet or NETCONF over Console access to the CLI in XML view.
Subscribe to events	rpc/create-subscription	execute
Lock a configuration datastore	rpc/lock	execute
Unlock a configuration datastore	rpc/unlock	execute
Perform the <get> operation to retrieve device configuration and state data	rpc/get	read
Perform the <get> operation to retrieve NETCONF state data	rpc/get/filter/netconf-state	read
Perform the <get-bulk> operation to retrieve device configuration and state data	rpc/get-bulk	read
Perform the <get-config> operation to retrieve configuration data	rpc/get-config	read
Perform the <get-bulk-config> operation to retrieve configuration data	rpc/get-bulk-config	read
Perform the <get-schema> operation to retrieve YANG file information	rpc/get-schema	read
Perform the <edit-config> operation to edit the configuration for a module	rpc/edit-config	write
Perform an <action> operation to execute a non-configuration instruction	rpc/action	execute
Save the configuration	rpc/save	write
Roll back the configuration	rpc/rollback	write
Load the configuration	rpc/load	write
Execute CLI commands	rpc/CLI	write
Retrieve session information	rpc/get-sessions	read
Force termination of a session other than the current one	rpc/kill-session	execute
Validate the NETCONF message	rpc/validate	read
Create a rollback point	rpc/save-point	write
Commit the configuration in the candidate configuration datastore to the running configuration datastore	rpc/commit	execute
Cancel the committed configuration	rpc/cancel-commit	execute
Copy a configuration datastore	rpc/copy-config	execute
Delete a configuration datastore	rpc/delete-config	execute
Revert the candidate configuration to the current running configuration	rpc/discard-changes	execute
Enable preprovisioning	rpc/config-provisioned	execute
Quit XML view	N/A	Execute access to the xml command.
Unsubscribe from events	rpc/cancel-subscription	execute

 

Configuring user role rules for the NETCONF client

1.     Enter system view.

system-view

2.     Create a user role and enter its user role view.

role name role-name

3.     Configure user role rules:

¡     Enable access to specified <rpc> elements in XML.

rule number permit { execute | read | write } * xml-element rpc/

To view the list of supported RPC operations, execute the rule number permit { execute | read | write } * xml-element rpc/? command. If you do not specify an operation, the rule permits all RPC operations.

¡     Configure access to a module or table in XML elements.

rule number { deny | permit } { execute | read | write } * xml-element [ module-xpath ]

To view the list of modules, execute the rule number { deny | permit } { execute | read | write } * xml-element ? command. To view the list of tables in a module, execute the rule number { deny | permit } { execute | read | write } * xml-element module-name/? command. If you do not specify a module or table, the rule applies to all modules or tables in a module, respectively.

Configuring a user account for the NETCONF client

About this task

In the user account for a NETCONF client, configure the following settings:

·     Enable network services for the user account depending on the NETCONF access method.

¡     To run NETCONF over SSH, enable SSH service.

¡     To run NETCONF over SOAP over HTTP, enable HTTP service.

¡     To run NETCONF over SOAP over HTTPS, enable HTTPS service.

·     Assign the user role or user roles to the NETCONF client.

The following information uses local authentication for example to describe the configuration procedure. For information about the configuration procedure for remote authentication, see AAA configuration in the set of configuration guides for the software release running on the device.

Procedure

1.     Enter system view.

system-view

2.     Create a local device management user account and enter its view.

local-user user-name class manage

3.     Set a password for the user.

In non-FIPS mode:

password [ { hash | simple } string ]

In FIPS mode:

password

In non-FIPS mode, the password setting is optional.

In FIPS mode, you must set a password in interactive mode for a device management user. The device management user must provide the password to pass local authentication.

4.     Assign services to the user. Choose one of the following options depending on the NETCONF session type:

¡     NETCONF over SSH:

service-type ssh

¡     NETCONF over SOAP over HTTP or NETCONF over SOAP over HTTPS:

In non-FIPS mode:

service-type { http | https } *

In FIPS mode:

service-type https

By default, none of the services are available for a local user.

5.     Assign a user role to the user.

authorization-attribute user-role role-name

Configuring NETCONF session establishment settings

Configuring settings for NETCONF over SSH

Configuring SSH service

The following information uses password-based SSH client authentication for example to describe the SSH server configuration procedure. For more information about configuring SSH and publickey authentication, see the security configuration guide for the device.

1.     Enter system view.

system-view

2.     Create local key pairs.

In non-FIPS mode:

public-key local create { dsa | ecdsa [ secp192r1 | secp256r1 | secp384r1 | secp521r1 ] | rsa } [ name key-name ]

In FIPS mode:

public-key local create { dsa | ecdsa [ secp256r1 | secp384r1 | secp521r1 ] | rsa } [ name key-name ]

3.     (Optional.) Create an SSH user, authorize the user to use NETCONF service, and set the authentication method to password.

ssh user username service-type netconf authentication-type password

4.     Enter VTY line view or class view.

¡     Enter VTY line view.

line vty first-number [ last-number ]

¡     Enter VTY line class view.

line class vty

5.     Enable scheme authentication.

In non-FIPS mode:

authentication-mode scheme

By default, password authentication is enabled for VTY lines.

In FIPS mode:

authentication-mode scheme

By default, scheme authentication is enabled for VTY lines.

Configuring NETCONF over SSH service

1.     Enter system view.

system-view

2.     Enable NETCONF over SSH.

netconf ssh server enable

By default, NETCONF over SSH is disabled.

3.     Specify the listening port for NETCONF over SSH packets.

netconf ssh server port port-number

By default, the listening port for NETCONF over SSH packets is 830.

4.     (Optional.) Enable NETCONF logging.

netconf log source { all | { agent | soap | web } * } { protocol-operation { all | { action | config | get | set | session | syntax | others } * } | row-operation | verbose }

By default, NETCONF logging is disabled.

5.     Establish a NETCONF over SSH session with the device from the configuration tool. For more information about the configuration tool, see its documentation.

Configuring NETCONF over SOAP over HTTP (or HTTPS) service

About this task

This task allows a NETCONF client (the network manager or controller) to establish a NETCONF over SOAP over HTTP/HTTPS session with the device.

This task provides only the basic configuration procedure. For information about advanced features such as marking the DSCP value of SOAP packets, controlling NETCONF access, and configuring a NETCONF user authentication domain, see the NETCONF configuration guide and command reference for the device.

Enabling NETCONF over SOAP service

1.     Enter system view.

system-view

2.     Enable NETCONF over SOAP.

In non-FIPS mode:

netconf soap { http | https } enable

In FIPS mode:

netconf soap https enable

By default, NETCONF over SOAP is disabled.

3.     (Optional.) Enable NETCONF logging.

netconf log source { all | { agent | soap | web } * } { protocol-operation { all | { action | config | get | set | session | syntax | others } * } | row-operation | verbose }

By default, NETCONF logging is disabled.

4.     Establish a NETCONF over SOAP session with the device from the configuration tool. For more information about the configuration tool, see its documentation.

Constructing XML NETCONF requests

About NETCONF API references

Comware NETCONF API references describe all capabilities available in Comware. Some of the capabilities might be unavailable for some devices. As a best practice, use the XSD schema files for the managed device to identify its support for capabilities.

Types of NETCONF API references

Every NETCONF-capable feature has a set of API references, one for each of the following namespaces:

·     Data namespace—Contains read-only operational state and configuration data and supports <get> and <get-bulk> operations.

·     Config namespace—Contains configuration data that is read and write accessible. A NETCONF client can perform operations such as <get-config>, <get-bulk-config> and <edit-config> to retrieve or edit this data.

·     Action namespace—Contains data that support execute access. A NETCONF client can use the <action> element to perform non-configuration operations such as ping and reset on this data.

·     Event namespace—Contains system event data to which a NETCONF client can subscribe by performing a <create-subscription> operation.

Every NETCONF-capable feature has a set of NETCONF API references to describe their capabilities in the data, config, action, and event namespaces. These API references use the following file naming conventions:

·     API namespace: Comware Module_name NETCONF XML API Data Reference

·     Config namespace: Comware Module_name NETCONF XML API Configuration Reference

·     Action namespace: Comware Module_name NETCONF XML API Action Reference

·     Event namespace: Comware Module_name NETCONF XML API Event Reference

A NETCONF module might also have an error message reference to describe the error messages that a NETCONF client might encounter when it performs NETCONF operations.

Organization of a NETCONF API reference

Every NETCONF API reference describes the objects in the tables for a feature (for example, APR or DHCP) in a namespace. A table contains rows and columns.

·     Each row represents one instance of an object.

·     Each column contains a parameter for the instance.

For example, each row in the ARP table is an ARP entry. Each ARP entry contains several parameters, including the IP address, MAC address, and VLAN.

In a NETCONF API reference, information for a table contains the following parts:

·     Table name—Presented in the table-path/table-name format, for example, ACL/Base. The table path starts with the feature module name.

·     XML structure—The XML structure for the table, starting from the module name element. In the API references, values in the XML structure are omitted. The following example shows the XML structure for a request:

 

 

·     Table description—Provides information about the feature module name, table name, table type, row name, and constraints. The table type indicates whether the table is a multi-instance table or a single-instance table.

¡     Multi-instance table—Contains one or more rows.

¡     Single-instance table—Contains only one row.

·     Columns—Provides information about each column in the table, including their column name, column description, column type, data type, and constraints (or restrictions). The column type indicates whether the column is an index column.

¡     Index—The column is an index column for the table.

¡     N/A—The column is not an index column.

·     XML structure for the response—This structure starts with the feature module name element. In the API references, values in the XML structure for the response are omitted. The NETCONF client uses the response to identify the operation result. This structure is available only for tables in the action namespace that are designed to return operation results. The following example shows the XML structure for a response:

 

 

·     Columns in the response—Describes the columns in a response.

Using NETCONF API references to construct NETCONF requests

NETCONF API references describe the syntax of the H3C-defined sections in the messages for feature modules. For more information about NETCONF message formats, see "NETCONF message formats." To construct a request message, identify the API reference that contains the applicable XML structure based on the operation type and feature module, as shown in Table 8.

Table 8 Matrix of operations and API references

Operations	Applicable API references
<get> <get-bulk>	Comware Module_name NETCONF XML API Data Reference For example, use Comware Ifmgr NETCONF XML API Data Reference when you construct NETCONF request messages for retrieving interface management data.
<get-config> <get-bulk-config> <edit-config>	Comware Module_name NETCONF XML API Configuration Reference For example, use Comware Ifmgr NETCONF XML API Configuration Reference when you construct NETCONF request messages for retrieving or editing interface settings.
<action>	Comware Module_name NETCONF XML API Action Reference For example, use Comware Ifmgr NETCONF XML API Action Reference when you construct NETCONF request messages to perform non-configuration operations.
<create-subscription>	Comware Module_name NETCONF XML API Event Reference For example, use Comware Ifmgr NETCONF XML API Event Reference when you construct NETCONF request messages to subscribe to interface management events.

 

After you obtain the applicable NETCONF API reference, verify that the capability of interest is available on the target device. If the capability is available, construct messages as needed. The following information describes the generic procedure to construct a NETCONF request message in XML format:

1.     Construct the protocol-defined section, the part outside the <top> and </top> tag pair.

The following example shows the generic RPC message format for the <get> operation, with the protocol-defined section highlighted:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter>

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        XML structure (module, submodule, table, and columns)

      </top>

    </filter>

  </get>

</rpc>

For information about the protocol-defined sections for all operations, see "Executing Comware NETCONF requests."

2.     Construct the <top> element.

The <top> element contains the xmlns attribute to specify an H3C proprietary namespace. For example, the <top xmlns="http://www.h3c.com/netconf/data:1.0"> tag specifies the H3C data namespace at http://www.h3c.com/netconf/data:1.0. To specify the config or action namespace, replace data:1.0 with config:1.0 or action:1.0, respectively.

3.     Construct the operation section.

Copy the applicable XML structure from the NETCONF API reference, and paste the XML structure in the <top> element. Then, delete unused columns and enter values in the remaining columns as required.

Using XSD schema files to construct NETCONF requests

H3C releases XSD schema files along with software version releases. You can use XSD schema files to construct NETCONF requests in the same way as you do with NETCONF API references.

Using YANG module files to construct NETCONF requests

In compliance with NETCONF standards, Comware supports the <get-schema> and <netconf-state> operations for a NETCONF client to retrieve the content of a YANG module file and obtain the list of YANG module files on the target device, respectively. For more information about these operations, see "get-schema" and "netconf-state."

You can use YANG module files to construct NETCONF requests in the same way as you do with NETCONF API references.

Connecting the NETCONF client to the target device

Selecting a NETCONF access method

Select an access method depending on the configuration method, as shown in Table 9.

Table 9 Configuration methods and NETCONF access methods matrix

Configuration method	Login method	NETCONF access method
CLI in XML view	Telnet	NETCONF over Telnet
	Console port	NETCONF over console
	SSH	NETCONF over SSH
SSH-based configuration tool (for example, NETCONF Browser)	SSH	NETCONF over SSH
SOAP-based configuration tool	HTTP or HTTPS	NETCONF over SOAP over HTTP/HTTPS

 

Before the NETCONF client can establish a NETCONF session with the target device, you must configure the target device with settings for NETCONF session establishment.

Establishing a NETCONF over SOAP over HTTP (or HTTPS) session to the target device

To establish a NETCONF over SOAP over HTTP (or HTTPS) session with the target device, configure the client to send SOAP-encapsulated request messages over HTTP or HTTPS to the URL in http://deviceIP:[portNum]/soap/netconf/ or https://deviceIP:portNum/soap/netconf/ format.

·     The deviceIP argument represents the IP address of the target device.

·     The portNum argument represents the service port for NETCONF over SOAP over HTTP (or HTTPS). The service port number must be the one configured on the target device. By default, the service port is 80 and 832 for NETCONF over SOAP over HTTP and NETCONF over SOAP over HTTPS, respectively.

For example, the device IP address is 192.168.1.1 and the default service ports are used. The NETCONF client must send requests to either of the following URLs:

·     In HTTP:

http://192.168.1.1/soap/netconf/

·     In HTTPS:

https://192.168.1.1:832/soap/netconf/

 

IMPORTANT: ·     Whe you specify the HTTP or HTTPS URL, you must retain the ending forward slash (/). ·     The service ports for NETCONF over SOAP over HTTP and NETCONF over SOAP over HTTPS are configurable. Make sure the NETCONF client sends the requests to the correct service port.

 

SOAP-encapsulated message format

As shown in Figure 2, a NETCONF over SOAP message format contains the following layers:

·     Outer layer—HTTP header.

·     Middle layer—HTTP content wrapped in a SOAP envelope.

·     SOAP inner layer (body)—NETCONF RPC message.

Figure 2 NETCONF over SOAP over HTTP (or HTTPS) message format

 

Delivering the username and password for NETCONF access

As shown in Figure 2, enclose the username and password for authentication in the \Envelope\Header\Authentication\UserName and \Envelope\Header\Authentication\Password elements, respectively.

The Authentication element must comply with the following rules:

·     Its xmlns attribute must be set to http://www.h3c.com/netconf/base:1.0.

·     It must contain the mustUnderstand attribute in the http://www.w3.org/2003/05/soap-envelope namespace, and the attribute value must be set to 1 or true.

Obtaining the authentication token returned for a login success

If the NETCONF client successfully connects to the device, the device returns an authentication token in the \Envelope\Header\Authentication\AuthInfo element, as shown in Figure 3. The client must retain this token and include it in the subsequent requests.

Figure 3 Obtaining the authentication token returned for a login success

 

Sending requests with the authentication token after a successful login

After the NETCONF client receives an authentication token in a hello message from the device, the client must send every subsequent request with the token included in the \Envelope\Header\Authentication\AuthInfo element.

Figure 4 Sending requests with an authentication token after a successful login

 

Changing the language preference for error messages

Comware NETCONF server can return error messages in Chinese (zh-cn) or English (en). The NETCONF client can specify the expected language when it sends a request message. As shown in Figure 4, set the language preference in the \Envelope\Header\Authentication\Language element. Options are zh-cn for Chinese, and en for English. If the request does not specify the language preference, English applies by default.

 

IMPORTANT: You must put the Language element behind the AuthInfo element.

 

Not all NETCONF response messages support error messages in Chinese. If an error message is not available in Chinese, the device sets the xml:lang attribute to "en".

Figure 5 Actual language used in a sample response message

 

Differences of NETCONF over SOAP requests with other types of NETCONF requests

NETCONF over SOAP has the following characteristics:

·     Authentication starts along with the first hello message.

·     The connection is not persistent across requests. The client closes the connection established for a request when it receives a response from the server. Consequently, NETCONF over SOAP does not support event subscription.

·     All requests and normal responses are encoded in a SOAP envelope, with the RPC request in the SOAP body.

·     NETCONF over SOAP supports multithreading for concurrent requests. A NETCONF over SOAP session supports a maximum of four concurrent requests. If the server receives a request after this limit has been reached, the server rejects the request and returns a resource inadequate error message.

Establishing a NETCONF over SSH session to the target device

A NETCONF client can establish a NETCONF over SSH session to operate and configure the target device after you configure the device with settings for NETCONF over SSH access. The access process complies with RFC 4742.

Typically, the client must provide the server’s IP address, the username and password for SSH access, the subsystem to access, and the service port.

The device might send banner, greeting, and legal statement information to the NETCONF client before this information is sent over the NETCONF over SSH session. The NETCONF client should ignore this information.

Establishing a NETCONF over Telnet, SSH, or console to access the CLI of the target device

After the NETCONF client accesses the CLI of the target device through a Telnet, SSH, or console session, execute the xml command to enter XML view.  In XML view, copy and paste NETCONF messages to operate and configure the device.

Verifying that the NETCONF session has been established

The NETCONF client can determine that a NETCONF over Telnet, SSH, or console session is established when it receives a hello message in the following format from the device:

<?xml version=”1.0” encoding=”UTF-8”?><hello xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”><capabilities><capability>urn:ietf:params:netconf:base:1.0</capability><capability>urn:ietf:params:netconf:capability:writable-running:1.0</capability><capability>urn:ietf:params:netconf:capability:notification:1.0</capability><capability>urn:ietf:params:netconf:capability:validate:1.0</capability><capability>urn:ietf:params:netconf:capability:interleave:1.0</capability><capability>urn:h3c:params:netconf:capability:h3c-netconf-ext:1.0</capability></capabilities><session-id>1</session-id></hello>

The NETCONF client can determine that a NETCONF over SOAP over HTTP or HTTPS session is established when it receives a hello message in the following format from the device:

<env:Envelope xmlns:env=”http://www.w3.org/2003/05/soap-envelope”>

  <env:Header>

    <auth:Authentication env:mustUnderstand=”true” xmlns:auth=”http://www.h3c.com/netconf/base:1.0”>

      <auth:AuthInfo>1001e17d1916e60ef0068f3c6387d4410a1b</auth:AuthInfo>

    </auth:Authentication>

  </env:Header>

  <env:Body>

    <hello xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

      <capabilities>

        <capability>urn:ietf:params:netconf:base:1.0</capability>

        <capability>urn:ietf:params:netconf:capability:writable-running:1.0</capability>

        <capability>urn:ietf:params:netconf:capability:notification:1.0</capability>

        <capability>urn:ietf:params:netconf:capability:validate:1.0</capability>

        <capability>urn:ietf:params:netconf:capability:interleave:1.0</capability>

        <capability>urn:h3c:params:netconf:capability:h3c-netconf-ext:1.0</capability>

      </capabilities>

      <session-id>1</session-id>

    </hello>

  </env:Body>

</env:Envelope>

Testing the connectivity between the NETCONF client and the target device

Exchanging capability sets

The device and the NETCONF client exchange their capability sets in a hello message immediately after they are connected. Only after the capability set exchange is complete will they continue with subsequent operations.

Capability set exchange message from the device to the client

The device notifies a NETCONF client of its NETCONF capabilities in a hello message in the following format:

<?xml version=”1.0” encoding=”UTF-8”?><hello xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”><capabilities><capability>urn:ietf:params:netconf:base:1.0</capability><capability>urn:ietf:params:netconf:writable-running</capability><capability>urn:ietf:params:netconf:capability:notification:1.0</capability><capability>urn:ietf:params:netconf:capability:validate:1.0</capability><capability>urn:ietf:params:netconf:capability:interleave:1.0</capability><capability>urn:h3c:params:netconf:capability:h3c-netconf-ext:1.0</capability></capabilities><session-id>1</session-id></hello>

Where:

·     The <capabilities> element contains the capabilities supported by the device. The supported capabilities vary by device model.

·     The <session-id> element contains a session ID that uniquely identifies the current NETCONF session.

Capability set exchange message from the client to the device

In response to the capability set hello message from the device, the NETCONF client must send a hello message to notify the device of its supported capability sets.

The NETCONF client must send the hello message for capability negotiation in the following format:

<hello xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

  <capabilities>

    <capability>

      capability-set

    </capability>

  </capabilities>

</hello>

Enclose a capability set in a <capability> element. Client-side capability sets depend on the client model. If the client supports multiple capability sets, enclose each of them in one pair of <capability> and </capability> element tags.

Tuning the client-side NETCONF access protocol settings

If NETCONF over SSH is used when both the server and client support Base 1.1 capabilities, the server and client must use the NETCONF over SSH access method specified in Base 1.1 for communication. The NETCONF client must examine the capabilities received from the server and make sure it runs the same transport protocol settings as the server.

Disconnecting a NETCONFsession

Sending a close-session message from the client to the device

A NETCONF client sends a message in the following format to terminate the current session:

<rpc message-id=”101” xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

  <close-session/>

</rpc>

 

NOTE: If you are in XML view, you must return to user view before you can execute commands in CLI to configure the device. To return from XML view to user view, copy and paste this message to the client.

 

Verifying the result

If the device closes the session, the client should receive the following message from the device:

<?xml version=”1.0” encoding=”UTF-8” ?>

<rpc-reply message-id=”101” xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

  <ok/>

</rpc-reply>

Validating a NETCONF XML request file

Before you integrate an XML request file into a NETCONF client, use a test tool (for example, SoapUI Open Source) to validate the XML request file. Alternatively, access the CLI of the target device and then copy and paste the request file in XML view for validation.

When you validate NETCONF XML request files from the CLI, use the following guidelines:

·     Run NETCONF over Telnet or SSH instead of console as long as possible. The console port has rate limiting, and the device does not generate prompts or warning in XML view. Validation of NETCONF requests over console is error prone.

·     To avoid typing errors, copy and paste the XML file.

·     For the device to correctly identify a NETCONF request, you must add the ]]>]]> end delimiter string to the end of its XML file in XML view.

Figure 6 shows a sample request message and its response on SoapUI Open Source.

Figure 6 Sample NETCONF XML request and response on SoapUI Open Source

 

Integrating the validated XML request into the NETCONF client script or program

After you verify that an XML request file is correct, integrate that file into the NETCONF client. If the client is an unattended program, design mechanisms to handle anomalies such as timeout and loss of connectivity so the program can operate correctly unattended for a long time.

Best practices

Fault tolerance

Client developers must provide mechanisms for recovery from response exceptions in situations such as loss of connectivity, malformed XML responses, and server unresponsiveness.

Massive data retrieval

It might be difficult or inefficient to retrieve all data from an oversized table in one request. As a best practice to retrieve all data from an oversized table, perform multiple <get-bulk> operations with the count attribute.

The count attribute specifies the number of data entries to retrieve. After the first <get-bulk> operation retrieves the specified number of entries, the client sends the second <get-bulk> operation request to retrieve the specified number of data entries next to the last entry in the previous <get-bulk> operation. The last entry in the previous <get-bulk> operation is identified by its index. This process continues until the client retrieves all data from the table.

When you design the massive data retrieval mechanism, set the TCP session timeout timer to a value that is high enough to prevent TCP session timeout from causing undesired NETCONF session disconnection. As a best practice, test and tune the setting before you deploy the NETCONF client in the production environment.

Session concurrency

Comware supports concurrent requests over multiple sessions. To make sure the device is configured as expected, lock the running configuration datastore before issuing an <edit-config> operation request.

The following issues might occur if you do not lock the datastore:

·     The system might not operate with the expected configuration if concurrent <edit-config> operations have been performed.

·     An <edit-config> operation with the error-option element set to rollback-on-error might roll back the settings made by other users. For more information about rollback-on-error, see Table 20.

After a configuration datastore is locked by a NETCONF client, only that client can change the configuration in that datastore. None of other users can configure the device through NETCONF, CLI or SNMP.

You do not necessarily get linear growth in overall request processing performance as the number of concurrent <get> or <edit-config> operations increases. This is because the response time for individual requests gradually grows as the number of requests increases to consume more resources.

For more information about the <lock> operation, see "lock."

Termination of NETCONF over SOAP over HTTP or HTTPS sessions

As a best practice, send a <close-session> request to close a NETCONF over SOAP over HTTP or HTTPS session when it becomes idle.

 

NOTE: The client might be unable to receive a response to a <close-session> request.

 

Event notification suppression

As a best practice, do not receive debugging log messages through NETCONF.

The device might generate a large number of log messages when a debugging switch is turned on. Receiving debugging log messages through NETCONF might cause slow responses to NETCONF requests.

Mixed use of HTTP and HTTPS

SOAP can run over both HTTP and HTTPS. Use either protocol for one session, not both. For example, do not configure the client to log in to the device through HTTP and then send subsequent requests with the returned authentication token (in the AuthInfo element) over HTTPS.

FAQ

What should I do when no response is received to a NETCONF XML request in CLI?

This issue might occur because the entered XML script is incomplete.

To resolve this issue:

1.     Manually enter the ]]>]]> string.

If the NETCONF server is operating correctly, it typically responds with an XML input error message.

2.     Verify that the XML file correct, and then copy and paste the script in the file to the CLI in XML view.

As a best practice to avoid mistyping, do not enter the script manually.

To avoid this issue, use the following guidelines:

·     Run NETCONF over Telnet or SSH to access the CLI. Console ports are slow in data transmission. Loss of characters and response issues might occur on a NETCONF over console session, even if the request script is copied and pasted. If you need to manually enter XML-encoded commands at the CLI over a console session, make sure you are familiar with Comware.

·     After you enter XML-encoded commands at the CLI, enter the ]]>]]> end delimiter string, copy and paste a <close-session> message, and wait for the system to quit XML view. For more information about the <close-session> message, see "Disconnecting a NETCONFsession."

What should I do when I receive a request timeout error message on a SOAP-based NETCONF client such as SoapUI?

This issue occurs if the client has failed to receive a response to a request in SOAP before the response timeout timer expires. This issue typically occurs when the client attempts to retrieve massive data. When a response timeout occurs, the client automatically returns a failure.

To avoid undesired response timeout, use the following guidelines:

·     Tune the response timeout timer for the socket to an appropriate value on the client.

·     Avoid retrieving all data from the device as long as possible. Use filters in requests to retrieve only data of interest. For more information about data filtering, see "Comware NETCONF data filtering."

Device-supplied test commands

Table 10 and Table 11 list the commands that you can use when you test NETCONF functionality and connectivity.

Table 10 SOAP related commands

Command	Purposes
display tcp	This command displays TCP connections. Use this command to verify that a TCP connection can be set up correctly for NETCONF over SOAP over HTTP (or HTTPS) service at the specified service port.

 

Table 11 NETCONF over SSH service related commands

Command	Purposes
display tcp	This command displays TCP connections. Use this command to verify that a TCP connection can be set up correctly for NETCONF over SSH service at the specified service port.
display ssh server session	This command displays active SSH sessions. Use this command to verify that NETCONF over SSH sessions can be correctly established.
netconf log	This command enable the device to log information about NETCONF requests and request processing results. Use this command to verify that the NETCONF requests are valid and can be correctly processed.

 

About Comware NETCONF sessions

Lifecycle of NETCONF sessions

Lifecycle of NETCONF over SOAP sessions

A NETCONF client starts to establish a NETCONF over SOAP session with the device when it sends the first <hello> message. The NETCONF over SOAP session closes when one of the following events occurs:

·     The NETCONF client sends a <close-session> request to close the session.

·     Another user forces the session to close by sending a <kill-session> request.

·     The idle timeout timer for the session expires.

During the lifetime of a session, one TCP connection is open for every request sent over the session. The NETCONF server closes the TCP connection for a request after it sends a response for that request.

The server sends its first <hello> message with an authentication token in the AuthInfo element. After the client receives this authentication token, the client must send every request with this authentication token set in the AuthInfo element for authentication.

The server maintains a session idle timeout timer for every NETCONF session. If no messages have been sent over a NETCONF session before the timer expires, the session closes automatically.

The NETCONF session idle timeout timer is configurable with the netconf idle-timeout command. By default, the timer is set to 10 minutes.

To maintain a session, configure the NETCONF client to regularly send a <hello> message to the NETCONF server, with the authentication token set in the AuthInfo element. The server will return a <hello> message that is the same as the first <hello> message sent over the session.

Lifecycle of NETCONF over console, Telnet or SSH sessions

A NETCONF client starts to establish a NETCONF over console, Telnet, or SSH session with the device when the underlying connection is established. The session closes when one of the following events occurs:

·     The NETCONF client sends a <close-session> request to close the session.

·     Another user forces the session to close by sending a <kill-session> request.

·     The underlying connection disconnects.

·     The idle timeout timer for the session expires. By default, the session idle timeout timer never expires for NETCONF over SSH, NETCONF over Telnet, and NETCONF over console sessions. These types of sessions persist until they are closed for other reasons. To set the NETCONF session idle timeout timer, use the netconf idle-timeout command.

Request concurrency over one session

Comware supports concurrent requests on one NETCONF over SOAP session.

A NETCONF client can use multiple threads to send requests with the same token in the AuthInfo element concurrently over one NETCONF over SOAP session. Despite this, do not design a NETCONF client to send concurrent requests over one NETCONF over SOAP session unless necessary.

Comware does not support concurrent requests on any types of NETCONF sessions other than NETCONF over SOAP.

RBAC-based access control

Comware NETCONF manages access at the protocol, module, and instance levels.

·     Protocol-level permission controls access to RPC operations.

·     Module-level permission controls access to modules and their tables, rows, groups, and columns.

·     Instance-level permission controls access to instances of an object, such as a VPN instance, interface, VLAN, or security zone.

For the device to execute a NETCONF request, make sure the client has sufficient access permissions at the protocol, module, and instance levels.

Look at the following <edit-config> request. For the device to process this request, you must make sure the client has the following access permissions:

·     Protocol level—Write access to the rpc/edit-config/config/top path.

·     Module level—Write access to the Ifmgr/Interfaces/Interface table.

·     Instance level—Write access to the interface with an interface index of 3.

<rpc message-id =”101” xmlns=”urn:ietf:params:xml:ns:netconf:base:1.0”>

  <edit-config>

    <target>

      <running/>

    </target>

    <default-operation> merge</default-operation>

    <test-option>set</test-option>

    <error-option>continue-on-error</error-option>

    <config xmlns:xc=”urn:ietf:params:xml:ns:netconf:base:1.0”>

      <top xmlns=”http://www.h3c.com/netconf/config:1.0”>

        <Ifmgr xc:operation=”delete”>

          <Interfaces>

            <Interface>

              <IfIndex>3</IfIndex>

            </Interface>

          </Interfaces>

        </Ifmgr>

      </top>

    </config>

  </edit-config>

</rpc>

To assign these access permissions to the NETCONF client, configure the following settings on the device:

#

role name netconf

 rule 1 permit write xml-element rpc/edit-config/config/top

 rule 2 permit write xml-element ifmgr/interfaces/interface

 interface policy deny

  permit interface GigabitEthernet2/0/1

#

Configuration lock

Comware NETCONF implements the configuration lock mechanism in compliant with RFC 4741. If a configuration datastore is locked, only the client that holds the lock can change the configuration in the datastore. Other NETCONF clients, non-NETCONF clients, and CLI users will be unable to change the configuration until after the lock is released or the NETCONF session closes.

Maximum number of NETCONF sessions

The maximum number of sessions supported for a type of NETCONF session (NETCONF over console, Telnet, SSH, SOAP over HTTP, or SOAP over HTTPS) depends on the session limit configured with the AAA module.

Executing Comware NETCONF requests

Supported NETCONF operations

Table 12 lists the NETCONF operations available with Comware.

Table 12 NETCONF operations available with Comware

Category	Operation	Purpose
Data retrieval	get	Retrieves configuration and state data.
	get-bulk	Retrieves the specified number of data entries.
	get-config	Retrieves configuration data.
	get-bulk-config	Retrieves the specified number of configuration data entries.
Configuration actions	edit-config	Edits the configuration on the managed device.
Non-configuration actions	action	Executes a non-configuration action, for example, an action to clear or retrieve operational statistics.
Event operations	get/filter/netconf	Retrieves the event streams supported by the target device.
	create-subscription	Subscribes to events.
	cancel-subscription	Unsubscribes from events.
Session management	close-session	Closes the current NETCONF session.
	kill-session	Forces another NETCONF session to close.
	get-sessions	Retrieves information about established sessions.
	lock	Locks a configuration datastore.
	unlock	Unlocks a configuration datastore.
Executes a non-interactive CLI commands.	CLI	Executes CLI commands that are not available in NETCONF API form.
Configuration management	rollback	Rolls back the configuration.
	save	Saves the configuration.
	load	Loads the configuration.
	save-point	Performs configuration rollback related operations, including creation of rollback points.
Request validation	validate	Examines a NETCONF request for XML syntax errors.
YANG module operations	get/filter/netconf-state/capabilities	Retrieves the capability sets of the device.
	get/filter/netconf-state/datastores	Retrieves the configuration datastores on the device.
	get/filter/netconf-state/schemas	Retrieves the list of YANG module file names on the device.
	get/filter/netconf-state/sessions	Retrieves information about sessions on the device.
	get/filter/netconf-state/statistics	Retrieves NETCONF statistics.
	get-schema	Retrieves the contents of a YANG module file.
Configuration datastore operations	commit	Commits the configuration from the candidate configuration datastore to the running configuration datastore.
	cancel-commit	Cancels the committed configuration.
	discard-changes	Reverts the candidate configuration to the current running configuration.
	copy-config	Copies the configuration in the source configuration datastore to the target configuration datastore.
	delete-config	Deletes a configuration datastore, which can only be the candidate configuration datastore.
Preprovisioning	config-provisioned	Enables preprovisioning.

 

NOTE: To prevent misconfiguration from causing undesirable issues, use the candidate configuration datastore to store or edit configuration data to be applied without impacting the running configuration. The candidate configuration applies to the device only after you perform a <commit> operation to commit the candidate configuration to the running configuration datastore. The system creates a configuration rollback point for every successful commit operation.

 

Standard NETCONF operations

The following information describes the most commonly used standard operations defined in NETCONF protocols.

Standard base operations include the <get>, <get-config>, and <edit-config> operations.

·     To retrieve state and configuration data from the target device, perform the <get> operation.

·     To retrieve only configuration data, perform the <get-config> operation.

·     To edit the configuration, perform the <edit-config> operation.

For more information about configuring and managing a module through NETCONF, see the NETCONF XML API references for that module.

get-config

The <get-config> operation retrieves only non-default configuration data, regardless of whether the data is configured from the CLI or Web interface or through MIB operations. To retrieve only configuration data of interest, use a <filter> subelement in the <get-config> operation element to filter data.

Request format

The following is the XML format for the <get-config> request:

<?xml version="1.0"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-config>

    <source>

      <datastore/>

    </source>

    <filter>

      <top xmlns="http://www.h3c.com/netconf/config:1.0">

          XML structure (module, submodule, table, and columns)

      </top>

    </filter>

  </get-config>

</rpc>

The value for datastore can be one of the following:

 

Value	Description
running	Specifies the running configuration datastore.
candidate	Specifies the candidate configuration datastore.

 

Verification

The request is successful if the client receives a response that contains the requested configuration data. The following is the response format:

<?xml version="1.0"?>

<rpc-reply message-id="100"   xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    Data matching the filter

  </data>

</rpc-reply>

edit-config

About the <edit-config> operation

By default, the device rejects an <edit-config> request while it is rolling back the configuration. To have the device accept an <edit-config> request while it is rolling back the configuration, use the <action> operation. For more information about this operation, see "action."

The standard <edit-config> operation supports the merge, create, replace, remove, delete, default-operation, error-option, and test-option options. For more information about these options, see Table 20.

 

NOTE: If a data table has substructures, the system processes all substructures as one column.

 

Request format

<?xml version="1.0"?>

<rpc message-id="100"  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <edit-config>

    <target>

      <datastore/>

    </target>

    <error-option>

      Action to take when error occurs during the operation

    </error-option>

    <config>

      <top xmlns="http://www.h3c.com/netconf/config:1.0">

        XML structure (module, submodule, table, and columns)

      </top>

    </config>

  </edit-config>

</rpc>

The value for datastore can be one of the following:

 

Value	Description
running	Specifies the running configuration datastore.
candidate	Specifies the candidate configuration datastore.

 

Verification

If the <edit-config> operation succeeds, the device returns the following response:

<?xml version="1.0">

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

To verify that the running configuration on the server has been changed as expected, perform a <get> operation.

Example: Retrieving all configuration data for all modules

Task

Retrieve all configuration data for all modules.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Retrieve all configuration data for all modules. Copy and paste the following request message to the client:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-config>

    <source>

      <running/>

    </source>

  </get-config>

</rpc>

Verification

If the requested operation succeeds, the server responds with the configuration for all modules. The following is a sample response:

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:web="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

  <data>

    <top xmlns="http://www.h3c.com/netconf/config:1.0">

      <Ifmgr>

        <Interfaces>

          <Interface>

            <IfIndex>1307</IfIndex>

            <Shutdown>1</Shutdown>

          </Interface>

          <Interface>

            <IfIndex>1308</IfIndex>

            <Shutdown>1</Shutdown>

          </Interface>

          <Interface>

            <IfIndex>1309</IfIndex>

            <Shutdown>1</Shutdown>

          </Interface>

          <Interface>

            <IfIndex>1311</IfIndex>

            <VlanType>2</VlanType>

          </Interface>

          <Interface>

            <IfIndex>1313</IfIndex>

            <VlanType>2</VlanType>

          </Interface>

        </Interfaces>

      </Ifmgr>

      <Syslog>

        <LogBuffer>

          <BufferSize>120</BufferSize>

        </LogBuffer>

      </Syslog>

      <System>

        <Device>

          <SysName>H3C</SysName>

          <TimeZone>

            <Zone>+11:44</Zone>

            <ZoneName>beijing</ZoneName>

          </TimeZone>

        </Device>

      </System>

      <Fundamentals>

        <WebUI>

          <SessionAgingTime>98</SessionAgingTime>

        </WebUI>

      </Fundamentals>

    </top>

  </data>

</rpc-reply>

Example: Retrieving all configuration data for the Syslog module

Task

Retrieve all configuration data for the Syslog module.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Retrieve all configuration data for the Syslog module. Copy and paste the following request message to the client:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-config>

    <source>

      <running/>

    </source>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/config:1.0">

        <Syslog/>

      </top>

    </filter>

  </get-config>

</rpc>

Verification

If the requested operation succeeds, the server responds with the configuration for the Syslog module. The following is a sample response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

  <data>

    <top xmlns="http://www.h3c.com/netconf/config:1.0">

      <Syslog>

        <LogBuffer>

          <BufferSize>120</BufferSize>

        </LogBuffer>

      </Syslog>

    </top>

  </data>

</rpc-reply>

Example: Retrieving one data entry from the interface table

Task

Retrieve one data entry from the interface table.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>urn:ietf:params:netconf:base:1.0</capability>

  </capabilities>

</hello>

# Retrieve one data entry from the interface table. Copy and paste the following request message to the client:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:web="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-bulk>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0" xmlns:web="http://www.h3c.com/netconf/base:1.0">

        <Ifmgr>

          <Interfaces web:count="1">

          </Interfaces>

        </Ifmgr>

      </top>

    </filter>

  </get-bulk>

</rpc>

Verification

If the requested operation succeeds, the server responds with the specified data entry from the interface table. The following is a sample response:

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:web="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

  <data>

    <top xmlns="http://www.h3c.com/netconf/data:1.0">

      <Ifmgr>

        <Interfaces>

          <Interface>

            <IfIndex>3</IfIndex>

            <Name>GigabitEthernet1/0/2</Name>

            <AbbreviatedName>GE1/0/2</AbbreviatedName>

            <PortIndex>3</PortIndex>

            <ifTypeExt>22</ifTypeExt>

            <ifType>6</ifType>

            <Description>GigabitEthernet 1/0/2 Interface</Description>

            <AdminStatus>2</AdminStatus>

            <OperStatus>2</OperStatus>

            <ConfigSpeed>0</ConfigSpeed>

            <ActualSpeed>100000</ActualSpeed>

            <ConfigDuplex>3</ConfigDuplex>

            <ActualDuplex>1</ActualDuplex>

          </Interface>

        </Interfaces>

      </Ifmgr>

    </top>

  </data>

</rpc-reply>

Example: Edit the setting for a parameter

Task

Configure the Syslog module (for the information center) to set the size of the general log buffer to 512. This setting enables the log buffer to store a maximum of 512 log entries.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>urn:ietf:params:netconf:base:1.0</capability>

  </capabilities>

</hello>

# Set the BufferSize column in the LogBuffer table of the Syslog module to 512. Copy and paste the following request message to the client:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:web="urn:ietf:params:xml:ns:netconf:base:1.0">

  <edit-config>

    <target>

      <running/>

    </target>

    <config>

      <top xmlns="http://www.h3c.com/netconf/config:1.0" web:operation="merge">

        <Syslog>

          <LogBuffer>

            <BufferSize>512</BufferSize>

          </LogBuffer>

        </Syslog>

      </top>

    </config>

  </edit-config>

</rpc>

Verification

If the requested operation succeeds, the device returns an operation succeeded response. The following is a sample response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

lock

The device supports a maximum of 32 concurrent NETCONF sessions for device management. In addition to NETCONF, users can configure and manage the device by using methods such as CLI and SNMP.

Before you configure, manage, or troubleshoot the device over a NETCONF session, you can lock the configuration to prevent other users from changing the device configuration.

After you lock the configuration, only you can perform <edit-config> operations to change or unlock the configuration as the lock holder. Other users can only read the configuration, and they will be unable to change or lock the configuration until after the configuration is unlocked.

 The system unlocks the configuration when the lock holder releases the lock or when its NETCONF session closes.

Request format

At the time of this writing, Comware NETCONF supports the <lock> operation only on the running configuration datastore. You cannot lock the configuration on a per-module basis.

Copy and paste the following request message to the client:

<?xml version="1.0" encoding="UTF-8"?>

  <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

    <lock>

      <target>

        <datastore/>

      </target>

    </lock>

  </rpc>

The value for datastore can be one of the following:

 

Value	Description
running	Specifies the running configuration datastore.
candidate	Specifies the candidate configuration datastore.

 

Verification

If the <lock> operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

Example: Locking the running configuration datastore

Task

Lock the running configuration datastore to prevent other users from changing the running configuration.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Lock the running configuration datastore. Copy and paste the following request message to the client:

<?xml version="1.0" encoding="UTF-8"?>

  <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

    <lock>

      <target>

        <running/>

      </target>

    </lock>

  </rpc>

Verification

If the <lock> operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

If the server receives a <lock> request from another NETCONF client after the running configuration datastore is locked, the device returns the following lock failed response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

<rpc-error>

  <error-type>protocol</error-type>

  <error-tag>lock-denied</error-tag>

  <error-severity>error</error-severity>

  <error-message xml:lang="en">Lock failed, lock is already held.</error-message>

  <error-info>

    <session-id>1</session-id>

  </error-info>

  </rpc-error>

</rpc-reply>

The message shows that the lock operation failed because the client with a session-id of 1 held the lock.

unlock

Only the NETCONF client that holds the configuration lock can perform the <unlock> operation to release the lock.

Request format

Copy and paste the following unlock request message to the client:

<?xml version="1.0" encoding="UTF-8"?>

  <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

    <unlock>

      <target>

        <datastore/>

      </target>

    </unlock>

  </rpc>

The value for datastore can be one of the following:

 

Value	Description
running	Specifies the running configuration datastore.
candidate	Specifies the candidate configuration datastore.

 

Verification

If the <unlock> operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

get

The <get> operation retrieves configuration and state date.

This operation retrieves all device configuration and state data that matches the specified filter in one request. As a best practice to retrieve massive data in multiple requests, use the Comware-extended <get-bulk> operation.

The <get-bulk> operation allows you to retrieve a specific number of data entries next to a particular data entry. For more information about using the <get-bulk> operation, see "get-bulk."

Request format

The following is the XML format for the <get> request:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter>

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        XML structure (module, submodule, table, and columns)

      </top>

    </filter>

  </get>

</rpc>

The <filter> element specifies the filtering conditions. For more information about filters and filtering results, see "Comware NETCONF data filtering." The filtering conditions can include the module name, submodule name, table name, and column name.

In a <get> request, you can use the Comware-extended count attribute to specify the number of data entries to retrieve, as shown in the following request message:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:xc="http://www.h3c.com/netconf/base:1.0">

  <get >

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0" xmlns:base="http://www.h3c.com/netconf/base:1.0">

        <Syslog>

          <Logs xc:count="5">

            <Log>

              <Index></Index>

           </Log>

          </Logs>

        </Syslog>

      </top>

    </filter>

  </get >

</rpc>

Use the count attribute in compliance with the following rules:

·     You can use the count attribute only in module and table elements within the <top> element. In this sample request, you can use the count attribute in the <Syslog> module element or in the <Logs> table element. In other types of elements, it cannot be resolved.

·     The table subelements in a module element inherit the count attribute (if any) specified in the module element, if they do not contain the count attribute.

·     If a table contains a subtable, only the count attribute in the table element takes effect. If you specify the count attribute in a subtable element, you must specify the index columns for all its ancestor elements.

·     If you do not specify the count attribute, the operation retrieves all data entries, starting from the specified index.

Verification

If the requested operation succeeds, the server responds with all matching configuration and state data. The following is the response format:

<?xml version="1.0"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    All matching configuration and state data

  </data>

</rpc-reply>

close-session

The <close-session> operation closes the current session.

Request format

To close the current session, copy and paste the following request message to the client:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <close-session/>

</rpc>

Verification

If the <close-session> operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

kill-session

The <kill-session> operation forces a NETCONF session other than the current session to close. If the client that established the session is at the CLI, this operation places the client in user view.

Request format

To force a session other than the current one to close, copy and paste the following message to the client, and then specify the session ID of that session:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <kill-session>

    <session-id>

      Specify the session ID of the session to close

    </session-id>

  </kill-session>

</rpc>

Verification

If the <kill-session> operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

Example: Forcing a session to close

Task

The target device has two NETCONF sessions, one with session ID 1 and the other with session ID 2. Force NETCONF session 2 to close from the NETCONF client connected to session 1.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Force NETCONF session 2 to close. Copy and paste the following request message to the client:

<rpc message-id="101"    xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <kill-session>

    <session-id>2</session-id>

  </kill-session>

</rpc>

Verification

If the server forces NETCONF session 2 to close successful, the device returns the following response. The NETCONF client connected to session 2 returns from XML view to user view.

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101"  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

create-subscription

A NETCONF client can subscribe to Syslog events, events monitored by NETCONF, and events reported by modules. The device will then push subscribed events to the subscribers as configured. Event subscription is available only for NETCONF over Telnet and NETCONF over SSH.

Subscribing to Syslog events

The Syslog events available for subscription are system log messages. If a NETCONF client has subscribed to a system log message, the server pushes the log message to the client when it occurs. The event notification includes the mnemonic symbol of the log message, its source module, severity level, time of occurrence, and event description.

For information about the log messages to which you can subscribe, see the system log messages reference for the device.

When you subscribe to Syslog events, use the following guidelines:

·     A subscription takes effect on a session for the lifetime of that session. It is canceled when the session closes.

·     You can subscribe to multiple events by specifying multiple <filter> elements, one for each event.

·     At the time of this writing, Comware does not support event playback.

·     You can unsubscribe from an event. However, you cannot renew or edit a subscription.

The following is the XML format for the Syslog event subscription request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <create-subscription  xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

    <stream>NETCONF</stream>

    <filter>

      <event xmlns="http://www.h3c.com/netconf/event:1.0">

        <Code>code</Code>

        <Group>group</Group>

        <Severity>severity</Severity>

      </event>

    </filter>

    <startTime>start-time</startTime>

    <stopTime>stop-time</stopTime>

  </create-subscription>

</rpc>

A Syslog event subscription request contains the following elements:

·     stream: Specifies an event stream. The name for the syslog event stream is NETCONF.

·     event: Specifies an event.

·     code: Specifies the mnemonic symbol of the log message.

·     group: Specifies the module name of the log message.

·     severity: Specifies the severity level of the log message.

·     start-time: Specifies the start date and time of the subscription.

·     stop-time: Specifies the end date and time of the subscription.

If the subscription is successful, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply >

If a subscription error occurs, the device returns an error response, in the following format:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <rpc-error>

    <error-type>error-type</error-type>

    <error-tag>error-tag</error-tag>

    <error-severity>error-severity</error-severity>

    <error-message xml:lang="en">error-message</error-message>

  </rpc-error>

</rpc-reply>

For more information about the elements in an error response, see RFC 4741.

Subscribing to events monitored by NETCONF

After a NETCONF client subscribes to an event monitored by NETCONF, the server regularly pushes the matching event instances to the NETCONF client.

The following is the XML format for the NETCONF monitored-event subscription request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <create-subscription xmlns='urn:ietf:params:xml:ns:netconf:notification:1.0'>

    <stream>NETCONF_MONITOR_EXTENSION</stream>

    <filter>

      <NetconfMonitor xmlns='http://www.h3c.com/netconf/monitor:1.0'>

        <XPath>XPath</XPath>

        <Interval>interval</Interval>

        <ColumnConditions>

          <ColumnCondition>

            <ColumnName>ColumnName</ColumnName>

            <ColumnValue>ColumnValue</ColumnValue>

            <ColumnCondition>ColumnCondition</ColumnCondition>

          </ColumnCondition>

        </ColumnConditions>

        <MustIncludeResultColumns>

          <ColumnName>columnName</ColumnName>

        </MustIncludeResultColumns>

      </NetconfMonitor>

    </filter>

    <startTime>start-time</startTime>

    <stopTime>stop-time</stopTime>

  </create-subscription>

</rpc>

Table 13 Elements in a monitored-event subscription request

Element	Description
stream	Specifies an event stream. The name for the monitored-event stream is NETCONF_MONITOR_EXTENSION.
NetconfMonitor	Specifies information that identifies the event of interest.
XPath	Specifies the XPath of the monitored event in the format of ModuleName[/SubmoduleName]/TableName.
Interval	Specifies the interval for the server to retrieve and push events that match the subscription condition. The value range is 1 to 4294967 seconds. The default value is 300 seconds.
ColumnName	Specifies the name of a column in the monitored table, in [GroupName.]ColumnName format.
ColumnValue	Specifies the column value on which the filter operates.
ColumnCondition	Specifies an operator: ·     more—Greater than the specified value. ·     less—Less than the specified value. ·     notLess—Equal to or greater than the specified value. ·     notMore—Equal to or less than the specified value. ·     equal—Equal to the specified value. ·     notEqual—Greater than or less than the specified value. ·     include—Include the specified value. ·     exclude—Not include the specified value. ·     startWith—Start with the specified value. ·     endWith—End with the specified value. The operators you can use depend on the data type of the specified value.
start-time	Start date and time of the subscription.
stop-time	End date and time of the subscription.

 

IMPORTANT: The order of the elements in a NETCONF monitored-event subscription request must be in strict compliance with the XML format provided in this document.

 

If the subscription succeeds, the device returns a response in the following format:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

Subscribing to events reported by modules

A NETCONF client can subscribe to a module to receive events of interest. On receipt of a subscribed event from the module, the NETCONF server pushes the event to the client.

The following is the XML format for the module-reported event subscription request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:xs="http://www.h3c.com/netconf/base:1.0">

  <create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

    <stream>XXX_STREAM</stream>

    <filter type="subtree">

      <event xmlns="http://www.h3c.com/netconf/event:1.0/xxx-features-list-name:1.0">

        <ColumnName xs:condition="Condition">value</ColumnName>

      </event>

    </filter>

    <startTime>start-time</startTime>

    <stopTime>stop-time</stopTime>

  </create-subscription>

</rpc>

Table 14 Elements in requests that subscribe to events reported by modules

Element	Description
stream	Specifies an event stream. Supported module-reported event streams vary by device model.
event	Specifies an event name. An event stream includes multiple events. The events use the same namespace as the event stream.
ColumnName	Specifies the name of a column.
Condition	Specifies an operator: ·     more—Greater than the specified value. ·     less—Less than the specified value. ·     notLess—Equal to or greater than the specified value. ·     notMore—Equal to or less than the specified value. ·     equal—Equal to the specified value. ·     notEqual—Greater than or less than the specified value. ·     include—Include the specified value. ·     exclude—Not include the specified value. ·     startWith—Start with the specified value. ·     endWith—End with the specified value. The operators you can use depend on the data type of the specified value.
value	Specifies a column value.
start-time	Start date and time of the subscription.
stop-time	End date and time of the subscription.

 

If the subscription succeeds, the device returns a response in the following format:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

Example: Subscribing to events

Task

Subscribe to all events without a time limit. The server pushes all events to the client until the NETCONF session closes.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Send the subscription message.

·     Subscribe to Syslog events:

# Subscribe to all Syslog events without a time limit. Copy and paste the following request message to the client:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <create-subscription xmlns ="urn:ietf:params:xml:ns:netconf:notification:1.0">

    <stream>NETCONF</stream>

  </create-subscription>

</rpc>

If the subscription succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

  <ok/>

</rpc-reply>

The following is a sample event notification that the device sent when an airflow issue was detected on fan tray 1:

<?xml version="1.0" encoding="UTF-8"?>

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

  <eventTime>2011-01-04T12:30:46</eventTime>

  <event xmlns="http://www.h3c.com/netconf/event:1.0">

    <Group>DEV</Group>

    <Code>FAN_DIRECTION_NOT_PREFERRED</Code>

    <Slot>6</Slot>

    <Severity>Alert</Severity>

    <context>Fan 1 airflow direction is not preferred on slot 6, please check it.</context>

  </event>

</notification>

The following is a sample event notification that the device sent when a user logged in to the device from 192.168.100.130:

<?xml version="1.0" encoding="UTF-8"?>

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

  <eventTime>2011-01-04T12:30:52</eventTime>

  <event xmlns="http://www.h3c.com/netconf/event:1.0">

    <Group>SHELL</Group>

    <Code>SHELL_LOGIN</Code>

    <Slot>6</Slot>

    <Severity>Notification</Severity>

    <context>VTY logged in from 192.168.100.130.</context>

  </event>

</notification>

·     Subscribe to events monitored by NETCONF.

# Subscribe to receive Device/Base table events at 1-second intervals. Copy and paste the following request message to the client:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

<create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

  <stream>NETCONF_MONITOR_EXTENSION</stream>

  <filter>

    <NetconfMonitor xmlns="http://www.h3c.com/netconf/monitor:1.0">

      <XPath>Device/Base</XPath>

      <Interval>1</Interval>

      <ColumnConditions>

        <ColumnCondition>

          <ColumnName>HostName</ColumnName>

          <ColumnValue>H3C</ColumnValue>

          <ColumnCondition>include</ColumnCondition>

        </ColumnCondition>

      </ColumnConditions>

    </NetconfMonitor>

  </filter>

</create-subscription>

</rpc>

If the subscription succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

  <ok/>

</rpc-reply>

Then, the device sends Device/Base table events to the client at 1-second intervals. The following is a sample event notification:

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

  <eventTime>2020-02-22T09:28:14</eventTime>

  <NetconfMonitor xmlns="http://www.h3c.com/netconf/monitor:1.0">

    <Device xmlns="http://www.h3c.com/netconf/data:1.0">

      <Base>

        <HostName>H3C</HostName>

      </Base>

    </Device>

  </NetconfMonitor>

</notification>

·     Subscribe to events reported by modules.

# Subscribe to all events reported by the Ifmgr module. Copy and paste the following request message to the client:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0" xmlns:xs="http://www.h3c.com/netconf/base:1.0">

    <stream>Ifmgr</stream>

  </create-subscription>

</rpc>

If the subscription succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

  <ok/>

</rpc-reply>

The following is a sample notification that the device sent when an interface went down:

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

  <eventTime>2020-02-22T09:32:10</eventTime>

  <InterfaceEvent xmlns="Ifmgr:1.0">

    <Interface>

      <Name>GigabitEthernet2/0/2</Name>

      <Status>IF_DEACTIVE</Status>

      <IfIndex>286</IfIndex>

      <AdminStatus>ADMIN_UP</AdminStatus>

      <OperStatus>OPER_DOWN</OperStatus>

      <Description>The Interface GigabitEthernet2/0/2 occurred IF_DEACTIVE event,the administration status is ADMIN_UP,operation status is OPER_DOWN.</Description>

    </Interface>

  </InterfaceEvent>

</notification>

The following is a sample notification that the device sent when an interface came up:

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

  <eventTime>2020-02-22T09:32:10</eventTime>

  <InterfaceEvent xmlns="Ifmgr:1.0">

    <Interface>

      <Name>GigabitEthernet2/0/2</Name>

      <Status>IF_ACTIVE</Status>

      <IfIndex>286</IfIndex>

      <AdminStatus>ADMIN_UP</AdminStatus>

      <OperStatus>OPER_DOWN</OperStatus>

      <Description>The Interface GigabitEthernet2/0/2 occurred IF_ACTIVE event,the administration status is ADMIN_UP,operation status is OPER_DOWN.</Description>

    </Interface>

  </InterfaceEvent>

</notification>

validate

The <validate> operation examines the NETCONF XML request for syntax errors and violation of constraints. The Comware NETCONF server only examines a request for syntax errors and does not check for violation of additional constraints. A request might still fail even if it has been validated to be syntactically correct.

You can send a request without using the <validate> operation for prior validation, because the NETCONF server always examines a request for syntax errors.

get-schema

The <get-schema> operation retrieves the content of a data model file. At the time of this writing, you can only retrieve the content of YANG module files.

Request format

The following is the XML format for the <get-schema> request message:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-schema xmlns='urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring'>

    <identifier>syslog-data</identifier>

    <version>2015-05-07</version>

    <format>yang</format>

  </get-schema>

</rpc>

For information about the <identifier>, <version>, and <format> elements, see "netconf-state."

Verification

If the requested operation succeeds, the device responds with the requested content of the YANG module file. The following is the response format:

<?xml version="1.0"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    Content of the specified YANG module file

  </data>

</rpc-reply>

netconf-state

To retrieve the following types of data, use the following subtrees in a get operation:

·     To retrieve the list of capability sets on the device, use the <netconf-state><capabilities/></netconf-state> subtree.

·     To retrieve the list of NETCONF configuration datastores on the device, use the <netconf-state><datastores/></netconf-state> subtree.

·     To retrieve the list of schema files on the device, use the <netconf-state><schemas/></netconf-state> subtree.

·     To retrieve the list of active NETCONF sessions on the device, use the <netconf-state><sessions/></netconf-state> subtree.

·     To retrieve the global statistics for the NETCONF server, use the <netconf-state><statistics/></netconf-state> subtree.

The following is the XML format for the <get> request message with the <netconf-state> subtree:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter type='subtree'>

      <netconf-state xmlns='urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring'>

        <getType/>

      </netconf-state>

    </filter>

  </get>

</rpc>

·     Replace the getType argument with capabilities, datastores, schemas, sessions, or statistics, depending on the data you are retrieving. To retrieve all types of netconf-state data, send the request without the <getType/> element.

·     At the time of this writing, data filtering is not available for netconf-state data retrieval.

Example: Retrieving the NETCONF capability sets on the device

Request format

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter type='subtree'>

      <netconf-state xmlns='urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring'>

        <capabilities/>

      </netconf-state>

    </filter>

  </get>

</rpc>

Verification

If the requested operation succeeds, the device responds with its NETCONF capability sets. The following is a sample response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">

      <capabilities>

        <capability>urn:ietf:params:netconf:base:1.0</capability>

        <capability>urn:ietf:params:netconf:capability:writable-running:1.0</capability>

        <capability>urn:ietf:params:netconf:capability:notification:1.0</capability>

     </capabilities>

    </netconf-state>

  <data>

</rpc-reply>

The capability set in this sample response is for illustration only.

Example: Retrieving the NETCONF datastores on the device

Request format

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter type='subtree'>

      <netconf-state xmlns='urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring'>

      <datastores/>

      </netconf-state>

    </filter>

  </get>

</rpc>

Verification

If the requested operation succeeds, the device responds with the requested NETCONF configuration datastore. The following is a sample response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">

      <datastores>

        <datastore>

          <name>running</name>

          <locks>

            <global-lock>

            <locked-by-session>1</locked-by-session>

            <locked-time>2015-07-30T12:54:45</locked-time>

            </global-lock>

          </locks>

       </datastore>

      </datastores>

    </netconf-state>

  <data>

</rpc-reply>

At the time of this writing, Comware supports only the running configuration datastore.

The <locks> element indicates whether the NETCONF client holds the lock and provides information about the lock.

Example: Retrieving the list of schema files on the device

Request format

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter type='subtree'>

      <netconf-state xmlns='urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring'>

        <schemas/>

      </netconf-state>

    </filter>

  </get>

</rpc>

Verification

If the requested operation succeeds, the server responds with the list of schema files on the device. The following is a sample response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">

<schemas>

        <schema>

          <identifier>syslog-data</identifier>

          <version>2015-05-07</version>

          <format>yang</format>

          <namespace>http://www.h3c.com/netconf/data:1.0</namespace>

          <location>NETCONF</location>

        </schema>

      </schemas>

    </netconf-state>

  <data>

</rpc-reply>

 

NOTE: ·     To retrieve the content of a schema file, use its identifier, version, and format information to construct a <get-schema> request. ·     The value for the <format> element can only be yang (YANG module files). ·     The <namespace> element contains the namespace of the file. ·     The <location> element contains the file storage location. At the time of this writing, the value is fixed at NETCONF. The file is stored on a disk on the device.

 

Example: Retrieving the list of active NETCONF sessions on the device

Request format

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter type='subtree'>

      <netconf-state xmlns='urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring'>

        <sessions/>

      </netconf-state>

    </filter>

  </get>

</rpc>

Verification

If the requested operation succeeds, the server responds with the list of active NETCONF sessions on the device. The following is a sample response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">

      <sessions>

        <session>

          <session-id>1</session-id>

          <transport>netconf-soap-over-http</transport>

          <username>test</username>

          <source-host>192.168.100.68</source-host>

          <login-time>2015-07-30T09:44:03</login-time>

          <in-rpcs>0</in-rpcs>

          <in-bad-rpcs>0</in-bad-rpcs>

          <out-rpc-errors>0</out-rpc-errors>

          <out-notifications>0</out-notifications>

        </session>

      </sessions>

    </netconf-state>

  <data>

</rpc-reply>

The response contains the following information:

 

Element	Description
session-id	Identifier that uniquely identifies the NETCONF session.
transport	The transport protocol for the session.
username	Username with which the NETCONF client logged in to the device.
source-host	The IP address with which the NETCONF client initiated the session.
login-time	The login date and time.
in-rpcs	Number of valid RPCs received by the device over the session.
in-bad-rpcs	Number of invalid RPCs received by the device over the session.
out-rpc-errors	Number of RPC errors sent by the device over the session.
out-notifications	Number of event notifications sent by the device over the session.

 

Example: Retrieving NETCONF global statistics

Request format

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter type='subtree'>

      <netconf-state xmlns='urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring'>

        <statistics/>

      </netconf-state>

    </filter>

  </get>

</rpc>

Verification

If the requested operation succeeds, the device responds with the NETCONF global statistics on it. The following is a sample response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">

      <statistics>

        <netconf-start-time>2015-07-30T09:44:01</netconf-start-time>

        <in-bad-hellos>0</in-bad-hellos>

        <in-sessions>2</in-sessions>

        <dropped-sessions>0</dropped-sessions>

        <in-rpcs>1</in-rpcs>

        <in-bad-rpcs>0</in-bad-rpcs>

        <out-rpc-errors>0</out-rpc-errors>

        <out-notifications>0</out-notifications>

      </statistics>

    </netconf-state>

  <data>

</rpc-reply>

The response contains the following information:

 

Element	Description
netconf-start-time	Date and time when the NETCONF service started.
in-bad-hellos	Number of invalid <hello> messages received by the device.
in-sessions	Number of sessions established.
dropped-sessions	Number of NETCONF sessions dropped because of session timeout.
in-rpcs	Number of valid RPC requests received by the device.
in-bad-rpcs	Number of invalid RPC requests received by the device.
out-rpc-errors	Number of RPC errors sent by the device.
out-notifications	Number of event notifications sent by the device.

 

commit (immediate commit)

The immediate <commit> operation commits the candidate configuration to the running configuration datastore immediately.

Request format

The following is the XML format for the immediate <commit> request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <commit/>

</rpc>

Verification

If the requested operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

commit (confirmed commit)

The confirmed <commit> operation requires a confirming <commit> operation to be performed within the confirmation timeout period to commit the candidate configuration to the running configuration datastore. If you fail to do a confirming <commit> within the timeout period, the device automatically rolls back the running configuration to the previously committed configuration.

When you perform a confirmed <commit> operation, you must specify the <confirmed> node and can optionally specify the following columns:

·     <confirm-timeout>—Sets the confirmation timeout timer, in seconds. The default is 600 seconds.

·     <persist>—Specifies an identifier to identify the target candidate configuration to be committed. This element ensures that a follow-up commit or other operations can be performed on the target candidate configuration on any sessions after the NETCONF session terminates. If you do not include the <persist> element in this commit operation, you can perform a follow-up commit operation or other operations on the specified candidate configuration only on the same session that issued the confirmed <commit> operation.

Request format

The following sample request shows the XML format for the confirmed <commit> request. This sample request sets the confirmation timeout timer to 600 seconds and sets the candidate configuration identifier to test.

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <commit>

    <confirmed/>

    <confirm-timeout>600</confirm-timeout>

    <persist>test</persist>

  </commit>

</rpc>

Verification

If the requested operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

commit (confirming commit)

The confirming <commit> operation commits the candidate configuration issued by a confirmed <commit> operation to the running configuration.

When you use this operation, follow these guidelines:

·     The confirming <commit> operation takes effect only if you execute it before the confirmation timeout timer sets in the confirmed <commit> operation expires.

·     If the <persist> element is included in the confirmed <commit> operation, you must also include the <persist-id> element in the confirming <commit> operation. Make sure the value for the <persist-id> element is the same as that specified in the <persist> element set in the confirmed <commit> operation.

·     If the <persist> element is not included in the confirmed operation, the confirming <commit> operation uses the same XML structure as the immediate <commit> operation.

Request format

The following sample request shows the XML format for the confirming <commit> request with the <persist-id> element included. In this example, the candidate configuration identifier is test.

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <commit>

    <persist-id>test</persist-id>

  </commit>

</rpc>

Verification

If the requested operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

cancel-commit

The <cancel-commit> operation cancels an ongoing confirmed <commit> operation and rolls back the running configuration to the state before the confirmed <commit> operation was performed.

Perform this task before the confirmation timeout timer expires.

Request format

The following is the XML format for the <cancel-commit> operation that cancels the confirmed <commit> operation on the same session that issued the confirmed <commit> operation:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <cancel-commit/>

</rpc>

Verification

If the requested operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

copy-config

The <copy-config> operation copies the running configuration to a target configuration datastore. If the target configuration datastore does not exist, this operation creates the datastore.

At the time of this writing, this operation can only copy the running configuration to the candidate configuration store.

Request format

The following is the XML format for the <copy-config> request to copy the running configuration to the candidate configuration datastore:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <copy-config>

    <source>

      <running/>

    </source>

    <target>

     <candidate/>

    </target>

  </copy-config>

</rpc>

Verification

If the requested operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

delete-config

The <delete-config> operation deletes a configuration datastore.

At the time of this writing, this operation can delete only the candidate configuration store.

Request format

The following is the XML format for the request to delete the candidate configuration datastore:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <delete-config>

    <target>

      <candidate/>

    </target>

  <delete-config/>

</rpc>

Verification

If the requested operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

discard-changes

The <discard-changes> operation revert the candidate configuration to the current running configuration.

Request format

The following is the XML format for the <discard-changes> request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <discard-changes/>

</rpc>

Verification

If the requested operation succeeds, the device returns the following response:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

Comware-extended protocol operations

get-bulk

The <get-bulk> operation retrieves a specific number of data entries starting from the data entry next to the one with the specified index. Use the <Index> element to specify an index and use the count attribute to specify the number of entries to retrieve.

If you do not specify an index, the retrieval starts from the first data entry.

This operation retrieves all remaining data entries starting from the data entry next to the one with the specified index if either of the following conditions occurs:

·     You do not specify the count attribute.

·     The number of matching data entries is less than the value in the count attribute.

The <get> operation retrieves all configuration and state data that matches the specified filter in one request. This might cause performance issues when a client retrieves massive data and is not efficient when the client only needs to retrieve some of the data entries.

For efficient retrieval of massive data, use the <get-bulk> operation to retrieve data in multiple requests. In addition, you can use the <get-bulk> operation to retrieve only the data entries of interest.

Request format

The following is the XML format for the <get-bulk> request:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-bulk>

    <filter>

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        XML structure (module, submodule, table, and columns)

      </top>

    </filter>

  </get-bulk>

</rpc>

The <filter> element specifies the filtering conditions. For more information about filters and filtering results, see "Comware NETCONF data filtering." The filtering conditions can include the module name, submodule name, table name, and column name.

The following is a sample <get-bulk> request that contains the count attribute and the <Index> element:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:xc="http://www.h3c.com/netconf/base:1.0">

  <get-bulk>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0" xmlns:base="http://www.h3c.com/netconf/base:1.0">

        <Syslog>

          <Logs xc:count="5">

            <Log>

              <Index>10</Index>

            </Log>

          </Logs>

        </Syslog>

      </top>

    </filter>

  </get-bulk>

</rpc>

Use the count attribute in compliance with the following rules:

·     You can use the count attribute only in module and table elements. In this sample request, you can use the count attribute in the <Syslog> module element or in the <Logs> table element. In other types of elements, it cannot be resolved.

·     The table subelements in a module element inherit the count attribute (if any) specified in the module element, if they do not contain the count attribute.

·     If a table contains a subtable, only the count attribute in the table element takes effect. If you specify the count attribute in a subtable element, you must specify the index columns for all its ancestor elements.

·     If you do not specify the count attribute, the operation retrieves all data entries, starting from the specified index.

Verification

If the requested operation succeeds, the server responds with all matching data entries. The following is the response format:

<?xml version="1.0"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    All matching configuration and state data

  </data>

</rpc-reply>

get-bulk-config

The <get-bulk-config> operation retrieves a specific number of non-default configuration data entries, starting from the data entry next to the one with the specified index.

The <get-bulk-config> operation uses the same XML request format as the <get-config> operation, except that the <get-bulk-config> operation introduces the <Index> and the count attribute for efficient retrieval of massive data.

In the <get-bulk-config> request, you can use the <Index> element to specify an index and use the count attribute to specify the number of entries to retrieve.

The guidelines for the <get-bulk> operation also apply to this operation.

Request format

The following is the XML format for the <get-config> and <get-bulk-config> requests:

<?xml version="1.0"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-config>

    <source>

      <datastore/>

    </source>

    <filter>

      <top xmlns="http://www.h3c.com/netconf/config:1.0">

          XML structure (module, submodule, table, and columns)

      </top>

    </filter>

  </get-config>

</rpc>

The value for datastore can be one of the following:

 

Value	Description
running	Specifies the running configuration datastore.
candidate	Specifies the candidate configuration datastore.

 

Verification

If the requested operation succeeds, the server responds with the matching configuration data entries. The following is the response format:

<?xml version="1.0"?>

<rpc-reply message-id="100"   xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    Data matching the filter

  </data>

</rpc-reply>

action

The <action> operation instructs the device to execute a non-configuration operation, for example, to ping an address or to clear the statistics on an interface.

If the operation succeeds, the device returns </ok> or information about the result. If the operation fails, the device returns an error message.

Request format

The following is the XML format for the <action> request:

<?xml version="1.0"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <action>

    <top xmlns="http://www.h3c.com/netconf/action:1.0">

      XML structure (module, submodule, table, and columns)

    </top>

  </action>

</rpc>

Verification

If the operation succeeds, the device returns </ok> or the operation results.

The following is the XML format for the success response without operation results:

<?xml version="1.0"?>

<rpc-reply message-id="100"   xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

The following is the XML format for the success response that contains operation results:

<?xml version="1.0"?>

<rpc-reply message-id="100"   xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <action-result>

    Operation results

  </action-result>

</rpc-reply>

Example: Permitting the NETCONF client to send <edit-config> requests during configuration rollback on the current session

Task

Permit the NETCONF client to send <edit-config> requests during configuration rollback on the current session.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>urn:ietf:params:netconf:base:1.0</capability>

  </capabilities>

</hello>

# Request the device to permit the NETCONF client to send <edit-config> requests during configuration rollback on the current session. Copy and paste the following request message to the client:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <action>

    <error-option>stop-on-error</error-option>

    <top xmlns="http://www.h3c.com/netconf/action:1.0">

      <Fundamentals>

        <CurrentSessionOpt>

          <DisableEditConfigWhenRollback>false</DisableEditConfigWhenRollback>

        </CurrentSessionOpt>

      </Fundamentals>

    </top>

  </action>

</rpc>

Verification

If the requested operation succeeds, the device responds with a success response without operation results.

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

# To prevent the NETCONF client from editing the configuration during configuration rollback on the current session, set the <DisableEditConfigWhenRollback> element to true.

load

The <load> operation adds the configuration in a configuration file into the running configuration datastore. If the running configuration already contains a setting for a parameter, the system replaces that setting with the setting in the configuration file.

 

IMPORTANT: The <load> operation will fail for a parameter if the system requires that you must delete its setting before you can reconfigure it.

 

Request format

The following is the XML format for the <load> request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <load>

    <file>Path of the configuration file to load</file>

  </load>

</rpc>

The configuration file must use the .cfg extension. The extension is case insensitive.

Verification

If the configuration file is loaded successfully, the device returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

save

The <save> operation saves the running configuration to a configuration file.

Request format

The following is the XML format for the <save> request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save OverWrite=”false” VsysName=”vsys-name” Safely=”false”>

    <file>destination configuration file name</file>

  </save>

</rpc>

 

Element or attribute	Description
<file>	In the <file> element, specify the name of the .cfg configuration file to which the running configuration is to be saved. The name must start with the storage media name and end with the .cfg extension. The extension is case insensitive. The <file> element is optional. If you include the element in the request, you must specify a file name. If the request does not include the element, the configuration is automatically saved to the default main next-startup configuration file.
OverWrite	The OverWriteattribute attribute determines whether to overwrite the specified file if the file already exists. The following values are available: ·     true—Overwrites the file. ·     false—Prevents the device from saving the running configuration to the specified file. In this situation, the device returns an error message. The default value is true.
VsysName	The VsysName attribute takes effect only when the target device supports vSystems. ·     If the NETCONF client is connected to a non-default vSystem, you cannot specify the VsysName attribute in the request or include the <file> element in the request to specify a destination file. ·     If the NETCONF client is connected to the default vSystem, you can include the VsysName attribute and <file> element in the request to save the running configuration to the specified file for the specified vSystem. You can use the VsysName attribute together with the OverWrite attribute, but not with the Binary-only attribute.
Safely	Determines whether to save the configuration file in safe mode or fast mode.  Available values: ·     true—Saves the configuration in safe mode. In this mode, the system saves the configuration in a temporary file and starts overwriting the target next-startup configuration file after the save operation is complete. If a disruptive event such as a reboot or power failure occurs during the save operation, the device can still start up with the original next-startup configuration file. ·     false—Saves the configuration in fast mode. In this mode, the system directly overwrites the target next-startup configuration file. If a disruptive event such as a reboot, power failure, out-of-memory, out-of-storage event occurs during this process, the next-startup configuration file is lost. You must specify a new startup configuration file after the device reboots. By default, the Safely attribute is set to false if you do not specify a value for it. Safe mode is slower than fast mode, but more secure. As a best practice, use the safe mode if the power source is not reliable or you are remotely configuring the device.

 

Verification

If the running configuration is saved successfully, the device returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

Example: Saving the running configuration to a configuration file

Task

Save the running configuration to the my_config.cfg configuration file.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Save the running configuration to the my_config.cfg configuration file. Copy and paste the following request message to the client:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save>

    <file>my_config.cfg</file>

  </save>

</rpc>

Verification

If the requested operation succeeds, the server responds with a success response without operation results.

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

rollback

The <rollback> operation replaces the running configuration with the configuration from a configuration file.

Request format

The following is the XML format for a <rollback> request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <rollback>

    <file>Replacement configuration file name</file>

  </rollback>

</rpc>

Verification

If the configuration rolls back successfully, the device returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

CLI

The <CLI> operation executes CLI commands encoded in XML format.

The <CLI> operation includes the Open-channel, Close-channel, Execution, and Configuration options.

·     Open-channel—Opens a persistent channel for the current session.

·     Close-channel—Closes the persistent channel for the current session.

·     Execution—Executes commands in user view. The system cannot execute the system command to enter system view for command execution.

·     Configuration—Executes commands in system view by default. From system view, you can enter lower-level views. To change between views, use the system and quit commands to change between views. If you issue CLI commands over a persistent or temporary channel, you cannot use the quit command to exit user view. The system executes each of the specified commands in the view that the CLI stays upon execution of the previous command, except that the system always executes the first command in system view.

Table 15 Elements and attributes in the <CLI> operation tag

Operation	Description	Example
<Open-channel>	Opens a persistent channel to access the CLI in system view. If a persistent channel already exists, the device returns a failure message.	Open a persistent channel to access the CLI in system view: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <CLI>     <Open-channel/>   </CLI> </rpc>
<Close-channel>	Closes the persistent channel. If the operation fails, the device returns an error message.	Close the persistent channel: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <CLI>     <Close-channel/>   </CLI> </rpc>
<Configuration>	You must include the exec-use-channel attribute in the <configuration> element to indicate the method to issue CLI commands. Options for the exec-use-channel attribute: ·     false—Issues commands without using a channel. ·     true—Issues commands over a temporary channel. The channel automatically closes after the commands are executed. ·     persist—Issues commands over a persistent channel for the session. A session can have only one persistent channel.	Execute the display this command in system over the persistent channel: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <CLI>     <Configuration exec-use-channel=”persist”>       display this     </Configuration>   </CLI> </rpc>
<Execution>	Executes commands in user view.	Execute the display this command in user view: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <CLI>     <Execution>       display this     </Execution>   </CLI> </rpc>

 

Table 16 describes the value options for the exec-use-channel attribute in the <Configuration> element.

Table 16 Value options for the exec-use-channel attribute in the <Configuration> element

Attribute value	Description	Example
false	Uses the exec comsh command to open the CLI. This method is slow because the system must start the comsh process to open the CLI.	Execute the display this command in system view: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <CLI>     <Configuration exec-use-channel=”false”>       display this     </Configuration>   </CLI> </rpc>
true	Issues commands over a temporary channel. This method is faster than the exec comsh method. However, the improvement is slight, because the system must execute the commands in CLI.	Execute the display this command in system view: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <CLI>     <Configuration exec-use-channel=”true”>       display this     </Configuration>   </CLI> </rpc>
persist	Issues commands over the persistent channel. If the channel has not been created, the system creates it first. If the channel already exists, the system executes commands in the view that the CLI stays for the channel.	Execute the display this command in system view: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <CLI>     <Configuration exec-use-channel=”persist”>       display this     </Configuration>   </CLI> </rpc>

 

Usage guidelines

·     As a best practice, do not use the <CLI> operation to execute interactive CLI commands. The operation is very likely to fail, because user interaction is required.

·     Before you issue a configuration command over a channel, make sure the returned data will not exceed 4000 lines. The channel will hang up if this limit is exceeded and you cannot execute the quit command to quit.

Request format

Use one of the following XML formats to construct a <CLI> request:

·     Issue commands without using a channel:

Method 1:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Execution>

      Series of commands, one on a line

    </Execution>

  </CLI>

</rpc>

Method 2:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Configuration exec-use-channel="false">

      Series of commands, one on a line

    </ Configuration>

  </CLI>

</rpc>

·     Issue commands over a temporary channel:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Configuration exec-use-channel="true">

      Series of commands, one on a line

    </ Configuration>

  </CLI>

</rpc>

·     Issue commands over the persistent channel:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Configuration exec-use-channel="persist">

      Series of commands, one on a line

    </ Configuration>

  </CLI>

</rpc>

·     Open a persistent channel:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Open-channel/>

  </CLI>

</rpc>

·     Close the persistent channel:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Close-channel/>

  </CLI>

</rpc>

You can enclose a series of commands in one <Execution> or <Configuration> element, with one command on a line.

Verification

If the requested operation succeeds, the device returns a response in the following format, with data enclosed in a CDATA tag:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Execution>

      <![CDATA[returned data]]>

    </Execution>

  </CLI>

</rpc-reply>

If the <Open-channel> or <Close-channel> operation succeeds, the device returns the following message:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="101235" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

If the <Open-channel>, <Close-channel>, <Configuration exec-use-channel="true">, or <Configuration exec-use-channel="persist"> operation fails, the device returns an error response in the following format:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-error xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <error-type>application</error-type>

  <error-tag>data-missing</error-tag>

  <error-severity>error</error-severity>

  <error-message xml:lang="en">error message</error-message>

</rpc-error>

Example: Executing CLI commands from a NETCONF client

Task

Retrieve the running configuration by issuing the display current-configuration  command from a NETCONF client.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Issue the command that displays the running configuration from the NETCONF client. Copy and paste the following request message to the client:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Execution>

      display current-configuration

    </Execution>

  </CLI>

</rpc>

Verification

If the requested operation succeeds, the device responds with the running configuration on the device.

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <CLI>

    <Execution><![CDATA[

#

 version 7.1.052, Demo 2501005

#

 sysname ab

#

 ftp server enable

 ftp update fast

 ftp timeout 2000

#

 irf mac-address persistent timer

 irf auto-update enable

 undo irf link-delay

#

 domain default enable system

#

 telnet server enable

#

vlan 1

#

vlan 1000

#

radius scheme system

 primary authentication 127.0.0.1 1645

   ]]>

   </Execution>

  </CLI>

</rpc-reply>

get-sessions

The <get-sessions> operation retrieves all active NETCONF sessions on the device.

Request format

The following is the XML format for the <get-sessions> request:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-sessions/>

</rpc>

Verification

If the requested operation succeeds, the device returns a response in the following format:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-sessions>

    <Session>

      <SessionID>session ID</SessionID>

      <Line>user line</Line>

      <UserName>login username</UserName>

      <Since>date and time of login</Since>

      <LockHeld>whether the user holds the lock</LockHeld>

    </Session>

  </get-sessions>

</rpc-reply>

Table 17 Elements in the <get-sessions> response

Element	Description
SessionID	ID of the session. The return value is 1 or a higher number.
Line	User line over which the session is established. For a NETCONF over SOAP session, this element contains an empty value.
UserName	Username with which the NETCONF client logged in to the device.
Since	Date and time when the client logged in. The return value is schema-defined standard DateTime data type.
LockHeld	Whether the client holds the lock. The return value is true or false.

Example: Retrieving the list of active NETCONF sessions on the device

Task

Retrieve the list of active NETCONF sessions on the device.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Retrieve the list of active NETCONF sessions on the device. Copy and paste the following request message to the client:

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get-sessions/>

</rpc>

Verification

If the requested operation succeeds, the server responds with the list of active NETCONF sessions on the device.

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

  <get-sessions>

    <Session>

      <SessionID>1</SessionID>

      <Line>vty0</Line>

      <UserName></UserName>

      <Since>2011-01-05T00:24:57</Since>

      <LockHeld>false</LockHeld>

    </Session>

  </get-sessions>

</rpc-reply>

The response shows that the device has one NETCONF session with a session ID of 1. The NETCONF client connected to the VTY 0 user line on January 5, 2011 at 00:24:57 and it does not hold the configuration lock.

save-point

The <save-point> operation enables you to set configuration rollback points for automatic or manual configuration rollback to a rollback point.

The system rolls back the configuration based on a rollback point when one of the following events occurs:

·     The NETCONF client sends a rollback request.

·     The NETCONF client has not issued any instruction before the rollback idle timeout timer expires.

·     The NETCONF client unexpectedly disconnects from the device.

Configuration rollback procedure

IMPORTANT: In a multisession environment, lock the running configuration datastore to prevent other users from editing the configuration when you use the configuration rollback feature. This action ensures that you can roll back the configuration to the expected state.

 

1.     Lock the running configuration datastore.

2.     Send a <save-point>/<begin> request to create the initial rollback point and set the rollback idle timeout timer.

3.     Send one or multiple <edit-config> requests to configure the device before the timer expires.

4.     Send a <save-point>/<commit> request to commit the configuration. You can perform multiple commit operations, one for a set of <edit-config> operations. The system creates a rollback point for every commit operation.

5.     If the settings made after a rollback point are not desirable, send a <save-point>/<rollback> request to roll back the configuration to that rollback point. If the NETCONF client has not issued any instruction before the rollback idle timeout timer expires, the system automatically rolls back the configuration to the rollback point created for the most recent commit operation.

6.     Send the <save-point>/<end> request to end the configuration rollback.

7.     Unlock the running configuration datastore.

Enabling the configuration rollback feature and creating the initial rollback point

Request format

The following is the XML format for the <save-point>/<begin> request:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save-point>

    <begin>

      <confirm-timeout>100</confirm-timeout>

    </begin>

  </save-point>

</rpc>

The <confirm-timeout> element specifies the idle timeout timer for rollback. The value range for the timer is 1 to 65535. This element is optional. If you do not send the request with this element, the timer is set to 600 seconds by default.

Verification

If the rollback point is created successfully, the device returns a response in the following format:

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <save-point>

      <commit>

        <commit-id>1</commit-id>

      </commit>

    </save-point>

  </data>

</rpc-reply>

Rolling back the configuration to a rollback point

Request format

The following is the XML format for the <save-point>/<rollback> request:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save-point>

    <rollback>

      <commit-id/>

      <commit-index/>

      <commit-label/>

    </rollback>

  </save-point>

</rpc>

To roll back to a rollback point other than the most recent one, you must send the request with the <commit-id/>, <commit-index/>, or <commit-label/> element to specify the commit operation upon which the rollback point was created.

To roll back to the most recent rollback point, send the request with one of those elements or none of the elements.

Table 18 Elements in a configuration rollback request

Element	Description
commit-id	The identifier uniquely identifies a commit operation.
commit-index	The index of a commit operation. The system supports a maximum of 50 commit operations (or rollback points) for a NETCONF session. A value of 49 represents the stored earliest rollback points. A value of 0 represents the most recent rollback point.
commit-label	Label that identifies the commit operation.

 

Verification

If the configuration rolls back successfully, the device returns the following response:

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok></ok>

</rpc-reply>

Committing the configuration

Send the <save-point>/<commit> request to commit the changes you have made to the running configuration. The system supports a maximum of 50 commit operations (or rollback points) for a NETCONF session. If you do a commit operation after the limit is reached, include the force attribute in the <commit> element to overwrite the earliest rollback point.

Request format

The following is the XML format for the <save-point>/<rollback> request:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save-point>

    <commit>

      <label>SUPPORT VLAN<label>

      <comment>vlan 1 to 100 and interfaces. Each vlan used for different custom as follows: ……</comment>

    </commit>

  </save-point>

</rpc>

The <label/> and <comment/> elements are optional.

Verification

If the configuration is committed successfully, the device returns a response in the following format:

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <save-point>

      <commit>

        <commit-id>2</commit-id>

      </commit>

    </save-point>

  </data>

</rpc-reply>

Disabling configuration rollback

Send the <save-point>/<end> request to disable configuration rollback for the current NETCONF session.

Request format

The following is the XML format for a <save-point>/<rollback> request:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save-point>

    <end/>

  </save-point>

</rpc>

Verification

If configuration rollback is disabled successfully, the device returns the following response:

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

</rpc-reply>

Retrieving records of rollback points

The <save-point>/<get-commits> operation retrieves records of rollback points.

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save-point>

    <get-commits>

      <commit-id/>

      <commit-index/>

      <commit-label/>

    </get-commits>

  </save-point>

</rpc>

To retrieve the record of a specific rollback point, send the request with the <commit-id>, <commit-index>, or <commit-label> element to specify the commit operation upon which the rollback point was created. To retrieve the records of all rollback points, send the request without any of those elements.

Request format

The following is the XML format for the rollback point retrieval request:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save-point>

    <get-commits>

      <commit-label>SUPPORT VLAN</commit-label>

    </get-commits>

  </save-point>

</rpc>

Verification

If the retrieval operation succeeds, the device returns a response in the following format:

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <save-point>

      <commit-information>

        <CommitID>2</CommitID>

        <TimeStamp>Thu Oct 30 11:30:28 1980</TimeStamp>

        <UserName>test</UserName>

        <Label>SUPPORT VLAN</Label>

      </commit-information>

      <commit-information>

        <CommitID>1</CommitID>

        <TimeStamp>Wed Nov  8 18:26:28 1972</TimeStamp>

        <UserName>test</UserName>

      </commit-information>

    </save-point>

  </data>

</rpc-reply>

Retrieving the configuration data at a rollback point

The <save-point>/<get-commits> operation retrieves the configuration data recorded at a rollback point.

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save-point>

    <get-commit-information>

      <commit-information>

        <commit-id/>

        <commit-index/>

        <commit-label/>

      </commit-information>

      <compare-information>

        <commit-id/>

        <commit-index/>

        <commit-label/>

      </compare-information>

    </get-commit-information>

  </save-point>

</rpc>

To retrieve the configuration data recorded at a specific rollback point, specify that point by using the <commit-id/>, <commit-index/>, or <commit-label/> element. The <compare-information> element is optional. If the <commit-information> does not contain the <commit-id/>, <commit-index/>, or <commit-label/> element, the server responds the configuration data recorded at the most recent rollback point.

Request format

The following is the XML format for a request to retrieve the configuration data recorded at a rollback point:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <save-point>

    <get-commit-information>

      <commit-label>SUPPORT VLAN</commit-label>

    </get-commit-information>

  </save-point>

</rpc>

Verification

If the configuration data retrieval succeeds, the device returns a response in the following format:

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <data>

    <save-point>

      <commit-information>

        <content>

          …

          interface vlan 1

          …

        </content>

      </commit-information>

    </save-point>

  </data>

</rpc-reply>

Name-to-index conversion

About name-to-index conversion

Name-to-index conversion (h3c-name2index) capability allows you to use a name type value in place of an index-type value in index elements when you perform the <get>, <get-config>, <edit-config>, or <action> operations. For example, interface Ethernet 1/0/1 is indexed at 1. In a request to operate on that interface, you can set the <IfIndex> element to Ethernet1/0/1 instead of 1. Support for h3c-name2index capability differs by table. To identify the support of a table for name-to-index conversion, see the NETCONF API reference that contains the table.

For example, GigabitEthernet 1/0/1 is a trunk port. To permit VLANs 2 and 3 to pass through the port, use the following message:

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <edit-config>

    <target>

      <running/>

    </target>

    <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">

      <top xmlns="http://www.h3c.com/netconf/config:1.0"> xmlns:base=”http://www.h3c.com/netconf/base:1.0”

        <VLAN>

          <TrunkInterfaces>

            <Interface>

              <IfIndex>GigabitEthernet1/0/1</IfIndex>

              <PermitVlanList>2-3</PermitVlanList>

            </Interface>

          </TrunkInterfaces>

        </VLAN>

      </top>

    </config>

  </edit-config>

</rpc>

As of the h3c-name2index1.1 version, you can use the valuetype attribute in the <IfIndex> element to explicitly identify the element value as a name or index. You can retrieve the capability sets on the target device to obtain its supported h3c-name2index version. For more information about exchange of capability sets, see "Testing the connectivity between the NETCONF client and the target device."

Options for the valuetype attribute:

·     Name—The value is a name.

·     index—The value is an index.

·     auto—The system looks up the value in the name column first. If no match is found, the system looks up the value in the index column.

If you do not specify the valuetype attribute, the auto option applies.

For example, the following message contains an index of 1 in the <IfIndex> element: 

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <getoperation>

    <filter>

      <top xmlns="http://www.h3c.com/netconf/config:1.0" xmlns:base=”http://www.h3c.com/netconf/base:1.0”>

        <VLAN>

          <TrunkInterfaces>

            <Interface>

              <IfIndex base:valuetype="index">1</IfIndex>

            </Interface>

          </TrunkInterfaces>

        </VLAN>

      </top>

    </filter >

  </getoperation>

</rpc>

Constraints

·     In a <get-bulk> or <get-bulk-config> operation, you cannot specify multiple names in an index element if all of the following conditions are met:

¡     The index values are table indexes.

¡     The index element acts as the start delimiter for the retrieval operation.

·     Name-to-index conversion is not supported for match filtering.

·     One-to-many conversion is not available for the non-index columns in an <edit-config> operation.

·     Conversion syntax differs by data type. For example, the interface management module (Ifmgr) allows you to specify a range of interfaces (for example, GigabitEthernet1/0/1 to GigabitEthernet1/0/24) in the <IfIndex> element. However, you can only specify one VPN instance in one VPN element.

edit-config:incremental

The <edit-config> operation with the incremental element adds configuration data to lists in a list column without impact on the original data in the lists.

An example of list columns is the <PermitVlanList> element in the <VLAN>/<TrunkIntefaces>/<Interface> subtree. The <PermitVlanList> element specifies a list of VLANs (for example, 2,3,5-8,9,10-100) permitted to pass through on a trunk interface.

To perform an incremental data operation on a list column, you must add incremental=”true” to the element in the request for that column.

For example, the list of permitted VLANs on interface indexed at 100 contains VLAN 10. To add or delete VLANs 2 and 3 to or from that VLAN list, send the following request message to perform an incremental data operation on that list:

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <edit-config>

    <target>

      <running/>

    </target>

    <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">

      <top xmlns="http://www.h3c.com/netconf/config:1.0">

           xmlns:base=”http://www.h3c.com/netconf/base:1.0”

        <VLAN xc:operation="operXXX">

          <TrunkInterfaces>

            <Interface>

              <IfIndex>100</IfIndex>

              <PermitVlanList base:incremental=”true”>2-3</PermitVlanList>

            </Interface>

          </TrunkInterfaces>

        </VLAN>

      </top>

    </config>

  </edit-config>

</rpc>

The result of the incremental <edit-config> operation differs depending on the operation type, as shown in Table 19.

Table 19 Results of incremental VLAN operations on the VLAN list

Operation (OperXXX)	Incremental operation on the VLAN list	Remarks
create	VLANs 2 and 3 are added to the PermitVlanList column. If you retrieve values from this column, the device returns 2,3,10.	If any specified values already exist, the server replies that the values already exist. If none of them exist, the device returns a success message.
delete	Operation fails. The device returns an error message to indicate that the operation failed because VLAN 2 does not exist.	The delete operation deletes all specified values from the column if they are all contained in the column. If any one of the specified values does not exist, the delete operation fails, whether or not the incremental attribute is specified.
merge	VLANs 2 and 3 are added to the PermitVlanList column. If you retrieve values from this column, the device returns 2,3,10.	N/A
replace	You cannot use the incremental attribute with a replace operation.	N/A
remove	Operation succeeds. The VLAN list stays unchanged, because the VLAN list does not contain VLANs 2 and 3.	Use caution when you perform a remove operation. This operation removes all data in the column if you do not specify the incremental attribute.

 

cancel-subscription

The <cancel-subscription> operation unsubscribes from an event stream.

Request format

The following is the XML format for the NETCONF event unsubscription request:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <cancel-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

    <stream>XXX_STREAM</stream>

  </cancel-subscription>

</rpc>

 

Element	Description
stream	Name of the subscribed event stream.

 

Verification

If the subscription is unsubscribed, the device returns a success response in the following format:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="100">

  <ok/>

</rpc-reply>

If the subscribed event stream does not exist, the device returns the following error message:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <rpc-error>

    <error-type>protocol</error-type>

    <error-tag>operation-failed</error-tag>

    <error-severity>error</error-severity>

    <error-message xml:lang="en">The subscription stream to be canceled doesn't exist: Stream name=XXX_STREAM.</error-message>

  </rpc-error>

</rpc-reply>

createDot1qFlow

The <createDot1qFlow> operation enables Dot1q termination on a subinterface and specifies a range of outermost VLAN IDs to terminate.

In the request for this operation, use the <ifName> element to specify the target subinterface name.

Use the <vlanIdBgn> and <vlanldEnd> elements to specify the start and end VLAN IDs, respectively, in the range of outermost VLAN IDs to terminate. To terminate only one VLAN, set the ID of that VLAN in both the <vlanIdBgn> and <vlanldEnd> elements.

The <groupId> element takes a value in the range of 1 to 16. For interoperability of the target device with a third-party device, make sure the two devices use the same group ID. If there is no interoperability issue, you can set the group ID to any value in the valid value range.

Request format

The following is a sample <createDot1qFlow> request that enables subinterface GigabitEthernet 1/0/1.1 to terminate VLAN-tagged packets with the outermost VLAN IDs in the range of 1 to 100:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <createDot1qFlow xmlns="http://www.gsta.com/netconf/gsta-ethernet">

    <ifName>GigabitEthernet1/0/1.1</ifName>

    <vlanIdBgn>1</vlanIdBgn>

    <vlanIdEnd>100</vlanIdEnd>

    <groupId>1</groupId>

  </createDot1qFlow>

</rpc>

 

Element	Description
ifName	Subinterface name.
vlanIdBgn	Start VLAN ID of the VLAN range.
vlanIdEnd	End VLAN ID of the VLAN range.
groupId	Group ID.

 

Verification

If the 802.1q termination settings are configured successfully, the device returns a success response in the following format:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="100">

  <ok/>

</rpc-reply>

If the target subinterface does not exist, the device returns the following error message:

<env:Body>

      <env:Fault>

         <env:Code>

            <env:Value>env:Receiver</env:Value>

         </env:Code>

         <env:Reason>

            <env:Text xml:lang="en">invalid-value</env:Text>

         </env:Reason>

         <env:Detail>

            <rpc-error xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

               <error-type>application</error-type>

               <error-tag>invalid-value</error-tag>

               <error-severity>error</error-severity>

               <error-message xml:lang="en">Configuration target does not exist.</error-message>

            </rpc-error>

         </env:Detail>

      </env:Fault>>

deleteDot1qFlow

The <deleteDot1qFlow> operation deletes the Dot1q settings on a subinterface. This operation is supported only in the B75 version train.

In the request for this operation, use the <ifName> element to specify the target subinterface name.

Use the <vlanIdBgn> and <vlanldEnd> elements to specify the start and VLAN IDs, respectively, in the range of outermost VLAN IDs to terminate. To terminate only one VLAN, set the ID of that VLAN in both the <vlanIdBgn> and <vlanldEnd> elements.

The <groupId> element takes a value in the range of 1 to 16. For interoperability of the target device with a third-party device, make sure the two devices use the same group ID. If there is no interoperability issue, you can set the group ID to any value in the valid value range.

Request format

The following is a sample <deleteDot1qFlow> request that disables subinterface GigabitEthernet 1/0/1.1 from terminating VLAN-tagged packets with the outermost VLAN IDs in the range of 1 to 100:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <deleteDot1qFlow xmlns="http://www.gsta.com/netconf/gsta-ethernet">

    <ifName>GigabitEthernet1/0/1.1</ifName>

    <vlanIdBgn>1</vlanIdBgn>

    <vlanIdEnd>100</vlanIdEnd>

    <groupId>1</groupId>

  </deleteDot1qFlow>

</rpc>

 

Element	Description
ifName	Subinterface name.
vlanIdBgn	Start VLAN ID of the VLAN range.
vlanIdEnd	End VLAN ID of the VLAN range.
groupId	Group ID.

 

Verification

If the 802.1q termination settings are deleted successfully, the device returns a success response in the following format:

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="100">

  <ok/>

</rpc-reply>

sortByName (for data retrieval operations)

The sortByName attribute enables the device to sort returned data by name in response to a data retrieval operation.

This attribute is useful for data retrieval from multi-instance tables that meet the following conditions:

·     The tables have an index value and a name value for each instance.

·     The index and name values are in one-to-one mappings.

For example, the Interfaces table has one IfIndex value and one Name value for each interface. By default, the device sorts the interface data returned in response to an interface data retrieval request by interface index.

To have the device sort the returned interface data by interface name, set the sortByName attribute to true on the Interfaces table.

Request format

The following sample request enables the device sort returned data by name:

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:xc=”http://www.h3c.com/netconf/base:1.0”>

  <get>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0" xmlns:data="http://www.h3c.com/netconf/data:1.0">

        <Ifmgr>

          <Interfaces xc:sortByName="true">

            <Interface>

              <IfIndex></IfIndex>

              <Name></Name>

            </Interface>

          </Interfaces>

        </Ifmgr>

      </top>

    </filter>

  </get>

</rpc>

Verification

If the requested operation succeeds, the device returns the following response, with data sorted by name:

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:xc="http://www.h3c.com/netconf/base:1.0">

  <data>

    <top xmlns="http://www.h3c.com/netconf/data:1.0">

      <Ifmgr>

        <Interfaces>

          Other row instances

          <Interface>

            <IfIndex>1413</IfIndex>

            <Name>Route-Aggregation1</Name>

          </Interface>

          <Interface>

            <IfIndex>1412</IfIndex>

            <Name>Route-Aggregation10</Name>

          </Interface>

        </Interfaces>

      </Ifmgr>

    </top>

  </data>

</rpc-reply>

xml2cli

About XML-to-CLI conversion

The Comware extended xml2cli:1.0 capability enables the device to convert the XML configuration in a request into their command line forms and send back to the client.

With this capability, a client can also request conversion of configuration data in XML format into command lines by using an xml2cli RPC.

The following is the URL for the xml2cli capability:

urn:$oem:params:netconf:capability:$oem-xml2cli:1.0

The $oem parameter represents the vendor name of the device.

If the client includes the xml2cli capability in its hello message for capability exchange on a session, the device enables xml2cli capability for that session.

When the device handles requests sent over the xml2cli-capable session, the device performs the following operations:

·     When the device handles an <edit-config> or <action> request, the device perform the following operations:

¡     Executes the requested configuration operation or action.

¡     Converts the XML configuration in the request to their command line forms and returns the command lines in <rpc-reply> to the client.

·     When the device handles the xml2cli RPC from the client, the device converts the XML configuration in the <xml2cli> element to their command line forms and returns the commands to the client.

Dependencies and constraints

The client must make sure the correctness of the XML configuration and verification of returned command lines. The device is only responsible for changing correct and valid XML configuration to their command line forms. It does not guarantee the correctness of the returned command lines.

xml2cli RPC

About the xml2cli RPC

The xml2cli method enables the client to obtain the command line forms of XML configuration data.

When the device handles the xml2cli RPC from the client, the device converts the XML configuration in the <xml2cli> element to their command line forms and returns the command lines to the client.

You can use the xml2cli RPC in the auditing module for a network controller to present the configuration differences detected between the controller and the device in their command line forms.

Request format

The following is the request format for the XML2CLI RPC:

<rpc message-id="100" xmlns=" urn:ietf:params:xml:ns:netconf:base:1.0">

  <xml2cli>

    ...

    XML configuration

    ...

  </xml2cli>

</rpc>

Response format

The following is the response returned by the device:

<rpc-reply message-id="100" xmlns=" urn:ietf:params:xml:ns:netconf:base:1.0">

  <xml2cli>

    …

    <cli>

      ...

      command lines for the XML configuration

      …

    </cli>

    …

  </xml2cli>

<rpc-reply/>

If the XML-to-CLI conversion succeeds, the device returns the commands for the configuration data in the <rpc-reply> element.

If the XML-to-CLI conversion fails, the device includes the <rpc-error> element in the <rpc-reply> element to indicate the failure.

Specification limitations for the xml2cli capability

 

Item	Support status	Remarks	Example
valueType	Supported	As of the h3c-name2index1.1 version, you can use the valuetype attribute to explicitly identify an element value as a name or index. You can retrieve the capability sets on the target device to obtain its supported h3c-name2index version. Options for the valuetype attribute: ·     name—The value is a name. ·     index—The value is an index. ·     auto—The system looks up the value in the name column first. If no match is found, the system looks up the value in the index column. If you do not specify the valuetype attribute, the auto option applies.	<xml2cli xmlns=” urn:ietf:params:xml:ns:netconf:base:1.0”>   <VLAN>     <TrunkInterfaces>       <Interface>         <IfIndex valuetype="index">1</IfIndex>       </Interface>     </TrunkInterfaces>   </VLAN> </xml2cli>
Per-row command conversion	Supported	By default, the device performs XML-to-CLI conversion by row and encloses the command lines in their respective row tags. If the conversion is performed for a subtable in a table, the device encloses the command lines in the <cli> row elements in the table element. This is because the subtables of a table are row nodes of the table.	<rpc-reply message-id="100" xmlns=" urn:ietf:params:xml:ns:netconf:base:1.0">   <xml2cli>     <Ifmgr>       <Interfaces>         <Interface>  //row node           <cli>               Interface gigabitethernet2/0/1               port link-type trunk               port trunk pvid vlan 1           </cli>           <IfIndex>1647</IfIndex>           <LinkType>2</LinkType>           <PVID>1</PVID>         </Interface>       </Interfaces>     </Ifmgr>   </xml2cli> </rpc-reply>
operation	Not supported	The <xml2cli> element does not support the operation attribute that is available for the <edit-config> operation. This is because XML-to-CLI conversion is primarily in configuration auditing and does not configure the device.	N/A
<error-option>	Not supported	The xml2cli RPC does not support the <error-option> parameter. The <error-option> parameter in an <edit-config> operation does not take effect on XML-to-CLI conversion. The device always applies the continue-on-error policy to XML-to-CLI conversion.	N/A

 

Examples

·     Example: XML-to-CLI conversion for one row of data

The client sends the following request to do XML-to-CLI conversion for one row of data:

<rpc message-id="100" xmlns=" urn:ietf:params:xml:ns:netconf:base:1.0">

  <xml2cli>

    <Ifmgr>

      <Interfaces>

        <Interface>

          <IfIndex>1647</IfIndex>

          <LinkType>2</LinkType>

          <PVID>1</PVID>

        </Interface>

      </Interfaces>

    </Ifmgr>

  </xml2cli>

</rpc>

The device returns the following response:

<rpc-reply message-id="100" xmlns=" urn:ietf:params:xml:ns:netconf:base:1.0">

  <xml2cli>

    <Ifmgr>

      <Interfaces>

        <Interface>

          <cli>

              Interface gigabitethernet2/0/1

              port link-type trunk

              port trunk pvid vlan 1

          </cli>

          <IfIndex>1647</IfIndex>

          <LinkType>2</LinkType>

          <PVID>1</PVID>

        </Interface>

      </Interfaces>

    </Ifmgr>

  </xml2cli>

</rpc-reply>

·     Example: XML-to-CLI conversion for multiple rows of data

The client sends the following request to do XML-to-CLI conversion for multiple rows of data:

<rpc message-id="100" xmlns=" urn:ietf:params:xml:ns:netconf:base:1.0">

  <xml2cli>

    <Ifmgr>

      <Interfaces>

        <Interface>

          <IfIndex>1647</IfIndex>

          <LinkType>2</LinkType>

          <PVID>1</PVID>

        </Interface>

        <Interface>

          <IfIndex>1648</IfIndex>

          <LinkType>2</LinkType>

          <PVID>1</PVID>

        </Interface>

      </Interfaces>

    </Ifmgr>

  </xml2cli>

</rpc>

The device returns the following response:

<rpc-reply message-id="100" xmlns=" urn:ietf:params:xml:ns:netconf:base:1.0">

  <xml2cli>

    <Ifmgr >

      <Interfaces>

        <Interface>

          <cli>

              Interface gigabitethernet2/0/1

              port link-type trunk

              port trunk pvid vlan 1

          </cli>

          <IfIndex>1647</IfIndex>

          <LinkType>2</LinkType>

          <PVID>1</PVID>

        </Interface>

      <Interface>

          <cli>

              Interface gigabitethernet2/0/2

              port link-type trunk

              port trunk pvid vlan 1

          </cli>

          <IfIndex>1648</IfIndex>

          <LinkType>2</LinkType>

          <PVID>1</PVID>

        </Interface>

      </Interfaces>

    </Ifmgr>

  </xml2cli>

</rpc-reply>

·     Example: XML-to-CLI conversion for a multilevel table

If the conversion is performed for a subtable in a table, the device encloses the command lines in the <cli> row elements in the table element. This is because the subtables of a table are row nodes of the table.

The client sends the following request to do XML-to-CLI conversion for a multilevel table:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <xml2cli>

    <GRPC>

      <SensorGroups>

        <SensorGroup>

          <GroupName>1</GroupName>

          <SensorPaths>

            <SensorPath>

              <Path>device/base</Path>

              <SelectionNodes>

                <SelectionNode>

                  <NodeName>uptime</NodeName>

                </SelectionNode>

              </SelectionNodes>

            </SensorPath>

          </SensorPaths>

        </SensorGroup>

      </SensorGroups>

    </GRPC>

  </xml2cli>

</rpc>

The device returns the following response:

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

  <xml2cli>

    <GRPC>

      <SensorGroups>

        <SensorGroup>

          <cli>

            telemetry

              sensor group 1

                sensor path device/base selection-nodes uptime

          </cli>

          <GroupName>1</GroupName>

          <SensorPaths>

            <SensorPath>

              <Path>device/base</Path>

              <SelectionNodes>

                <SelectionNode>

                  <NodeName>uptime</NodeName>

                </SelectionNode>

              </SelectionNodes>

            </SensorPath>

          </SensorPaths>

        </SensorGroup>

      </SensorGroups>

    </GRPC>

  </xml2cli>

</rpc-reply>

xml2cli for <edit-config>

About XML-to-CLI conversion for <edit-config>

The xml2cli capability extends the <rpc-reply> response to the <edit-config> request. It adds the <xml2cli> element in the <rpc-rely> element to return the command lines for the XML configuration in the request.

 

NOTE: The device returns the conversion results, regardless of whether the <edit-config> RPC has been executed successfully or not.

 

Example: An <edit-config> operation successfully executed on an xml2cli-capable session

The client sends the following <edit-config> request over an xml2cli-capable session:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <edit-config>

    <target>

      <running/>

    </target>

    <config>

      <top xmlns="http://www.h3c.com/netconf/config:1.0" web:operation="merge">

        <Ifmgr>

          <Interfaces>

            <Interface>

              <IfIndex>1647</IfIndex>

              <LinkType>2</LinkType>

              <PVID>1</PVID>

            </Interface>

            <Interface>

              <IfIndex>1648</IfIndex>

              <LinkType>2</LinkType>

              <PVID>1</PVID>

            </Interface>

          </Interfaces>

        </Ifmgr>

      <top/>

    <config/>

  <edit-config/>

<rpc/>

Upon a successful execution of the requested operation, the device returns the following response, with the command lines for the requested XML configuration:

<rpc-reply message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <ok/>

  <xml2cli>

    <Ifmgr >

      <Interfaces>

        <Interface>

          <cli>

              Interface gigabitethernet2/0/1

              port link-type trunk

              port trunk pvid vlan 1

          </cli>

          <IfIndex>1647</IfIndex>

          <LinkType>2</LinkType>

          <PVID>1</PVID>

        </Interface>

        <Interface>

          <cli>

              Interface gigabitethernet2/0/2

              port link-type trunk

              port trunk pvid vlan 1

          </cli>

          <IfIndex>1648</IfIndex>

          <LinkType>2</LinkType>

          <PVID>1</PVID>

        </Interface>

      </Interfaces>

    </Ifmgr>

  </xml2cli>

</rpc-reply>

Example: A failed <edit-config> operation on an xml2cli-capable session

The client sends the following request:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <edit-config>

    <target>

      <running/>

    </target>

    <config>

      <top xmlns="http://www.h3c.com/netconf/config:1.0">

        <Device xc:operation="create">

          <Base>

            <HostName>xml2cli</HostName>

          </Base>

        </Device>

      <top/>

    <config/>

  <edit-config/>

<rpc/>

Upon a failed execution of the requested operation, the device returns the following response, with the command lines for the requested XML configuration:

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="100">

  <rpc-error>

    <error-type>application</error-type>

    <error-tag>invalid-value</error-tag>

    <error-severity>error</error-severity>

    <error-path>/rpc/edit-config[1]/config[1]/Device[1]/Base[1]</error-path>

    <error-message xml:lang="en">When the create, merge, or replace operation is issued, empty data cannot be assigned to columns.</error-message>

  </rpc-error>

  <xml2cli>

    <Device >

      <Base>

        <CLI>

           hostname xml2cli

        </CLI>

        <HostName>xml2cli</HostName>

      </Base>

    </Device>

  </xml2cli>

</rpc-reply> 

xml2cli for <action>

About XML-to-CLI conversion for <action>

The xml2cli capability extends the <rpc-reply> response to the <action> request. It adds the <xml2cli> element in the <rpc-rely> element to return the command lines for the XML configuration in the request.

 

NOTE: The device returns the conversion results, regardless of whether the <action> RPC has been executed successfully or not.

 

Example: An <action> operation successfully executed on an xml2cli-capable session

The client sends the following request over an xml2cli-capable session:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <action>

    <top xmlns="http://www.h3c.com/netconf/action:1.0">

      <VLAN>

        <BatchVlans>

          <CreateVlanList>5-15</CreateVlanList>

          <DestroyVlanList>5-9</DestroyVlanList>

        </BatchVlans>

      </VLAN>

    </top>

  </action>

</rpc>

Upon a successful execution of the requested operation, the device returns the following response, with the command lines for the requested XML configuration:

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <action-result xmlns="http://www.h3c.com/netconf/action:1.0">

    <request-path>/Envelope/Body[1]/rpc[1]/action[1]/top[1]/VLAN[1]/BatchVlans[1]</request-path>

    <result-data>

      ...

    </result-data>

  </action-result>

  <xml2cli>

    <VLAN>

      <BatchVlans>

        <cli>

          vlan 1 to 15

          undo vlan 5 to 10

        </cli>

        <CreateVlanList>1-15</CreateVlanList>

        <DestroyVlanList>5-10</DestroyVlanList>

      </BatchVlans>

    </VLAN>

  </xml2cli>

</rpc-reply>

Example: A failed <action> operation on an xml2cli-capable session

The client sends the following request:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <action>

    <top xmlns="http://www.h3c.com/netconf/action:1.0">

      <VLAN>

        <BatchVlans>

          <CreateVlanList>5-15</CreateVlanList>

          <DestroyVlanList>5-9</DestroyVlanList>

        </BatchVlans>

      </VLAN>

    </top>

  </action>

</rpc>

The following is the sample response returned by the device:

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

  <rpc-error>

    <error-type>rpc</error-type>

    <error-tag>unknown-element</error-tag>

    <error-severity>error</error-severity>

    <error-message xml:lang="en">Unexpected element 'http://www.h3c.com/netconf/action:1.0':'BatchVlan'(index:0) under element '/rpc/action[1]/top[1]/VLAN[1]</error-message>

    <error-info>

      <bad-element>BatchVlan</bad-element>

    </error-info>

  </rpc-error>

  <xml2cli>

    <VLAN>

      <BatchVlans>

        <cli>

          vlan 1 to 15

          undo vlan 5 to 10

        </cli>

        <CreateVlanList>1-15</CreateVlanList>

        <DestroyVlanList>5-10</DestroyVlanList>

      </BatchVlans>

    </VLAN>

  </xml2cli>

</rpc-reply>

Summary of NETCONF data operations

Table 20 lists all NETCONF operations available with Comware at the time of this writing. These operations include <get>, <get-config>, <get-bulk>, <get-bulk-config>, <edit-config>, and <action>.

Table 20 Summary of NETCONF operations available with Comware

Operation	Description	Sample request in XML format
get	Retrieves configuration and state data.	Retrieve all Syslog configuration and state data: <rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:xc="http://www.h3c.com/netconf/base:1.0">   <get>     <filter type="subtree">       <top xmlns="http://www.h3c.com/netconf/data:1.0" >         <Syslog>         </Syslog>       </top>     </filter>   </get> </rpc>
get-config	Retrieves configuration data. This operation retrieves only non-default configuration data. If no non-default configuration data exists, the device returns a response without a value for the <data> element.	Retrieve all non-default configuration data from the Interfaces table: <rpc message-id ="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:xc="http://www.h3c.com/netconf/base:1.0">   <get-config>     <source>       <running/>     </source>     <filter type="subtree">       <top xmlns="http://www.h3c.com/netconf/config:1.0">         <Ifmgr>            <Interfaces>               <Interface/>             </Interfaces>         </Ifmgr>       </top>     </filter>   </get-config> </rpc>
get-bulk	Retrieves a specific number of data entries starting from the data entry next to the one with the specified index, including the configuration and state data. Use the <Index> element to specify an index and use the count attribute to specify the number of entries to retrieve. If you do not specify an index, the retrieval starts from the first data entry. This operation retrieves all remaining data entries starting from the data entry next to the one with the specified index if either of the following conditions occurs: ·     You do not specify the count attribute. ·     The number of matching data entries is less than the value in the count attribute. The <get> operation retrieves all configuration and state data that matches the specified filter in one request. In some situations, the <get-bulk> operation is a better choice than the <get> operation. For example, when you retrieve massive data, you can use the <get-bulk> operation to retrieve data in multiple requests to improve data retrieval performance.	Retrieve all interface data: <rpc message-id ="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <get-bulk>     <filter type="subtree">       <top xmlns="http://www.h3c.com/netconf/data:1.0">         <Ifmgr>           <Interfaces xc:count=”5” xmlns:xc=” http://www.h3c.com/netconf/base:1.0”>             <Interface/>           </Interfaces>         </Ifmgr>       </top>     </filter>   </get-bulk> </rpc>
get-bulk-config	Retrieves a specific number of configuration data entries, starting from the data entry next to the one with the specified index. The <get-bulk> operation constraints also apply to this operation.	Retrieve all interface configuration data: <rpc message-id ="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" >   <get-bulk-config>     <source>       <running/>     </source>     <filter type="subtree">       <top xmlns="http://www.h3c.com/netconf/config:1.0">         <Ifmgr>         </Ifmgr>       </top>     </filter>   </get-bulk-config> </rpc>
edit-config: merge	Merges target configuration data to the running configuration. In a merge request, you must specify the target (or the row) on which the merge operation to be performed. ·     If the target already exists, the merge operation updates the setting for it. ·     If the target does not exist, but it can be created, the merge operation creates and then configures the target. ·     If the target does not exist and it cannot be created, the device returns a merge failure message.	Set the size of the log buffer to 120: <rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"  xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">   <edit-config>     <target>       <running/>     </target>     <config>       <top xmlns="http://www.h3c.com/netconf/config:1.0">         <Syslog xmlns="http://www.h3c.com/netconf/config:1.0" xc:operation="merge">            <LogBuffer>              <BufferSize>120</BufferSize>           </LogBuffer>         </Syslog>       </top>     </config>   </edit-config> </rpc>
edit-config: create	Creates the specified target. In the <edit-config> request for a create operation, you must specify the target to create. The <edit-config> request for a create operation uses the same XML data format as the <edit-config> request for a merge operation, except that you must change the operation attribute value to create in the request. ·     If the target can be created, the device creates and then configures the target as requested. ·     If the specified target already exists, the device returns a data-exist error message.	See the XML format for the merge operation. Change the operation attribute value to create in the request.
edit-config: replace	·     Replaces the specified target. If the specified target already exists, the operation replaces the configuration for the target with the configuration specified in the request. ·     If the target does not exist, but it can be created, the replace operation creates and then configures the target as requested. ·     If the specified target does not exist and cannot be created, the device does not perform the replace operation and it returns an invalid-value error message.	See the XML format for the merge operation. Change the operation attribute value to replace in the request.
edit-config: remove	Deletes the specified configuration target. ·     To delete a table and all configuration data in it, specify only the table index in the <target> element. ·     To delete the configuration for a parameter from a table, specify the index of the table and the configuration to delete in the <target> element. ·     If the specified target does not exist or if the request contains an empty <target> element, the device returns a success message.	See the XML format for the merge operation. Change the operation attribute value to remove in the request.
edit-config: delete	Deletes the specified configuration target. ·     To delete a table and all configuration data in it, specify only the table index in the <target> element. ·     To delete the configuration for a parameter from a table, specify the index of the table and the configuration to delete in the <target> element. ·     If the specified target does not exist, the device returns an error message.	See the XML format for the merge operation. Change the operation attribute value to delete in the request.
edit-config: default-operation	Modifies the running configuration of the device by using the default operation method. NETCONF uses one of the following operation attributes to modify configuration: merge, create, delete, and replace. If you do not specify an operation attribute in an <edit-config> request, NETCONF uses the specified default operation method. The value specified for the <default-operation> element takes effect only once. If you do not specify an operation attribute or the default operation method for an <edit-config> message, merge always applies. The following are values available for the <default-operation> element: ·     merge—Requests the server to perform a merge operation if the request does not contain an operation attribute.  If an <edit-config> request does not contain an operation attribute or a default operation, the merge operation applies. ·     replace—Requests the server to perform a replace operation if the request does not contain an operation attribute. ·     none—Requests the server to verify the request for schema syntax errors if the request does not contain an operation attribute. This option does not change configuration data. If schema verification is passed, the device returns a success message. If schema verification fails, the device returns an error message.	Verify the request for schema syntax errors: <rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <edit-config>     <target>       <running/>     </target>     <default-operation>none</default-operation>     <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">       <top xmlns="http://www.h3c.com/netconf/config:1.0">         <Ifmgr>           <Interfaces>             <Interface>               <IfIndex>262</IfIndex>               <Description>222222</Description>             </Interface>           </Interfaces>         </Ifmgr>       </top>     </config>   </edit-config> </rpc>
edit-config: error-option	Specifies the action to take on a configuration error. By default, the device returns an error message if a request fails. To take a different action, include the <error-option> parameter in an <edit-config> request. The following are values available for the <error-option> element: ·     stop-on-error—Stops the operation on error and returns an error message. This is the default error-option value. ·     continue-on-error—Continues the operation on error and returns an error message. ·     rollback-on-error—Rolls back the configuration.	Configure two interfaces and take the continue-on-error action when an error occurs: <rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <edit-config>     <target>       <running/>     </target>   <error-option>continue-on-error</error-option>     <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">       <top xmlns="http://www.h3c.com/netconf/config:1.0">         <Ifmgr xc:operation="merge">           <Interfaces>             <Interface>               <IfIndex>262</IfIndex>               <Description>222</Description>                 <ConfigSpeed>1000000</ConfigSpeed>                 <ConfigDuplex>1</ConfigDuplex>             </Interface>             <Interface>               <IfIndex>263</IfIndex>               <Description>333</Description>                 <ConfigSpeed>1000000</ConfigSpeed>                 <ConfigDuplex>1</ConfigDuplex>             </Interface>           </Interfaces>         </Ifmgr>       </top>     </config>   </edit-config> </rpc>
edit-config: test-option	Determines whether to issue a configuration item in the <edit-config> operation. The <test-option> element has one of the following values: ·     test-then-set—Performs a validation test before setting the configuration on the system. If the validation test fails, the <edit-config> operation is not performed. This is the default test-option value. ·     set—Performs the set operation without validation. ·     test-only—Performs validation without the set operation. If syntax verification is passed, the device returns a success message. If syntax verification fails, the device returns an error message.	Test the configuration for an interface: <rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <edit-config>     <target>       <running/>     </target>      <test-option>test-only</test-option>     <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">       <top xmlns="http://www.h3c.com/netconf/config:1.0">         <Ifmgr xc:operation="merge">           <Interfaces>             <Interface>               <IfIndex>262</IfIndex>               <Description>222</Description>                 <ConfigSpeed>1000000</ConfigSpeed>                 <ConfigDuplex>1</ConfigDuplex>                </Interface>           </Interfaces>         </Ifmgr>       </top>     </config>   </edit-config> </rpc>
action	Performs non-configuration actions, for example, the reset action.	Clear all interface statistics data: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">   <action>     <top xmlns="http://www.h3c.com/netconf/action:1.0">       <Ifmgr>             <ClearAllIfStatistics>                 <Clear>                 </Clear>         </ClearAllIfStatistics>       </Ifmgr>     </top>   </action> </rpc>

 

About responses to data retrieval requests

The following information describes the responses to data retrieval requests, including <get>, <get-bulk>, <get-config>, and <get-bulk-config> requests.

Returning data in tables, rows, or columns

General XML formats for data retrieval requests

The following is the general XML format for <get-> and <get-bulk> requests:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <getoperation>

    <filter>

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        XML structure (module, submodule, table, and columns)

      </top>

    </filter>

  </getoperation>

</rpc>

The following is the general XML format for <get-config> and <get-bulk-config> requests:

<?xml version="1.0" encoding="UTF-8" ?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <getoperation>

    <source>

      <running/>

    </source>

    <filter>

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        XML structure (module, submodule, table, and columns)

      </top>

    </filter>

  </getoperation>

</rpc>

Replace the getoperation argument with get, get-bulk, get-config, or get-bulk-config.

Use the <filter> element to identify data of interest.

Usage of the <filter> element

The <filter> element can filter data by module, submodule, table, or column. Depending on the filter you use, the device returns data in tables, rows, or columns.

Retrieving data in tables

·     To retrieve data from all modules (submodules), do not specify any modules (or submodules) in the <filter> element. To retrieve data from only one module (submodule), specify that module (or submodule) in the <filter> element.

·     To retrieve data from all tables for the specified module, do not specify a table. To retrieve data from only one table for a module, specify that table.

Retrieving data in rows

·     To retrieve data from all rows of a table, do not specify any column names in that table.

·     To retrieve data in a row for all columns in a table, specify the row-specific index value in the index column for that table. If the table has multiple index columns, specify all of them in the request.

·     To retrieve data in a row for some of the columns in a table, specify the row-specific index column for that table and the columns of interest. If the table has multiple index columns, specify all of them in the request.

Retrieving data in columns

·     To retrieve data in a row for all columns in a table, specify the row-specific index value in the index column for that table. If the table has multiple index columns, specify all of them in the request.

·     To retrieve data in a row for some of the columns in a table, specify the row-specific index column for that table and the columns of interest. If the table has multiple index columns, specify all of them in the request.

If a retrieval request does not specify all index columns in a multi-index table, the device returns data in all rows for all index columns.

If a <get-bulk> request specifies an incomplete set of discrete index column nodes for data retrieval from a multi-index table, the device processes the request as follows:

·     Uses the leading consecutive index column nodes as the start delimiters for the retrieval operation. The device retrieves data entries starting from the one next to the entry identified by the start delimiters.

·     Uses the remaining index column nodes as filtering criteria to identify data entries to retrieve.

For example, a multi-instance table has five index columns (A, B, C, D, and E). If the <get-bulk> request specifies all the index columns except column C, the device uses A and B as the start delimiters and uses D and E as filtering criteria to identify data of interest:

·     Searches the table starting from the entry next to the one identified by A and B.

·     Returns values in each index column that are in the same row as the values specified for columns D and E.

If a <get> request contains an incomplete set of indexes, the server uses all index columns as filtering criteria. The returned values in each index column will be those in rows that contain all the specified index column values.

Returning empty data to a data retrieval request

The device returns empty data to a data retrieval request in the following situations:

·     The target modules have not started.

·     The client has no access to the requested targets.

·     The filter excludes all data.

·     Non-format constraints are violated.

·     The target tables in configuration retrieval requests contain only default settings.

·     The target tables are not supported on the target device.

Impact of RBAC on data retrieval results

If the NETCONF client does not have read access to a table, the device does not return data in that table.

If the NETCONF client does not have read access to a column, do not include that column in the request. The device can return data from read-accessible columns if the request does not contain read-inaccessible column nodes. If the request contains an explicitly specified read-inaccessible column node, the device will not return data from the target table.

If the NETCONF client does not have read access to the object instance at the specified index, the device does not return the object instance when it performs a <get> or <get-config> operation. The device skips the row when it performs a <get-bulk> or <get-bulk-config> operation.

Impact of module-specific filters on data retrieval

Some modules provide module-specific filtering criteria for you to do more complicated filtering than with standard filtering criteria. You can set a filter as an attribute in row name elements for data retrieval from a multi-instance table or in the table name element for data retrieval from a single-instance table.

The following sample request includes a filter attribute in the row name element to retrieve data from the Ipv4Routes table of the Route module.

  <Route>

    <Ipv4Routes>

      <RouteEntry h3c:filter=' ip 1.1.1.1' xmlns:h3c='http://www.h3c.com/netconf/base:1.0' >

      </RouteEntry>

    </Ipv4Routes>

  </Route>

The device returns data that matches the criteria defined by all filters, including module-specific filters and standard filters.

For information about the availability of module-specific self-defined filters, see the NETCONF XML API references for that module.

Comware NETCONF data filtering

Data filtering methods

To retrieve only data of interest, use a filter when you perform a data retrieval operation (<get>, <get-bulk>, <get-config>, or <get-bulk-config>). You can filter data by doing an exact match, regular expression match, or conditional match.

If multiple types of filters apply to an element, only one of them takes effect. The device selects the filter to apply in order of exact match, regular expression match, and conditional match.

Exact match

When you define a filter in a request, specify an element value or an attribute for exact match. If both types of filtering criteria are present, the device preferentially uses the element value for exact match.

If multiple elements are set, the device returns data that match all of them. The device responds a success message only if it has found data that fully matches all the specified criteria.

The following is a sample request that retrieves the configuration and state data from all interfaces in up state. The request includes the <AdminStatus> element in the subtree filter and sets the element to 2.

<rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        <Ifmgr>

          <Interfaces>

            <Interface>

              <AdminStatus>2</AdminStatus>

            </Interface>

          </Interfaces>

        </Ifmgr>

      </top>

    </filter>

  </get>

</rpc>

Alternatively, you can include the AdminStatus="2" attribute name-value pair in the <Interface> row name element tag for the same purpose, as shown below:

<rpc message-id ="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <get>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0" xmlns:data="http://www.h3c.com/netconf/data:1.0">

        <Ifmgr>

          <Interfaces>

            <Interface data:AdminStatus="2" />

          </Interfaces>

        </Ifmgr>

      </top>

    </filter>

  </get>

</rpc>

Regular expression match

About regular expressions

To do more sophisticated filtering on an element than with exact match, set a regExp attribute in the element tag. You can use regular expressions to match various types of data, including integers, date and time values, strings, IPv4 addresses, IPv4 masks, IPv6 addresses, MAC addresses, OIDs, and time zones.

 

NOTE: Comware depends on libraries such as ucLibC and gLibC to handle regular expressions. Differences might exist between libraries. As a best practice to ensure successful regular expression parsing, avoid using overcomplicated regular expressions.

 

For example, the following request uses a regular expression to retrieve interface descriptions that contain only letters in uppercase:

<rpc message-id="1-0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:h3c="http://www.h3c.com/netconf/base:1.0" >

  <get-config>

    <source>

      <running/>

    </source>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/config:1.0">

        <Ifmgr>

          <Interfaces>

            <Interface>

              <Description h3c:regExp="^[A-Z]*$" />

            </Interface>

          </Interfaces>

        </Ifmgr>

      </top>

    </filter>

  </get-config>

</rpc>

Table 21 shows the metacharacters that you can use to build a regular expression.

Table 21 Commonly used metacharacters for regular expressions

Metacharacter	Description	Examples
^	Matches lines that begin with the character next to the caret sign (^).	The ^u pattern matches all lines that begin with the u character. The pattern does not match lines that begin with Au.
$	Matches lines that end with the character that precedes the dollar ($) sign.	The u$ pattern matches all lines that end with the u character. The pattern does not match lines that end with uA.
.	Matches any single character.	The .s matches as and bs.
*	Matches zero or more occurrences of the character that precedes the asterisk (*) sign.	·     The zo* pattern matches z and zoo. ·     The (zo)* pattern matches zo and zozo.
+	Matches one or more occurrences of the character or character string that precedes the plus (+) sign.	The zo+ pattern matches zo and zoo, but not z.
|	Matches the string on either side of the vertical bar (|).	The def|int pattern matches lines that contain def or int.
( )	Matches the string in the parentheses, typically used together with the plus sign (+) or asterisk sign (*).	The (123A) pattern matches 123A. The 408(12)+ pattern matches 40812 and 408121212, but not 408.
\index	Matches the preceding strings and then the repetition of a particular string. You must enclose the preceding strings each in a pair of parentheses. The strings are each indexed with a number starting from 1, from left to right. To match one repetition of a string at a particular index, specify the index number for that string.	For example, the (string)\1 pattern matches stringstring. The (string1)(string2)\2 matches string1string2string2. The (string1)(string2)\1\2 pattern matches string1string2string1string2.
[ ]	Matches any characters or characters in a hyphenated range in the brackets.	·     The [16A] pattern matches strings that contain 1, 6, or A. ·     The [1-36A] pattern matches strings that contain 1, 2, 3, 6, or A. The hyphen (-) represents a range. To match the right bracket character (]), put it immediately after the [ metacharacter, in the []string] format. This constraint does not apply to the left bracket character ([).
[^]	Matches a string that contains characters not in the brackets. A matching string can contain characters in the brackets, as long as it contains a minimum of one character not in the brackets.	The [^16A] pattern matches strings that contain one or more characters except for 1, 6, or A. For example, the [^16A] pattern matches abc, m16, but not 1, 16, or 16A.
{n}	Matches the preceding character n times. The n argument represents a non-negative integer.	The o{2} pattern matches food, but not Bob.
{n,}	Matches the preceding character a minimum of n times. The n argument represents a non-negative integer.	The o{2,} pattern matches foooood, but not Bob.
{n,m}	Matches the preceding character n to m times or more. The n and m arguments represent non-negative integers and the value for n must be equal to or less than the value for m.	The o{1,3} pattern matches fod, food, and foooood, but not fd.
\<	Matches strings that start with the pattern following \<. A string that contains the pattern is also a match if the characters that precede the pattern are not digits, letters, or underscores.	The \<do pattern matches domain and doa.
\>	Matches strings that end with the pattern preceding \>. A string that contains the pattern is also a match if the characters that follow the pattern are not digits, letters, or underscores.	The do\> pattern matches undo and cdo.
\b	Matches words that start with the pattern following \b or end with the pattern preceding \b.	The er\b pattern matches never, but not verb. The \ber pattern matches erase, but not verb.
\B	Matches a word that contains the pattern preceding \B but does not start or end with the pattern.	The er\B pattern matches verb, but not never.
\w	Matches a character that is a digit, letter, or underscore. It is identical to [A-Za-z0-9_].	The v\w pattern matches vlan and services.
\W	Matches a character that is not a digit, letter, or underscore. It is identical to [^A-Za-z0-9_].	The \Wa pattern matches -a, but not 2a or ba.
\	Escapes the character that follows the back slash(\). To have the device treat a special character listed in this table as a literal character, precede that character with a back slash.	·     The \\ pattern matches strings that contain \. ·      The \^ pattern matches strings that contain ^. ·     The \\b pattern matches strings that contains \b.

 

Example: Using a regular expression to filter data

Task

Retrieve all data entries that contain a colon (:) in the Description column of the Interfaces table in the Ifmgr module.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Retrieve all data entries that contain a colon (:) in the Description column of the Interfaces table in the Ifmgr module. Copy and paste the following request message to the client:

<?xml version="1.0"?>

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:reg="http://www.h3c.com/netconf/base:1.0">

  <get>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        <Ifmgr>

          <Interfaces>

            <Interface>

              <Description  reg:regExp=":" />

            </Interface>

          </Interfaces>

        </Ifmgr>

      </top>

    </filter>

  </get>

</rpc>

Verification

If the requested operation succeeds, the server responds with the list of interface data entries that contain a colon in their interface descriptions.

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:reg="http://www.h3c.com/netconf/base:1.0" message-id="100">

  <data>

    <top xmlns="http://www.h3c.com/netconf/data:1.0">

      <Ifmgr>

        <Interfaces>

          <Interface>

            <IfIndex>2681</IfIndex>

            <Description>Ten-GigabitEthernet1/0/49:1 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2682</IfIndex>

            <Description>Ten-GigabitEthernet1/0/49:2 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2683</IfIndex>

            <Description>Ten-GigabitEthernet1/0/49:3 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2684</IfIndex>

            <Description>Ten-GigabitEthernet1/0/49:4 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2685</IfIndex>

            <Description>Ten-GigabitEthernet1/0/50:1 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2686</IfIndex>

            <Description>Ten-GigabitEthernet1/0/50:2 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2687</IfIndex>

            <Description>Ten-GigabitEthernet1/0/50:3 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2688</IfIndex>

            <Description>Ten-GigabitEthernet1/0/50:4 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2689</IfIndex>

            <Description>Ten-GigabitEthernet1/0/51:1 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2690</IfIndex>

            <Description>Ten-GigabitEthernet1/0/51:2 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2691</IfIndex>

            <Description>Ten-GigabitEthernet1/0/51:3 Interface</Description>

          </Interface>

          <Interface>

            <IfIndex>2692</IfIndex>

            <Description>Ten-GigabitEthernet1/0/51:4 Interface</Description>

          </Interface>

        </Interfaces>

      </Ifmgr>

    </top>

  </data>

</rpc-reply>

Conditional match

About conditional match

Regular expressions are intended for character string matching. To filter data based on logical operations on numbers, use conditional match.

To do a conditional match on an element, add the match attribute in the element tag, and set the value for the attribute to be a filtering condition that operates on numbers or strings.

Table 22 Conditional match commands

Operator	Command	Description
Greater than	match=”more:value”	Matches values higher than the specified value. The specified value can be one of the following data types: ·     Any number type. ·     Any date and time type. ·     Any string type. ·     IPv4 address, IPv4 mask, IPv6 address, or MAC address. ·     Time zone.
Less than	match=”less:value”	Matches values lower than the specified value. The specified value can be one of the following data types: ·     Any number type. ·     Any date and time type. ·     Any string type. ·     IPv4 address, IPv4 mask, IPv6 address, or MAC address. ·     Time zone.
Not less than	match=”notLess:value”	Matches values equal to or higher than the specified value. The specified value can be one of the following data types: ·     Any number type. ·     Any date and time type. ·     Any string type. ·     IPv4 address, IPv4 mask, IPv6 address, or MAC address. ·     Time zone.
Not greater than	match=”notMore:value”	Matches values equal to or less than the specified value.  Matches values equal to or higher than the specified value. The specified value can be one of the following data types: ·     Any number type. ·     Any date and time type. ·     Any string type. ·     IPv4 address, IPv4 mask, IPv6 address, or MAC address. ·     Time zone.
Equal to	match=”equal:value”	Matches values equal to the specified value, which can be any data type.
Not equal to	match=”notEqual:value”	Matches values not equal to the specified value, which can be any data type.
Include	match=”include:string”	Includes the specified string. The specified string can be any one of the following data types: ·     Any string type. ·     IPv4 address or IPv4 mask.
Exclude	match=”exclude:string”	Excludes the specified string. The specified string can be any one of the following data types: ·     Any string type. ·     IPv4 address or IPv4 mask.
Begin with	match=”startWith:string”	Starts with the specified string. The specified string can be any one of the following data types: ·     Any string type. ·     OID. ·     IPv4 address or IPv4 mask.
End with	match=”endWith:string”	Ends with the specified string. The specified string can be any one of the following data types: ·     Any string type. ·     IPv4 address or IPv4 mask.

 

For example, send the following NETCONF message to retrieve extension information about entities whose CPU usage is higher than 50%.

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:h3c="http://www.h3c.com/netconf/base:1.0" >

  <get>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        <Device>

          <ExtPhysicalEntities>

            <Entity>

              <CpuUsage h3c:match="more:50"></CpuUsage>

            </Entity>

          </ExtPhysicalEntities>

        </Device>

      </top>

    </filter>

  </get>

</rpc>

Example: Performing conditional match to filter data

Task

Retrieve names of the interfaces that have an interface index equal to or higher than 5000.

Procedure

# Enter XML view.

<Sysname> xml

# Exchange capability sets. Copy and paste the following request message to the client:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

  <capabilities>

    <capability>

      urn:ietf:params:netconf:base:1.0

    </capability>

  </capabilities>

</hello>

# Retrieve interface names of the interfaces with an interface index equal to or higher than 5000 from the Name column of the Interfaces table in the Ifmgr module. Copy and paste the following request message to the client:

<rpc message-id="100" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nc="http://www.h3c.com/netconf/base:1.0">

  <get>

    <filter type="subtree">

      <top xmlns="http://www.h3c.com/netconf/data:1.0">

        <Ifmgr>

          <Interfaces>

            <Interface>

              <IfIndex nc:match="more:5000"/>

              <Name/>

            </Interface>

          </Interfaces>

        </Ifmgr>

      </top>

    </filter>

  </get>

</rpc>

Verification

If the requested operation succeeds, the server responds with interface names of the interfaces with an interface index of 5000 or higher.

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nc="http://www.h3c.com/netconf/base:1.0" message-id="100">

  <data>

    <top xmlns="http://www.h3c.com/netconf/data:1.0">

      <Ifmgr>

        <Interfaces>

          <Interface>

            <IfIndex>7241</IfIndex>

            <Name>NULL0</Name>

          </Interface>

          <Interface>

            <IfIndex>7243</IfIndex>

            <Name>Register-Tunnel0</Name>

          </Interface>

        </Interfaces>

      </Ifmgr>

    </top>

  </data>

</rpc-reply>

Filtering instances of a column

Some columns allow you to specify multiple instances of them in one row element for data retrieval. If you apply a filter to such a column, the device returns only matching instances. If no matches are found, the device does not return the row.

Filtering instances of a group (data structure)

For the ease of management, Comware groups columns for the same purpose in data structures. Some of the groups allow you to specify multiple instances of them in one row element for data retrieval. If you apply a filter to such a group, the device returns an instance of the group only if all group members in the instance match the filtering criteria. If no matches are found, the device does not return the row.