Network Working Group M. Wasserman
Internet-Draft Nokia
Expires: April 18, 2004 T. Goddard
Wind River
October 19, 2003
Using the NETCONF Configuration Protocol over Secure Shell (SSH)
draft-ietf-netconf-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 April 18, 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 as
an SSH subsystem. Some features of the NETCONF protocol are not
suited for use in a single shell session, and those limitations are
described here.
Wasserman & Goddard Expires April 18, 2004 [Page 1]
Internet-Draft NETCONF over SSH October 2003
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Starting NETCONF over SSH . . . . . . . . . . . . . . . . . . 4
2.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . . . 5
2.2 Reversability of Connections . . . . . . . . . . . . . . . . . 6
3. Using NETCONF over SSH . . . . . . . . . . . . . . . . . . . . 7
4. Sending NETCONF Notifications over SSH . . . . . . . . . . . . 9
5. Exiting the NETCONF Subsystem . . . . . . . . . . . . . . . . 10
6. Running NETCONF from an SSH Shell . . . . . . . . . . . . . . 11
6.1 Starting a NETCONF Shell Session . . . . . . . . . . . . . . . 11
6.2 Exiting a NETCONF Shell Session . . . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 13
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 14
Normative References . . . . . . . . . . . . . . . . . . . . . 15
Informative References . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16
Intellectual Property and Copyright Statements . . . . . . . . 17
Wasserman & Goddard Expires April 18, 2004 [Page 2]
Internet-Draft NETCONF over SSH October 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
session-layer and transport independent, allowing mappings to be
defined for multiple session-layer or 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 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 NETCONF notifications, if
enabled, will also be transmitted over the same channel.
Throughout this document, the terms "client" and "server" are used to
refer to the two ends of the SSH transport connection. The client
actively opens the SSH connection, and the server passively listens
for the incoming SSH connection.
The terms "manager" and "agent" are used to refer to the two ends of
the NETCONF protocol session. The manager issues NETCONF RPC
commands, and the agent replies to those commands. Depending upon
negotiated capabilities, the manager may also receive NETCONF
notifications and the agent may send notifications.
Wasserman & Goddard Expires April 18, 2004 [Page 3]
Internet-Draft NETCONF over SSH October 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 the client
and server will exchange keys for message integrity and encryption.
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.
Once the SSH session has been established, the user (or script) will
invoke NETCONF as an SSH subsystem called "netconf". Running NETCONF
as an SSH subsystem avoids the need for the script to recognize shell
prompts or skip over extraneous information, such as a system
message, 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. Although this example shows the
text transmitted by both sides, the server MUST NOT echo the commands
that it receives back to the client.
Wasserman & Goddard Expires April 18, 2004 [Page 4]
Internet-Draft NETCONF over SSH October 2003
<!-- The user (or script) invokes the SSH subsystem. Depending upon
the configuration of the client and server, the passphrase prompt
may not be issued or may be replaced by a password prompt. -->
[user@client]$ ssh -s server.example.org netconf
Enter passphrase for key '/foo/.ssh/id_dsa':
<!-- The NETCONF subsystem running on the server sends a complete
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/agent</capbability>
<capability>http://ietf.org/xmlconf/1.0/base#lock</capability>
</capabilities>
</hello>
<!-- The client sends a complete XML document to the server. -->
<?xml version="1.0" encoding="UTF-8"?>
<hello>
<capabilities>
<capability>http://ietf.org/xmlconf/1.0/base</capability>
<capability>http://ietf.org/xmlcong/1.0/manager</capability>
<capability>http://ietf.org/xmlconf/1.0/base#lock</capability>
</capabilities>
</hello>
While the NETCONF subsystem is active, the NETCONF manager can
interact with the NETCONF agent by sending complete XML documents
containing NETCONF RPC elements, and the NETCONF server will respond
by sending complete XML documents containing appropriate RPC replies.
2.1 Capabilities Exchange
As indicated in the example above, the server MUST 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 which
NETCONF capabilities are supported by the server.
The client must also send an XML document containing a <hello>
element to indicate the client's capabilities to the server. The
document containing the <hello> element must be the first XML
document that the client sends after the NETCONF session is
Wasserman & Goddard Expires April 18, 2004 [Page 5]
Internet-Draft NETCONF over SSH October 2003
established.
Although the example shows the server sending a $lt;hello> message
followed by the client's message, both sides will send the message as
soon as the NETCONF subsystem is initialized, perhaps simultaneously.
2.2 Reversability of Connections
The NETCONF protocol is reversible -- either the manager or the agent
may initiate the session-layer or transport connection. Once the
session is established, the NETCONF capabilities exchange will be
used to indicate which side of the connection is the agent and which
is the manager, as indicated in the previous example. If there is no
agreement, each side MUST close the transport connection and log an
error.
In order to provide for reversability when used over SSH, it may be
necessary for either the NETCONF agent or the NETCONF manager to have
a well known host key, as it is always required for the SSH server to
have a well known host key. Thus, the server will authenticate
itself to the client with its host key. The client will then
authenticate itself with any allowable mechanism, as specified in
[4]. The authenticated principle is then passed to NETCONF.
Because the use of NETCONF may involve transferring sensitive
configuration information in either direction, both the client and
server must be authenticated and all of the data exchanged must be
encrypted. If either the client or server fails to successfully
authenticate itself, or if it is not possible to establish an
encrypted session, the NETCONF session MUST be aborted.
Wasserman & Goddard Expires April 18, 2004 [Page 6]
Internet-Draft NETCONF over SSH October 2003
3. Using NETCONF over SSH
A NETCONF over SSH session consists of the manager and agent
exchanging complete XML documents. Once the session has been
established and capabilities have been exchanged, the manager will
send complete XML documents to the server containing <rpc> elements,
and the agent will respond with complete XML documents containing
<rpc-reply> elements.
To continue the example given above, an XMLCONF over SSH session to
retrieve a set of configuration information might look like this:
<!-- The manager 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 agent 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 & Goddard Expires April 18, 2004 [Page 7]
Internet-Draft NETCONF over SSH October 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 & Goddard Expires April 18, 2004 [Page 8]
Internet-Draft NETCONF over SSH October 2003
4. Sending NETCONF Notifications over SSH
The SSH protocol has the capability to support multiple sessions, and
therefore, theoretically to support multiple NETCONF channels.
However, because the NETCONF over SSH mapping is designed for
simplified scripting, use of this mapping for such multiple purposes
is not supported.
Instead, if both the manager and agent indicate support for the
notification capability and the manager issues a <notification-open>
RPC command, notifications may be sent over the SSH session,
interleaved with NETCONF RPC commands and responses. Notifications
are transmitted and received as described in RFC 3195 [5], with the
exception that authentication information is passed from the SSH
layer instead of the BEEP layer.
Once the client or the server begins sending an XML document, it must
suspend all other output (i.e. other XML documents) until the
document has been sent in its entirety. This means that asynchronous
notifications may be delayed while waiting for the transmission of
other documents to be completed. It is recommended that if an agent
has at least one notification pending and at least one response
pending that the notification(s) be sent first. If a manager deems
that notifications are particularly time-sensitive, it may open
another NETCONF session that is used only for notifications.
It is acceptable for a NETCONF manager to be sending a command to the
agent, while the agent is simultaneously sending a response or
notification to the manager.
Once the manager has requested that the agent send notifications, via
a <notification-open> RPC message, the agent may send notification
until the SSH session is closed.
Wasserman & Goddard Expires April 18, 2004 [Page 9]
Internet-Draft NETCONF over SSH October 2003
5. Exiting the NETCONF Subsystem
Exiting NETCONF is accomplished using the <kill-session> operation.
When a <kill-session> command is issued by the manager, the agent
shall respond, terminate the SSH session, and close the TCP
connection.
To continue the example used in previous sections, an existing
NETCONF subsystem session could be closed as follows:
<!-- The manager 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 agent 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 subsystem exits, ending the SSH session and returning
the user (or script) to the local shell prompt. -->
[user@client]$
Wasserman & Goddard Expires April 18, 2004 [Page 10]
Internet-Draft NETCONF over SSH October 2003
6. Running NETCONF from an SSH Shell
The techniques described in this document could be used to access the
NETCONF protocol over the SSH shell session, or from other shell
types such as a console session or a Telnet [7] connection. However,
there are serious security implications associated with allowing
NETCONF access via any method that does not provide strong support
for user authentication, server authentication and data privacy. See
the Security Considerations section for more details.
If the server supports NETCONF invocation from an SSH shell session,
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.
6.1 Starting a NETCONF Shell Session
To the user, the establishment of an SSH shell and the invocation of
the NETCONF program may look similar to the following example:
<!-- 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', but which might have different
names on different systems. -->
[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>
6.2 Exiting a NETCONF Shell Session
When the user has run NETCONF from a shell, he will need to exit the
Wasserman & Goddard Expires April 18, 2004 [Page 11]
Internet-Draft NETCONF over SSH October 2003
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:
<!-- The manager 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? -->
<?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 agent 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 & Goddard Expires April 18, 2004 [Page 12]
Internet-Draft NETCONF over SSH October 2003
7. Security Considerations
NETCONF is used to access and modify configuration and state
information, so the ability to access this protocol should be limited
to users and systems that are authorized to view or modify the
agent's configuration and state data.
The identity of the server MUST be verified and authenticated by the
client before password-based authentication data or any configuration
data is sent to it. The identity of the client MUST also be verified
and authenticated by the server to ensure that the incoming client
request is legitimate. Neither side should establish a connection
with an unknown, unexpected or incorrect identity on the opposite
side.
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. This document defines a NETCONF over SSH mapping which
provides for support of strong encryption and authentication.
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. Because it may be difficult or impossible,
in some operating environments, to determine whether a shell command
was accessed over a secure protocol, such as SSH, or an insecure
protocol, such as Telnet, it may be necessary to disable insecure
shell access to the system to prevent insecure access to a NETCONF
program. Alternatively, it would be possible to disable NETCONF
access from the command line, only allowing NETCONF to be accessed
through invocation of the SSH 'netconf' subsystem.
Because NETCONF data is being sent over the standard SSH protocol
port mapping (to the NETCONF subsystem or shell), use of this
protocol mapping would allow NETCONF data to be transferred over a
firewall boundary that has open access for SSH connections. Network
policies which restrict NETCONF operations to within a trusted
network may clash with other policies that allows network-external
SSH access to internal ssh services.
Wasserman & Goddard Expires April 18, 2004 [Page 13]
Internet-Draft NETCONF over SSH October 2003
8. Acknowledgements
This document was written using the xml2rfc tool described in RFC
2629 [8].
Extensive input was received from the members of the NETCONF design
team, including: Andy Bierman, Weijing Chen, Rob Enns, Wes Hardaker,
Eliot Lear, Simon Leinen, Phil Shafer, Juergen Shoenwaelder and Steve
Waldbusser. The following people have also reviewed this document
and provided helpful input: Bill Sommerfeld.
Wasserman & Goddard Expires April 18, 2004 [Page 14]
Internet-Draft NETCONF over SSH October 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.
[5] New, D. and M. Rose, "Reliable Delivery for syslog", RFC 3195,
November 2001.
Wasserman & Goddard Expires April 18, 2004 [Page 15]
Internet-Draft NETCONF over SSH October 2003
Informative References
[6] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
9, RFC 2026, October 1996.
[7] Postel, J. and J. Reynolds, "Telnet Protocol Specification", STD
8, RFC 854, May 1983.
[8] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June
1999.
Authors' Addresses
Margaret Wasserman
Nokia
5 Wayside Road
Burlington, MA 01803
USA
Phone: +1 781 993 3858
EMail: margaret.wasserman@nokia.com
URI: http://www.nokia.com
Ted Goddard
Wind River
#180, 6815-8th St. N.E.
Calgary, AB T2E 7H7
Canada
Phone: +1 403 730 7590
EMail: ted.goddard@windriver.com
Wasserman & Goddard Expires April 18, 2004 [Page 16]
Internet-Draft NETCONF over SSH October 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 & Goddard Expires April 18, 2004 [Page 17]
Internet-Draft NETCONF over SSH October 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 & Goddard Expires April 18, 2004 [Page 18]
