draft-ietf-netconf-server-model-04.txt   draft-ietf-netconf-server-model-05.txt 
NETCONF Working Group K. Watsen NETCONF Working Group K. Watsen
Internet-Draft Juniper Networks Internet-Draft Juniper Networks
Intended status: Standards Track J. Schoenwaelder Intended status: Standards Track J. Schoenwaelder
Expires: April 29, 2015 Jacobs University Bremen Expires: June 14, 2015 Jacobs University Bremen
October 26, 2014 December 11, 2014
NETCONF Server Configuration Model NETCONF Server and RESTCONF Server Configuration Models
draft-ietf-netconf-server-model-04 draft-ietf-netconf-server-model-05
Abstract Abstract
This draft defines a NETCONF server configuration data model. This This draft defines a NETCONF server configuration data model and a
data model enables configuration of the NETCONF service itself, RESTCONF server configuration data model. These data models enable
including which transports it supports, what ports they listen on, configuration of the NETCONF and RESTCONF services themselves,
whether call-home is supported, and associated parameters. including which transports are supported, what ports the servers
listens on, whether call-home is supported, and associated
parameters.
Editorial Note (To be removed by RFC Editor)
This draft contains many placeholder values that need to be replaced
with finalized values at the time of publication. This note
summarizes all of the substitutions that are needed. Please note
that no other RFC Editor instructions are specified anywhere else in
this document.
This document contains references to other drafts in progress, both
in the Normative References section, as well as in body text
throughout. Please update the following references to reflect their
final RFC assignments:
o draft-ietf-netconf-rfc5539bis
o draft-ietf-netconf-restconf
o draft-ietf-netconf-call-home
o draft-ietf-netmod-snmp-cfg
Artwork in this document contains shorthand references to drafts in
progress. Please apply the following replacements:
o "VVVV" --> the assigned RFC value for this draft
o "WWWW" --> the assigned RFC value for draft-ietf-netconf-
rfc5539bis
o "XXXX" --> the assigned RFC value for draft-ietf-netconf-restconf
o "YYYY" --> the assigned RFC value for draft-ietf-netconf-call-home
o "ZZZZ" --> the assigned RFC value for draft-ietf-netmod-snmp-cfg
Artwork in this document contains placeholder values for ports
pending IANA assignment from "draft-ietf-netconf-call-home". Please
apply the following replacements:
o "7777" --> the assigned port value for "netconf-ch-ssh"
o "8888" --> the assigned port value for "netconf-ch-tls"
o "9999" --> the assigned port value for "restconf-ch-tls"
Artwork in this document contains placeholder values for the date of
publication of this draft. Please apply the following replacement:
o "2014-12-11" --> the publication date of this draft
The following two Appendix sections are to be removed prior to
publication:
o Appendix B. Change Log
o Appendix C. Open Issues
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
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."
This Internet-Draft will expire on April 29, 2015. This Internet-Draft will expire on June 14, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 4
2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Support all NETCONF transports . . . . . . . . . . . . . 3 2.1. Support all NETCONF and RESTCONF transports . . . . . . . 5
2.2. Enable each transport to select which keys to use . . . . 4 2.2. Enable each transport to select which keys to use . . . . 5
2.3. Support authenticating client-certificates . . . . . . . 4 2.3. Support authenticating NETCONF clients certificates . . . 5
2.4. Support mapping authenticated client-certificates to 2.4. Support mapping authenticated NETCONF client-certificates
usernames . . . . . . . . . . . . . . . . . . . . . . . . 4 to usernames . . . . . . . . . . . . . . . . . . . . . . 6
2.5. Support both Listening for connections and Call Home . . 4 2.5. Support both Listening for connections and Call Home . . 6
2.6. For Call Home connections . . . . . . . . . . . . . . . . 4 2.6. For Call Home connections . . . . . . . . . . . . . . . . 6
2.6.1. Support more than one application . . . . . . . . . . 4 2.6.1. Support more than one northbound application . . . . 6
2.6.2. Support applications having more than one server . . 5 2.6.2. Support applications having more than one server . . 6
2.6.3. Support a reconnection strategy . . . . . . . . . . . 5 2.6.3. Support a reconnection strategy . . . . . . . . . . . 6
2.6.4. Support both persistent and periodic connections . . 5 2.6.4. Support both persistent and periodic connections . . 7
2.6.5. Reconnection strategy for periodic connections . . . 5 2.6.5. Reconnection strategy for periodic connections . . . 7
2.6.6. Keep-alives for persistent connections . . . . . . . 5 2.6.6. Keep-alives for persistent connections . . . . . . . 7
2.6.7. Customizations for periodic connections . . . . . . . 6 2.6.7. Customizations for periodic connections . . . . . . . 7
3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. The NETCONF Server Configuration Model . . . . . . . . . . . 8
3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1.1. The "session-options" subtree . . . . . . . . . . . . 6 3.1.1. The "session-options" subtree . . . . . . . . . . . . 8
3.1.2. The "listen" subtree . . . . . . . . . . . . . . . . 6 3.1.2. The "listen" subtree . . . . . . . . . . . . . . . . 8
3.1.3. The "call-home" subtree . . . . . . . . . . . . . . . 7 3.1.3. The "call-home" subtree . . . . . . . . . . . . . . . 9
3.1.4. The "ssh" subtree . . . . . . . . . . . . . . . . . . 9 3.1.4. The "ssh" subtree . . . . . . . . . . . . . . . . . . 11
3.1.5. The "tls" subtree . . . . . . . . . . . . . . . . . . 9 3.1.5. The "tls" subtree . . . . . . . . . . . . . . . . . . 11
3.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 3.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 12
4. Implementation strategy for keep-alives . . . . . . . . . . . 24 4. The RESTCONF Server Configuration Model . . . . . . . . . . . 25
4.1. Keep-alives for SSH . . . . . . . . . . . . . . . . . . . 24 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 25
4.2. Keep-alives for TLS . . . . . . . . . . . . . . . . . . . 25 4.1.1. The "listen" subtree . . . . . . . . . . . . . . . . 25
5. Security Considerations . . . . . . . . . . . . . . . . . . . 25 4.1.2. The "call-home" subtree . . . . . . . . . . . . . . . 26
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 4.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 28
7. Other Considerations . . . . . . . . . . . . . . . . . . . . 26
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26 5. Implementation strategy for keep-alives . . . . . . . . . . . 36
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.1. Keep-alives for SSH . . . . . . . . . . . . . . . . . . . 37
9.1. Normative References . . . . . . . . . . . . . . . . . . 27 5.2. Keep-alives for TLS . . . . . . . . . . . . . . . . . . . 37
9.2. Informative References . . . . . . . . . . . . . . . . . 28 6. Security Considerations . . . . . . . . . . . . . . . . . . . 37
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 29 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
A.1. SSH Transport Configuration + State . . . . . . . . . . . 29 8. Other Considerations . . . . . . . . . . . . . . . . . . . . 39
A.2. TLS Transport Configuration + State . . . . . . . . . . . 31 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 32 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 39
B.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 33 10.1. Normative References . . . . . . . . . . . . . . . . . . 39
B.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 33 10.2. Informative References . . . . . . . . . . . . . . . . . 40
B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 33 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 41
B.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 33 A.1. NETCONF Configuration using SSH Transport . . . . . . . . 41
Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 34 A.2. NETCONF Configuration using TLS Transport . . . . . . . . 42
A.3. RESTCONF Configuration using TLS Transport . . . . . . . 44
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 44
B.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 44
B.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 45
B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 45
B.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 45
B.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 45
Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 46
1. Introduction 1. Introduction
This draft defines a NETCONF [RFC6241] server configuration data This draft defines a NETCONF [RFC6241] server configuration data
model. This data model enables configuration of the NETCONF service model and a RESTCONF [draft-ietf-netconf-restconf] server
itself, including which transports are supported, what ports the configuration data model. These data models enable configuration of
server listens on, whether call-home is supported, and associated the NETCONF and RESTCONF services themselves, including which
parameters. transports are supported, what ports the servers listens on, whether
call-home is supported, and associated parameters.
1.1. Terminology 1.1. Terminology
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
1.2. Tree Diagrams 1.2. Tree Diagrams
A simplified graphical representation of data models is used in this A simplified graphical representation of the data models is used in
document. The meaning of the symbols in these diagrams is as this document. The meaning of the symbols in these diagrams is as
follows: follows:
o Brackets "[" and "]" enclose list keys. o Brackets "[" and "]" enclose list keys.
o Abbreviations before data node names: "rw" means configuration o Abbreviations before data node names: "rw" means configuration
(read-write) and "ro" state data (read-only). (read-write) and "ro" state data (read-only).
o Symbols after data node names: "?" means an optional node, "!" o Symbols after data node names: "?" means an optional node, "!"
means a presence container, and "*" denotes a list and leaf-list. means a presence container, and "*" denotes a list and leaf-list.
o Parentheses enclose choice and case nodes, and case nodes are also o Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":"). marked with a colon (":").
o Ellipsis ("...") stands for contents of subtrees that are not
shown.
2. Objectives 2. Objectives
The primary purpose of the YANG module defined herein is to enable The primary purpose of the YANG modules defined herein is to enable
the configuration of the NETCONF server service on the device. This the configuration of the NETCONF and RESTCONF services on a network
scope includes the following objectives: element. This scope includes the following objectives:
2.1. Support all NETCONF transports 2.1. Support all NETCONF and RESTCONF transports
The YANG module should support all current NETCONF transports, namely The YANG module should support all current NETCONF and RESTCONF
NETCONF over SSH [RFC6242] and NETCONF over TLS [rfc5539bis], and be transports, namely NETCONF over SSH [RFC6242], NETCONF over TLS
extensible to support future transports as necessary. [draft-ietf-netconf-rfc5539bis], and RESTCONF over TLS
[draft-ietf-netconf-restconf], and to be extensible to support future
transports as necessary.
Because implementations may not support all transports, the module Because implementations may not support all transports, the module
should use YANG "feature" statements so that implementations can should use YANG "feature" statements so that implementations can
accurately advertise which transports are supported. accurately advertise which transports are supported.
2.2. Enable each transport to select which keys to use 2.2. Enable each transport to select which keys to use
Systems may have a multiplicity of host-keys or server-certificates Servers may have a multiplicity of host-keys or server-certificates
from which subsets are configured for specific uses. For instance, a from which subsets may be selected for specific uses. For instance,
system may want to use one set of SSH host-keys when listening on a NETCONF server may want to use one set of SSH host-keys when
port 830, and a different set of SSH host-keys when calling home. listening on port 830, and a different set of SSH host-keys when
calling home. The data models provided herein should enable
configuration of which keys to use on a per-use basis.
2.3. Support authenticating client-certificates 2.3. Support authenticating NETCONF clients certificates
When certificates are used to authenticate NETCONF clients, there is When a certificate is used to authenticate a NETCONF client, either
a need to configure the system to know how to authenticate the when using the TLS transport or the SSH transport with X.509
certificates. The system should be able to do this either by using certificates [RFC6187], there is a need to configure the server to
path-validation to a configured trust anchor or by matching the know how to authenticate the certificates. The server should be able
client-certificate to one previously configured. to do this either by using path-validation to a configured trust
anchor or by matching the client-certificate to one previously
configured.
2.4. Support mapping authenticated client-certificates to usernames 2.4. Support mapping authenticated NETCONF client-certificates to
usernames
Some transports (e.g., TLS) need additional support to map Some NETCONF transports (e.g., TLS) need additional support to map
authenticated transport-level sessions to a NETCONF username. The authenticated transport-level sessions to a NETCONF username. The
NETCONF server model defined herein should define an ability for this NETCONF server model defined herein should define an ability for this
mapping to be configured." mapping to be configured."
2.5. Support both Listening for connections and Call Home 2.5. Support both Listening for connections and Call Home
NETCONF has always supported the server opening a port to listen for The NETCONF and RESTCONF protocols were originally defined as having
client connections. More recently the NETCONF working group defined the server opening a port to listen for client connections. More
support for call-home ([draft-ietf-netconf-call-home]). The module recently the NETCONF working group defined support for call-home
should configure both listening for connections and call-home. ([draft-ietf-netconf-call-home]), enabling the server to initiate the
connection to the client, for both the NETCONF and RESTCONF
protocols. Thus the modules defined herein should enable
configuration for both listening for connections and calling home.
Because implementations may not support both listening for Because implementations may not support both listening for
connections and call home, YANG "feature" statements should be used connections and calling home, YANG "feature" statements should be
so that implementation can accurately advertise the connection types used so that implementation can accurately advertise the connection
it supports. types it supports.
2.6. For Call Home connections 2.6. For Call Home connections
The following objectives only pertain to call home connections. The following objectives only pertain to call home connections.
2.6.1. Support more than one application 2.6.1. Support more than one northbound application
A device may be managed by more than one northbound application. For A device may be managed by more than one northbound application. For
instance, a deployment may have one application for provisioning and instance, a deployment may have one application for provisioning and
another for fault monitoring. Therefore, when it is desired for a another for fault monitoring. Therefore, when it is desired for a
device to initiate call home connections, it should be able to do so device to initiate call home connections, it should be able to do so
for more than one application. to more than one application.
2.6.2. Support applications having more than one server 2.6.2. Support applications having more than one server
An application managing a device may implement a high-availability An application managing a device may implement a high-availability
strategy employing a multiplicity of active and/or passive servers. strategy employing a multiplicity of active and/or passive servers.
Therefore, when it is desired for a device to initiate call home Therefore, when it is desired for a device to initiate call home
connections, it should be able to connect to any of the application's connections, it should be able to connect to any of the application's
servers. servers.
2.6.3. Support a reconnection strategy 2.6.3. Support a reconnection strategy
skipping to change at page 5, line 30 skipping to change at page 7, line 15
last server it was connected to. Secondary settings might specify last server it was connected to. Secondary settings might specify
the frequency of attempts and number of attempts per server. the frequency of attempts and number of attempts per server.
Therefore, a reconnection strategy should be configurable. Therefore, a reconnection strategy should be configurable.
2.6.4. Support both persistent and periodic connections 2.6.4. Support both persistent and periodic connections
Applications may vary greatly on how frequently they need to interact Applications may vary greatly on how frequently they need to interact
with a device, how responsive interactions with devices need to be, with a device, how responsive interactions with devices need to be,
and how many simultaneous connections they can support. Some and how many simultaneous connections they can support. Some
applications may need a persistent connection to devices to optimize applications may need a persistent connection to devices to optimize
real-time interactions, while others are satisfied with periodic real-time interactions, while others prefer periodic interactions in
interactions and reduced resources required. Therefore, when it is order to minimize resource requirements. Therefore, when it is
necessary for devices to initiate connections, the type of connection necessary for devices to initiate connections, the type of connection
desired should be configured. desired should be configurable.
2.6.5. Reconnection strategy for periodic connections 2.6.5. Reconnection strategy for periodic connections
The reconnection strategy should apply to both persistent and The reconnection strategy should apply to both persistent and
periodic connections. How it applies to periodic connections becomes periodic connections. How it applies to periodic connections becomes
clear when considering that a periodic "connection" is a logical clear when considering that a periodic "connection" is a logical
connection to a single server. That is, the periods of connection to a single server. That is, the periods of
unconnectedness are intentional as opposed to due to external unconnectedness are intentional as opposed to due to external
reasons. A periodic "connection" should always reconnect to the same reasons. A periodic "connection" should always reconnect to the same
server until it is no longer able to, at which time the reconnection server until it is no longer able to, at which time the reconnection
skipping to change at page 6, line 25 skipping to change at page 8, line 13
to it. to it.
A common communication pattern is that one data transmission is many A common communication pattern is that one data transmission is many
times closely followed by another. For instance, if the device needs times closely followed by another. For instance, if the device needs
to send a notification message, there's a high probability that it to send a notification message, there's a high probability that it
will send another shortly thereafter. Likewise, the application may will send another shortly thereafter. Likewise, the application may
have a sequence of pending messages to send. Thus, it should be have a sequence of pending messages to send. Thus, it should be
possible for a device to hold a connection open until some amount of possible for a device to hold a connection open until some amount of
time of no data being transmitted as transpired. time of no data being transmitted as transpired.
3. Data Model 3. The NETCONF Server Configuration Model
3.1. Overview 3.1. Overview
3.1.1. The "session-options" subtree 3.1.1. The "session-options" subtree
module: ietf-netconf-server module: ietf-netconf-server
+--rw netconf-server +--rw netconf-server
+--rw session-options +--rw session-options {session-options}?
+--rw hello-timeout? uint32 +--rw hello-timeout? uint32
+--rw idle-timeout? uint32 +--rw idle-timeout? uint32
The above subtree illustrates how this YANG module enables The above subtree illustrates how the ietf-netconf-server YANG module
configuration of NETCONF session options, independent of any enables configuration of NETCONF session options, independent of any
transport or connection strategy. Please see the YANG module transport or connection strategy. A feature statement is used for
(Section 3.2) for a complete description of these configuration the server to advertise support for configuring these NETCONF server
knobs. options. Please see the YANG module (Section 3.2) for a complete
description of these configuration knobs.
3.1.2. The "listen" subtree 3.1.2. The "listen" subtree
module: ietf-netconf-server module: ietf-netconf-server
+--rw netconf-server +--rw netconf-server
+--rw listen {"(ssh-listen or tls-listen)"}? // YANG 1.1 syntax +--rw listen {listen}?
+--rw max-sessions? uint16 +--rw max-sessions? uint16
+--rw endpoint* [name] +--rw endpoint* [name]
+--rw name string +--rw name string
+--rw (transport) +--rw (transport)
| +--:(ssh) {ssh-listen}? | +--:(ssh) {ssh}?
| | +--rw ssh | | +--rw ssh
| | +--rw address? inet:ip-address | | +--rw address? inet:ip-address
| | +--rw port? inet:port-number | | +--rw port? inet:port-number
| | +--rw host-keys | | +--rw host-keys
| | +--rw host-key* string | | +--rw host-key* string
| +--:(tls) {tls-listen}? | +--:(tls) {tls}?
| +--rw tls | +--rw tls
| +--rw address? inet:ip-address | +--rw address? inet:ip-address
| +--rw port? inet:port-number | +--rw port? inet:port-number
| +--rw certificates | +--rw certificates
| +--rw certificate* string | +--rw certificate* string
+--rw keep-alives +--rw keep-alives
+--rw interval-secs? uint8 +--rw interval-secs? uint8
+--rw count-max? uint8 +--rw count-max? uint8
The above subtree illustrates how this YANG module enables The above subtree illustrates how the ietf-netconf-server YANG module
configuration for listening for remote connections, as described in enables configuration for listening for remote connections, as
[RFC6242] and [rfc5539bis]. Feature statements are used to limit described in [RFC6242] and [draft-ietf-netconf-call-home]. Feature
both if listening is supported at all as well as for which statements are used to limit both if listening is supported at all as
transports. If listening for connections is supported, then the well as for which transports. If listening for connections is
model enables configuring a list of listening endpoints, each supported, then the model enables configuring a list of listening
configured with a user-specified name (the key field), the transport endpoints, each configured with a user-specified name (the key
to use (i.e. SSH, TLS), and the IP address and port to listen on. field), the transport to use (i.e. SSH, TLS), and the IP address and
The port field is optional, defaulting to the transport-specific port port to listen on. The port field is optional, defaulting to the
when not configured. transport-specific port when not configured. Please see the YANG
module (Section 3.2) for a complete description of these
configuration knobs.
3.1.3. The "call-home" subtree 3.1.3. The "call-home" subtree
module: ietf-netconf-server module: ietf-netconf-server
+--rw netconf-server +--rw netconf-server
+--rw call-home {"(ssh-call-home or tls-call-home)"}? // YANG 1.1 syntax +--rw call-home {call-home}?
+--rw application* [name] +--rw application* [name]
+--rw name string +--rw name string
+--rw (transport) +--rw (transport)
| +--:(ssh) {ssh-call-home}? | +--:(ssh) {ssh}?
| | +--rw ssh | | +--rw ssh
| | +--rw endpoints | | +--rw endpoints
| | | +--rw endpoint* [name] | | | +--rw endpoint* [name]
| | | +--rw name string | | | +--rw name string
| | | +--rw address inet:host | | | +--rw address inet:host
| | | +--rw port? inet:port-number | | | +--rw port? inet:port-number
| | +--rw host-keys | | +--rw host-keys
| | +--rw host-key* string | | +--rw host-key* string
| +--:(tls) {tls-call-home}? | +--:(tls) {tls}?
| +--rw tls | +--rw tls
| +--rw endpoints | +--rw endpoints
| | +--rw endpoint* [name] | | +--rw endpoint* [name]
| | +--rw name string | | +--rw name string
| | +--rw address inet:host | | +--rw address inet:host
| | +--rw port? inet:port-number | | +--rw port? inet:port-number
| +--rw certificates | +--rw certificates
| +--rw certificate* string | +--rw certificate* string
+--rw connection-type +--rw connection-type
| +--rw (connection-type)? | +--rw (connection-type)?
| +--:(persistent-connection) | +--:(persistent-connection)
| | +--rw persistent | | +--rw persistent
| | +--rw keep-alives | | +--rw keep-alives
| | +--rw interval-secs? uint8 | | +--rw interval-secs? uint8
| | +--rw count-max? uint8 | | +--rw count-max? uint8
| +--:(periodic-connection) | +--:(periodic-connection)
| +--rw periodic | +--rw periodic
| +--rw timeout-mins? uint8 | +--rw timeout-mins? uint8
| +--rw linger-secs? uint8 | +--rw linger-secs? uint8
+--rw reconnect-strategy +--rw reconnect-strategy
+--rw start-with? enumeration +--rw start-with? enumeration
+--rw interval-secs? uint8 +--rw interval-secs? uint8
+--rw count-max? uint8 +--rw count-max? uint8
The above subtree illustrates how this YANG module enables The above subtree illustrates how the ietf-netconf-server YANG module
configuration for call home, as described in enables configuration for call home, as described in
[draft-ietf-netconf-call-home]. Feature statements are used to limit [draft-ietf-netconf-call-home]. Feature statements are used to limit
both if call-home is supported at all as well as for which both if call-home is supported at all as well as for which
transports, if it is. If call-home is supported, then the model transports, if it is. If call-home is supported, then the model
supports configuring a list of applications to connect to. Each supports configuring a list of applications to connect to. Each
application is configured with a user-specified name (the key field), application is configured with a user-specified name (the key field),
the transport to be used (i.e. SSH, TLS), and a list of remote the transport to be used (i.e. SSH, TLS), and a list of remote
endpoints, each having a name, an IP address, and an optional port. endpoints, each having a name, an IP address, and an optional port.
Additionally, the configuration for each remote application indicates Additionally, the configuration for each remote application indicates
the connection-type (persistent vs. periodic) and associated the connection-type (persistent vs. periodic) and associated
parameters, as well as the reconnection strategy to use. parameters, as well as the reconnection strategy to use. Please see
the YANG module (Section 3.2) for a complete description of these
configuration knobs.
3.1.4. The "ssh" subtree 3.1.4. The "ssh" subtree
module: ietf-netconf-server module: ietf-netconf-server
+--rw netconf-server +--rw netconf-server
+--rw ssh +--rw ssh {ssh}?
+--ro host-keys +--rw x509 {rfc6187}?
+--ro host-key* [name] +--rw trusted-ca-certs
+--ro name string | +--rw trusted-ca-cert* binary
+--ro format-identifier string +--rw trusted-client-certs
+--ro data binary +--rw trusted-client-cert* binary
+--ro fingerprint string
The above subtree illustrates how this YANG module provides SSH state The above subtree illustrates how the ietf-netconf-server YANG module
independent of if the NETCONF server if listening or calling home. enables some SSH configuration independent of if the NETCONF server
This data-model provides a read-only listing of currently configured is listening or calling home. Specifically, when RFC 6187 is
TLC certificates. supported, this data model provides an ability to configure how
client-certificates are authenticated. Please see the YANG module
(Section 3.2) for a complete description of these configuration
knobs.
3.1.5. The "tls" subtree 3.1.5. The "tls" subtree
module: ietf-netconf-server module: ietf-netconf-server
+--rw netconf-server +--rw netconf-server
+--rw tls +--rw tls {tls}?
+--ro certificates
| +--ro certificate* [name]
| +--ro name string
| +--ro data binary
+--rw client-auth +--rw client-auth
+--rw trusted-ca-certs +--rw trusted-ca-certs
| +--rw trusted-ca-cert* binary | +--rw trusted-ca-cert* binary
+--rw trusted-client-certs +--rw trusted-client-certs
| +--rw trusted-client-cert* binary | +--rw trusted-client-cert* binary
+--rw cert-maps +--rw cert-maps
+--rw cert-to-name* [id] +--rw cert-to-name* [id]
+--rw id uint32 +--rw id uint32
+--rw fingerprint x509c2n:tls-fingerprint +--rw fingerprint x509c2n:tls-fingerprint
+--rw map-type identityref +--rw map-type identityref
+--rw name string +--rw name string
The above subtree illustrates how this YANG module provides TLS state The above subtree illustrates how the ietf-netconf-server YANG module
and enables TLS configuration independent of if the NETCONF server if enables TLS configuration independent of if the NETCONF server is
listening or calling home. This data-model provides 1) a read-only listening or calling home. Specifically, this data-model provides 1)
listing of currently configured TLC certificates and 2) an ability to an ability to configure how client-certificates are authenticated and
configure how client-certificates are authenicated and how 2) how authenticated client-certificates are mapped to NETCONF user
authenticated client-certificates are mapped to NETCONF user names. names. Please see the YANG module (Section 3.2) for a complete
description of these configuration knobs.
3.2. YANG Module 3.2. YANG Module
This YANG module imports YANG types from [RFC6991], and This YANG module imports YANG types from [RFC6991], and
[draft-ietf-netmod-snmp-cfg]. [draft-ietf-netmod-snmp-cfg].
RFC Ed.: update the date below with the date of RFC publication <CODE BEGINS> file "ietf-netconf-server@2014-12-11.yang"
and remove this note.
<CODE BEGINS> file "ietf-netconf-server@2014-10-26.yang" module ietf-netconf-server {
module ietf-netconf-server { namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server";
prefix "ncserver";
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server"; import ietf-inet-types { // RFC 6991
prefix "ncserver"; prefix inet;
revision-date 2013-07-15;
}
import ietf-x509-cert-to-name { // RFC ZZZZ
prefix x509c2n;
revision-date 2014-05-06;
}
import ietf-inet-types { organization
prefix inet; // RFC 6991 "IETF NETCONF (Network Configuration) Working Group";
}
import ietf-x509-cert-to-name {
prefix x509c2n; // draft-ietf-netmod-snmp-cfg
}
organization contact
"IETF NETCONF (Network Configuration) Working Group"; "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
contact WG Chair: Mehmet Ersue
"WG Web: <http://tools.ietf.org/wg/netconf/> <mailto:mehmet.ersue@nsn.com>
WG List: <mailto:netconf@ietf.org>
WG Chair: Mehmet Ersue WG Chair: Mahesh Jethanandani
<mailto:mehmet.ersue@nsn.com> <mailto:mjethanandani@gmail.com>
WG Chair: Bert Wijnen Editor: Kent Watsen
<mailto:bertietf@bwijnen.net> <mailto:kwatsen@juniper.net>";
Editor: Kent Watsen description
<mailto:kwatsen@juniper.net>"; "This module contains a collection of YANG definitions for
configuring NETCONF servers.
description Copyright (c) 2014 IETF Trust and the persons identified as
"This module contains a collection of YANG definitions for authors of the code. All rights reserved.
configuring NETCONF servers.
Copyright (c) 2014 IETF Trust and the persons identified as Redistribution and use in source and binary forms, with or
authors of the code. All rights reserved. without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD
License set forth in Section 4.c of the IETF Trust's
Legal Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info).
Redistribution and use in source and binary forms, with or This version of this YANG module is part of RFC VVVV; see
without modification, is permitted pursuant to, and subject the RFC itself for full legal notices.";
to the license terms contained in, the Simplified BSD
License set forth in Section 4.c of the IETF Trust's
Legal Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see revision "2014-12-11" {
the RFC itself for full legal notices."; description
// RFC Ed.: replace XXXX with actual RFC number and "Initial version";
// remove this note reference
"RFC VVVV: NETCONF Server and RESTCONF Server Configuration Models";
}
// RFC Ed.: please update the date to the date of publication // Features
revision "2014-10-26" { // YYYY-MM-DD feature session-options {
description description
"Initial version"; "The session-options feature indicates that the NETCONF server
reference supports the session-options container.";
"RFC XXXX: NETCONF Server Configuration Model"; }
}
// Features feature ssh {
description
"The ssh feature indicates that the server supports the
SSH transport protocol.";
reference
"RFC 6242: Using the NETCONF Protocol over Secure Shell (SSH)";
}
feature ssh-listen { feature tls {
description description
"The ssh-listen feature indicates that the NETCONF server can "The tls feature indicates that the server supports the
open a port to listen for incoming client connections."; TLS transport protocol.";
} reference
"RFC 5539: NETCONF over Transport Layer Security (TLS)";
}
feature ssh-call-home { feature listen {
description description
"The ssh-call-home feature indicates that the NETCONF server can "The listen feature indicates that the server supports
connect to a client."; opening a port to listen for incoming client connections.";
reference reference
"RFC XXXX: Reverse Secure Shell (Reverse SSH)"; "RFC 6242: Using the NETCONF Protocol over Secure Shell (SSH)
} RFC 5539: NETCONF over Transport Layer Security (TLS)";
}
feature tls-listen { feature call-home {
description description
"The tls-listen feature indicates that the NETCONF server can "The call-home feature indicates that the server supports
open a port to listen for incoming client connections."; connecting to the client";
} reference
"RFC YYYY: NETCONF Call Home and RESTCONF Call Home";
}
feature tls-call-home { feature rfc6187 {
description description
"The tls-call-home feature indicates that the NETCONF server can "The rfc6187 feature indicates that the NETCONF server supports
connect to a client."; RFC 6187";
reference
"RFC 6187: X.509v3 Certificates for Secure Shell Authentication";
}
} // top-level container (groupings below)
container netconf-server {
description
"Top-level container for NETCONF server configuration.";
// top-level container (groupings below) uses session-options-container;
container netconf-server { uses listen-container;
description uses call-home-container;
"Top-level container for NETCONF server configuration."; uses ssh-container;
uses tls-container;
uses session-options-container; }
uses listen-container;
uses call-home-container;
uses ssh-container;
uses tls-container;
} grouping session-options-container {
description
"";
container session-options {
description
"NETCONF session options, independent of transport or
connection strategy.";
if-feature session-options;
leaf hello-timeout {
type uint32 {
range "0 | 10 .. 3600";
}
units "seconds";
default '600';
description
"Specifies the number of seconds that a session may exist
before the hello PDU is received. A session will be
dropped if no hello PDU is received before this number
of seconds elapses.
grouping session-options-container { If this parameter is set to zero, then the server will
description wait forever for a hello message, and not drop any
""; sessions stuck in 'hello-wait' state.
container session-options {
description
"NETCONF session options, independent of transport
or connection strategy.";
leaf hello-timeout {
type uint32 {
range "0 | 10 .. 3600";
}
units "seconds";
default '600';
description
"Specifies the number of seconds that a session
may exist before the hello PDU is received.
A session will be dropped if no hello PDU
is received before this number of seconds elapses.
If this parameter is set to zero, then the server Setting this parameter to zero may permit denial of
will wait forever for a hello message, and not service attacks, since only a limited number of
drop any sessions stuck in 'hello-wait' state. concurrent sessions may be supported by the server.";
}
leaf idle-timeout {
type uint32 {
range "0 | 10 .. 360000";
}
units "seconds";
default '3600';
description
"Specifies the number of seconds that a NETCONF session may
remain idle without issuing any RPC requests. A session
will be dropped if it is idle for an interval longer than
this number of seconds. If this parameter is set to zero,
then the server will never drop a session because it is
idle. Sessions that have a notification subscription
active are never dropped.
Setting this parameter to zero may permit This mechanism is independent of keep-alives, as it regards
denial of service attacks, since only a limited activity occurring at the NETCONF protocol layer, whereas
number of concurrent sessions are supported the keep-alive mechanism regards transport-level activity.";
by the server."; }
} }
leaf idle-timeout { }
type uint32 {
range "0 | 10 .. 360000";
}
units "seconds";
default '3600';
description
"Specifies the number of seconds that a session
may remain idle without issuing any RPC requests.
A session will be dropped if it is idle for an
interval longer than this number of seconds.
Sessions that have a notification subscription grouping listen-container {
active are never dropped. description
"";
container listen {
description
"Configures listen behavior";
if-feature listen;
leaf max-sessions {
type uint16 {
range "0 .. 1024";
}
default '0';
description
"Specifies the maximum number of concurrent sessions
that can be active at one time. The value 0 indicates
that no artificial session limit should be used.";
}
list endpoint {
key name;
description
"List of endpoints to listen for connections on.";
leaf name {
type string;
description
"An arbitrary name for the listen endpoint.";
}
choice transport {
mandatory true;
description
"Selects between SSH and TLS transports.";
case ssh {
if-feature ssh;
container ssh {
description
"SSH-specific listening configuration for inbound
connections.";
uses address-and-port-grouping {
refine port {
default 830;
}
}
uses host-keys-container;
}
}
case tls {
if-feature tls;
container tls {
description
"TLS-specific listening configuration for inbound
connections.";
uses address-and-port-grouping {
refine port {
default 6513;
}
}
uses certificates-container;
}
}
}
uses keep-alives-container {
refine keep-alives/interval-secs {
default 0; // disabled by default for listen connections
}
}
}
}
}
If this parameter is set to zero, then the server grouping call-home-container {
will never drop a session because it is idle."; description
} "";
} container call-home {
} if-feature call-home;
description
"Configures call-home behavior";
list application {
key name;
description
"List of NETCONF clients the NETCONF server is to initiate
call-home connections to.";
leaf name {
type string;
description
"An arbitrary name for the remote NETCONF client.";
}
choice transport {
mandatory true;
description
"Selects between available transports.";
case ssh {
if-feature ssh;
container ssh {
description
"Specifies SSH-specific call-home transport
configuration.";
uses endpoints-container {
refine endpoints/endpoint/port {
default 7777;
}
}
uses host-keys-container;
}
}
case tls {
if-feature tls;
container tls {
description
"Specifies TLS-specific call-home transport
configuration.";
uses endpoints-container {
refine endpoints/endpoint/port {
default 8888;
}
}
uses certificates-container;
}
}
}
container connection-type {
description
"Indicates the kind of connection to be maintained.";
choice connection-type {
default persistent-connection;
description
"Selects between persistent and periodic connections.";
case persistent-connection {
container persistent {
description
"Maintain a persistent connection to the NETCONF
client. If the connection goes down, immediately
start trying to reconnect to it, using the
reconnection strategy.
grouping listen-container { This connection type minimizes any NETCONF client
description to NETCONF server data-transfer delay, albeit at
""; the expense of holding resources longer.";
container listen { uses keep-alives-container {
description refine keep-alives/interval-secs {
"Configures listen behavior"; default 15; // 15 seconds for call-home sessions
//if-feature "(ssh-listen or tls-listen)"; }
leaf max-sessions { }
type uint16 { }
range "0 .. 1024"; }
} case periodic-connection {
default '0'; container periodic {
description description
"Specifies the maximum number of concurrent sessions "Periodically connect to NETCONF client, using the
that can be active at one time. The value 0 indicates reconnection strategy, so the NETCONF client can
that no artificial session limit should be used."; deliver pending messages to the NETCONF server.
}
list endpoint {
key name;
description
"List of endpoints to listen for connections on.";
leaf name {
type string;
description
"An arbitrary name for the listen endpoint.";
}
choice transport {
mandatory true;
description
"Selects between SSH and TLS transports.";
case ssh {
if-feature ssh-listen;
container ssh {
description
"SSH-specific listening configuration for inbound
connections.";
uses address-and-port-grouping {
refine port {
default 830;
}
}
uses host-keys-container;
}
}
case tls {
if-feature tls-listen;
container tls {
description
"TLS-specific listening configuration for inbound
connections.";
uses address-and-port-grouping {
refine port {
default 6513;
}
}
uses certificates-container;
}
}
}
uses keep-alives-container {
refine keep-alives/interval-secs {
default 0; // disabled by default for listen connections
}
}
}
}
}
grouping call-home-container { For messages the NETCONF server wants to send to
description to the NETCONF client, the NETCONF server should
""; proactively connect to the NETCONF client, if
container call-home { not already, to send the messages immediately.";
//if-feature "(ssh-call-home or tls-call-home)"; leaf timeout-mins {
description type uint8;
"Configures call-home behavior"; units minutes;
list application { default 5;
key name; description
description "The maximum amount of unconnected time the NETCONF
"List of applications to call-home to."; server will wait until establishing a connection to
leaf name { the NETCONF client again. The NETCONF server MAY
type string; establish a connection before this time if it has
description data it needs to send to the NETCONF client. Note:
"An arbitrary name for the remote application."; this value differs from the reconnection strategy's
} interval-secs value.";
choice transport { }
mandatory true; leaf linger-secs {
description type uint8;
"Selects between SSH and TLS transports."; units seconds;
case ssh { default 30;
if-feature ssh-call-home; description
container ssh { "The amount of time the NETCONF server should wait
description after last receiving data from or sending data to
"Specifies SSH-specific call-home transport the NETCONF client's endpoint before closing its
configuration."; connection to it. This is an optimization to
uses endpoints-container { prevent unnecessary connections.";
refine endpoints/endpoint/port { }
default 8888; // pending IANA assignment }
} }
} }
uses host-keys-container; }
} container reconnect-strategy {
} description
case tls { "The reconnection strategy guides how a NETCONF server
if-feature tls-call-home; reconnects to an NETCONF client, after losing a connection
container tls { to it, even if due to a reboot. The NETCONF server starts
description with the specified endpoint and tries to connect to it
"Specifies TLS-specific call-home transport count-max times, waiting interval-secs between each
configuration."; connection attempt, before trying the next endpoint in
uses endpoints-container { the list (round robin).";
refine endpoints/endpoint/port { leaf start-with {
default 9999; // pending IANA assignment type enumeration {
} enum first-listed {
} description
uses certificates-container; "Indicates that reconnections should start with
} the first endpoint listed.";
} }
} enum last-connected {
container connection-type { description
description "Indicates that reconnections should start with
"Indicates the NETCONF client's preference for how the the endpoint last connected to. NETCONF servers
device's connection is maintained."; SHOULD support this flag across reboots.";
choice connection-type {
default persistent-connection;
description
"Selects between persistent and periodic connections.";
case persistent-connection { }
container persistent { }
description default first-listed;
"Maintain a persistent connection to the description
NETCONF client. If the connection goes down, "Specifies which of the NETCONF client's endpoints the
immediately start trying to reconnect to it, NETCONF server should start with when trying to connect
using the reconnection strategy. to the NETCONF client. If no previous connection has
ever been established, last-connected defaults to
the first endpoint listed.";
}
leaf interval-secs {
type uint8;
units seconds;
default 5;
description
"Specifies the time delay between connection attempts
to the same endpoint. Note: this value differs from
the periodic-connection's timeout-mins value.";
}
leaf count-max {
type uint8;
default 3;
description
"Specifies the number times the NETCONF server tries to
connect to a specific endpoint before moving on to the
next endpoint in the list (round robin).";
}
}
}
}
}
This connection type minimizes any NETCONF grouping ssh-container {
client to NETCONF server data-transfer delay, description
albeit at the expense of holding resources "";
longer."; container ssh {
uses keep-alives-container { description
refine keep-alives/interval-secs { "Configures SSH properties not specific to the listen
default 15; // 15 seconds for call-home sessions or call-home use-cases";
} if-feature ssh;
} container x509 {
} if-feature rfc6187;
} uses trusted-certs-grouping;
case periodic-connection { }
container periodic { }
description }
"Periodically connect to NETCONF client, using the grouping tls-container {
reconnection strategy, so the NETCONF client can description
deliver pending messages to the NETCONF server. "";
container tls {
description
"Configures TLS properties not specific to the listen
or call-home use-cases";
if-feature tls;
container client-auth {
description
"Container for TLS client authentication configuration.";
uses trusted-certs-grouping;
container cert-maps {
uses x509c2n:cert-to-name;
description
"The cert-maps container is used by a NETCONF server to
map the NETCONF client's presented X.509 certificate to a
NETCONF username. If no matching and valid cert-to-name
list entry can be found, then the NETCONF server MUST
close the connection, and MUST NOT accept NETCONF
messages over it.";
}
}
}
}
For messages the NETCONF server wants to send to grouping trusted-certs-grouping {
to the NETCONF client, the NETCONF server should description
proactively connect to the NETCONF client, if "";
not already, to send the messages immediately."; container trusted-ca-certs {
leaf timeout-mins { description
type uint8; "A list of Certificate Authority (CA) certificates that
units minutes; a NETCONF server can use to authenticate NETCONF client
default 5; certificates. A client's certificate is authenticated
description if there is a chain of trust to a configured trusted CA
"The maximum amount of unconnected time the certificate. The client certificate MAY be accompanied
device will wait until establishing a with additional certificates forming a chain of trust.
connection to the NETCONF client again. The The client's certificate is authenticated if there is
device MAY establish a connection before this path-validation from any of the certificates it presents
time if it has data it needs to send to the to a configured trust anchor.";
NETCONF client. Note: this value differs from leaf-list trusted-ca-cert {
the reconnection strategy's interval-secs type binary;
value."; ordered-by system;
} description
leaf linger-secs { "The binary certificate structure as specified by RFC
type uint8; 5246, Section 7.4.6, i.e.,: opaque ASN.1Cert<1..2^24>;
units seconds; ";
default 30; reference
description "RFC 5246: The Transport Layer Security (TLS)
"The amount of time the device should wait after Protocol Version 1.2";
last receiving data from or sending data to the }
NETCONF client's endpoint before closing its }
connection to it. This is an optimization to container trusted-client-certs {
prevent unnecessary connections."; description
} "A list of client certificates that a NETCONF server can
} use to authenticate a NETCONF client's certificate. A
} client's certificate is authenticated if it is an exact
} match to a configured trusted client certificates.";
} leaf-list trusted-client-cert {
container reconnect-strategy { type binary;
description ordered-by system;
"The reconnection strategy guides how a device reconnects description
to an application, after losing a connection to it, "The binary certificate structure, as
even if due to a reboot. The device starts with the specified by RFC 5246, Section 7.4.6, i.e.,:
specified endpoint, tries to connect to it count-max
times, waiting interval-secs between each connection
attempt, before trying the next endpoint in the list
(round robin).";
leaf start-with {
type enumeration {
enum first-listed {
description
"Indicates that reconnections should start with
the first endpoint listed.";
}
enum last-connected {
description
"Indicates that reconnections should start with
the endpoint last connected to. NETCONF servers
SHOULD support this flag across reboots.";
}
}
default first-listed;
description
"Specifies which of the application's endpoints the
device should start with when trying to connect to
the application. If no previous connection has
ever been established, last-connected defaults to
the first endpoint listed.";
}
leaf interval-secs {
type uint8;
units seconds;
default 5;
description
"Specifies the time delay between connection attempts
to the same endpoint. Note: this value differs from
the periodic-connection's timeout-mins value.";
}
leaf count-max {
type uint8;
default 3;
description
"Specifies the number times the device tries to
connect to a specific endpoint before moving on to
the next endpoint in the list (round robin).";
}
}
}
}
}
grouping ssh-container { opaque ASN.1Cert<1..2^24>;
description
"";
container ssh {
description
"Configures SSH properties not specific to the listen
or call-home use-cases";
//if-feature "(ssh-listen or ssh-call-home)";
container host-keys {
config false;
description
"Parent container for a list of host keys";
list host-key {
key name;
description
"A read-only list of host-keys supported by server";
leaf name {
type string;
description
"Common name for the host-key";
}
leaf format-identifier {
type string;
mandatory true;
description
"ssh-dss, ssh-rsa, x509v3-rsa2048-sha256, etc.";
reference
"RFC 4253: SSH Transport Layer Protocol, section 6.6
RFC 6187: X.509v3 Certificates for SSH, section 3";
}
leaf data {
type binary;
mandatory true;
description
"Key-specific binary encoding.";
reference
"RFC 4253: SSH Transport Layer Protocol, section 6.6";
}
leaf fingerprint {
type string;
mandatory true;
description
"c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87";
reference
"RFC 4716: The Secure Shell (SSH) Public Key File
Format, section 4";
}
}
}
}
}
grouping tls-container { ";
description reference
""; "RFC 5246: The Transport Layer Security (TLS)
container tls { Protocol Version 1.2";
description }
"Configures TLS properties not specific to the listen }
or call-home use-cases"; }
//if-feature "(tls-listen or tls-call-home)";
container certificates {
config false;
description
"Parent container for a list of certificates";
list certificate {
key name;
description
"A list of certificates";
leaf name {
type string;
description
"the certificate's common name";
}
leaf data {
type binary;
mandatory true;
description
"The binary certificate structure, as specified
by RFC 5246, Section 7.4.2, i.e.,: opaque
ASN.1Cert<1..2^24-1>;";
}
}
}
container client-auth {
description
"Container for TLS client authentication configuration.";
container trusted-ca-certs {
description
"A list of Certificate Authority (CA) certificates that
a NETCONF server can use to authenticate NETCONF client
certificates. A client's certificate is authenticated
if there is a chain of trust to a configured trusted CA
certificate. Note, in the TLS protocol, the client
certificate MAY be accompanied with additional
certificates forming a chain of trust. The client's
certificate is authenticated if there is path-validation
from any of the certificates it presents to a configured
trust anchor.";
leaf-list trusted-ca-cert {
type binary;
ordered-by system;
description
"The binary certificate structure as specified by RFC
5246, Section 7.4.6, i.e.,: opaque ASN.1Cert<1..2^24>;
";
reference
"RFC 5246: The Transport Layer Security (TLS)
Protocol Version 1.2";
}
}
container trusted-client-certs {
description
"A list of client certificates that a NETCONF server can
use to authenticate a NETCONF client's certificate. A
client's certificate is authenticated if it is an exact
match to a configured trusted client certificates.";
leaf-list trusted-client-cert {
type binary;
ordered-by system;
description
"The binary certificate structure, as
specified by RFC 5246, Section 7.4.6, i.e.,:
opaque ASN.1Cert<1..2^24>; grouping host-keys-container {
description
"";
container host-keys {
description
"Parent container for the list of host-keys.";
leaf-list host-key {
type string;
min-elements 1;
ordered-by user;
description
"A user-ordered list of host-keys the SSH server
considers when composing the list of server host
key algorithms it will send to the client in its
SSH_MSG_KEXINIT message. The value of the string
is the unique identifier for a host-key configured
on the system. How valid values are discovered is
outside the scope of this module, but they are
envisioned to be the keys for a list of host-keys
provided by another YANG module";
reference
"RFC 4253: The SSH Transport Layer Protocol, Section 7";
}
}
}
"; grouping certificates-container {
description
"";
container certificates {
description
"Parent container for the list of certificates.";
leaf-list certificate {
type string;
min-elements 1;
description
"An unordered list of certificates the TLS server can pick
from when sending its Server Certificate message. The value
of the string is the unique identifier for a certificate
configured on the system. How valid values are discovered
is outside the scope of this module, but they are envisioned
to be the keys for a list of certificates provided
by another YANG module";
reference
"RFC 5246: The TLS Protocol, Section 7.4.2";
}
}
}
reference grouping address-and-port-grouping {
"RFC 5246: The Transport Layer Security (TLS) description
Protocol Version 1.2"; "a common grouping";
} leaf address {
} type inet:ip-address;
container cert-maps { description
uses x509c2n:cert-to-name; "The IP address of the interface to listen on.";
description }
"The cert-maps container is used by a NETCONF server to leaf port {
map the NETCONF client's presented X.509 certificate to type inet:port-number;
a NETCONF username. description
"The local port number on this interface the NETCONF server
listens on.";
}
}
If no matching and valid cert-to-name list entry can be grouping endpoints-container {
found, then the NETCONF server MUST close the connection, description
and MUST NOT accept NETCONF messages over it."; "Grouping for transport-specific configuration for
} call-home connections.";
} container endpoints {
} description
} "Container for the list of endpoints.";
list endpoint {
key name;
min-elements 1;
ordered-by user;
description
"User-ordered list of endpoints for this NETCONF client.
Defining more than one enables high-availability.";
leaf name {
type string;
description
"An arbitrary name for the endpoint to connect to.";
}
leaf address {
type inet:host;
mandatory true;
description
"The hostname or IP address or hostname of the endpoint.
If a hostname is provided and DNS resolves to more than
one IP address, the NETCONF server SHOULD try all of
the ones it can based on how its networking stack is
configured (e.g. v4, v6, dual-stack).";
}
leaf port {
type inet:port-number;
description
"The IP port for this endpoint. The NETCONF server will
use the IANA-assigned well-known port if not specified.";
}
}
}
}
grouping host-keys-container { grouping keep-alives-container {
description description
""; "";
container host-keys { container keep-alives {
description description
"Parent container for the list of host-keys."; "Configures the keep-alive policy, to proactively test the
leaf-list host-key { aliveness of the NETCONF client, in order to know when a
type string; new call home connection should be established.";
min-elements 1; reference
ordered-by user; "RFC VVVV: NETCONF Server and RESTCONF Server Configuration
description Models, Section 4";
"User-ordered list of host-keys the SSH server leaf interval-secs {
considers when composing the list of server type uint8;
host key algorithms it will send to the client. units seconds;
The value of the string is the name of a description
host-key configured on the system, as returned "Sets a timeout interval in seconds after which if no data
by /netconf-server/ssh/host-keys/host-key/name."; has been received from the NETCONF client, a message will
reference be sent to request a response from the NETCONF client. A
"RFC 4253: The SSH Transport Layer Protocol, Section 7"; value of '0' indicates that no keep-alive messages should
} be sent.";
} }
} leaf count-max {
type uint8;
default 3;
description
"Sets the number of keep-alive messages that may be sent
without receiving any data from the NETCONF client before
assuming the NETCONF client is no longer alive. If this
threshold is reached, the transport-level connection will
be disconnected, which will trigger the reconnection
strategy). The interval timer is reset after each
transmission, thus an unresponsive NETCONF client will
be dropped after ~count-max * interval-secs seconds.";
}
}
}
}
grouping certificates-container { <CODE ENDS>
description
"";
container certificates {
description
"Parent container for the list of certificates.";
leaf-list certificate {
type string;
min-elements 1;
description
"Unordered list of certificates the TLS server can
pick from when sending its Server Certificate
message. The value of the string is the name of a
certificate configured on the system, as returned by
/netconf-server/tls/certificates/certificate/name";
reference
"RFC 5246: The TLS Protocol, Section 7.4.2";
}
}
}
grouping address-and-port-grouping { 4. The RESTCONF Server Configuration Model
description
"a common grouping";
leaf address {
type inet:ip-address;
description
"The IP address of the interface to listen on.";
}
leaf port {
type inet:port-number;
description
"The local port number on this interface the
NETCONF server listens on.";
}
}
grouping endpoints-container { 4.1. Overview
description
"Grouping for transport-specific configuration for
call-home connections.";
container endpoints {
description
"Container for the list of endpoints.";
list endpoint {
key name;
min-elements 1;
ordered-by user;
description
"User-ordered list of endpoints for this application.
Defining more than one enables high-availability.";
leaf name { 4.1.1. The "listen" subtree
type string; module: ietf-restconf-server
description +--rw restconf-server
"An arbitrary name for the endpoint to connect to."; +--rw listen {listen}?
} +--rw max-sessions? uint16
leaf address { +--rw endpoint* [name]
type inet:host; +--rw name string
mandatory true; +--rw (transport)
description | +--:(tls)
"The hostname or IP address or hostname of the | +--rw tls
endpoint. If a hostname is provided and DNS | +--rw address? inet:ip-address
resolves to more than one IP address, the device | +--rw port? inet:port-number
SHOULD try all of the ones it can based on how | +--rw certificates
its networking stack is configured (e.g. v4, v6, | +--rw certificate* string
dual-stack)."; +--rw keep-alives
} +--rw interval-secs? uint8
leaf port { +--rw count-max? uint8
type inet:port-number;
description
"The IP port for this endpoint. The device will use
the IANA-assigned well-known port if not specified.";
}
}
}
}
grouping keep-alives-container { The above subtree illustrates how the ietf-restconf-server YANG
description module enables configuration for listening for remote connections, as
""; described in [draft-ietf-netconf-restconf] and
container keep-alives { [draft-ietf-netconf-call-home]. Feature statements are used to limit
description both if listening is supported at all as well as for which
"Configures the keep-alive policy, to proactively transports. If listening for connections is supported, then the
test the aliveness of the NETCONF client, in model enables configuring a list of listening endpoints, each
order to know when a new call home connection configured with a user-specified name (the key field), the transport
should be established. Keepalive implementation to use (i.e. SSH, TLS), and the IP address and port to listen on.
is described in RFC XXXX, section 4."; The port field is optional, defaulting to the transport-specific port
reference when not configured. Please see the YANG module (Section 4.2) for a
"RFC XXXX: NETCONF Server Configuration Model complete description of these configuration knobs.
Section 4";
leaf interval-secs {
type uint8;
units seconds;
description
"Sets a timeout interval in seconds after which
if no data has been received from the NETCONF
client, a message will be sent to request a
response from the NETCONF client. A value of
'0' indicates that no keep-alive messages
should be sent.";
}
leaf count-max {
type uint8;
default 3;
description
"Sets the number of keep-alive messages that
may be sent without receiving any data from
the NETCONF client before assuming the NETCONF
client is no longer alive. If this threshold
is reached, the transport-level connection
will be disconnected, which will trigger the
reconnection strategy). The interval timer is
reset after each transmission, thus an
unresponsive NETCONF client will be dropped
after ~count-max * interval-secs seconds.";
}
}
}
}
<CODE ENDS> 4.1.2. The "call-home" subtree
module: ietf-restconf-server
+--rw restconf-server
+--rw call-home {call-home}?
+--rw application* [name]
+--rw name string
+--rw (transport)
| +--:(tls) {tls}?
| +--rw tls
| +--rw endpoints
| | +--rw endpoint* [name]
| | +--rw name string
| | +--rw address inet:host
| | +--rw port? inet:port-number
| +--rw certificates
| +--rw certificate* string
+--rw connection-type
| +--rw (connection-type)?
| +--:(persistent-connection)
| | +--rw persistent
| | +--rw keep-alives
| | +--rw interval-secs? uint8
| | +--rw count-max? uint8
| +--:(periodic-connection)
| +--rw periodic
| +--rw timeout-mins? uint8
| +--rw linger-secs? uint8
+--rw reconnect-strategy
+--rw start-with? enumeration
+--rw interval-secs? uint8
+--rw count-max? uint8
4. Implementation strategy for keep-alives The above subtree illustrates how the ietf-restconf-server YANG
module enables configuration for call home, as described in
[draft-ietf-netconf-call-home]. Feature statements are used to limit
both if call-home is supported at all as well as for which
transports, if it is. If call-home is supported, then the model
supports configuring a list of applications to connect to. Each
application is configured with a user-specified name (the key field),
the transport to be used (i.e. SSH, TLS), and a list of remote
endpoints, each having a name, an IP address, and an optional port.
Additionally, the configuration for each remote application indicates
the connection-type (persistent vs. periodic) and associated
parameters, as well as the reconnection strategy to use. Please see
the YANG module (Section 4.2) for a complete description of these
configuration knobs.
4.2. YANG Module
This YANG module imports YANG types from [RFC6991].
<CODE BEGINS> file "ietf-restconf-server@2014-12-11.yang"
module ietf-restconf-server {
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server";
prefix "rcserver";
import ietf-inet-types { // RFC 6991
prefix inet;
revision-date 2013-07-15;
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
WG Chair: Mahesh Jethanandani
<mailto:mjethanandani@gmail.com>
Editor: Kent Watsen
<mailto:kwatsen@juniper.net>";
description
"This module contains a collection of YANG definitions for
configuring RESTCONF servers.
Copyright (c) 2014 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD
License set forth in Section 4.c of the IETF Trust's
Legal Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC VVVV; see
the RFC itself for full legal notices.";
revision "2014-12-11" {
description
"Initial version";
reference
"RFC VVVV: NETCONF Server and RESTCONF Server Configuration Models";
}
// Features
feature tls {
description
"The tls feature indicates that the server supports RESTCONF
over the TLS transport protocol.";
reference
"RFC XXXX: RESTCONF Protocol";
}
feature listen {
description
"The listen feature indicates that the server supports
opening a port to listen for incoming client connections.";
reference
"RFC XXXX: RESTCONF Protocol";
}
feature call-home {
description
"The call-home feature indicates that the server supports
connecting to the client";
reference
"RFC YYYY: NETCONF Call Home and RESTCONF Call Home";
}
// top-level container (groupings below)
container restconf-server {
description
"Top-level container for RESTCONF server configuration.";
uses listen-container;
uses call-home-container;
}
grouping listen-container {
description
"";
container listen {
description
"Configures listen behavior";
if-feature listen;
leaf max-sessions {
type uint16 {
range "0 .. 1024";
}
default '0';
description
"Specifies the maximum number of concurrent sessions
that can be active at one time. The value 0 indicates
that no artificial session limit should be used.";
}
list endpoint {
key name;
description
"List of endpoints to listen for connections on.";
leaf name {
type string;
description
"An arbitrary name for the listen endpoint.";
}
choice transport {
mandatory true;
description
"Selects between available transports.";
case tls {
container tls {
description
"TLS-specific listening configuration for inbound
connections.";
uses address-and-port-grouping {
refine port {
default 6513;
}
}
uses certificates-container;
}
}
}
uses keep-alives-container {
refine keep-alives/interval-secs {
default 0; // disabled by default for listen connections
}
}
}
}
}
grouping call-home-container {
description
"";
container call-home {
if-feature call-home;
description
"Configures call-home behavior";
list application {
key name;
description
"List of RESTCONF clients the RESTCONF server is to initiate
call-home connections to.";
leaf name {
type string;
description
"An arbitrary name for the remote RESTCONF client.";
}
choice transport {
mandatory true;
description
"Selects between SSH and TLS transports.";
case tls {
if-feature tls;
container tls {
description
"Specifies TLS-specific call-home transport
configuration.";
uses endpoints-container {
refine endpoints/endpoint/port {
default 9999;
}
}
uses certificates-container;
}
}
}
container connection-type {
description
"Indicates the RESTCONF client's preference for how the
RESTCONF server's connection is maintained.";
choice connection-type {
default persistent-connection;
description
"Selects between persistent and periodic connections.";
case persistent-connection {
container persistent {
description
"Maintain a persistent connection to the RESTCONF
client. If the connection goes down, immediately
start trying to reconnect to it, using the
reconnection strategy.
This connection type minimizes any RESTCONF client
to RESTCONF server data-transfer delay, albeit at
the expense of holding resources longer.";
uses keep-alives-container {
refine keep-alives/interval-secs {
default 15; // 15 seconds for call-home sessions
}
}
}
}
case periodic-connection {
container periodic {
description
"Periodically connect to RESTCONF client, using the
reconnection strategy, so the RESTCONF client can
deliver pending messages to the RESTCONF server.
For messages the RESTCONF server wants to send to
to the RESTCONF client, the RESTCONF server should
proactively connect to the RESTCONF client, if
not already, to send the messages immediately.";
leaf timeout-mins {
type uint8;
units minutes;
default 5;
description
"The maximum amount of unconnected time the RESTCONF
server will wait until establishing a connection to
the RESTCONF client again. The RESTCONF server MAY
establish a connection before this time if it has
data it needs to send to the RESTCONF client. Note:
this value differs from the reconnection strategy's
interval-secs value.";
}
leaf linger-secs {
type uint8;
units seconds;
default 30;
description
"The amount of time the RESTCONF server should wait
after last receiving data from or sending data to
the RESTCONF client's endpoint before closing its
connection to it. This is an optimization to
prevent unnecessary connections.";
}
}
}
}
}
container reconnect-strategy {
description
"The reconnection strategy guides how a RESTCONF server
reconnects to an RESTCONF client, after losing a connection
to it, even if due to a reboot. The RESTCONF server starts
with the specified endpoint and tries to connect to it
count-max times, waiting interval-secs between each
connection attempt, before trying the next endpoint in
the list (round robin).";
leaf start-with {
type enumeration {
enum first-listed {
description
"Indicates that reconnections should start with
the first endpoint listed.";
}
enum last-connected {
description
"Indicates that reconnections should start with
the endpoint last connected to. RESTCONF servers
SHOULD support this flag across reboots.";
}
}
default first-listed;
description
"Specifies which of the RESTCONF client's endpoints the
RESTCONF server should start with when trying to connect
to the RESTCONF client. If no previous connection has
ever been established, last-connected defaults to
the first endpoint listed.";
}
leaf interval-secs {
type uint8;
units seconds;
default 5;
description
"Specifies the time delay between connection attempts
to the same endpoint. Note: this value differs from
the periodic-connection's timeout-mins value.";
}
leaf count-max {
type uint8;
default 3;
description
"Specifies the number times the RESTCONF server tries to
connect to a specific endpoint before moving on to the
next endpoint in the list (round robin).";
}
}
}
}
}
grouping certificates-container {
description
"";
container certificates {
description
"Parent container for the list of certificates.";
leaf-list certificate {
type string;
min-elements 1;
description
"An unordered list of certificates the TLS server can pick
from when sending its Server Certificate message. The value
of the string is the unique identifier for a certificate
configured on the system. How valid values are discovered
is outside the scope of this module, but they are envisioned
to be the keys for a list of certificates provided
by another YANG module";
reference
"RFC 5246: The TLS Protocol, Section 7.4.2";
}
}
}
grouping address-and-port-grouping {
description
"a common grouping";
leaf address {
type inet:ip-address;
description
"The IP address of the interface to listen on.";
}
leaf port {
type inet:port-number;
description
"The local port number on this interface the RESTCONF server
listens on.";
}
}
grouping endpoints-container {
description
"Grouping for transport-specific configuration for
call-home connections.";
container endpoints {
description
"Container for the list of endpoints.";
list endpoint {
key name;
min-elements 1;
ordered-by user;
description
"User-ordered list of endpoints for this RESTCONF client.
Defining more than one enables high-availability.";
leaf name {
type string;
description
"An arbitrary name for the endpoint to connect to.";
}
leaf address {
type inet:host;
mandatory true;
description
"The hostname or IP address or hostname of the endpoint.
If a hostname is provided and DNS resolves to more than
one IP address, the RESTCONF server SHOULD try all of
the ones it can based on how its networking stack is
configured (e.g. v4, v6, dual-stack).";
}
leaf port {
type inet:port-number;
description
"The IP port for this endpoint. The RESTCONF server will
use the IANA-assigned well-known port if not specified.";
}
}
}
}
grouping keep-alives-container {
description
"";
container keep-alives {
description
"Configures the keep-alive policy, to proactively test the
aliveness of the RESTCONF client, in order to know when a
new call home connection should be established.";
reference
"RFC VVVV: NETCONF Server and RESTCONF Server Configuration
Models, Section 4";
leaf interval-secs {
type uint8;
units seconds;
description
"Sets a timeout interval in seconds after which if no data
has been received from the RESTCONF client, a message will
be sent to request a response from the RESTCONF client. A
value of '0' indicates that no keep-alive messages should
be sent.";
}
leaf count-max {
type uint8;
default 3;
description
"Sets the number of keep-alive messages that may be sent
without receiving any data from the RESTCONF client before
assuming the RESTCONF client is no longer alive. If this
threshold is reached, the transport-level connection will
be disconnected, which will trigger the reconnection
strategy). The interval timer is reset after each
transmission, thus an unresponsive RESTCONF client will
be dropped after ~count-max * interval-secs seconds.";
}
}
}
}
<CODE ENDS>
5. Implementation strategy for keep-alives
One of the objectives listed above, Keep-alives for persistent One of the objectives listed above, Keep-alives for persistent
connections (Section 2.6.6), indicates a need for a "keep-alive" connections Section 2.6.6, indicates a need for a "keep-alive"
mechanism. This section specifies how the NETCONF keep-alive mechanism. This section specifies how the keep-alive mechanism is to
mechanism is to be implemented for both the SSH and TLS transports. be implemented for both the SSH and TLS transports.
Both SSH and TLS have the ability to support keep-alives securely. Both SSH and TLS have the ability to support keep-alives securely.
Using the strategies listed below, the keep-alive messages are sent Using the strategies listed below, the keep-alive messages are sent
inside the encrypted transport sessions. inside the encrypted tunnel and thus immune to attack.
4.1. Keep-alives for SSH 5.1. Keep-alives for SSH
The SSH keep-alive solution that is expected to be used is ubiquitous The SSH keep-alive solution that is expected to be used is ubiquitous
in practice, though never being explicitly defined in an RFC. The in practice, though never being explicitly defined in an RFC. The
strategy used is to purposely send a malformed request message with a strategy used is to purposely send a malformed request message with a
flag set to ensure a response. More specifically, per section 4 of flag set to ensure a response. More specifically, per section 4 of
[RFC4253], either SSH peer can send a SSH_MSG_GLOBAL_REQUEST message [RFC4253], either SSH peer can send a SSH_MSG_GLOBAL_REQUEST message
with "want reply" set to '1' and that, if there is an error, will get with "want reply" set to '1' and that, if there is an error, will get
back a SSH_MSG_REQUEST_FAILURE response. Similarly, section 5 of back a SSH_MSG_REQUEST_FAILURE response. Similarly, section 5 of
[RFC4253] says that either SSH peer can send a [RFC4253] says that either SSH peer can send a
SSH_MSG_CHANNEL_REQUEST message with "want reply" set to '1' and SSH_MSG_CHANNEL_REQUEST message with "want reply" set to '1' and
skipping to change at page 25, line 16 skipping to change at page 37, line 30
keep-alive strategy (e.g. OpenSSH's `sshd` server) send an invalid keep-alive strategy (e.g. OpenSSH's `sshd` server) send an invalid
"request name" or "request type", respectively. Abiding to the "request name" or "request type", respectively. Abiding to the
extensibility guidelines specified in Section 6 of [RFC4251], these extensibility guidelines specified in Section 6 of [RFC4251], these
implementations use the "name@domain". For instance, when configured implementations use the "name@domain". For instance, when configured
to send keep-alives, OpenSSH sends the string to send keep-alives, OpenSSH sends the string
"keepalive@openssh.com". In order to remain compatible with existing "keepalive@openssh.com". In order to remain compatible with existing
implementations, this draft does not require a specific "request implementations, this draft does not require a specific "request
name" or "request type" string be used, implementations are free to name" or "request type" string be used, implementations are free to
pick values of their choosing. pick values of their choosing.
4.2. Keep-alives for TLS 5.2. Keep-alives for TLS
The TLS keep-alive solution that is expected to be used is defined in The TLS keep-alive solution that is expected to be used is defined in
[RFC6520]. This solution allows both peers to advertise if they can [RFC6520]. This solution allows both peers to advertise if they can
receive heartbeat request messages from its peer. For standard receive heartbeat request messages from its peer. For standard TLS
NETCONF over TLS connections, devices SHOULD advertise connections, devices SHOULD advertise "peer_allowed_to_send", as per
"peer_allowed_to_send", as per [RFC6520]. This advertisement is not [RFC6520]. This advertisement is not a "MUST" in order to
a "MUST" in order to grandfather existing NETCONF over TLS grandfather existing NETCONF/RESTCONF over TLS implementations. For
implementations. For NETCONF Call Home, the network management NETCONF Call Home or RESTCONF Call Home, the network management
system MUST advertise "peer_allowed_to_send" per [RFC6520]. This is system MUST advertise "peer_allowed_to_send" per [RFC6520]. This is
a "MUST" so as to ensure devices can depend in it always being there a "MUST" so as to ensure devices can depend on it always being there
for call home connections, which is when keep-alives are needed the for call home connections, which is when keep-alives are needed the
most. most.
5. Security Considerations 6. Security Considerations
The YANG modules defined in this memo are designed to be accessed via The YANG modules defined in this memo are designed to be accessed via
the NETCONF protocol [RFC6241]. Authorization for access to specific the NETCONF protocol [RFC6241]. Authorization for access to specific
portions of conceptual data and operations within this module is portions of conceptual data and operations within this module is
provided by the NETCONF access control model (NACM) [RFC6536]. provided by the NETCONF access control model (NACM) [RFC6536].
There are a number of data nodes defined in the "ietf-netconf-server" There are a number of data nodes defined in the "ietf-netconf-server"
YANG module which are readable and/or writable that may be considered YANG module which are readable and/or writable that may be considered
sensitive or vulnerable in some network environments. Write and read sensitive or vulnerable in some network environments. Write and read
operations to these data nodes can have a negative effect on network operations to these data nodes can have a negative effect on network
operations. It is thus important to control write and read access to operations. It is thus important to control write and read access to
these data nodes. Below are the data nodes and their sensitivity/ these data nodes. Below are the data nodes and their sensitivity/
vulnerability. vulnerability.
netconf-server/tls/client-auth/trusted-ca-certs: netconf-server/tls/client-auth/trusted-ca-certs:
o This container contains certificates that the system is to use as o This container contains certificates that the server is to use as
trust anchors for authenticating TLS-specific client certificates. trust anchors for authenticating TLS-specific client certificates.
Write access to this node should be protected. Write access to this node should be protected.
netconf-server/tls/client-auth/trusted-client-certs: netconf-server/tls/client-auth/trusted-client-certs:
o This container contains certificates that the system is to trust o This container contains certificates that the server is to trust
directly when authenticating TLS-specific client certificates. directly when authenticating TLS-specific client certificates.
Write access to this node should be protected. Write access to this node should be protected.
netconf-server/tls/client-auth/cert-map: netconf-server/tls/client-auth/cert-map:
o This container contains a user name that some deployments may o This container contains a user name that some deployments may
consider sensitive information. Read access to this node may need consider sensitive information. Read access to this node may need
to be guarded. to be guarded.
6. IANA Considerations 7. IANA Considerations
This document registers two URIs in the IETF XML registry [RFC2119]. This document registers two URIs in the IETF XML registry [RFC2119].
Following the format in [RFC3688], the following registrations are Following the format in [RFC3688], the following registrations are
requested: requested:
URI: urn:ietf:params:xml:ns:yang:ietf-netconf-server URI: urn:ietf:params:xml:ns:yang:ietf-netconf-server
Registrant Contact: The NETCONF WG of the IETF. Registrant Contact: The NETCONF WG of the IETF.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-system-tle-auth URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server
Registrant Contact: The NETCONF WG of the IETF. Registrant Contact: The NETCONF WG of the IETF.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
This document registers two YANG modules in the YANG Module Names This document registers two YANG modules in the YANG Module Names
registry [RFC6020]. registry [RFC6020]. Following the format in [RFC6020], the the
following registrations are requested:
name: ietf-netconf-server name: ietf-netconf-server
namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-server namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-server
prefix: ncserver prefix: ncserver
reference: RFC XXXX reference: RFC VVVV
name: ietf-system-tls-auth name: ietf-restconf-server
namespace: urn:ietf:params:xml:ns:yang:ietf-system-tls-auth namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server
prefix: sys-tls-auth prefix: rcserver
reference: RFC XXXX reference: RFC VVVV
7. Other Considerations 8. Other Considerations
The YANG module define herein does not itself support virtual routing The YANG modules define herein do not themselves support virtual
and forwarding (VRF). It is expected that external modules will routing and forwarding (VRF). It is expected that external modules
augment in VRF designations when needed. will augment in VRF designations when needed.
8. Acknowledgements 9. Acknowledgements
The authors would like to thank for following for lively discussions The authors would like to thank for following for lively discussions
on list and in the halls (ordered by last name): Andy Bierman, Martin on list and in the halls (ordered by last name): Andy Bierman, Martin
Bjorklund, Benoit Claise, David Lamparter, Alan Luchuk, Ladislav Bjorklund, Benoit Claise, Mehmet Ersue, David Lamparter, Alan Luchuk,
Lhotka, Radek Krejci, Tom Petch, and Phil Shafer. Ladislav Lhotka, Radek Krejci, Tom Petch, Phil Shafer, and Bert
Wijnen.
Juergen Schoenwaelder and was partly funded by Flamingo, a Network of Juergen Schoenwaelder and was partly funded by Flamingo, a Network of
Excellence project (ICT-318488) supported by the European Commission Excellence project (ICT-318488) supported by the European Commission
under its Seventh Framework Programme. under its Seventh Framework Programme.
9. References 10. References
9.1. Normative References 10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
Protocol Architecture", RFC 4251, January 2006. Protocol Architecture", RFC 4251, January 2006.
[RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
Transport Layer Protocol", RFC 4253, January 2006. Transport Layer Protocol", RFC 4253, January 2006.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020, Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010. October 2010.
[RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure
Shell Authentication", RFC 6187, March 2011.
[RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A.
Bierman, "Network Configuration Protocol (NETCONF)", RFC Bierman, "Network Configuration Protocol (NETCONF)", RFC
6241, June 2011. 6241, June 2011.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, June 2011. Shell (SSH)", RFC 6242, June 2011.
[RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport
Layer Security (TLS) and Datagram Transport Layer Security Layer Security (TLS) and Datagram Transport Layer Security
(DTLS) Heartbeat Extension", RFC 6520, February 2012. (DTLS) Heartbeat Extension", RFC 6520, February 2012.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536, March Protocol (NETCONF) Access Control Model", RFC 6536, March
2012. 2012.
[RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
July 2013. July 2013.
[draft-ietf-netconf-call-home] [draft-ietf-netconf-call-home]
Watsen, K., "NETCONF Call Home", draft-ieft-netconf-call- Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
home-00 (work in progress), 2014. draft-ieft-netconf-call-home-02 (work in progress), 2014.
[draft-ietf-netconf-restconf]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", draft-ieft-netconf-restconf-04 (work in
progress), 2014.
[draft-ietf-netconf-rfc5539bis]
Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
NETCONF Protocol over Transport Layer Security (TLS)",
draft-ietf-netconf-rfc5539bis-06 (work in progress), 2014.
[draft-ietf-netmod-snmp-cfg] [draft-ietf-netmod-snmp-cfg]
Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for
SNMP Configuration", draft-ietf-netmod-snmp-cfg-08 (work SNMP Configuration", draft-ietf-netmod-snmp-cfg-08 (work
in progress), September 2014. in progress), September 2014.
[rfc5539bis] 10.2. Informative References
Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
NETCONF Protocol over Transport Layer Security (TLS)",
draft-ietf-netconf-rfc5539bis-04 (work in progress),
October 2013.
9.2. Informative References
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
Appendix A. Examples Appendix A. Examples
A.1. SSH Transport Configuration + State A.1. NETCONF Configuration using SSH Transport
The following example illustrastes the <get> response from a NETCONF The following example illustrates the <get> response from a NETCONF
server that only supports SSH, both listening for incoming server that only supports SSH, both listening for incoming
connections as well as calling home to a single application having connections as well as calling home to a single application having
two endpoints. Please also note that the list of host-keys at the two endpoints.
end is read-only operational state.
<netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server"> <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
<session-options>
<hello-timeout>600</hello-timeout>
<idle-timeout>3600</idle-timeout>
</session-options>
<listen> <listen>
<endpoint> <endpoint>
<name>foo bar</name> <name>foo bar</name>
<ssh> <ssh>
<address>11.22.33.44</address> <address>11.22.33.44</address>
<host-keys> <host-keys>
<host-key>my-rsa-key</host-key> <host-key>my-rsa-key</host-key>
<host-key>my-dss-key</host-key> <host-key>my-dss-key</host-key>
</host-keys> </host-keys>
</ssh> </ssh>
skipping to change at page 29, line 49 skipping to change at page 41, line 52
<address>55.66.77.88</address> <address>55.66.77.88</address>
</endpoint> </endpoint>
</endpoints> </endpoints>
<host-keys> <host-keys>
<host-key>my-call-home-x509-key</host-key> <host-key>my-call-home-x509-key</host-key>
</host-keys> </host-keys>
</ssh> </ssh>
</application> </application>
</call-home> </call-home>
<ssh> <ssh>
<host-keys> <x509>
<host-key> <trusted-ca-certs>
<name>my-rsa-key</name> <trusted-ca-cert>
<format-identifier>ssh-rsa</format-identifier> QW4gRWFzdGVyIGVnZywgZm9yIHRob3NlIHdobyBtaWdodCBsb29rICA6KQo=
<data> <!-- base64 reformated for draft --> </trusted-ca-cert>
AAAAB3NzaC1yc2EAAAABIwAAAQEA7D2lxYg3+WD97RZqZtO8bUU8QpIl6g9 </trusted-ca-certs>
X11kZHZ8NgSIR+x2H1MHCD5sEjmx/B6JIouK5eBvbJE9FFV3phsl62fupN6 <trusted-client-certs>
Y4EmXosC6iqpuI41dcGA63XCQ1OenWG4ppdq1f8tlecSrmEcLw7MKPzBHK6 <trusted-client-cert>
rNQTciqMuVuLPOKwBu/54QAiUwvvHKAsk8bkN9YxEJ1NTV1FFQmvMOADVcD SSBhbSB0aGUgZWdnIG1hbiwgdGhleSBhcmUgdGhlIGVnZyBtZW4uCg==
2qqPangETwV5zInW8AEkBbLccM/mmHucGNS81axXR3V9R5KgXF2DyGB47d2 </trusted-client-cert>
k6iOnGa3LBIOYi/5Q+O8IFUlO+kytfqwuFgUc+Mx7aKReSIAPov3owVjeBL <trusted-client-cert>
KWsvjD24UO68qtwQ== SSBhbSB0aGUgd2FscnVzLCBnb28gZ29vIGcnam9vYi4K
</data> </trusted-client-cert>
<fingerprint> </trusted-client-certs>
c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87 </x509>
</fingerprint>
</host-key>
<host-key>
<name>my-dss-key</name>
<format-identifier>ssh-dss</format-identifier>
<data> <!-- base64 reformated for draft -->
AAAAB3NzaC1kc3MAAACBAIq7XfGmZKJgibJEIMzj70YMVfpeewBCj89VrUS
gLsJmxP/TrXFuhzW2UIaI8sePMYUXj/Vgp5DUD+eBSBkHMH4ga0U5t/clqn
y73x8Vg6LQg9f0OTaUnpRWbWrdac7U5/BRBTtMA3amHZhHrKs7BrCepS/y8
cUbxBCPF3aYMK/5AAAAFQC7wetEbDwghYtz8Z3xIwDdxs6mOwAAAIBursEk
jnvs5zzyUH7iNiyBojDoyrsq81jPM6KopkfA5Ypp2KTySPev/mkL0SoVfIb
+HttVfQ3Q63+sf1Qyk+gUtniSdN2AqtFQYKxtTcXim4McWk6IixkYFP8kkt
02t9Hsl0eXvltmogrlRsiuJsTAbFS+QTeq4OGTODCT5jjVdQAAAIA2llpZg
y5v46lGt4dQhkH8ytyMGyjBRPF6rm51msinX3lMR9xfwTaS7ZYP0b6HJt5M
sQI+m7iIYaVFB1oC8niXbkkavLcxhGpNVkwE2INWS4TIBbTQhivuoE+dMYY
KauLQxqSUjixJk3LjhCQb
</data>
<fingerprint>
c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87
</fingerprint>
</host-key>
<host-key>
<name>my-call-home-x509-key</name>
<format-identifier>x509v3-rsa2048-sha256</format-identifier>
<data> <!-- base64 reformated for draft -->
AAAAB3NzaC1yc2EAAAABIwAAAQEAyBLl90dPUGX7Es12q7YKkw6v8WgWop+
B62zhT39C+yvslMIwIqgHYii0h/TGktahKpBwssawfhvAZoMF/nOyO3yDPD
pQxNrA76H7owNOjG5206QHDYfVALKPvxgrDy/6BjsR9MayOGkZTSL6GRFSl
g7ivT9AIR9E5qXmP+1z+IDufRlpwfaGfpZAxjJLEwzAjFAIwXsXKJ5FH/QP
mfC6gxfhqpt9rJCDlgqmzrXi8dXKsFUC3/o1lzezqTXTV1iMETTuCHgWegF
5QcX2baBdFgCnkd1SnftVoBHVnvXA1euRqgiG3fMNK4rct0D99D+GI+kZc+
vQyUdCw3dPlhXPZw==
</data>
<fingerprint>
97:77:10:29:d7:b8:de:6c:97:77:30:29:d7:41:63:87
</fingerprint>
</host-key>
</host-keys>
</ssh> </ssh>
</netconf-server> </netconf-server>
A.2. TLS Transport Configuration + State A.2. NETCONF Configuration using TLS Transport
The following example illustrastes the <get> response from a NETCONF The following example illustrates the <get> response from a NETCONF
server that only supports TLS, both listening for incoming server that only supports TLS, both listening for incoming
connections as well as calling home to a single application having connections as well as calling home to a single application having
two endpoints. Please note also the configurations for two endpoints. Please note also the configurations for
authenticating client certificates and mappings authenticated authenticating client certificates and mappings authenticated
certificates to NETCONF user names. certificates to NETCONF user names.
<netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server"> <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
<session-options>
<hello-timeout>600</hello-timeout>
<idle-timeout>3600</idle-timeout>
</session-options>
<listen> <listen>
<endpoint> <endpoint>
<name>primary-netconf-endpoint</name> <name>primary-netconf-endpoint</name>
<tls> <tls>
<address>11.22.33.44</address> <address>11.22.33.44</address>
<certificates> <certificates>
<certificate>fw1.east.example.com</certificate> <certificate>fw1.east.example.com</certificate>
</certificates> </certificates>
</tls> </tls>
</endpoint> </endpoint>
skipping to change at page 31, line 51 skipping to change at page 43, line 19
<address>55.66.77.88</address> <address>55.66.77.88</address>
</endpoint> </endpoint>
</endpoints> </endpoints>
<certificates> <certificates>
<certificate>fw1.east.example.com</certificate> <certificate>fw1.east.example.com</certificate>
</certificates> </certificates>
</tls> </tls>
</application> </application>
</call-home> </call-home>
<tls> <tls>
<certificates>
<certificate>
<name>fw1.east.example.com</name>
<data> <!-- base64 reformated for draft -->
AAAAB3NzaC1yc2EAAAABIwAAAQEA7D2lxYg3+WD97RZqZtO8bUU8QpIl6g9
X11kZHZ8NgSIR+x2H1MHCD5sEjmx/B6JIouK5eBvbJE9FFV3phsl62fupN6
Y4EmXosC6iqpuI41dcGA63XCQ1OenWG4ppdq1f8tlecSrmEcLw7MKPzBHK6
rNQTciqMuVuLPOKwBu/54QAiUwvvHKAsk8bkN9YxEJ1NTV1FFQmvMOADVcD
2qqPangETwV5zInW8AEkBbLccM/mmHucGNS81axXR3V9R5KgXF2DyGB47d2
k6iOnGa3LBIOYi/5Q+O8IFUlO+kytfqwuFgUc+Mx7aKReSIAPov3owVjeBL
KWsvjD24UO68qtwQ==
</data>
</certificate>
</certificates>
<client-auth> <client-auth>
<trusted-ca-certs> <trusted-ca-certs>
<trusted-ca-cert> <trusted-ca-cert>
QW4gRWFzdGVyIGVnZywgZm9yIHRob3NlIHdobyBtaWdodCBsb29rICA6KQo= QW4gRWFzdGVyIGVnZywgZm9yIHRob3NlIHdobyBtaWdodCBsb29rICA6KQo=
</trusted-ca-cert> </trusted-ca-cert>
</trusted-ca-certs> </trusted-ca-certs>
<trusted-client-certs> <trusted-client-certs>
<trusted-client-cert> <trusted-client-cert>
SSBhbSB0aGUgZWdnIG1hbiwgdGhleSBhcmUgdGhlIGVnZyBtZW4uCg== SSBhbSB0aGUgZWdnIG1hbiwgdGhleSBhcmUgdGhlIGVnZyBtZW4uCg==
</trusted-client-cert> </trusted-client-cert>
skipping to change at page 32, line 46 skipping to change at page 44, line 4
<cert-to-name> <cert-to-name>
<id>2</id> <id>2</id>
<fingerprint>11:0A:05:11:00</fingerprint> <fingerprint>11:0A:05:11:00</fingerprint>
<map-type>x509c2n:specified</map-type> <map-type>x509c2n:specified</map-type>
<name>Joe Cool</name> <name>Joe Cool</name>
</cert-to-name> </cert-to-name>
</cert-maps> </cert-maps>
</client-auth> </client-auth>
</tls> </tls>
</netconf-server> </netconf-server>
A.3. RESTCONF Configuration using TLS Transport
The following example illustrates the <get> response from a RESTCONF
server that only supports TLS, both listening for incoming
connections as well as calling home to a single application having
two endpoints.
<restconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-server">
<listen>
<endpoint>
<name>primary-restconf-endpoint</name>
<tls>
<address>11.22.33.44</address>
<certificates>
<certificate>fw1.east.example.com</certificate>
</certificates>
</tls>
</endpoint>
</listen>
<call-home>
<application>
<name>config-mgr</name>
<tls>
<endpoints>
<endpoint>
<name>east-data-center</name>
<address>11.22.33.44</address>
</endpoint>
<endpoint>
<name>west-data-center</name>
<address>55.66.77.88</address>
</endpoint>
</endpoints>
<certificates>
<certificate>fw1.east.example.com</certificate>
</certificates>
</tls>
</application>
</call-home>
</restconf-server>
Appendix B. Change Log Appendix B. Change Log
B.1. 00 to 01 B.1. 00 to 01
o Restructured document so it flows better o Restructured document so it flows better
o Added trusted-ca-certs and trusted-client-certs objects into the o Added trusted-ca-certs and trusted-client-certs objects into the
ietf-system-tls-auth module ietf-system-tls-auth module
B.2. 01 to 02 B.2. 01 to 02
o removed the "one-to-many" construct o removed the "one-to-many" construct
o removed "address" as a key field o removed "address" as a key field
o removed "network-manager" terminology o removed "network-manager" terminology
skipping to change at page 34, line 5 skipping to change at page 45, line 44
o added missing "objectives" for selecting which keys to use, o added missing "objectives" for selecting which keys to use,
authenticating client-certificates, and mapping authenticated authenticating client-certificates, and mapping authenticated
client-certificates to usernames client-certificates to usernames
o clarified indirect client certificate authentication o clarified indirect client certificate authentication
o added keep-alive configuration for listen connections o added keep-alive configuration for listen connections
o added global-level NETCONF session parameters o added global-level NETCONF session parameters
B.5. 04 to 05
o Removed all refs to the old ietf-system-tls-auth module
o Removed YANG 1.1 style if-feature statements (loss some
expressiveness)
o Removed the read-only (config false) lists of SSH host-keys and
TLS certs
o Added an if-feature around session-options container
o Added ability to configure trust-anchors for SSH X.509 client
certs
o Now imports by revision, per best practice
o Added support for RESTCONF server
o Added RFC Editor instructions
Appendix C. Open Issues Appendix C. Open Issues
Please see: https://github.com/netconf-wg/server-model/issues. Please see: https://github.com/netconf-wg/server-model/issues.
Authors' Addresses Authors' Addresses
Kent Watsen Kent Watsen
Juniper Networks Juniper Networks
EMail: kwatsen@juniper.net EMail: kwatsen@juniper.net
 End of changes. 120 change blocks. 
952 lines changed or deleted 1516 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/