protocol/netconf-server/src/main/yang/ietf-netconf-server@2023-04-17.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) 2023 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 2023-04-17 {
  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 a single connection.";
 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             "SSH-specific listening configuration for inbound
 207              connections.";
 208           container tcp-server-parameters {
 209             description
 210               "A wrapper around the TCP client parameters
 211                to avoid name collisions.";
 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               "A wrapper around the SSH server parameters
 226                to avoid name collisions.";
 227             uses sshs:ssh-server-grouping;
 228           }
 229           container netconf-server-parameters {
 230             description
 231               "A wrapper around the NETCONF server parameters
 232                to avoid name collisions.";
 233             uses ncs:netconf-server-grouping {
 234               refine "client-identity-mappings" {
 235                 if-feature "sshcmn:ssh-x509-certs";
 236                 description
 237                   "Augments 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             "TLS-specific listening configuration for inbound
 263              connections.";
 264           container tcp-server-parameters {
 265             description
 266               "A wrapper around the TCP client parameters
 267                to avoid name collisions.";
 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               "A wrapper around the TLS server parameters to
 282                avoid name collisions.";
 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               "A wrapper around the NETCONF server parameters
 302                to avoid name collisions.";
 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 connection.";
 320     choice transport {
 321       mandatory true;
 322       description
 323         "Selects between available transports.";
 324       case ssh {
 325         if-feature "ssh-call-home";
 326         container ssh {
 327           description
 328             "Specifies SSH-specific call-home transport
 329              configuration.";
 330           container tcp-client-parameters {
 331             description
 332               "A wrapper around the TCP client parameters
 333                to avoid name collisions.";
 334             uses tcpc:tcp-client-grouping {
 335               refine "remote-port" {
 336                 default "4334";
 337                 description
 338                   "The NETCONF server will attempt to connect
 339                    to the IANA-assigned well-known port for
 340                    'netconf-ch-ssh' (4334) if no value is
 341                    specified.";
 342               }
 343             }
 344           }
 345           container ssh-server-parameters {
 346             description
 347               "A wrapper around the SSH server parameters
 348                to avoid name collisions.";
 349             uses sshs:ssh-server-grouping;
 350           }
 351           container netconf-server-parameters {
 352             description
 353               "A wrapper around the NETCONF server parameters
 354                to avoid name collisions.";
 355             uses ncs:netconf-server-grouping {
 356               refine "client-identity-mappings" {
 357                 if-feature "sshcmn:ssh-x509-certs";
 358                 description
 359                   "Augments in an 'if-feature' statement
 360                    ensuring the 'client-identity-mappings'
 361                    descendant is enabled only when SSH
 362                    supports X.509 certificates.";
 363               }
 364               augment "client-identity-mappings" {
 365                 description
 366                   "Adds a flag indicating if a cert-to-name
 367                    is required.";
 368                 leaf mapping-required {
 369                   type boolean;
 370                   description
 371                     "Indicates that the cert-to-name mapping
 372                      is required (i.e., the SSH-level username
 373                      is ignored).";
 374                 }
 375               }
 376             }
 377           }
 378         }
 379       }
 380       case tls {
 381         if-feature "tls-call-home";
 382         container tls {
 383           description
 384             "Specifies TLS-specific call-home transport
 385              configuration.";
 386           container tcp-client-parameters {
 387             description
 388               "A wrapper around the TCP client parameters
 389                to avoid name collisions.";
 390             uses tcpc:tcp-client-grouping {
 391               refine "remote-port" {
 392                 default "4335";
 393                 description
 394                   "The NETCONF server will attempt to connect
 395                    to the IANA-assigned well-known port for
 396                    'netconf-ch-tls' (4335) if no value is
 397                    specified.";
 398               }
 399             }
 400           }
 401           container tls-server-parameters {
 402             description
 403               "A wrapper around the TLS server parameters to
 404                avoid name collisions.";
 405             uses tlss:tls-server-grouping {
 406               refine "client-authentication" {
 407                 must 'ca-certs or ee-certs';
 408                 description
 409                   "NETCONF/TLS servers MUST validate client
 410                    certificates.  This configures certificates
 411                    at the socket-level (i.e. bags), more
 412                    discriminating client-certificate checks
 413                    SHOULD be implemented by the application.";
 414                 reference
 415                   "RFC 7589:
 416                     Using the NETCONF Protocol over Transport Layer
 417                     Security (TLS) with Mutual X.509 Authentication";
 418               }
 419             }
 420           }
 421           container netconf-server-parameters {
 422             description
 423               "A wrapper around the NETCONF server parameters
 424                to avoid name collisions.";
 425             uses ncs:netconf-server-grouping {
 426               refine "client-identity-mappings/cert-to-name" {
 427                 min-elements 1;
 428                 description
 429                   "The TLS transport requires a mapping.";
 430               }
 431             }
 432           }
 433         }
 434       }
 435     }
 436   }
 437
 438   grouping netconf-server-app-grouping {
 439     description
 440       "A reusable grouping for configuring a NETCONF server
 441        application that supports both 'listen' and 'call-home'
 442        protocol stacks for a multiplicity of connections.";
 443     container listen {
 444       if-feature "ssh-listen or tls-listen";
 445       presence
 446         "Indicates that server-listening ports have been configured.
 447          This statement is present so the mandatory descendant
 448          nodes do not imply that this node must be configured.";
 449       description
 450         "Configures listen behavior";
 451       leaf idle-timeout {
 452         type uint16;
 453         units "seconds";
 454         default "180"; // three minutes
 455         description
 456           "Specifies the maximum number of seconds that a NETCONF
 457            session may remain idle. A NETCONF session will be
 458            dropped if it is idle for an interval longer than this
 459            number of seconds.  If set to zero, then the server
 460            will never drop a session because it is idle.";
 461       }
 462       list endpoint {
 463         key "name";
 464         min-elements 1;
 465         description
 466           "List of endpoints to listen for NETCONF connections.";
 467         leaf name {
 468           type string;
 469           description
 470             "An arbitrary name for the NETCONF listen endpoint.";
 471         }
 472         uses netconf-server-listen-stack-grouping;
 473       }
 474     }
 475     container call-home {
 476       if-feature "ssh-call-home or tls-call-home";
 477       presence
 478         "Indicates that server-initiated call home connections have
 479          been configured.  This statement is present so the mandatory
 480          descendant nodes do not imply that this node must be
 481          configured.";
 482       description
 483         "Configures the NETCONF server to initiate the underlying
 484          transport connection to NETCONF clients.";
 485       list netconf-client {
 486         key "name";
 487         min-elements 1;
 488         description
 489           "List of NETCONF clients the NETCONF server is to
 490            maintain simultaneous call-home connections with.";
 491         leaf name {
 492           type string;
 493           description
 494             "An arbitrary name for the remote NETCONF client.";
 495         }
 496         container endpoints {
 497           description
 498             "Container for the list of endpoints.";
 499           list endpoint {
 500             key "name";
 501             min-elements 1;
 502             ordered-by user;
 503             description
 504               "A non-empty user-ordered list of endpoints for this
 505                NETCONF server to try to connect to in sequence.
 506                Defining more than one enables high-availability.";
 507             leaf name {
 508               type string;
 509               description
 510                 "An arbitrary name for this endpoint.";
 511             }
 512             uses netconf-server-callhome-stack-grouping;
 513           }
 514         }
 515         container connection-type {
 516           description
 517             "Indicates the NETCONF server's preference for how the
 518              NETCONF connection is maintained.";
 519           choice connection-type {
 520             mandatory true;
 521             description
 522               "Selects between available connection types.";
 523             case persistent-connection {
 524               container persistent {
 525                 presence
 526                   "Indicates that a persistent connection is to be
 527                    maintained.";
 528                 description
 529                   "Maintain a persistent connection to the NETCONF
 530                    client. If the connection goes down, immediately
 531                    start trying to reconnect to the NETCONF client,
 532                    using the reconnection strategy.
 533
 534                    This connection type minimizes any NETCONF client
 535                    to NETCONF server data-transfer delay, albeit at
 536                    the expense of holding resources longer.";
 537               }
 538             }
 539             case periodic-connection {
 540               container periodic {
 541                 presence "Indicates that a periodic connection is
 542                           to be maintained.";
 543                 description
 544                   "Periodically connect to the NETCONF client.
 545
 546                    This connection type decreases resource
 547                    utilization, albeit with increased delay in
 548                    NETCONF client to NETCONF server interactions.
 549
 550                    The NETCONF client SHOULD gracefully close the
 551                    connection using <close-session> upon completing
 552                    planned activities.  If the NETCONF session is
 553                    not closed gracefully, the NETCONF server MUST
 554                    immediately attempt to reestablish the connection.
 555
 556                    Connections are established at the same start
 557                    time regardless how long the previous connection
 558                    stayed open.
 559
 560                    In the case that the previous connection is still
 561                    active (i.e., the NETCONF client has not closed
 562                    it yet), establishing a new connection is NOT
 563                    RECOMMENDED.";
 564                 leaf period {
 565                   type uint16;
 566                   units "minutes";
 567                   default "60";
 568                   description
 569                     "Duration of time between periodic connections.";
 570                 }
 571                 leaf anchor-time {
 572                   type yang:date-and-time {
 573                     // constrained to minute-level granularity
 574                     pattern '[0-9]{4}-(1[0-2]|0[1-9])-(0[1-9]|[1-2]'
 575                           + '[0-9]|3[0-1])T(0[0-9]|1[0-9]|2[0-3]):['
 576                           + '0-5][0-9]:00(Z|[\+\-]((1[0-3]|0[0-9]):'
 577                           + '([0-5][0-9])|14:00))?';
 578                   }
 579                   description
 580                     "Designates a timestamp before or after which a
 581                      series of periodic connections are determined.
 582                      The periodic connections occur at a whole
 583                      multiple interval from the anchor time.
 584
 585                      If an 'anchor-time' is not provided, then the
 586                      server may implicitly set it to the time when
 587                      this configuraton is applied (e.g., on boot).
 588
 589                      For example, for an anchor time is 15 minutes
 590                      past midnight and a period interval of 24 hours,
 591                      then a periodic connection will occur 15 minutes
 592                      past midnight everyday.";
 593                 }
 594                 leaf idle-timeout {
 595                   type uint16;
 596                   units "seconds";
 597                   default "180"; // three minutes
 598                   description
 599                     "Specifies the maximum number of seconds that
 600                      a NETCONF session may remain idle. A NETCONF
 601                      session will be dropped if it is idle for an
 602                      interval longer than this number of seconds.
 603                      If set to zero, then the server will never
 604                      drop a session because it is idle.";
 605                 }
 606               }
 607             } // case periodic-connection
 608           } // choice connection-type
 609         } // container connection-type
 610         container reconnect-strategy {
 611           description
 612             "The reconnection strategy directs how a NETCONF server
 613              reconnects to a NETCONF client, after discovering its
 614              connection to the client has dropped, even if due to a
 615              reboot.  The NETCONF server starts with the specified
 616              endpoint and tries to connect to it max-attempts times
 617              before trying the next endpoint in the list (round
 618              robin).";
 619           leaf start-with {
 620             type enumeration {
 621               enum first-listed {
 622                 description
 623                   "Indicates that reconnections should start with
 624                    the first endpoint listed.";
 625               }
 626               enum last-connected {
 627                 description
 628                   "Indicates that reconnections should start with
 629                    the endpoint last connected to.  If no previous
 630                    connection has ever been established, then the
 631                    first endpoint configured is used.   NETCONF
 632                    servers SHOULD be able to remember the last
 633                    endpoint connected to across reboots.";
 634               }
 635               enum random-selection {
 636                 description
 637                   "Indicates that reconnections should start with
 638                    a random endpoint.";
 639               }
 640             }
 641             default "first-listed";
 642             description
 643               "Specifies which of the NETCONF client's endpoints
 644                the NETCONF server should start with when trying
 645                to connect to the NETCONF client.";
 646           }
 647           leaf max-wait {
 648             type uint16 {
 649               range "1..max";
 650             }
 651             units "seconds";
 652             default "5";
 653             description
 654               "Specifies the amount of time in seconds after which,
 655                if the connection is not established, an endpoint
 656                connection attempt is considered unsuccessful.";
 657           }
 658           leaf max-attempts {
 659             type uint8 {
 660               range "1..max";
 661             }
 662             default "3";
 663             description
 664               "Specifies the number times the NETCONF server tries
 665                to connect to a specific endpoint before moving on
 666                to the next endpoint in the list (round robin).";
 667           }
 668         } // container reconnect-strategy
 669       } // list netconf-client
 670     } // container call-home
 671   } // grouping netconf-server-app-grouping
 672
 673   // Protocol accessible node for servers that implement this module.
 674   container netconf-server {
 675     if-feature central-netconf-server-supported;
 676     uses netconf-server-app-grouping;
 677     description
 678       "Top-level container for NETCONF server configuration.";
 679   }
 680 }