protocol/netconf-client/src/main/yang/ietf-netconf-client@2023-12-28.yang

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