protocol/restconf-client/src/main/yang/ietf-restconf-client@2024-02-08.yang

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