diff options
Diffstat (limited to 'doc/rfc/rfc5381.txt')
| -rw-r--r-- | doc/rfc/rfc5381.txt | 1235 |
1 files changed, 1235 insertions, 0 deletions
diff --git a/doc/rfc/rfc5381.txt b/doc/rfc/rfc5381.txt new file mode 100644 index 0000000..47e0306 --- /dev/null +++ b/doc/rfc/rfc5381.txt @@ -0,0 +1,1235 @@ + + + + + + +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 + +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 + + 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. + +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. + + + + + + + + + +Iijima, et al. Informational [Page 1] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + +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 + + + + + + + + + + + + + + + + + + + + + + +Iijima, et al. Informational [Page 2] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 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 can 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 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. + +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 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. + + 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. + + + + + + + + + +Iijima, et al. Informational [Page 3] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 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, a + network configuration performed by NETCONF is achieved on the Web + Services framework. In this section, the overall architecture of Web + Services is described. + + +----------------+ +----------------------------+ + | 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 + + 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. + + + + + + + + + + + + +Iijima, et al. Informational [Page 4] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + +2.1. WSDL as an Interface Description Language + + 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. + + 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. + +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. + +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 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. + + + + + + + + + + + + + + + + +Iijima, et al. Informational [Page 5] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + +---------------------------+ +---------------------------+ + | 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. + +3.1. SOAP Implementation in NMS + + Several SOAP implementations appropriate for use in an NMS are + available today. Apache Axis is one such widely used implementation. + + 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. + + 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. + + + + + + + +Iijima, et al. Informational [Page 6] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + +3.1.1. SOAP Parser in NMS + + The SOAP Parser function is performed entirely 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, a NETCONF session has to be maintained on both sides, as + described in [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. + + 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. + + + + + + +Iijima, et al. Informational [Page 7] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + +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 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. + +3.2.1. SOAP Parser in the Network Equipment + + 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 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]. + + 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. + +4. Guidelines for Developing NETCONF Clients and Servers + + 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. + + + + +Iijima, et al. Informational [Page 8] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + +4.1. Procedures of Development of NETCONF Clients + + 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. + + 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 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]. + + 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]. + + <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. + + + + + +Iijima, et al. Informational [Page 9] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + 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. + +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 that + "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 + + 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. + + + + +Iijima, et al. Informational [Page 10] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + 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 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. + +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 one + time. In this case, files named "build.xml" and "build.properties" + are required for Apache Ant. + + + + +Iijima, et al. Informational [Page 11] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + 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. + + Examples of "build.xml" and "build.properties" are shown in Figure 4 + and Figure 5, respectively. + + <?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 + + + + + +Iijima, et al. Informational [Page 12] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + 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 + + 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. + + 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. + + 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 in compliance with + the WSDL file. + + + + + +Iijima, et al. Informational [Page 13] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + 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. + + 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. + + 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". + + 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. + +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 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 + + + +Iijima, et al. Informational [Page 14] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + 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. + + 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. + + 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. + + 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. + +4.2.2. Developing NETCONF Servers Using Eclipse + + 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. + + + + + + + + + + +Iijima, et al. Informational [Page 15] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + <?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"/> + + + +Iijima, et al. Informational [Page 16] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + + <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 + + 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 may be added to the skeleton codes according to the + functions that developers intend to add. + + 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. + + + + + + + + + + + + +Iijima, et al. Informational [Page 17] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 2008 + + +4.2.3. Developing NETCONF Servers with C Programming Language + + 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. + + 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. + + 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. + +5. Security Considerations + + 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. + + 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. + +6. Acknowledgements + + 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. + + + + + + +Iijima, et al. Informational [Page 18] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 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". + <http://ant.apache.org/> + + [Axis] "Web Services - Axis". + <http://ws.apache.org/axis/> + + [Eclipse] "Eclipse". + <http://www.eclipse.org/> + + [JDK] "Java SE". + <http://java.sun.com/javase/index.jsp> + + [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. + + [RFC4744] Lear, E. and K. Crozier, "Using the NETCONF Protocol over + the Blocks Extensible Exchange Protocol (BEEP)", + RFC 4744, December 2006. + + [Tomcat] "Apache Tomcat". + <http://tomcat.apache.org/> + + [WSDL] "Web Service Description Language (WSDL) 1.1". + <http://www.w3.org/TR/wsdl> + + + + + + + + + + + +Iijima, et al. Informational [Page 19] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 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. Informational [Page 20] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 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. Informational [Page 21] + +RFC 5381 Experience of Implementing NETCONF/SOAP October 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. Informational [Page 22] + |