Network Working Group T. Iijima Internet-Draft Y. Atarashi Intended status: Informational H. Kimura Expires: October 23, 2008 M. Kitani Alaxala Networks Corp. H. Okita Hitachi, Ltd. April 21, 2008 Experience of implementing NETCONF over SOAP draft-iijima-netconf-soap-implementation-07 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on October 23, 2008. Iijima, et al. Expires October 23, 2008 [Page 1] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 Abstract This document describes how the authors developed a SOAP (Simple Object Access Protocol)-based NETCONF client and server. In the case that 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. 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 . . . . . . . . 4 2.2. Generation of APIs . . . . . . . . . . . . . . . . . . . . 5 3. Architecture of the NETCONF over SOAP Implementation . . . . . 6 3.1. SOAP Implementation in NMS . . . . . . . . . . . . . . . . 7 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 . . . . 9 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 . . . . . . . 12 4.2. Procedures of Development of NETCONF Servers . . . . . . . 14 4.2.1. Developing NETCONF Servers without Eclipse . . . . . . 15 4.2.2. Developing NETCONF Servers using Eclipse . . . . . . . 16 4.2.3. Developing NETCONF Servers by C Language Programming . . . . . . . . . . . . . . . . . . . . . 18 5. Security Considerations . . . . . . . . . . . . . . . . . . . 20 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 7.1. Normative References . . . . . . . . . . . . . . . . . . . 22 7.2. Informative References . . . . . . . . . . . . . . . . . . 22 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 Intellectual Property and Copyright Statements . . . . . . . . . . 25 Iijima, et al. Expires October 23, 2008 [Page 2] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 1. Introduction 1.1. NETCONF over SOAP This document is not a product from the NETCONF WG but a report on the experience acquired by individual developers. 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 could be deployed widely. 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 Interface) that are automatically generated from the XSD 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). And the SOAP- based NETCONF server that the authors developed runs on network equipment and accepts NETCONF messages sent from the NETCONF client. 1.2. Motivation 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 could be used according to 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. Iijima, et al. Expires October 23, 2008 [Page 3] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 2. NETCONF Development on Web Services Framework SOAP is a fundamental messaging technology for Web Services. Therefore, if SOAP is used as a transport protocol for NETCONF, network configuration performed by NETCONF is achieved on the Web Services framework. In this section, the overall architecture of Web Services is described. +---+ +----------+ +-----------+ +-------------+ +--------+ |XML| | Security | | Reliable | | Transaction | | Search | | | | | | Message | | | | | | | | | | | | | | UDDI |22 | | | WS- | | WS- | | WS- | +--------+ | | | Security | |Reliability| | Transaction | +--------+ +-------+ | | | | | | | | |Language| | API | | | | | | | | | | | | | | | | | | | | | | WSDL | | JAXM | | | +----------+ +-----------+ +-------------+ +--------+ |JAX-RPC| | | +---------------------------------------------------+ | .NET | | | | Fundamental Messaging | | | | | | | | | | | | SOAP | | | +---+ +---------------------------------------------------+ +-------+ +---------------------------------------------------+ | Transport | | | | HTTP, HTTPS... | +---------------------------------------------------+ Figure 1: Overall architecture of Web Services 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, each surrounding technology does not have to be developed from scratch. Hence, the development of a NETCONF-based NMS is relatively easy when SOAP is chosen as a transport protocol for NETCONF. 2.1. WSDL as an Interface Description Language WSDL [WSDL] defines how SOAP messages are exchanged among 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. Iijima, et al. Expires October 23, 2008 [Page 4] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 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 acts as a widely used SOAP implementation middleware. 2.2. Generation of APIs 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. Iijima, et al. Expires October 23, 2008 [Page 5] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 3. Architecture of the NETCONF over SOAP Implementation 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 needs to be installed on both, NMS and 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. +---------------------------+ +---------------------------+ | 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. Iijima, et al. Expires October 23, 2008 [Page 6] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 3.1. SOAP Implementation in NMS Several SOAP implementations capable for an NMS are available today. As one such free SOAP implementation, Apache Axis is the widely used. Axis works as a SOAP implementation and an NMS-development tool. For instance, WSDL2Java, one of Axis's 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 kinds of benefits can be acquired if Axis is introduced as a SOAP implementation. To develop a NETCONF application that is capable of various functions such as releasing log messages, Java-class files generated by the Axis tool need to be extended by adding more functions. By utilizing these Java libraries, engineers can easily develop NETCONF applications. 3.1.1. SOAP Parser in NMS The SOAP Parser function is completely performed by a SOAP implementation such as Apache Axis. 3.1.2. Session Maintenance in NMS When exchanging NETCONF messages between an NMS and network equipment, implementation of a session-maintenance function is necessary on both sides. HTTP is a stateless protocol that is used as an underlying transport protocol for SOAP. HTTP creates and terminates a TCP session at every request. Therefore, when using HTTP as a transport protocol for SOAP messages, session maintenance at the TCP level as well as at the NETCONF level is necessary. Unless a session is maintained at the TCP level, a different NETCONF service provider is invoked every time the NETCONF client sends a NETCONF message to the NETCONF server. We used a cookie field inside a HTTP header as a session identifier for the session on TCP level. The session-maintenance function at the TCP level has to be incorporated as follows. After the NETCONF application sends a NETCONF hello message to a NETCONF service provider, the application receives a newly allocated session identifier written in the cookie field of a replying hello message. The NETCONF application preserves the cookie paired with the network equipment's MAC address and uses it as a session identifier for subsequent NETCONF message exchanges. When an NMS sets the cookie for subsequent NETCONF messages, the network equipment recognizes the session and maintains it. The Iijima, et al. Expires October 23, 2008 [Page 7] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 stored cookie is erased when the NMS sends a close-session message and a response message is received from the network equipment. 3.2. SOAP Implementation in the Network Equipment To accept SOAP messages sent from the NMS, it is also necessary to provide SOAP in the network equipment. As in the case of the NMS, some free SOAP implementations to be installed on network equipment are available today. However, in the case of network equipment, the capacity of the memory might be limited. Therefore, a SOAP implementation has to be chosen while memory capacity is taken into consideration. In some cases, a memory-saving method will be required when implementing SOAP in the network equipment. 3.2.1. SOAP Parser in the Network Equipment When using HTTP as an underlying protocol of SOAP, a SOAP message consists of an HTTP header and a SOAP envelope. The SOAP envelope is a mandatory part of every SOAP message. However, the SOAP encodingStyle attribute inside the envelope elements does not need to be specified. If the encodingStyle attribute is not specified, the default of "http://schemas.xmlsoap.org/soap/encoding" is applied. If there is a memory constraint, we can omit a parsing function of the encodingStyle attribute. Similarly, 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. 3.2.2. Session Maintenance in the Network Equipment To maintain sessions with the NMS, the SOAP implementation in network equipment must provide a session identifier to the NMS. The session-maintenance function that we implemented works as follows. When network equipment receives a NETCONF hello message from the NMS, the SOAP implementation in the network equipment sets a session identifier paired with the network equipment's MAC address in the cookie field inside the HTTP header and sends a response message to the network equipment. When the network equipment receives a NETCONF close message from the NMS, it erases the stored session identifier. Iijima, et al. Expires October 23, 2008 [Page 8] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 4. Guidelines for Developing NETCONF Clients and Servers In the case of SOAP transport mapping, sharing what kinds of development tools 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. 4.1. Procedures of Development of NETCONF Clients To develop a SOAP-based NETCONF client, a stub code needs to be generated. A stub is a library generated automatically from WSDL by a Web Services tool and acts as a group of APIs. In the case of 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. 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. 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". 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". When interfaces are used to configure network functions at network equipment, a data model of each network function has to be defined in the style of an XML schema. The XML schema is required to be imported into "netconf-soap_1.0.wsdl" in the same manner as that of the XML schema in [RFC4741]. 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]. Iijima, et al. Expires October 23, 2008 [Page 9] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 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. When stub codes are generated, the development environment needs to be arranged as well. The development of a Java-based NETCONF client needs 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. 4.1.1. Developing NETCONF Clients without Eclipse Given that development of a NETCONF client is carried out in the environment of a Windows computer without Eclipse and "myNetconfService.wsdl" is placed in the "C:\NetconfClient" directory, a stub is generated by executing the following command in the command prompt. 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". 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 Iijima, et al. Expires October 23, 2008 [Page 10] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 After the compilation of those java files, "*.class" files are generated. At the time of compiling, we need to be careful about the encoding style. 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. 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); 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(); } } } Figure 3: Sample source code of NETCONF clients To add functions such as release of log messages, these functions Iijima, et al. Expires October 23, 2008 [Page 11] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 have to be incorporated at this stage. Again, the NETCONF client is developed by compiling its source codes. 4.1.2. Developing NETCONF Clients using Eclipse When we use Eclipse and Apache Ant, the procedures described in the previous section are significantly simplified and executed at once. In this case, files named "build.xml" and "build.properties" are required for Apache Ant. 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. And the file is referred to by the "build.xml" file. Examples of "build.xml" and "build.properties" are shown in Figure 4 and Figure 5, respectively. Iijima, et al. Expires October 23, 2008 [Page 12] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 Figure 4: build.xml of NETCONF clients 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 Iijima, et al. Expires October 23, 2008 [Page 13] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 The location of the WSDL file has to 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. By running Apache Ant on Eclipse, the steps specified in Figure 4 are taken. First, stub codes are generated. Then, compiling those stub codes is executed. 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. 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. 4.2. Procedures of Development of NETCONF Servers 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 compliant with the WSDL file. 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 case of the bottom-up approach, ensuring interoperability becomes difficult, since implementation of a Web Services becomes vendor specific. In the case of 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 the Iijima, et al. Expires October 23, 2008 [Page 14] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 section describes the top-down approach for developing a NETCONF server. 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. In the case of 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 being used for generating the stub code, skeleton codes are generated in files such as "NetconfBindingSkeleton.java", "Hello.java", and "GetConfigType.java". When skeleton codes are being generated, the development environment needs to 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. 4.2.1. Developing NETCONF Servers without Eclipse 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. 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 have to be specified. The environment variable of "AXIS_HOME" is a directory where Axis is installed. By executing the above command, files with an extension 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 undeploying a NETCONF server from a servlet container, respectively. Adding source codes of NETCONF server functions to skeleton codes such as "NetconfBindingImpl.java" is required as the need arises. Iijima, et al. Expires October 23, 2008 [Page 15] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 Functions such as 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. 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. Copying these class files into the directory "webapps\axis\WEB- INFO\classes" of the Apache Tomcat directory is required. Finally, deploying the NETCONF server by executing the following command is required. 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 as the skeleton code is generated. After deployment, the NETCONF server receives NETCONF messages sent from the NETCONF client. 4.2.2. Developing NETCONF Servers using Eclipse When Eclipse and Apache Ant are used, the procedures followed 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. Iijima, et al. Expires October 23, 2008 [Page 16] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 Figure 6: build.xml of NETCONF servers Iijima, et al. Expires October 23, 2008 [Page 17] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 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 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. 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 must be added to the skeleton codes according to the function that developers intend to add. Then, by running Apache Ant again, compiling 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 from the NETCONF client. The NETCONF server is developed in this manner. 4.2.3. Developing NETCONF Servers by C Language Programming When the NETCONF server for network equipment is being implemented, memory capacity might be limited, so installing a Java environment on the network equipment might not be attainable. 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 on the network equipment. To develop a NETCONF server capable of receiving NETCONF messages sent over SOAP/HTTP, the network equipment needs a HTTP daemon and a NETCONF service provider. A commonly used HTTP daemon can be used. A SOAP module needs to 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 Iijima, et al. Expires October 23, 2008 [Page 18] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 client has to be developed. 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. Iijima, et al. Expires October 23, 2008 [Page 19] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 5. Security Considerations The security considerations of [RFC4741] and [RFC4743] are applicable to this document. Implementers or users of SOAP-based NETCONF clients and servers should take these considerations into account. 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. Iijima, et al. Expires October 23, 2008 [Page 20] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 6. IANA Considerations This document has no actions for IANA. Iijima, et al. Expires October 23, 2008 [Page 21] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 7. References 7.1. Normative References [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [RFC4743] Goddard, T., "Using NETCONF over the Simple Object Access Protocol (SOAP)", RFC 4743, December 2006. 7.2. Informative References [Ant] "Apache Ant" . [Axis] "Web Services - Axis". [Eclipse] "Eclipse". [JDK] "Java SE". [NetBeans] "NetBeans". [Tomcat] "Apache Tomcat". [WSDL] "Web Service Description Language (WSDL) 1.1". Iijima, et al. Expires October 23, 2008 [Page 22] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 Authors' Addresses Iijima Tomoyuki Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan 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 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 Phone: +81-44-549-1735 Fax: +81-44-549-1272 Email: h-kimura@alaxala.net Iijima, et al. Expires October 23, 2008 [Page 23] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 Makoto Kitani Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan 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 Phone: +81-42-323-1111 Fax: +81-42-327-7868 Email: hideki.okita.pf@hitachi.com Iijima, et al. Expires October 23, 2008 [Page 24] Internet-Draft Experience of implementing NETCONF/SOAP April 2008 Full Copyright Statement Copyright (C) The IETF Trust (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. 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. 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. 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. 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. Iijima, et al. Expires October 23, 2008 [Page 25]