Network Working Group                                          T. Iijima
Request for Comments: 5381                                   Y. Atarashi
Category: Informational                                        H. Kimura
                                                               M. Kitani
                                                  Alaxala Networks Corp.
                                                                H. Okita
                                                           Hitachi, Ltd.
                                                            October 2008
        
Network Working Group                                          T. Iijima
Request for Comments: 5381                                   Y. Atarashi
Category: Informational                                        H. Kimura
                                                               M. Kitani
                                                  Alaxala Networks Corp.
                                                                H. Okita
                                                           Hitachi, Ltd.
                                                            October 2008
        

Experience of Implementing NETCONF over SOAP

在SOAP上实现NETCONF的经验

Status of This Memo

关于下段备忘

This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited.

本备忘录为互联网社区提供信息。它没有规定任何类型的互联网标准。本备忘录的分发不受限制。

IESG Note

IESG注释

This document discusses implementation experience of NETCONF over SOAP. Note that Section 2.4 of RFC 4741 states, "A NETCONF implementation MUST support the SSH transport protocol mapping". Therefore, a NETCONF implementation that only supports the SOAP transport described in this document and not (at least) also SSH is not in compliance with the NETCONF standards.

本文档讨论了NETCONF在SOAP上的实现经验。请注意,RFC 4741的第2.4节指出,“NETCONF实现必须支持SSH传输协议映射”。因此,仅支持本文档中描述的SOAP传输而不(至少)支持SSH的NETCONF实现不符合NETCONF标准。

Abstract

摘要

This document describes how the authors developed a SOAP (Simple Object Access Protocol)-based NETCONF (Network Configuration Protocol) client and server. It describes an alternative SOAP binding for NETCONF that does not interoperate with an RFC 4743 conformant implementation making use of cookies on top of the persistent transport connections of HTTP. When SOAP is used as a transport protocol for NETCONF, various kinds of development tools are available. By making full use of these tools, developers can significantly reduce their workload. The authors developed an NMS (Network Management System) and network equipment that can deal with NETCONF messages sent over SOAP. This document aims to provide NETCONF development guidelines gained from the experience of implementing a SOAP-based NETCONF client and server.

本文档描述了作者如何开发基于SOAP(简单对象访问协议)的NETCONF(网络配置协议)客户端和服务器。它描述了NETCONF的另一种SOAP绑定,该绑定不与在HTTP的持久传输连接上使用cookie的RFC4743一致性实现进行互操作。当SOAP用作NETCONF的传输协议时,可以使用各种开发工具。通过充分利用这些工具,开发人员可以大大减少他们的工作量。作者开发了一个NMS(网络管理系统)和网络设备,可以处理通过SOAP发送的NETCONF消息。本文档旨在提供从实现基于SOAP的NETCONF客户端和服务器的经验中获得的NETCONF开发指南。

Table of Contents

目录

   1. Introduction ....................................................3
      1.1. NETCONF over SOAP ..........................................3
      1.2. Motivation .................................................3
   2. NETCONF Development on Web Services Framework ...................4
      2.1. WSDL as an Interface Description Language ..................5
      2.2. Generation of APIs .........................................5
   3. Architecture of the NETCONF over SOAP Implementation ............5
      3.1. SOAP Implementation in NMS .................................6
           3.1.1. SOAP Parser in NMS ..................................7
           3.1.2. Session Maintenance in NMS ..........................7
      3.2. SOAP Implementation in the Network Equipment ...............8
           3.2.1. SOAP Parser in the Network Equipment ................8
           3.2.2. Session Maintenance in the Network Equipment ........8
   4. Guidelines for Developing NETCONF Clients and Servers ...........8
      4.1. Procedures of Development of NETCONF Clients ...............9
           4.1.1. Developing NETCONF Clients without Eclipse .........10
           4.1.2. Developing NETCONF Clients Using Eclipse ...........11
      4.2. Procedures of Development of NETCONF Servers ..............13
           4.2.1. Developing NETCONF Servers without Eclipse .........14
           4.2.2. Developing NETCONF Servers Using Eclipse ...........15
           4.2.3. Developing NETCONF Servers with C
                  Programming Language ...............................18
   5. Security Considerations ........................................18
   6. Acknowledgements ...............................................18
   7. References .....................................................19
      7.1. Normative References ......................................19
      7.2. Informative References ....................................19
        
   1. Introduction ....................................................3
      1.1. NETCONF over SOAP ..........................................3
      1.2. Motivation .................................................3
   2. NETCONF Development on Web Services Framework ...................4
      2.1. WSDL as an Interface Description Language ..................5
      2.2. Generation of APIs .........................................5
   3. Architecture of the NETCONF over SOAP Implementation ............5
      3.1. SOAP Implementation in NMS .................................6
           3.1.1. SOAP Parser in NMS ..................................7
           3.1.2. Session Maintenance in NMS ..........................7
      3.2. SOAP Implementation in the Network Equipment ...............8
           3.2.1. SOAP Parser in the Network Equipment ................8
           3.2.2. Session Maintenance in the Network Equipment ........8
   4. Guidelines for Developing NETCONF Clients and Servers ...........8
      4.1. Procedures of Development of NETCONF Clients ...............9
           4.1.1. Developing NETCONF Clients without Eclipse .........10
           4.1.2. Developing NETCONF Clients Using Eclipse ...........11
      4.2. Procedures of Development of NETCONF Servers ..............13
           4.2.1. Developing NETCONF Servers without Eclipse .........14
           4.2.2. Developing NETCONF Servers Using Eclipse ...........15
           4.2.3. Developing NETCONF Servers with C
                  Programming Language ...............................18
   5. Security Considerations ........................................18
   6. Acknowledgements ...............................................18
   7. References .....................................................19
      7.1. Normative References ......................................19
      7.2. Informative References ....................................19
        
1. Introduction
1. 介绍
1.1. NETCONF over SOAP
1.1. 基于SOAP的NETCONF

This document is not a product from the NETCONF WG but a report on the experience acquired by individual developers.

本文档不是NETCONF工作组的产品,而是关于单个开发人员获得的经验的报告。

SOAP (Simple Object Access Protocol) was specified in [RFC4743] as one of the transport protocols for NETCONF. It is designed to use XML (eXtensible Markup Language) as its description language, which is a fundamental messaging technology for Web Services. For this reason, SOAP is well suited to the NETCONF protocol and can be deployed widely.

SOAP(简单对象访问协议)在[RFC4743]中被指定为NETCONF的传输协议之一。它被设计为使用XML(可扩展标记语言)作为其描述语言,这是Web服务的基本消息传递技术。因此,SOAP非常适合NETCONF协议,并且可以广泛部署。

To develop a SOAP-based NETCONF client and server, several development tools are available as open-source software. The authors developed a SOAP-based NETCONF client and server by using available development tools. The SOAP-based NETCONF client was developed by utilizing Java APIs (Application Programming Interfaces) that are automatically generated from the XSD (XML Schema Definition) file and WSDL (Web Services Description Language) file obtained from [RFC4741] and [RFC4743], respectively. The SOAP-based NETCONF client that the authors developed acts as an NMS (Network Management System). The SOAP-based NETCONF server that the authors developed runs on network equipment and accepts NETCONF messages sent from the NETCONF client.

要开发基于SOAP的NETCONF客户端和服务器,可以使用几种开发工具作为开源软件。作者使用可用的开发工具开发了一个基于SOAP的NETCONF客户端和服务器。基于SOAP的NETCONF客户端是通过利用Java API(应用程序编程接口)开发的,Java API是分别从[RFC4741]和[RFC4743]获取的XSD(XML模式定义)文件和WSDL(Web服务描述语言)文件自动生成的。作者开发的基于SOAP的NETCONF客户端充当NMS(网络管理系统)。作者开发的基于SOAP的NETCONF服务器在网络设备上运行,并接受从NETCONF客户端发送的NETCONF消息。

1.2. Motivation
1.2. 动机

The aim of this document is to describe why the authors believe SOAP is practical as a transport protocol for NETCONF when an NMS is developed. When developing an NMS that uses SOAP as its transport protocol, development tools and procedures can be used according to the Web Services framework. This document also describes the experience of implementing NETCONF over SOAP so that even those who have little knowledge of SOAP can start developing a SOAP-based NETCONF client and server.

本文档的目的是描述当开发NMS时,为什么作者认为SOAP作为NETCONF的传输协议是实用的。在开发使用SOAP作为传输协议的NMS时,可以根据Web服务框架使用开发工具和过程。本文档还描述了通过SOAP实现NETCONF的经验,以便即使对SOAP知之甚少的人也可以开始开发基于SOAP的NETCONF客户机和服务器。

This document describes an alternative SOAP binding for NETCONF that does not interoperate with an RFC 4743 conformant implementation as it relies on cookies used on top of the persistent transport connections of HTTP. This is provided for information purposes only based on the implementation experience of the authors.

本文档描述了NETCONF的另一种SOAP绑定,它不与符合RFC 4743的实现进行互操作,因为它依赖于HTTP的持久传输连接之上使用的cookie。本文仅根据作者的实施经验提供信息。

2. NETCONF Development on Web Services Framework
2. 基于Web服务框架的NETCONF开发

SOAP is a fundamental messaging technology for Web Services. Therefore, if SOAP is used as a transport protocol for NETCONF, a network configuration performed by NETCONF is achieved on the Web Services framework. In this section, the overall architecture of Web Services is described.

SOAP是Web服务的基本消息传递技术。因此,如果将SOAP用作NETCONF的传输协议,则在Web服务框架上实现由NETCONF执行的网络配置。在本节中,将描述Web服务的总体架构。

    +----------------+ +----------------------------+
    |     Format     | |     Register / Search      |
    |                | |                            |
    |      XML       | |           UDDI             |
    |                | |  (Universal Description,   |
    |                | | Discovery and Integration) |
    |                | +----------------------------+
    |                | +----------------------------+ +----------------+
    |                | |    Service Description     | |      API       |
    |                | |                            | |                |
    |                | |           WSDL             | |      JAXM      |
    |                | +----------------------------+ | (Java API for  |
    |                | +----------------------------+ | XML Messaging) |
    |                | |   Fundamental Messaging    | |    JAX-RPC     |
    |                | |                            | | (Java API for  |
    |                | |           SOAP             | |   XML / RPC)   |
    +----------------+ +----------------------------+ +----------------+
                       +----------------------------+
                       |        Transport           |
                       |                            |
                       |       HTTP, HTTPS...       |
                       +----------------------------+
        
    +----------------+ +----------------------------+
    |     Format     | |     Register / Search      |
    |                | |                            |
    |      XML       | |           UDDI             |
    |                | |  (Universal Description,   |
    |                | | Discovery and Integration) |
    |                | +----------------------------+
    |                | +----------------------------+ +----------------+
    |                | |    Service Description     | |      API       |
    |                | |                            | |                |
    |                | |           WSDL             | |      JAXM      |
    |                | +----------------------------+ | (Java API for  |
    |                | +----------------------------+ | XML Messaging) |
    |                | |   Fundamental Messaging    | |    JAX-RPC     |
    |                | |                            | | (Java API for  |
    |                | |           SOAP             | |   XML / RPC)   |
    +----------------+ +----------------------------+ +----------------+
                       +----------------------------+
                       |        Transport           |
                       |                            |
                       |       HTTP, HTTPS...       |
                       +----------------------------+
        

Figure 1: Overall Architecture of Web Services

图1:Web服务的总体架构

As depicted in Figure 1, peripheral technologies around SOAP/HTTP are well developed. Therefore, if SOAP/HTTP is chosen as a transport layer for the NETCONF protocol, the NMS development based on the Web Services framework can choose from different optional services and might be less expensive based on the use of already available services.

如图1所示,围绕SOAP/HTTP的外围技术得到了很好的开发。因此,如果选择SOAP/HTTP作为NETCONF协议的传输层,那么基于Web服务框架的NMS开发可以从不同的可选服务中进行选择,并且根据已经可用的服务的使用,成本可能会更低。

2.1. WSDL as an Interface Description Language
2.1. 作为接口描述语言的WSDL

WSDL [WSDL] defines how SOAP messages are exchanged between Web Services entities. Interfaces of Web Services entities are automatically generated by development tools when importing a WSDL file. Interfaces generated in this manner act as APIs. For the development of an NMS, only these APIs are necessary; there is no need to use SOAP directly.

WSDL[WSDL]定义了如何在Web服务实体之间交换SOAP消息。Web服务实体的接口在导入WSDL文件时由开发工具自动生成。以这种方式生成的接口充当API。对于NMS的开发,只需要这些API;没有必要直接使用SOAP。

Useful tools that can import a WSDL file are available with SOAP. For instance, Apache Axis [Axis] generates an interface from a WSDL file and is a widely used SOAP implementation middleware.

SOAP提供了可以导入WSDL文件的有用工具。例如,ApacheAxis[Axis]从WSDL文件生成接口,是一种广泛使用的SOAP实现中间件。

2.2. Generation of APIs
2.2. API的生成

As described in the previous section, APIs are generated from a WSDL file by development tools such as Apache Axis. Such APIs are in the form of a Java library and act as programming interfaces for an NMS. By using these APIs, an NMS can send SOAP messages to Web Services entities.

如前一节所述,API是由开发工具(如ApacheAxis)从WSDL文件生成的。此类API以Java库的形式存在,并充当NMS的编程接口。通过使用这些API,NMS可以向Web服务实体发送SOAP消息。

3. Architecture of the NETCONF over SOAP Implementation
3. netconfoversoap实现的体系结构

The architecture of the NETCONF over SOAP implementation is shown in Figure 2. A NETCONF implementation residing in an NMS works as a NETCONF client while network equipment acts as a NETCONF server. In this document, we call NETCONF-client and NETCONF-server implementations a NETCONF application and a NETCONF service provider, respectively. A SOAP implementation may be installed on both the NMS and the network equipment. Each instance of the SOAP implementations exchanges SOAP messages based on WSDL, as described in [RFC4743]. If Java libraries generated from the WSDL are provided in the NMS, engineers can develop a NETCONF application, which configures network equipment via the NETCONF protocol, by utilizing the Java library. There is no need for engineers to use XML or SOAP directly.

图2显示了基于SOAP的NETCONF实现的体系结构。驻留在NMS中的NETCONF实现充当NETCONF客户端,而网络设备充当NETCONF服务器。在本文档中,我们将NETCONF客户端和NETCONF服务器实现分别称为NETCONF应用程序和NETCONF服务提供程序。可以在NMS和网络设备上安装SOAP实现。SOAP实现的每个实例都基于WSDL交换SOAP消息,如[RFC4743]中所述。如果NMS中提供了从WSDL生成的Java库,工程师可以开发一个NETCONF应用程序,通过利用Java库通过NETCONF协议配置网络设备。工程师不需要直接使用XML或SOAP。

    +---------------------------+   +---------------------------+
    |      NETCONF Client       |   |       NETCONF Server      |
    |           (NMS)           |   |     (Network Equipment)   |
    |  +---------------------+  |   |  +---------------------+  |
    |  | NETCONF application |  |   |  |    NETCONF service  |  |
    |  |                     |  |   |  |       provider      |  |
    |  +---------------------+  |   |  +---------------------+  |
    |  +---------------------+  |   |                           |
    |  |    Java library     |  |   |                           |
    |  +---------------------+  |   |                           |
    |  +---------------------+  |   |  +---------------------+  |
    |  | SOAP Implementation |  |   |  | SOAP Implementation |  |
    |  |    (Apache Axis)    |  |   |  |                     |  |
    |  +---------------------+  |   |  +---------------------+  |
    +-------^----------|--------+   +-------^----------|--------+
            |          |     rpc-request    |          |
            |          +-----  /SOAP    ----+          |
            |                  / HTTP(S)               |
            |                                          |
            |                 rpc-reply                |
            +----------------  /SOAP    ---------------+
                               / HTTP(S)
        Figure 2: Architecture of NETCONF Implementation Using SOAP
        
    +---------------------------+   +---------------------------+
    |      NETCONF Client       |   |       NETCONF Server      |
    |           (NMS)           |   |     (Network Equipment)   |
    |  +---------------------+  |   |  +---------------------+  |
    |  | NETCONF application |  |   |  |    NETCONF service  |  |
    |  |                     |  |   |  |       provider      |  |
    |  +---------------------+  |   |  +---------------------+  |
    |  +---------------------+  |   |                           |
    |  |    Java library     |  |   |                           |
    |  +---------------------+  |   |                           |
    |  +---------------------+  |   |  +---------------------+  |
    |  | SOAP Implementation |  |   |  | SOAP Implementation |  |
    |  |    (Apache Axis)    |  |   |  |                     |  |
    |  +---------------------+  |   |  +---------------------+  |
    +-------^----------|--------+   +-------^----------|--------+
            |          |     rpc-request    |          |
            |          +-----  /SOAP    ----+          |
            |                  / HTTP(S)               |
            |                                          |
            |                 rpc-reply                |
            +----------------  /SOAP    ---------------+
                               / HTTP(S)
        Figure 2: Architecture of NETCONF Implementation Using SOAP
        

The SOAP implementation in both the NMS and network equipment is explained in detail in the following sections.

以下各节将详细说明NMS和网络设备中的SOAP实现。

3.1. SOAP Implementation in NMS
3.1. 网络管理系统中SOAP的实现

Several SOAP implementations appropriate for use in an NMS are available today. Apache Axis is one such widely used implementation.

目前有几种适合在NMS中使用的SOAP实现。ApacheAxis就是这样一种广泛使用的实现。

Axis works as a SOAP implementation and an NMS-development tool. For instance, WSDL2Java, one of Axis' tools, generates Java-class files from a WSDL file. Another tool called Java2WSDL does the opposite: it generates a WSDL file from Java-class files. Consequently, various benefits can be obtained if Axis is introduced as a SOAP implementation.

Axis用作SOAP实现和NMS开发工具。例如,Axis的工具之一WSDL2Java从WSDL文件生成Java类文件。另一个名为Java2WSDL的工具的作用正好相反:它从Java类文件生成WSDL文件。因此,如果将Axis作为SOAP实现引入,则可以获得各种好处。

To develop a NETCONF application that is capable of various functions such as releasing log messages, Java-class files generated by the Axis tool may be extended by adding more functions. By utilizing these Java libraries, engineers can easily develop NETCONF applications.

为了开发一个NETCONF应用程序,该应用程序能够实现各种功能,例如发布日志消息,可以通过添加更多功能来扩展Axis工具生成的Java类文件。通过利用这些Java库,工程师可以轻松地开发NETCONF应用程序。

3.1.1. SOAP Parser in NMS
3.1.1. 网管系统中的SOAP解析器

The SOAP Parser function is performed entirely by a SOAP implementation such as Apache Axis.

SOAP解析器功能完全由诸如ApacheAxis之类的SOAP实现执行。

3.1.2. Session Maintenance in NMS
3.1.2. 网络管理系统中的会话维护

When exchanging NETCONF messages between an NMS and network equipment, a NETCONF session has to be maintained on both sides, as described in [RFC4741].

在NMS和网络设备之间交换NETCONF消息时,必须在双方维护NETCONF会话,如[RFC4741]所述。

In [RFC4743], HTTP is specified as an option of an underlying protocol for NETCONF over SOAP. When HTTP is used for that purpose, it is also specified that a NETCONF session state is tied to the state of the underlying transport (TCP) connection (just like in NETCONF over SSH [RFC4742] and NETCONF over BEEP [RFC4744]). However, HTTP itself is a stateless protocol, and many server implementations process user requests independently of previous requests received over the same transport connection. To simplify implementation of the NETCONF service provider, we used the cookie field inside the HTTP header to map incoming requests to NETCONF sessions. Note that this means our implementation actually uses an alternative SOAP binding for NETCONF, which does not interoperate with RFC 4743 compliant implementations.

在[RFC4743]中,HTTP被指定为基于SOAP的NETCONF的底层协议的选项。当HTTP用于此目的时,还指定NETCONF会话状态与底层传输(TCP)连接的状态相关联(就像在NETCONF over SSH[RFC4742]和NETCONF over BEEP[RFC4744]中一样)。然而,HTTP本身是一种无状态协议,许多服务器实现独立于先前通过相同传输连接接收的请求来处理用户请求。为了简化NETCONF服务提供者的实现,我们使用HTTP头中的cookie字段将传入请求映射到NETCONF会话。注意,这意味着我们的实现实际上为NETCONF使用了一个替代的SOAP绑定,它不与RFC4743兼容的实现进行互操作。

For example, the implemented NETCONF-session maintenance in the NMS works as follows. After the NMS sends a NETCONF hello message to the network equipment, the NETCONF service provider in the network equipment allocates a session identifier for the NETCONF application in the NMS and writes it inside the <session> element of a replying NETCONF hello message, as described in [RFC4741]. At the same time, the network equipment writes the same value in the cookie field inside an HTTP header. After that, a SOAP message encompassing the replying NETCONF hello message is added. When the NMS receives the newly allocated session identifier from the replying NETCONF hello message, the NETCONF application stores it and writes it inside a <session> element for subsequent NETCONF request messages and in a cookie field for subsequent HTTP headers. By recognizing the session identifier in NETCONF request messages and the cookie field in HTTP headers, the network equipment can maintain both a NETCONF session and the state of an HTTP connection. The NETCONF session is maintained over the maintained state of the HTTP connection. The stored session identifier is erased when the NMS sends a NETCONF close-session message and receives a NETCONF response message from the network equipment.

例如,在NMS中实现的NETCONF会话维护工作如下。NMS向网络设备发送NETCONF hello消息后,网络设备中的NETCONF服务提供商为NMS中的NETCONF应用程序分配会话标识符,并将其写入应答NETCONF hello消息的<session>元素中,如[RFC4741]所述。同时,网络设备在HTTP报头内的cookie字段中写入相同的值。然后,添加一条包含回复NETCONF hello消息的SOAP消息。当NMS从应答的NETCONF hello消息接收到新分配的会话标识符时,NETCONF应用程序将其存储并写入后续NETCONF请求消息的<session>元素中,以及后续HTTP头的cookie字段中。通过识别NETCONF请求消息中的会话标识符和HTTP头中的cookie字段,网络设备可以维护NETCONF会话和HTTP连接的状态。NETCONF会话在HTTP连接的维护状态下进行维护。当NMS发送NETCONF关闭会话消息并从网络设备接收NETCONF响应消息时,存储的会话标识符将被擦除。

3.2. SOAP Implementation in the Network Equipment
3.2. SOAP在网络设备中的实现

To accept SOAP messages sent from the NMS, it is also necessary to provide SOAP in the network equipment. As in the case of NMS, some free SOAP implementations are available today for installation on network equipment. However, the memory capacity of the network equipment might be limited. Therefore, the SOAP implementation may be chosen taking memory capacity into consideration. In some cases, a memory-saving method will be required when implementing SOAP in the network equipment.

为了接受从NMS发送的SOAP消息,还需要在网络设备中提供SOAP。与NMS的情况一样,现在可以在网络设备上安装一些免费的SOAP实现。然而,网络设备的存储容量可能会受到限制。因此,可以考虑存储器容量来选择SOAP实现。在某些情况下,在网络设备中实现SOAP时需要一种内存节省方法。

3.2.1. SOAP Parser in the Network Equipment
3.2.1. 网络设备中的SOAP解析器

A SOAP header inside the SOAP envelope is defined as optional. Therefore, the module that processes the SOAP header can be omitted if the memory capacity in the network equipment is insufficient. In this case, a SOAP parser in the network equipment is allowed to parse only mandatory parts of a SOAP envelope.

SOAP信封中的SOAP头被定义为可选的。因此,如果网络设备中的存储器容量不足,则可以省略处理SOAP报头的模块。在这种情况下,允许网络设备中的SOAP解析器仅解析SOAP信封的必需部分。

3.2.2. Session Maintenance in the Network Equipment
3.2.2. 网络设备中的会话维护

To maintain NETCONF sessions with the NMS, the NETCONF service provider in the network equipment has to provide a session identifier to the NMS, as described in [RFC4741].

如[RFC4741]所述,为了维护与NMS的NETCONF会话,网络设备中的NETCONF服务提供商必须向NMS提供会话标识符。

For example, the implemented NETCONF-session maintenance in the network equipment works as follows. When the network equipment receives a NETCONF hello message from the NMS, the NETCONF service provider in the network equipment sets a session identifier inside the <session> element of a replying NETCONF hello message, as described in [RFC4741]. At the same time, the network equipment also sets the same value in the cookie field inside an HTTP header. After that, a SOAP message encompassing the replying NETCONF hello message is added. The cookie field inside the HTTP header is used for maintaining the state of the HTTP connection over which the NETCONF-session maintenance is ensured. The network equipment then sends an HTTP response message to the NMS. When the network equipment receives a NETCONF close-session message from the NMS, it erases the stored session identifier.

例如,在网络设备中实现的NETCONF会话维护工作如下。当网络设备从NMS接收到NETCONF hello消息时,网络设备中的NETCONF服务提供商在应答NETCONF hello消息的<session>元素内设置会话标识符,如[RFC4741]中所述。同时,网络设备还在HTTP报头内的cookie字段中设置相同的值。然后,添加一条包含回复NETCONF hello消息的SOAP消息。HTTP头中的cookie字段用于维护HTTP连接的状态,通过该状态可以确保NETCONF会话维护。然后,网络设备向NMS发送HTTP响应消息。当网络设备从NMS接收到NETCONF close session消息时,它将删除存储的会话标识符。

4. Guidelines for Developing NETCONF Clients and Servers
4. 开发NETCONF客户端和服务器的指南

In the case of SOAP transport mapping, sharing information on the kinds of development tools that are available would help developers start developing SOAP-based NETCONF clients and servers. That would contribute to the rapid deployment of SOAP-based NETCONF clients and servers.

在SOAP传输映射的情况下,共享关于可用开发工具种类的信息将帮助开发人员开始开发基于SOAP的NETCONF客户端和服务器。这将有助于快速部署基于SOAP的NETCONF客户端和服务器。

4.1. Procedures of Development of NETCONF Clients
4.1. NETCONF客户端的开发过程

To develop a SOAP-based NETCONF client, a stub code may be generated. A stub is a library that is generated automatically from WSDL by a Web Services tool and that acts as a group of APIs. When using Apache Axis as a Web Services tool, a generated stub is in the form of Java APIs. These Java APIs display interfaces of a Web Service as if they are methods capable of configuring a local machine.

要开发基于SOAP的NETCONF客户端,可以生成存根代码。存根是由Web服务工具从WSDL自动生成的库,它充当一组API。当使用ApacheAxis作为Web服务工具时,生成的存根采用JavaAPI的形式。这些JavaAPI显示Web服务的接口,就好像它们是能够配置本地机器的方法一样。

The WSDL file named "netconf-soap_1.0.wsdl", which is selected from [RFC4743], specifies NETCONF messages to be exchanged between the NETCONF client and server. These NETCONF messages are the "hello" message and "rpc" message. Therefore, stub codes for creating the "hello" message and "rpc" message are generated from "netconf-soap_1.0.wsdl". However, the file "netconf-soap_1.0.wsdl" is not sufficient because no service element is specified.

从[RFC4743]中选择的名为“netconf-soap_1.0.WSDL”的WSDL文件指定要在netconf客户端和服务器之间交换的netconf消息。这些NETCONF消息是“hello”消息和“rpc”消息。因此,用于创建“hello”消息和“rpc”消息的存根代码是从“netconf-soap_1.0.wsdl”生成的。但是,文件“netconf-soap_1.0.wsdl”不够,因为没有指定服务元素。

In "myNetconfService.wsdl", which is also selected from [RFC4743], a service element is specified and "netconf-soap_1.0.wsdl" is imported. Stub codes generated from those WSDL files are found in files such as "Netconf.java", "NetconfLocator.java", and "NetconfBindingStub.java".

在“myNetconfService.wsdl”中(也从[RFC4743]中选择),指定了一个服务元素,并导入了“netconf-soap_1.0.wsdl”。从这些WSDL文件生成的存根代码可以在诸如“Netconf.java”、“NetconfLocator.java”和“NetconfBindingStub.java”等文件中找到。

When interfaces are used to operate the NETCONF protocol in the manner of "get-config" and "edit-config", for example, an XML schema file named "netconf.xsd", which is selected from [RFC4741], is used by being imported into "netconf-soap_1.0.wsdl". Using the XML schema, methods of operating the NETCONF protocol are generated in files such as "GetConfigType.java" and "EditConfigType.java".

例如,当使用接口以“get-config”和“edit-config”的方式操作NETCONF协议时,从[RFC4741]中选择的名为“NETCONF.xsd”的XML模式文件被导入到“NETCONF-soap_1.0.wsdl”中。使用XML模式,在诸如“GetConfigType.java”和“EditConfigType.java”等文件中生成操作NETCONF协议的方法。

When interfaces are used to configure network functions at the network equipment, a data model of each network function has to be defined in the style of an XML schema. The XML schema may be imported into "netconf-soap_1.0.wsdl" in the same manner as that of the XML schema in [RFC4741].

当使用接口在网络设备上配置网络功能时,必须以XML模式的样式定义每个网络功能的数据模型。XML模式可以以与[RFC4741]中XML模式相同的方式导入“netconf-soap_1.0.wsdl”。

The connection between the NETCONF schema and a data model should be made by inserting the following attribute into elements of each data model. This attribute is defined in the XML schema in [RFC4741].

NETCONF模式和数据模型之间的连接应该通过在每个数据模型的元素中插入以下属性来实现。此属性在[RFC4741]中的XML模式中定义。

   <xs:attribute name="operation" type="editOperationType"
   default="merge"/>
        
   <xs:attribute name="operation" type="editOperationType"
   default="merge"/>
        

Consequently, using "myNetconfService.wsdl" to import "netconf-soap_1.0.wsdl", NETCONF schema, and the data model makes it possible to generate stub files containing interfaces to configure network equipment.

因此,使用“myNetconfService.wsdl”导入“netconf-soap_1.0.wsdl”、netconf模式和数据模型,可以生成包含配置网络设备接口的存根文件。

When stub codes are generated, the development environment may be arranged as well. The development of a Java-based NETCONF client may use JDK (Java Development Kit) [JDK] and Apache Axis. In addition, using some IDE (Integrated Development Environment) such as Eclipse [Eclipse] with Apache Ant [Ant] and NetBeans [NetBeans] would reduce the developer workload significantly. When Eclipse is used as an IDE, first, the library (*.jar files) of Axis has to be added to the development project's build path as an external library. The library of Axis acts as a SOAP library, so there is no need to be concerned about SOAP messaging when programming a NETCONF client using the library of Axis.

生成存根代码时,还可以安排开发环境。基于Java的NETCONF客户端的开发可以使用JDK(Java开发工具包)[JDK]和Apache Axis。此外,使用一些IDE(集成开发环境),例如Eclipse[Eclipse]和ApacheAnt[Ant]以及NetBeans[NetBeans]将显著减少开发人员的工作量。当Eclipse用作IDE时,首先,Axis的库(*.jar文件)必须作为外部库添加到开发项目的构建路径中。Axis库充当SOAP库,因此在使用Axis库编程NETCONF客户端时,无需担心SOAP消息传递。

4.1.1. Developing NETCONF Clients without Eclipse
4.1.1. 在没有Eclipse的情况下开发NETCONF客户端

Given that development of a NETCONF client is carried out in the environment of a Windows computer without Eclipse, and that "myNetconfService.wsdl" is placed in the "C:\NetconfClient" directory, a stub is generated by executing the following command in the command prompt.

假设NETCONF客户端的开发是在没有Eclipse的Windows计算机环境中进行的,并且“myNetconfService.wsdl”被放置在“C:\NetconfClient”目录中,则通过在命令提示符中执行以下命令生成存根。

   C:\NetconfClient>java -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME%
   \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery-
   0.2.jar;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar
   org.apache.axis.wsdl.WSDL2Java -p stub myNetconfService.wsdl
        
   C:\NetconfClient>java -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME%
   \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery-
   0.2.jar;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar
   org.apache.axis.wsdl.WSDL2Java -p stub myNetconfService.wsdl
        

In the directory where the WSDL file is located, the WSDL2Java command is executed. Locations of each Axis library have to be specified. The environment variable of "AXIS_HOME" is the directory where Axis is installed. By executing the above command, files with an extension of "*.java" are generated in the "stub" directory, which is specified by the above command. Inside the stub directory, we can find files such as "NetconfBindingStub.java", "Hello.java", and "GetConfigType.java".

在WSDL文件所在的目录中,执行WSDL2Java命令。必须指定每个轴库的位置。环境变量“AXIS_HOME”是安装AXIS的目录。通过执行上述命令,扩展名为“*.java”的文件将在上述命令指定的“存根”目录中生成。在存根目录中,我们可以找到诸如“NetconfBindingStub.java”、“Hello.java”和“GetConfigType.java”等文件。

Next, it is necessary to compile these files by executing the following command in the command prompt.

接下来,需要通过在命令提示符下执行以下命令来编译这些文件。

   C:\NetconfClient>javac -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar stub/*.java
        
   C:\NetconfClient>javac -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar stub/*.java
        

After the compilation of those java files, "*.class" files are generated. After the compiling is done, the source code of the NETCONF client has to be written. Sample source code of the NETCONF client is shown in Figure 3. This NETCONF client is written by utilizing stub classes and interfaces, which are imported into the local package and referenced.

编译这些java文件后,将生成“*.class”文件。编译完成后,必须编写NETCONF客户端的源代码。NETCONF客户端的示例源代码如图3所示。这个NETCONF客户机是利用存根类和接口编写的,存根类和接口被导入本地包并被引用。

   import org.apache.axis.types.UnsignedInt;
   import org.apache.axis.types.*;
        
   import org.apache.axis.types.UnsignedInt;
   import org.apache.axis.types.*;
        
   public class NetconfClient {
           /**
            * @param args
            */
           public static void main(String[] args) {
                   // TODO Auto-generated method stub
                   try{
                           NetconfClient client = new NetconfClient();
                           java.net.URL url = new java.net.URL(args[0]);
                           stub.Netconf netconf =
                                   new stub.NetconfLocator();
                           stub.NetconfPortType stubNetconf =
                                   netconf.getnetconfPort(url);
        
   public class NetconfClient {
           /**
            * @param args
            */
           public static void main(String[] args) {
                   // TODO Auto-generated method stub
                   try{
                           NetconfClient client = new NetconfClient();
                           java.net.URL url = new java.net.URL(args[0]);
                           stub.Netconf netconf =
                                   new stub.NetconfLocator();
                           stub.NetconfPortType stubNetconf =
                                   netconf.getnetconfPort(url);
        
                           URI[] uri = new URI[1];
                           stub.holders.HelloCapabilitiesHolder
                           capability = new
                           stub.holders.HelloCapabilitiesHolder(uri);
        
                           URI[] uri = new URI[1];
                           stub.holders.HelloCapabilitiesHolder
                           capability = new
                           stub.holders.HelloCapabilitiesHolder(uri);
        
                           UnsignedInt id = new UnsignedInt();
                           id.setValue(1);
                           org.apache.axis.holders.UnsignedIntHolder
                           holder = new
                           org.apache.axis.holders.UnsignedIntHolder(id)
                           ;
                           stubNetconf.hello(capability, holder);
                   }catch(Exception e){
                           e.printStackTrace();
                   }
           }
   }
        
                           UnsignedInt id = new UnsignedInt();
                           id.setValue(1);
                           org.apache.axis.holders.UnsignedIntHolder
                           holder = new
                           org.apache.axis.holders.UnsignedIntHolder(id)
                           ;
                           stubNetconf.hello(capability, holder);
                   }catch(Exception e){
                           e.printStackTrace();
                   }
           }
   }
        

Figure 3: Sample Source Code of NETCONF Clients

图3:NETCONF客户端的示例源代码

To add functions such as the release of log messages, these functions have to be incorporated at this stage. Again, the NETCONF client is developed by compiling its source codes.

要添加诸如发布日志消息之类的功能,必须在此阶段合并这些功能。同样,NETCONF客户端是通过编译其源代码开发的。

4.1.2. Developing NETCONF Clients Using Eclipse
4.1.2. 使用Eclipse开发NETCONF客户端

When we use Eclipse and Apache Ant, the procedures described in the previous section are significantly simplified and executed at one time. In this case, files named "build.xml" and "build.properties" are required for Apache Ant.

当我们使用Eclipse和ApacheAnt时,上一节中描述的过程将大大简化并一次性执行。在本例中,ApacheAnt需要名为“build.xml”和“build.properties”的文件。

The file named "build.xml" is written in XML and seen by Apache Ant when Apache Ant is running on Eclipse. The file specifies how Apache Ant behaves. According to the descriptions of the file, Apache Ant compiles source codes, generates JAR (Java ARchive) file, and so on. On the other hand, the file named "build.properties" specifies properties of the development environment where Apache Ant runs. This file is referred to by the "build.xml" file.

名为“build.xml”的文件是用xml编写的,当ApacheAnt在Eclipse上运行时,ApacheAnt可以看到该文件。该文件指定ApacheAnt的行为方式。根据文件的描述,ApacheAnt编译源代码,生成JAR(Java存档)文件,等等。另一方面,名为“build.properties”的文件指定运行ApacheAnt的开发环境的属性。此文件由“build.xml”文件引用。

Examples of "build.xml" and "build.properties" are shown in Figure 4 and Figure 5, respectively.

图4和图5分别显示了“build.xml”和“build.properties”的示例。

   <?xml version="1.0"?>
   <project name="NetconfClient" default="all" basedir=".">
           <property file="build.properties"/>
           <path id="axis-classpath">
                   <fileset dir="${axis.libdir}">
                           <include name="*.jar"/>
                   </fileset>
           </path>
           <target name="prepare">
                   <mkdir dir="${destdir}"/>
           </target>
           <target name="stub" depends="prepare">
                   <java classname="org.apache.axis.wsdl.WSDL2Java" fork
                           ="Yes">
                           <arg value="-o"/>
                           <arg value="${srcdir}"/>
                           <arg value="-p"/>
                           <arg value="${stub.stubdir}"/>
                           <arg value="${stub.wsdlpath}"/>
                           <classpath refid="axis-classpath"/>
                   </java>
           </target>
           <target name="compile" depends="stub">
                   <javac srcdir="${srcdir}" destdir="${destdir}"
                           encoding="UTF-8">
                           <classpath refid="axis-classpath"/>
                   </javac>
           </target>
           <target name="stub-jar" depends="compile">
                   <jar jarfile="${stub.jar}" basedir="${destdir}"/>
           </target>
           <target name="all" depends="stub-jar"/>
   </project>
        
   <?xml version="1.0"?>
   <project name="NetconfClient" default="all" basedir=".">
           <property file="build.properties"/>
           <path id="axis-classpath">
                   <fileset dir="${axis.libdir}">
                           <include name="*.jar"/>
                   </fileset>
           </path>
           <target name="prepare">
                   <mkdir dir="${destdir}"/>
           </target>
           <target name="stub" depends="prepare">
                   <java classname="org.apache.axis.wsdl.WSDL2Java" fork
                           ="Yes">
                           <arg value="-o"/>
                           <arg value="${srcdir}"/>
                           <arg value="-p"/>
                           <arg value="${stub.stubdir}"/>
                           <arg value="${stub.wsdlpath}"/>
                           <classpath refid="axis-classpath"/>
                   </java>
           </target>
           <target name="compile" depends="stub">
                   <javac srcdir="${srcdir}" destdir="${destdir}"
                           encoding="UTF-8">
                           <classpath refid="axis-classpath"/>
                   </javac>
           </target>
           <target name="stub-jar" depends="compile">
                   <jar jarfile="${stub.jar}" basedir="${destdir}"/>
           </target>
           <target name="all" depends="stub-jar"/>
   </project>
        

Figure 4: build.xml of NETCONF Clients

图4:NETCONF客户端的build.xml

   axis.libdir=C:/axis-1_4/lib
   srcdir=src
   destdir=classes
   stub.stubdir=stub
   stub.wsdlpath=myNetconfService.wsdl
   stub.jar=NETCONF.jar
        
   axis.libdir=C:/axis-1_4/lib
   srcdir=src
   destdir=classes
   stub.stubdir=stub
   stub.wsdlpath=myNetconfService.wsdl
   stub.jar=NETCONF.jar
        

Figure 5: build.properties of NETCONF Clients

图5:NETCONF客户端的build.properties

The location of the WSDL file should be specified in the "build.properties" file. In the case shown in Figure 5, the location of the WSDL file is specified as being under the current directory.

WSDL文件的位置应该在“build.properties”文件中指定。在图5所示的情况下,WSDL文件的位置被指定为在当前目录下。

By running Apache Ant on Eclipse, the steps specified in Figure 4 are taken. First, stub codes are generated. Then, compiling of those stub codes is executed. We were careful about the encoding style used for the compiling. After the compilation, Apache Ant will generate a JAR file, which is the output that compresses all stub files (*.class) and acts as a library. In this example, the name "NETCONF.jar" is specified in Figure 5. The "NETCONF.jar" file also has to be added to the build path of the development project as an external library.

通过在Eclipse上运行ApacheAnt,可以执行图4中指定的步骤。首先,生成存根代码。然后,执行这些存根代码的编译。我们对编译时使用的编码风格非常谨慎。编译完成后,ApacheAnt将生成一个JAR文件,该文件是压缩所有存根文件(*.class)并充当库的输出。在本例中,名称“NETCONF.jar”在图5中指定。“NETCONF.jar”文件还必须作为外部库添加到开发项目的构建路径中。

After the "NETCONF.jar" file is added to the build path of the development project, source codes of the NETCONF client can be written by utilizing stub classes and interfaces. Source codes like the one shown in Figure 3 can be written. By running Apache Ant again, the source code of the NETCONF client is compiled. The NETCONF client is developed in this manner.

将“NETCONF.jar”文件添加到开发项目的构建路径后,可以利用存根类和接口编写NETCONF客户机的源代码。可以编写如图3所示的源代码。通过再次运行ApacheAnt,可以编译NETCONF客户端的源代码。NETCONF客户端就是以这种方式开发的。

4.2. Procedures of Development of NETCONF Servers
4.2. NETCONF服务器的开发过程

In the Web Services framework, there are two approaches for developing a Web Services provider, namely a NETCONF server. One is called the top-down approach, and the other is called the bottom-up approach. The top-down approach is carried out by first designing a WSDL file. A skeleton source code from the WSDL file is then generated by using a Web Services tool such as Apache Axis. The generated skeleton code is just a template of the Web Services provider's source code. Therefore, even though the Web Services provider's skeleton code works on its own, if additional functions were necessary, the generated skeleton code would require additional source codes. This approach is superior to the bottom-up approach in terms of interoperability because the specification is already defined in the WSDL file. All vendors have to be in compliance with the WSDL file.

在Web服务框架中,有两种开发Web服务提供者的方法,即NETCONF服务器。一种称为自顶向下方法,另一种称为自下而上方法。自顶向下的方法是通过首先设计一个WSDL文件来实现的。然后使用诸如ApacheAxis之类的Web服务工具从WSDL文件生成一个框架源代码。生成的框架代码只是Web服务提供商源代码的模板。因此,即使Web服务提供商的框架代码能够独立工作,如果需要其他功能,生成的框架代码也需要其他源代码。这种方法在互操作性方面优于自底向上的方法,因为规范已经在WSDL文件中定义。所有供应商都必须遵守WSDL文件。

In contrast, the bottom-up approach is carried out by first creating Web Services from source code (e.g., Java bean) and then generating a WSDL file from the source code by using a Web Services tool such as Axis. This approach is faster and easier than the top-down approach. However, in the bottom-up approach, it is difficult to ensure interoperability since implementation of a Web Services becomes vendor-specific.

相反,自下而上的方法是通过首先从源代码(如JavaBean)创建Web服务,然后使用Axis等Web服务工具从源代码生成WSDL文件来实现的。这种方法比自顶向下的方法更快、更容易。然而,在自下而上的方法中,很难确保互操作性,因为Web服务的实现是特定于供应商的。

When developing a NETCONF server, the WSDL file is already defined in [RFC4743], so there is no choice but to develop the NETCONF server using the top-down approach. The remainder of this section describes the top-down approach for developing a NETCONF server.

在开发NETCONF服务器时,[RFC4743]中已经定义了WSDL文件,因此除了使用自顶向下的方法开发NETCONF服务器之外别无选择。本节的其余部分描述了开发NETCONF服务器的自顶向下方法。

To develop a SOAP-based NETCONF server using the top-down approach, a skeleton code is necessary. A skeleton is a library, which is also generated automatically from WSDL by a Web Services tool. When using Axis as a Web Services tool, the generated skeleton is in the form of a Java library. From the same WSDL file as that used for generating the stub code, skeleton codes are generated in files such as "NetconfBindingSkeleton.java", "Hello.java", and "GetConfigType.java".

要使用自顶向下的方法开发基于SOAP的NETCONF服务器,需要一个框架代码。骨架是一个库,它也是由Web服务工具从WSDL自动生成的。将Axis用作Web服务工具时,生成的框架是Java库的形式。从与用于生成存根代码的WSDL文件相同的WSDL文件中,在诸如“NetconfBindingSkeleton.java”、“Hello.java”和“GetConfigType.java”等文件中生成骨架代码。

When skeleton codes are being generated, the development environment may be arranged as well. Moreover, when a Java-based NETCONF server is being developed, in addition to JDK and Axis, a servlet container such as Apache Tomcat [Tomcat] is necessary. The "webapps\axis" directory under the Axis directory has to be copied to the "webapps" directory under the Tomcat directory.

生成骨架代码时,还可以安排开发环境。此外,在开发基于Java的NETCONF服务器时,除了JDK和Axis之外,还需要一个servlet容器,例如ApacheTomcat[Tomcat]。axis目录下的“webapps\axis”目录必须复制到Tomcat目录下的“webapps”目录。

4.2.1. Developing NETCONF Servers without Eclipse
4.2.1. 在没有Eclipse的情况下开发NETCONF服务器

Given that the development environment of a NETCONF server is created in the environment of a Windows computer without Eclipse and "myNetconfService.wsdl" is placed in the "C:\NetconfServer" directory, a skeleton is generated by executing the following command in the command prompt.

假定NETCONF服务器的开发环境是在没有Eclipse的Windows计算机环境中创建的,并且“myNetconfService.wsdl”被放置在“C:\NetconfServer”目录中,则通过在命令提示符中执行以下命令生成一个框架。

   C:\NetconfServer>java -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME%
   \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery-
   0.2.jar;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar
   org.apache.axis.wsdl.WSDL2Java -p skeleton -s -S true -d Session
   myNetconfService.wsdl
        
   C:\NetconfServer>java -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME%
   \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery-
   0.2.jar;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar
   org.apache.axis.wsdl.WSDL2Java -p skeleton -s -S true -d Session
   myNetconfService.wsdl
        

In the directory where the WSDL file is located, a WSDL2Java command is executed. Locations of each Axis library should be specified. The environment variable of "AXIS_HOME" is a directory where Axis is installed. By executing the above command, files with an extension

在WSDL文件所在的目录中,执行WSDL2Java命令。应指定每个轴库的位置。环境变量“AXIS_HOME”是安装AXIS的目录。通过执行上述命令,可以创建具有扩展名的文件

of "*.java" are generated in the "skeleton" directory, which is specified in the above command. Inside the skeleton directory, files such as "NetconfBindingSkeleton.java", "Hello.java", and "GetConfigType.java" exist. Furthermore, files named "deploy.wsdd" and "undeploy.wsdd" are found. "Deploy.wsdd" and "undeploy.wsdd" are used when deploying a NETCONF server in a servlet container and when undeploying a NETCONF server from a servlet container, respectively.

在上述命令中指定的“骨架”目录中生成“*.java”的。在skeleton目录中,存在诸如“NetconfBindingSkeleton.java”、“Hello.java”和“GetConfigType.java”等文件。此外,还可以找到名为“deploy.wsdd”和“undeploy.wsdd”的文件。“Deploy.wsdd”和“undeploy.wsdd”分别用于在servlet容器中部署NETCONF服务器和从servlet容器中取消部署NETCONF服务器。

Adding source codes of NETCONF server functions to skeleton codes such as "NetconfBindingImpl.java" is required as the need arises. Functions such as the release of log messages have to be added at this stage. After that, by executing the following command in the command prompt, compilation of java files is carried out. Doing so will generate "*.class" files.

根据需要,需要将NETCONF服务器函数的源代码添加到诸如“NetconfBindingImpl.java”之类的框架代码中。在此阶段必须添加日志消息发布等功能。然后,通过在命令提示符中执行以下命令,执行java文件的编译。这样做将生成“*.class”文件。

   C:\NetconfServer>javac -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar skeleton/*.java
        
   C:\NetconfServer>javac -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar skeleton/*.java
        

A NETCONF server can be developed by following the above-described procedures. These class files should be copied into the directory "webapps\axis\WEB-INFO\classes" of the Apache Tomcat directory. Finally, the NETCONF server is deployed by executing the following command.

可以按照上述步骤开发NETCONF服务器。这些类文件应复制到Apache Tomcat目录的目录“webapps\axis\WEB-INFO\classes”中。最后,通过执行以下命令部署NETCONF服务器。

   C:\NetconfServer>java -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME%
   \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery-
   0.2.jar org.apache.axis.client.AdminClient -p 832 depoy.wsdd
        
   C:\NetconfServer>java -classpath .;%AXIS_HOME%\lib\axis.jar;%
   AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME%
   \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery-
   0.2.jar org.apache.axis.client.AdminClient -p 832 depoy.wsdd
        

The command is executed in the directory where "deploy.wsdd" is located. The file "deploy.wsdd" is generated at the same time the skeleton code is generated. After deployment, the NETCONF server receives NETCONF messages sent from the NETCONF client.

该命令在“deploy.wsdd”所在的目录中执行。文件“deploy.wsdd”是在生成框架代码的同时生成的。部署后,NETCONF服务器接收从NETCONF客户端发送的NETCONF消息。

4.2.2. Developing NETCONF Servers Using Eclipse
4.2.2. 使用Eclipse开发NETCONF服务器

When Eclipse and Apache Ant are used, the procedures described in the previous section are significantly simplified and executed at one time. Files named "build.xml" and "build.properties" are required for Apache Ant. Examples of "build.xml" and "build.properties" are shown in Figure 6 and Figure 7, respectively.

当使用Eclipse和ApacheAnt时,上一节中描述的过程将大大简化并一次性执行。ApacheAnt需要名为“build.xml”和“build.properties”的文件。图6和图7分别显示了“build.xml”和“build.properties”的示例。

   <?xml version="1.0"?>
   <project name="NetconfService" default="all" basedir=".">
           <property file="build.properties"/>
           <path id="axis-classpath">
                   <fileset dir="${axis.libdir}">
                           <include name="*.jar"/>
                   </fileset>
           </path>
           <target name="prepare">
                   <mkdir dir="${srcdir}"/>
                   <mkdir dir="${destdir}"/>
           </target>
           <target name="skeleton" depends="prepare">
                   <java classname="org.apache.axis.wsdl.WSDL2Java" fork
                           ="Yes">
                           <arg value="-p"/>
                           <arg value="${skeletondir}"/>
                           <arg value="-o"/>
                           <arg value="${srcdir}"/>
                           <arg value="-s"/>
                           <arg value="-S"/>
                           <arg value="true"/>
                           <arg value="-d"/>
                           <arg value="Session"/>
                           <arg value="${wsdlpath}"/>
                           <classpath refid="axis-classpath"/>
                   </java>
           </target>
           <target name="compile" depends="skeleton">
                   <javac srcdir="${srcdir}" destdir="${destdir}"
                           encoding="UTF-8">
                           <classpath refid="axis-classpath"/>
                   </javac>
           </target>
           <target name="copy2axis" depends="compile">
                   <copy todir="${tomcat.axis.classesdir}" overwrite=
                           "true">
                           <fileset dir="${destdir}">
                                   <include name="*.class"/>
                                   <include name="*/*.class"/>
                                   <include name="*/*/*.class"/>
                           </fileset>
                   </copy>
           </target>
           <target name="deploy" depends="copy2axis">
                   <java classname="org.apache.axis.client.AdminClient"
                           fork="Yes">
                           <arg value="-p"/>
        
   <?xml version="1.0"?>
   <project name="NetconfService" default="all" basedir=".">
           <property file="build.properties"/>
           <path id="axis-classpath">
                   <fileset dir="${axis.libdir}">
                           <include name="*.jar"/>
                   </fileset>
           </path>
           <target name="prepare">
                   <mkdir dir="${srcdir}"/>
                   <mkdir dir="${destdir}"/>
           </target>
           <target name="skeleton" depends="prepare">
                   <java classname="org.apache.axis.wsdl.WSDL2Java" fork
                           ="Yes">
                           <arg value="-p"/>
                           <arg value="${skeletondir}"/>
                           <arg value="-o"/>
                           <arg value="${srcdir}"/>
                           <arg value="-s"/>
                           <arg value="-S"/>
                           <arg value="true"/>
                           <arg value="-d"/>
                           <arg value="Session"/>
                           <arg value="${wsdlpath}"/>
                           <classpath refid="axis-classpath"/>
                   </java>
           </target>
           <target name="compile" depends="skeleton">
                   <javac srcdir="${srcdir}" destdir="${destdir}"
                           encoding="UTF-8">
                           <classpath refid="axis-classpath"/>
                   </javac>
           </target>
           <target name="copy2axis" depends="compile">
                   <copy todir="${tomcat.axis.classesdir}" overwrite=
                           "true">
                           <fileset dir="${destdir}">
                                   <include name="*.class"/>
                                   <include name="*/*.class"/>
                                   <include name="*/*/*.class"/>
                           </fileset>
                   </copy>
           </target>
           <target name="deploy" depends="copy2axis">
                   <java classname="org.apache.axis.client.AdminClient"
                           fork="Yes">
                           <arg value="-p"/>
        
                           <arg value="${deploy.port}"/>
                           <arg value="${deploy.ddname}"/>
                           <classpath refid="axis-classpath"/>
                   </java>
           </target>
           <target name="all" depends="deploy"/>
   </project>
        
                           <arg value="${deploy.port}"/>
                           <arg value="${deploy.ddname}"/>
                           <classpath refid="axis-classpath"/>
                   </java>
           </target>
           <target name="all" depends="deploy"/>
   </project>
        

Figure 6: build.xml of NETCONF Servers

图6:NETCONF服务器的build.xml

   axis.libdir=C:/axis-1_4/lib
   tomcat.axis.classesdir=
   C:/Program Files/Apache Software Foundation/Tomcat 6.0/
   webapps/axis/WEB-INF/classes
   srcdir=src
   destdir=classes
   skeletondir=skeleton
   wsdlpath=myNetconfService.wsdl
   deploy.port=832
   deploy.ddname=src/skeleton/deploy.wsdd
        
   axis.libdir=C:/axis-1_4/lib
   tomcat.axis.classesdir=
   C:/Program Files/Apache Software Foundation/Tomcat 6.0/
   webapps/axis/WEB-INF/classes
   srcdir=src
   destdir=classes
   skeletondir=skeleton
   wsdlpath=myNetconfService.wsdl
   deploy.port=832
   deploy.ddname=src/skeleton/deploy.wsdd
        

Figure 7: build.properties of NETCONF Servers

图7:NETCONF服务器的build.properties

The locations of the WSDL file and "deploy.wsdd" file have to be specified in the "build.properties" file. In Figure 7, the location of the WSDL file and "deploy.wsdd" file are specified as being under the current directory.

WSDL文件和“deploy.wsdd”文件的位置必须在“build.properties”文件中指定。在图7中,WSDL文件和“deploy.wsdd”文件的位置被指定为位于当前目录下。

By running Apache Ant on Eclipse, the steps shown in Figure 6 are followed. First, skeleton codes have to be generated. After the skeleton codes are generated, source codes of the NETCONF server functions may be added to the skeleton codes according to the functions that developers intend to add.

通过在Eclipse上运行ApacheAnt,遵循图6所示的步骤。首先,必须生成骨架代码。生成骨架代码后,可以根据开发人员打算添加的功能将NETCONF服务器功能的源代码添加到骨架代码中。

Then, by running Apache Ant again, compiling of the skeleton codes is executed. As a result, class files of the NETCONF server are generated. Apache Ant copies these class files to the directory of Tomcat and deploys the NETCONF server. After that, the NETCONF server becomes accessible by the NETCONF client.

然后,通过再次运行ApacheAnt,执行骨架代码的编译。因此,将生成NETCONF服务器的类文件。ApacheAnt将这些类文件复制到Tomcat目录并部署NETCONF服务器。之后,NETCONF客户端可以访问NETCONF服务器。

4.2.3. Developing NETCONF Servers with C Programming Language
4.2.3. 用C语言开发NETCONF服务器

When the NETCONF server for network equipment is being implemented, memory capacity might be limited, so it might not be possible to install a Java environment on the network equipment. The network-equipment platform might not support a Web Services tool. In that case, it may be necessary to implement SOAP as well as the NETCONF server by using C programming language on the network equipment.

在实现网络设备的NETCONF服务器时,内存容量可能会受到限制,因此可能无法在网络设备上安装Java环境。网络设备平台可能不支持Web服务工具。在这种情况下,可能需要在网络设备上使用C编程语言实现SOAP和NETCONF服务器。

To develop a NETCONF server capable of receiving NETCONF messages sent over SOAP/HTTP, the network equipment may have an HTTP daemon and a NETCONF service provider. A commonly used HTTP daemon can be used. A SOAP module may be added to the HTTP daemon as a connector between the HTTP daemon and the NETCONF service provider. The NETCONF service provider for parsing NETCONF messages sent from the NETCONF client and sending reply NETCONF messages toward the NETCONF client may be developed.

为了开发能够接收通过SOAP/HTTP发送的NETCONF消息的NETCONF服务器,网络设备可以具有HTTP守护程序和NETCONF服务提供者。可以使用常用的HTTP守护进程。SOAP模块可以作为HTTP守护程序和NETCONF服务提供程序之间的连接器添加到HTTP守护程序。可以开发用于解析从NETCONF客户端发送的NETCONF消息并向NETCONF客户端发送回复NETCONF消息的NETCONF服务提供商。

When an HTTP daemon receives a SOAP message that is sent over HTTP, the message is handed over to the SOAP module incorporated in the HTTP daemon. Then, the SOAP module removes the SOAP header and passes NETCONF messages to the NETCONF service provider. After that, the NETCONF service provider parses the NETCONF messages and configures the network equipment accordingly.

当HTTP守护进程接收到通过HTTP发送的SOAP消息时,该消息将移交给HTTP守护进程中包含的SOAP模块。然后,SOAP模块删除SOAP头并将NETCONF消息传递给NETCONF服务提供者。然后,NETCONF服务提供商解析NETCONF消息并相应地配置网络设备。

5. Security Considerations
5. 安全考虑

The security considerations of [RFC4741] and [RFC4743] are applicable in this document. Implementers or users of SOAP-based NETCONF clients and servers should take these considerations into account.

[RFC4741]和[RFC4743]的安全注意事项适用于本文件。基于SOAP的NETCONF客户端和服务器的实现者或用户应该考虑这些因素。

As specified in the security considerations section of [RFC4743], transport-level security, such as authentication of users and encryption of transport protocol, has to be ensured by TLS (Transport Layer Security) in the case of NETCONF SOAP binding. That is, security has to be provided in the form of NETCONF/SOAP/HTTPS.

如[RFC4743]的“安全注意事项”部分所述,在NETCONF SOAP绑定的情况下,必须通过TLS(传输层安全)确保传输级安全性,如用户身份验证和传输协议加密。也就是说,必须以NETCONF/SOAP/HTTPS的形式提供安全性。

6. Acknowledgements
6. 致谢

Extensive input was received from the members of the NETCONF design team, including: Andy Bierman, Simon Leinen, Bert Wijnen, Mehmet Ersue, Ted Goddard, Ray Atarashi, Ron Bonica, and Dan Romascanu. The following people have also reviewed this document and provided valuable input: Jari Arkko, Pasi Eronen, Chris Newman, Tim Polk, David Ward, Magnus Westerlund, and Christian Vogt.

NETCONF设计团队成员提供了广泛的意见,包括:Andy Bierman、Simon Leinen、Bert Wijnen、Mehmet Ersue、Ted Goddard、Ray Atarashi、Ron Bonica和Dan Romascanu。以下人员也对本文件进行了审查,并提供了宝贵的意见:贾里·阿尔科、帕西·埃隆、克里斯·纽曼、蒂姆·波尔克、大卫·沃德、马格纳斯·韦斯特隆德和克里斯蒂安·沃格特。

7. References
7. 工具书类
7.1. Normative References
7.1. 规范性引用文件

[RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006.

[RFC4741]Enns,R.,“网络配置协议”,RFC 47412006年12月。

[RFC4743] Goddard, T., "Using NETCONF over the Simple Object Access Protocol (SOAP)", RFC 4743, December 2006.

[RFC4743]Goddard,T.,“通过简单对象访问协议(SOAP)使用NETCONF”,RFC 4743,2006年12月。

7.2. Informative References
7.2. 资料性引用
   [Ant]       "Apache Ant".
               <http://ant.apache.org/>
        
   [Ant]       "Apache Ant".
               <http://ant.apache.org/>
        
   [Axis]      "Web Services - Axis".
               <http://ws.apache.org/axis/>
        
   [Axis]      "Web Services - Axis".
               <http://ws.apache.org/axis/>
        
   [Eclipse]   "Eclipse".
               <http://www.eclipse.org/>
        
   [Eclipse]   "Eclipse".
               <http://www.eclipse.org/>
        
   [JDK]       "Java SE".
               <http://java.sun.com/javase/index.jsp>
        
   [JDK]       "Java SE".
               <http://java.sun.com/javase/index.jsp>
        
   [NetBeans]  "NetBeans".
               <http://www.netbeans.org/index.html>
        
   [NetBeans]  "NetBeans".
               <http://www.netbeans.org/index.html>
        

[RFC4742] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration Protocol over Secure SHell (SSH)", RFC 4742, December 2006.

[RFC4742]Wasserman,M.和T.Goddard,“在安全外壳(SSH)上使用NETCONF配置协议”,RFC 4742,2006年12月。

[RFC4744] Lear, E. and K. Crozier, "Using the NETCONF Protocol over the Blocks Extensible Exchange Protocol (BEEP)", RFC 4744, December 2006.

[RFC4744]Lear,E.和K.Crozier,“在块可扩展交换协议(BEEP)上使用NETCONF协议”,RFC 47442006年12月。

   [Tomcat]    "Apache Tomcat".
               <http://tomcat.apache.org/>
        
   [Tomcat]    "Apache Tomcat".
               <http://tomcat.apache.org/>
        
   [WSDL]      "Web Service Description Language (WSDL) 1.1".
               <http://www.w3.org/TR/wsdl>
        
   [WSDL]      "Web Service Description Language (WSDL) 1.1".
               <http://www.w3.org/TR/wsdl>
        

Authors' Addresses

作者地址

Iijima Tomoyuki Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan

Iijima Tomoyuki Alaxala Networks Corp.新川崎三井大厦890号Kanagawa ku Kashimada Kawasaki,日本神奈川212-0058

   Phone: +81-44-549-1735
   Fax:   +81-44-549-1272
   EMail: tomoyuki.iijima@alaxala.com
        
   Phone: +81-44-549-1735
   Fax:   +81-44-549-1272
   EMail: tomoyuki.iijima@alaxala.com
        

Yoshifumi Atarashi Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan

日本神奈川Kashimada Kawaki Saiwai ku Kashimada Kawasaki 890号新川崎三井大厦Yoshifumi Atarashi Alaxala网络公司212-0058

   Phone: +81-44-549-1735
   Fax:   +81-44-549-1272
   EMail: atarashi@alaxala.net
        
   Phone: +81-44-549-1735
   Fax:   +81-44-549-1272
   EMail: atarashi@alaxala.net
        

Hiroyasu Kimura Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan

Hiroyasu Kimura Alaxala Networks Corp.新川崎三井大厦890号Kanagawa ku Kashimada Kawasaki,日本神奈川212-0058

   Phone: +81-44-549-1735
   Fax:   +81-44-549-1272
   EMail: h-kimura@alaxala.net
        
   Phone: +81-44-549-1735
   Fax:   +81-44-549-1272
   EMail: h-kimura@alaxala.net
        

Makoto Kitani Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan

Makoto Kitani Alaxala Networks Corp.新川崎三井大厦890号Kashimada Kawasaki,神奈川212-0058

   Phone: +81-44-549-1735
   Fax:   +81-44-549-1272
   EMail: makoto.kitani@alaxala.com
        
   Phone: +81-44-549-1735
   Fax:   +81-44-549-1272
   EMail: makoto.kitani@alaxala.com
        

Hideki Okita Hitachi, Ltd. 1-280 Higashi-Koigakubo Kokubunji, Tokyo 185-8601 Japan

大田英机日立株式会社1-280日本东京东小谷博小谷本次185-8601

   Phone: +81-42-323-1111
   Fax:   +81-42-327-7868
   EMail: hideki.okita.pf@hitachi.com
        
   Phone: +81-42-323-1111
   Fax:   +81-42-327-7868
   EMail: hideki.okita.pf@hitachi.com
        

Full Copyright Statement

完整版权声明

Copyright (C) The IETF Trust (2008).

版权所有(C)IETF信托基金(2008年)。

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

本文件受BCP 78中包含的权利、许可和限制的约束,除其中规定外,作者保留其所有权利。

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

本文件及其包含的信息以“原样”为基础提供,贡献者、他/她所代表或赞助的组织(如有)、互联网协会、IETF信托基金和互联网工程任务组不承担任何明示或暗示的担保,包括但不限于任何保证,即使用本文中的信息不会侵犯任何权利,或对适销性或特定用途适用性的任何默示保证。

Intellectual Property

知识产权

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

IETF对可能声称与本文件所述技术的实施或使用有关的任何知识产权或其他权利的有效性或范围,或此类权利下的任何许可可能或可能不可用的程度,不采取任何立场;它也不表示它已作出任何独立努力来确定任何此类权利。有关RFC文件中权利的程序信息,请参见BCP 78和BCP 79。

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

向IETF秘书处披露的知识产权副本和任何许可证保证,或本规范实施者或用户试图获得使用此类专有权利的一般许可证或许可的结果,可从IETF在线知识产权存储库获取,网址为http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.

IETF邀请任何相关方提请其注意任何版权、专利或专利申请,或其他可能涵盖实施本标准所需技术的专有权利。请将信息发送至IETF的IETF-ipr@ietf.org.