protocol/netconf-client/src/main/yang/ietf-netconf-client@2023-04-17.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-04-17 {
  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 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 IP and SSH specific configuration
 152              for the connection.";
 153           container tcp-client-parameters {
 154             description
 155               "A wrapper around the TCP client parameters
 156                to avoid name collisions.";
 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               "A wrapper around the SSH client parameters to
 171                avoid name collisions.";
 172             uses sshc:ssh-client-grouping;
 173           }
 174           container netconf-client-parameters {
 175             description
 176               "A wrapper around the NETCONF client parameters
 177                to avoid name collisions.
 178
 179                This container does not define any nodes.  It
 180                exists as a potential augmentation target by
 181                other modules.";
 182             uses ncc:netconf-client-grouping;
 183           }
 184         }
 185       }
 186       case tls {
 187         if-feature "tls-initiate";
 188         container tls {
 189           description
 190             "Specifies IP and TLS specific configuration
 191              for the connection.";
 192           container tcp-client-parameters {
 193             description
 194               "A wrapper around the TCP client parameters
 195                to avoid name collisions.";
 196             uses tcpc:tcp-client-grouping {
 197               refine "remote-port" {
 198                 default "6513";
 199                 description
 200                   "The NETCONF client will attempt to connect
 201                    to the IANA-assigned well-known port value
 202                    for 'netconf-tls' (6513) if no value is
 203                    specified.";
 204               }
 205             }
 206           }
 207           container tls-client-parameters {
 208             must client-identity {
 209               description
 210                 "NETCONF/TLS clients MUST pass some
 211                  authentication credentials.";
 212             }
 213             description
 214               "A wrapper around the TLS client parameters
 215                to avoid name collisions.";
 216             uses tlsc:tls-client-grouping;
 217           }
 218           container netconf-client-parameters {
 219             description
 220               "A wrapper around the NETCONF client parameters
 221                to avoid name collisions.
 222
 223                This container does not define any nodes.  It
 224                exists as a potential augmentation target by
 225                other modules.";
 226             uses ncc:netconf-client-grouping;
 227           }
 228         }
 229       }
 230     }
 231   } // netconf-client-initiate-stack-grouping
 232
 233   grouping netconf-client-listen-stack-grouping {
 234     description
 235       "A reusable grouping for configuring a NETCONF client
 236        'listen' protocol stack for a single connection.  The
 237        'listen' stack supports call home connections, as
 238        described in RFC 8071";
 239     reference
 240       "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
 241     choice transport {
 242       mandatory true;
 243       description
 244         "Selects between available transports.";
 245       case ssh {
 246         if-feature "ssh-listen";
 247         container ssh {
 248           description
 249             "SSH-specific listening configuration for inbound
 250              connections.";
 251           container tcp-server-parameters {
 252             description
 253               "A wrapper around the TCP server parameters
 254                to avoid name collisions.";
 255             uses tcps:tcp-server-grouping {
 256               refine "local-port" {
 257                 default "4334";
 258                 description
 259                   "The NETCONF client will listen on the IANA-
 260                    assigned well-known port for 'netconf-ch-ssh'
 261                    (4334) if no value is specified.";
 262               }
 263             }
 264           }
 265           container ssh-client-parameters {
 266             description
 267               "A wrapper around the SSH client parameters
 268                to avoid name collisions.";
 269             uses sshc:ssh-client-grouping;
 270           }
 271           container netconf-client-parameters {
 272             description
 273               "A wrapper around the NETCONF client parameters
 274                to avoid name collisions.
 275
 276                This container does not define any nodes.  It
 277                exists as a potential augmentation target by
 278                other modules.";
 279             uses ncc:netconf-client-grouping;
 280           }
 281         }
 282       }
 283       case tls {
 284         if-feature "tls-listen";
 285         container tls {
 286           description
 287             "TLS-specific listening configuration for inbound
 288              connections.";
 289           container tcp-server-parameters {
 290             description
 291               "A wrapper around the TCP server parameters
 292                to avoid name collisions.";
 293             uses tcps:tcp-server-grouping {
 294               refine "local-port" {
 295                 default "4335";
 296                 description
 297                   "The NETCONF client will listen on the IANA-
 298                    assigned well-known port for 'netconf-ch-tls'
 299                    (4335) if no value is specified.";
 300               }
 301             }
 302           }
 303           container tls-client-parameters {
 304             must client-identity {
 305               description
 306                 "NETCONF/TLS clients MUST pass some
 307                  authentication credentials.";
 308             }
 309             description
 310               "A wrapper around the TLS client parameters
 311                to avoid name collisions.";
 312             uses tlsc:tls-client-grouping;
 313           }
 314           container netconf-client-parameters {
 315             description
 316               "A wrapper around the NETCONF client parameters
 317                to avoid name collisions.
 318
 319                This container does not define any nodes.  It
 320                exists as a potential augmentation target by
 321                other modules.";
 322             uses ncc:netconf-client-grouping;
 323           }
 324         }
 325       }
 326     }
 327   } // netconf-client-listen-stack-grouping
 328
 329   grouping netconf-client-app-grouping {
 330     description
 331       "A reusable grouping for configuring a NETCONF client
 332        application that supports both 'initiate' and 'listen'
 333        protocol stacks for a multiplicity of connections.";
 334     container initiate {
 335       if-feature "ssh-initiate or tls-initiate";
 336       presence
 337         "Indicates that client-initiated connections have been
 338          configured.  This statement is present so the mandatory
 339          descendant nodes do not imply that this node must be
 340          configured.";
 341       description
 342         "Configures client initiating underlying TCP connections.";
 343       list netconf-server {
 344         key "name";
 345         min-elements 1;
 346         description
 347           "List of NETCONF servers the NETCONF client is to
 348            maintain simultaneous connections with.";
 349         leaf name {
 350           type string;
 351           description
 352             "An arbitrary name for the NETCONF server.";
 353         }
 354         container endpoints {
 355           description
 356             "Container for the list of endpoints.";
 357           list endpoint {
 358             key "name";
 359             min-elements 1;
 360             ordered-by user;
 361             description
 362               "A user-ordered list of endpoints that the NETCONF
 363                client will attempt to connect to in the specified
 364                sequence.  Defining more than one enables
 365                high-availability.";
 366             leaf name {
 367               type string;
 368               description
 369                 "An arbitrary name for the endpoint.";
 370             }
 371             uses netconf-client-initiate-stack-grouping;
 372           } // list endpoint
 373         } // container endpoints
 374
 375         container connection-type {
 376           description
 377             "Indicates the NETCONF client's preference for how the
 378              NETCONF connection is maintained.";
 379           choice connection-type {
 380             mandatory true;
 381             description
 382               "Selects between available connection types.";
 383             case persistent-connection {
 384               container persistent {
 385                 presence
 386                   "Indicates that a persistent connection is to be
 387                    maintained.";
 388                 description
 389                   "Maintain a persistent connection to the NETCONF
 390                    server.  If the connection goes down, immediately
 391                    start trying to reconnect to the NETCONF server,
 392                    using the reconnection strategy.
 393
 394                    This connection type minimizes any NETCONF server
 395                    to NETCONF client data-transfer delay, albeit at
 396                    the expense of holding resources longer.";
 397               }
 398             }
 399             case periodic-connection {
 400               container periodic {
 401                 presence "Indicates that a periodic connection is
 402                           to be maintained.";
 403                 description
 404                   "Periodically connect to the NETCONF server.
 405
 406                    This connection type decreases resource
 407                    utilization, albeit with increased delay in
 408                    NETCONF server to NETCONF client interactions.
 409
 410                    The NETCONF client should close the underlying
 411                    TCP connection upon completing planned activities.
 412
 413                    Connections are established at the same start
 414                    time regardless how long the previous connection
 415                    stayed open.
 416
 417                    In the case that the previous connection is still
 418                    active, establishing a new connection is NOT
 419                    RECOMMENDED.";
 420                 leaf period {
 421                   type uint16;
 422                   units "minutes";
 423                   default "60";
 424                   description
 425                     "Duration of time between periodic connections.";
 426                 }
 427                 leaf anchor-time {
 428                   type yang:date-and-time {
 429                     // constrained to minute-level granularity
 430                     pattern '[0-9]{4}-(1[0-2]|0[1-9])-(0[1-9]|[1-2]'
 431                           + '[0-9]|3[0-1])T(0[0-9]|1[0-9]|2[0-3]):['
 432                           + '0-5][0-9]:00(Z|[\+\-]((1[0-3]|0[0-9]):'
 433                           + '([0-5][0-9])|14:00))?';
 434                   }
 435                   description
 436                     "Designates a timestamp before or after which a
 437                      series of periodic connections are determined.
 438                      The periodic connections occur at a whole
 439                      multiple interval from the anchor time.
 440
 441                      If an 'anchor-time' is not provided, then the
 442                      server may implicitly set it to the time when
 443                      this configuraton is applied (e.g., on boot).
 444
 445                      For example, for an anchor time is 15 minutes
 446                      past midnight and a period interval of 24 hours,
 447                      then a periodic connection will occur 15 minutes
 448                      past midnight everyday.";
 449                 }
 450                 leaf idle-timeout {
 451                   type uint16;
 452                   units "seconds";
 453                   default 180; // three minutes
 454                   description
 455                     "Specifies the maximum number of seconds that
 456                      a NETCONF session may remain idle. A NETCONF
 457                      session will be dropped if it is idle for an
 458                      interval longer then this number of seconds.
 459                      If set to zero, then the NETCONF client will
 460                      never drop a session because it is idle.";
 461                 }
 462               }
 463             }
 464           }
 465         }
 466         container reconnect-strategy {
 467           description
 468             "The reconnection strategy directs how a NETCONF client
 469              reconnects to a NETCONF server, after discovering its
 470              connection to the server has dropped, even if due to a
 471              reboot.  The NETCONF client starts with the specified
 472              endpoint and tries to connect to it max-attempts times
 473              before trying the next endpoint in the list (round
 474              robin).";
 475           leaf start-with {
 476             type enumeration {
 477               enum first-listed {
 478                 description
 479                   "Indicates that reconnections should start with
 480                    the first endpoint listed.";
 481               }
 482               enum last-connected {
 483                 description
 484                   "Indicates that reconnections should start with
 485                    the endpoint last connected to.  If no previous
 486                    connection has ever been established, then the
 487                    first endpoint configured is used.   NETCONF
 488                    clients SHOULD be able to remember the last
 489                    endpoint connected to across reboots.";
 490               }
 491               enum random-selection {
 492                 description
 493                   "Indicates that reconnections should start with
 494                    a random endpoint.";
 495               }
 496             }
 497             default "first-listed";
 498             description
 499               "Specifies which of the NETCONF server's endpoints
 500                the NETCONF client should start with when trying
 501                to connect to the NETCONF server.";
 502           }
 503           leaf max-wait {
 504             type uint16 {
 505               range "1..max";
 506             }
 507             units "seconds";
 508             default "5";
 509             description
 510               "Specifies the amount of time in seconds after which,
 511                if the connection is not established, an endpoint
 512                connection attempt is considered unsuccessful.";
 513           }
 514           leaf max-attempts {
 515             type uint8 {
 516               range "1..max";
 517             }
 518             default "3";
 519             description
 520               "Specifies the number times the NETCONF client tries
 521                to connect to a specific endpoint before moving on
 522                to the next endpoint in the list (round robin).";
 523           }
 524         }
 525       } // netconf-server
 526     } // initiate
 527
 528     container listen {
 529       if-feature "ssh-listen or tls-listen";
 530       presence
 531         "Indicates that client-listening ports have been configured.
 532          This statement is present so the mandatory descendant nodes
 533          do not imply that this node must be configured.";
 534       description
 535         "Configures the client to accept call-home TCP connections.";
 536       leaf idle-timeout {
 537         type uint16;
 538         units "seconds";
 539         default "180"; // three minutes
 540         description
 541           "Specifies the maximum number of seconds that a NETCONF
 542            session may remain idle. A NETCONF session will be
 543            dropped if it is idle for an interval longer than this
 544            number of seconds.  If set to zero, then the server
 545            will never drop a session because it is idle.";
 546       }
 547       list endpoint {
 548         key "name";
 549         min-elements 1;
 550         description
 551           "List of endpoints to listen for NETCONF connections.";
 552         leaf name {
 553           type string;
 554           description
 555             "An arbitrary name for the NETCONF listen endpoint.";
 556         }
 557         uses netconf-client-listen-stack-grouping;
 558       } // endpoint
 559     } // listen
 560   } // netconf-client-app-grouping
 561
 562   // Protocol accessible node for clients that implement this module.
 563   container netconf-client {
 564     if-feature central-netconf-client-supported;
 565     uses netconf-client-app-grouping;
 566     description
 567       "Top-level container for NETCONF client configuration.";
 568   }
 569 }