685 lines
25 KiB
YANG
685 lines
25 KiB
YANG
module ietf-netconf-server {
|
|
yang-version 1.1;
|
|
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server";
|
|
prefix ncs;
|
|
|
|
import ietf-yang-types {
|
|
prefix yang;
|
|
reference
|
|
"RFC 6991: Common YANG Data Types";
|
|
}
|
|
|
|
import ietf-x509-cert-to-name {
|
|
prefix x509c2n;
|
|
reference
|
|
"RFC 7407: A YANG Data Model for SNMP Configuration";
|
|
}
|
|
|
|
import ietf-tcp-client {
|
|
prefix tcpc;
|
|
reference
|
|
"RFC DDDD: YANG Groupings for TCP Clients and TCP Servers";
|
|
}
|
|
|
|
import ietf-tcp-server {
|
|
prefix tcps;
|
|
reference
|
|
"RFC DDDD: YANG Groupings for TCP Clients and TCP Servers";
|
|
}
|
|
|
|
import ietf-ssh-common {
|
|
prefix sshcmn;
|
|
reference
|
|
"RFC EEEE: YANG Groupings for SSH Clients and SSH Servers";
|
|
}
|
|
|
|
import ietf-ssh-server {
|
|
prefix sshs;
|
|
reference
|
|
"RFC EEEE: YANG Groupings for SSH Clients and SSH Servers";
|
|
}
|
|
|
|
import ietf-tls-server {
|
|
prefix tlss;
|
|
reference
|
|
"RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
|
|
}
|
|
|
|
organization
|
|
"IETF NETCONF (Network Configuration) Working Group";
|
|
|
|
contact
|
|
"WG Web: https://datatracker.ietf.org/wg/netconf
|
|
WG List: NETCONF WG list <mailto:netconf@ietf.org>
|
|
Author: Kent Watsen <mailto:kent+ietf@watsen.net>";
|
|
|
|
description
|
|
"This module contains a collection of YANG definitions
|
|
for configuring NETCONF servers.
|
|
|
|
Copyright (c) 2023 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 Revised
|
|
BSD License set forth in Section 4.c of the IETF Trust's
|
|
Legal Provisions Relating to IETF Documents
|
|
(https://trustee.ietf.org/license-info).
|
|
|
|
This version of this YANG module is part of RFC HHHH
|
|
(https://www.rfc-editor.org/info/rfcHHHH); see the RFC
|
|
itself for full legal notices.
|
|
|
|
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
|
|
'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
|
|
'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
|
|
are to be interpreted as described in BCP 14 (RFC 2119)
|
|
(RFC 8174) when, and only when, they appear in all
|
|
capitals, as shown here.";
|
|
|
|
revision 2023-12-28 {
|
|
description
|
|
"Initial version";
|
|
reference
|
|
"RFC HHHH: NETCONF Client and Server Models";
|
|
}
|
|
|
|
// Features
|
|
|
|
feature ssh-listen {
|
|
description
|
|
"The 'ssh-listen' feature indicates that the NETCONF server
|
|
supports opening a port to accept NETCONF over SSH
|
|
client connections.";
|
|
reference
|
|
"RFC 6242:
|
|
Using the NETCONF Protocol over Secure Shell (SSH)";
|
|
}
|
|
|
|
feature tls-listen {
|
|
description
|
|
"The 'tls-listen' feature indicates that the NETCONF server
|
|
supports opening a port to accept NETCONF over TLS
|
|
client connections.";
|
|
reference
|
|
"RFC 7589: Using the NETCONF Protocol over Transport
|
|
Layer Security (TLS) with Mutual X.509
|
|
Authentication";
|
|
}
|
|
|
|
feature ssh-call-home {
|
|
description
|
|
"The 'ssh-call-home' feature indicates that the NETCONF
|
|
server supports initiating a NETCONF over SSH call
|
|
home connection to NETCONF clients.";
|
|
reference
|
|
"RFC 8071: NETCONF Call Home and RESTCONF Call Home";
|
|
}
|
|
|
|
feature tls-call-home {
|
|
description
|
|
"The 'tls-call-home' feature indicates that the NETCONF
|
|
server supports initiating a NETCONF over TLS call
|
|
home connection to NETCONF clients.";
|
|
reference
|
|
"RFC 8071: NETCONF Call Home and RESTCONF Call Home";
|
|
}
|
|
|
|
feature central-netconf-server-supported {
|
|
description
|
|
"The 'central-netconf-server-supported' feature indicates
|
|
that the server supports the top-level 'netconf-server'
|
|
node.
|
|
|
|
This feature is needed as some servers may want to use
|
|
features defined in this module, which requires this
|
|
module to be implemented, without having to support
|
|
the top-level 'netconf-server' node.";
|
|
}
|
|
|
|
// Groupings
|
|
|
|
grouping netconf-server-grouping {
|
|
description
|
|
"A reusable grouping for configuring a NETCONF server
|
|
without any consideration for how underlying transport
|
|
sessions are established.
|
|
|
|
Note that this grouping uses a fairly typical descendant
|
|
node name such that a stack of 'uses' statements will
|
|
have name conflicts. It is intended that the consuming
|
|
data model will resolve the issue by wrapping the 'uses'
|
|
statement in a container called, e.g.,
|
|
'netconf-server-parameters'. This model purposely does
|
|
not do this itself so as to provide maximum flexibility
|
|
to consuming models.";
|
|
|
|
container client-identity-mappings {
|
|
description
|
|
"Specifies mappings through which NETCONF client X.509
|
|
certificates are used to determine a NETCONF username,
|
|
per RFC 7407.
|
|
|
|
For TLS-based transports, 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, per Section 7 in RFC 7589.
|
|
|
|
For SSH-based transports, a matching cert-to-name
|
|
entry overrides the username provided by the SSH
|
|
implementation, consistent with the second paragraph
|
|
of Section 3 in RFC 6242.";
|
|
reference
|
|
"RFC 6242:
|
|
Using the NETCONF Protocol over Secure Shell (SSH)
|
|
RFC 7589:
|
|
Using the NETCONF Protocol over Transport Layer
|
|
Security (TLS) with Mutual X.509 Authentication";
|
|
uses x509c2n:cert-to-name {
|
|
refine "cert-to-name/fingerprint" {
|
|
mandatory false;
|
|
description
|
|
"A 'fingerprint' value does not need to be specified
|
|
when the 'cert-to-name' mapping is independent of
|
|
fingerprint matching. A 'cert-to-name' having no
|
|
fingerprint value will match any client certificate
|
|
and therefore should only be present at the end of
|
|
the user-ordered 'cert-to-name' list.";
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
grouping netconf-server-listen-stack-grouping {
|
|
description
|
|
"A reusable grouping for configuring a NETCONF server
|
|
'listen' protocol stack for listening on a single port.";
|
|
choice transport {
|
|
mandatory true;
|
|
description
|
|
"Selects between available transports.";
|
|
case ssh {
|
|
if-feature "ssh-listen";
|
|
container ssh {
|
|
description
|
|
"TCP, SSH, and NETCONF configuration to listen
|
|
for NETCONF over SSH connections.";
|
|
container tcp-server-parameters {
|
|
description
|
|
"TCP-level server parameters to listen
|
|
for NETCONF over SSH connections.";
|
|
uses tcps:tcp-server-grouping {
|
|
refine "local-port" {
|
|
default "830";
|
|
description
|
|
"The NETCONF server will listen on the
|
|
IANA-assigned well-known port value
|
|
for 'netconf-ssh' (830) if no value
|
|
is specified.";
|
|
}
|
|
}
|
|
}
|
|
container ssh-server-parameters {
|
|
description
|
|
"SSH-level server parameters to listen
|
|
for NETCONF over SSH connections.";
|
|
uses sshs:ssh-server-grouping;
|
|
}
|
|
container netconf-server-parameters {
|
|
description
|
|
"NETCONF-level server parameters to listen
|
|
for NETCONF over SSH connections.";
|
|
uses ncs:netconf-server-grouping {
|
|
refine "client-identity-mappings" {
|
|
if-feature "sshcmn:ssh-x509-certs";
|
|
description
|
|
"Adds in an 'if-feature' statement
|
|
ensuring the 'client-identity-mappings'
|
|
descendant is enabled only when SSH
|
|
supports X.509 certificates.";
|
|
}
|
|
augment "client-identity-mappings" {
|
|
description
|
|
"Adds a flag indicating if a cert-to-name
|
|
is required.";
|
|
leaf mapping-required {
|
|
type boolean;
|
|
description
|
|
"Indicates that the cert-to-name mapping
|
|
is required (i.e., the SSH-level username
|
|
is ignored).";
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
case tls {
|
|
if-feature "tls-listen";
|
|
container tls {
|
|
description
|
|
"TCP, TLS, and NETCONF configuration to listen
|
|
for NETCONF over TLS connections.";
|
|
container tcp-server-parameters {
|
|
description
|
|
"TCP-level server parameters to listen
|
|
for NETCONF over TLS connections.";
|
|
uses tcps:tcp-server-grouping {
|
|
refine "local-port" {
|
|
default "6513";
|
|
description
|
|
"The NETCONF server will listen on the
|
|
IANA-assigned well-known port value
|
|
for 'netconf-tls' (6513) if no value
|
|
is specified.";
|
|
}
|
|
}
|
|
}
|
|
container tls-server-parameters {
|
|
description
|
|
"TLS-level server parameters to listen
|
|
for NETCONF over TLS connections.";
|
|
uses tlss:tls-server-grouping {
|
|
refine "client-authentication" {
|
|
must 'ca-certs or ee-certs';
|
|
description
|
|
"NETCONF/TLS servers MUST validate client
|
|
certificates. This configures certificates
|
|
at the socket-level (i.e. bags). More
|
|
discriminating client-certificate checks
|
|
SHOULD be implemented by the application.";
|
|
reference
|
|
"RFC 7589:
|
|
Using the NETCONF Protocol over Transport Layer
|
|
Security (TLS) with Mutual X.509 Authentication";
|
|
}
|
|
}
|
|
}
|
|
container netconf-server-parameters {
|
|
description
|
|
"NETCONF-level server parameters to listen
|
|
for NETCONF over TLS connections.";
|
|
uses ncs:netconf-server-grouping {
|
|
refine "client-identity-mappings/cert-to-name" {
|
|
min-elements 1;
|
|
description
|
|
"The TLS transport requires a mapping.";
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
grouping netconf-server-callhome-stack-grouping {
|
|
description
|
|
"A reusable grouping for configuring a NETCONF server
|
|
'call-home' protocol stack, for a single outbound
|
|
connection.";
|
|
choice transport {
|
|
mandatory true;
|
|
description
|
|
"Selects between available transports.";
|
|
case ssh {
|
|
if-feature "ssh-call-home";
|
|
container ssh {
|
|
description
|
|
"TCP, SSH, and NETCONF configuration to initiate
|
|
a NETCONF over SSH Call Home connection.";
|
|
container tcp-client-parameters {
|
|
description
|
|
"TCP-level client parameters to initiate a
|
|
NETCONF over SSH Call Home connection.";
|
|
uses tcpc:tcp-client-grouping {
|
|
refine "remote-port" {
|
|
default "4334";
|
|
description
|
|
"The NETCONF server will attempt to connect
|
|
to the IANA-assigned well-known port for
|
|
'netconf-ch-ssh' (4334) if no value is
|
|
specified.";
|
|
}
|
|
}
|
|
}
|
|
container ssh-server-parameters {
|
|
description
|
|
"SSH-level server parameters to initiate a
|
|
NETCONF over SSH Call Home connection.";
|
|
uses sshs:ssh-server-grouping;
|
|
}
|
|
container netconf-server-parameters {
|
|
description
|
|
"NETCONF-level server parameters to initiate a
|
|
NETCONF over SSH Call Home connection.";
|
|
uses ncs:netconf-server-grouping {
|
|
refine "client-identity-mappings" {
|
|
if-feature "sshcmn:ssh-x509-certs";
|
|
description
|
|
"Adds in an 'if-feature' statement
|
|
ensuring the 'client-identity-mappings'
|
|
descendant is enabled only when SSH
|
|
supports X.509 certificates.";
|
|
}
|
|
augment "client-identity-mappings" {
|
|
description
|
|
"Adds a flag indicating if a cert-to-name
|
|
is required.";
|
|
leaf mapping-required {
|
|
type boolean;
|
|
description
|
|
"Indicates that the cert-to-name mapping
|
|
is required (i.e., the SSH-level username
|
|
is ignored).";
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
case tls {
|
|
if-feature "tls-call-home";
|
|
container tls {
|
|
description
|
|
"TCP, TLS, and NETCONF configuration to initiate
|
|
a NETCONF over TLS Call Home connection.";
|
|
container tcp-client-parameters {
|
|
description
|
|
"TCP-level client parameters to initiate a
|
|
NETCONF over TLS Call Home connection.";
|
|
uses tcpc:tcp-client-grouping {
|
|
refine "remote-port" {
|
|
default "4335";
|
|
description
|
|
"The NETCONF server will attempt to connect
|
|
to the IANA-assigned well-known port for
|
|
'netconf-ch-tls' (4335) if no value is
|
|
specified.";
|
|
}
|
|
}
|
|
}
|
|
container tls-server-parameters {
|
|
description
|
|
"TLS-level server parameters to initiate a
|
|
NETCONF over TLS Call Home connection.";
|
|
uses tlss:tls-server-grouping {
|
|
refine "client-authentication" {
|
|
must 'ca-certs or ee-certs';
|
|
description
|
|
"NETCONF/TLS servers MUST validate client
|
|
certificates. This configures certificates
|
|
at the socket-level (i.e. bags). More
|
|
discriminating client-certificate checks
|
|
SHOULD be implemented by the application.";
|
|
reference
|
|
"RFC 7589:
|
|
Using the NETCONF Protocol over Transport Layer
|
|
Security (TLS) with Mutual X.509 Authentication";
|
|
}
|
|
}
|
|
}
|
|
container netconf-server-parameters {
|
|
description
|
|
"NETCONF-level server parameters to initiate a
|
|
NETCONF over TLS Call Home connection.";
|
|
uses ncs:netconf-server-grouping {
|
|
refine "client-identity-mappings/cert-to-name" {
|
|
min-elements 1;
|
|
description
|
|
"The TLS transport requires a mapping.";
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
grouping netconf-server-app-grouping {
|
|
description
|
|
"A reusable grouping for configuring a NETCONF server
|
|
application that supports both 'listen' and 'call-home'
|
|
protocol stacks for a multiplicity of connections.";
|
|
container listen {
|
|
if-feature "ssh-listen or tls-listen";
|
|
presence
|
|
"Indicates that server-listening ports have been configured.
|
|
This statement is present so the mandatory descendant
|
|
nodes do not imply that this node must be configured.";
|
|
description
|
|
"Configures listen behavior";
|
|
leaf idle-timeout {
|
|
type uint16;
|
|
units "seconds";
|
|
default "180"; // three minutes
|
|
description
|
|
"Specifies the maximum number of seconds that a NETCONF
|
|
session may remain idle. A NETCONF 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.";
|
|
}
|
|
container endpoints {
|
|
description
|
|
"Container for a list of endpoints.";
|
|
list endpoint {
|
|
key "name";
|
|
min-elements 1;
|
|
description
|
|
"List of endpoints to listen for NETCONF connections.";
|
|
leaf name {
|
|
type string;
|
|
description
|
|
"An arbitrary name for the NETCONF listen endpoint.";
|
|
}
|
|
uses netconf-server-listen-stack-grouping;
|
|
}
|
|
}
|
|
}
|
|
container call-home {
|
|
if-feature "ssh-call-home or tls-call-home";
|
|
presence
|
|
"Indicates that server-initiated call home connections have
|
|
been configured. This statement is present so the mandatory
|
|
descendant nodes do not imply that this node must be
|
|
configured.";
|
|
description
|
|
"Configures the NETCONF server to initiate the underlying
|
|
transport connection to NETCONF clients.";
|
|
list netconf-client {
|
|
key "name";
|
|
min-elements 1;
|
|
description
|
|
"List of NETCONF clients the NETCONF server is to
|
|
maintain simultaneous call-home connections with.";
|
|
leaf name {
|
|
type string;
|
|
description
|
|
"An arbitrary name for the remote NETCONF client.";
|
|
}
|
|
container endpoints {
|
|
description
|
|
"Container for the list of endpoints.";
|
|
list endpoint {
|
|
key "name";
|
|
min-elements 1;
|
|
ordered-by user;
|
|
description
|
|
"A non-empty user-ordered list of endpoints for this
|
|
NETCONF server to try to connect to in sequence.
|
|
Defining more than one enables high-availability.";
|
|
leaf name {
|
|
type string;
|
|
description
|
|
"An arbitrary name for this endpoint.";
|
|
}
|
|
uses netconf-server-callhome-stack-grouping;
|
|
}
|
|
}
|
|
container connection-type {
|
|
description
|
|
"Indicates the NETCONF server's preference for how the
|
|
NETCONF connection is maintained.";
|
|
choice connection-type {
|
|
mandatory true;
|
|
description
|
|
"Selects between available connection types.";
|
|
case persistent-connection {
|
|
container persistent {
|
|
presence
|
|
"Indicates that a persistent connection is to be
|
|
maintained.";
|
|
description
|
|
"Maintain a persistent connection to the NETCONF
|
|
client. If the connection goes down, immediately
|
|
start trying to reconnect to the NETCONF client,
|
|
using the reconnection strategy.
|
|
|
|
This connection type minimizes any NETCONF client
|
|
to NETCONF server data-transfer delay, albeit at
|
|
the expense of holding resources longer.";
|
|
}
|
|
}
|
|
case periodic-connection {
|
|
container periodic {
|
|
presence "Indicates that a periodic connection is
|
|
to be maintained.";
|
|
description
|
|
"Periodically connect to the NETCONF client.
|
|
|
|
This connection type decreases resource
|
|
utilization, albeit with increased delay in
|
|
NETCONF client to NETCONF server interactions.
|
|
|
|
The NETCONF client SHOULD gracefully close the
|
|
connection using <close-session> upon completing
|
|
planned activities. If the NETCONF session is
|
|
not closed gracefully, the NETCONF server MUST
|
|
immediately attempt to reestablish the connection.
|
|
|
|
Connections are established at the same start
|
|
time regardless how long the previous connection
|
|
stayed open.
|
|
|
|
In the case that the previous connection is still
|
|
active (i.e., the NETCONF client has not closed
|
|
it yet), establishing a new connection is NOT
|
|
RECOMMENDED.";
|
|
leaf period {
|
|
type uint16;
|
|
units "minutes";
|
|
default "60";
|
|
description
|
|
"Duration of time between periodic connections.";
|
|
}
|
|
leaf anchor-time {
|
|
type yang:date-and-time {
|
|
// constrained to minute-level granularity
|
|
pattern '[0-9]{4}-(1[0-2]|0[1-9])-(0[1-9]|[1-2]'
|
|
+ '[0-9]|3[0-1])T(0[0-9]|1[0-9]|2[0-3]):['
|
|
+ '0-5][0-9]:00(Z|[\+\-]((1[0-3]|0[0-9]):'
|
|
+ '([0-5][0-9])|14:00))?';
|
|
}
|
|
description
|
|
"Designates a timestamp before or after which a
|
|
series of periodic connections are determined.
|
|
The periodic connections occur at a whole
|
|
multiple interval from the anchor time.
|
|
|
|
If an 'anchor-time' is not provided, then the
|
|
server may implicitly set it to the time when
|
|
this configuraton is applied (e.g., on boot).
|
|
|
|
For example, for an anchor time is 15 minutes
|
|
past midnight and a period interval of 24 hours,
|
|
then a periodic connection will occur 15 minutes
|
|
past midnight everyday.";
|
|
}
|
|
leaf idle-timeout {
|
|
type uint16;
|
|
units "seconds";
|
|
default "180"; // three minutes
|
|
description
|
|
"Specifies the maximum number of seconds that
|
|
a NETCONF session may remain idle. A NETCONF
|
|
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.";
|
|
}
|
|
}
|
|
} // case periodic-connection
|
|
} // choice connection-type
|
|
} // container connection-type
|
|
container reconnect-strategy {
|
|
description
|
|
"The reconnection strategy directs how a NETCONF server
|
|
reconnects to a NETCONF client, after discovering its
|
|
connection to the client has dropped, even if due to a
|
|
reboot. The NETCONF 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.";
|
|
}
|
|
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. NETCONF
|
|
servers SHOULD be able to remember the last
|
|
endpoint connected to across reboots.";
|
|
}
|
|
enum random-selection {
|
|
description
|
|
"Indicates that reconnections should start with
|
|
a random endpoint.";
|
|
}
|
|
}
|
|
default "first-listed";
|
|
description
|
|
"Specifies which of the NETCONF client's endpoints
|
|
the NETCONF server should start with when trying
|
|
to connect to the NETCONF client.";
|
|
}
|
|
leaf max-wait {
|
|
type uint16 {
|
|
range "1..max";
|
|
}
|
|
units "seconds";
|
|
default "5";
|
|
description
|
|
"Specifies the amount of time in seconds after which,
|
|
if the connection is not established, an endpoint
|
|
connection attempt is considered unsuccessful.";
|
|
}
|
|
leaf max-attempts {
|
|
type uint8 {
|
|
range "1..max";
|
|
}
|
|
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).";
|
|
}
|
|
} // container reconnect-strategy
|
|
} // list netconf-client
|
|
} // container call-home
|
|
} // grouping netconf-server-app-grouping
|
|
|
|
// Protocol accessible node for servers that implement this module.
|
|
container netconf-server {
|
|
if-feature central-netconf-server-supported;
|
|
uses netconf-server-app-grouping;
|
|
description
|
|
"Top-level container for NETCONF server configuration.";
|
|
}
|
|
}
|