Network Working Group T. Goddard
Request for Comments: 4743 ICEsoft Technologies Inc.
Category: Standards Track December 2006
Using NETCONF over the Simple Object Access Protocol (SOAP)
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The IETF Trust (2006).
Abstract
The Network Configuration Protocol (NETCONF) is applicable to a wide
range of devices in a variety of environments. Web Services is one
such environment and is presently characterized by the use of the
Simple Object Access Protocol (SOAP). NETCONF finds many benefits in
this environment: from the reuse of existing standards, to ease of
software development, to integration with deployed systems. Herein,
we describe SOAP over HTTP and SOAP over Blocks Exchange Extensible
Protocol (BEEP) bindings for NETCONF.
Goddard Standards Track [Page 1]
RFC 4743 NETCONF over SOAP December 2006
Table of Contents
1. Introduction ....................................................2
2. SOAP Background for NETCONF .....................................3
2.1. Use and Storage of WSDL and XSD ............................4
2.2. SOAP over HTTP .............................................4
2.3. HTTP Drawbacks .............................................4
2.4. BCP56: On the Use of HTTP as a Substrate ...................5
2.5. Important HTTP 1.1 Features ................................6
2.6. SOAP over BEEP .............................................7
2.7. SOAP Implementation Considerations .........................7
2.7.1. SOAP Feature Exploitation ...........................7
2.7.2. SOAP Headers ........................................7
2.7.3. SOAP Faults .........................................8
3. A SOAP Service for NETCONF ......................................9
3.1. Fundamental Use Case .......................................9
3.2. NETCONF Session Establishment ..............................9
3.3. NETCONF Capabilities Exchange ..............................9
3.4. NETCONF Session Usage .....................................11
3.5. NETCONF Session Teardown ..................................11
3.6. A NETCONF over SOAP Example ...............................11
3.7. NETCONF SOAP WSDL .........................................13
3.8. Sample Service Definition WSDL ............................14
4. Security Considerations ........................................15
4.1. Integrity, Privacy, and Authentication ....................15
4.2. Vulnerabilities ...........................................16
4.3. Environmental Specifics ...................................16
5. IANA Considerations ............................................17
6. References .....................................................17
6.1. Normative References ......................................17
6.2. Informative References ....................................18
1. Introduction
Given the use of Extensible Markup Language (XML) [2] and the remote
procedure call characteristics, it is natural to consider a binding
of the NETCONF [1] operations to a SOAP [3] application protocol.
This document proposes a binding of this form.
In general, SOAP is a natural messaging scheme for NETCONF,
essentially because of the remote procedure call character of both.
However, care must be taken with SOAP over HTTP as it is inherently
synchronous and client-driven. SOAP over BEEP [11] is technically
superior, but is not as widely adopted.
Four basic topics are presented: SOAP specifics of interest to
NETCONF, specifics on implementing NETCONF as a SOAP-based web
service, security considerations, and functional Web Services
Goddard Standards Track [Page 2]
RFC 4743 NETCONF over SOAP December 2006
Description Language (WSDL) definitions. In some sense, the most
important part of the document is the brief WSDL document presented
in Section 3.7. With the right tools, the WSDL combined with the
base NETCONF XML Schemas provides machine-readable descriptions
sufficient for the development of software 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 [8].
2. SOAP Background for NETCONF
Why introduce SOAP as yet another wrapper around what is already a
remote procedure call message? There are, in fact, both technical
and practical reasons. The technical reasons are perhaps less
compelling, but let's examine them first.
The use of SOAP does offer a few technical advantages. SOAP is
fundamentally an XML messaging scheme (which is capable of supporting
remote procedure call), and it defines a simple message format
composed of a "header" and a "body" contained within an "envelope".
The "header" contains meta-information relating to the message and
can be used to indicate such things as store-and-forward behaviour or
transactional characteristics. In addition, SOAP specifies an
optional encoding for the "body" of the message. However, this
encoding is not applicable to NETCONF as one of the goals is to have
highly readable XML, and SOAP-encoding is optimized instead for ease
of automated de-serialization. These benefits of the SOAP message
structure are simple, but worthwhile because they are already
standardized.
It is the practical reasons that truly make SOAP an interesting
choice for device management. It is not difficult to invent a
mechanism for exchanging XML messages over TCP, but what is difficult
is getting that mechanism supported in a wide variety of tools and
operating systems and having that mechanism understood by a great
many developers. SOAP over HTTP (with WSDL) is seeing good success
at this, and this means that a device management protocol making use
of these technologies has advantages in being implemented and
adopted. Admittedly, there are interoperability problems with SOAP
and WSDL, but such problems have wide attention and can be expected
to be resolved.
Goddard Standards Track [Page 3]
RFC 4743 NETCONF over SOAP December 2006
2.1. Use and Storage of WSDL and XSD
One of the advantages of using machine-readable formats (such as Web
Services Description Language (WSDL) [16] and XML Schemas [4]) is
that they can be used automatically in the software development
process. With appropriate tools, WSDL and XSD can be used to
generate classes that act as remote interfaces or
application-specific data structures. Other uses, such as document
generation and service location, are also common. A great innovation
found with many XML-based definition languages is the use of
hyperlinks for referring to documents containing supporting
definitions.
For instance, in WSDL, the above import statement imports the
definitions of XML types and elements from the base NETCONF schema.
Ideally, the file containing that schema is hosted on a web server
under the authority of the standards body that defined the schema.
In this way, dependent standards can be built up over time, and all
are accessible to automated software tools that ensure adherence to
the standards. The IANA-maintained registry for this purpose is
described in "The IETF XML Registry" [13].
Note that WSDL declarations for SOAP over BEEP bindings are not yet
standardized.
2.2. SOAP over HTTP
Although SOAP focuses on messages and can be bound to different
underlying protocols such as HTTP, SMTP, or BEEP, most existing SOAP
implementations support only HTTP or HTTP/TLS.
There are a number of advantages to considering SOAP over protocols
other than HTTP, as HTTP assigns the very distinct client and server
roles by connection initiation. This causes difficulties in
supporting asynchronous notification and can be relieved in many ways
by replacing HTTP with BEEP.
2.3. HTTP Drawbacks
HTTP is not the ideal transport for messaging, but it is adequate for
the most basic interpretation of "remote procedure call". HTTP is
based on a communication pattern whereby the client (which initiates
the TCP connection) makes a "request" to the server. The server
returns a "response", and this process is continued (possibly over a
Goddard Standards Track [Page 4]
RFC 4743 NETCONF over SOAP December 2006
persistent connection, as described below). This matches the basic
idea of a remote procedure call where the caller invokes a procedure
on a remote server and waits for the return value.
Potential criticisms of HTTP could include the following:
o Server-initiated data flow is awkward to provide.
o Headers are verbose and text-based
o Idle connections may be closed by intermediate proxies
o Data encapsulation must adhere to Multipurpose Internet Mail
Extensions (MIME) [15].
o Bulk transfer relies on stream-based ordering.
In many ways, these criticisms are directed at particular compromises
in the design of HTTP. As such, they are important to consider, but
it is not clear that they result in fatal drawbacks for a device
management protocol.
2.4. BCP56: On the Use of HTTP as a Substrate
Best Current Practice 56 [6] presents a number of important
considerations on the use of HTTP in application protocols. In
particular, it raises the following concerns:
o HTTP may be more complex than is necessary for the application.
o The use of HTTP may mask the application from some firewalls.
o A substantially new service should not reuse port 80 as assigned
to HTTP.
o HTTP caching may mask connection state.
Fundamentally, these concerns lie directly with common usage of SOAP
over HTTP, rather than the application of SOAP over HTTP to NETCONF.
As BCP 56 indicates, it is debatable whether HTTP is an appropriate
protocol for SOAP at all, and it is likely that BEEP would be a
superior protocol for most SOAP applications. Unfortunately, SOAP
over HTTP 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 actually makes it more readily processed by firewalls, albeit
firewalls designed to process SOAP messages.
Goddard Standards Track [Page 5]
RFC 4743 NETCONF over SOAP December 2006
HTTP caches SHOULD NOT be inserted between NETCONF managers and
agents as NETCONF session state is tied to the state of the
underlying transport connection. Three defensive actions can be
taken:
o Caching MUST be prohibited through the use of HTTP headers Cache-
Control and Pragma: no-cache.
o HTTP proxies SHOULD NOT be deployed within the management network.
o Use HTTPS.
It is also possible to respond to the concern on the reuse of port
80. Any NETCONF SOAP service MUST always be supported over the new
standard port for NETCONF over SOAP, and all conforming
implementations MUST default to attempting connections over this new
standard port for NETCONF. A standard port for NETCONF over SOAP
(over HTTP) has been assigned in the IANA considerations of this
document.
2.5. Important HTTP 1.1 Features
HTTP 1.1 [5] includes two important features that provide for
relatively efficient transport of SOAP messages. These features are
"persistent connections" and "chunked transfer-coding".
Persistent connections allow a single TCP connection to be used
across multiple HTTP requests. This permits multiple SOAP request/
response message pairs to be exchanged without the overhead of
creating a new TCP connection for each request. Given that a single
stream is used for both requests and responses, it is clear that some
form of framing is necessary. For messages whose length is known in
advance, this is handled by the HTTP header "Content-length". For
messages of dynamic length, "Chunking" is required.
HTTP "Chunking" or "chunked transfer-coding" allows the sender to
send an indefinite amount of binary data. This is accomplished by
informing the receiver of the size of each "chunk" (substring of the
data) before the chunk is transmitted. The last chunk is indicated
by a chunk of zero length. Chunking can be effectively used to
transfer a large XML document where the document is generated on-line
from a non-XML form in memory.
In terms of its application to SOAP message exchanges, persistent
connections are clearly important for performance reasons and are
particularly important when the persistence of authenticated
connections is at stake. When one considers that messages of dynamic
length are the rule rather than the exception for SOAP messages, it
Goddard Standards Track [Page 6]
RFC 4743 NETCONF over SOAP December 2006
is also clear that Chunking is very useful. In some cases, it is
possible to buffer a SOAP response and determine its length before
sending, but the storage requirements for this are prohibitive for
many devices. Together, these two features provide a good foundation
for device management using SOAP over HTTP. HTTP chunking and
persistent connections [5] SHOULD be used.
2.6. SOAP over BEEP
Although not widely adopted by the Web Services community, BEEP is an
excellent substrate for SOAP [12]. In particular, it provides for
request/response message exchanges initiated by either BEEP peer and
allows the number of response messages to be arbitrary (including
zero). The BEEP profile for SOAP simply makes use of a single BEEP
channel for exchanging SOAP messages and benefits from BEEP's
inherent strengths for message exchange over a single transport
connection.
2.7. SOAP Implementation Considerations
It is not the goal of this document to cover the SOAP [3]
specification in detail. Instead, we provide a few comments that may
be of interest to an implementor of NETCONF over SOAP.
2.7.1. SOAP Feature Exploitation
NETCONF over SOAP does not make extensive use of SOAP features. For
instance, NETCONF operations are not broken into SOAP message parts,
and the SOAP header is not used to convey metadata. This is a
deliberate design decision as it allows the implementor to provide
NETCONF over multiple substrates easily while handling the messages
over those different substrates in a common way.
2.7.2. SOAP Headers
Implementers of NETCONF over SOAP should be aware of the following
characteristic of SOAP headers: a SOAP header may have the attribute
"mustUnderstand", and, if it does, the recipient must either process
the header block or not process the SOAP message at all, and instead
generate a fault. A "mustUnderstand" header must not be silently
discarded.
In general, however, SOAP headers are intended for application-
specific uses. The NETCONF SOAP binding does not make use of SOAP
headers.
Goddard Standards Track [Page 7]
RFC 4743 NETCONF over SOAP December 2006
2.7.3. SOAP Faults
A SOAP Fault is returned in the event of a NETCONF . It
is constructed essentially as a wrapper for the , but it
allows SOAP processors to propagate the to application
code using a language-appropriate exception mechanism.
A SOAP Fault is constructed from an as follows: the SOAP
Fault Code Value is "Receiver" in the SOAP envelope namespace, the
SOAP Fault Reason Text is the contents of the NETCONF
"error-tag", and the SOAP Fault detail is the original
structure.
For instance, given the following ,
rpcMISSING_ATTRIBUTEerrormessage-idrpc
the associated SOAP Fault message is

3. A SOAP Service for NETCONF
3.1. Fundamental Use Case
The fundamental use case for NETCONF over SOAP is that of a
management console ("manager" role) managing one or more devices
running NETCONF agents ("agent" role). The manager initiates an HTTP
or BEEP connection to an agent and drives the NETCONF session via a
sequence of SOAP messages. When the manager closes the connection,
the NETCONF session is also closed.
3.2. NETCONF Session Establishment
A NETCONF over SOAP session is established by the initial message
exchange on the underlying substrate. For HTTP, a NETCONF session is
established once a SOAP message is POSTed to the NETCONF web
application URI. For BEEP, a NETCONF session is established once the
BEEP profile for SOAP handshake establishes the SOAP channel.
3.3. NETCONF Capabilities Exchange
Capabilities exchange and session ID establishment are performed
through the exchange of messages. In the case of SOAP over
HTTP, the HTTP client MUST send the first message. The case
of SOAP over BEEP imposes no ordering constraints. For instance, the
following example shows the exchange of messages and
establishes a session ID value of 4. Observe that the management
client initiates the exchange and the server agent assigns the
session ID.
Goddard Standards Track [Page 9]
RFC 4743 NETCONF over SOAP December 2006
C: POST /netconf HTTP/1.1
C: Host: netconfdevice
C: Content-Type: text/xml; charset=utf-8
C: Accept: application/soap+xml, text/*
C: Cache-Control: no-cache
C: Pragma: no-cache
C: Content-Length: 376
C:
C:
C:
C:

S:
Goddard Standards Track [Page 10]
RFC 4743 NETCONF over SOAP December 2006
3.4. NETCONF Session Usage
NETCONF sessions are persistent for both performance and semantic
reasons. NETCONF session state contains the following:
1. Authentication Information
2. Capability Information
3. Locks
4. Pending Operations
5. Operation Sequence Numbers
Authentication must be maintained throughout a session due to the
fact that it is expensive to establish. Capability Information is
maintained so that appropriate operations can be applied during a
session. Locks are released upon termination of a session as this
makes the protocol more robust. Pending operations come and go from
existence during the normal course of remote procedure call (RPC)
operations. Operation sequence numbers provide the small but
necessary state information to refer to operations during the
session.
In the case of SOAP over HTTP, a NETCONF session is supported by an
HTTP connection with an authenticated user. For SOAP over BEEP, a
NETCONF session is supported by a BEEP channel operating according to
the BEEP profile for SOAP [12].
3.5. NETCONF Session Teardown
To allow automated cleanup, NETCONF over SOAP session teardown takes
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
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
capable of programatically closing the transport connections
associated with NETCONF sessions, such as in response to a
operation; thus, the HTTP or BEEP substrate
implementation must expose this appropriately.
3.6. A NETCONF over SOAP Example
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
representation of a NETCONF operation. This example shows HTTP/1.1
for simplicity. An example for BEEP would be similar.
Goddard Standards Track [Page 11]
RFC 4743 NETCONF over SOAP December 2006
C: POST /netconf HTTP/1.1
C: Host: netconfdevice
C: Content-Type: text/xml; charset=utf-8
C: Accept: application/soap+xml, text/*
C: Cache-Control: no-cache
C: Pragma: no-cache
C: Content-Length: 465
C:
C:
C:
C:

3.8. Sample Service Definition WSDL
The following WSDL document assumes a local 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.