draft-ietf-netconf-soap-01.txt   draft-ietf-netconf-soap-02.txt 
Network Working Group T. Goddard Network Working Group T. Goddard
Internet-Draft ICEsoft Technologies Inc. Internet-Draft ICEsoft Technologies Inc.
Expires: August 13, 2004 February 13, 2004 Expires: December 3, 2004 June 4, 2004
NETCONF Over SOAP NETCONF Over SOAP
draft-ietf-netconf-soap-01 draft-ietf-netconf-soap-02
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other Task Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts. groups may also distribute working documents as Internet-Drafts.
skipping to change at page 1, line 30 skipping to change at page 1, line 30
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 http:// The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt. 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 August 13, 2004. This Internet-Draft will expire on December 3, 2004.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved. Copyright (C) The Internet Society (2004). All Rights Reserved.
Abstract Abstract
The device management protocol NETCONF is applicable to a wide range The device management protocol NETCONF is applicable to a wide range
of devices in a variety of environments. The emergence of Web 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
skipping to change at page 2, line 17 skipping to change at page 2, line 17
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
2.6 SOAP Implementation Considerations . . . . . . . . . . . . . 7 2.6 SOAP Implementation Considerations . . . . . . . . . . . . . 7
2.6.1 SOAP Feature Exploitation . . . . . . . . . . . . . . . . . 7 2.6.1 SOAP Feature Exploitation . . . . . . . . . . . . . . . . . 7
2.6.2 SOAP Headers . . . . . . . . . . . . . . . . . . . . . . . . 7 2.6.2 SOAP Headers . . . . . . . . . . . . . . . . . . . . . . . . 7
3. A SOAP Web Service for NETCONF . . . . . . . . . . . . . . . 8 2.6.3 SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . . 8 3. A SOAP Web Service for NETCONF . . . . . . . . . . . . . . . 9
3.2 NETCONF Sessions . . . . . . . . . . . . . . . . . . . . . . 8 3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . . 9
3.3 Capabilities Exchange . . . . . . . . . . . . . . . . . . . 8 3.2 NETCONF Sessions . . . . . . . . . . . . . . . . . . . . . . 9
3.4 A NETCONF/SOAP example . . . . . . . . . . . . . . . . . . . 9 3.3 Capabilities Exchange . . . . . . . . . . . . . . . . . . . 9
4. Security Considerations . . . . . . . . . . . . . . . . . . 11 3.4 A NETCONF/SOAP example . . . . . . . . . . . . . . . . . . . 10
4.1 Integrity, Privacy, and Authentication . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . 12
4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . . 11 4.1 Integrity, Privacy, and Authentication . . . . . . . . . . . 12
4.3 Environmental Specifics . . . . . . . . . . . . . . . . . . 12 4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . . 12
Normative References . . . . . . . . . . . . . . . . . . . . 13 4.3 Environmental Specifics . . . . . . . . . . . . . . . . . . 13
Informative References . . . . . . . . . . . . . . . . . . . 15 Normative References . . . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . 15 Informative References . . . . . . . . . . . . . . . . . . . 16
A. WSDL Definitions . . . . . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . 16
A.1 NETCONF SOAP Binding . . . . . . . . . . . . . . . . . . . . 16 A. WSDL Definitions . . . . . . . . . . . . . . . . . . . . . . 17
A.2 Sample Service Definition . . . . . . . . . . . . . . . . . 17 A.1 NETCONF SOAP Binding . . . . . . . . . . . . . . . . . . . . 17
Intellectual Property and Copyright Statements . . . . . . . 18 A.2 Sample Service Definition . . . . . . . . . . . . . . . . . 18
Intellectual Property and Copyright Statements . . . . . . . 19
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 over HTTP is a natural application protocol for In general, SOAP over HTTP is a natural application protocol for
NETCONF, essentially because of the remote procedure call character NETCONF, essentially because of the remote procedure call character
skipping to change at page 4, line 51 skipping to change at page 4, line 51
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. For instance, in
WSDL, the import statement WSDL, the import statement
<import namespace="http://iana.org/netconf/1.0/base" <import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
location="http://iana.org/netconf/1.0/base.xsd"/> location="http://iana.org/ietf/netconf/base_1.0.xsd"/>
imports the definitions of XML types and elements from the base imports the definitions of XML types and elements from the base
NETCONF schema. Ideally, the file containing that schema is hosted NETCONF schema. Ideally, the file containing that schema is hosted
on a web server under the authority of the standards body that on a web server under the authority of the standards body that
defined the schema. In this way, dependent standards can be built up defined the schema. In this way, dependent standards can be built up
over time and all are accessible to automated software tools that over time and all are accessible to automated software tools that
ensure adherence to the standards. Thus, it will gradually become as ensure adherence to the standards. Thus, it will gradually become as
important for iana.org to host documents like important for iana.org to host documents like
http://iana.org/netconf/1.0/base/base.xsd http://iana.org/ietf/netconf/base_1.0.xsd
as the IETF now hosts documents such as as the IETF now hosts documents such as
http://www.ietf.org/rfc/rfc2616.txt http://www.ietf.org/rfc/rfc2616.txt
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. For existing SOAP implementations support only HTTP or HTTP/TLS. For
skipping to change at page 8, line 5 skipping to change at page 7, line 49
2.6.2 SOAP Headers 2.6.2 SOAP Headers
Implementors of NETCONF over SOAP should be aware of the following Implementors of NETCONF over SOAP should be aware of the following
characteristic of SOAP headers: a SOAP header may have the attribute characteristic of SOAP headers: a SOAP header may have the attribute
"mustUnderstand" and, if so, the recipient must either process the "mustUnderstand" and, if so, the recipient must either process the
header block or not process the SOAP message at all, and instead header block or not process the SOAP message at all, and instead
generate a fault. A "mustUnderstand" header must not be silently generate a fault. A "mustUnderstand" header must not be silently
discarded. discarded.
In general, however, SOAP headers are intended for
application-specific uses. The NETCONF SOAP binding does not make
use of SOAP headers.
2.6.3 SOAP Faults
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
allow SOAP processors to propagate the <rpc-error> to application
code using a language-appropriate exception mechanism.
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 faultstring is the contents of the NETCONF <rpc-error> "tag",
and the SOAP Fault detail is the original <rpc-error> structure.
For instance, given the following <rpc-error>,
<rpc-error message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<tag>EXAMPLE_MTU_RANGE</tag>
<error-code>128</error-code>
<severity>error</severity>
<statement>mtu 21050;</statement>
<message>MTU 21050 on Ethernet/1 is
outside range 256..9192</message>
</rpc-error>
the associated SOAP Fault message is
<soapenv:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<soapenv:Fault>
<faultcode>soapenv:Client</faultcode>
<faultstring>EXAMPLE_MTU_RANGE</faultstring>
<detail>
<rpc-error message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<tag>EXAMPLE_MTU_RANGE</tag>
<error-code>128</error-code>
<severity>error</severity>
<statement>mtu 21050;</statement>
<message>MTU 21050 on Ethernet/1 is
outside range 256..9192</message>
</rpc-error>
</detail>
</soapenv:Fault>
</soapenv:Body>
</soapenv:Envelope>
3. A SOAP Web Service for NETCONF 3. A SOAP Web Service for NETCONF
3.1 Fundamental Use Case 3.1 Fundamental Use Case
The fundamental use case for NETCONF over SOAP (NETCONF/SOAP) over The fundamental use case for NETCONF over SOAP (NETCONF/SOAP) over
HTTP is that of a management console ("manager" role) managing one or HTTP is that of a management console ("manager" role) managing one or
more devices running NETCONF agents ("agent" role). The manager more devices running NETCONF agents ("agent" role). The manager
initiates an HTTP connection to an agent and drives the NETCONF initiates an HTTP connection to an agent and drives the NETCONF
session via a sequence of SOAP messages over HTTP requests. When the session via a sequence of SOAP messages over HTTP requests. When the
manager closes the HTTP connection, the NETCONF session is also manager closes the HTTP connection, the NETCONF session is also
skipping to change at page 9, line 23 skipping to change at page 10, line 23
Content-Type: text/xml; charset=utf-8 Content-Type: text/xml; charset=utf-8
Accept: application/soap+xml, text/* Accept: application/soap+xml, text/*
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Pragma: no-cache
Content-Length: 470 Content-Length: 470
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope <soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body> <soapenv:Body>
<rpc id="101" xmlns="http://ietf.org/netconf/1.0/base"> <rpc id="101"
xmlns="http://iana.org/ietf/netconf/base_1.0.xsd">
<get-config> <get-config>
<source> <source>
<running/> <running/>
</source> </source>
<config xmlns="http://example.com/schema/1.2/config"> <config xmlns="http://example.com/schema/1.2/config">
<users/> <users/>
</config> </config>
<format>xml</format> <format>xml</format>
</get-config> </get-config>
</rpc> </rpc>
skipping to change at page 10, line 12 skipping to change at page 11, line 12
The HTTP/1.0 response is also straightforward: The HTTP/1.0 response is also straightforward:
HTTP/1.0 200 OK HTTP/1.0 200 OK
Content-Type: text/xml; charset=utf-8 Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope <soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body> <soapenv:Body>
<rpc-reply id="101" xmlns="http://ietf.org/netconf/1.0/base"> <rpc-reply id="101"
xmlns="http://iana.org/ietf/netconf/base_1.0.xsd">
<config xmlns="http://example.com/schema/1.2/config"> <config xmlns="http://example.com/schema/1.2/config">
<users> <users>
<user> <user>
<name>root</name> <name>root</name>
<type>superuser</type> <type>superuser</type>
</user> </user>
<user> <user>
<name>fred</name> <name>fred</name>
<type>admin</type> <type>admin</type>
</user> </user>
skipping to change at page 13, line 8 skipping to change at page 14, line 8
deployments involving closed networks or debugging scenarios. deployments involving closed networks or debugging 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.
Normative References Normative References
[1] Enns, R., "XMLCONF Configuration Protocol", [1] Enns, R., "XMLCONF Configuration Protocol",
draft-enns-xmlconf-spec-00 (work in progress), Feb 2003, draft-enns-xmlconf-spec-03 (work in progress), Feb 2003,
<http://www.ietf.org/internet-drafts/ <http://www.ietf.org/internet-drafts/
draft-enns-xmlconf-spec-00.txt>. draft-enns-xmlconf-spec-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, <http://www.w3.org/TR/2000/ REC REC-xml-20001006, October 2000, <http://www.w3.org/TR/2000/
REC-xml-20001006>. REC-xml-20001006>.
[3] Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendelsohn, [3] Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendelsohn,
N., Nielsen, H., Thatte, S. and D. Winer, "Simple Object Access N., Nielsen, H., Thatte, S. and D. Winer, "Simple Object Access
Protocol (SOAP) 1.1", W3C Note NOTE-SOAP-20000508, May 2000, Protocol (SOAP) 1.1", W3C Note NOTE-SOAP-20000508, May 2000,
<http://www.w3.org/TR/2000/NOTE-SOAP-20000508>. <http://www.w3.org/TR/2000/NOTE-SOAP-20000508>.
skipping to change at page 16, line 16 skipping to change at page 17, line 16
A.1 NETCONF SOAP Binding A.1 NETCONF SOAP Binding
The following WSDL document assumes a hypothetical location for the The following WSDL document assumes a hypothetical location for the
NETCONF schema. NETCONF schema.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<definitions <definitions
xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://ietf.org/netconf/1.0/soap" xmlns:tns="urn:ietf:params:xml:ns:netconf:soap:1.0"
xmlns:xb="http://ietf.org/netconf/1.0/base" xmlns:xb="urn:ietf:params:xml:ns:netconf:base:1.0"
targetNamespace="http://ietf.org/netconf/1.0/soap" targetNamespace="urn:ietf:params:xml:ns:netconf:soap:1.0"
name="http://ietf.org/netconf/1.0/soap"> name="soap_1.0.wsdl">
<import namespace="http://ietf.org/netconf/1.0/base" <import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
location="base.xsd"/> location="http://iana.org/ietf/netconf/base_1.0.xsd"/>
<message name="rpcRequest"> <message name="rpcRequest">
<part name="in" element="xb:rpc"/> <part name="in" element="xb:rpc"/>
</message> </message>
<message name="rpcResponse"> <message name="rpcResponse">
<part name="out" element="xb:rpc-reply"/> <part name="out" element="xb:rpc-reply"/>
</message> </message>
<portType name="rpcPortType"> <portType name="rpcPortType">
<operation name="rpc"> <operation name="rpc">
skipping to change at page 16, line 45 skipping to change at page 17, line 45
</operation> </operation>
</portType> </portType>
<binding name="rpcBinding" type="tns:rpcPortType"> <binding name="rpcBinding" type="tns:rpcPortType">
<SOAP:binding style="document" <SOAP:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/> transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="rpc"> <operation name="rpc">
<SOAP:operation/> <SOAP:operation/>
<input> <input>
<SOAP:body use="literal" <SOAP:body use="literal"
namespace="http://ietf.org/netconf/1.0/base"/> namespace="urn:ietf:params:xml:ns:netconf:base:1.0"/>
</input> </input>
<output> <output>
<SOAP:body use="literal" <SOAP:body use="literal"
namespace="http://ietf.org/netconf/1.0/base"/> namespace="urn:ietf:params:xml:ns:netconf:base:1.0"/>
</output> </output>
</operation> </operation>
</binding> </binding>
</definitions> </definitions>
A.2 Sample Service Definition A.2 Sample Service Definition
The following WSDL document assumes a hypothetical location for the The following WSDL document assumes a hypothetical location for the
NETCONF/SOAP WSDL definitions. A typical deployment of a device NETCONF/SOAP WSDL definitions. A typical deployment of a device
manageable via NETCONF/SOAP would provide a service definition manageable via NETCONF/SOAP would provide a service definition
similar to the following to identify the address of the device. 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"?>
<definitions <definitions
xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xs="http://ietf.org/netconf/1.0/soap" xmlns:xs="urn:ietf:params:xml:ns:netconf:soap:1.0"
targetNamespace="urn:myNetconfService" targetNamespace="urn:myNetconfService"
name="myNetconfService.wsdl"> name="myNetconfService.wsdl">
<import namespace="http://ietf.org/netconf/1.0/soap" <import namespace="urn:ietf:params:xml:ns:netconf:soap:1.0"
location="soap.wsdl"/> location="http://iana.org/ietf/netconf/soap_1.0.wsdl"/>
<service name="netconf"> <service name="netconf">
<port name="rpcPort" binding="xs:rpcBinding"> <port name="rpcPort" binding="xs:rpcBinding">
<SOAP:address location="http://localhost:8080/netconf"/> <SOAP:address location="http://localhost:8080/netconf"/>
</port> </port>
</service> </service>
</definitions> </definitions>
Intellectual Property Statement Intellectual Property Statement
 End of changes. 

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