Network Working Group M. Wasserman
Internet-Draft Wind River
Expires: February 25, 2004 August 27, 2003
Using the NETCONF Configuration Protocol over Secure Shell (SSH)
draft-wasserman-netconf-over-ssh-00.txt
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on February 25, 2004.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract
This document describes a simple method for invoking and running the
NETCONF configuration protocol within a Secure Shell (SSH) session.
Some features of the NETCONF protocol are not suited for use in a
single shell session, and those limitations are described here.
Wasserman Expires February 25, 2004 [Page 1]
Internet-Draft NETCONF over SSH August 2003
1. Introduction
The NETCONF protocol [1] is an XML-based protocol used to manage the
configuration of networking equipment. NETCONF is defined to be
transport-independent, allowing mappings to be defined for multiple
transport protocols. This document defines how XMLCONF can be used
within a Secure Shell (SSH) session, using the SSH connection
protocol [2] over the SSH transport protocol [3].
NETCONF is defined as a multi-channel protocol, with separate
communications channels for session management, protocol operations
and notifications. In this document, however, we have defined a
mapping to run NETCONF over a single SSH session (a single SSH
channel of type "session", see section 4 of [2]). This mapping will
allow NETCONF to be executed from the a secure shell session, by a
user or a simple expect script. Mapping NETCONF to a single SSH
session does impose some limitations on the use of NETCONF over SSH.
In particular, the <rpc-progress> and <rpc-abort> elements are not
supported, NETCONF capabilities must be exchanged over the same
channel as the NETCONF RPC commands, and the notification capability
is not supported.
Wasserman Expires February 25, 2004 [Page 2]
Internet-Draft NETCONF over SSH August 2003
2. Starting NETCONF over SSH
To run NETCONF over SSH, the client will first establish an SSH
transport connection using the SSH transport protocol and exchange
keys. The client will then invoke the "ssh-userauth" service to
authenticate the user, as described in the SSH authentication
protocol [4]. Once the user has been successfully authenticated, the
client will invoke the "ssh-connection" service, also known as the
SSH connection protocol.
After the ssh-connection service is established, the client will open
a channel of type "session", which will result in an SSH session
running the user's default shell. Once an SSH session has been
established, there are two different ways that NETCONF can be run:
(1) as an SSH subsystem, or (2) by starting a shell and invoking a
NETCONF program from the command line.
2.1 Running NETCONF as an SSH Subsystem
The simplest way for a script to invoke NETCONF over SSH will be for
the script to invoke NETCONF as an SSH subsystem. This avoids the
need for the script to recognize shell prompts or skip over
information that is printed at shell start-up. To the user (or
script), running NETCONF as an SSH subsystem may look similar to the
following example (lines beginning with ## are comments):
## The user (or script) invokes the SSH subsystem
[user@client]$ ssh -s server.example.org netconf
user@server.example.org's password: ********
## The NETCONF subsystem sends an XML document to the client
<?xml version="1.0" encoding="UTF-8"?>
<hello>
<capabilities>
<capability>http://ietf.org/xmlconf/1.0/base</capability>
<capability>http://ietf.org/xmlconf/1.0/base#lock</capability>
</capabilities>
</hello>
While the NETCONF subsystem is active, the user can interact with the
NETCONF server by entering complete XML documents containing NETCONF
elements, and the NETCONF server will respond by sending complete XML
documents containing appropriate replies.
Wasserman Expires February 25, 2004 [Page 3]
Internet-Draft NETCONF over SSH August 2003
2.2 Running NETCONF from an SSH Shell
The user may choose to invoke a NETCONF program from the shell
command line. This would involve using SSH to establish a shell
session, and entering the name of a NETCONF program (with the full
path, if necessary) at the remote shell prompt. To the user, the
establishment of an SSH shell and the invocation of the NETCONF
program may look similar to the following example (lines beginning
with ## are comments):
## The user enters an SSH shell session
[user@client]$ ssh server.example.org
user@server.example.org's password: ********
## At the shell prompt, the user invokes the NETCONF program, which
## in this example is called 'netconf'
[user@server]$ netconf
## The NETCONF program sends an XML document to the client
<?xml version="1.0" encoding="UTF-8"?>
<hello>
<capabilities>
<capability>http://ietf.org/xmlconf/1.0/base</capability>
<capability>http://ietf.org/xmlconf/1.0/base#lock</capability>
</capabilities>
</hello>
After the NETCONF program is invoked, the user can interact with the
NETCONF server by entering complete XML documents containing NETCONF
elements, and the NETCONF server will respond by sending complete XML
documents containing appropriate replies.
Wasserman Expires February 25, 2004 [Page 4]
Internet-Draft NETCONF over SSH August 2003
3. Capabilities Exchange
As indicated in the example above, the NETCONF server may indicate
its capabilities by sending an XML document containing a <hello>
element as soon as the NETCONF session is established. The user (or
the user's expect script) can parse this message to determine the
capabilities of the server, and use that information to determine
which NETCONF commands are supported by the server. If no <hello>
message is received, the client should expect the server to support
the default NETCONF capabilities.
If desired, the user may also send an XML document containing a
<hello> element to indicate his client's capabilities to the server.
If the client does choose to send a <hello> message, it must be the
first XML document that the client sends after the NETCONF session is
established. If no <hello> message is received, the server must
expect the client to support the default NETCONF capabilities.
Because NETCONF runs over a single SSH session, the notification
capability is not supported. So, if the client does send a <hello>
message, it must not indicate support for the notification
capability.
Wasserman Expires February 25, 2004 [Page 5]
Internet-Draft NETCONF over SSH August 2003
4. Using NETCONF over SSH
A NETCONF over SSH session consists of the client and server
exchanging complete XML documents. Once the session has been
established and capabilities have optionally been exchanged, the
client will send complete XML documents to the server containing
<rpc> elements, and the server will respond with complete XML
documents containing <rpc-reply> elements.
To continue the examples given above, an XMLCONF over SSH session to
retrieve a set of configuration information might look like this
(lines beginning with ## are comments):
## The client sends an XML document containing an <rpc> element
<?xml version="1.0" encoding="UTF-8"?>
<rpc id="101" xmlns="http://ietf.org/netconf/1.0/base">
<get-config>
<source> <running/> </source>
<config xmlns="http://example.com/schema/1.2/config">
<users/>
</config>
<format>xml</format>
</get-config>
</rpc>
## The server responds with an XML document containing an <rpc-reply>
## element
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply id="101" xmlns="http://ietf.org/netconf/1.0/base">
<config xmlns="http://example.com/schema/1.2/config">
<users>
<user><name>root</name><type>superuser</type></user>
<user><name>fred</name><type>admin</type></user>
<user><name>barney</name><type>admin</type></user>
</users>
</config>
</rpc-reply>
There are two NETCONF protocol operations that are not supported when
running NETCONF over SSH, the <rpc-progress> and <rpc-abort>
operations. These operations use the NETCONF management channel to
allow the processing of out-of-band operations that affect RPC
processing on the operations channel. Since this document defines a
single-channel mechanism for using NETCONF over SSH, these operations
Wasserman Expires February 25, 2004 [Page 6]
Internet-Draft NETCONF over SSH August 2003
cannot be supported in this transport mapping.
In this mapping, there is no way to obtain a progress indication
regarding an outstanding RPC request, and the only way to abort an
RPC request before it completes is to terminate the SSH session.
Wasserman Expires February 25, 2004 [Page 7]
Internet-Draft NETCONF over SSH August 2003
5. Exiting NETCONF
Exiting NETCONF is accomplished using the <kill-session> operation.
5.1 Exiting a NETCONF Subsystem
To continue the example used in previous sections, an existing
NETCONF subsystem session could be closed as follows (lines beginning
with ## are comments):
## The client sends an XML document containing a <kill-session>
## operation. Question: Where do we get the session-id? Should it be
## sent in the <hello> message?
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="102" xmlns="http://ietf.org/xmlconf/1.0/base">
<kill-session>
<session-id>0</session-id>
</kill-session>
</rpc>
## The server returns an "OK" reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply id="102" xmlns="http://ietf.org/netconf/1.0/base">
<ok/>
</rpc-reply>
## The NETCONF program exits, returning the user to the local
## shell.
[user@client]$
5.2 Exiting a NETCONF Shell Session
When the user has run NETCONF from a shell, he will need to exit the
NETCONF program using the <kill-session> operation, and then exit the
remote shell to return to the local shell. To continue the example
used in previous sections, an existing NETCONF shell session could be
closed as follows (lines beginning with ## are comments):
## The client sends an XML document containing an <kill-session>
## operation Question: Where do we get the session-id? Should it be
## sent in the <hello> message?
Wasserman Expires February 25, 2004 [Page 8]
Internet-Draft NETCONF over SSH August 2003
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="102" xmlns="http://ietf.org/xmlconf/1.0/base">
<kill-session>
<session-id>0</session-id>
</kill-session>
</rpc>
## The server returns an "OK" reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply id="102" xmlns="http://ietf.org/netconf/1.0/base">
<ok/>
</rpc-reply>
## The NETCONF program exits, returning the user to the SSH prompt.
## The user then types 'exit' to exit the SSH shell and return to the
## local shell.
[user@server]$ exit
[user@client]$
Wasserman Expires February 25, 2004 [Page 9]
Internet-Draft NETCONF over SSH August 2003
6. Applicability to Other Shell Types
The techniques described in this document could be used to access the
NETCONF protocol over other shell types, such as console sessions or
a Telnet [6] connections. However, there are serious security
implications associated with allowing NETCONF access via any method
that does not provide strong support for user authentication and data
privacy. See the Security Considerations section for more details.
Wasserman Expires February 25, 2004 [Page 10]
Internet-Draft NETCONF over SSH August 2003
7. Security Considerations
NETCONF is used to access and modify configuration information, so
the ability to access this protocol should be limited to users and
systems that are authorized to view or modify the server's
configuration data. NETCONF should only be accessible to users who
have been authenticated using a strong authentication mechanism. [Do
we need to specify? Or will any SSH authentication mechanism
suffice?]
Also, the configuration data may include sensitive information, such
as usernames or security keys. So, NETCONF should only be used over
communications channels that provide strong encryption for data
privacy. [Do we need to specify? Or will any SSH encryption algorithm
suffice?]
If the NETCONF server provides remote shell access through insecure
protocols, such as Telnet, care should be taken to prevent execution
of the NETCONF program when strong user authentication or data
privacy is not available.
Wasserman Expires February 25, 2004 [Page 11]
Internet-Draft NETCONF over SSH August 2003
8. Acknowledgements
Some of the examples in the document were adapted from a presentation
authored by Ted Goddard. This document was written using the xml2rfc
tool described in RFC 2629 [7].
Wasserman Expires February 25, 2004 [Page 12]
Internet-Draft NETCONF over SSH August 2003
Normative References
[1] Enns, R., "NETCONF Configuration Protocol",
draft-ietf-netconf-prot-00 (work in progress), August 2003.
[2] Ylonen, T., Kivinen, T., Rinne, T. and S. Lehtinen, "SSH
Connection Protocol", draft-ietf-secsh-connect-17 (work in
progress), July 2003.
[3] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S.
Lehtinen, "SSH Transport Layer Protocol",
draft-ietf-secsh-transport-16 (work in progress), July 2003.
[4] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S.
Lehtinen, "SSH Authentication Protocol",
draft-ietf-secsh-userauth-17 (work in progress), July 2003.
Wasserman Expires February 25, 2004 [Page 13]
Internet-Draft NETCONF over SSH August 2003
Informative References
[5] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
9, RFC 2026, October 1996.
[6] Postel, J. and J. Reynolds, "Telnet Protocol Specification", STD
8, RFC 854, May 1983.
[7] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June
1999.
Author's Address
Margaret Wasserman
Wind River
10 Tara Blvd, Suite 330
Nashua, NH 03062
US
Phone: +1 603 897 2067
EMail: mrw@windriver.com
URI: http://www.windriver.com/
Wasserman Expires February 25, 2004 [Page 14]
Internet-Draft NETCONF over SSH August 2003
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to
obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Full Copyright Statement
Copyright (C) The Internet Society (2003). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
Wasserman Expires February 25, 2004 [Page 15]
Internet-Draft NETCONF over SSH August 2003
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Wasserman Expires February 25, 2004 [Page 16]