Network Working Group T. Iijima
Internet-Draft Y. Atarashi
Intended status: Informational H. Kimura
Expires: August 24, 2008 M. Kitani
Alaxala Networks Corp.
H. Okita
Central Research Laboratory,
Hitachi, Ltd.
February 21, 2008
Experience of implementing NETCONF over SOAP
draft-iijima-netconf-soap-implementation-06
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 August 24, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2008).
Iijima, et al. Expires August 24, 2008 [Page 1]
Internet-Draft SOAP implementation February 2008
Abstract
This document describes how we developed a SOAP-based NETCONF client
and server. In the case of using SOAP as a transport protocol of
NETCONF, various kinds of development tools are available. By making
full use of those tools, developers' workloads are significantly
reduced. We developed an NMS (Network Management System) and network
equipment that can deal with NETCONF messages sent over SOAP. This
document is aimed at providing knowledge about development guidelines
gained from the implementation experience of a SOAP-based NETCONF
client and server.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. NETCONF over SOAP . . . . . . . . . . . . . . . . . . . . 3
1.2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 3
1.3. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 3
2. NETCONF Development on the Web Service Framework . . . . . . . 4
2.1. WSDL as an Interface Description Language . . . . . . . . 4
2.2. API as Programming Interface . . . . . . . . . . . . . . . 5
3. Architecture of 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 Network Equipment . . . . . . . . . 8
3.2.1. SOAP Parser in Network Equipment . . . . . . . . . . . 8
3.2.2. Session Maintenance in Network Equipment . . . . . . . 8
4. Guidelines of Developing NETCONF Client and Server . . . . . . 9
4.1. Procedures of Development of NETCONF Client . . . . . . . 9
4.1.1. Developing NETCONF Client without Eclipse . . . . . . 10
4.1.2. Developing NETCONF Client with Eclipse . . . . . . . . 12
4.2. Procedures of Development of NETCONF Server . . . . . . . 13
4.2.1. Developing NETCONF Server without Eclipse . . . . . . 14
4.2.2. Developing NETCONF Server using Eclipse . . . . . . . 15
4.2.3. Developing NETCONF Server by C Language Programming . 17
5. Security Considerations . . . . . . . . . . . . . . . . . . . 19
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.1. Normative References . . . . . . . . . . . . . . . . . . . 21
7.2. Informative References . . . . . . . . . . . . . . . . . . 21
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22
Intellectual Property and Copyright Statements . . . . . . . . . . 24
Iijima, et al. Expires August 24, 2008 [Page 2]
Internet-Draft SOAP implementation February 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 was specified in RFC4743[2] as one of the transport protocols of
NETCONF. SOAP is designed to use XML as its description language,
which is a fundamental messaging technology of Web Service. For this
reason, SOAP is well suited to the NETCONF protocol and could be
deployed widely.
In the case of developing a SOAP-based NETCONF client and server,
several development tools are available. We developed a SOAP-based
NETCONF client and server by using those development tools. In this
document, we provide information about our experience and guidelines
of how to develop a NETCONF client and server so that even those who
have little knowledge about SOAP can start developing a SOAP-based
NETCONF client and server.
The SOAP-based NETCONF client that we developed acts as an NMS. The
client is developed by utilizing Java APIs that are automatically
generated from the XSD file and WSDL file obtained from RFC4741[1]
and RFC4743[2], respectively. The SOAP-based NETCONF server that we
developed runs on network equipment and accepts NETCONF messages sent
from the NETCONF client.
1.2. Conventions
The key words "must", "must not", "required", "shall", "shall not",
"should", "should not", "recommended", "may", and "optional" in this
document are to be interpreted as described in RFC2119 [3].
1.3. Motivation
This document describes why the authors believe SOAP is practical as
a transport protocol of NETCONF in developing an NMS. This document
also describes the experience of implementing NETCONF over SOAP so
that even those who have little knowledge about SOAP can start
developing a SOAP-based NETCONF client and server.
Iijima, et al. Expires August 24, 2008 [Page 3]
Internet-Draft SOAP implementation February 2008
2. NETCONF Development on the Web Service Framework
SOAP is a fundamental messaging technology of Web Service.
Therefore, if we use SOAP as a transport protocol of NETCONF, network
configuration performed by NETCONF is achieved on the Web Service
framework. In this section, we describe the overall architecture of
Web Service.
+---+ +----------+ +-----------+ +-------------+ +--------+
|XML| | Security | | Reliable | | Transaction | | Search |
| | | | | Message | | | | |
| | | | | | | | | UDDI |
| | | 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 Service
As depicted in Figure 1, peripheral technologies around SOAP/HTTP are
well developed. Therefore, if we choose SOAP/HTTP as a transport
layer of the NETCONF protocol, we do not have to develop each
surrounding technology from scratch. Hence, the development of a
NETCONF-based NMS is relatively easy when we choose SOAP as a
transport protocol of NETCONF.
2.1. WSDL as an Interface Description Language
WSDL (Web Service Description Language)[4] is defining how SOAP
messages are exchanged among Web Service entities. Interfaces of Web
Service entities are automatically generated by development tools
when importing a WSDL file. Interfaces of Web Service entities
generated in this manner act as APIs (Application Programming
Interface). Developers only need these APIs when developing an NMS,
Iijima, et al. Expires August 24, 2008 [Page 4]
Internet-Draft SOAP implementation February 2008
but SOAP is not needed.
Useful development tools that can import a WSDL file are available
with SOAP. For instance, Apache Axis[5] will generate an interface
from a WSDL file and act as a widely used SOAP implementation
middleware.
2.2. API as Programming Interface
As described in the previous section, APIs are generated from a WSDL
file by development tools such as Apache Axis. APIs generated by
Apache Axis are in the form of a Java library and act as programming
interfaces for a NMS. The NMS developed using those APIs can send
SOAP messages to Web Service entities.
Iijima, et al. Expires August 24, 2008 [Page 5]
Internet-Draft SOAP implementation February 2008
3. Architecture of NETCONF over SOAP Implementation
In this section, we describe the architecture of the NETCONF
implementation using SOAP as its transport protocol. 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 NETCONF service provider,
respectively. A SOAP implementation needs to be installed on both an
NMS and network equipment. Each instance of the SOAP implementations
exchanges SOAP messages based on the WSDL, as described in
RFC4743[2]. 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 write directly
in XML or 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
In the following section, we explain the SOAP implementation in
detail in both the NMS and network equipment.
Iijima, et al. Expires August 24, 2008 [Page 6]
Internet-Draft SOAP implementation February 2008
3.1. SOAP Implementation in NMS
Several SOAP implementations capable of being installed on an NMS are
available today. Apache Axis is one of the widely used free SOAP
implementations.
Axis works as a SOAP implementation and a useful tool to develop an
NMS. 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. In
conclusion, various kinds of benefits can be acquired if we introduce
Axis 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 function of SOAP Parser 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 of SOAP. HTTP creates and kills a TCP session at every
request. Therefore, when using HTTP as a transport protocol of 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 TCP-level session.
The session maintenance function at the TCP-level has to be
incorporated to work 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
MAC address and uses it as a session identifier for subsequent
NETCONF message exchanges. When an NMS sets the Cookie for
Iijima, et al. Expires August 24, 2008 [Page 7]
Internet-Draft SOAP implementation February 2008
subsequent NETCONF messages, the network equipment recognizes the
session and maintains it. The stored Cookie is erased when the NMS
sends a close session message and a response message is received from
network equipment.
3.2. SOAP Implementation in Network Equipment
SOAP must also be implemented in the network equipment to accept SOAP
messages sent from the NMS. Like 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 memory
capacity might be limited. Therefore, a SOAP implementation has to
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 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 necessary part of every SOAP message. However, the SOAP
encodingStyle attribute inside the envelope elements does not need to
be specified. When not specified, default the encodingStyle
attribute 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. After all, a SOAP parser in network equipment is
allowed to parse only mandatory parts of a SOAP envelope.
3.2.2. Session Maintenance in Network Equipment
To maintain sessions with the NMS, 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 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, the network equipment erases the
stored session identifier.
Iijima, et al. Expires August 24, 2008 [Page 8]
Internet-Draft SOAP implementation February 2008
4. Guidelines of Developing NETCONF Client and Server
This section provides guidelines on development of 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 Client
To develop a SOAP-based NETCONF client, generating stub code is
necessary. Stub is a library generated automatically from WSDL by a
Web Service tool and acts as a group of APIs. In the case of using
Apache Axis as a Web Service tool, a generated stub is in the form of
Java APIs. Those 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" is selected from
RFC4743[2] specifies NETCONF messages to be exchanged between the
NETCONF client and server. Those NETCONF messages are the "hello"
message and "rpc" message. Therefore, stub codes of 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[2], 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 NETCONF protocol in the manner of
"get-config" and "edit-config", for example, a XML schema file named
"netconf.xsd", which is selected from RFC4741[1], is used by being
imported into "netconf- soap_1.0.wsdl". Using the XML schema,
methods of operating NETCONF protocol are generated in files such as
"GetConfigType.java" and "EditConfigType.java", for example.
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
XML schema in [1].
The connection between the NETCONF schema and data model should be
made by inserting the following attribute into elements of each data
model. This attribute is defined in XML schema in [1].
Iijima, et al. Expires August 24, 2008 [Page 9]
Internet-Draft SOAP implementation February 2008
<xs:attribute name="operation" type="editOperationType"
default="merge"/>
In conclusion, using "myNetconfService.wsdl" to import "netconf-
soap_1.0.wsdl", NETCONF schema, and the data model, we generate stub
files containing interfaces to configure network equipment.
The development environment needs to be arranged as well when
generating stub codes. The development of a Java-based NETCONF
client needs JDK (Java Development Kit)[6] and Apache Axis. In
addition, using some IDE (Integrated Development Environment) such as
Eclipse[7] with Apache Ant[8] and NetBeans[9] would reduce the
developer workload significantly. When using Eclipse as an IDE,
first, the library (*.jar files) of Axis has to be added to the
development project build path as an external library. The library
of Axis acts as a SOAP library, so we do not need to be concerned
about SOAP messaging when programming a NETCONF client using the
library of Axis.
4.1.1. Developing NETCONF Client 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 directory of
"C:\NetconfClient", 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 a 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", for example.
Next, compilation of those files by executing the following command
in the command prompt is necessary.
C:\NetconfClient>javac -classpath .;%AXIS_HOME%\lib\axis.jar;%
AXIS_HOME%\lib\jaxrpc.jar stub/*.java
Iijima, et al. Expires August 24, 2008 [Page 10]
Internet-Draft SOAP implementation February 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 compiling, source code of the NETCONF client
has to be written. 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: Source code of NETCONF client
To add functions such as releasing of log messages, those functions
Iijima, et al. Expires August 24, 2008 [Page 11]
Internet-Draft SOAP implementation February 2008
have to be incorporated at this stage. Again, the NETCONF client is
developed by compiling its source code.
4.1.2. Developing NETCONF Client with Eclipse
When we use Eclipse and Apache Ant, 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. 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 client
Iijima, et al. Expires August 24, 2008 [Page 12]
Internet-Draft SOAP implementation February 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 client
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, 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 (Java ARchive ) file, which is the output compressing all stub
files (*.class) and acts as a library. In this example, the name of
"NETCONF.jar" is specified in Figure 5. The "NETCONF.jar" file also
has to be added to the build path of the development project used in
Eclipse as an external library.
After adding the "NETCONF.jar" file to the build path of the
development project, we can write source codes of the NETCONF client
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 will be compiled. NETCONF client
is developed in this manner.
4.2. Procedures of Development of NETCONF Server
In the Web Service framework, there are two approaches of developing
a Web Service provider, namely NETCONF server in this case. 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, and then, skeleton source code from the WSDL file is
generated by using a Web Service tool such as Apache Axis. Generated
skeleton code is just a template of the Web Service provider's source
code. Therefore, even though the Web Service provider's skeleton
code works as its own, if additional functions were necessary,
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.
By contrast, the bottom-up approach is carried out by first creating
a Web service from source code (e.g., Java bean) and then generating
Iijima, et al. Expires August 24, 2008 [Page 13]
Internet-Draft SOAP implementation February 2008
a WSDL file from the source code using a Web Service 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
service becomes vendor specific.
In the case of developing NETCONF server, the WSDL file is already
defined in [2], so there is no choice but to develop NETCONF server
using the top-down approach. The remainder of the section describes
the top-down approach of developing NETCONF server.
To develop a SOAP-based NETCONF server using the top-down approach,
skeleton code is necessary. Skeleton is a library, which is also
generated automatically from WSDL by a Web Service tool. In the case
of using Axis as a Web Service tool, the generated skeleton is in the
form of a Java library. From the same WSDL file as that being used
for generating stub code, skeleton codes are generated in files such
as "NetconfBindingSkeleton.java", "Hello.java", and
"GetConfigType.java", for example.
The development environment needs to be arranged as well when
generating skeleton codes. When developing a Java-based NETCONF
server, a servlet container such as Apache Tomcat[10] is necessary in
addition to JDK and Axis. The directory of "webapps\axis" under the
Axis directory has to be copied to the directory of "webapps" under
the Tomcat directory.
4.2.1. Developing NETCONF Server without Eclipse
Given that the development environment of NETCONF server is created
in the environment of a Windows computer without Eclipse and
"myNetconfService.wsdl" is placed in the directory of
"C:\NetconfServer", 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, we
Iijima, et al. Expires August 24, 2008 [Page 14]
Internet-Draft SOAP implementation February 2008
find files such as "NetconfBindingSkeleton.java", "Hello.java", and
"GetConfigType.java", for example. Furthermore, files named
"deploy.wsdd" and "undeploy.wsdd" are found. "Deploy.wsdd" and
"undeploy.wsdd" are used when deploying NETCONF server in a servlet
container and undeploying NETCONF server from a servlet container,
respectively.
Then, adding source codes of NETCONF server functions to the skeleton
codes such as "NetconfBindingImpl.java" is required as the need
arises. Functions such as releasing 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 will be carried out. That
will generate "*.class" files.
C:\NetconfServer>javac -classpath .;%AXIS_HOME%\lib\axis.jar;%
AXIS_HOME%\lib\jaxrpc.jar skeleton/*.java
NETCONF server can be developed by following these procedures. Then,
copying these class files into the directory of "webapps\axis\WEB-
INFO\classes" of the Apache Tomcat directory is required. Finally,
deploying 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 was executed in the directory where "deploy.wsdd" is
located. The file, "deploy.wsdd", was generated at the same time as
generating the skeleton code. After deployment, the NETCONF server
receives NETCONF messages sent from the NETCONF client.
4.2.2. Developing NETCONF Server using Eclipse
When we use Eclipse and Apache Ant, procedures followed 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. Examples of "build.xml" and
"build.properties" are shown in Figure 6 and Figure 7, respectively.
<?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"/>
Iijima, et al. Expires August 24, 2008 [Page 15]
Internet-Draft SOAP implementation February 2008
</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"/>
Iijima, et al. Expires August 24, 2008 [Page 16]
Internet-Draft SOAP implementation February 2008
</project>
Figure 6: build.xml of NETCONF server
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 server
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, steps shown in Figure 6 are
followed. First, skeleton codes have to be generated. After
generating skeleton codes, adding source codes of the NETCONF server
functions to the skeleton code is necessary depending on the function
that developers intend to add.
Then, by running Apache Ant again, compiling those skeleton codes is
executed. As a result, class files of NETCONF server will be
generated. Apache Ant will copy these class files to the directory
of Tomcat and deploy the NETCONF server. After that, NETCONF server
will become accessible from the NETCONF client. NETCONF server is
developed in this manner.
4.2.3. Developing NETCONF Server by C Language Programming
When implementing NETCONF server on network equipment, memory
capacity might be limited, so installing a Java environment on
network equipment might not be attainable. The network equipment
platform might not support a Web Service tool. In that case,
implementation of SOAP as well as NETCONF server by using C
programming on the network equipment may be necessary.
Iijima, et al. Expires August 24, 2008 [Page 17]
Internet-Draft SOAP implementation February 2008
To develop a NETCONF server capable of receiving NETCONF messages
sent over SOAP/HTTP, the network equipment needs 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 HTTP daemon and a NETCONF service provider. The NETCONF
service provider has to be developed to parse NETCONF messages sent
from the NETCONF client and send reply NETCONF messages toward the
NETCONF client.
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. Then, the
NETCONF service provider parses the NETCONF messages and configures
the network equipment accordingly.
Iijima, et al. Expires August 24, 2008 [Page 18]
Internet-Draft SOAP implementation February 2008
5. Security Considerations
The security considerations of RFC4741[1] and RFC4743[2] are
applicable to this document. Implementers or users of SOAP-based
NETCONF clients and servers should take into account those
considerations.
As specified in the security considerations section of RFC4743[2],
transport-level security, such as authentication of users and
encryption of transport protocol, has to be ensured by TLS 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 August 24, 2008 [Page 19]
Internet-Draft SOAP implementation February 2008
6. IANA Considerations
This document has no actions for IANA.
Iijima, et al. Expires August 24, 2008 [Page 20]
Internet-Draft SOAP implementation February 2008
7. References
7.1. Normative References
[1] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006.
[2] Goddard, T., "Using NETCONF over the Simple Object Access
Protocol (SOAP)", RFC 4743, December 2006.
7.2. Informative References
[3] Bradner, S. , "Key words for use in RFCs to Indicate
Requirement Levels" , BCP 14 , RFC 2119 , March 1997 .
[4] "Web Service Description Language (WSDL) 1.1" .
<http://www.w3.org/TR/wsdl/>
[5] "Web Services - Axis".
<http://ws.apache.org/axis/>
[6] "Java SE".
<http://java.sun.com/javase/index.jsp>
[7] "Eclipse".
<http://www.eclipse.org/>
[8] "Apache Ant".
<http://ant.apache.org/>
[9] "NetBeans".
<http://www.netbeans.org/index.html>
[10] "Apache Tomcat".
<http://tomcat.apache.org/>
Iijima, et al. Expires August 24, 2008 [Page 21]
Internet-Draft SOAP implementation February 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 August 24, 2008 [Page 22]
Internet-Draft SOAP implementation February 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
Central Research Laboratory, 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 August 24, 2008 [Page 23]
Internet-Draft SOAP implementation February 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.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Iijima, et al. Expires August 24, 2008 [Page 24]
