protocol/netconf-server/src/main/yang/ietf-netconf-server@2024-02-08.yang

   1 module ietf-netconf-server {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server";
   4   prefix ncs;
   5
   6   import ietf-yang-types {
   7     prefix yang;
   8     reference
   9       "RFC 6991: Common YANG Data Types";
  10   }
  11
  12   import ietf-x509-cert-to-name {
  13     prefix x509c2n;
  14     reference
  15       "RFC 7407: A YANG Data Model for SNMP Configuration";
  16   }
  17
  18   import ietf-tcp-client {
  19     prefix tcpc;
  20     reference
  21       "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers";
  22   }
  23
  24   import ietf-tcp-server {
  25     prefix tcps;
  26     reference
  27       "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers";
  28   }
  29
  30   import ietf-ssh-common {
  31     prefix sshcmn;
  32     reference
  33       "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers";
  34   }
  35
  36   import ietf-ssh-server {
  37     prefix sshs;
  38     reference
  39       "RFC EEEE: YANG Groupings for SSH Clients and SSH Servers";
  40   }
  41
  42   import ietf-tls-server {
  43     prefix tlss;
  44     reference
  45       "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
  46   }
  47
  48   organization
  49     "IETF NETCONF (Network Configuration) Working Group";
  50
  51   contact
  52     "WG Web:   https://datatracker.ietf.org/wg/netconf
  53      WG List:  NETCONF WG list <mailto:netconf@ietf.org>
  54      Author:   Kent Watsen <mailto:kent+ietf@watsen.net>";
  55
  56   description
  57     "This module contains a collection of YANG definitions
  58      for configuring NETCONF servers.
  59
  60      Copyright (c) 2024 IETF Trust and the persons identified
  61      as authors of the code. All rights reserved.
  62
  63      Redistribution and use in source and binary forms, with
  64      or without modification, is permitted pursuant to, and
  65      subject to the license terms contained in, the Revised
  66      BSD License set forth in Section 4.c of the IETF Trust's
  67      Legal Provisions Relating to IETF Documents
  68      (https://trustee.ietf.org/license-info).
  69
  70      This version of this YANG module is part of RFC HHHH
  71      (https://www.rfc-editor.org/info/rfcHHHH); see the RFC
  72      itself for full legal notices.
  73
  74      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
  75      'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
  76      'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
  77      are to be interpreted as described in BCP 14 (RFC 2119)
  78      (RFC 8174) when, and only when, they appear in all
  79      capitals, as shown here.";
  80
  81   revision 2024-02-08 {
  82     description
  83       "Initial version";
  84     reference
  85       "RFC HHHH: NETCONF Client and Server Models";
  86   }
  87
  88   // Features
  89
  90   feature ssh-listen {
  91     description
  92       "The 'ssh-listen' feature indicates that the NETCONF server
  93        supports opening a port to accept NETCONF over SSH
  94        client connections.";
  95     reference
  96       "RFC 6242:
  97          Using the NETCONF Protocol over Secure Shell (SSH)";
  98   }
  99
 100   feature tls-listen {
 101     description
 102       "The 'tls-listen' feature indicates that the NETCONF server
 103        supports opening a port to accept NETCONF over TLS
 104        client connections.";
 105     reference
 106       "RFC 7589: Using the NETCONF Protocol over Transport
 107                  Layer Security (TLS) with Mutual X.509
 108                  Authentication";
 109   }
 110
 111   feature ssh-call-home {
 112     description
 113       "The 'ssh-call-home' feature indicates that the NETCONF
 114        server supports initiating a NETCONF over SSH call
 115        home connection to NETCONF clients.";
 116     reference
 117       "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
 118   }
 119
 120   feature tls-call-home {
 121     description
 122       "The 'tls-call-home' feature indicates that the NETCONF
 123        server supports initiating a NETCONF over TLS call
 124        home connection to NETCONF clients.";
 125     reference
 126       "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
 127   }
 128
 129   feature central-netconf-server-supported {
 130     description
 131       "The 'central-netconf-server-supported' feature indicates
 132        that the server supports the top-level 'netconf-server'
 133        node.
 134
 135        This feature is needed as some servers may want to use
 136        features defined in this module, which requires this
 137        module to be implemented, without having to support
 138        the top-level 'netconf-server' node.";
 139   }
 140
 141   // Groupings
 142
 143   grouping netconf-server-grouping {
 144     description
 145       "A reusable grouping for configuring a NETCONF server
 146        without any consideration for how underlying transport
 147        sessions are established.
 148
 149        Note that this grouping uses a fairly typical descendant
 150        node name such that a stack of 'uses' statements will
 151        have name conflicts.  It is intended that the consuming
 152        data model will resolve the issue by wrapping the 'uses'
 153        statement in a container called, e.g.,
 154        'netconf-server-parameters'.  This model purposely does
 155        not do this itself so as to provide maximum flexibility
 156        to consuming models.";
 157
 158     container client-identity-mappings {
 159       description
 160         "Specifies mappings through which NETCONF client X.509
 161          certificates are used to determine a NETCONF username,
 162          per RFC 7407.
 163
 164          For TLS-based transports, if no matching and valid
 165          cert-to-name list entry can be found, then the NETCONF
 166          server MUST close the connection, and MUST NOT accept
 167          NETCONF messages over it, per Section 7 in RFC 7589.
 168
 169          For SSH-based transports, a matching cert-to-name
 170          entry overrides the username provided by the SSH
 171          implementation, consistent with the second paragraph
 172          of Section 3 in RFC 6242.";
 173       reference
 174         "RFC 6242:
 175            Using the NETCONF Protocol over Secure Shell (SSH)
 176          RFC 7589:
 177            Using the NETCONF Protocol over Transport Layer
 178            Security (TLS) with Mutual X.509 Authentication";
 179       uses x509c2n:cert-to-name {
 180         refine "cert-to-name/fingerprint" {
 181           mandatory false;
 182           description
 183             "A 'fingerprint' value does not need to be specified
 184              when the 'cert-to-name' mapping is independent of
 185              fingerprint matching.  A 'cert-to-name' having no
 186              fingerprint value will match any client certificate
 187              and therefore should only be present at the end of
 188              the user-ordered 'cert-to-name' list.";
 189         }
 190       }
 191     }
 192   }
 193
 194   grouping netconf-server-listen-stack-grouping {
 195     description
 196       "A reusable grouping for configuring a NETCONF server
 197        'listen' protocol stack for listening on a single port.";
 198     choice transport {
 199       mandatory true;
 200       description
 201         "Selects between available transports.";
 202       case ssh {
 203         if-feature "ssh-listen";
 204         container ssh {
 205           description
 206             "TCP, SSH, and NETCONF configuration to listen
 207              for NETCONF over SSH connections.";
 208           container tcp-server-parameters {
 209             description
 210               "TCP-level server parameters to listen
 211                for NETCONF over SSH connections.";
 212             uses tcps:tcp-server-grouping {
 213               refine "local-port" {
 214                 default "830";
 215                 description
 216                   "The NETCONF server will listen on the
 217                    IANA-assigned well-known port value
 218                    for 'netconf-ssh' (830) if no value
 219                    is specified.";
 220               }
 221             }
 222           }
 223           container ssh-server-parameters {
 224             description
 225               "SSH-level server parameters to listen
 226                for NETCONF over SSH connections.";
 227             uses sshs:ssh-server-grouping;
 228           }
 229           container netconf-server-parameters {
 230             description
 231               "NETCONF-level server parameters to listen
 232                for NETCONF over SSH connections.";
 233             uses ncs:netconf-server-grouping {
 234               refine "client-identity-mappings" {
 235                 if-feature "sshcmn:ssh-x509-certs";
 236                 description
 237                   "Adds in an 'if-feature' statement
 238                    ensuring the 'client-identity-mappings'
 239                    descendant is enabled only when SSH
 240                    supports X.509 certificates.";
 241               }
 242               augment "client-identity-mappings" {
 243                 description
 244                   "Adds a flag indicating if a cert-to-name
 245                    is required.";
 246                 leaf mapping-required {
 247                   type boolean;
 248                   description
 249                     "Indicates that the cert-to-name mapping
 250                      is required (i.e., the SSH-level username
 251                      is ignored).";
 252                 }
 253               }
 254             }
 255           }
 256         }
 257       }
 258       case tls {
 259         if-feature "tls-listen";
 260         container tls {
 261           description
 262             "TCP, TLS, and NETCONF configuration to listen
 263              for NETCONF over TLS connections.";
 264           container tcp-server-parameters {
 265             description
 266               "TCP-level server parameters to listen
 267                for NETCONF over TLS connections.";
 268             uses tcps:tcp-server-grouping {
 269               refine "local-port" {
 270                 default "6513";
 271                 description
 272                   "The NETCONF server will listen on the
 273                    IANA-assigned well-known port value
 274                    for 'netconf-tls' (6513) if no value
 275                    is specified.";
 276               }
 277             }
 278           }
 279           container tls-server-parameters {
 280             description
 281               "TLS-level server parameters to listen
 282                for NETCONF over TLS connections.";
 283             uses tlss:tls-server-grouping {
 284               refine "client-authentication" {
 285                 must 'ca-certs or ee-certs';
 286                 description
 287                   "NETCONF/TLS servers MUST validate client
 288                    certificates.  This configures certificates
 289                    at the socket-level (i.e. bags).  More
 290                    discriminating client-certificate checks
 291                    SHOULD be implemented by the application.";
 292                 reference
 293                   "RFC 7589:
 294                     Using the NETCONF Protocol over Transport Layer
 295                     Security (TLS) with Mutual X.509 Authentication";
 296               }
 297             }
 298           }
 299           container netconf-server-parameters {
 300             description
 301               "NETCONF-level server parameters to listen
 302                for NETCONF over TLS connections.";
 303             uses ncs:netconf-server-grouping {
 304               refine "client-identity-mappings/cert-to-name" {
 305                 min-elements 1;
 306                 description
 307                   "The TLS transport requires a mapping.";
 308               }
 309             }
 310           }
 311         }
 312       }
 313     }
 314   }
 315
 316   grouping netconf-server-callhome-stack-grouping {
 317     description
 318       "A reusable grouping for configuring a NETCONF server
 319        'call-home' protocol stack, for a single outbound
 320        connection.";
 321     choice transport {
 322       mandatory true;
 323       description
 324         "Selects between available transports.";
 325       case ssh {
 326         if-feature "ssh-call-home";
 327         container ssh {
 328           description
 329             "TCP, SSH, and NETCONF configuration to initiate
 330              a NETCONF over SSH Call Home connection.";
 331           container tcp-client-parameters {
 332             description
 333               "TCP-level client parameters to initiate a
 334                NETCONF over SSH Call Home connection.";
 335             uses tcpc:tcp-client-grouping {
 336               refine "remote-port" {
 337                 default "4334";
 338                 description
 339                   "The NETCONF server will attempt to connect
 340                    to the IANA-assigned well-known port for
 341                    'netconf-ch-ssh' (4334) if no value is
 342                    specified.";
 343               }
 344             }
 345           }
 346           container ssh-server-parameters {
 347             description
 348               "SSH-level server parameters to initiate a
 349                NETCONF over SSH Call Home connection.";
 350             uses sshs:ssh-server-grouping;
 351           }
 352           container netconf-server-parameters {
 353             description
 354               "NETCONF-level server parameters to initiate a
 355                NETCONF over SSH Call Home connection.";
 356             uses ncs:netconf-server-grouping {
 357               refine "client-identity-mappings" {
 358                 if-feature "sshcmn:ssh-x509-certs";
 359                 description
 360                   "Adds in an 'if-feature' statement
 361                    ensuring the 'client-identity-mappings'
 362                    descendant is enabled only when SSH
 363                    supports X.509 certificates.";
 364               }
 365               augment "client-identity-mappings" {
 366                 description
 367                   "Adds a flag indicating if a cert-to-name
 368                    is required.";
 369                 leaf mapping-required {
 370                   type boolean;
 371                   description
 372                     "Indicates that the cert-to-name mapping
 373                      is required (i.e., the SSH-level username
 374                      is ignored).";
 375                 }
 376               }
 377             }
 378           }
 379         }
 380       }
 381       case tls {
 382         if-feature "tls-call-home";
 383         container tls {
 384           description
 385             "TCP, TLS, and NETCONF configuration to initiate
 386              a NETCONF over TLS Call Home connection.";
 387           container tcp-client-parameters {
 388             description
 389               "TCP-level client parameters to initiate a
 390                NETCONF over TLS Call Home connection.";
 391             uses tcpc:tcp-client-grouping {
 392               refine "remote-port" {
 393                 default "4335";
 394                 description
 395                   "The NETCONF server will attempt to connect
 396                    to the IANA-assigned well-known port for
 397                    'netconf-ch-tls' (4335) if no value is
 398                    specified.";
 399               }
 400             }
 401           }
 402           container tls-server-parameters {
 403             description
 404               "TLS-level server parameters to initiate a
 405                NETCONF over TLS Call Home connection.";
 406             uses tlss:tls-server-grouping {
 407               refine "client-authentication" {
 408                 must 'ca-certs or ee-certs';
 409                 description
 410                   "NETCONF/TLS servers MUST validate client
 411                    certificates.  This configures certificates
 412                    at the socket-level (i.e. bags).  More
 413                    discriminating client-certificate checks
 414                    SHOULD be implemented by the application.";
 415                 reference
 416                   "RFC 7589:
 417                     Using the NETCONF Protocol over Transport Layer
 418                     Security (TLS) with Mutual X.509 Authentication";
 419               }
 420             }
 421           }
 422           container netconf-server-parameters {
 423             description
 424               "NETCONF-level server parameters to initiate a
 425                NETCONF over TLS Call Home connection.";
 426             uses ncs:netconf-server-grouping {
 427               refine "client-identity-mappings/cert-to-name" {
 428                 min-elements 1;
 429                 description
 430                   "The TLS transport requires a mapping.";
 431               }
 432             }
 433           }
 434         }
 435       }
 436     }
 437   }
 438
 439   grouping netconf-server-app-grouping {
 440     description
 441       "A reusable grouping for configuring a NETCONF server
 442        application that supports both 'listen' and 'call-home'
 443        protocol stacks for a multiplicity of connections.";
 444     container listen {
 445       if-feature "ssh-listen or tls-listen";
 446       presence
 447         "Indicates that server-listening ports have been configured.
 448          This statement is present so the mandatory descendant
 449          nodes do not imply that this node must be configured.";
 450       description
 451         "Configures listen behavior";
 452       leaf idle-timeout {
 453         type uint16;
 454         units "seconds";
 455         default "180"; // three minutes
 456         description
 457           "Specifies the maximum number of seconds that a NETCONF
 458            session may remain idle. A NETCONF session will be
 459            dropped if it is idle for an interval longer than this
 460            number of seconds.  If set to zero, then the server
 461            will never drop a session because it is idle.";
 462       }
 463       container endpoints {
 464         description
 465           "Container for a list of endpoints.";
 466         list endpoint {
 467           key "name";
 468           min-elements 1;
 469           description
 470             "List of endpoints to listen for NETCONF connections.";
 471           leaf name {
 472             type string;
 473             description
 474               "An arbitrary name for the NETCONF listen endpoint.";
 475           }
 476           uses netconf-server-listen-stack-grouping;
 477         }
 478       }
 479     }
 480     container call-home {
 481       if-feature "ssh-call-home or tls-call-home";
 482       presence
 483         "Indicates that server-initiated call home connections have
 484          been configured.  This statement is present so the mandatory
 485          descendant nodes do not imply that this node must be
 486          configured.";
 487       description
 488         "Configures the NETCONF server to initiate the underlying
 489          transport connection to NETCONF clients.";
 490       list netconf-client {
 491         key "name";
 492         min-elements 1;
 493         description
 494           "List of NETCONF clients the NETCONF server is to
 495            maintain simultaneous call-home connections with.";
 496         leaf name {
 497           type string;
 498           description
 499             "An arbitrary name for the remote NETCONF client.";
 500         }
 501         container endpoints {
 502           description
 503             "Container for the list of endpoints.";
 504           list endpoint {
 505             key "name";
 506             min-elements 1;
 507             ordered-by user;
 508             description
 509               "A non-empty user-ordered list of endpoints for this
 510                NETCONF server to try to connect to in sequence.
 511                Defining more than one enables high-availability.";
 512             leaf name {
 513               type string;
 514               description
 515                 "An arbitrary name for this endpoint.";
 516             }
 517             uses netconf-server-callhome-stack-grouping;
 518           }
 519         }
 520         container connection-type {
 521           description
 522             "Indicates the NETCONF server's preference for how the
 523              NETCONF connection is maintained.";
 524           choice connection-type {
 525             mandatory true;
 526             description
 527               "Selects between available connection types.";
 528             case persistent-connection {
 529               container persistent {
 530                 presence
 531                   "Indicates that a persistent connection is to be
 532                    maintained.";
 533                 description
 534                   "Maintain a persistent connection to the NETCONF
 535                    client. If the connection goes down, immediately
 536                    start trying to reconnect to the NETCONF client,
 537                    using the reconnection strategy.
 538
 539                    This connection type minimizes any NETCONF client
 540                    to NETCONF server data-transfer delay, albeit at
 541                    the expense of holding resources longer.";
 542               }
 543             }
 544             case periodic-connection {
 545               container periodic {
 546                 presence "Indicates that a periodic connection is
 547                           to be maintained.";
 548                 description
 549                   "Periodically connect to the NETCONF client.
 550
 551                    This connection type decreases resource
 552                    utilization, albeit with increased delay in
 553                    NETCONF client to NETCONF server interactions.
 554
 555                    The NETCONF client SHOULD gracefully close the
 556                    connection using <close-session> upon completing
 557                    planned activities.  If the NETCONF session is
 558                    not closed gracefully, the NETCONF server MUST
 559                    immediately attempt to reestablish the connection.
 560
 561                    Connections are established at the same start
 562                    time regardless how long the previous connection
 563                    stayed open.
 564
 565                    In the case that the previous connection is still
 566                    active (i.e., the NETCONF client has not closed
 567                    it yet), establishing a new connection is NOT
 568                    RECOMMENDED.";
 569                 leaf period {
 570                   type uint16;
 571                   units "minutes";
 572                   default "60";
 573                   description
 574                     "Duration of time between periodic connections.";
 575                 }
 576                 leaf anchor-time {
 577                   type yang:date-and-time {
 578                     // constrained to minute-level granularity
 579                     pattern '[0-9]{4}-(1[0-2]|0[1-9])-(0[1-9]|[1-2]'
 580                           + '[0-9]|3[0-1])T(0[0-9]|1[0-9]|2[0-3]):['
 581                           + '0-5][0-9]:00(Z|[\+\-]((1[0-3]|0[0-9]):'
 582                           + '([0-5][0-9])|14:00))?';
 583                   }
 584                   description
 585                     "Designates a timestamp before or after which a
 586                      series of periodic connections are determined.
 587                      The periodic connections occur at a whole
 588                      multiple interval from the anchor time.
 589
 590                      If an 'anchor-time' is not provided, then the
 591                      server may implicitly set it to the time when
 592                      this configuraton is applied (e.g., on boot).
 593
 594                      For example, for an anchor time is 15 minutes
 595                      past midnight and a period interval of 24 hours,
 596                      then a periodic connection will occur 15 minutes
 597                      past midnight everyday.";
 598                 }
 599                 leaf idle-timeout {
 600                   type uint16;
 601                   units "seconds";
 602                   default "180"; // three minutes
 603                   description
 604                     "Specifies the maximum number of seconds that
 605                      a NETCONF session may remain idle. A NETCONF
 606                      session will be dropped if it is idle for an
 607                      interval longer than this number of seconds.
 608                      If set to zero, then the server will never
 609                      drop a session because it is idle.";
 610                 }
 611               }
 612             } // case periodic-connection
 613           } // choice connection-type
 614         } // container connection-type
 615         container reconnect-strategy {
 616           description
 617             "The reconnection strategy directs how a NETCONF server
 618              reconnects to a NETCONF client, after discovering its
 619              connection to the client has dropped, even if due to a
 620              reboot.  The NETCONF server starts with the specified
 621              endpoint and tries to connect to it max-attempts times
 622              before trying the next endpoint in the list (round
 623              robin).";
 624           leaf start-with {
 625             type enumeration {
 626               enum first-listed {
 627                 description
 628                   "Indicates that reconnections should start with
 629                    the first endpoint listed.";
 630               }
 631               enum last-connected {
 632                 description
 633                   "Indicates that reconnections should start with
 634                    the endpoint last connected to.  If no previous
 635                    connection has ever been established, then the
 636                    first endpoint configured is used.   NETCONF
 637                    servers SHOULD be able to remember the last
 638                    endpoint connected to across reboots.";
 639               }
 640               enum random-selection {
 641                 description
 642                   "Indicates that reconnections should start with
 643                    a random endpoint.";
 644               }
 645             }
 646             default "first-listed";
 647             description
 648               "Specifies which of the NETCONF client's endpoints
 649                the NETCONF server should start with when trying
 650                to connect to the NETCONF client.";
 651           }
 652           leaf max-wait {
 653             type uint16 {
 654               range "1..max";
 655             }
 656             units "seconds";
 657             default "5";
 658             description
 659               "Specifies the amount of time in seconds after which,
 660                if the connection is not established, an endpoint
 661                connection attempt is considered unsuccessful.";
 662           }
 663           leaf max-attempts {
 664             type uint8 {
 665               range "1..max";
 666             }
 667             default "3";
 668             description
 669               "Specifies the number times the NETCONF server tries
 670                to connect to a specific endpoint before moving on
 671                to the next endpoint in the list (round robin).";
 672           }
 673         } // container reconnect-strategy
 674       } // list netconf-client
 675     } // container call-home
 676   } // grouping netconf-server-app-grouping
 677
 678   // Protocol accessible node for servers that implement this module.
 679   container netconf-server {
 680     if-feature central-netconf-server-supported;
 681     uses netconf-server-app-grouping;
 682     description
 683       "Top-level container for NETCONF server configuration.";
 684   }
 685 }