H3C 交换机NETCONF API二次开发指南

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

前  言

本文档主用来指导用户使用NETCONF客户端配置和管理设备。

前言部分包含如下内容：

·     读者对象

·     本书约定

·     资料意见反馈

读者对象

本手册主要适用于如下工程师：

·     具有一定XML和NETCONF技术基础的网络规划人员

·     负责网络配置和维护，且具有一定XML和NETCONF技术基础的网络管理员

本书约定

1. 命令行格式约定

格    式	意    义
粗体	命令行关键字（命令中保持不变、必须照输的部分）采用加粗字体表示。
斜体	命令行参数（命令中必须由实际值进行替代的部分）采用斜体表示。
[ ]	表示用“[ ]”括起来的部分在命令配置时是可选的。
{ x | y | ... }	表示从多个选项中仅选取一个。
[ x | y | ... ]	表示从多个选项中选取一个或者不选。
{ x | y | ... } *	表示从多个选项中至少选取一个。
[ x | y | ... ] *	表示从多个选项中选取一个、多个或者不选。
&<1-n>	表示符号&前面的参数可以重复输入1～n次。
#	由“#”号开始的行表示为注释行。

 

2. 各类标志

本书还采用各种醒目标志来表示在操作过程中应该特别注意的地方，这些标志的意义如下：

	该标志后的注释需给予格外关注，不当的操作可能会对人身造成伤害。
	提醒操作中应注意的事项，不当的操作可能会导致数据丢失或者设备损坏。
	为确保设备配置成功或者正常工作而需要特别关注的操作或信息。
	对操作内容的描述进行必要的补充和说明。
	配置、操作、或使用设备的技巧、小窍门。

 

3. 图标约定

本书使用的图标及其含义如下：

	该图标及其相关描述文字代表一般网络设备，如路由器、交换机、防火墙等。
	该图标及其相关描述文字代表一般意义下的路由器，以及其他运行了路由协议的设备。
	该图标及其相关描述文字代表二、三层以太网交换机，以及运行了二层协议的设备。
	该图标及其相关描述文字代表无线控制器、无线控制器业务板和有线无线一体化交换机的无线控制引擎设备。
	该图标及其相关描述文字代表无线接入点设备。
	该图标及其相关描述文字代表无线终结单元。
	该图标及其相关描述文字代表无线终结者。
	该图标及其相关描述文字代表无线Mesh设备。
	该图标代表发散的无线射频信号。
	该图标代表点到点的无线射频信号。
	该图标及其相关描述文字代表防火墙、UTM、多业务安全网关、负载均衡等安全设备。
	该图标及其相关描述文字代表防火墙插卡、负载均衡插卡、NetStream插卡、SSL VPN插卡、IPS插卡、ACG插卡等安全插卡。

 

4. 示例约定

由于设备型号不同、配置不同、版本升级等原因，可能造成本手册中的内容与用户使用的设备显示信息不一致。实际使用中请以设备显示的内容为准。

本手册中出现的端口编号仅作示例，并不代表设备上实际具有此编号的端口，实际使用中请以设备上存在的端口编号为准。

资料意见反馈

如果您在使用过程中发现产品资料的任何问题，可以通过以下方式反馈：

E-mail：[email protected]

感谢您的反馈，让我们做得更好！

 

目  录

1 NETCONF协议介绍··· 1-1

1.1 NETCONF协议结构·· 1-1

1.2 NETCONF基本网络架构·· 1-2

1.3 NETCONF报文格式·· 1-2

1.3.1 NETCONF· 1-2

1.3.2 NETCONF over SOAP· 1-4

1.3.3 NETCONF报文的其他格式要求·· 1-6

1.4 Comware NETCONF遵循的协议·· 1-6

1.5 Comware NETCONF支持的能力集·· 1-7

1.6 Comware支持的协议操作·· 1-8

2 使用NETCONF配置和管理设备··· 2-1

2.1 使用NETCONF配置和管理设备的通用流程·· 2-1

2.2 选择NETCONF客户端并确定客户端对设备的访问方式·· 2-2

2.2.1 NETCONF配置方式简介·· 2-2

2.2.2 访问方式介绍·· 2-2

2.3 在设备上为NETCONF用户设置权限·· 2-3

2.3.1 确定NETCONF用户需要的权限·· 2-3

2.3.2 定义NETCONF用户角色规则·· 2-4

2.3.3 配置NETCONF用户·· 2-5

2.4 在设备上进行访问方式相关配置·· 2-6

2.4.1 配置NETCONF over SSH访问方式·· 2-6

2.4.2 配置NETCONF over SOAP over HTTP（或HTTPS）访问方式·· 2-7

2.5 准备NETCONF请求使用的XML消息·· 2-8

2.5.1 NETCONF API文档介绍·· 2-8

2.5.2 使用NETCONF API文档构造NETCONF请求报文·· 2-9

2.5.3 使用XSD文件构造NETCONF请求·· 2-10

2.5.4 使用YANG文件构造NETCONF请求·· 2-11

2.6 使用NETCONF客户端连接到设备·· 2-11

2.6.1 选择合适的NETCONF访问方式·· 2-11

2.6.2 客户端使用SOAP方式连接到设备·· 2-11

2.6.3 客户端使用NETCONF over SSH访问方式连接到设备·· 2-15

2.6.4 客户端使用Telnet/SSH/Console以命令行方式连接到设备·· 2-15

2.6.5 确认连接成功·· 2-15

2.7 测试NETCONF客户端和设备的连通性·· 2-16

2.7.1 交换能力集·· 2-16

2.7.2 断开NETCONF连接·· 2-16

2.8 验证准备的NETCONF请求XML报文的正确性·· 2-17

2.9 将请求集成到客户端脚本或程序·· 2-18

2.10 最佳实践建议·· 2-18

2.10.1 容错处理·· 2-18

2.10.2 大数据量处理·· 2-18

2.10.3 并发处理·· 2-18

2.10.4 及时关闭连接·· 2-19

2.10.5 事件通知·· 2-19

2.10.6 HTTP和HTTPS混用·· 2-19

2.11 常见问题及处理方法·· 2-19

2.11.1 命令行上XML请求没有反应·· 2-19

2.11.2 SOAP UI等待客户端请求超时·· 2-19

2.12 XML测试阶段使用的工具·· 2-19

3 Comware NETCONF会话介绍··· 3-1

3.1 会话生命周期·· 3-1

3.1.1 基于SOAP的会话生命周期·· 3-1

3.1.2 基于其他访问方式的会话生命周期·· 3-1

3.2 请求并发·· 3-1

3.3 会话使用的RBAC权限·· 3-1

3.4 会话中使用的锁·· 3-2

3.5 最大会话个数·· 3-2

4 执行Comware NETCONF请求··· 4-1

4.1 Comware支持的NETCONF操作速览·· 4-1

4.2 NETCONF协议规定的操作·· 4-2

4.2.1 get-config操作·· 4-2

4.2.2 edit-config操作·· 4-3

4.2.3 lock操作·· 4-8

4.2.4 unlock操作·· 4-10

4.2.5 get操作·· 4-10

4.2.6 close-session操作·· 4-12

4.2.7 kill-session操作·· 4-12

4.2.8 create-subscription操作·· 4-13

4.2.9 validate 操作·· 4-20

4.2.10 get-schema 操作·· 4-20

4.2.11 获取netconf-state操作·· 4-20

4.3 H3C扩展的协议操作·· 4-25

4.3.1 get-bulk操作·· 4-25

4.3.2 get-bulk-config操作·· 4-26

4.3.3 action操作·· 4-27

4.3.4 load操作·· 4-28

4.3.5 save操作·· 4-29

4.3.6 rollback操作·· 4-30

4.3.7 CLI操作·· 4-31

4.3.8 get-sessions操作·· 4-35

4.3.9 save-point操作·· 4-37

4.3.10 索引替换功能·· 4-42

4.3.11 edit-config的增量下发功能·· 4-43

4.3.12 cancel-subscription操作·· 4-44

4.4 获取和设置数据操作详细列表·· 4-45

4.5 数据获取请求返回值说明·· 4-49

4.5.1 get系列请求返回值包括表、行和列的情况汇总·· 4-49

4.5.2 get系列返回空数据的情况说明·· 4-50

4.5.3 RBAC配置对get系列返回结果的影响·· 4-51

4.5.4 模块自定义过滤对get系列返回结果的影响·· 4-51

5 Comware NETCONF数据过滤功能··· 5-1

5.1 数据过滤方式·· 5-1

5.2 严格匹配·· 5-1

5.3 正则表达式匹配·· 5-2

5.3.1 正则表达式匹配简介·· 5-2

5.3.2 正则表达式操作举例·· 5-4

5.4 条件匹配·· 5-6

5.4.1 条件匹配简介·· 5-6

5.4.2 条件匹配操作举例·· 5-7

5.5 可重复列的过滤·· 5-8

5.6 具有子结构情况下的过滤·· 5-8

6 ncclient作为NETCONF客户端编程示例··· 6-1

6.1 ncclient客户端使用环境准备·· 6-1

6.1.1 ncclient介绍·· 6-1

6.1.2 环境准备·· 6-1

6.1.3 ncclient安装·· 6-1

6.1.4 脚本使用·· 6-2

6.2 建立NETCONF会话·· 6-2

6.2.2 配置NETCONF访问方式·· 6-2

6.2.3 运行脚本建立NETCONF会话·· 6-2

6.3 ncclient基本操作及其示例·· 6-4

6.3.2 配置（edit-config）·· 6-4

6.3.3 查询（get/get-config）·· 6-7

6.3.4 查询（get-bulk/get-bulk-config）·· 6-10

6.3.5 action操作·· 6-12

6.3.6 订阅（subscription）·· 6-14

7 附录··· 7-1

7.1 附录 A Comware系统中NETCONF操作可能返回的错误说明·· 7-1

7.1.1 错误处理说明·· 7-1

7.1.2 Schema验证常见错误·· 7-1

7.1.3 NETCONF处理中的错误·· 7-8

7.2 附录 B Comware Schema内置类型说明·· 7-21

7.3 附录 C Comware Schema的Boolean/boolean说明·· 7-22

7.4 附录 D Comware NETCONF处理可能会遇到的情况建议·· 7-22

7.4.1 部分支持的情况·· 7-22

7.4.2 IP和掩码为索引的情况·· 7-22

7.4.3 请求下发顺序·· 7-22

 

1 NETCONF协议介绍

NETCONF（Network Configuration Protocol，网络配置协议）是一种基于XML的网络管理协议，它提供了一种可编程的、对网络设备进行配置和管理的方法。用户可以通过该协议设置属性、获取属性值、获取统计信息等。这使得它在第三方软件的开发上非常便利，很容易开发出在混合不同厂商、不同设备的环境下的特殊定制的网管软件。

1.1  NETCONF协议结构

NETCONF协议采用分层结构，分为内容层（Content）、操作层（Operations）、RPC（Remote Procedure Call，远程调用）层和通信协议层（Transport Protocol）等。

表1-1 XML分层与NETCONF分层模型对应关系

NETCONF分层	XML分层	说明
内容层	配置数据、状态数据、统计信息等	被管理对象的集合，可以是配置数据、状态数据、统计信息等 NETCONF协议具体可读写的数据请参见《NETCONF XML API 手册》
操作层	<get>,<get-config>,<edit-config>…	在RPC中应用的基本的原语操作集，这些操作组成NETCONF的基本能力 NETCONF全面地定义了对被管理设备的各种基础操作，设备支持的操作请参见“1.6  Comware支持的协议操作”
RPC层	<rpc>,<rpc-reply>	为RPC模块的编码提供了简单的、传输协议无关的机制。通过使用<rpc>和<rpc-reply>元素分别对NETCONF请求和响应数据（即操作层和内容层的内容）进行封装
通信协议层	非FIPS模式下：Console/Telnet/SSH/HTTP/HTTPS/TLS FIPS模式下： Console/SSH/HTTPS/TLS	为NETCONF提供面向连接的、可靠的、顺序的数据链路。 非FIPS模式下： ·     NETCONF支持Telnet、SSH和Console等CLI登录方式/协议，即NETCONF over SSH、NETCONF over Telnet和NETCONF over Console ·     NETCONF支持HTTP和HTTPS协议，即NETCONF over HTTP和NETCONF over HTTPS ·     NETCONF支持封装成SOAP（Simple Object Access Protocol，简单对象访问协议）报文后通过HTTP或HTTPS协议传输，即NETCONF over SOAP over HTTP和NETCONF over SOAP over HTTPS FIPS模式下： ·     NETCONF支持SSH和Console等CLI方式/协议，即NETCONF over SSH和NETCONF over Console ·     NETCONF支持HTTPS登录协议，即NETCONF over HTTPS ·     NETCONF支持封装成SOAP报文后通过HTTPS协议传输，即NETCONF over SOAP over HTTPS

 

1.2  NETCONF基本网络架构

图1-1 NETCONF基本网络架构

 

NETCONF网络主要由NETCONF客户端和NETCONF服务器组成：

·     客户端上需要安装NETCONF客户端软件（如ncclient、NetconfBrowser），或运行基于SOAP请求的脚本或程序。客户端的主要作用为：

¡     通过NETCONF协议对网络设备进行配置和管理。

¡     主动查询网络设备的状态。

¡     接收网络设备主动发送的告警和事件，以获知网络设备的当前状态。

·     服务器（即待管理网络设备）上需要运行NETCONF服务端程序，即支持NETCONF功能。服务器主要用于响应客户端的请求，并在发生故障或事件时，主动通告给客户端。

1.3  NETCONF报文格式

1.3.1  NETCONF

NETCONF命令必须符合XML语言的基本格式，格式遵循RFC 4741。

NETCONF报文分为请求和应答报文两种。NETCONF请求和应答报文的格式有所不同。

执行NETCONF请求前，需要先校验NETCONF报文的数据合法性。如果校验失败，则会向客户端报错。其中，数据合法性校验通过XML Schema的方式完成。

1. 请求格式（能力集Base 1.0）

Comware NETCONF请求遵循NETCONF协议，其格式如下：

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

  <operation>

</rpc>

其中<operation>为“1.6  Comware支持的协议操作”中列举的支持的操作类型：

·     对于get系列操作，filter元素下为H3C自定义部分，以top元素为起点。以get-config操作为例，报文格式为：

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

        模块信息

      </top>

    </filter>

  </get-config>

</rpc>

·     对于edit-config操作，config元素下为H3C自定义部分，以top元素为起点。以edit-config操作为例，报文格式为：

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

        模块信息

      </top>

    </config>

  </edit-config>

</rpc>

 

如下为一个NETCONF请求报文示例，用于获取设备上所有接口的所有参数：

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

]]>]]>

 

2. 应答格式（能力集Base 1.0）

统一为RFC 4741定义的<rpc-reply>，如：

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

  <ok/>

</rpc-reply>

1.3.2  NETCONF over SOAP

通过NETCONF over SOAP访问设备，NETCONF报文会封装在SOAP报文的BODY元素里，这些报文除了需要遵循纯NETCONF报文的规则外，还需要遵循以下规则：

·     SOAP消息必须用XML来编码。

·     SOAP消息必须使用SOAP Envelope命名空间和SOAP Encoding命名空间。

·     SOAP消息不能包含DTD（Document Type Definition，文件类型定义）引用。

·     SOAP消息不能包含XML处理指令。

NETCONF over SOAP请求和应答报文的格式有所不同。

1. 请求格式（SOAP）

如下为一个NETCONF over SOAP请求报文示例，用于获取设备上所有接口的所有参数：

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

2. 应答格式（SOAP）

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

1.3.3  NETCONF报文的其他格式要求

1. CDATA节点

Comware NETCONF中，CLI操作返回的数据因为是命令行的原始输出，故统一使用CDATA标记来封装，以防止客户端程序解析XML出现错误。使用时，客户端需要从CDATA中抽取返回结果。

2. 注释

Comware NETCONF中，XML请求对注释没有要求，可以随意添加合法的注释。XML应答中不包含XML注释。

3. 空格

请求中，如果要保持两端的空格字符，必须对最开始和最后一个空格进行转义，转义遵循W3C XML规范。如果不进行转义，则两端连续的空格会被忽略。

应答元素的值中，两端最外侧的空格会被Comware NETCONF转义。

4. 使用转义

如果需要使用一个当前编码不能支持的字符时，可以使用标准的W3C XML规范来进行转义，比如&#x09;代表一个Tab键。

5. XML编码

Comware NETCONF支持使用gb2312、GB18030、utf-8、utf-16、utf-16BE、utf-16LE、utf-32、utf-32BE、utf-32LE进行传输。默认情况下，如果请求中不指定XML传输格式，将使用utf-8作为默认编码，转换编码过程中，如果出现类似半个汉字之类无法转换的情况，将使用?来替代无法转换的字符。

1.4  Comware NETCONF遵循的协议

NETCONF相关的协议规范如表1-2所示。

表1-2 NETCONF相关协议规范

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

 

1.5  Comware NETCONF支持的能力集

Comware NETCONF支持的能力集如表1-3所示。除RFC中定义的标准能力集外，Comware NETCONF还定义了一些私有能力集。私有能力集没有对应的RFC，因此，私有能力集的RFC列取值为“-”。

表1-3 Comware NETCONF的能力集支持情况

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

 

1.6  Comware支持的协议操作

Comware NETCONF支持的协议操作如表1-4所示。

表1-4 Comware NETCONF对协议操作的支持情况

RPC操作名称	说明	支持情况
action	修改、获取运行统计信息之类的动作	支持
CLI	作为NETCONF的补充，执行NETCONF尚未提供的命令	支持
commit	把候选库的配置提交到生效库	不支持
cancel-commit	取消已提交到运行数据库中的候选数据库配置	不支持
close-session	关闭当前会话	支持
copy-config	配置库拷贝	不支持
create-subscription	事件订阅	支持
delete-config	删除配置	不支持
discard-changes	放弃变更	不支持
edit-config	配置修改	支持
get	获取设备数据	支持
get/filter/netconf	获取系统支持的事件流	支持
get/filter/netconf-state	获取系统NETCONF状态信息	支持
get-bulk	批量获取设备数据	支持
get-bulk-config	批量获取设备配置数据	支持
get-config	获取设备配置数据	支持
get-sessions	获取NETCONF会话信息	支持
kill-session	关闭非当前会话	支持
load	配置加载	支持
lock	加锁NETCONF	支持
rollback	配置回滚	支持
save	配置保存	支持
unlock	解锁NETCONF	支持
validate	NETCONF请求的XML语法检查	支持
get-schema	获取YANG/Schema模型文件	有限支持 目前，设备只为部分模块提供了YANG文件
cancel-subscription	取消订阅	支持

 

 

2 使用NETCONF配置和管理设备

2.1  使用NETCONF配置和管理设备的通用流程

管理员通过NETCONF客户端配置和管理设备时，通常需要按照如下流程来操作：

(1)     选择NETCONF客户端并确定客户端对设备的访问方式

Comware支持如下NETCONF访问方式：

¡     NETCONF over Telnet

¡     NETCONF over Console

¡     NETCONF over SSH

¡     NETCONF over SOAP over HTTP

¡     NETCONF over SOAP over HTTPS

需要根据NETCONF客户端的实际组网环境和需求，选择合适的访问方式。

(2)     在设备上为NETCONF用户设置权限

不同访问方式需要的用户权限不同：

¡     NETCONF over SOAP over HTTP访问方式，需要为用户设置HTTP访问权限。

¡     NETCONF over SOAP over HTTPS访问方式，需要为用户设置HTTPS访问权限。

¡     NETCONF over SSH访问方式，需要为用户设置SSH访问权限。

(3)     在设备上进行访问方式相关配置

依据需要使用的访问方式，打开对应的功能。

(4)     准备NETCONF请求使用的XML消息

根据需访问模块的API文档，构造NETCONF XML请求。

(5)     准备NETCONF客户端

按照RFC 4741的描述准备客户端软件、基于SOAP请求的脚本或程序，使其能发送hello和close-session。具体方法请参见客户端软件的操作指导等。

(6)     使用NETCONF客户端连接到设备

依据需要使用的访问方式，使用准备好的NETCONF客户端连接到设备。

(7)     测试NETCONF客户端和设备的连通性

测试建立连接（hello）和断开连接（close-session）的能力，使后续工作能够正常进行。

(8)     验证准备的NETCONF请求XML报文的正确性

使用工具或命令行XML方式来验证XML报文的正确性。

(9)     将请求集成到客户端脚本或程序

把测试好的XML报文集成到客户端程序中。

(10)     （可选）最佳实践建议

通过NETCONF客户端配置和管理设备时，在某些特殊情况下需要进行特殊处理。例如，容错处理、大数据量处理、并发处理等。

(11)     （可选）常见问题及处理方法

完成上述操作后，即可使用NETCONF客户端程序执行NETCONF操作管理设备。Comware支持操作的详细介绍，请参见“4 执行Comware NETCONF请求”。

2.2  选择NETCONF客户端并确定客户端对设备的访问方式

2.2.1  NETCONF配置方式简介

用户可通过以下方式来使用NETCONF配置和管理设备：

·     通过Telnet、SSH或Console登录到设备并进入XML视图，将合法的NETCONF报文（报文格式请参见“1.3.1  NETCONF”）直接拷贝、粘贴到命令行中执行，即可实现对设备的配置和管理。该方式一般用于研发和测试环境。

·     使用配置工具与设备建立连接并向设备下发NETCONF指令来实现对设备的配置和管理。配置工具支持以下两种传输方式：

¡     NETCONF over SSH传输方式：配置工具采用该方式与设备建立SSH连接后，可下发NETCONF格式报文（报文格式请参见“1.3.1  NETCONF”）配置和管理设备。

¡     NETCONF over SOAP传输方式：该方式通过HTTP/HTTPS与设备建立连接，并将NETCONF指令用SOAP封装成通用格式的报文后发送给设备，报文格式请参见“1.3.2  NETCONF over SOAP”。使用该方式前设备上必须开启NETCONF over SOAP功能。

客户可以根据需要选择NETCONF传输方式，开发和定制自己专用的配置工具软件，也可以使用第三方开发的配置工具。第三方的配置工具有：

·     采用NETCONF over SSH传输方式配置工具：NETCONF Browser等。

·     采用NETCONF over SOAP传输方式配置工具：SOAP UI等。

关于各配置工具的使用方法，请参见配置工具的使用指导文档。

2.2.2  访问方式介绍

H3C设备目前支持如下访问方式：

非FIPS模式下：

·     NETCONF over SSH

·     NETCONF over Telnet

·     NETCONF over Console

·     NETCONF over SOAP over HTTP

·     NETCONF over SOAP over HTTPS

FIPS模式下：

·     NETCONF over SSH

·     NETCONF over Console

·     NETCONF over SOAP over HTTPS

使用不同配置方式时，需要使用的访问方式不同：

·     使用Telnet或SSH登录到设备，进入XML视图执行NETCONF配置时，需要使用NETCONF over Telnet访问方式。

·     使用Console登录到设备，进入XML视图执行NETCONF配置时，需要使用NETCONF over Console访问方式。

·     使用SSH配置工具（例如NETCONF Browser）执行NETCONF配置时，需要使用NETCONF over SSH访问方式。

·     使用SOAP配置工具下发NETCONF指令配置设备时，需要使用NETCONF over SOAP over HTTP或NETCONF over SOAP over HTTPS方式。

2.3  在设备上为NETCONF用户设置权限

使用配置工具与设备建立NETCONF连接前，需要确保NETCONF用户具有对应的操作权限。

2.3.1  确定NETCONF用户需要的权限

Comware通过RBAC（Role Based Access Control，基于角色的访问控制）实现基于角色的用户访问权限控制。RBAC对用户权限的控制包括用户角色规则和资源控制策略两个方面：

·     用户角色规则用来控制用户对系统功能的操作权限。例如，定义用户角色规则允许用户配置A功能，或禁止用户配置B功能。

·     资源控制策略用来控制用户对系统资源的操作权限。例如，定义资源控制策略允许用户操作VLAN 10。

在用户角色规则方面，NETCONF用户角色需要具有如下权限：

·     执行NETCONF操作需要具有执行XML元素NETCONF RPC节点的权限，不同NETCONF操作需要的权限不同，具体请参见表2-1。

·     执行NETCONF操作内容的权限，即用户执行XML元素（具体模块或模块中表的Xpath）的权限。例如，配置用户具有执行接口模块XML元素的权限时，需要执行rule number permit read write execute xml-element ifmgr/命令。

在资源策略方面，可以根据实际需要配置用户角色操作接口、VLAN、VPN、安全域的权限。缺省情况下，用户具有操作所有资源的权限。

不同用户角色的操作权限有所不同：

·     缺省用户角色network-admin、mdc-admin、context-admin具有操作对应设备/MDC/Context的所有功能和资源（除安全日志文件管理相关命令display security-logfile summary、info-center security-logfile directory、security-logfile save之外）的权限。如果用户所属角色是这几种，则只需要指定用户角色为network-admin、mdc-admin或context-admin即可。

·     缺省用户角色network-operator、context-operator和mdc-operator默认只有读权限和部分可执行权限，必须事先配置后才有对应的操作权限。

·     其他用户角色必须事先配置后才有对应的操作权限。

NETCONF操作需要权限的详细介绍请见表2-1。

表2-1 执行NETCONF操作需要配置的权限

执行的NETCONF操作	需要配置的权限节点	需要配置的权限
建立NETCONF会话	不涉及	执行xml命令的权限 对于NETCONF over Telnet、NETCONF over Console访问方式，用户必须具有执行xml命令行的权限，否则无法进入XML视图
向设备订阅事件	rpc/create-subscription	execute
给当前配置加锁	rpc/lock	execute
给当前配置解锁	rpc/unlock	execute
使用<get>获取信息	rpc/get	read
使用<get>获取NETCON状态信息	rpc/get/filter/netconf-state	read
使用<get-bulk>获取信息	rpc/get-bulk	read
使用<get-config>获取配置信息	rpc/get-config	read
使用<get-bulk-config>获取配置信息	rpc/get-bulk-config	read
使用<get-schema>获取yang文件信息	rpc/get-schema	read
<edit-config>编辑指定模块数据	rpc/edit-config	write
执行一个<action>操作	rpc/action	execute
配置保存	rpc/save	write
配置回滚	rpc/rollback	write
配置加载	rpc/load	write
命令行操作	rpc/CLI	write
获取会话信息	rpc/get-sessions	read
关闭另一个会话	rpc/kill-session	execute
执行语法验证	rpc/validate	read
配置回滚点	rpc/save-point	write
候选库配置提交	rpc/commit	execute
取消已提交的配置	rpc/cancel-commit	execute
复制数据库	rpc/copy-config	execute
删除数据库	rpc/delete-config	execute
删除候选库配置	rpc/discard-changes	execute
预配置	rpc/config-provisioned	execute
退出XML视图	不涉及	执行xml命令的权限
取消当前订阅事件	rpc/cancel-subscription	execute

 

2.3.2  定义NETCONF用户角色规则

(1)     进入系统视图。

system-view

(2)     创建用户角色，并进入用户角色视图。

role name role-name

(3)     请根据需要配置用户操作权限的规则。

¡     配置用户具有执行XML元素NETCONF RPC节点的权限。

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

通过rule number permit { execute | read | write } * xml-element rpc/?可以查看具体操作的列表。不指定具体操作时，表示所有操作。

¡     配置用户执行XML元素具体模块的权限。

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

通过rule number { deny | permit } { execute | read | write } * xml-element ？可以查看具体模块列表，通过rule number { deny | permit } { execute | read | write } * xml-element module-name/？可以查看模块中具体表的列表。不指定具体模块和表时表示所有模块/所有表。

2.3.3  配置NETCONF用户

1. 功能简介

本配置用来为NETCONF用户指定如下属性：

·     根据NETCONF访问方式，指定正确的服务类型：使用NETCONF over SSH访问方式时，用户的服务类型为SSH；使用NETCONF over SOAP over HTTP访问方式时，用户的服务类型为HTTP；使用NETCONF over SOAP over HTTPS访问方式时，用户的服务类型为HTTPS。

·     为用户指定用户角色，使其具有所需权限。

本文以本地认证为例，介绍配置过程。使用远程认证的配置方式请参见产品对应版本的AAA配置指导。

2. 配置步骤

(1)     进入系统视图。

system-view

(2)     添加设备管理类本地用户，并进入设备管理类本地用户视图。

local-user user-name class manage

(3)     设置本地用户的密码。

（非FIPS模式）

password [ { hash | simple } string ]

（FIPS模式）

password

在非FIPS模式下，可以不为本地用户设置密码；在FIPS模式下，必须且只能通过交互式方式设置明文密码，否则用户的本地认证不能成功。

(4)     设置本地用户可以使用的服务类型。请根据访问方式选择其中一项进行配置

¡     使用NETCONF over SSH访问方式：

service-type ssh

¡     使用NETCONF over SOAP over HTTP或NETCONF over SOAP over HTTPS访问方式：

（非FIPS模式）

service-type { http | https } *

（FIPS模式）

service-type https

缺省情况下，本地用户不能使用任何服务类型。

(5)     设置本地用户的角色。

authorization-attribute user-role role-name

2.4  在设备上进行访问方式相关配置

2.4.1  配置NETCONF over SSH访问方式

1. 配置SSH登录

以下配置步骤只介绍采用password方式认证SSH客户端的配置方法，publickey方式的配置方法及SSH的详细介绍，请参见“安全配置指导”中的“SSH”。

(1)     进入系统视图。

system-view

(2)     生成本地密钥对。

（非FIPS模式）

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

（FIPS模式）

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

(3)     （可选）创建SSH用户，并指定SSH用户的服务类型为NETCONF，认证方式为password。

ssh user username service-type netconf authentication-type password

(4)     进入VTY用户线或VTY用户线类视图。

¡     进入VTY用户线视图。

line vty first-number [ last-number ]

¡     进入VTY用户线类视图。

line class vty

(5)     配置VTY用户线的认证方式为scheme方式。

（非FIPS模式）

authentication-mode scheme

缺省情况下，VTY用户线的认证方式为password方式。

（FIPS模式）

authentication-mode scheme

缺省情况下，VTY用户线的认证方式为scheme方式。

2. 配置NETCONF over SSH

(1)     进入系统视图。

system-view

(2)     开启NETCONF over SSH。

netconf ssh server enable

缺省情况下，NETCONF over SSH处于关闭状态。

(3)     配置NETCONF over SSH的监听端口。

netconf ssh server port port-number

缺省情况下，NETCONF over SSH的监听端口为830。

(4)     （可选）开启NETCONF日志功能。

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

缺省情况下，NETCONF日志功能处于关闭状态。

(5)     通过SSH配置工具与设备建立NETCONF over SSH会话。关于SSH配置工具的使用方法，具体参见SSH配置工具的配置指导。

2.4.2  配置NETCONF over SOAP over HTTP（或HTTPS）访问方式

1. 功能简介

使用NETCONF over SOAP over HTTP或NETCONF over SOAP over HTTPS访问方式时，配置工具将配置指令封装成SOAP报文后通过HTTP或HTTPS协议传输到设备。

本文仅介绍基本配置，有关SOAP报文的DSCP优先级、NETCONF客户端访问控制、NETCONF用户使用的认证域等相关内容请参见产品对应版本的NETCONF配置、NETCONF命令手册。

2. 开启NETCONF over SOAP功能

(1)     进入系统视图。

system-view

(2)     开启NETCONF over SOAP功能。

（非FIPS模式）

netconf soap { http | https } enable

（FIPS模式）

netconf soap https enable

缺省情况下，NETCONF over SOAP处于关闭状态。

(3)     （可选）开启NETCONF日志功能。

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

缺省情况下，NETCONF日志功能处于关闭状态。

(4)     通过配置工具与设备建立NETCONF over SOAP会话。关于配置工具的使用方法，具体参见配置工具的配置指导。

2.5  准备NETCONF请求使用的XML消息

2.5.1  NETCONF API文档介绍

 

1. 文档组织

NETCONF API文档分属于四个命名空间：

·     data命名空间：提供系统的运行状态数据和配置数据，为只读，支持下发get和get-bulk操作。

·     config命名空间：提供系统的配置数据信息，可读写，支持下发get-config、get-bulk-config和edit-config操作。

·     action命名空间：通常提供系统非配置类的操作（如ping、reset操作），可执行，支持下发action操作。

·     event命名空间：提供系统的事件数据信息，支持通过create-subscription操作订阅指定类型的事件。

每一个支持NETCONF的模块都包括一个或者多个NETCONF API文档，分别描述其在data命名空间、config命名空间、action命名空间和event命名空间的功能。文档命名遵循如下格式，其中XXX代表模块名：

·     data命名空间：Comware XXX NETCONF XML API Data Reference.docx

·     config命名空间：Comware XXX NETCONF XML API Configuration Reference.docx

·     action命名空间：Comware XXX NETCONF XML API Action Reference.docx

·     event命名空间：Comware XXX NETCONF XML API Event Reference.docx

NETCONF模块可能还存在一个名为Comware XXX NETCONF XML API Error Message Reference.docx的模块错误提示信息参考文档，该文档用来描述模块操作过程中的各种错误。

2. 文档内容说明

每一个NETCONF API文档对应一个功能模块，如ARP、DHCP。每个模块由一个或者多个表组成。表以行和列的形式进行组织：

·     行：表示一个对象实例。

·     列：表示每个对象实例中包含的信息。

以ARP表为例，一条ARP表项为一行，ARP表项中的IP地址、MAC地址、所属VLAN等为列。

在NETCONF API文档中，每个表包含下面几个部分的信息：

·     表名称：提供了从模块开始的路径和最终的表名，如：ACL/Base

·     表的XML结构（XML structure）：列举了本表从模块开始的XML表示方式，但不包括值信息，例如：

 

·     表描述（Table description）：提供模块名称、表名称、表类型、行名称和约束信息。其中，表类型取值包括：

¡     Multi-instance table：多实例表格，表示该表可以包含多行。

¡     Single-instance table：单实例表格，表示该表能包括一行。

·     列详细信息（Columns）：提供列名称、列描述、列数据类型和约束条件等信息。列数据类型取值包括：

¡     Index：表示该列为表格的索引列。

¡     N/A：表示该列不作为索引列。

·     应答的XML结构（Responsed XML structure）：列举了本表从模块开始应答消息的XML表示方式，但不包括值信息。客户端可以依据返回结果来判断操作执行的效果。仅action命名空间中可以返回操作结果的表提供此信息。例如：

 

·     应答列详细信息（Responsed columns）：用来描述应答XML结构中的各列。

2.5.2  使用NETCONF API文档构造NETCONF请求报文

NETCONF API文档介绍了NETCONF请求报文（参见“1.3  NETCONF报文格式”）中H3C自定义部分的模块信息语法。构造某一请求时，需要先根据操作类型查找对应模块、对应空间的API文档来获取需要的XML结构，如表2-2所示。

表2-2 操作类型与API文档对应关系

操作类型	需查询的API文档
<get> <get-bulk>	Comware XXX NETCONF XML API Data Reference.docx 例如，接口管理请查询《Comware Ifmgr NETCONF XML API Data Reference.docx》
<get-config> <get-bulk-config> <edit-config>	Comware XXX NETCONF XML API Configuration Reference.docx 例如，接口管理请查询《Comware Ifmgr NETCONF XML API Configuration Reference.docx》
<action>	Comware XXX NETCONF XML API Action Reference.docx 例如，接口管理请查询《Comware Ifmgr NETCONF XML API Action Reference.docx》
<create-subscription>	Comware XXX NETCONF XML API Event Reference.docx 例如，接口管理请查询《Comware Ifmgr NETCONF XML API Event Reference.docx》

 

获取到所需模块的NETCONF API文档后，应当先确认需要的功能是否已经支持。若已经支持，则可以依据真实需求，构造所需报文。一般情况下，可以从对应的表的XML Structure部分开始，依据如下步骤构造NETCONF请求：

(1)     构造XML请求的协议定义部分，即top外层的部分。

以get操作为例，top以外的部分为协议定义部分，可以直接从现有请求或者本文档拷贝。

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

        指定模块，子模块，表名，列名

      </top>

    </filter>

  </get>

</rpc>

其他操作的协议定义部分格式，请参见“4 执行Comware NETCONF请求”。

(2)     构造top元素。

top元素的格式通常为：<top xmlns="http://www.h3c.com/netconf/data:1.0">。其中，http://www.h3c.com/netconf/data:1.0为H3C自定义的命名空间，需要根据需要设置为data、config或action命名空间，即data:1.0也可根据需要设置为config:1.0或action:1.0。

(3)     构造模块操作部分。

拷贝NETCONF API文档中表格XML结构到“指定模块，子模块，表名，列名”部分，然后依据实际情况删除不需要的列或者为已知列赋值。

2.5.3  使用XSD文件构造NETCONF请求

目前产品发布时，会同步发布该产品支持的XSD文件。用户也可以根据XSD文件构造NETCONF请求。构造方法与NETCONF API类似，本文不再赘述。

2.5.4  使用YANG文件构造NETCONF请求

Comware NETCONF请求遵循NETCONF协议，可通过get-schema操作获取设备上某个YANG文件内容，通过获取netconf-state操作获取设备上所有YANG文件列表，详细介绍请参见“4.2.10  get-schema 操作”和“4.2.11  获取netconf-state操作”。

用户也可以根据YANG文件构造NETCONF请求。构造方法与NETCONF API类似，本文不再赘述。

2.6  使用NETCONF客户端连接到设备

2.6.1  选择合适的NETCONF访问方式

Comware目前支持使用NETCONF over Telnet、NETCONF over Console、NETCONF over SSH、NETCONF over SOAP over HTTP、NETCONF over SOAP over HTTPS几种方式访问NETCONF功能。按其访问方式不同，NETCONF的访问方式可以分为下面3类：

·     客户端使用SOAP方式连接到设备：即NETCONF over SOAP over HTTP和NETCONF over SOAP over HTTPS方式。

·     客户端使用NETCONF over SSH访问方式连接到设备：即NETCONF over SSH方式。

·     客户端使用Telnet/SSH/Console以命令行方式连接到设备：即NETCONF over Telnet、NETCONF over Console和NETCONF over SSH方式。

使用前，需要先确定NETCONF客户端选取的访问方式，并在设备上使能对应的功能。使能对应功能后，NETCONF客户端即可使用对应的连接手段访问设备的NETCONF功能。

2.6.2  客户端使用SOAP方式连接到设备

配置完设备后，客户端通过HTTP/HTTPS协议，向设备的80端口（HTTP）或者832端口（HTTPS）的URL地址/soap/netconf/，发送SOAP包装过的NETCONF xml请求来进行配置。例如，设备地址为192.168.1.1，则请求地址为：

·     HTTP方式：http://192.168.1.1/soap/netconf/

·     HTTPS方式：https://192.168.1.1:832/soap/netconf/

 

1. 基于SOAP的报文格式

如图2-1所示，基于SOAP的报文格式，本质是HTTP报文，其格式可分为3个层次：

·     外层：HTTP报文头

·     中间层（HTTP内容）：SOAP格式的报文

·     SOAP内层（Body部分）：NETCONF RPC报文。

图2-1 基于SOAP的报文格式

 

2. 传递登录名和密码

如图2-1所示，登录时，用户名和密码分别放在元素\Envelope\Header\Authentication\UserName和元素\Envelope\Header\Authentication\Password中。

其中，元素Authentication必须满足原则：

·     属于命名空间http://www.h3c.com/netconf/base:1.0。

·     具有http://www.w3.org/2003/05/soap-envelope命名空间下的mustUnderstand属性，且属性值必须为1或者true。

3. 获取登录成功的凭据

如图2-2所示，登录成功后，返回的元素\Envelope\Header\Authentication\AuthInfo的值为下次请求的凭据，客户端必须保留此凭据作为下次请求的凭证。

图2-2 获取登录成功的凭据

 

4. 登录成功后的请求使用凭据的方式

必须使用hello报文返回的凭据作为下次请求的依据，才能成功进行登录后的请求，凭据放在\Envelope\Header\Authentication\AuthInfo中。

图2-3 登录成功后的请求使用凭据

 

5. 变更语言

设备支持中文和英文，可以通过在请求中指定语言的方式来强迫设备在遇到错误时，返回指定语言的错误提示。如图2-3所示，语言放在元素\Envelope\Header\Authentication\Language中，中文取值为zh-cn，英文取值为en，不提供Language时默认为英文。

 

并不是所有的请求应答消息都支持中文。应答消息实际使用的语言，请以返回的属性 xml:lang=”xx”的指示为准。

图2-4 应答消息实际采用的语言

 

6. 基于SOAP的NETCONF请求和其他NETCONF请求的不同点

·     第一个Hello报文和认证是同时进行的。

·     连接为短连接，发送每个请求并接收到应答后，断开与服务器的连接。因此不支持事件订阅。

·     所有请求和正常应答都在外层封装一个SOAP层，只有Body层才封装RPC请求。

·     基于SOAP的NETCONF请求支持多线程并行发送请求，但不要在同一个会话中超过4个并发，一个会话超过4个并发的请求会被拒绝并返回资源不足的错误。

2.6.3  客户端使用NETCONF over SSH访问方式连接到设备

在设备上完成NETCONF over SSH连接相关配置后，客户端可通过NETCONF over SSH访问方式来配置和管理设备。访问过程遵循RFC 4742。

一般情况下，客户端需要提供IP地址、用户名、密码、子系统、端口这几个信息。

Banner、欢迎、前置法律告警在下发到NETCONF over SSH之前可能会被传递到客户端，这些信息应当被客户端忽略。

2.6.4  客户端使用Telnet/SSH/Console以命令行方式连接到设备

客户端通过Telnet、SSH或Console方式登录设备的命令行终端后，执行xml命令进入XML视图，将合法的NETCONF报文直接拷贝、粘贴到命令行提示符处执行，即可实现对设备的配置和管理。

2.6.5  确认连接成功

使用Telnet/SSH/Console/NETCONF over SSH模式连接成功后，会收到服务器发送的hello报文，格式如下，收到后即可确认和设备连接是正常的：

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

使用SOAP方式连接后，收到如下格式的hello报文，可确认NETCONF客户端和设备连接是正常的：

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

2.7  测试NETCONF客户端和设备的连通性

2.7.1  交换能力集

建立NETCONF连接后，客户端和设备必须交换各自支持的能力集，双方收到对方的能力集后才可以进行下一步操作。

1. 设备发送给客户端的报文

设备会发送如下报文自动告知客户端支持的NETCONF能力集：

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

其中：

·     <capabilities>和</capabilities>之间的内容表示设备支持的能力集，以设备实际返回值为准。

·     <session-id>和</session-id>之间的内容表示为本次会话分配的会话ID，用来唯一标识本次会话。

2. 客户端发送给设备的报文

客户端收到设备发送的能力集协商报文后，需要给设备发送如下格式的报文，告知设备客户端支持哪些NETCONF能力集。

Hello协商报文格式如下：

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

  <capabilities>

    <capability>

      capability-set

    </capability>

  </capabilities>

</hello>

其中，capability-set表示客户端支持的能力集，由用户定义。一个<capability>和</capability>选项对中填写一个能力集，可以使用多个选项对，发送多个能力集。

3. 客户端依据设备能力调整NETCONF连接协议

对于NETCONF over SSH功能，按照协议规定，如果两者都有Base 1.1的能力，将自动使用Base1.1规定的访问方式进行通信，故客户端需要检查服务器返回的能力集，依据能力集进行通信协议调整。

2.7.2  断开NETCONF连接

1. 客户端发送报文

客户端通过下发以下报文断开NETCONF连接：

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

  <close-session/>

</rpc>

 

2. 结果验证

设备收到会话关闭请求后，会返回如下报文并退回到用户视图：

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

2.8  验证准备的NETCONF请求XML报文的正确性

连接到设备后，使用准备好的XML来查看请求是否正确。

推荐使用SOAP UI开源工具或者直接使用命令行XML方式来验证。

SOAP UI执行的结果，如图2-5所示。

图2-5 SOAP UI下发XML请求及返回结果举例

 

 

2.9  将请求集成到客户端脚本或程序

当准备好的XML经过验证是正确的后，可以把验证好的XML集成到自己的客户端程序中。如果是无人值守的程序，需要考虑超时、断线等异常情况，以保证长时间情况下也能正确运行。

2.10  最佳实践建议

2.10.1  容错处理

客户端应答需要考虑在某些情况下的异常恢复，如连接断开的情况、XML应答结果不是良好格式的情况、长时间不能得到结果的情况。

2.10.2  大数据量处理

系统中部分表的数据量可能非常大，不适合在一次请求中把数据全部取出，此时可以考虑使用get-bulk操作配合count属性。每次获取一定量的数据，取完需要下一批数据时，使用最后一条数据的索引为条件，继续使用get-bulk，直到获取到所有的数据为止。

另外，在处理大数据量请求时，请考虑TCP底层超时的情况发生，需要适当放大底层TCP timeout参数的值，最好在客户端部署到生产环境前对最大数据情况进行模拟，以期找到一个合适的超时时间。

2.10.3  并发处理

系统支持多个用户或者会话同时下发NETCONF请求，但需要注意的是：

·     多个edit-config同时来变更系统时，如果不加锁，系统最终状态不一定是最终要求的状态。如果携带了错误后自动回滚的选项（edit-config携带的error-option取值为rollback-on-error，详细介绍请参见表4-7），则多人情况下，可能会回退他人的修改。如果有可能，应当避免多个NETCONF客户端同时修改系统，或者对所有请求进行加锁后再下发。加锁方法的详细介绍，请参见“4.2.3  lock操作”。

·     通过lock操作对当前NETCONF会话加锁后，用户仅可以通过该NETCONF会话配置设备。无法通过其他NETCONF会话、其他配置方式（如命令行或SNMP）配置设备。

·     多个get系列操作或者edit-config请求并发时，不能保证一定得到线性的性能提升，视请求占用资源的情况，随着请求的数量增加，单个请求响应时间会加长，整体时间的缩短逐渐减小。

2.10.4  及时关闭连接

通过SOAP发送请求时，当不再使用会话时，建议使用close-session请求关闭当前会话。但需要注意的是：通过close-session关闭会话后，客户端有可能无法收到应答。

2.10.5  事件通知

当debug开关打开时，设备可能会生成大量的debug日志，导致正常响应滞后。因此，不建议通过NETCONF接收Debug级别的日志。

2.10.6  HTTP和HTTPS混用

SOAP同时支持HTTP和HTTPS用户，但不能串用：不能用HTTP登录后，使用HTTP的AuthInfo通过HTTPS访问；反之亦然。

2.11  常见问题及处理方法

2.11.1  命令行上XML请求没有反应

可能的原因是输入没有完成，可以通过手工敲入]]>]]>查看是否真的没有反应。一般情况下，输入]]>]]>后能看到一个应答，提示XML输入错误。为了解决该问题，需要在确认输入XML无误的情况下，使用拷贝粘贴的方式进行，不要手工敲击XML命令片段。

 

2.11.2  SOAP UI等待客户端请求超时

因为系统中某些请求可能耗时很长，对于SOAP方式的请求，客户端软件可能设置了服务器的应答超时时间。当响应时间超过超时时间时，客户端软件直接返回失败。

为避免上述情况发生，建议：

·     逐渐调整客户端socket的超时时间，使之处于一个合适的数值。

·     通过过滤功能对需要获取的数据进行过滤，尽量避免获取整机数据。过滤功能的详细介绍，请参见“5 Comware NETCONF数据过滤功能”。

2.12  XML测试阶段使用的工具

设备上可使用表2-3和表2-4中的命令辅助调试NETCONF功能。

表2-3 SOAP相关

命令	目的
display tcp	查看设备是否监听指定端口，是否存在对应服务的连接

 

表2-4 NETCONF over SSH相关

命令	目的
display tcp	查看设备是否监听指定端口，是否存在对应服务的连接
display ssh server session	查看是否存在活跃的NETCONF over SSH会话
netconf log	查看NETCONF请求的日志和处理结果