idnits 2.17.1 draft-iijima-netconf-soap-implementation-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 19. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1066. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1077. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1084. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1090. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 7 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (Aug 19, 2008) is 5728 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '0' on line 448 -- Looks like a reference, but probably isn't: '1' on line 454 ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) -- Obsolete informational reference (is this intentional?): RFC 2629 (Obsoleted by RFC 7749) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Iijima 3 Internet-Draft Y. Atarashi 4 Intended status: Informational H. Kimura 5 Expires: February 20, 2009 M. Kitani 6 Alaxala Networks Corp. 7 H. Okita 8 Hitachi, Ltd. 9 Aug 19, 2008 11 Experience of implementing NETCONF over SOAP 12 draft-iijima-netconf-soap-implementation-10 14 Status of this Memo 16 By submitting this Internet-Draft, each author represents that any 17 applicable patent or other IPR claims of which he or she is aware 18 have been or will be disclosed, and any of which he or she becomes 19 aware will be disclosed, in accordance with Section 6 of BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on February 20, 2009. 39 Abstract 41 This document describes how the authors developed a SOAP (Simple 42 Object Access Protocol)-based NETCONF client and server. When SOAP 43 is used as a transport protocol for NETCONF, various kinds of 44 development tools are available. By making full use of these tools, 45 developers can significantly reduce their workload. The authors 46 developed an NMS (Network Management System) and network equipment 47 that can deal with NETCONF messages sent over SOAP. This document 48 aims to provide NETCONF development guidelines gained from the 49 experience of implementing a SOAP-based NETCONF client and server. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.1. NETCONF over SOAP . . . . . . . . . . . . . . . . . . . . 4 55 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2. NETCONF Development on Web Services Framework . . . . . . . . 5 57 2.1. WSDL as an Interface Description Language . . . . . . . . 5 58 2.2. Generation of APIs . . . . . . . . . . . . . . . . . . . . 6 59 3. Architecture of the NETCONF over SOAP Implementation . . . . . 7 60 3.1. SOAP Implementation in NMS . . . . . . . . . . . . . . . . 8 61 3.1.1. SOAP Parser in NMS . . . . . . . . . . . . . . . . . . 8 62 3.1.2. Session Maintenance in NMS . . . . . . . . . . . . . . 8 63 3.2. SOAP Implementation in the Network Equipment . . . . . . . 9 64 3.2.1. SOAP Parser in the Network Equipment . . . . . . . . . 9 65 3.2.2. Session Maintenance in the Network Equipment . . . . . 9 66 4. Guidelines for Developing NETCONF Clients and Servers . . . . 11 67 4.1. Procedures of Development of NETCONF Clients . . . . . . . 11 68 4.1.1. Developing NETCONF Clients without Eclipse . . . . . . 12 69 4.1.2. Developing NETCONF Clients using Eclipse . . . . . . . 14 70 4.2. Procedures of Development of NETCONF Servers . . . . . . . 16 71 4.2.1. Developing NETCONF Servers without Eclipse . . . . . . 17 72 4.2.2. Developing NETCONF Servers using Eclipse . . . . . . . 18 73 4.2.3. Developing NETCONF Servers with C Programming 74 Language . . . . . . . . . . . . . . . . . . . . . . . 20 75 5. Security Considerations . . . . . . . . . . . . . . . . . . . 22 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 77 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 24 78 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 79 8.1. Normative References . . . . . . . . . . . . . . . . . . . 25 80 8.2. Informative References . . . . . . . . . . . . . . . . . . 25 81 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 26 82 A.1. draft-iijima-netconf-soap-implementation-10 . . . . . . . 26 83 A.2. draft-iijima-netconf-soap-implementation-09 . . . . . . . 26 84 A.3. draft-iijima-netconf-soap-implementation-08 . . . . . . . 26 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 86 Intellectual Property and Copyright Statements . . . . . . . . . . 31 88 1. Introduction 90 1.1. NETCONF over SOAP 92 This document is not a product from the NETCONF WG but a report on 93 the experience acquired by individual developers. 95 SOAP (Simple Object Access Protocol) was specified in [RFC4743] as 96 one of the transport protocols for NETCONF. It is designed to use 97 XML (eXtensible Markup Language) as its description language, which 98 is a fundamental messaging technology for Web services. For this 99 reason, SOAP is well suited to the NETCONF protocol and can be 100 deployed widely. 102 To develop a SOAP-based NETCONF client and server, several 103 development tools are available as open-source software. The authors 104 developed a SOAP-based NETCONF client and server by using available 105 development tools. The SOAP-based NETCONF client was developed by 106 utilizing Java APIs (Application Programming Interface) that are 107 automatically generated from the XSD (XML Schema Definition) file and 108 WSDL (Web Services Description Language) file obtained from [RFC4741] 109 and [RFC4743], respectively. The SOAP-based NETCONF client that the 110 authors developed acts as an NMS (Network Management System). The 111 SOAP-based NETCONF server that the authors developed runs on network 112 equipment and accepts NETCONF messages sent from the NETCONF client. 114 1.2. Motivation 116 The aim of this document is to describe why the authors believe SOAP 117 is practical as a transport protocol for NETCONF when an NMS is 118 developed. When developing an NMS that uses SOAP as its transport 119 protocol, development tools and procedures can be used according to 120 Web Services framework. This document also describes the experience 121 of implementing NETCONF over SOAP so that even those who have little 122 knowledge of SOAP can start developing a SOAP-based NETCONF client 123 and server. 125 2. NETCONF Development on Web Services Framework 127 SOAP is a fundamental messaging technology for Web Services. 128 Therefore, if SOAP is used as a transport protocol for NETCONF, a 129 network configuration performed by NETCONF is achieved on the Web 130 Services framework. In this section, the overall architecture of Web 131 Services is described. 133 +----------------+ +----------------------------+ 134 | Format | | Register / Search | 135 | | | | 136 | XML | | UDDI | 137 | | | (Universal Description, | 138 | | | Discovery and Integration) | 139 | | +----------------------------+ 140 | | +----------------------------+ +----------------+ 141 | | | Service Description | | API | 142 | | | | | | 143 | | | WSDL | | JAXM | 144 | | +----------------------------+ | (Java API for | 145 | | +----------------------------+ | XML Messaging) | 146 | | | Fundamental Messaging | | JAX-RPC | 147 | | | | | (Java API for | 148 | | | SOAP | | XML / RPC) | 149 +----------------+ +----------------------------+ +----------------+ 150 +----------------------------+ 151 | Transport | 152 | | 153 | HTTP, HTTPS... | 154 +----------------------------+ 156 Figure 1: Overall architecture of Web Services 158 As depicted in Figure 1, peripheral technologies around SOAP/HTTP are 159 well developed. Therefore, if SOAP/HTTP is chosen as a transport 160 layer for the NETCONF protocol, the NMS development based on the Web 161 Services framework can choose from different optional services and 162 might be less expensive based on the use of already available 163 services. 165 2.1. WSDL as an Interface Description Language 167 WSDL [WSDL] defines how SOAP messages are exchanged between Web 168 Services entities. Interfaces of Web Services entities are 169 automatically generated by development tools when importing a WSDL 170 file. Interfaces generated in this manner act as APIs. For the 171 development of an NMS only these APIs are necessary; there is no need 172 to use SOAP directly. 174 Useful tools that can import a WSDL file are available with SOAP. 175 For instance, Apache Axis [Axis] generates an interface from a WSDL 176 file and is a widely used SOAP implementation middleware. 178 2.2. Generation of APIs 180 As described in the previous section, APIs are generated from a WSDL 181 file by development tools such as Apache Axis. Such APIs are in the 182 form of a Java library and act as programming interfaces for an NMS. 183 By using these APIs an NMS can send SOAP messages to Web Services 184 entities. 186 3. Architecture of the NETCONF over SOAP Implementation 188 The architecture of the NETCONF over SOAP implementation is shown in 189 Figure 2. A NETCONF implementation residing in an NMS works as a 190 NETCONF client while network equipment acts as a NETCONF server. In 191 this document, we call NETCONF-client and NETCONF-server 192 implementations a NETCONF application and a NETCONF service provider, 193 respectively. A SOAP implementation may be installed on both the NMS 194 and the network equipment. Each instance of the SOAP implementations 195 exchanges SOAP messages based on WSDL, as described in [RFC4743]. If 196 Java libraries generated from the WSDL are provided in the NMS, 197 engineers can develop a NETCONF application, which configures network 198 equipment via the NETCONF protocol, by utilizing the Java library. 199 There is no need for engineers to use XML or SOAP directly. 201 +---------------------------+ +---------------------------+ 202 | NETCONF Client | | NETCONF Server | 203 | (NMS) | | (Network Equipment) | 204 | +---------------------+ | | +---------------------+ | 205 | | NETCONF application | | | | NETCONF service | | 206 | | | | | | provider | | 207 | +---------------------+ | | +---------------------+ | 208 | +---------------------+ | | | 209 | | Java library | | | | 210 | +---------------------+ | | | 211 | +---------------------+ | | +---------------------+ | 212 | | SOAP Implementation | | | | SOAP Implementation | | 213 | | (Apache Axis) | | | | | | 214 | +---------------------+ | | +---------------------+ | 215 +-------^----------|--------+ +-------^----------|--------+ 216 | | rpc-request | | 217 | +----- /SOAP ----+ | 218 | / HTTP(S) | 219 | | 220 | rpc-reply | 221 +---------------- /SOAP ---------------+ 222 / HTTP(S) 224 Figure 2: Architecture of NETCONF implementation using SOAP 226 The SOAP implementation in both the NMS and network equipment is 227 explained in detail in the following sections. 229 3.1. SOAP Implementation in NMS 231 Several SOAP implementations appropriate for use in an NMS are 232 available today. Apache Axis is one such widely used implementation. 234 Axis works as a SOAP implementation and an NMS-development tool. For 235 instance, WSDL2Java, one of Axis' tools, generates Java-class files 236 from a WSDL file. Another tool called Java2WSDL does the opposite: 237 it generates a WSDL file from Java-class files. Consequently, 238 various benefits can be obtained if Axis is introduced as a SOAP 239 implementation. 241 To develop a NETCONF application that is capable of various functions 242 such as releasing log messages, Java-class files generated by the 243 Axis tool may be extended by adding more functions. By utilizing 244 these Java libraries, engineers can easily develop NETCONF 245 applications. 247 3.1.1. SOAP Parser in NMS 249 The SOAP Parser function is performed entirely by a SOAP 250 implementation such as Apache Axis. 252 3.1.2. Session Maintenance in NMS 254 When exchanging NETCONF messages between an NMS and network 255 equipment, a NETCONF session has to be maintained on both sides, as 256 described in [RFC4741]. 258 In [RFC4743], HTTP is specified as an option of an underlying 259 protocol for NETCONF over SOAP. When HTTP is used for that purpose, 260 it is also specified that a NETCONF session will be supported by an 261 HTTP connection. However HTTP is a stateless protocol; that is, HTTP 262 cannot process a user's request according to the state resulting from 263 the user's previous request. Unless the state is kept at the HTTP- 264 level, a different NETCONF service provider will be invoked every 265 time the NETCONF application sends a NETCONF message to the NETCONF 266 service provider. To ensure that the same NETCONF service provider 267 is used every time the NETCONF application sends a NETCONF message, 268 the state of the HTTP connection must be maintained. Accordingly, a 269 cookie field inside an HTTP header was devised for maintaining the 270 state of an HTTP connection. We therefore used such a cookie field 271 to maintain the state of the HTTP connection over which the NETCONF- 272 session maintenance is ensured. 274 For example, the implemented NETCONF-session maintenance in the NMS 275 works as follows. After the NMS sends a NETCONF hello message to the 276 network equipment, the NETCONF service provider in the network 277 equipment allocates a session identifier for the NETCONF application 278 in the NMS and writes it inside the element of a replying 279 NETCONF hello message, as described in [RFC4741]. At the same time, 280 the network equipment writes the same value in the cookie field 281 inside an HTTP header. After that, a SOAP message encompassing the 282 replying NETCONF hello message is added. When the NMS receives the 283 newly allocated session identifier from the replying NETCONF hello 284 message, the NETCONF application stores it and writes it inside a 285 element for subsequent NETCONF request messages and in a 286 cookie field for subsequent HTTP headers. By recognizing the session 287 identifier in NETCONF request messages and the cookie field in HTTP 288 headers, the network equipment can maintain both a NETCONF session 289 and the state of an HTTP connection. The NETCONF session is 290 maintained over the maintained state of the HTTP connection. The 291 stored session identifier is erased when the NMS sends a NETCONF 292 close-session message and receives a NETCONF response message from 293 the network equipment. 295 3.2. SOAP Implementation in the Network Equipment 297 To accept SOAP messages sent from the NMS, it is also necessary to 298 provide SOAP in the network equipment. As in the case of NMS, some 299 free SOAP implementations are available today for installation on 300 network equipment. However, the memory capacity of the network 301 equipment might be limited. Therefore, the SOAP implementation may 302 be chosen taking memory capacity into consideration. In some cases, 303 a memory-saving method will be required when implementing SOAP in the 304 network equipment. 306 3.2.1. SOAP Parser in the Network Equipment 308 A SOAP header inside the SOAP envelope is defined as optional. 309 Therefore, the module that processes the SOAP header can be omitted 310 if the memory capacity in the network equipment is insufficient. In 311 this case, a SOAP parser in the network equipment is allowed to parse 312 only mandatory parts of a SOAP envelope. 314 3.2.2. Session Maintenance in the Network Equipment 316 To maintain NETCONF sessions with the NMS, the NETCONF service 317 provider in the network equipment has to provide a session identifier 318 to the NMS, as described in [RFC4741]. 320 For example, the implemented NETCONF-session maintenance in the 321 network equipment works as follows. When the network equipment 322 receives a NETCONF hello message from the NMS, the NETCONF service 323 provider in the network equipment sets a session identifier inside 324 the element of a replying NETCONF hello message, as 325 described in [RFC4741]. At the same time, the network equipment also 326 sets the same value in the cookie field inside an HTTP header. After 327 that, a SOAP message encompassing the replying NETCONF hello message 328 is added. The cookie field inside the HTTP header is used for 329 maintaining the state of the HTTP connection over which the NETCONF- 330 session maintenance is ensured. The network equipment then sends an 331 HTTP response message to the NMS. When the network equipment 332 receives a NETCONF close-session message from the NMS, it erases the 333 stored session identifier. 335 4. Guidelines for Developing NETCONF Clients and Servers 337 In the case of SOAP transport mapping, sharing information on the 338 kinds of development tools that are available would help developers 339 start developing SOAP-based NETCONF clients and servers. That would 340 contribute to the rapid deployment of SOAP-based NETCONF clients and 341 servers. 343 4.1. Procedures of Development of NETCONF Clients 345 To develop a SOAP-based NETCONF client, a stub code may be generated. 346 A stub is a library generated automatically from WSDL by a Web 347 Services tool and that acts as a group of APIs. When using Apache 348 Axis as a Web Services tool, a generated stub is in the form of Java 349 APIs. These Java APIs display interfaces of a Web Service as if they 350 are methods capable of configuring a local machine. 352 The WSDL file named "netconf-soap_1.0.wsdl", which is selected from 353 [RFC4743], specifies NETCONF messages to be exchanged between the 354 NETCONF client and server. These NETCONF messages are the "hello" 355 message and "rpc" message. Therefore, stub codes for creating the 356 "hello" message and "rpc" message are generated from "netconf- 357 soap_1.0.wsdl". However, the file "netconf- soap_1.0.wsdl" is not 358 sufficient because no service element is specified. 360 In "myNetconfService.wsdl", which is also selected from [RFC4743], a 361 service element is specified and "netconf-soap_1.0.wsdl" is imported. 362 Stub codes generated from those WSDL files are found in files such as 363 "Netconf.java", "NetconfLocator.java", and "NetconfBindingStub.java". 365 When interfaces are used to operate the NETCONF protocol in the 366 manner of "get-config" and "edit-config", for example, an XML schema 367 file named "netconf.xsd", which is selected from [RFC4741], is used 368 by being imported into "netconf-soap_1.0.wsdl". Using the XML 369 schema, methods of operating the NETCONF protocol are generated in 370 files such as "GetConfigType.java" and "EditConfigType.java". 372 When interfaces are used to configure network functions at the 373 network equipment, a data model of each network function has to be 374 defined in the style of an XML schema. The XML schema may be 375 imported into "netconf-soap_1.0.wsdl" in the same manner as that of 376 the XML schema in [RFC4741]. 378 The connection between the NETCONF schema and a data model should be 379 made by inserting the following attribute into elements of each data 380 model. This attribute is defined in the XML schema in [RFC4741]. 382 385 Consequently, using "myNetconfService.wsdl" to import "netconf- 386 soap_1.0.wsdl", NETCONF schema, and the data model makes it possible 387 to generate stub files containing interfaces to configure network 388 equipment. 390 When stub codes are generated, the development environment may be 391 arranged as well. The development of a Java-based NETCONF client may 392 use JDK (Java Development Kit) [JDK] and Apache Axis. In addition, 393 using some IDE (Integrated Development Environment) such as Eclipse 394 [Eclipse] with Apache Ant [Ant] and NetBeans [NetBeans] would reduce 395 the developer workload significantly. When Eclipse is used as an 396 IDE, first, the library (*.jar files) of Axis has to be added to the 397 development project's build path as an external library. The library 398 of Axis acts as a SOAP library, so there is no need to be concerned 399 about SOAP messaging when programming a NETCONF client using the 400 library of Axis. 402 4.1.1. Developing NETCONF Clients without Eclipse 404 Given that development of a NETCONF client is carried out in the 405 environment of a Windows computer without Eclipse, and that 406 "myNetconfService.wsdl" is placed in the "C:\NetconfClient" 407 directory, a stub is generated by executing the following command in 408 the command prompt. 410 C:\NetconfClient>java -classpath .;%AXIS_HOME%\lib\axis.jar;% 411 AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME% 412 \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery- 413 0.2.jar;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar 414 org.apache.axis.wsdl.WSDL2Java -p stub myNetconfService.wsdl 416 In the directory where the WSDL file is located, the WSDL2Java 417 command is executed. Locations of each Axis library have to be 418 specified. The environment variable of "AXIS_HOME" is the directory 419 where Axis is installed. By executing the above command, files with 420 an extension of "*.java" are generated in the "stub" directory, which 421 is specified by the above command. Inside the stub directory, we can 422 find files such as "NetconfBindingStub.java", "Hello.java", and 423 "GetConfigType.java". 425 Next, it is necessary to compile these files by executing the 426 following command in the command prompt. 428 C:\NetconfClient>javac -classpath .;%AXIS_HOME%\lib\axis.jar;% 429 AXIS_HOME%\lib\jaxrpc.jar stub/*.java 430 After the compilation of those java files, "*.class" files are 431 generated. After the compiling is done, the source code of the 432 NETCONF client has to be written. Sample source code of the NETCONF 433 client is shown in Figure 3. This NETCONF client is written by 434 utilizing stub classes and interfaces, which are imported into the 435 local package and referenced. 437 import org.apache.axis.types.UnsignedInt; 438 import org.apache.axis.types.*; 440 public class NetconfClient { 441 /** 442 * @param args 443 */ 444 public static void main(String[] args) { 445 // TODO Auto-generated method stub 446 try{ 447 NetconfClient client = new NetconfClient(); 448 java.net.URL url = new java.net.URL(args[0]); 449 stub.Netconf netconf = 450 new stub.NetconfLocator(); 451 stub.NetconfPortType stubNetconf = 452 netconf.getnetconfPort(url); 454 URI[] uri = new URI[1]; 455 stub.holders.HelloCapabilitiesHolder 456 capability = new 457 stub.holders.HelloCapabilitiesHolder(uri); 459 UnsignedInt id = new UnsignedInt(); 460 id.setValue(1); 461 org.apache.axis.holders.UnsignedIntHolder 462 holder = new 463 org.apache.axis.holders.UnsignedIntHolder(id) 464 ; 465 stubNetconf.hello(capability, holder); 466 }catch(Exception e){ 467 e.printStackTrace(); 468 } 469 } 470 } 472 Figure 3: Sample source code of NETCONF clients 474 To add functions such as the release of log messages, these functions 475 have to be incorporated at this stage. Again, the NETCONF client is 476 developed by compiling its source codes. 478 4.1.2. Developing NETCONF Clients using Eclipse 480 When we use Eclipse and Apache Ant, the procedures described in the 481 previous section are significantly simplified and executed at one 482 time. In this case, files named "build.xml" and "build.properties" 483 are required for Apache Ant. 485 The file named "build.xml" is written in XML and seen by Apache Ant 486 when Apache Ant is running on Eclipse. The file specifies how Apache 487 Ant behaves. According to the descriptions of the file, Apache Ant 488 compiles source codes, generates JAR (Java ARchive) file, and so on. 489 On the other hand, the file named "build.properties" specifies 490 properties of the development environment where Apache Ant runs. 491 This file is referred to by the "build.xml" file. 493 Examples of "build.xml" and "build.properties" are shown in Figure 4 494 and Figure 5, respectively. 496 497 498 499 500 501 502 503 504 505 506 507 508 510 511 512 513 514 515 516 517 518 519 521 522 523 524 525 526 527 528 530 Figure 4: build.xml of NETCONF clients 532 axis.libdir=C:/axis-1_4/lib 533 srcdir=src 534 destdir=classes 535 stub.stubdir=stub 536 stub.wsdlpath=myNetconfService.wsdl 537 stub.jar=NETCONF.jar 539 Figure 5: build.properties of NETCONF clients 541 The location of the WSDL file should be specified in the 542 "build.properties" file. In the case shown in Figure 5, the location 543 of the WSDL file is specified as being under the current directory. 545 By running Apache Ant on Eclipse, the steps specified in Figure 4 are 546 taken. First, stub codes are generated. Then, compiling of those 547 stub codes is executed. We were careful about the encoding style 548 used for the compiling. After the compilation, Apache Ant will 549 generate a JAR file, which is the output that compresses all stub 550 files (*.class) and acts as a library. In this example, the name 551 "NETCONF.jar" is specified in Figure 5. The "NETCONF.jar" file also 552 has to be added to the build path of the development project as an 553 external library. 555 After the "NETCONF.jar" file is added to the build path of the 556 development project, source codes of the NETCONF client can be 557 written by utilizing stub classes and interfaces. Source codes like 558 the one shown in Figure 3 can be written. By running Apache Ant 559 again, the source code of the NETCONF client is compiled. The 560 NETCONF client is developed in this manner. 562 4.2. Procedures of Development of NETCONF Servers 564 In the Web Services framework, there are two approaches for 565 developing a Web Services provider, namely a NETCONF server. One is 566 called the top-down approach, and the other is called the bottom-up 567 approach. The top-down approach is carried out by first designing a 568 WSDL file. A skeleton source code from the WSDL file is then 569 generated by using a Web Services tool such as Apache Axis. The 570 generated skeleton code is just a template of the Web Services 571 provider's source code. Therefore, even though the Web Services 572 provider's skeleton code works on its own, if additional functions 573 were necessary, the generated skeleton code would require additional 574 source codes. This approach is superior to the bottom-up approach in 575 terms of interoperability because the specification is already 576 defined in the WSDL file. All vendors have to be in compliance with 577 the WSDL file. 579 In contrast, the bottom-up approach is carried out by first creating 580 Web Services from source code (e.g., Java bean) and then generating a 581 WSDL file from the source code by using a Web Services tool such as 582 Axis. This approach is faster and easier than the top-down approach. 583 However, in the bottom-up approach, it is difficult to ensure 584 interoperability since implementation of a Web Services becomes 585 vendor-specific. 587 When developing a NETCONF server, the WSDL file is already defined in 588 [RFC4743], so there is no choice but to develop the NETCONF server 589 using the top-down approach. The remainder of this section describes 590 the top-down approach for developing a NETCONF server. 592 To develop a SOAP-based NETCONF server using the top-down approach, a 593 skeleton code is necessary. A skeleton is a library, which is also 594 generated automatically from WSDL by a Web Services tool. When using 595 Axis as a Web Services tool, the generated skeleton is in the form of 596 a Java library. From the same WSDL file as that used for generating 597 the stub code, skeleton codes are generated in files such as 598 "NetconfBindingSkeleton.java", "Hello.java", and 599 "GetConfigType.java". 601 When skeleton codes are being generated, the development environment 602 may be arranged as well. Moreover, when a Java-based NETCONF server 603 is being developed, in addition to JDK and Axis, a servlet container 604 such as Apache Tomcat [Tomcat] is necessary. The "webapps\axis" 605 directory under the Axis directory has to be copied to the "webapps" 606 directory under the Tomcat directory. 608 4.2.1. Developing NETCONF Servers without Eclipse 610 Given that the development environment of a NETCONF server is created 611 in the environment of a Windows computer without Eclipse and 612 "myNetconfService.wsdl" is placed in the "C:\NetconfServer" 613 directory, a skeleton is generated by executing the following command 614 in the command prompt. 616 C:\NetconfServer>java -classpath .;%AXIS_HOME%\lib\axis.jar;% 617 AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME% 618 \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery- 619 0.2.jar;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar 620 org.apache.axis.wsdl.WSDL2Java -p skeleton -s -S true -d Session 621 myNetconfService.wsdl 623 In the directory where the WSDL file is located, a WSDL2Java command 624 is executed. Locations of each Axis library should be specified. 625 The environment variable of "AXIS_HOME" is a directory where Axis is 626 installed. By executing the above command, files with an extension 627 of "*.java" are generated in the "skeleton" directory, which is 628 specified in the above command. Inside the skeleton directory, files 629 such as "NetconfBindingSkeleton.java", "Hello.java", and 630 "GetConfigType.java" exist. Furthermore, files named "deploy.wsdd" 631 and "undeploy.wsdd" are found. "Deploy.wsdd" and "undeploy.wsdd" are 632 used when deploying a NETCONF server in a servlet container and 633 undeploying a NETCONF server from a servlet container, respectively. 635 Adding source codes of NETCONF server functions to skeleton codes 636 such as "NetconfBindingImpl.java" is required as the need arises. 638 Functions such as the release of log messages have to be added at 639 this stage. After that, by executing the following command in the 640 command prompt, compilation of java files is carried out. Doing so 641 will generate "*.class" files. 643 C:\NetconfServer>javac -classpath .;%AXIS_HOME%\lib\axis.jar;% 644 AXIS_HOME%\lib\jaxrpc.jar skeleton/*.java 646 A NETCONF server can be developed by following the above-described 647 procedures. These class files should be copied into the directory 648 "webapps\axis\WEB-INFO\classes" of the Apache Tomcat directory. 649 Finally, the NETCONF server is deployed by executing the following 650 command. 652 C:\NetconfServer>java -classpath .;%AXIS_HOME%\lib\axis.jar;% 653 AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME% 654 \lib\commons-logging-1.0.4.jar;%AXIS_HOME%\lib\commons-discovery- 655 0.2.jar org.apache.axis.client.AdminClient -p 832 depoy.wsdd 657 The command is executed in the directory where "deploy.wsdd" is 658 located. The file "deploy.wsdd" is generated at the same time the 659 skeleton code is generated. After deployment, the NETCONF server 660 receives NETCONF messages sent from the NETCONF client. 662 4.2.2. Developing NETCONF Servers using Eclipse 664 When Eclipse and Apache Ant are used, the procedures described in the 665 previous section are significantly simplified and executed at one 666 time. Files named "build.xml" and "build.properties" are required 667 for Apache Ant. Examples of "build.xml" and "build.properties" are 668 shown in Figure 6 and Figure 7, respectively. 670 671 672 673 674 675 676 677 678 679 680 681 682 683 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 701 702 703 704 705 707 708 709 710 711 712 713 714 715 717 718 719 720 721 722 723 724 726 Figure 6: build.xml of NETCONF servers 728 axis.libdir=C:/axis-1_4/lib 729 tomcat.axis.classesdir= 730 C:/Program Files/Apache Software Foundation/Tomcat 6.0/ 731 webapps/axis/WEB-INF/classes 732 srcdir=src 733 destdir=classes 734 skeletondir=skeleton 735 wsdlpath=myNetconfService.wsdl 736 deploy.port=832 737 deploy.ddname=src/skeleton/deploy.wsdd 739 Figure 7: build.properties of NETCONF servers 741 The locations of the WSDL file and "deploy.wsdd" file have to be 742 specified in the "build.properties" file. In Figure 7, the location 743 of the WSDL file and "deploy.wsdd" file are specified as being under 744 the current directory. 746 By running Apache Ant on Eclipse, the steps shown in Figure 6 are 747 followed. First, skeleton codes have to be generated. After the 748 skeleton codes are generated, source codes of the NETCONF server 749 functions may be added to the skeleton codes according to the 750 functions that developers intend to add. 752 Then, by running Apache Ant again, compiling of the skeleton codes is 753 executed. As a result, class files of the NETCONF server are 754 generated. Apache Ant copies these class files to the directory of 755 Tomcat and deploys the NETCONF server. After that, the NETCONF 756 server becomes accessible by the NETCONF client. 758 4.2.3. Developing NETCONF Servers with C Programming Language 760 When the NETCONF server for network equipment is being implemented, 761 memory capacity might be limited, so it might not be possible to 762 install a Java environment on the network equipment. The network- 763 equipment platform might not support a Web Services tool. In that 764 case, it may be necessary to implement SOAP as well as the NETCONF 765 server by using C programming language on the network equipment. 767 To develop a NETCONF server capable of receiving NETCONF messages 768 sent over SOAP/HTTP, the network equipment may have an HTTP daemon 769 and a NETCONF service provider. A commonly used HTTP daemon can be 770 used. A SOAP module may be added to the HTTP daemon as a connector 771 between the HTTP daemon and the NETCONF service provider. The 772 NETCONF service provider for parsing NETCONF messages sent from the 773 NETCONF client and sending reply NETCONF messages toward the NETCONF 774 client may be developed. 776 When an HTTP daemon receives a SOAP message that is sent over HTTP, 777 the message is handed over to the SOAP module incorporated in the 778 HTTP daemon. Then, the SOAP module removes the SOAP header and 779 passes NETCONF messages to the NETCONF service provider. After that, 780 the NETCONF service provider parses the NETCONF messages and 781 configures the network equipment accordingly. 783 5. Security Considerations 785 The security considerations of [RFC4741] and [RFC4743] are applicable 786 in this document. Implementers or users of SOAP-based NETCONF 787 clients and servers should take these considerations into account. 789 As specified in the security considerations section of [RFC4743], 790 transport-level security, such as authentication of users and 791 encryption of transport protocol, has to be ensured by TLS (Transport 792 Layer Security) in the case of NETCONF SOAP binding. That is, 793 security has to be provided in the form of NETCONF/SOAP/HTTPS. 795 6. IANA Considerations 797 This document has no actions for IANA. 799 7. Acknowledgements 801 This document was written using the xml2rfc tool described in RFC 802 2629 [RFC2629]. 804 Extensive input was received from the members of the NETCONF design 805 team, including: Andy Bierman, Simon Leinen, Bert Wijnen, Mehmet 806 Ersue, Ted Goddard, Ray Atarashi, Ron Bonica, and Dan Romascanu. The 807 following people have also reviewed this document and provided 808 valuable input: Jari Arkko, Pasi Eronen, Chris Newman, Tim Polk, 809 David Ward, Magnus Westerlund, and Christian Vogt. 811 8. References 813 8.1. Normative References 815 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 816 December 2006. 818 [RFC4743] Goddard, T., "Using NETCONF over the Simple Object Access 819 Protocol (SOAP)", RFC 4743, December 2006. 821 8.2. Informative References 823 [Ant] "Apache Ant" . 825 827 [Axis] "Web Services - Axis". 829 831 [Eclipse] "Eclipse". 833 835 [JDK] "Java SE". 837 839 [NetBeans] 840 "NetBeans". 842 844 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 845 June 1999. 847 [Tomcat] "Apache Tomcat". 849 851 [WSDL] "Web Service Description Language (WSDL) 1.1". 853 855 Appendix A. Change Log 857 A.1. draft-iijima-netconf-soap-implementation-10 859 o Update Section 3.1.2 to clarify that a session is needed only for 860 the NETCONF level and that session IDs can be carried as HTTP 861 cookies to maintain HTTP connection. 863 o Update Section 3.2.2 to clarify that a session is needed only for 864 the NETCONF level and that session IDs can be carried as HTTP 865 cookies to maintain HTTP connection. 867 A.2. draft-iijima-netconf-soap-implementation-09 869 o Change "it is not necessary to develop all of the surrounding 870 technologies from scratch. Hence, the development of a NETCONF- 871 based NMS is relatively easy when SOAP is chosen as a transport 872 protocol for NETCONF" to "the NMS development based on the Web 873 Services framework can choose from different optional services and 874 might be less expensive based on the use of already available 875 services" in Section 2 877 o Change "Apache Axis generates an interface from a WSDL file and 878 acts as a widely used SOAP implementation middleware" to "Apache 879 Axis generates an interface from a WSDL file and is a widely used 880 SOAP implementation middleware" in Section 2.1 882 o Change "HTTP is originally a stateless protocol. HTTP can not 883 process" to "HTTP is a stateless protocol and can not process" in 884 Section 3.1.2 886 o Change "the SOAP implementation in the network equipment must 887 provide a session identifier to the NMS" to "the SOAP 888 implementation in the network equipment may provide a session 889 identifier to the NMS" in Section 3.2.2 891 A.3. draft-iijima-netconf-soap-implementation-08 893 o Change awkward sentences to more natural ones throughout the 894 entire document 896 o Extend acronym of XSD in Section 1.1 898 o Delete WS-Security, WS-Reliability and WS-Transaction from 899 Figure 1 in order to avoid confusion 901 o Change "A SOAP implementation needs to be installed" to "A SOAP 902 implementation may be installed" in Section 3 904 o Change "Several SOAP implementations capable for an NMS are 905 available today. As one such free SOAP implementation, Apache 906 Axis is the widely used" to "Several SOAP implementations 907 appropriate for use in an NMS are available today. Apache Axis is 908 one such widely used implementation" in Section 3.1 910 o Change "Java-class files generated by the Axis tool need to be 911 extended" to "Java-class files generated by the Axis tool may be 912 extended" in Section 3.1 914 o Update Section 3.1.2 to clarify that NETCONF-level session 915 management is done on top of the HTTP-level session management and 916 that HTTP-level session management does not change the behavior of 917 the NETCONF-level session management. 919 o Update Section 3.1.2 to clarify that we used cookies in order to 920 ensure there is an HTTP connection between NMS and network 921 equipment. 923 o Delete description about MAC address from Section 3.1.2 in order 924 to avoid confusion 926 o Delete description about parsing of encodingStyle attribute from 927 Section 3.2.1 in order to avoid confusion 929 o Update Section 3.2.2 to clarify that NETCONF-level session 930 management is done on top of the HTTP-level session management and 931 that HTTP-level session management does not change the behavior of 932 the NETCONF-level session management. 934 o Update Section 3.2.2 to clarify that we used cookies in order to 935 ensure there is an HTTP connection between NMS and network 936 equipment. 938 o Delete description about MAC address from Section 3.2.2 in order 939 to avoid confusion 941 o Change "a stub code needs to be generated" to "a stub code may be 942 generated" in Section 4.1 944 o Change "The XML schema is required to be imported" to "The XML 945 schema may be imported" in Section 4.1 947 o Change "the development environment needs to be arranged" to "the 948 development environment may be arranged" in Section 4.1 950 o Change "The development of a Java-based NETCONF client needs JDK" 951 to "The development of a Java-based NETCONF client may use JDK" in 952 Section 4.1 954 o Move description about encoding style at the time of compiling 955 from Section 4.1.1 to Section 4.1.2 for understandability 957 o Change "the development environment needs to be arranged" to "the 958 development environment may be arranged" in Section 4.2 960 o Change "deploying the NETCONF server by executing the following 961 command is required" to "the NETCONF server is deployed by 962 executing the following command" in Section 4.2.1 964 o Change "source codes of the NETCONF server functions must be 965 added" to "source codes of the NETCONF server functions may be 966 added" in Section 4.2.2 968 o Removed "The NETCONF server is developed in this manner" from 969 Section 4.2.2 971 o Change Section 4.2.3 title from "Developing NETCONF Servers by C 972 Language Programming" to "Developing NETCONF Servers with C 973 Programming Language" 975 o Change "C programming" to "C programming language" in Section 976 4.2.3 978 o Change "the network equipment needs a HTTP daemon" to "the network 979 equipment may have an HTTP daemon" in Section 4.2.3 981 o Change "A SOAP module needs to be added" to "A SOAP module may be 982 added" in Section 4.2.3 984 o Change " The NETCONF service provider for parsing NETCONF messages 985 sent from the NETCONF client and sending reply NETCONF messages 986 toward the NETCONF client has to be developed" to " The NETCONF 987 service provider for parsing NETCONF messages sent from the 988 NETCONF client and sending reply NETCONF messages toward the 989 NETCONF client may be developed" in Section 4.2.3 991 o Add Acknowledgements 993 o Add RFC2629 in Informative References 995 o Add Change Log 997 Authors' Addresses 999 Iijima Tomoyuki 1000 Alaxala Networks Corp. 1001 Shin-Kawasaki Mitsui Bldg. 1002 890 Saiwai-ku Kashimada 1003 Kawasaki, Kanagawa 212-0058 1004 Japan 1006 Phone: +81-44-549-1735 1007 Fax: +81-44-549-1272 1008 Email: tomoyuki.iijima@alaxala.com 1010 Yoshifumi Atarashi 1011 Alaxala Networks Corp. 1012 Shin-Kawasaki Mitsui Bldg. 1013 890 Saiwai-ku Kashimada 1014 Kawasaki, Kanagawa 212-0058 1015 Japan 1017 Phone: +81-44-549-1735 1018 Fax: +81-44-549-1272 1019 Email: atarashi@alaxala.net 1021 Hiroyasu Kimura 1022 Alaxala Networks Corp. 1023 Shin-Kawasaki Mitsui Bldg. 1024 890 Saiwai-ku Kashimada 1025 Kawasaki, Kanagawa 212-0058 1026 Japan 1028 Phone: +81-44-549-1735 1029 Fax: +81-44-549-1272 1030 Email: h-kimura@alaxala.net 1031 Makoto Kitani 1032 Alaxala Networks Corp. 1033 Shin-Kawasaki Mitsui Bldg. 1034 890 Saiwai-ku Kashimada 1035 Kawasaki, Kanagawa 212-0058 1036 Japan 1038 Phone: +81-44-549-1735 1039 Fax: +81-44-549-1272 1040 Email: makoto.kitani@alaxala.com 1042 Hideki Okita 1043 Hitachi, Ltd. 1044 1-280 Higashi-Koigakubo 1045 Kokubunji, Tokyo 185-8601 1046 Japan 1048 Phone: +81-42-323-1111 1049 Fax: +81-42-327-7868 1050 Email: hideki.okita.pf@hitachi.com 1052 Full Copyright Statement 1054 Copyright (C) The IETF Trust (2008). 1056 This document is subject to the rights, licenses and restrictions 1057 contained in BCP 78, and except as set forth therein, the authors 1058 retain all their rights. 1060 This document and the information contained herein are provided on an 1061 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1062 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1063 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1064 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1065 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1066 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1068 Intellectual Property 1070 The IETF takes no position regarding the validity or scope of any 1071 Intellectual Property Rights or other rights that might be claimed to 1072 pertain to the implementation or use of the technology described in 1073 this document or the extent to which any license under such rights 1074 might or might not be available; nor does it represent that it has 1075 made any independent effort to identify any such rights. Information 1076 on the procedures with respect to rights in RFC documents can be 1077 found in BCP 78 and BCP 79. 1079 Copies of IPR disclosures made to the IETF Secretariat and any 1080 assurances of licenses to be made available, or the result of an 1081 attempt made to obtain a general license or permission for the use of 1082 such proprietary rights by implementers or users of this 1083 specification can be obtained from the IETF on-line IPR repository at 1084 http://www.ietf.org/ipr. 1086 The IETF invites any interested party to bring to its attention any 1087 copyrights, patents or patent applications, or other proprietary 1088 rights that may cover technology that may be required to implement 1089 this standard. Please address the information to the IETF at 1090 ietf-ipr@ietf.org.