RFC 4742

Using the NETCONF Configuration Protocol over Secure SHell (SSH)

📅 published December 2006, from ietf

RFC 4742: Using the NETCONF Configuration Protocol over Secure SHell (SSH) 🎀

Okay bestie, let's start with the vibe check ✨. This is RFC 4742 from the Network Working Group, and it's on the Standards Track, so it's a real standard, no cap 👑. It came out in December 2006. M. Wasserman (ThingMagic) and T. Goddard (ICEsoft Technologies, Inc.) wrote it. The title block doesn't list anything it obsoletes or updates, so it's just vibing on its own 🦋.

Status of This Memo 📜

Okay so this doc is an Internet standards track protocol for the whole Internet community, and it's literally asking for discussion and suggestions to make it better 🫶. If you want to know where this protocol stands in standardization, check the current edition of "Internet Official Protocol Standards" (STD 1) 📚. And the distribution of this memo is unlimited, so share it with everyone 🌈.

Copyright Notice 🔒

Abstract ✨

This doc describes a method for invoking and running the Network Configuration Protocol (NETCONF) within a Secure Shell (SSH) session as an SSH subsystem 🦋.

Table of Contents 🧚

   1. Introduction ....................................................2
   2. Requirements Terminology ........................................2
   3. Starting NETCONF over SSH .......................................2
      3.1. Capabilities Exchange ......................................3
   4. Using NETCONF over SSH ..........................................5
   5. Exiting the NETCONF Subsystem ...................................6
   6. Security Considerations .........................................6
   7. IANA Considerations .............................................7
   8. Acknowledgements ................................................7
   9. References ......................................................8
      9.1. Normative References .......................................8
      9.2. Informative References .....................................8

1. Introduction 💖

Okay so the NETCONF protocol [RFC4721] is XML-based, and it's used to manage the configuration of networking equipment 🔥. It's defined to be session-layer and transport independent, which means mappings can be defined for multiple session-layer or transport protocols. This document defines how NETCONF can be used within a Secure Shell (SSH) session, using the SSH connection protocol [RFC4254] over the SSH transport protocol [RFC4253]. This mapping lets a user or application run NETCONF from a secure shell session 💅.

Throughout this doc, "client" and "server" 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 one 🎀. "Manager" and "agent" refer to the two ends of the NETCONF protocol session. The manager issues NETCONF remote procedure call (RPC) commands, and the agent replies to them 🧚. When NETCONF runs over SSH using the mapping in this doc, the client is always the manager, and the server is always the agent 👑.

2. Requirements Terminology 📚

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 [RFC2119].

3. Starting NETCONF over SSH 🦋

Okay so to run NETCONF over SSH, the client first sets up an SSH transport connection using the SSH transport protocol. The client and server then exchange keys for message integrity and encryption 🔐. Next, the client invokes the "ssh-userauth" service to authenticate the user, as described in the SSH authentication protocol [RFC4252]. Once the user is successfully authenticated, the client invokes the "ssh-connection" service, which is also known as the SSH connection protocol 💜.

After the ssh-connection service is established, the client opens a channel of type "session", and that results in an SSH session ✨.

Once the SSH session is established, the user (or application) invokes NETCONF as an SSH subsystem called "netconf" 🌸. Subsystem support is a feature of SSH version 2 (SSHv2) and is not included in SSHv1. Running NETCONF as an SSH subsystem means the script doesn't have to recognize shell prompts or skip over extra info, like a system message sent at shell start-up 🙈. Even so, when a subsystem is used, some extra messages may still get printed by the user's start-up scripts. Implementations MUST skip over these messages by searching for an 'xml' start directive, which MUST be followed by a <hello> element in the 'NETCONF' namespace 🧹.

So NETCONF traffic is easy for firewalls and other network devices to spot and filter 🔥. NETCONF servers MUST default to providing access to the "netconf" SSH subsystem only when the SSH session is established using the IANA-assigned TCP port <830>. Servers SHOULD be configurable to allow access to the netconf SSH subsystem over other ports 🍓.

A user (or application) could use this command line to invoke NETCONF as an SSH subsystem on the IANA-assigned port 💻:

   [user@client]$ ssh -s server.example.org -p <830> netconf

Note that the -s option makes the command ("netconf") get invoked as an SSH subsystem 🧚.

3.1. Capabilities Exchange 🎀

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 application) can parse this message to figure out which NETCONF capabilities the server supports 👀.

The client must also send an XML document containing a <hello> element to tell the server its capabilities. The document containing the <hello> element MUST be the first XML document the client sends after the NETCONF session is established 💅.

Here's an example of a capability exchange. Messages sent by the client are marked with "C:", and messages sent by the server are marked with "S:" 💖.

   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <hello>
   S:   <capabilities>
   S:     <capability>
   S:       urn:ietf:params:xml:ns:netconf:base:1.0
   S:     </capability>
   S:     <capability>
   S:       urn:ietf:params:ns:netconf:capability:startup:1.0
   S:     </capability>
   S:   </capabilities>
   S:   <session-id>4<session-id>
   S: </hello>
   S: ]]>]]>

   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <hello>
   C:   <capabilities>
   C:     <capability>
   C:       urn:ietf:params:xml:ns:netconf:base:1.0
   C:     </capability>
   C:   </capabilities>
   C: </hello>
   C: ]]>]]>

Even though the example shows the server's <hello> going first, both sides send their message as soon as the NETCONF subsystem is initialized, so they might go at the same time 🌈.

As the example shows, a special character sequence, ]]>]]>, MUST be sent by both the client and the server after each XML document in the NETCONF exchange 🚨. This sequence can't legally appear in an XML document, so it can be used to clearly mark where the current document ends. That lets the NETCONF exchange resync if there's an XML syntax or parsing error 🧚.

7. IANA Considerations 🦋

okay so IANA has this sweet little job: they assigned a TCP port number as the default for NETCONF over SSH sessions 🎀 and that port is 830. bestie, that's the one 🌸

IANA is also requested to assign the SSH Service Name "netconf" 💅 (this is the [RFC4250] thing, and it's listed with the reference RFC 4742)

Here's how that table looks:

         Service Name                  Reference
         -------------                 ---------
         netconf                       RFC 4742

8. Acknowledgements 🫶

this doc was written with the xml2rfc tool, described in RFC 2629 [RFC2629] 💻✨

so many people helped out 😭💖 extensive input came from the other members of the NETCONF design team: Andy Bierman, Weijing Chen, Rob Enns, Wes Hardaker, David Harrington, Eliot Lear, Simon Leinen, Phil Shafer, Juergen Schoenwaelder, and Steve Waldbusser 👑 and then a few more people reviewed it and gave valuable input: Olafur Gudmundsson, Sam Hartman, Scott Hollenbeck, Bill Sommerfeld, and Bert Wijnen 🌈

9. References 📚

9.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 🔥
[RFC4250] Lehtinen, S. and C. Lonvick, "The Secure Shell (SSH) Protocol Assigned Numbers", RFC 4250, January 2006. 🦋
[RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Authentication Protocol", RFC 4252, January 2006. 🌸
[RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Transport Layer Protocol", RFC 4253, January 2006. 🧚
[RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Connection Protocol", RFC 4254, January 2006. 💜
[RFC4721] Enns, R., Ed., "NETCONF Configuration Protocol", RFC 4721, December 2006. ⭐

9.2. Informative References

[RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. 🍓

Authors' Addresses 💌

Margaret Wasserman ThingMagic One Broadway, 5th Floor Cambridge, MA 02142 USA

Phone: +1 781 405-7464 EMail: margaret@thingmagic.com URI: http://www.thingmagic.com

Ted Goddard ICEsoft Technologies, Inc. Suite 300, 1717 10th St. NW Calgary, AB T2M 4S2 Canada

Phone: +1 403 663-3322 EMail: ted.goddard@icesoft.com URI: http://www.icesoft.com

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property 🔐

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights 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; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat 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 implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.

Acknowledgement 💖

Funding for the RFC Editor function is currently provided by the Internet Society. ✨

📦 where this page comes from

ietf: rfc4742 2006-12
💖 girlified by claude-haiku-5-5 on 2026-10-16: a language model's rewrite of the original, under its terms