draft-ietf-netconf-soap-03.txt   draft-ietf-netconf-soap-04.txt 
Network Working Group T. Goddard Network Working Group T. Goddard
Internet-Draft ICEsoft Technologies Inc. Internet-Draft ICEsoft Technologies Inc.
Expires: March 8, 2005 September 7, 2004 Expires: July 2, 2005 January 2005
Using the Network Configuration Protocol (NETCONF) Over the Simple Using the Network Configuration Protocol (NETCONF) Over the Simple
Object Access Protocol (SOAP) Object Access Protocol (SOAP)
draft-ietf-netconf-soap-03 draft-ietf-netconf-soap-04
Status of this Memo Status of this Memo
This document is an Internet-Draft and is subject to all provisions This document is an Internet-Draft and is subject to all provisions
of section 3 of RFC 3667. By submitting this Internet-Draft, each of section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of 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 is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with which he or she become aware will be disclosed, in accordance with
RFC 3668. RFC 3668.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on March 8, 2005. This Internet-Draft will expire on July 2, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). Copyright (C) The Internet Society (2005).
Abstract Abstract
The Network Configuration Protocol (NETCONF) is applicable to a wide The Network Configuration Protocol (NETCONF) is applicable to a wide
range of devices in a variety of environments. The emergence of Web range of devices in a variety of environments. The emergence of Web
Services gives one such environment, and is presently characterized Services gives one such environment, and is presently characterized
by the use of the Simple Object Access Protocol (SOAP). NETCONF by the use of the Simple Object Access Protocol (SOAP). NETCONF
finds many benefits in this environment: from the re-use of existing finds many benefits in this environment: from the re-use of existing
standards, to ease of software development, to integration with standards, to ease of software development, to integration with
deployed systems. Herein, we describe SOAP over HTTP and SOAP over deployed systems. Herein, we describe SOAP over HTTP and SOAP over
BEEP bindings that yield application protocols sufficient for BEEP bindings for NETCONF.
NETCONF.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. SOAP Background for NETCONF . . . . . . . . . . . . . . . . . 4 2. SOAP Background for NETCONF . . . . . . . . . . . . . . . . . 4
2.1 Use and Storage of WSDL and XSD . . . . . . . . . . . . . 4 2.1 Use and Storage of WSDL and XSD . . . . . . . . . . . . . 4
2.2 SOAP over HTTP . . . . . . . . . . . . . . . . . . . . . . 5 2.2 SOAP over HTTP . . . . . . . . . . . . . . . . . . . . . . 5
2.3 HTTP Drawbacks . . . . . . . . . . . . . . . . . . . . . . 5 2.3 HTTP Drawbacks . . . . . . . . . . . . . . . . . . . . . . 5
2.4 BCP56: On the Use of HTTP as a Substrate . . . . . . . . . 6 2.4 BCP56: On the Use of HTTP as a Substrate . . . . . . . . . 6
2.5 Important HTTP 1.1 Features . . . . . . . . . . . . . . . 6 2.5 Important HTTP 1.1 Features . . . . . . . . . . . . . . . 6
skipping to change at page 2, line 28 skipping to change at page 2, line 27
2.7.1 SOAP Feature Exploitation . . . . . . . . . . . . . . 7 2.7.1 SOAP Feature Exploitation . . . . . . . . . . . . . . 7
2.7.2 SOAP Headers . . . . . . . . . . . . . . . . . . . . . 8 2.7.2 SOAP Headers . . . . . . . . . . . . . . . . . . . . . 8
2.7.3 SOAP Faults . . . . . . . . . . . . . . . . . . . . . 8 2.7.3 SOAP Faults . . . . . . . . . . . . . . . . . . . . . 8
3. A SOAP Service for NETCONF . . . . . . . . . . . . . . . . . . 10 3. A SOAP Service for NETCONF . . . . . . . . . . . . . . . . . . 10
3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . 10 3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . 10
3.2 NETCONF Session Establishment . . . . . . . . . . . . . . 10 3.2 NETCONF Session Establishment . . . . . . . . . . . . . . 10
3.3 NETCONF Capabilities Exchange . . . . . . . . . . . . . . 10 3.3 NETCONF Capabilities Exchange . . . . . . . . . . . . . . 10
3.4 NETCONF Session Usage . . . . . . . . . . . . . . . . . . 10 3.4 NETCONF Session Usage . . . . . . . . . . . . . . . . . . 10
3.5 NETCONF Session Teardown . . . . . . . . . . . . . . . . . 11 3.5 NETCONF Session Teardown . . . . . . . . . . . . . . . . . 11
3.6 A NETCONF Over SOAP example . . . . . . . . . . . . . . . 11 3.6 A NETCONF Over SOAP example . . . . . . . . . . . . . . . 11
4. Security Considerations . . . . . . . . . . . . . . . . . . . 13 3.7 NETCONF SOAP WSDL . . . . . . . . . . . . . . . . . . . . 12
4.1 Integrity, Privacy, and Authentication . . . . . . . . . . 13 3.8 Sample Service Definition WSDL . . . . . . . . . . . . . . 14
4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 13 4. Security Considerations . . . . . . . . . . . . . . . . . . . 16
4.3 Environmental Specifics . . . . . . . . . . . . . . . . . 14 4.1 Integrity, Privacy, and Authentication . . . . . . . . . . 16
5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 16
5.1 Normative References . . . . . . . . . . . . . . . . . . . . 15 4.3 Environmental Specifics . . . . . . . . . . . . . . . . . 17
5.2 Informative References . . . . . . . . . . . . . . . . . . . 16 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 16 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
A. WSDL Definitions . . . . . . . . . . . . . . . . . . . . . . . 17 6.1 Normative References . . . . . . . . . . . . . . . . . . . . 19
A.1 NETCONF SOAP Binding . . . . . . . . . . . . . . . . . . . 17 6.2 Informative References . . . . . . . . . . . . . . . . . . . 20
A.2 Sample Service Definition . . . . . . . . . . . . . . . . 18 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 21
Intellectual Property and Copyright Statements . . . . . . . . 19 Intellectual Property and Copyright Statements . . . . . . . . 22
1. Introduction 1. Introduction
Given the use of XML [2] and the remote procedure call Given the use of XML [2] and the remote procedure call
characteristics, it is natural to consider a binding of the NETCONF characteristics, it is natural to consider a binding of the NETCONF
[1] operations to a SOAP [3] application protocol. This document [1] operations to a SOAP [3] application protocol. This document
proposes a binding of this form. proposes a binding of this form.
In general, SOAP is a natural application protocol for NETCONF, In general, SOAP is a natural messaging scheme for NETCONF,
essentially because of the remote procedure call character of both. essentially because of the remote procedure call character of both.
However, care must be taken with SOAP over HTTP as it is inherently However, care must be taken with SOAP over HTTP as it is inherently
synchronous and client-driven. SOAP over BEEP [15] is technically synchronous and client-driven. SOAP over BEEP [15] is technically
superior, but is not as widely adopted. superior, but is not as widely adopted.
Four basic topics are presented: SOAP specifics of interest to Four basic topics are presented: SOAP specifics of interest to
NETCONF, specifics on implementing NETCONF as a SOAP-based web NETCONF, specifics on implementing NETCONF as a SOAP-based web
service, security considerations, and an appendix with functional service, security considerations, and an appendix with functional
WSDL. In some sense, the most important part of the document is the WSDL. In some sense, the most important part of the document is the
brief WSDL document presented in the Appendix. With the right tools, brief WSDL document presented in Section 3.7. With the right tools,
the WSDL combined with the base NETCONF XML Schemas provide machine the WSDL combined with the base NETCONF XML Schemas provide machine
readable descriptions sufficient for the development of software readable descriptions sufficient for the development of software
applications using NETCONF. applications using NETCONF.
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 RFC 2119 [11]
2. SOAP Background for NETCONF 2. SOAP Background for NETCONF
Why introduce SOAP as yet another wrapper around what is already a Why introduce SOAP as yet another wrapper around what is already a
remote procedure call message? There are, in fact, both technical remote procedure call message? There are, in fact, both technical
and practical reasons. The technical reasons are perhaps less and practical reasons. The technical reasons are perhaps less
compelling, but let's examine them first. compelling, but let's examine them first.
The use of SOAP does offer a few technical advantages. SOAP is The use of SOAP does offer a few technical advantages. SOAP is
fundamentally an XML messaging scheme (which is capable of supporting fundamentally an XML messaging scheme (which is capable of supporting
remote procedure call) and it defines a simple message format remote procedure call) and it defines a simple message format
skipping to change at page 4, line 48 skipping to change at page 4, line 48
2.1 Use and Storage of WSDL and XSD 2.1 Use and Storage of WSDL and XSD
One of the advantages of using machine readable formats such as Web One of the advantages of using machine readable formats such as Web
Services Description Language (WSDL) [4] and XML Schemas [5] is that Services Description Language (WSDL) [4] and XML Schemas [5] is that
they can be used automatically in the software development process. they can be used automatically in the software development process.
With appropriate tools, WSDL and XSD can be used to generate classes With appropriate tools, WSDL and XSD can be used to generate classes
that act as remote interfaces or application specific data that act as remote interfaces or application specific data
structures. Other uses, such as document generation and service structures. Other uses, such as document generation and service
location, are also common. A great innovation found with many location, are also common. A great innovation found with many
XML-based definition languages is the use of hyperlinks for referring XML-based definition languages is the use of hyperlinks for referring
to documents containing supporting definitions. For instance, in to documents containing supporting definitions.
WSDL, the import statement
<import namespace="urn:ietf:params:xml:ns:netconf:base:1.0" <import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
location="http://iana.org/ietf/netconf/base_1.0.xsd"/> location="http://www.iana.org/assignments/xml-registry/
imports the definitions of XML types and elements from the base schema/netconf-base_1.0.xsd" />
NETCONF schema. Ideally, the file containing that schema is hosted For instance, in WSDL, the above import statement imports the
on a web server under the authority of the standards body that definitions of XML types and elements from the base NETCONF schema.
defined the schema. In this way, dependent standards can be built up Ideally, the file containing that schema is hosted on a web server
over time and all are accessible to automated software tools that under the authority of the standards body that defined the schema.
ensure adherence to the standards. Thus, it will gradually become as In this way, dependent standards can be built up over time and all
important for iana.org to host documents like are accessible to automated software tools that ensure adherence to
the standards. The IANA maintained registry for this purpose is
http://iana.org/ietf/netconf/base_1.0.xsd described in The IETF XML Registry [17].
as the IETF now hosts documents such as
http://www.ietf.org/rfc/rfc2616.txt
Note that WSDL declarations for SOAP over BEEP bindings are not yet Note that WSDL declarations for SOAP over BEEP bindings are not yet
standardized. standardized.
2.2 SOAP over HTTP 2.2 SOAP over HTTP
While it is true that SOAP focuses on messages and can be bound to While it is true that SOAP focuses on messages and can be bound to
different underlying protocols such as HTTP, SMTP, or BEEP, most different underlying protocols such as HTTP, SMTP, or BEEP, most
existing SOAP implementations support only HTTP or HTTP/TLS. existing SOAP implementations support only HTTP or HTTP/TLS.
skipping to change at page 6, line 29 skipping to change at page 6, line 26
Fundamentally, these concerns lie directly with SOAP over HTTP, Fundamentally, these concerns lie directly with SOAP over HTTP,
rather than the application of SOAP over HTTP to NETCONF. As BCP 56 rather than the application of SOAP over HTTP to NETCONF. As BCP 56
indicates, it is debatable whether HTTP is an appropriate protocol indicates, it is debatable whether HTTP is an appropriate protocol
for SOAP at all, and it is likely that BEEP would be a superior for SOAP at all, and it is likely that BEEP would be a superior
protocol for most SOAP applications. Unfortunately, SOAP over HTTP protocol for most SOAP applications. Unfortunately, SOAP over HTTP
is in common use and must be supported if the practical benefits of is in common use and must be supported if the practical benefits of
SOAP are to be realized. Note that the verbose nature of SOAP SOAP are to be realized. Note that the verbose nature of SOAP
actually makes it more readily processed by firewalls, albeit actually makes it more readily processed by firewalls, albeit
firewalls designed to process SOAP messages. firewalls designed to process SOAP messages.
It is very important that HTTP caches are not inserted between HTTP caches SHOULD NOT be inserted between NETCONF managers and
NETCONF managers and agents as NETCONF session state is tied to the agents as NETCONF session state is tied to the state of the
state of the underlying transport connection. Three defensive underlying transport connection. Three defensive actions can be
actions can be taken: taken:
o Prohibit caching through the use of HTTP headers Cache-Control and o Caching MUST be prohibited through the use of HTTP headers
Pragma: no-cache Cache-Control and Pragma: no-cache
o Ensure that HTTP proxies are not deployed within the management o HTTP proxies SHOULD NOT be deployed within the management network
network
o Use HTTPS o Use HTTPS
It is also possible to respond to the concern on the re-use of port It is also possible to respond to the concern on the re-use of port
80. A NETCONF SOAP service can be offered on any desired port, and 80. A NETCONF SOAP service can be offered on any desired port, and
it is recommended that a new standard port for SOAP over HTTP, or a it is recommended that a new standard port for SOAP over HTTP, or a
new standard port for NETCONF over SOAP (over HTTP) be defined. new standard port for NETCONF over SOAP (over HTTP) be defined, as
requested in the IANA considerations of this document.
2.5 Important HTTP 1.1 Features 2.5 Important HTTP 1.1 Features
HTTP 1.1 [8] includes two important features that provide for HTTP 1.1 [8] includes two important features that provide for
relatively efficient transport of SOAP messages. These features are relatively efficient transport of SOAP messages. These features are
"persistent connections" and "chunked transfer-coding". "persistent connections" and "chunked transfer-coding".
Persistent connections allow a single TCP connection to be used Persistent connections allow a single TCP connection to be used
across multiple HTTP requests. This permits multiple SOAP request/ across multiple HTTP requests. This permits multiple SOAP request/
response message pairs to be exchanged without the overhead of response message pairs to be exchanged without the overhead of
skipping to change at page 7, line 28 skipping to change at page 7, line 24
In terms of application to SOAP message exchanges, persistent In terms of application to SOAP message exchanges, persistent
connections are clearly important for performance reasons, and are connections are clearly important for performance reasons, and are
particularly important when it is the persistence of authenticated particularly important when it is the persistence of authenticated
connections that is at stake. When one considers that messages of connections that is at stake. When one considers that messages of
dynamic length are the rule rather than the exception for SOAP dynamic length are the rule rather than the exception for SOAP
messages, it is also clear that Chunking is very useful. In some messages, it is also clear that Chunking is very useful. In some
cases it is possible to buffer a SOAP response and determine its cases it is possible to buffer a SOAP response and determine its
length before sending, but the storage requirements for this are length before sending, but the storage requirements for this are
prohibitive for many devices. Together, these two features provide a prohibitive for many devices. Together, these two features provide a
good foundation for device management using SOAP over HTTP. good foundation for device management using SOAP over HTTP. HTTP
chunking and persistent connections SHOULD be used.
2.6 SOAP Over BEEP 2.6 SOAP Over BEEP
Although not widely adopted by the Web Services community, BEEP is an Although not widely adopted by the Web Services community, BEEP is an
excellent substrate for SOAP [16]. In particular, it provides for excellent substrate for SOAP [16]. In particular, it provides for
request/response message exchanges initiated by either BEEP peer and request/response message exchanges initiated by either BEEP peer and
allows the number of response messages to be arbitrary (including allows the number of response messages to be arbitrary (including
zero). The BEEP profile for SOAP simply makes use of a single BEEP zero). The BEEP profile for SOAP simply makes use of a single BEEP
channel for exchanging SOAP messages and benefits from BEEP's channel for exchanging SOAP messages and benefits from BEEP's
inherent strengths for message exchange over a single transport inherent strengths for message exchange over a single transport
skipping to change at page 8, line 30 skipping to change at page 8, line 27
2.7.3 SOAP Faults 2.7.3 SOAP Faults
A SOAP Fault is returned in the event of a NETCONF <rpc-error>. It A SOAP Fault is returned in the event of a NETCONF <rpc-error>. It
is constructed essentially as a wrapper for the <rpc-error>, but is constructed essentially as a wrapper for the <rpc-error>, but
allow SOAP processors to propagate the <rpc-error> to application allow SOAP processors to propagate the <rpc-error> to application
code using a language-appropriate exception mechanism. code using a language-appropriate exception mechanism.
A SOAP Fault is constructed from an <rpc-error> as follows: the SOAP A SOAP Fault is constructed from an <rpc-error> as follows: the SOAP
Fault faultcode is "Client" in the SOAP envelope namespace, the SOAP Fault faultcode is "Client" in the SOAP envelope namespace, the SOAP
Fault faultstring is the contents of the NETCONF <rpc-error> "tag", Fault faultstring is the contents of the NETCONF <rpc-error>
and the SOAP Fault detail is the original <rpc-error> structure. "error-tag", and the SOAP Fault detail is the original <rpc-error>
structure.
For instance, given the following <rpc-error>, For instance, given the following <rpc-error>,
<rpc-error message-id="102" <rpc-error xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <error-type>rpc</error-type>
<tag>EXAMPLE_MTU_RANGE</tag> <error-tag>MISSING_ATTRIBUTE</error-tag>
<error-code>128</error-code> <error-severity>error</error-severity>
<severity>error</severity> <error-info>
<statement>mtu 21050;</statement> <bad-attribute>message-id</bad-attribute>
<message>MTU 21050 on Ethernet/1 is <bad-element>rpc</bad-element>
outside range 256..9192</message> </error-info>
</rpc-error> </rpc-error>
the associated SOAP Fault message is the associated SOAP Fault message is
<soapenv:Envelope <soapenv:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> xmlns:SOAP-ENV=
"http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body> <soapenv:Body>
<soapenv:Fault> <soapenv:Fault>
<faultcode>soapenv:Client</faultcode> <faultcode>soapenv:Client</faultcode>
<faultstring>EXAMPLE_MTU_RANGE</faultstring> <faultstring>MISSING_ATTRIBUTE</faultstring>
<detail> <detail>
<rpc-error message-id="102" <rpc-error xmlns=
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> "urn:ietf:params:xml:ns:netconf:base:1.0">
<tag>EXAMPLE_MTU_RANGE</tag> <error-type>rpc</error-type>
<error-code>128</error-code> <error-tag>MISSING_ATTRIBUTE</error-tag>
<severity>error</severity> <error-severity>error</error-severity>
<statement>mtu 21050;</statement> <error-info>
<message>MTU 21050 on Ethernet/1 is <bad-attribute>message-id</bad-attribute>
outside range 256..9192</message> <bad-element>rpc</bad-element>
</error-info>
</rpc-error> </rpc-error>
</detail> </detail>
</soapenv:Fault> </soapenv:Fault>
</soapenv:Body> </soapenv:Body>
</soapenv:Envelope> </soapenv:Envelope>
3. A SOAP Service for NETCONF 3. A SOAP Service for NETCONF
3.1 Fundamental Use Case 3.1 Fundamental Use Case
skipping to change at page 10, line 26 skipping to change at page 10, line 26
3.2 NETCONF Session Establishment 3.2 NETCONF Session Establishment
A NETCONF over SOAP session is established by the initial message A NETCONF over SOAP session is established by the initial message
exchange on the underlying substrate. For HTTP, a NETCONF session is exchange on the underlying substrate. For HTTP, a NETCONF session is
established once a SOAP message is POSTed to the NETCONF web established once a SOAP message is POSTed to the NETCONF web
application URI. For BEEP, a NETCONF session is established once the application URI. For BEEP, a NETCONF session is established once the
BEEP profile for SOAP handshake establishes the SOAP channel. BEEP profile for SOAP handshake establishes the SOAP channel.
3.3 NETCONF Capabilities Exchange 3.3 NETCONF Capabilities Exchange
Capabilities exchange, if defined through a NETCONF RPC operation, Capabilities exchange is performed through the exchange of <hello>
can easily be accommodated in the SOAP binding. messages. In the case of SOAP over HTTP, the HTTP client MUST send
the first <hello> message. The case of SOAP over BEEP imposes no
ordering constraints.
3.4 NETCONF Session Usage 3.4 NETCONF Session Usage
NETCONF sessions are persistent for both performance and semantic NETCONF sessions are persistent for both performance and semantic
reasons. NETCONF session state contains the following: reasons. NETCONF session state contains the following:
1. Authentication Information 1. Authentication Information
2. Capability Information 2. Capability Information
3. Locks 3. Locks
4. Pending Operations 4. Pending Operations
5. Operation Sequence Numbers 5. Operation Sequence Numbers
skipping to change at page 11, line 13 skipping to change at page 11, line 14
the BEEP profile for SOAP [16]. the BEEP profile for SOAP [16].
3.5 NETCONF Session Teardown 3.5 NETCONF Session Teardown
To allow automated cleanup, NETCONF over SOAP session teardown takes To allow automated cleanup, NETCONF over SOAP session teardown takes
place when the underlying connection (in the case of HTTP) or channel place when the underlying connection (in the case of HTTP) or channel
(in the case of BEEP) is closed. Note that the root cause of such (in the case of BEEP) is closed. Note that the root cause of such
teardown may be the closure of the TCP connection under either HTTP teardown may be the closure of the TCP connection under either HTTP
or BEEP as the case may be. NETCONF managers and agents must be or BEEP as the case may be. NETCONF managers and agents must be
capable of programatically closing the transport connections capable of programatically closing the transport connections
associated with NETCONF sessions; thus, the HTTP or BEEP substrate associated with NETCONF sessions, such as in response to a
<close-session> operation; thus, the HTTP or BEEP substrate
implementation must expose this appropriately. implementation must expose this appropriately.
3.6 A NETCONF Over SOAP example 3.6 A NETCONF Over SOAP example
Since the proposed WSDL (in Appendix A.1) uses document/literal Since the proposed WSDL (in Section 3.7) uses document/literal
encoding, the use of a SOAP header and body has little impact on the encoding, the use of a SOAP header and body has little impact on the
representation of a NETCONF operation. This example shows HTTP/1.0 representation of a NETCONF operation. This example shows HTTP/1.0
for simplicity. Examples for HTTP/1.1 and BEEP would be similar. for simplicity. Examples for HTTP/1.1 and BEEP would be similar.
POST /netconf HTTP/1.0 C: POST /netconf HTTP/1.0
Content-Type: text/xml; charset=utf-8 C: Content-Type: text/xml; charset=utf-8
Accept: application/soap+xml, text/* C: Accept: application/soap+xml, text/*
Cache-Control: no-cache C: Cache-Control: no-cache
Pragma: no-cache C: Pragma: no-cache
Content-Length: 470 C: Content-Length: 467
C:
C: <?xml version="1.0" encoding="UTF-8"?>
C: <soapenv:Envelope
C: xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
C: <soapenv:Body>
C: <rpc message-id="101"
C: xmlns="xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
C: <get-config>
C: <filter type="subtree">
C: <top xmlns="http://example.com/schema/1.2/config">
C: <users/>
C: </top>
C: </filter>
C: </get-config>
C: </rpc>
C: </soapenv:Body>
C: </soapenv:Envelope>
The HTTP/1.0 response is also straightforward:
S: HTTP/1.0 200 OK
S: Content-Type: text/xml; charset=utf-8
S:
S: <?xml version="1.0" encoding="UTF-8"?>
S: <soapenv:Envelope
S: xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
S: <soapenv:Body>
S: <rpc-reply message-id="101"
S: xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
S: <data>
S: <top xmlns="http://example.com/schema/1.2/config">
S: <users>
S: <user>
S: <name>root</name>
S: <type>superuser</type>
S: <full-name>Charlie Root</full-name>
S: <dept>1</dept>
S: <id>1</id>
S: </company-info>
S: </user>
S: <user>
S: <name>fred</name>
S: <type>admin</type>
S: <full-name>Fred Flintstone</full-name>
S: <dept>2</dept>
S: <id>2</id>
S: </company-info>
S: </user>
S: </users>
S: </top>
S: </data>
S: </rpc-reply>
S: </soapenv:Body>
S: </soapenv:Envelope>
3.7 NETCONF SOAP WSDL
The following WSDL document assumes a hypothetical location for the
NETCONF schema.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope <definitions
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> xmlns="http://schemas.xmlsoap.org/wsdl/"
<soapenv:Body> xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/"
<rpc id="101" xmlns:tns="urn:ietf:params:xml:ns:netconf:soap:1.0"
xmlns="http://iana.org/ietf/netconf/base_1.0.xsd"> xmlns:netb="urn:ietf:params:xml:ns:netconf:base:1.0"
<get-config> targetNamespace="urn:ietf:params:xml:ns:netconf:soap:1.0"
<source> name="netconf-soap_1.0.wsdl">
<running/>
</source>
<config xmlns="http://example.com/schema/1.2/config">
<users/>
</config>
<format>xml</format>
</get-config>
</rpc>
</soapenv:Body>
</soapenv:Envelope>
The HTTP/1.0 response is also straightforward: <import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
location="http://www.iana.org/assignments/xml-registry/
schema/netconf-base_1.0.xsd"/>
HTTP/1.0 200 OK <types>
Content-Type: text/xml; charset=utf-8 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="urn:ietf:params:xml:ns:netconf:soap:1.0" >
<xsd:element name="capability" type="xsd:anyURI" />
<xsd:element name="capabilities">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="tns:capability"
maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="hello">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="tns:capabilities"
maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</types>
<message name="helloRequest">
<part name="in" element="tns:hello"/>
</message>
<message name="helloResponse">
<part name="out" element="tns:hello"/>
</message>
<message name="rpcRequest">
<part name="in" element="netb:rpc"/>
</message>
<message name="rpcResponse">
<part name="out" element="netb:rpc-reply"/>
</message>
<portType name="netconfPortType">
<operation name="rpc">
<input message="tns:rpcRequest"/>
<output message="tns:rpcResponse"/>
</operation>
<operation name="hello">
<input message="tns:helloRequest"/>
<output message="tns:helloResponse"/>
</operation>
</portType>
<binding name="netconfBinding" type="tns:netconfPortType">
<SOAP:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="hello">
<SOAP:operation/>
<input>
<SOAP:body use="literal"
namespace="urn:ietf:params:xml:ns:netconf:soap:1.0"/>
</input>
<output>
<SOAP:body use="literal"
namespace="urn:ietf:params:xml:ns:netconf:soap:1.0"/>
</output>
</operation>
<operation name="rpc">
<SOAP:operation/>
<input>
<SOAP:body use="literal"
namespace="urn:ietf:params:xml:ns:netconf:base:1.0"/>
</input>
<output>
<SOAP:body use="literal"
namespace="urn:ietf:params:xml:ns:netconf:base:1.0"/>
</output>
</operation>
</binding>
</definitions>
3.8 Sample Service Definition WSDL
The following WSDL document assumes a hypothetical location for the
NETCONF over SOAP WSDL definitions. A typical deployment of a device
manageable via NETCONF over SOAP would provide a service definition
similar to the following to identify the address of the device.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope <definitions
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> xmlns="http://schemas.xmlsoap.org/wsdl/"
<soapenv:Body> xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/"
<rpc-reply id="101" xmlns:nets="urn:ietf:params:xml:ns:netconf:soap:1.0"
xmlns="http://iana.org/ietf/netconf/base_1.0.xsd"> targetNamespace="urn:myNetconfService"
<config xmlns="http://example.com/schema/1.2/config"> name="myNetconfService.wsdl">
<users>
<user> <import namespace="urn:ietf:params:xml:ns:netconf:soap:1.0"
<name>root</name> location="http://www.iana.org/assignments/xml-registry/
<type>superuser</type> schema/netconf-soap_1.0.wsdl"/>
</user>
<user> <service name="netconf">
<name>fred</name> <port name="netconfPort" binding="nets:netconfBinding">
<type>admin</type> <SOAP:address location="http://localhost:8080/netconf"/>
</user> </port>
<user> </service>
<name>barney</name>
<type>admin</type> </definitions>
</user>
</users>
</config>
</rpc-reply>
</soapenv:Body>
</soapenv:Envelope>
4. Security Considerations 4. Security Considerations
NETCONF is used to access and modify configuration information, so NETCONF is used to access and modify configuration information, so
the ability to access this protocol should be limited to users and the ability to access this protocol should be limited to users and
systems that are authorized to view or modify the agent's systems that are authorized to view or modify the agent's
configuration data. configuration data.
Because configuration information is sent in both directions, it is Because configuration information is sent in both directions, it is
not sufficient for just the client or user to be authenticated with not sufficient for just the client or user to be authenticated with
skipping to change at page 13, line 35 skipping to change at page 16, line 35
is not available. is not available.
4.1 Integrity, Privacy, and Authentication 4.1 Integrity, Privacy, and Authentication
The NETCONF SOAP binding relies on an underlying secure transport for The NETCONF SOAP binding relies on an underlying secure transport for
integrity and privacy. Such transports are expected to include TLS integrity and privacy. Such transports are expected to include TLS
[12] and IPSec. There are a number of options for authentication [12] and IPSec. There are a number of options for authentication
(some of which are deployment-specific): (some of which are deployment-specific):
o within the transport (such as with TLS client certificates) o within the transport (such as with TLS client certificates)
o within HTTP (such as Digest Access Authentication [10]) o within HTTP (such as Digest Access Authentication [10])
o within SOAP (such as a digital signature in the header [18]) o within SOAP (such as a digital signature in the header [19])
HTTP, BEEP, and SOAP level authentication can be integrated with HTTP, BEEP, and SOAP level authentication can be integrated with
RADIUS [13] to support remote authentication databases. RADIUS [13] to support remote authentication databases.
4.2 Vulnerabilities 4.2 Vulnerabilities
The above protocols may have various vulnerabilities, and these may The above protocols may have various vulnerabilities, and these may
be inherited by NETCONF over SOAP. be inherited by NETCONF over SOAP.
NETCONF itself may have vulnerabilities due to the fact that an NETCONF itself may have vulnerabilities due to the fact that an
skipping to change at page 15, line 5 skipping to change at page 18, line 5
Some deployments of NETCONF over SOAP may choose to use transports Some deployments of NETCONF over SOAP may choose to use transports
without encryption. This presents vulnerabilities but may be without encryption. This presents vulnerabilities but may be
selected for deployments involving closed networks or debugging selected for deployments involving closed networks or debugging
scenarios. scenarios.
A device managed by NETCONF may interact (over protocols other than A device managed by NETCONF may interact (over protocols other than
NETCONF) with devices managed by other protocols, all of differing NETCONF) with devices managed by other protocols, all of differing
security. Each point of entry brings with it a potential security. Each point of entry brings with it a potential
vulnerability. vulnerability.
5. References 5. IANA Considerations
5.1 Normative References The IANA will assign TCP ports for NETCONF for SOAP over HTTP and
SOAP over BEEP.
The IANA will place netconf-soap_1.0.wsdl in the IANA XML registry.
6. References
6.1 Normative References
[1] Enns, R., "NETCONF Configuration Protocol", [1] Enns, R., "NETCONF Configuration Protocol",
draft-ietf-netconf-prot-03 (work in progress), June 2004, draft-ietf-netconf-prot-03 (work in progress), June 2004,
<http://www.ietf.org/internet-drafts/ <http://www.ietf.org/internet-drafts/
draft-ietf-netconf-prot-03.txt>. draft-ietf-netconf-prot-03.txt>.
[2] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, [2] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
"Extensible Markup Language (XML) 1.0 (Second Edition)", W3C "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C
REC REC-xml-20001006, October 2000, REC REC-xml-20001006, October 2000,
<http://www.w3.org/TR/2000/REC-xml-20001006>. <http://www.w3.org/TR/2000/REC-xml-20001006>.
skipping to change at page 16, line 28 skipping to change at page 20, line 28
[14] Rose, M. and D. New, "Reliable Delivery for syslog", RFC 3195, [14] Rose, M. and D. New, "Reliable Delivery for syslog", RFC 3195,
November 2001, <http://www.ietf.org/rfc/rfc3195.txt>. November 2001, <http://www.ietf.org/rfc/rfc3195.txt>.
[15] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC [15] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
3080, March 2001, <http://www.ietf.org/rfc/rfc3080.txt>. 3080, March 2001, <http://www.ietf.org/rfc/rfc3080.txt>.
[16] O'Tuathail, E. and M. Rose, "Using the Simple Object Access [16] O'Tuathail, E. and M. Rose, "Using the Simple Object Access
Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)", Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)",
RFC 3288, June 2002, <http://www.ietf.org/rfc/rfc3288.txt>. RFC 3288, June 2002, <http://www.ietf.org/rfc/rfc3288.txt>.
5.2 Informative References [17] Mealling, M., "The IETF XML Registry", RFC 3688, January 2004,
<http://www.ietf.org/rfc/rfc3688.txt>.
[17] Barton, J., Nielsen, H. and S. Thatte, "SOAP Messages with 6.2 Informative References
[18] Barton, J., Nielsen, H. and S. Thatte, "SOAP Messages with
Attachments", W3C Note NOTE-SOAP-attachments-20001211, Dec Attachments", W3C Note NOTE-SOAP-attachments-20001211, Dec
2000, 2000,
<http://www.w3.org/TR/2000/NOTE-SOAP-attachments-20001211>. <http://www.w3.org/TR/2000/NOTE-SOAP-attachments-20001211>.
[18] Brown, A., Fox, B., Hada, S., LaMacchia, B. and H. Maruyama, [19] Brown, A., Fox, B., Hada, S., LaMacchia, B. and H. Maruyama,
"SOAP Security Extensions: Digital Signature", W3C Note "SOAP Security Extensions: Digital Signature", W3C Note
NOTE-SOAP-dsig-20010206, Feb 2001, NOTE-SOAP-dsig-20010206, Feb 2001,
<http://www.w3.org/TR/2001/NOTE-SOAP-dsig-20010206/>. <http://www.w3.org/TR/SOAP-dsig/>.
[20] Nadalin, A., Kaler, C., Hallam-Baker, P. and R. Monzillo, "Web
Services Security: SOAP Message Security V1.0", OASIS Standard
wss-soap-message-security-1.0, Mar 2004,
<http://www.oasis-open.org/committees/
tc_home.php?wg_abbrev=wss>.
Author's Address Author's Address
Ted Goddard Ted Goddard
ICEsoft Technologies Inc. ICEsoft Technologies Inc.
Suite 300, 1717 10th St. NW Suite 300, 1717 10th St. NW
Calgary, AB T2M 4S2 Calgary, AB T2M 4S2
Canada Canada
Phone: (403) 663-3322 Phone: (403) 663-3322
EMail: ted.goddard@icesoft.com EMail: ted.goddard@icesoft.com
URI: http://www.icesoft.com URI: http://www.icesoft.com
Appendix A. WSDL Definitions
A.1 NETCONF SOAP Binding
The following WSDL document assumes a hypothetical location for the
NETCONF schema.
<?xml version="1.0" encoding="UTF-8"?>
<definitions
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="urn:ietf:params:xml:ns:netconf:soap:1.0"
xmlns:xb="urn:ietf:params:xml:ns:netconf:base:1.0"
targetNamespace="urn:ietf:params:xml:ns:netconf:soap:1.0"
name="soap_1.0.wsdl">
<import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
location="http://iana.org/ietf/netconf/base_1.0.xsd"/>
<message name="rpcRequest">
<part name="in" element="xb:rpc"/>
</message>
<message name="rpcResponse">
<part name="out" element="xb:rpc-reply"/>
</message>
<portType name="rpcPortType">
<operation name="rpc">
<input message="tns:rpcRequest"/>
<output message="tns:rpcResponse"/>
</operation>
</portType>
<binding name="rpcBinding" type="tns:rpcPortType">
<SOAP:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="rpc">
<SOAP:operation/>
<input>
<SOAP:body use="literal"
namespace="urn:ietf:params:xml:ns:netconf:base:1.0"/>
</input>
<output>
<SOAP:body use="literal"
namespace="urn:ietf:params:xml:ns:netconf:base:1.0"/>
</output>
</operation>
</binding>
</definitions>
A.2 Sample Service Definition
The following WSDL document assumes a hypothetical location for the
NETCONF over SOAP WSDL definitions. A typical deployment of a device
manageable via NETCONF over SOAP would provide a service definition
similar to the following to identify the address of the device.
<?xml version="1.0" encoding="UTF-8"?>
<definitions
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xs="urn:ietf:params:xml:ns:netconf:soap:1.0"
targetNamespace="urn:myNetconfService"
name="myNetconfService.wsdl">
<import namespace="urn:ietf:params:xml:ns:netconf:soap:1.0"
location="http://iana.org/ietf/netconf/soap_1.0.wsdl"/>
<service name="netconf">
<port name="rpcPort" binding="xs:rpcBinding">
<SOAP:address location="http://localhost:8080/netconf"/>
</port>
</service>
</definitions>
Intellectual Property Statement Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights 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 might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79. found in BCP 78 and BCP 79.
skipping to change at page 19, line 41 skipping to change at page 22, line 41
This document and the information contained herein are provided on an This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright Statement Copyright Statement
Copyright (C) The Internet Society (2004). This document is subject Copyright (C) The Internet Society (2005). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights. except as set forth therein, the authors retain all their rights.
Acknowledgment Acknowledgment
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is currently provided by the
Internet Society. Internet Society.
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/