RFC 5381
Experience of Implementing NETCONF over SOAP
RFC 5381: Experience of Implementing NETCONF over SOAP 🎀
okay bestie, this one is RFC 5381, and it's titled Experience of Implementing NETCONF over SOAP ✨ It came out in October 2008 from the Network Working Group, and it's Informational 💅 That means it shares info, it's not a standard. The authors are T. Iijima, Y. Atarashi, H. Kimura, and M. Kitani from Alaxala Networks Corp., plus H. Okita from Hitachi, Ltd. 🧚 Its title block doesn't list anything it obsoletes or updates.
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 🚨
okay so this section is really important, no cap 😭 The doc talks about how NETCONF over SOAP was implemented. Section 2.4 of RFC 4741 says, "A NETCONF implementation MUST support the SSH transport protocol mapping". 💀 That means a NETCONF implementation that only supports the SOAP transport from this doc, and not (at least) SSH as well, is not in compliance with the NETCONF standards. Lowkey the whole point, so don't skip it 🙈
Abstract 🦋
This doc is about how the authors built 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, because it uses cookies on top of the persistent transport connections of HTTP. 😬 When SOAP is the transport for NETCONF, there are all kinds of development tools around, and using them fully can seriously cut down developers' workload 🔥 The authors built an NMS (Network Management System) and network equipment that can handle NETCONF messages sent over SOAP. 👑 The goal is to share NETCONF development guidelines from their experience building a SOAP-based NETCONF client and server ✨
Table of Contents 🍓
1. Introduction ....................................................3
1.1. NETCONF over SOAP ..........................................3
1.2. Motivation .................................................3
2. NETCONF Development on Web Services Framework ...................4
2.1. WSDL as an Interface Description Language ..................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 ....................................191. Introduction 🦋
1.1. NETCONF over SOAP 💅
This doc is not a product from the NETCONF WG 🙅♀️ It's a report on what individual developers learned from their own experience 📝
SOAP (Simple Object Access Protocol) was specified in [RFC4743] as one of the transport protocols for NETCONF 💜 It uses XML (eXtensible Markup Language) as its description language, and XML is a fundamental messaging technology for Web Services. ✨ That's why SOAP is a great fit for NETCONF and can be deployed widely 🌈
To build a SOAP-based NETCONF client and server, there are several development tools available as open-source software 🧰 The authors built theirs using those tools. The SOAP-based NETCONF client was made with Java APIs (Application Programming Interfaces) that are automatically generated from the XSD (XML Schema Definition) file and WSDL (Web Services Description Language) file, which come from [RFC4741] and [RFC4743], respectively 🎀 This client acts as an NMS (Network Management System). The SOAP-based NETCONF server runs on network equipment and accepts NETCONF messages sent from the NETCONF client 🔥
1.2. Motivation 💖
The point of this doc is to explain why the authors think SOAP is practical as a transport protocol for NETCONF when you're building an NMS 🧠 If your NMS uses SOAP as its transport, you can use development tools and procedures from the Web Services framework 🛠️ The doc also covers what they learned implementing NETCONF over SOAP, so even people who barely know SOAP can start building a SOAP-based NETCONF client and server 🥹
This doc also describes an alternative SOAP binding for NETCONF that does not interoperate with an RFC 4743 conformant implementation, since it relies on cookies used on top of the persistent transport connections of HTTP 😬 It's shared for information purposes only, based on the authors' implementation experience 🫶
2. NETCONF Development on Web Services Framework 🌸
SOAP is a fundamental messaging technology for Web Services 🕸️ So if SOAP is the transport for NETCONF, then a network configuration done by NETCONF happens on the Web Services framework ✨ This section walks through the overall architecture of Web Services 👑
+----------------+ +----------------------------+
| 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 ServicesAs Figure 1 shows, the peripheral technologies around SOAP/HTTP are well developed 🌟 So if you pick SOAP/HTTP as the transport layer for NETCONF, NMS development on the Web Services framework can choose from different optional services, and it might be less expensive because it can use services that already exist 🤑
2.1. WSDL as an Interface Description Language 🧚
WSDL [WSDL] defines how SOAP messages are exchanged between Web Services entities 📨 Interfaces for those entities get generated automatically by development tools when you import a WSDL file, and those generated interfaces act as APIs 🔌 For developing an NMS, these APIs are all you need, so there's no need to use SOAP directly 🙌
There are useful tools that can import a WSDL file and come with SOAP 🧰 For example, Apache Axis [Axis] generates an interface from a WSDL file, and it's a widely used SOAP implementation middleware 💅
2.2. Generation of APIs 🍓
Like the previous section said, development tools such as Apache Axis generate APIs from a WSDL file 🛠️ These APIs are in the form of a Java library and act as programming interfaces for an NMS 💜 With them, 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 living in an NMS works as a NETCONF client, and network equipment acts as a NETCONF server 🤝 In this doc, the NETCONF-client and NETCONF-server implementations are called a NETCONF application and a NETCONF service provider, respectively 🏷️ A SOAP implementation may be installed on both the NMS and the network equipment 💖 Each SOAP implementation instance exchanges SOAP messages based on WSDL, as described in [RFC4743] 📬 If Java libraries generated from the WSDL are provided in the NMS, engineers can build a NETCONF application that configures network equipment over the NETCONF protocol by using that Java library 🎀 Engineers don't need to use XML or SOAP directly 🙈
+---------------------------+ +---------------------------+
| NETCONF Client | | NETCONF Server |
| (NMS) | | (Network Equipment) |
| +---------------------+ | | +---------------------+ |
| | NETCONF application | | | | NETCONF service | |
| | | | | | provider | |
| +---------------------+ | | +---------------------+ |
| +---------------------+ | | |
| | Java library | | | |
| +---------------------+ | | |
| +---------------------+ | | +---------------------+ |
| | SOAP Implementation | | | | SOAP Implementation | |
| | (Apache Axis) | | | | | |
| +---------------------+ | | +---------------------+ |
+-------^----------|--------+ +-------^----------|--------+
| | rpc-request | |
| +----- /SOAP ----+ |
| / HTTP(S) |
| |
| rpc-reply |
+---------------- /SOAP ---------------+
/ HTTP(S)
Figure 2: Architecture of NETCONF Implementation Using SOAPOkay, so the SOAP implementation on both the NMS and the network equipment gets its own breakdown in the sections that follow 🦋✨
3.1. SOAP Implementation in NMS ✨
Okay so, there are several SOAP implementations that are appropriate for use in an NMS available today 💅 Apache Axis is one such widely used implementation.
Axis is giving two jobs at once 🔥 It works as a SOAP implementation and as an NMS-development tool. For instance, WSDL2Java, one of Axis' tools, generates Java-class files from a WSDL file. Another tool, Java2WSDL, does the opposite and 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 can do various things, like releasing log messages, the 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 🧚
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]. Main character energy, no notes 🎀
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. So, 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 💀
Bestie, heads up: this alternative SOAP binding does not interoperate with RFC 4743 compliant implementations. Don't say I didn't warn you 🫶
For example, the implemented NETCONF-session maintenance in the NMS works like this 🦋 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 🌸
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. Same as the NMS side, 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 like this. 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 🚀
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 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, the NETCONF schema, and the data model makes it possible to generate stub files containing interfaces to configure network equipment 🎀
When stub codes are generated, the development environment 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 ✨
okay so bestie, first up is making a NETCONF client on a Windows computer without Eclipse 💻🎀 Say your WSDL file, myNetconfService.wsdl, is chilling in the C:\NetconfClient folder. You generate the stub by typing this into 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.wsdlYou run WSDL2Java from the folder where the WSDL file lives. You also have to point at each Axis library yourself. AXIS_HOME is just the folder where Axis is installed 🧚 Once it runs, you'll get *.java files inside the stub folder (the one you named in the command). Look for stuff like NetconfBindingStub.java, Hello.java, and GetConfigType.java 🌸
Next, compile those files with this command:
C:\NetconfClient>javac -classpath .;%AXIS_HOME%\lib\axis.jar;%
AXIS_HOME%\lib\jaxrpc.jar stub/*.javaAfter that you get *.class files, and yay, progress 🥹 Then you write the actual NETCONF client source code. Figure 3 shows a sample. It uses the stub classes and interfaces by importing them into the local package and referencing them, which is so clean 💅
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
If you want extras like release of log messages, this is the moment to add them 📝 Then you compile the source code again, and you're basically done 🎉
4.1.2. Developing NETCONF Clients Using Eclipse 🦋
If you're using Eclipse and Apache Ant, the steps from the last section get way simpler and run all at once 😭🙌 For this you need two files, build.xml and build.properties, for Apache Ant.
build.xml is written in XML, and Apache Ant reads it when it's running on Eclipse. It says how Ant should behave, so Ant knows how to compile source code, make a JAR (Java ARchive) file, and so on 💖 build.properties is different: it holds properties of the development environment Ant runs in. build.xml refers to this file 🌈
Figure 4 shows an example build.xml, and Figure 5 shows an example build.properties.
<?xml version="1.0"?>
<project name="NetconfClient" default="all" basedir=".">
<property file="build.properties"/>
<path id="axis-classpath">
<fileset dir="${axis.libdir}">
<include name="*.jar"/>
</fileset>
</path>
<target name="prepare">
<mkdir dir="${destdir}"/>
</target>
<target name="stub" depends="prepare">
<java classname="org.apache.axis.wsdl.WSDL2Java" fork
="Yes">
<arg value="-o"/>
<arg value="${srcdir}"/>
<arg value="-p"/>
<arg value="${stub.stubdir}"/>
<arg value="${stub.wsdlpath}"/>
<classpath refid="axis-classpath"/>
</java>
</target>
<target name="compile" depends="stub">
<javac srcdir="${srcdir}" destdir="${destdir}"
encoding="UTF-8">
<classpath refid="axis-classpath"/>
</javac>
</target>
<target name="stub-jar" depends="compile">
<jar jarfile="${stub.jar}" basedir="${destdir}"/>
</target>
<target name="all" depends="stub-jar"/>
</project>Figure 4: build.xml of NETCONF Clients
axis.libdir=C:/axis-1_4/lib
srcdir=src
destdir=classes
stub.stubdir=stub
stub.wsdlpath=myNetconfService.wsdl
stub.jar=NETCONF.jarFigure 5: build.properties of NETCONF Clients
The WSDL file's location goes in build.properties. In Figure 5, the WSDL file is set to sit under the current directory 📂
When you run Apache Ant on Eclipse, it does the steps in Figure 4 for you: it generates the stub code first, then compiles that stub code 🔥 We were careful about the encoding style used for the compiling, so don't skip that part 🫶 After compiling, Ant makes a JAR file that bundles all the stub files (*.class) into a library. In this example the JAR is called NETCONF.jar, as set in Figure 5. You also have to add NETCONF.jar to your development project's build path as an external library 💜
Once NETCONF.jar is on the build path, you can write NETCONF client source code using the stub classes and interfaces, like the one in Figure 3. Run Apache Ant again and the client gets compiled. That's the whole process, and it's giving smooth 💅✨
4.2. Procedures of Development of NETCONF Servers 🧚
Okay, so with Web Services there are two ways to build a Web Services provider, which is what a NETCONF server is. They're called the top-down approach and the bottom-up approach 🌸
The top-down approach starts by designing a WSDL file. Then a Web Services tool, like Apache Axis, generates a skeleton source code from that WSDL file. The skeleton is just a template for the provider's source code, so even though it works on its own, if you need extra functions you'll have to add more source code to it 📝 This approach beats bottom-up when it comes to interoperability, because the spec is already written down in the WSDL file. Every vendor has to comply with that WSDL file 🫶
The bottom-up approach is the reverse. You write the Web Services from source code first (a Java bean, for example), then a tool like Axis generates a WSDL file from that code. It's faster and easier than top-down 🏃♀️ BUT, and this is a big but, it's hard to keep interoperability, because each vendor's implementation ends up being vendor-specific 💀
For a NETCONF server, the WSDL file is already defined in [RFC4743], so there's no choice here: you have to go top-down 🙈 The rest of this section walks through the top-down approach for building a NETCONF server.
To build a SOAP-based NETCONF server top-down, you need a skeleton. A skeleton is a library that a Web Services tool generates automatically from the WSDL file. If you're using Axis, the skeleton comes out as a Java library. From the same WSDL file you used for the stub code, you get skeleton files like NetconfBindingSkeleton.java, Hello.java, and GetConfigType.java 🎀
While the skeleton code is being generated, you can also set up the development environment 🛠️ If you're building a Java-based NETCONF server, you need JDK and Axis, plus a servlet container such as Apache Tomcat [Tomcat]. To wire it up, copy the webapps\axis directory under the Axis directory into the webapps directory under the Tomcat directory 👑
4.2.1. Developing NETCONF Servers without Eclipse ✨
okay so bestie, let's start with the no-Eclipse route 💻🎀 Picture a Windows computer with no Eclipse in sight. The development environment for a NETCONF server lives there, and "myNetconfService.wsdl" is sitting in the "C:\NetconfServer" directory. To generate a skeleton, you run this command at 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.wsdlYou run that WSDL2Java command from the folder where the WSDL file lives 📂 You'll need to point it at wherever your Axis libraries are. "AXIS_HOME" is the environment variable that holds the directory where Axis is installed. Once the command finishes, you'll get a bunch of "*.java" files inside the "skeleton" directory you named in the command. Among them are "NetconfBindingSkeleton.java", "Hello.java", and "GetConfigType.java". You'll also find two extra files, "deploy.wsdd" and "undeploy.wsdd" 🧚 These are the ones you use to deploy a NETCONF server into a servlet container and to undeploy it again, respectively.
Next up, you add your own NETCONF server functions to the skeleton code, like "NetconfBindingImpl.java", whenever you need them 💅 Things like releasing log messages get added at this stage. After that, you compile the Java files by running this command at the command prompt. That produces the "*.class" files.
C:\NetconfServer>javac -classpath .;%AXIS_HOME%\lib\axis.jar;%
AXIS_HOME%\lib\jaxrpc.jar skeleton/*.javaAnd just like that, you've developed a NETCONF server 🥹 Copy those class files into the "webapps\axis\WEB-INFO\classes" directory of your Apache Tomcat directory. Last step: deploy the server by running this 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.wsddMake sure you run it from the directory where "deploy.wsdd" is located. That file was generated at the same time as the skeleton code, so it's already waiting for you 🌸 Once the deployment is done, the NETCONF server is ready to receive NETCONF messages from the NETCONF client. Iconic behaviour, honestly 👑
4.2.2. Developing NETCONF Servers Using Eclipse 🦋
okay, this is where the process gets a major glow-up 🔥 When you use Eclipse together with Apache Ant, everything from the previous section gets streamlined and runs all at once. You need two files for Apache Ant, "build.xml" and "build.properties". Figure 6 and Figure 7 show examples of each one, 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"/>
</fileset>
</path>
<target name="prepare">
<mkdir dir="${srcdir}"/>
<mkdir dir="${destdir}"/>
</target>
<target name="skeleton" depends="prepare">
<java classname="org.apache.axis.wsdl.WSDL2Java" fork
="Yes">
<arg value="-p"/>
<arg value="${skeletondir}"/>
<arg value="-o"/>
<arg value="${srcdir}"/>
<arg value="-s"/>
<arg value="-S"/>
<arg value="true"/>
<arg value="-d"/>
<arg value="Session"/>
<arg value="${wsdlpath}"/>
<classpath refid="axis-classpath"/>
</java>
</target>
<target name="compile" depends="skeleton">
<javac srcdir="${srcdir}" destdir="${destdir}"
encoding="UTF-8">
<classpath refid="axis-classpath"/>
</javac>
</target>
<target name="copy2axis" depends="compile">
<copy todir="${tomcat.axis.classesdir}" overwrite=
"true">
<fileset dir="${destdir}">
<include name="*.class"/>
<include name="*/*.class"/>
<include name="*/*/*.class"/>
</fileset>
</copy>
</target>
<target name="deploy" depends="copy2axis">
<java classname="org.apache.axis.client.AdminClient"
fork="Yes">
<arg value="-p"/>
<arg value="${deploy.port}"/>
<arg value="${deploy.ddname}"/>
<classpath refid="axis-classpath"/>
</java>
</target>
<target name="all" depends="deploy"/>
</project>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.wsddFigure 7: build.properties of NETCONF Servers
The "build.properties" file is where you tell everything where the WSDL file and "deploy.wsdd" file are. In Figure 7, both of those are set to live in the current directory, so it's all very cozy 🧸
When you run Apache Ant on Eclipse, it follows the steps shown in Figure 6 🫶 First, it generates the skeleton code. Once that's there, you can add your NETCONF server functions to the skeleton code, depending on what you want to build. Then you run Apache Ant again, and this time it compiles the skeleton code, which produces the class files of the NETCONF server. Ant copies those class files over to the Tomcat directory and deploys the server. After that, the NETCONF server is accessible to the NETCONF client. Literally so efficient 😭✨
4.2.3. Developing NETCONF Servers with C Programming Language 💜
okay so here's the plot twist 🌈 Network equipment doesn't always have room for a whole Java environment, because memory capacity can be limited. And the platform might not support a Web Services tool at all. In that case, you may need to implement SOAP as well as the NETCONF server in C on the network equipment itself. It's giving low-level energy, and I'm here for it 💅
To build a NETCONF server that can receive NETCONF messages sent over SOAP/HTTP, the network equipment may have an HTTP daemon and a NETCONF service provider. You can use a commonly used HTTP daemon 🍓 A SOAP module can be added to the HTTP daemon, acting as a connector between the HTTP daemon and the NETCONF service provider. You may also develop the NETCONF service provider, which parses NETCONF messages sent from the NETCONF client and sends reply NETCONF messages back toward the client.
Here's the flow: when the HTTP daemon receives a SOAP message sent over HTTP, it hands that message to the SOAP module built into the daemon. The SOAP module strips off the SOAP header and passes the NETCONF messages along to the NETCONF service provider. The service provider then parses those NETCONF messages and configures the network equipment accordingly 🎀 Main character energy, truly.
5. Security Considerations 🔐
The security considerations of [RFC4741] and [RFC4743] apply to this document. Anyone implementing or using SOAP-based NETCONF clients and servers should take these considerations into account 🙈
As [RFC4743] spells out in its security considerations section, transport-level security (things like user authentication and encryption of the transport protocol) has to be ensured by TLS (Transport Layer Security) when using the NETCONF SOAP binding. So security has to be delivered in the form of NETCONF/SOAP/HTTPS. This part is seriously important, bestie. Do not skip it. 💀
6. Acknowledgements 🌸
Extensive input came 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 also reviewed this document and gave valuable input: Jari Arkko, Pasi Eronen, Chris Newman, Tim Polk, David Ward, Magnus Westerlund, and Christian Vogt. Thank you all, you're the real MVPs 👑🫶
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>
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.comYoshifumi 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.netHiroyasu 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.netMakoto 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.comHideki 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.comFull Copyright Statement ✨
Okay bestie, copyright time 🎀 The IETF Trust owns the copyright on this one (2008) 💅 This document is covered by the rights, licenses, and restrictions in BCP 78, and the authors keep all their rights except where BCP 78 says otherwise 🫶
This document and everything in it is handed over "AS IS" 😭 The contributor, the organization they represent or are sponsored by (if any), the Internet Society, the IETF Trust, and the Internet Engineering Task Force all say no to every warranty, whether it's stated or implied 🙈 That includes no promise that using the info won't infringe anyone's rights, and no implied promise of merchantability or fitness for a particular purpose 💀 Not them being mean, just legal being legal.
Intellectual Property
Here's the tea on IP drama 🍓 The IETF doesn't take a side on whether any Intellectual Property Rights or other rights might cover the technology in this document, or how much license might be available for them. It also doesn't claim it went digging to find any such rights 🕵️♀️ If you want the procedures for rights in RFC documents, check BCP 78 and BCP 79 💜
Copies of IPR disclosures sent to the IETF Secretariat, plus any assurances that licenses will be available, or the results of anyone trying to get a general license or permission to use proprietary rights for implementing or using this spec, can be found in the IETF's online IPR repository at http://www.ietf.org/ipr 🌸
The IETF also invites anyone who knows about copyrights, patents, patent applications, or other proprietary rights that might cover technology needed to implement this standard to let them know. Send that info to the IETF at ietf-ipr@ietf.org 🦋 Spill it, we want to hear it ✨
📦 where this page comes from
- ietf: rfc5381 2008-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms