Network Working Group T. Iijima
Internet-Draft Y. Atarashi
Intended status: Informational H. Kimura
Expires: July 13, 2008 M. Kitani
Alaxala Networks Corp.
H. Okita
Central Research Laboratory,
Hitachi, Ltd.
January 10, 2008
Experience of implementing NETCONF over SOAP
draft-iijima-netconf-soap-implementation-05
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 July 13, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2008).
Iijima, et al. Expires July 13, 2008 [Page 1]
Internet-Draft SOAP implementation January 2008
Abstract
NETCONF protocol is standardized to be exchanged over SSH, SOAP, or
BEEP. We developed a network management system based on NETCONF
protocol. For several reasons, we chose the SOAP protocol as a
transport protocol of NETCONF. This document describes why we chose
SOAP as a transport protocol and the insight gained from actual
development.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. NETCONF over SOAP . . . . . . . . . . . . . . . . . . . . 3
1.2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 3
1.3. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 3
2. NETCONF Development on a Framework of Web Service . . . . . . 4
2.1. SOAP as a Transport Protocol . . . . . . . . . . . . . . . 4
2.2. WSDL as an Interface Description Language . . . . . . . . 5
2.3. API as a 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. Guideline of Developing NETCONF Client and Server . . . . . . 9
4.1. Procedures of Development of NETCONF Client . . . . . . . 9
4.1.1. Developing NETCONF Client without Eclipse . . . . . . 11
4.1.2. Developing NETCONF Client with Eclipse . . . . . . . . 12
4.2. Procedures of Development of NETCONF Server . . . . . . . 14
4.2.1. Developing NETCONF Server without Eclipse . . . . . . 15
4.2.2. Developing NETCONF Server with Eclipse . . . . . . . . 16
4.2.3. Developing NETCONF Server by C 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 July 13, 2008 [Page 2]
Internet-Draft SOAP implementation January 2008
1. Introduction
1.1. NETCONF over SOAP
In order to enable network equipment configuration automatically from
network systems, NETCONF is designed to use XML as its description
language[1]. Because XML is easy for systems to understand, it is a
suitable technology to cope with flexible specification changes and
frequent functional extensions, and it enables automatic operation.
SOAP was defined in RFC4743[2] as one of the transport protocol of
NETCONF. SOAP is also designed to use XML and is expected to become
an indispensable technology of Web service. For this reason, SOAP is
a prospective technology and well suited to the NETCONF protocol.
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 SOAP is practical as a transport protocol
of NETCONF in developing a network management system. This document
also describes the experience of implementing NETCONF over SOAP.
Iijima, et al. Expires July 13, 2008 [Page 3]
Internet-Draft SOAP implementation January 2008
2. NETCONF Development on a Framework of Web Service
SOAP is considered to be a fundamental technology of Web service. So
if we use SOAP as a transport protocol of NETCONF, network
configuration by NETCONF is achieved on a framework of Web service.
In this section, we describe the overall architecture of the Web
service.
+---+ +-----------+ +-----------+ +--------------+ +--------+
| | | Security | | Reliable | | Transaction | | Search |
|XML| | | | Message | | | | |
| | | | | | | | | UDDI |
| | | | | WS- | | | +--------+
| | |WS-Security| |Reliability| |WS-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, including security technology. For instance, WS-
Security and WS-Transaction technology are installed on SOAP only by
inserting particular messages in the SOAP Header. If we do not
choose SOAP/HTTP as a transport layer of the NETCONF protocol, we
have to develop each surrounding technology from scratch. Hence,
when introducing additional technologies around SOAP, the development
of a NETCONF-based network management system is relatively easy when
we choose SOAP as a transport protocol of NETCONF.
2.1. SOAP as a Transport Protocol
SOAP is basically designed to use distributed objects scattered
around the Internet regardless of platform. Therefore, SOAP is
developed as a messaging technology that uses standardized internet
Iijima, et al. Expires July 13, 2008 [Page 4]
Internet-Draft SOAP implementation January 2008
technologies such as HTTP and XML. In addition, SOAP is so flexible
that it is easy to incorporate other technologies.
2.2. WSDL as an Interface Description Language
WSDL (Web Service Description Language)[4] is a language expressing
how SOAP messages are exchanged among Web service entities. It is an
innovative technology for Web service since the development tool can
automatically generates interfaces to Web service by simply importing
WSDL into the development tool. Interfaces to Web service generated
in this way acts as APIs (Application Programming Interface).
Developers only need to use these APIs when developing a
configuration application.
Regarding development tools that can understand WSDL, useful
technologies are available with SOAP. For instance, Apache Axis[5]
is an interface generator from WSDL as well as a widely used SOAP
implementation middleware. If we choose SOAP as a transport
protocol, we do not need to develop interfaces to Web service by
ourselves because interfaces are generated in a form of API by the
development tool.
2.3. API as a Programming Interface
As described in the previous section, API is generated from WSDL by
development tools such as Apache Axis. Apache Axis can generate API
which is in a form of Java library and acts as a programming
interface for a configuration application. By taking advantage of
those APIs, developers can develop NETCONF application which can send
SOAP messages to network equipment and configure the equipment.
Iijima, et al. Expires July 13, 2008 [Page 5]
Internet-Draft SOAP implementation January 2008
3. Architecture of NETCONF over SOAP Implementation
In this section, we describe the architecture of NETCONF
implementation using SOAP as its transport protocol. Figure 2 is the
architecture of the NETCONF implementation using SOAP. SOAP
implementation needs to be implemented on both a network management
system and network equipment. And each SOAP implementation exchanges
SOAP messages based on the WSDL which is provided by RFC4743[2]. If
Java library generated from the WSDL are provided on the network
management system, engineers can develop NETCONF application, which
can configure network equipment via the NETCONF protocol, by
utilizing the Java library. Engineers don't need to write neither
SOAP nor XML directly by hands. NETCONF application developed in
network management system works as a NETCONF client while network
equipment acts as a NETCONF server.
+-------------------------------------------------------+
| Network Management System |
| |
| +--------------------------------------------+ |
| | NETCONF application | |
| +--------------------------------------------+ |
| +--------------------------------------------+ |
| | Java library | |
| +--------------------------------------------+ |
| +--------------------------------------------+ |
| | SOAP Implementation | |
| | | |
| | Apache Axis | |
| +--------------------------------------------+ |
+---------------------|----------^----------------------+
| |
rpc-request | | rpc-reply
/ SOAP | | / SOAP
/ HTTP(S) | | / HTTP(S)
| |
+---------------------v----------|----------------------+
| +--------------------------------------------+ |
| | SOAP Implementation | |
| +--------------------------------------------+ |
| |
| Network Equipment |
+-------------------------------------------------------+
Figure 2: Architecture of NETCONF implementation using SOAP
Iijima, et al. Expires July 13, 2008 [Page 6]
Internet-Draft SOAP implementation January 2008
In the following section, we explain the SOAP implementation in
detail in both NMS (Network Management System) and network equipment.
3.1. SOAP Implementation in NMS
Several SOAP implementations capable of being installed on NMS are
available today. Apache Axis is one of the practical free SOAP
implementation. Rapid parsing in the NMS is achieved by Axis since
it uses SAX (Simple API for XML) as its parser.
Axis is not only a SOAP implementation but a useful tool to develop a
NMS. For instance, WSDL2Java, one of Axis's tools, can generate
Java's class file from WSDL file. Another tool called Java2WSDL does
the opposite. We can also generate WSDL file from Java's class file.
Conclusively, various kinds of benefits can be acquired if we
introduce Axis as a SOAP implementation.
In order to develop a NETCONF application which is capable of various
functions such as session management and releasing of log messages,
Java library, which is generated by Apache Axis tool and run over
SOAP implementation, needs to be extended. By utilizing these Java
libraries, engineers can easily develop NETCONF applications.
3.1.1. SOAP Parser in NMS
The function of SOAP Parser is totally left to a SOAP implementation
such as Apache Axis.
3.1.2. Session Maintenance in NMS
When exchanging NETCONF messages between NMS and network equipment,
implementation of session maintenance function is necessary in both
sides. We used Cookie field inside a HTTP header as a session
identifier and implemented a session maintenance function which
manages the Cookie field. After NMS sends a NETCONF hello message to
network equipment, NMS receives a newly allocated session identifier
which is written in the Cookie field of a replying hello message.
NMS preserves the Cookie paired with the network equipment's MAC
address and uses it as a session identifier for the subsequent
NETCONF messages exchange. When NMS sets the Cookie for the
following NETCONF messages, the network equipment recognize the
session and maintains it. The stored Cookie is erased when the NMS
sends a close session message and received a response message from
network equipment.
Iijima, et al. Expires July 13, 2008 [Page 7]
Internet-Draft SOAP implementation January 2008
3.2. SOAP Implementation in Network Equipment
SOAP must also be implemented in the network equipment in order to
accept SOAP messages sent from the NMS. Like the case of NMS, some
free SOAP implementations to be installed on network equipment are
available today. However, in the case of network equipment, memory
capacity might be limited. Therefore, SOAP implementation has to be
chosen taking memory capacity into consideration. In some case,
memory saving method will be required when implementing SOAP in the
network equipment.
3.2.1. SOAP Parser in Network Equipment
When we choose HTTP as an underlying protocol over which SOAP
messages are exchanged, the SOAP message consists of HTTP header and
a SOAP Envelope. The SOAP Envelope is a necessary part of every SOAP
message. But in regard to the SOAP encodingStyle attribute inside
the Envelope elements, it is not required to be specified. In such a
case, default encodingStyle of
"http://schema.xmlsoap.org/soap/encoding" is applied. So if there's
a memory constraint, we can omit a function of parsing encodingStyle.
Similarly, SOAP Header inside the SOAP Envelope is defined as
optional. So, when memory capacity in network equipment is
insufficient, the module that processes SOAP Header can be omitted.
After all, a SOAP parser in network equipment is allowed to act only
as a SOAP Envelope and Body parser.
3.2.2. Session Maintenance in Network Equipment
In order to maintain sessions with the NMS, SOAP implementation in
network equipment MUST provide session identifier to the NMS. When
network equipment receives NETCONF hello message from the NMS, SOAP
implementation in network equipment sets session identifier paired
with network equipment's MAC address at Cookie field inside the HTTP
header and sends a response message to network equipment. The
session identifier is used when locking the configuration of the
network equipment. When network equipment receives a NETCONF close
message from the NMS, the network equipment erases the stored session
identifier.
Iijima, et al. Expires July 13, 2008 [Page 8]
Internet-Draft SOAP implementation January 2008
4. Guideline of Developing NETCONF Client and Server
NETCONF implementations running on SOAP implementation in NMS and in
network equipment acts as NETCONF client and NETCONF server
respectively. This relationship is illustrated in Figure 3. This
section describes how to develop NETCONF client and server.
+---------------------------+ +---------------------------+
| NETCONF Client | | NETCONF Server |
|(Network Management System)| | (Network Equipment) |
| +---------------------+ | | +---------------------+ |
| | NETCONF application | | | | NETCONF daemon | |
| +---------------------+ | | +---------------------+ |
| +---------------------+ | | +---------------------+ |
| | SOAP Implementation | | | | SOAP Implementation | |
| +---------------------+ | | +---------------------+ |
+-------^----------|--------+ +-------^----------|--------+
| | rpc-request | |
| +----- /SOAP ----+ |
| / HTTP(S) |
| |
| rpc-reply |
+---------------- /SOAP ---------------+
/ HTTP(S)
Figure 3: NETCONF Client and Server
When developing SOAP-based NETCONF client and server, developers'
workload are significantly reduced by making full use of various
tools such as Apache Axis, Apache Ant[6], and so on. Therefore, in
the case of using SOAP as a transport protocol of NETCONF, making
public of what kinds of development tools are available would help
SOAP-based NETCONF client and server be deployed widely.
4.1. Procedures of Development of NETCONF Client
In order to develop SOAP-based NETCONF client, stub code is
necessary. Stub is a library generated automatically from WSDL by a
Web service tool and acts as APIs. In the case of using Apache Axis
as a Web service tool, generated stub is in a form of Java APIs.
Those Java APIs show interfaces toward Web service as if they
configure local machine.
WSDL file named "netconf-soap_1.0.wsdl" extracted from RFC4743[2] is
specifying NETCONF messages to be exchanged between NETCONF client
Iijima, et al. Expires July 13, 2008 [Page 9]
Internet-Draft SOAP implementation January 2008
and server. Those NETCONF messages are "hello" message and "rpc"
message. So stub codes of making "hello" message and "rpc" message
are generated from "netconf-soap_1.0.wsdl". But, the file "netconf-
soap_1.0.wsdl" is not enough since service element is not specified
in it.
So, from "myNetconfService.wsdl", which is specifying the service
element and importing "netconf-soap_1.0.wsdl", basic stub codes of
NETCONF are generated. Stub codes are generated in the files such as
"Netconf.java", "NetconfLocator.java", and "NetconfBindingStub.java".
As for interfaces of how to configure network equipment such as "get-
config", "edit-config", and so on, "netconf-soap_1.0.wsdl" is
importing XML schema file named "netconf.xsd" from RFC4741[1]. From
"netconf.xsd", stub codes of methods of accessing network equipment
are generated in the files such as "GetConfigType.java",
"EditConfigType.java", and so on.
In regards to interfaces towards network functions to be configured
at network equipment, however, data model of each network function
has to be defined in the style of XML schema. And the XML schema is
REQUIRED to be imported to "netconf-soap_1.0.wsdl"[2] in a same way
as "netconf.xsd".
The connection between NETCONF schema and data model SHOULD be done
by inserting following attribute into each data model's elements.
This attribute is defined in NETCONF schema[1].
<xs:attribute name="operation" type="editOperationType"
default="merge"/>
From the "myNetconfService.wsdl" importing "netconf-soap_1.0.wsdl",
NETCONF schema, and data model, we can generate stub files containing
interfaces to configure network equipment.
Development environment needs to be arranged beforehand, when
generating stub codes. Development of Java-based NETCONF client
needs JDK (Java Development Kit)[8], and Apache Axis. In addition,
some IDE (Integrated Development Environment) such as Eclipse[7],
Apache Ant, and NetBeans[9] would reduce developers workload
significantly. When using Eclipse as an IDE, first of all, library
(*.jar files) of Apache Axis have to be added to development
project's build path as an external library. The library of Apache
Axis acts as SOAP library. So we don't need to care about SOAP
messaging when programming NETCONF client using the library of Apache
Axis.
Iijima, et al. Expires July 13, 2008 [Page 10]
Internet-Draft SOAP implementation January 2008
4.1.1. Developing NETCONF Client without Eclipse
Given that development of NETCONF client is done in the environment
of Windows computer without Eclipse and "myNetconfService.wsdl" is
placed in the directory of "C:\NetconfClient", stub is generated by
executing following command in DOS-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 WSDL file is located, WSDL2Java command was
executed. In the case we don't use Eclipse, locations of each Axis
library have to be specified. Environment variable of "AXIS_HOME" is
a directory where Apache Axis is installed. By executing above
command, files with extension of "*.java" are generated in the "stub"
directory, which is specified by above command. Inside the stub
directory, we can find files such as "NetconfBindingStub.java",
"Hello.java", "GetConfigType.java" and the like.
Next, compilation of those files by executing following command in
DOS-prompt is necessary.
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. At the time of compiling, encoding style might be taken
care of. After compiling, source code of the NETCONF client is
REQUIRED to be written. Figure 4 is an example of the source code of
the NETCONF client. This NETCONF client is written by utilizing
stub's classes and interfaces which are imported to local package and
referenced.
Iijima, et al. Expires July 13, 2008 [Page 11]
Internet-Draft SOAP implementation January 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 4: Example of source code of NETCONF client
In order to add functions such as session management, releasing of
log messages, and son on, those functions have to be incorporated at
this stage. And again, by compiling the source code of the NETCONF
client, NETCONF client is developed.
4.1.2. Developing NETCONF Client with Eclipse
In the case when we can use Eclipse and Apache Ant, procedures taken
in the previous section are significantly simplified and executed at
Iijima, et al. Expires July 13, 2008 [Page 12]
Internet-Draft SOAP implementation January 2008
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 5 and Figure 6
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}">
</jar>
</target>
<target name="all" depends="stub-jar"/>
</project>
Figure 5: build.xml of NETCONF client
Iijima, et al. Expires July 13, 2008 [Page 13]
Internet-Draft SOAP implementation January 2008
axis.libdir=C:/axis-1_4/lib
srcdir=src
destdir=classes
stub.stubdir=stub
stub.wsdlpath=myNetconfService.wsdl
stub.jar=NETCONF.jar
Figure 6: build.properties of NETCONF client
The location of WSDL file has to be specified in the
"build.properties" file. In the case of Figure 6, the location of
WSDL file is specified as under the current directory.
By running the Apache Ant at Eclipse, steps shown in Figure 5 are
taken. First of all, stub codes are generated. Then, compiling of
those stub codes are executed. After the compilation, Apache Ant
will generate 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 6. The
"NETCONF.jar" file also have to be added to the development project's
build path at Eclipse as an external library.
After adding "NETCONF.jar" file to the development project's build
path, we can write NETCONF client's source codes by utilizing stub's
classes and interfaces. Source codes like the one shown in Figure 4
are written. In order to add functions such as session management,
releasing of log messages, and son on, those functions have to be
incorporated at this stage. And by running Apache Ant again, it will
compile the source code of the NETCONF client. NETCONF client is
developed as this way.
4.2. Procedures of Development of NETCONF Server
In the framework of Web service, there are two approaches of
developing Web service provider, namely NETCONF server in this case.
The one is called top-down approach, and another is called bottom-up
approach. The top-down approach is done by first designing WSDL
file, and then generate skeleton source code from WSDL file 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. So even
though Web service provider's skeleton code works as its own, if
additional functions were necessary, generated skeleton code REQUIRES
additional source codes. This way is superior to bottom-up approach
in terms of interoperability since specification is already defined
in WSDL file. All vendors have to obey the WSDL file.
By contrast, the bottom-up approach is done by first creating Web
Iijima, et al. Expires July 13, 2008 [Page 14]
Internet-Draft SOAP implementation January 2008
service from a source code (e.x. Java bean) and then generating WSDL
file from the source code using a Web service tool such as Apache
Axis. This approach is faster and easier than top-down approach.
But in the case of bottom-up approach, ensuring the interoperability
becomes difficult since implementation of Web service becomes vendor-
specific.
In the case of developing NETCONF server, since WSDL file is already
defined in [2], there's no choice but to develop NETCONF server by
top-down approach. The rest of the section describes the top-down
approach of developing NETCONF server.
In order to develop SOAP-based NETCONF server by 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 Apache Axis as a Web service tool, generated skeleton is in
a form of Java library. From the same WSDL file as the one being
used for generating stub code, skeleton codes are generated in files
such as "NetconfBindingSkeleton.java", "Hello.java",
"GetConfigType.java", and so forth.
Development environment needs to be arranged beforehand, when
generating skeleton codes. When developing Java-based NETCONF
server, servlet container such as Apache Tomcat[10] is necessary in
addition to JDK, Apache Axis. And the directory of "webapps\axis"
under the Apache Axis directory has to be copied to the directory of
"webapps" under the Apache Tomcat directory.
4.2.1. Developing NETCONF Server without Eclipse
Given that development environment of NETCONF server is done in the
environment of Windows computer without Eclipse and
"myNetconfService.wsdl" is placed in the directory of
"C:\NetconfServer", skeleton is generated by executing following
command in DOS-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 WSDL file is located, WSDL2Java command was
executed. In the case we don't use Eclipse, locations of each Axis
library have to be specified. Environment variable of "AXIS_HOME" is
a directory where Apache Axis is installed. By executing above
command, files with extension of "*.java" are generated in the
Iijima, et al. Expires July 13, 2008 [Page 15]
Internet-Draft SOAP implementation January 2008
"skeleton" directory, which is specified in the above command.
Inside the skeleton directory, we can find files such as
"NetconfBindingSkeleton.java", "Hello.java", and "GetConfigType.java"
and the like. Furthermore, files named "deploy.wsdd" and
"undeploy.wsdd" are found. "Deploy.wsdd" and "undeploy.wsdd" are
used when deploying NETCONF server to servlet container and
undeploying NETCONF server from servlet container respectively.
Then, it is REQUIRED to add source codes of NETCONF server's
functions to the skeleton codes such as "NetconfBindingImpl.java" as
the need arises. Functions such as session management, releasing of
log messages, and son on have to be added at this stage. After that,
by executing following command in DOS-prompt, compilation of java
files will be done. It 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 taking these procedures. Then, it
is REQUIRED to copy these class files into the directory of
"webapps\axis\WEB-INFO\classes" of the Apache Tomcat directory.
Finally, it is REQUIRED to deploy NETCONF server by executing
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
In the direcotory where "deploy.wsdd" is located, the command was
executed. The file, "deploy.wsdd", was generated at the same time as
generating skeleton code. After deploying the NETCONF server, the
NETCONF client can access to the NETCONF server and exchange NETCONF
messages.
4.2.2. Developing NETCONF Server with Eclipse
In the case when we can use Eclipse and Apache Ant, procedures taken
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 7 and Figure 8
respectively.
<?xml version="1.0"?>
<project name="NetconfService" default="all" basedir=".">
<property file="build.properties"/>
Iijima, et al. Expires July 13, 2008 [Page 16]
Internet-Draft SOAP implementation January 2008
<path id="axis-classpath">
<fileset dir="${axis.libdir}">
<include name="*.jar"/>
</fileset>
</path>
<target name="prepare">
<mkdir dir="${srcdir}"/>
<mkdir dir="${destdir}"/>
</target>
<target name="skeleton" depends="prepare">
<java classname="org.apache.axis.wsdl.WSDL2Java" fork
="Yes">
<arg value="-p"/>
<arg value="${skeletondir}"/>
<arg value="-o"/>
<arg value="${srcdir}"/>
<arg value="-s"/>
<arg value="-S"/>
<arg value="true"/>
<arg value="-d"/>
<arg value="Session"/>
<arg value="${wsdlpath}"/>
<classpath refid="axis-classpath"/>
</java>
</target>
<target name="compile" depends="skeleton">
<javac srcdir="${srcdir}" destdir="${destdir}"
encoding="UTF-8">
<classpath refid="axis-classpath"/>
</javac>
</target>
<target name="copy2axis" depends="compile">
<copy todir="${tomcat.axis.classesdir}" overwrite=
"true">
<fileset dir="${destdir}">
<include name="*.class"/>
<include name="*/*.class"/>
<include name="*/*/*.class"/>
</fileset>
</copy>
</target>
<target name="deploy" depends="copy2axis">
<java classname="org.apache.axis.client.AdminClient"
fork="Yes">
<arg value="-p"/>
<arg value="${deploy.port}"/>
<arg value="${deploy.ddname}"/>
<classpath refid="axis-classpath"/>
Iijima, et al. Expires July 13, 2008 [Page 17]
Internet-Draft SOAP implementation January 2008
</java>
</target>
<target name="all" depends="deploy"/>
</project>
Figure 7: 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 8: build.properties of NETCONF server
The location of WSDL file and "deploy.wsdd" file have to be specified
in the "build.properties" file. In the case of Figure 8, the
location of WSDL file and "deploy.wsdd" file are specified as under
the current directory.
By running the Apache Ant at Eclipse, steps shown in Figure 7 are
taken. First of all, skeleton codes have to be generated.
After generating skeleton codes, it is REQUIRED to add source codes
of the NETCONF server's functions to the skeleton code if necessary.
Functions such as session management, releasing of log messages, and
so on have to be added at this stage.
Then, by running the Apache Ant again, compiling of those skeleton
codes are executed. As a result, class files of NETCONF server will
be generated. And 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 as this way.
4.2.3. Developing NETCONF Server by C Programming
When implementing NETCONF server on network equipment, memory
capacity might be limited and it might be unattainable to install
Iijima, et al. Expires July 13, 2008 [Page 18]
Internet-Draft SOAP implementation January 2008
Java environment on network equipment. Or platform of network
equipment might not be the one which doesn't support Web service
tool. In such occasion, implementation of SOAP as well as NETCONF
server by C programming on the network equipment MAY be necessary.
In order to develop NETCONF server capable of receiving NETCONF
message sent over SOAP/HTTP, HTTP daemon and NETCONF daemon are
necessary inside network equipment. As for the HTTP daemon, a
commonly used daemon will be usable. And a SOAP engine needs to be
added to the HTTP daemon as a connector between HTTP daemon and
NETCONF daemon. The NETCONF daemon has to be developed so as to
parse NETCONF messages sent from the NETCONF client and send replying
NETCONF message toward the NETCONF client.
When HTTP daemon receives a SOAP message which is sent over HTTP, the
message is handed over to the SOAP engine incorporated in the HTTP
daemon. Then the SOAP engine removes the SOAP Header and passes
NETCONF messages on to the NETCONF daemon. Then, the NETCONF daemon
parses the NETCONF messages and configure the network equipment
accordingly.
Iijima, et al. Expires July 13, 2008 [Page 19]
Internet-Draft SOAP implementation January 2008
5. Security Considerations
Security SHOULD be considered from two angles. One is transport-
level security, and the other is message-level security. Transport-
level security, such as encryption of entire messages, is a matter of
SSL/TLS. So only message-level security, such as partial encryption
of messages or signatures, SHOULD be considered when implementing
NETCONF server and client. To fulfill that need, WS-security and WS-
Reliability have been defined.
WS-Security is a Web service technology and is dependent on SOAP
technology. WS-Security technology can be incorporated by inserting
XML encryption and XML signatures into the SOAP Header.
Also, WS-Reliability achieves confirmation of sent messages and
resending of messages. WS-Reliability is also achieved by inserting
particular messages into the SOAP Header.
Iijima, et al. Expires July 13, 2008 [Page 20]
Internet-Draft SOAP implementation January 2008
6. IANA Considerations
This document has no actions for IANA.
Iijima, et al. Expires July 13, 2008 [Page 21]
Internet-Draft SOAP implementation January 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] "Apache Ant".
<http://ant.apache.org/>
[7] "Eclipse".
<http://www.eclipse.org/>
[8] "Java SE".
<http://java.sun.com/javase/index.jsp>
[9] "NetBeans".
<http://www.netbeans.org/index.html>
[10] "Apache Tomcat".
<http://tomcat.apache.org/>
Iijima, et al. Expires July 13, 2008 [Page 22]
Internet-Draft SOAP implementation January 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 July 13, 2008 [Page 23]
Internet-Draft SOAP implementation January 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 July 13, 2008 [Page 24]
Internet-Draft SOAP implementation January 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 July 13, 2008 [Page 25]
