draft-ietf-netconf-restconf-client-server-01.txt   draft-ietf-netconf-restconf-client-server-02.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: May 7, 2017 Jacobs University Bremen Expires: September 14, 2017 Jacobs University Bremen
November 3, 2016 March 13, 2017
RESTCONF Client and Server Models RESTCONF Client and Server Models
draft-ietf-netconf-restconf-client-server-01 draft-ietf-netconf-restconf-client-server-02
Abstract Abstract
This document defines two YANG modules, one module to configure a This document defines two YANG modules, one module to configure a
RESTCONF client and the other module to configure a RESTCONF server. RESTCONF client and the other module to configure a RESTCONF server.
Both modules support the TLS transport protocol with both standard Both modules support the TLS transport protocol with both standard
RESTCONF and RESTCONF Call Home connections. RESTCONF and RESTCONF Call Home connections.
Editorial Note (To be removed by RFC Editor) Editorial Note (To be removed by RFC Editor)
This draft contains many placeholder values that need to be replaced This draft contains many placeholder values that need to be replaced
with finalized values at the time of publication. This note with finalized values at the time of publication. This note
summarizes all of the substitutions that are needed. No other RFC summarizes all of the substitutions that are needed. No other RFC
Editor instructions are specified elsewhere in this document. Editor instructions are specified elsewhere in this document.
This document contains references to other drafts in progress, both This document contains references to other drafts in progress, both
in the Normative References section, as well as in body text in the Normative References section, as well as in body text
throughout. Please update the following references to reflect their throughout. Please update the following references to reflect their
final RFC assignments: final RFC assignments:
o draft-ietf-netconf-keystore o I-D.ietf-netconf-keystore
o draft-ietf-netconf-tls-client-server o I-D.ietf-netconf-tls-client-server
Artwork in this document contains shorthand references to drafts in Artwork in this document contains shorthand references to drafts in
progress. Please apply the following replacements: progress. Please apply the following replacements:
o "XXXX" --> the assigned RFC value for this draft o "XXXX" --> the assigned RFC value for this draft
o "YYYY" --> the assigned RFC value for draft-ietf-netconf-restconf o "ZZZZ" --> the assigned RFC value for I-D.ietf-netconf-tls-client-
server
o "ZZZZ" --> the assigned RFC value for draft-ietf-netconf-tls-
client-server
Artwork in this document contains placeholder values for the date of Artwork in this document contains placeholder values for the date of
publication of this draft. Please apply the following replacement: publication of this draft. Please apply the following replacement:
o "2016-11-02" --> the publication date of this draft o "2017-03-13" --> the publication date of this draft
The following two Appendix sections are to be removed prior to The following two Appendix sections are to be removed prior to
publication: publication:
o Appendix A. Change Log o Appendix A. Change Log
o Appendix B. Open Issues o Appendix B. 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
skipping to change at page 2, line 26 skipping to change at page 2, line 24
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 May 7, 2017. This Internet-Draft will expire on September 14, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2017 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 . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3
2. The RESTCONF Client Model . . . . . . . . . . . . . . . . . . 4 2. The RESTCONF Client Model . . . . . . . . . . . . . . . . . . 4
2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4
2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 6
2.3. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 8
3. The RESTCONF Server Model . . . . . . . . . . . . . . . . . . 16
3. The RESTCONF Server Model . . . . . . . . . . . . . . . . . . 7 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 16
3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 18
3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 9 3.3. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 20
3.3. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . . 29
4. Security Considerations . . . . . . . . . . . . . . . . . . . 20 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 30
5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 20 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 30
5.2. The YANG Module Names Registry . . . . . . . . . . . . . 20 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 31
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.1. Normative References . . . . . . . . . . . . . . . . . . 31
7.1. Normative References . . . . . . . . . . . . . . . . . . 21 7.2. Informative References . . . . . . . . . . . . . . . . . 31
7.2. Informative References . . . . . . . . . . . . . . . . . 21 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 33
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 23 A.1. server-model-09 to 00 . . . . . . . . . . . . . . . . . . 33
A.1. server-model-09 to 00 . . . . . . . . . . . . . . . . . . 23 A.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 33
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 23 A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 33
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 33
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33
1. Introduction 1. Introduction
This document defines two YANG [RFC6020] modules, one module to This document defines two YANG [RFC7950] modules, one module to
configure a RESTCONF client and the other module to configure a configure a RESTCONF client and the other module to configure a
RESTCONF server [draft-ietf-netconf-restconf]. Both modules support RESTCONF server [RFC8040]. Both modules support the TLS [RFC5246]
the TLS [RFC5246] transport protocol with both standard RESTCONF and transport protocol with both standard RESTCONF and RESTCONF Call Home
RESTCONF Call Home connections [draft-ietf-netconf-call-home]. connections [RFC8071].
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 the data models is used in A simplified graphical representation of the data models is used in
skipping to change at page 4, line 19 skipping to change at page 4, line 19
shown. shown.
2. The RESTCONF Client Model 2. The RESTCONF Client Model
EDITOR NOTE: Please ignore this section, it is incomplete. EDITOR NOTE: Please ignore this section, it is incomplete.
The RESTCONF client model presented in this section supports both The RESTCONF client model presented in this section supports both
clients initiating connections to servers, as well as clients clients initiating connections to servers, as well as clients
listening for connections from servers calling home. listening for connections from servers calling home.
This model supports both TLS transport protocols using the TLS client This model supports the TLS transport protocol using the TLS client
groupings defined in [draft-ietf-netconf-tls-client-server]. groupings defined in [I-D.ietf-netconf-tls-client-server].
All private keys and trusted certificates are held in the keystore All private keys and trusted certificates are held in the keystore
model defined in [draft-ietf-netconf-keystore]. model defined in [I-D.ietf-netconf-keystore].
YANG feature statements are used to enable implementations to YANG feature statements are used to enable implementations to
advertise which parts of the model the RESTCONF client supports. advertise which parts of the model the RESTCONF client supports.
2.1. Tree Diagram 2.1. Tree Diagram
Note: all lines are folded at column 71 with no '\' character. Note: all lines are folded at column 71 with no '\' character.
module: ietf-restconf-client module: ietf-restconf-client
+--rw restconf-client +--rw restconf-client
+--rw initiate {tls-initiate}? +--rw initiate {initiate}?
+--rw listen {tls-listen}? | +--rw restconf-server* [name]
| +--rw name string
| +--rw (transport)
| | +--:(tls) {tls-initiate}?
| | +--rw tls
| | +--rw endpoints
| | | +--rw endpoint* [name]
| | | +--rw name string
| | | +--rw address inet:host
| | | +--rw port? inet:port-number
| | +--rw server-auth
| | | +--rw trusted-ca-certs? leafref
| | | +--rw trusted-server-certs? leafref
| | +--rw client-auth
| | | +--rw (auth-type)?
| | | +--:(certificate)
| | | +--rw certificate? leafref
| | +--rw hello-params
| | {tls-client-hello-params-config}?
| | +--rw tls-versions
| | | +--rw tls-version* identityref
| | +--rw cipher-suites
| | +--rw cipher-suite* identityref
| +--rw connection-type
| | +--rw (connection-type)?
| | +--:(persistent-connection)
| | | +--rw persistent!
| | | +--rw idle-timeout? uint32
| | | +--rw keep-alives
| | | +--rw max-wait? uint16
| | | +--rw max-attempts? uint8
| | +--:(periodic-connection)
| | +--rw periodic!
| | +--rw idle-timeout? uint16
| | +--rw reconnect-timeout? uint16
| +--rw reconnect-strategy
| +--rw start-with? enumeration
| +--rw max-attempts? uint8
+--rw listen {listen}?
+--rw max-sessions? uint16
+--rw idle-timeout? uint16
+--rw endpoint* [name]
+--rw name string
+--rw (transport)
+--:(tls) {tls-listen}?
+--rw tls
+--rw address? inet:ip-address
+--rw port? inet:port-number
+--rw server-auth
| +--rw trusted-ca-certs? leafref
| +--rw trusted-server-certs? leafref
+--rw client-auth
| +--rw (auth-type)?
| +--:(certificate)
| +--rw certificate? leafref
+--rw hello-params
{tls-client-hello-params-config}?
+--rw tls-versions
| +--rw tls-version* identityref
+--rw cipher-suites
+--rw cipher-suite* identityref
2.2. Example Usage 2.2. Example Usage
The following example illustrates configuring a RESTCONF client to The following example illustrates configuring a RESTCONF client to
initiate connections, as well as listening for call-home connections. initiate connections, as well as listening for call-home connections.
This example is consistent with the examples presented in Section 2.2 This example is consistent with the examples presented in Section 2.2
of [draft-ietf-netconf-keystore]. of [I-D.ietf-netconf-keystore].
FIXME <restconf-client
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-client">
<!-- RESTCONF servers to initiate connections to -->
<initiate>
<restconf-server>
<name>corp-fw1</name>
<tls>
<endpoints>
<endpoint>
<name>corp-fw1.example.com</name>
<address>corp-fw1.example.com</address>
</endpoint>
<endpoint>
<name>corp-fw2.example.com</name>
<address>corp-fw2.example.com</address>
</endpoint>
</endpoints>
<server-auth>
<trusted-server-certs>deployment-specific-ca-certs</trusted-server-certs>
</server-auth>
<client-auth>
<certificate>tls-ec-cert</certificate>
</client-auth>
</tls>
</restconf-server>
</initiate>
<!-- endpoints to listen for RESTCONF Call Home connections on -->
<listen>
<endpoint>
<name>Intranet-facing listener</name>
<tls>
<address>11.22.33.44</address>
<server-auth>
<trusted-ca-certs>deployment-specific-ca-certs</trusted-ca-certs>
<trusted-server-certs>explicitly-trusted-server-certs</trusted-server-certs>
</server-auth>
<client-auth>
<certificate>tls-ec-cert</certificate>
</client-auth>
</tls>
</endpoint>
</listen>
</restconf-client>
2.3. YANG Model 2.3. YANG Model
This YANG module imports YANG types from [RFC6991] and [RFC7407]. This YANG module imports YANG types from [RFC6991] and [RFC7407].
<CODE BEGINS> file "ietf-restconf-client@2016-11-02.yang" <CODE BEGINS> file "ietf-restconf-client@2017-03-13.yang"
// Editor's Note:
// This module is incomplete at this time. Below is
// just a skeleton so there's something in the draft.
// Please ignore this module for now!
module ietf-restconf-client { module ietf-restconf-client {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client";
prefix "rcc"; prefix "rcc";
/* import ietf-inet-types {
import ietf-inet-types { prefix inet;
prefix inet; reference
reference "RFC 6991: Common YANG Data Types";
"RFC 6991: Common YANG Data Types"; }
}
//import ietf-netconf-acm { import ietf-tls-client {
// prefix nacm; prefix ts;
// reference revision-date 2017-03-13; // stable grouping definitions
// "RFC 6536: Network Configuration Protocol (NETCONF) reference
// Access Control Model"; "RFC ZZZZ: TLS Client and Server Models";
//} }
import ietf-x509-cert-to-name { organization
prefix x509c2n; "IETF NETCONF (Network Configuration) Working Group";
reference
"RFC 7407: A YANG Data Model for SNMP Configuration";
}
import ietf-tls-client { contact
prefix ts; "WG Web: <http://tools.ietf.org/wg/restconf/>
revision-date 2016-11-02; // stable grouping definitions WG List: <mailto:restconf@ietf.org>
reference
"RFC ZZZZ: TLS Client and Server Models";
}
*/
organization
"IETF NETCONF (Network Configuration) Working Group";
contact Author: Kent Watsen
"WG Web: <http://tools.ietf.org/wg/netconf/> <mailto:kwatsen@juniper.net>
WG List: <mailto:netconf@ietf.org>
WG Chair: Mehmet Ersue Author: Gary Wu
<mailto:mehmet.ersue@nsn.com> <mailto:garywu@cisco.com>";
WG Chair: Mahesh Jethanandani description
<mailto:mjethanandani@gmail.com> "This module contains a collection of YANG definitions for
configuring RESTCONF clients.
Editor: Kent Watsen Copyright (c) 2014 IETF Trust and the persons identified as
<mailto:kwatsen@juniper.net>"; authors of the code. All rights reserved.
description Redistribution and use in source and binary forms, with or
"This module contains a collection of YANG definitions for without modification, is permitted pursuant to, and subject
configuring RESTCONF servers. 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).
Copyright (c) 2014 IETF Trust and the persons identified as This version of this YANG module is part of RFC XXXX; see
authors of the code. All rights reserved. the RFC itself for full legal notices.";
Redistribution and use in source and binary forms, with or revision "2017-03-13" {
without modification, is permitted pursuant to, and subject description
to the license terms contained in, the Simplified BSD "Initial version";
License set forth in Section 4.c of the IETF Trust's reference
Legal Provisions Relating to IETF Documents "RFC XXXX: RESTCONF Client and Server Models";
(http://trustee.ietf.org/license-info). }
This version of this YANG module is part of RFC XXXX; see // Features
the RFC itself for full legal notices.";
revision "2016-11-02" { feature initiate {
description description
"Initial version"; "The 'initiate' feature indicates that the RESTCONF client
reference supports initiating RESTCONF connections to RESTCONF servers
"RFC XXXX: RESTCONF Client and Server Models"; using at least one transport (e.g., TLS, etc.).";
} }
// Features feature tls-initiate {
description
"The 'tls-initiate' feature indicates that the RESTCONF client
supports initiating TLS connections to RESTCONF servers.";
reference
"RFC 8040: RESTCONF Protocol";
}
feature tls-initiate { feature listen {
description description
"The tls-initiate feature indicates that the RESTCONF client "The 'listen' feature indicates that the RESTCONF client
supports initiating TLS connections to RESTCONF servers."; supports opening a port to accept RESTCONF server call
reference home connections using at least one transport (e.g.,
"RFC YYYY: RESTCONF Protocol"; TLS, etc.).";
} }
feature tls-listen { feature tls-listen {
description description
"The tls-listen feature indicates that the RESTCONF client "The 'tls-listen' feature indicates that the RESTCONF client
supports opening a port to listen for incoming RESTCONF supports opening a port to listen for incoming RESTCONF
server call-home TLS connections."; server call-home TLS connections.";
reference reference
"RFC AAAA: NETCONF Call Home and RESTCONF Call Home"; "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
} }
container restconf-client { container restconf-client {
description description
"Top-level container for RESTCONF client configuration."; "Top-level container for RESTCONF client configuration.";
container initiate {
if-feature tls-initiate;
description
"Configures client intiating underlying TCP connections.";
}
container listen {
if-feature tls-listen;
description
"Configures client accepting call-home TCP connections.";
}
}
} container initiate {
if-feature initiate;
description
"Configures client initiating underlying TCP connections.";
list restconf-server {
key name;
description
"List of RESTCONF servers the RESTCONF client is to initiate
connections to.";
leaf name {
type string;
description
"An arbitrary name for the RESTCONF server.";
}
choice transport {
mandatory true;
description
"Selects between available transports.";
<CODE ENDS> case tls {
if-feature tls-initiate;
container tls {
description
"Specifies TLS-specific transport configuration.";
uses endpoints-container {
refine endpoints/endpoint/port {
default 443;
}
}
uses ts:tls-client-grouping;
}
} // end tls
} // end transport
container connection-type {
description
"Indicates the kind of connection to use.";
choice connection-type {
description
"Selects between available connection types.";
case persistent-connection {
container persistent {
presence true;
description
"Maintain a persistent connection to the RESTCONF
server. If the connection goes down, immediately
start trying to reconnect to it, using the
reconnection strategy.
This connection type minimizes any RESTCONF server
to RESTCONF client data-transfer delay, albeit at
the expense of holding resources longer.";
leaf idle-timeout {
type uint32;
units "seconds";
default 86400; // one day;
description
"Specifies the maximum number of seconds that a
a RESTCONF session may remain idle. A RESTCONF
session will be dropped if it is idle for an
interval longer than this number of seconds.
If set to zero, then the client will never drop
a session because it is idle. Sessions that
have a notification subscription active are
never dropped.";
}
container keep-alives {
description
"Configures the keep-alive policy, to proactively
test the aliveness of the SSH/TLS server. An
unresponsive SSH/TLS server will be dropped after
approximately max-attempts * max-wait seconds.";
reference
"RFC 8071: NETCONF Call Home and RESTCONF Call
Home, Section 3.1, item S6";
leaf max-wait {
type uint16 {
range "1..max";
}
units seconds;
default 30;
description
"Sets the amount of time in seconds after which
if no data has been received from the SSH/TLS
server, a SSH/TLS-level message will be sent
to test the aliveness of the SSH/TLS server.";
}
leaf max-attempts {
type uint8;
default 3;
description
"Sets the maximum number of sequential keep-alive
messages that can fail to obtain a response from
the SSH/TLS server before assuming the SSH/TLS
server is no longer alive.";
}
}
}
}
case periodic-connection {
container periodic {
presence true;
description
"Periodically connect to the RESTCONF server, so that
the RESTCONF server may deliver messages pending for
the RESTCONF client. The RESTCONF server must close
the connection when it is ready to release it. Once
the connection has been closed, the RESTCONF client
will restart its timer until the next connection.";
leaf idle-timeout {
type uint16;
units "seconds";
default 300; // five minutes
description
"Specifies the maximum number of seconds that a
a RESTCONF session may remain idle. A RESTCONF
session will be dropped if it is idle for an
interval longer than this number of seconds.
If 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.";
}
leaf reconnect-timeout {
type uint16 {
range "1..max";
}
units minutes;
default 60;
description
"Sets the maximum amount of unconnected time the
RESTCONF client will wait before re-establishing
a connection to the RESTCONF server. The RESTCONF
client may initiate a connection before this
time if desired (e.g., to set configuration).";
}
}
}
}
}
container reconnect-strategy {
description
"The reconnection strategy directs how a RESTCONF client
reconnects to a RESTCONF server, after discovering its
connection to the server has dropped, even if due to a
reboot. The RESTCONF client starts with the specified
endpoint and tries to connect to it max-attempts times
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. If no previous
connection has ever been established, then the
first endpoint configured is used. RESTCONF
clients SHOULD be able to remember the last
endpoint connected to across reboots.";
}
}
default first-listed;
description
"Specifies which of the RESTCONF server's endpoints the
RESTCONF client should start with when trying to connect
to the RESTCONF server.";
}
leaf max-attempts {
type uint8 {
range "1..max";
}
default 3;
description
"Specifies the number times the RESTCONF client tries to
connect to a specific endpoint before moving on to the
next endpoint in the list (round robin).";
}
}
} // end restconf-server
} // end initiate
container listen {
if-feature listen;
description
"Configures client accepting call-home TCP connections.";
leaf max-sessions {
type uint16;
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.";
}
leaf idle-timeout {
type uint16;
units "seconds";
default 3600; // one hour
description
"Specifies the maximum number of seconds that a RESTCONF
session may remain idle. A RESTCONF session will be dropped
if it is idle for an interval longer than this number of
seconds. If 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.";
}
list endpoint {
key name;
description
"List of endpoints to listen for RESTCONF connections.";
leaf name {
type string;
description
"An arbitrary name for the RESTCONF listen endpoint.";
}
choice transport {
mandatory true;
description
"Selects between available transports.";
case tls {
if-feature tls-listen;
container tls {
description
"TLS-specific listening configuration for inbound
connections.";
leaf address {
type inet:ip-address;
description
"The IP address to listen for call-home connections.";
}
leaf port {
type inet:port-number;
default 4336;
description
"The port number to listen for call-home connections.";
}
uses ts:tls-client-grouping;
}
}
} // end transport
} // end endpoint
} // end listen
} // end restconf-client
grouping endpoints-container {
description
"This grouping is used to configure a set of RESTCONF servers
a RESTCONF client may initiate connections to.";
container endpoints {
description
"Container for the list of endpoints.";
list endpoint {
key name;
unique "address port";
min-elements 1;
ordered-by user;
description
"A non-empty user-ordered list of endpoints for this RESTCONF
client to try to connect to. Defining more than one enables
high-availability.";
leaf name {
type string;
description
"An arbitrary name for this endpoint.";
}
leaf address {
type inet:host;
mandatory true;
description
"The IP address or hostname of the endpoint. If a
hostname is configured and the DNS resolution results
in more than one IP address, the RESTCONF client
will process the IP addresses as if they had been
explicitly configured in place of the hostname.";
}
leaf port {
type inet:port-number;
description
"The IP port for this endpoint. The RESTCONF client will
use the IANA-assigned well-known port (set via a refine
statement when uses) if no value is specified.";
}
}
}
}
}
<CODE ENDS>
3. The RESTCONF Server Model 3. The RESTCONF Server Model
The RESTCONF Server model presented in this section supports servers The RESTCONF Server model presented in this section supports servers
both listening for connections as well as initiating call-home both listening for connections as well as initiating call-home
connections. connections.
This model supports the TLS using the TLS server groupings defined in This model supports the TLS transport protocol using the TLS server
[draft-ietf-netconf-tls-client-server]. groupings defined in [I-D.ietf-netconf-tls-client-server].
All private keys and trusted certificates are held in the keystore All private keys and trusted certificates are held in the keystore
model defined in [draft-ietf-netconf-keystore]. model defined in [I-D.ietf-netconf-keystore].
YANG feature statements are used to enable implementations to YANG feature statements are used to enable implementations to
advertise which parts of the model the RESTCONF server supports. advertise which parts of the model the RESTCONF server supports.
3.1. Tree Diagram 3.1. Tree Diagram
Note: all lines are folded at column 71 with no '\' character. Note: all lines are folded at column 71 with no '\' character.
module: ietf-restconf-server module: ietf-restconf-server
+--rw restconf-server +--rw restconf-server
+--rw listen {listen}? +--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)
| +--:(tls) {tls-listen}? | +--:(tls) {tls-listen}?
| +--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* [name] | | +--rw certificate* [name]
| | +--rw name -> /ks:keystore/private-keys/ | | +--rw name leafref
private-key/certificate-chains/certificate-chain/name | +--rw client-auth
| +--rw client-auth | | +--rw trusted-ca-certs? leafref
| +--rw trusted-ca-certs? -> /ks:keystore/ | | +--rw trusted-client-certs? leafref
trusted-certificates/name | | +--rw cert-maps
| +--rw trusted-client-certs? -> /ks:keystore/ | | +--rw cert-to-name* [id]
trusted-certificates/name | | +--rw id uint32
| +--rw cert-maps | | +--rw fingerprint x509c2n:tls-fingerprint
| +--rw cert-to-name* [id] | | +--rw map-type identityref
| +--rw id uint32 | | +--rw name string
| +--rw fingerprint x509c2n:tls-fingerp | +--rw hello-params
rint | {tls-server-hello-params-config}?
| +--rw map-type identityref | +--rw tls-versions
| +--rw name string | | +--rw tls-version* identityref
+--rw call-home {call-home}? | +--rw cipher-suites
+--rw restconf-client* [name] | +--rw cipher-suite* identityref
+--rw name string +--rw call-home {call-home}?
+--rw (transport) +--rw restconf-client* [name]
| +--:(tls) {tls-call-home}? +--rw name string
| +--rw tls +--rw (transport)
| +--rw endpoints | +--:(tls) {tls-call-home}?
| | +--rw endpoint* [name] | +--rw tls
| | +--rw name string | +--rw endpoints
| | +--rw address inet:host | | +--rw endpoint* [name]
| | +--rw port? inet:port-number | | +--rw name string
| +--rw certificates | | +--rw address inet:host
| | +--rw certificate* [name] | | +--rw port? inet:port-number
| | +--rw name -> /ks:keystore/private-keys/ | +--rw certificates
private-key/certificate-chains/certificate-chain/name | | +--rw certificate* [name]
| +--rw client-auth | | +--rw name leafref
| +--rw trusted-ca-certs? -> /ks:keystore/ | +--rw client-auth
trusted-certificates/name | | +--rw trusted-ca-certs? leafref
| +--rw trusted-client-certs? -> /ks:keystore/ | | +--rw trusted-client-certs? leafref
trusted-certificates/name | | +--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-fingerp | | +--rw map-type identityref
rint | | +--rw name string
| +--rw map-type identityref | +--rw hello-params
| +--rw name string | {tls-server-hello-params-config}?
+--rw connection-type | +--rw tls-versions
| +--rw (connection-type)? | | +--rw tls-version* identityref
| +--:(persistent-connection) | +--rw cipher-suites
| | +--rw persistent! | +--rw cipher-suite* identityref
| | +--rw keep-alives +--rw connection-type
| | +--rw max-wait? uint16 | +--rw (connection-type)?
| | +--rw max-attempts? uint8 | +--:(persistent-connection)
| +--:(periodic-connection) | | +--rw persistent!
| +--rw periodic! | | +--rw keep-alives
| +--rw reconnect-timeout? uint16 | | +--rw max-wait? uint16
+--rw reconnect-strategy | | +--rw max-attempts? uint8
+--rw start-with? enumeration | +--:(periodic-connection)
+--rw max-attempts? uint8 | +--rw periodic!
| +--rw reconnect-timeout? uint16
+--rw reconnect-strategy
+--rw start-with? enumeration
+--rw max-attempts? uint8
3.2. Example Usage 3.2. Example Usage
The following example illustrates configuring a RESTCONF server to The following example illustrates configuring a RESTCONF server to
listen for RESTCONF client connections, as well as configuring call- listen for RESTCONF client connections, as well as configuring call-
home to one RESTCONF client. home to one RESTCONF client.
This example is consistent with the examples presented in Section 2.2 This example is consistent with the examples presented in Section 2.2
of [draft-ietf-netconf-keystore]. of [I-D.ietf-netconf-keystore].
<restconf-server
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-server">
<!-- listening for TLS (HTTPS) connections -->
<listen>
<endpoint>
<name>netconf/tls</name>
<tls>
<address>11.22.33.44</address>
<certificates>
<certificate>ex-key-sect571r1-cert</certificate>
</certificates>
<client-auth>
<trusted-ca-certs>
deployment-specific-ca-certs
</trusted-ca-certs>
<trusted-client-certs>
explicitly-trusted-client-certs
</trusted-client-certs>
<cert-maps>
<cert-to-name>
<id>1</id>
<fingerprint>11:0A:05:11:00</fingerprint>
<map-type>x509c2n:san-any</map-type>
</cert-to-name>
<cert-to-name>
<id>2</id>
<fingerprint>B3:4F:A1:8C:54</fingerprint>
<map-type>x509c2n:specified</map-type>
<name>scooby-doo</name>
</cert-to-name>
</cert-maps>
</client-auth>
</tls>
</endpoint> <restconf-server
</listen> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-server"
xmlns:x509c2n="urn:ietf:params:xml:ns:yang:ietf-x509-cert-to-name">
<!-- calling home to a RESTCONF client --> <!-- listening for TLS (HTTPS) connections -->
<call-home> <listen>
<restconf-client> <endpoint>
<name>config-manager</name> <name>netconf/tls</name>
<tls> <tls>
<endpoints> <address>11.22.33.44</address>
<endpoint> <certificates>
<name>east-data-center</name> <certificate>
<address>22.33.44.55</address> <name>tls-ec-cert</name>
</endpoint> </certificate>
<endpoint> </certificates>
<name>west-data-center</name> <client-auth>
<address>33.44.55.66</address> <trusted-ca-certs>deployment-specific-ca-certs</trusted-ca-certs>
</endpoint> <trusted-client-certs>explicitly-trusted-client-certs</trusted-client-certs>
</endpoints> <cert-maps>
<certificates> <cert-to-name>
<certificate>ex-key-sect571r1-cert</certificate> <id>1</id>
</certificates> <fingerprint>11:0A:05:11:00</fingerprint>
<client-auth> <map-type>x509c2n:san-any</map-type>
<trusted-ca-certs> </cert-to-name>
deployment-specific-ca-certs <cert-to-name>
</trusted-ca-certs> <id>2</id>
<trusted-client-certs> <fingerprint>B3:4F:A1:8C:54</fingerprint>
explicitly-trusted-client-certs <map-type>x509c2n:specified</map-type>
</trusted-client-certs> <name>scooby-doo</name>
<cert-maps> </cert-to-name>
<cert-to-name> </cert-maps>
<id>1</id> </client-auth>
<fingerprint>11:0A:05:11:00</fingerprint> </tls>
<map-type>x509c2n:san-any</map-type> </endpoint>
</cert-to-name> </listen>
<cert-to-name>
<id>2</id>
<fingerprint>B3:4F:A1:8C:54</fingerprint>
<map-type>x509c2n:specified</map-type>
<name>scooby-doo</name>
</cert-to-name> <!-- calling home to a RESTCONF client -->
</cert-maps> <call-home>
</client-auth> <restconf-client>
</tls> <name>config-manager</name>
<connection-type> <tls>
<periodic> <endpoints>
<idle-timeout>300</idle-timeout> <endpoint>
<reconnect-timeout>60</reconnect-timeout> <name>east-data-center</name>
</periodic> <address>22.33.44.55</address>
</connection-type> </endpoint>
<reconnect-strategy> <endpoint>
<start-with>last-connected</start-with> <name>west-data-center</name>
<max-attempts>3</max-attempts> <address>33.44.55.66</address>
</reconnect-strategy> </endpoint>
</restconf-client> </endpoints>
</call-home> <certificates>
<certificate>
<name>tls-ec-cert</name>
</certificate>
</certificates>
<client-auth>
<trusted-ca-certs>deployment-specific-ca-certs</trusted-ca-certs>
<trusted-client-certs>explicitly-trusted-client-certs</trusted-client-certs>
<cert-maps>
<cert-to-name>
<id>1</id>
<fingerprint>11:0A:05:11:00</fingerprint>
<map-type>x509c2n:san-any</map-type>
</cert-to-name>
<cert-to-name>
<id>2</id>
<fingerprint>B3:4F:A1:8C:54</fingerprint>
<map-type>x509c2n:specified</map-type>
<name>scooby-doo</name>
</cert-to-name>
</cert-maps>
</client-auth>
</tls>
<connection-type>
<periodic>
<idle-timeout>300</idle-timeout>
<reconnect-timeout>60</reconnect-timeout>
</periodic>
</connection-type>
<reconnect-strategy>
<start-with>last-connected</start-with>
<max-attempts>3</max-attempts>
</reconnect-strategy>
</restconf-client>
</call-home>
</restconf-server> </restconf-server>
3.3. YANG Model 3.3. YANG Model
This YANG module imports YANG types from [RFC6991] and [RFC7407]. This YANG module imports YANG types from [RFC6991] and [RFC7407].
<CODE BEGINS> file "ietf-restconf-server@2016-11-02.yang" <CODE BEGINS> file "ietf-restconf-server@2017-03-13.yang"
module ietf-restconf-server { module ietf-restconf-server {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server";
prefix "rcs"; prefix "rcs";
//import ietf-netconf-acm { //import ietf-netconf-acm {
// prefix nacm; // prefix nacm;
// reference // reference
// "RFC 6536: Network Configuration Protocol (NETCONF) // "RFC 6536: Network Configuration Protocol (NETCONF)
// Access Control Model"; // Access Control Model";
//} //}
import ietf-inet-types { import ietf-inet-types {
prefix inet; prefix inet;
reference reference
"RFC 6991: Common YANG Data Types"; "RFC 6991: Common YANG Data Types";
} }
import ietf-x509-cert-to-name { import ietf-x509-cert-to-name {
prefix x509c2n; prefix x509c2n;
reference reference
"RFC 7407: A YANG Data Model for SNMP Configuration"; "RFC 7407: A YANG Data Model for SNMP Configuration";
} }
import ietf-tls-server { import ietf-tls-server {
prefix ts; prefix ts;
revision-date 2016-11-02; // stable grouping definitions revision-date 2017-03-13; // stable grouping definitions
reference reference
"RFC ZZZZ: TLS Client and Server Models"; "RFC ZZZZ: TLS Client and Server Models";
} }
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netconf/> "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org> WG List: <mailto:netconf@ietf.org>
WG Chair: Mehmet Ersue WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com> <mailto:mehmet.ersue@nsn.com>
WG Chair: Mahesh Jethanandani WG Chair: Mahesh Jethanandani
<mailto:mjethanandani@gmail.com> <mailto:mjethanandani@gmail.com>
Editor: Kent Watsen Editor: Kent Watsen
<mailto:kwatsen@juniper.net>"; <mailto:kwatsen@juniper.net>";
description description
"This module contains a collection of YANG definitions for "This module contains a collection of YANG definitions for
configuring RESTCONF servers. configuring RESTCONF servers.
Copyright (c) 2014 IETF Trust and the persons identified as Copyright (c) 2014 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD to the license terms contained in, the Simplified BSD
License set forth in Section 4.c of the IETF Trust's License set forth in Section 4.c of the IETF Trust's
Legal Provisions Relating to IETF Documents Legal Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
revision "2016-11-02" { revision "2017-03-13" {
description description
"Initial version"; "Initial version";
reference reference
"RFC XXXX: RESTCONF Client and Server Models"; "RFC XXXX: RESTCONF Client and Server Models";
} }
// Features // Features
feature listen {
description
"The 'listen' feature indicates that the RESTCONF server
supports opening a port to accept RESTCONF client connections
using at least one transport (e.g., TLS, etc.).";
}
feature listen { feature tls-listen {
description description
"The 'listen' feature indicates that the RESTCONF server "The 'tls-listen' feature indicates that the RESTCONF server
supports opening a port to accept RESTCONF client connections supports opening a port to listen for incoming RESTCONF
using at least one transport (e.g., TLS, etc.)."; client connections.";
} reference
"RFC XXXX: RESTCONF Protocol";
}
feature tls-listen { feature call-home {
description description
"The 'tls-listen' feature indicates that the RESTCONF server "The 'call-home' feature indicates that the RESTCONF server
supports opening a port to listen for incoming RESTCONF supports initiating RESTCONF call home connections to REETCONF
client connections."; clients using at least one transport (e.g., TLS, etc.).";
reference reference
"RFC XXXX: RESTCONF Protocol"; "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
} }
feature call-home { feature tls-call-home {
description description
"The 'call-home' feature indicates that the RESTCONF server "The 'tls-call-home' feature indicates that the RESTCONF server
supports initiating RESTCONF call home connections to REETCONF supports initiating connections to RESTCONF clients.";
clients using at least one transport (e.g., TLS, etc.)."; reference
reference "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
"RFC YYYY: NETCONF Call Home and RESTCONF Call Home"; }
}
feature tls-call-home { feature client-cert-auth {
description description
"The 'tls-call-home' feature indicates that the RESTCONF server "The client-cert-auth feature indicates that the RESTCONF
supports initiating connections to RESTCONF clients."; server supports the ClientCertificate authentication scheme.";
reference reference
"RFC YYYY: NETCONF Call Home and RESTCONF Call Home"; "RFC ZZZZ: Client Authentication over New TLS Connection";
} }
feature client-cert-auth { // top-level container
description container restconf-server {
"The client-cert-auth feature indicates that the RESTCONF description
server supports the ClientCertificate authentication scheme."; "Top-level container for RESTCONF server configuration.";
reference
"RFC ZZZZ: Client Authentication over New TLS Connection";
}
// top-level container
container restconf-server {
description
"Top-level container for RESTCONF server configuration.";
container listen { container listen {
if-feature listen; if-feature listen;
description
"Configures listen behavior";
leaf max-sessions {
type uint16;
default 0; // should this be 'max'?
description description
"Configures listen behavior"; "Specifies the maximum number of concurrent sessions
leaf max-sessions { that can be active at one time. The value 0 indicates
type uint16; that no artificial session limit should be used.";
default 0; // should this be 'max'? }
list endpoint {
key name;
description
"List of endpoints to listen for RESTCONF connections.";
leaf name {
type string;
description description
"Specifies the maximum number of concurrent sessions "An arbitrary name for the RESTCONF listen endpoint.";
that can be active at one time. The value 0 indicates
that no artificial session limit should be used.";
} }
list endpoint { choice transport {
key name; mandatory true;
description description
"List of endpoints to listen for RESTCONF connections on."; "Selects between available transports.";
leaf name { case tls {
type string; if-feature tls-listen;
description container tls {
"An arbitrary name for the RESTCONF listen endpoint."; description
} "TLS-specific listening configuration for inbound
choice transport { connections.";
mandatory true; leaf address {
description type inet:ip-address;
"Selects between available transports.";
case tls {
if-feature tls-listen;
container tls {
description description
"TLS-specific listening configuration for inbound "The IP address of the interface to listen on. The
connections."; TLS server will listen on all interfaces if no value
uses ts:listening-tls-server-grouping { is specified. Please note that some addresses have
refine port { special meanings (e.g., '0.0.0.0' and '::').";
default 443; }
} leaf port {
augment "client-auth" { type inet:port-number;
description default 443;
"Augments in the cert-to-name structure."; description
uses cert-maps-grouping; "The local port number on this interface the TLS server
} listens on.";
}
uses ts:tls-server-grouping {
augment "client-auth" {
description
"Augments in the cert-to-name structure.";
uses cert-maps-grouping;
} }
} }
} }
} }
} }
} }
}
container call-home { container call-home {
if-feature call-home; if-feature call-home;
description
"Configures call-home behavior";
list restconf-client {
key name;
description description
"Configures call-home behavior"; "List of RESTCONF clients the RESTCONF server is to
list restconf-client { initiate call-home connections to.";
key name; leaf name {
type string;
description description
"List of RESTCONF clients the RESTCONF server is to "An arbitrary name for the remote RESTCONF client.";
initiate call-home connections to."; }
leaf name { choice transport {
type string; mandatory true;
description description
"An arbitrary name for the remote RESTCONF client."; "Selects between TLS and any transports augmented in.";
} case tls {
choice transport { if-feature tls-call-home;
mandatory true; container tls {
description description
"Selects between TLS and any transports augmented in."; "Specifies TLS-specific call-home transport
case tls { configuration.";
if-feature tls-call-home; uses endpoints-container {
container tls { refine endpoints/endpoint/port {
description default 4336;
"Specifies TLS-specific call-home transport
configuration.";
uses endpoints-container {
refine endpoints/endpoint/port {
default 4336;
}
} }
uses ts:non-listening-tls-server-grouping { }
augment "client-auth" { uses ts:tls-server-grouping {
description augment "client-auth" {
"Augments in the cert-to-name structure."; description
uses cert-maps-grouping; "Augments in the cert-to-name structure.";
} uses cert-maps-grouping;
} }
} }
} }
} }
container connection-type {
description
"Indicates the RESTCONF client's preference for how the
RESTCONF server's connection is maintained.";
choice connection-type {
description
"Selects between available connection types.";
case persistent-connection {
container persistent {
presence true;
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 container connection-type {
the expense of holding resources longer."; description
"Indicates the RESTCONF client's preference for how the
RESTCONF server's connection is maintained.";
choice connection-type {
description
"Selects between available connection types.";
case persistent-connection {
container persistent {
presence true;
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.
container keep-alives { This connection type minimizes any RESTCONF client
description to RESTCONF server data-transfer delay, albeit at
"Configures the keep-alive policy, to proactively the expense of holding resources longer.";
test the aliveness of the TLS client. An
unresponsive TLS client will be dropped after
approximately (max-attempts * max-wait)
seconds.";
reference
"RFC YYYY: NETCONF Call Home and RESTCONF Call
Home, Section 3.1, item S6";
leaf max-wait {
type uint16 {
range "1..max";
}
units seconds;
default 30;
description
"Sets the amount of time in seconds after which
if no data has been received from the TLS
client, a TLS-level message will be sent to
test the aliveness of the TLS client.";
}
leaf max-attempts {
type uint8;
default 3;
description
"Sets the maximum number of sequential keep-alive
messages that can fail to obtain a response from
the TLS client before assuming the TLS client is
no longer alive.";
}
}
}
} container keep-alives {
case periodic-connection {
container periodic {
presence true;
description description
"Periodically connect to the RESTCONF client, so that "Configures the keep-alive policy, to proactively
the RESTCONF client may deliver messages pending for test the aliveness of the TLS client. An
the RESTCONF server. The client must close the unresponsive TLS client will be dropped after
connection when it's ready to release it. Once the approximately (max-attempts * max-wait)
connection has been closed, the server will restart seconds.";
its timer until the next connection."; reference
leaf reconnect-timeout { "RFC 8071: NETCONF Call Home and RESTCONF Call
Home, Section 3.1, item S6";
leaf max-wait {
type uint16 { type uint16 {
range "1..max"; range "1..max";
} }
units minutes; units seconds;
default 60; default 30;
description description
"The maximum amount of unconnected time the "Sets the amount of time in seconds after which
RESTCONF server will wait before re-establishing if no data has been received from the TLS
a connection to the RESTCONF client. The client, a TLS-level message will be sent to
RESTCONF server may initiate a connection to test the aliveness of the TLS client.";
the RESTCONF client before this time if desired }
(e.g., to deliver a notification)."; leaf max-attempts {
type uint8;
default 3;
description
"Sets the maximum number of sequential keep-alive
messages that can fail to obtain a response from
the TLS client before assuming the TLS client is
no longer alive.";
} }
} }
} }
} }
} case periodic-connection {
container reconnect-strategy { container periodic {
description presence true;
"The reconnection strategy directs how a RESTCONF server description
reconnects to a RESTCONF client after after discovering "Periodically connect to the RESTCONF client, so that
its connection to the client has dropped, even if due to the RESTCONF client may deliver messages pending for
a reboot. The RESTCONF server starts with the specified the RESTCONF server. The client must close the
endpoint and tries to connect to it max-attempts times connection when it's ready to release it. Once the
before trying the next endpoint in the list (round connection has been closed, the server will restart
robin)."; its timer until the next connection.";
leaf start-with { leaf reconnect-timeout {
type enumeration { type uint16 {
enum first-listed { range "1..max";
description }
"Indicates that reconnections should start with units minutes;
the first endpoint listed."; default 60;
}
enum last-connected {
description description
"Indicates that reconnections should start with "The maximum amount of unconnected time the
the endpoint last connected to. If no previous RESTCONF server will wait before re-establishing
connection has ever been established, then the a connection to the RESTCONF client. The
first endpoint configured is used. RESTCONF RESTCONF server may initiate a connection to
servers SHOULD be able to remember the last the RESTCONF client before this time if desired
endpoint connected to across reboots."; (e.g., to deliver a notification).";
} }
} }
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.";
} }
leaf max-attempts { }
type uint8 { }
range "1..max"; container reconnect-strategy {
description
"The reconnection strategy directs how a RESTCONF server
reconnects to a RESTCONF client after after discovering
its connection to the client has dropped, even if due to
a reboot. The RESTCONF server starts with the specified
endpoint and tries to connect to it max-attempts times
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.";
} }
default 3; enum last-connected {
description description
"Specifies the number times the RESTCONF server tries to "Indicates that reconnections should start with
connect to a specific endpoint before moving on to the the endpoint last connected to. If no previous
next endpoint in the list (round robin)."; connection has ever been established, then the
first endpoint configured is used. RESTCONF
servers SHOULD be able to remember the last
endpoint connected to 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.";
}
leaf max-attempts {
type uint8 {
range "1..max";
} }
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 cert-maps-grouping { grouping cert-maps-grouping {
description
"A grouping that defines a container around the
cert-to-name structure defined in RFC 7407.";
container cert-maps {
uses x509c2n:cert-to-name;
description description
"A grouping that defines a container around the "The cert-maps container is used by a TLS-based RESTCONF
cert-to-name structure defined in RFC 7407."; server to map the RESTCONF client's presented X.509
container cert-maps { certificate to a RESTCONF username. If no matching and
uses x509c2n:cert-to-name; valid cert-to-name list entry can be found, then the
description RESTCONF server MUST close the connection, and MUST NOT
"The cert-maps container is used by a TLS-based RESTCONF accept RESTCONF messages over it.";
server to map the RESTCONF client's presented X.509
certificate to a RESTCONF username. If no matching and reference
valid cert-to-name list entry can be found, then the "RFC XXXX: The RESTCONF Protocol";
RESTCONF server MUST close the connection, and MUST NOT
accept RESTCONF messages over it.";
reference
"RFC XXXX: The RESTCONF Protocol";
}
} }
grouping endpoints-container { }
grouping endpoints-container {
description
"This grouping is used by tls container for call-home
configurations.";
container endpoints {
description description
"This grouping is used by tls container for call-home "Container for the list of endpoints.";
configurations."; list endpoint {
container endpoints { key name;
unique "address port";
min-elements 1;
ordered-by user;
description description
"Container for the list of endpoints."; "User-ordered list of endpoints for this RESTCONF client.
list endpoint { Defining more than one enables high-availability.";
key name; leaf name {
min-elements 1; type string;
ordered-by user;
description description
"User-ordered list of endpoints for this RESTCONF client. "An arbitrary name for this endpoint.";
Defining more than one enables high-availability."; }
leaf name { leaf address {
type string; type inet:host;
description mandatory true;
"An arbitrary name for this endpoint."; description
} "The IP address or hostname of the endpoint. If a
leaf address { hostname is configured and the DNS resolution results
type inet:host; in more than one IP address, the RESTCONF server
mandatory true; will process the IP addresses as if they had been
description explicitly configured in place of the hostname.";
"The IP address or hostname of the endpoint. If a }
hostname is configured and the DNS resolution results leaf port {
in more than one IP address, the RESTCONF server type inet:port-number;
will process the IP addresses as if they had been description
explicitly configured in place of the hostname."; "The IP port for this endpoint. The RESTCONF server will
} use the IANA-assigned well-known port if no value is
leaf port { specified.";
type inet:port-number;
description
"The IP port for this endpoint. The RESTCONF server will
use the IANA-assigned well-known port if no value is
specified.";
}
} }
} }
} }
} }
<CODE ENDS> }
<CODE ENDS>
4. Security Considerations 4. Security Considerations
The YANG module defined in this document uses a grouping defined in
[I-D.ietf-netconf-tls-client-server]. Please see the Security
Considerations section in that document for concerns related that
grouping.
The YANG module defined in this document is designed to be accessed
via YANG based management protocols, such as NETCONF [RFC6241] and
RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
implement secure transport layers (e.g., SSH, TLS) with mutual
authentication.
The NETCONF access control model (NACM) [RFC6536] provides the means
to restrict access for particular users to a pre-configured subset of
all available protocol operations and content.
There are a number of data nodes defined in this YANG module that are
writable/creatable/deletable (i.e., config true, which is the
default). These data nodes may be considered sensitive or vulnerable
in some network environments. Write operations (e.g., edit-config)
to these data nodes without proper protection can have a negative
effect on network operations. These are the subtrees and data nodes
and their sensitivity/vulnerability:
NONE
Some of the readable data nodes in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus
important to control read access (e.g., via get, get-config, or
notification) to these data nodes. These are the subtrees and data
nodes and their sensitivity/vulnerability:
NONE
Some of the RPC operations in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus
important to control access to these operations. These are the
operations and their sensitivity/vulnerability:
NONE
5. IANA Considerations 5. IANA Considerations
5.1. The IETF XML Registry 5.1. The IETF XML Registry
This document registers two URIs in the IETF XML registry [RFC2119]. This document registers two URIs in the IETF XML registry [RFC3688].
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-restconf-client URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client
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-restconf-server 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.
5.2. The YANG Module Names Registry 5.2. The YANG Module Names Registry
This document registers two YANG modules in the YANG Module Names This document registers two YANG modules in the YANG Module Names
registry [RFC6020]. Following the format in [RFC6020], the the registry [RFC7950]. Following the format in [RFC7950], the the
following registrations are requested: following registrations are requested:
name: ietf-restconf-client name: ietf-restconf-client
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client
prefix: ncc prefix: ncc
reference: RFC XXXX reference: RFC XXXX
name: ietf-restconf-server name: ietf-restconf-server
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server
prefix: ncs prefix: ncs
skipping to change at page 21, line 9 skipping to change at page 31, line 9
and Bert Wijnen. 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.
7. References 7. References
7.1. Normative References 7.1. Normative References
[draft-ietf-netconf-keystore] [I-D.ietf-netconf-keystore]
Watsen, K., "Keystore Model", draft-ieft-netconf- Watsen, K. and G. Wu, "Keystore Model", draft-ietf-
keystore-00 (work in progress), 2016, netconf-keystore-00 (work in progress), October 2016.
<https://datatracker.ietf.org/html/draft-ieft-netconf-
keystore>.
[draft-ietf-netconf-restconf]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", draft-ieft-netconf-restconf-13 (work in
progress), 2016, <https://datatracker.ietf.org/html/draft-
ieft-netconf-restconf>.
[draft-ietf-netconf-tls-client-server] [I-D.ietf-netconf-tls-client-server]
Watsen, K., "TLS Client and Server Models", draft-ieft- Watsen, K., "TLS Client and Server Models", draft-ietf-
netconf-tls-client-server-00 (work in progress), 2016, netconf-tls-client-server-01 (work in progress), November
<https://datatracker.ietf.org/html/draft-ieft-netconf-tls- 2016.
client-server>.
[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, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
the Network Configuration Protocol (NETCONF)", RFC 6020, Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6020, October 2010, DOI 10.17487/RFC6536, March 2012,
<http://www.rfc-editor.org/info/rfc6020>. <http://www.rfc-editor.org/info/rfc6536>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013, RFC 6991, DOI 10.17487/RFC6991, July 2013,
<http://www.rfc-editor.org/info/rfc6991>. <http://www.rfc-editor.org/info/rfc6991>.
[RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for
SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407,
December 2014, <http://www.rfc-editor.org/info/rfc7407>. December 2014, <http://www.rfc-editor.org/info/rfc7407>.
7.2. Informative References [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<http://www.rfc-editor.org/info/rfc7950>.
[draft-ietf-netconf-call-home] 7.2. Informative References
Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
draft-ieft-netconf-call-home-17 (work in progress), 2015,
<https://datatracker.ietf.org/html/draft-ieft-netconf-
call-home-17>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004, DOI 10.17487/RFC3688, January 2004,
<http://www.rfc-editor.org/info/rfc3688>. <http://www.rfc-editor.org/info/rfc3688>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, (TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008, DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>. <http://www.rfc-editor.org/info/rfc5246>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<http://www.rfc-editor.org/info/rfc6241>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<http://www.rfc-editor.org/info/rfc8040>.
[RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
RFC 8071, DOI 10.17487/RFC8071, February 2017,
<http://www.rfc-editor.org/info/rfc8071>.
Appendix A. Change Log Appendix A. Change Log
A.1. server-model-09 to 00 A.1. server-model-09 to 00
o This draft was split out from draft-ietf-netconf-server-model-09. o This draft was split out from draft-ietf-netconf-server-model-09.
o Added in new features 'listen' and 'call-home' so future o Added in new features 'listen' and 'call-home' so future
transports can be augmented in. transports can be augmented in.
A.2. 00 to 01
o Renamed "keychain" to "keystore".
A.3. 01 to 02
o Filled in previously missing 'ietf-restconf-client' module.
o Updated the ietf-restconf-server module to accomodate new grouping
'ietf-tls-server-grouping'.
Appendix B. Open Issues Appendix B. Open Issues
Please see: https://github.com/netconf-wg/restconf-client-server/ Please see: https://github.com/netconf-wg/restconf-client-server/
issues. issues.
Authors' Addresses Authors' Addresses
Kent Watsen Kent Watsen
Juniper Networks Juniper Networks
 End of changes. 115 change blocks. 
649 lines changed or deleted 1095 lines changed or added

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