netconfcentral logo

ietf-restconf-server@2015-02-02



  module ietf-restconf-server {

    yang-version 1;

    namespace
      "urn:ietf:params:xml:ns:yang:ietf-restconf-server";

    prefix rcserver;

    import ietf-netconf-acm {
      prefix nacm;
      revision-date "2012-02-22";
    }
    import ietf-inet-types {
      prefix inet;
      revision-date "2013-07-15";
    }
    import ietf-x509-cert-to-name {
      prefix x509c2n;
      revision-date "2014-12-10";
    }

    organization
      "IETF NETCONF (Network Configuration) Working Group";

    contact
      "WG Web:   <http://tools.ietf.org/wg/netconf/>
    WG List:  <mailto:netconf@ietf.org>

    WG Chair: Mehmet Ersue
              <mailto:mehmet.ersue@nsn.com>

    WG Chair: Mahesh Jethanandani
              <mailto:mjethanandani@gmail.com>

    Editor:   Kent Watsen
              <mailto:kwatsen@juniper.net>";

    description
      "This module contains a collection of YANG definitions for
    configuring RESTCONF servers.

    Copyright (c) 2014 IETF Trust and the persons identified as
    authors of the code. All rights reserved.

    Redistribution and use in source and binary forms, with or
    without modification, is permitted pursuant to, and subject
    to the license terms contained in, the Simplified BSD
    License set forth in Section 4.c of the IETF Trust's
    Legal Provisions Relating to IETF Documents
    (http://trustee.ietf.org/license-info).

    This version of this YANG module is part of RFC VVVV; see
    the RFC itself for full legal notices.";

    revision "2015-02-02" {
      description "Initial version";
      reference
        "RFC VVVV: NETCONF Server and RESTCONF Server Configuration Models";

    }


    feature tls {
      description
        "The tls feature indicates that the server supports RESTCONF
      over the TLS transport protocol.";
      reference
        "RFC XXXX: RESTCONF Protocol";

    }

    feature listen {
      description
        "The listen feature indicates that the server supports
      opening a port to listen for incoming client connections.";
      reference
        "RFC XXXX: RESTCONF Protocol";

    }

    feature call-home {
      description
        "The call-home feature indicates that the server supports
      connecting to the client.";
      reference
        "RFC YYYY: NETCONF Call Home and RESTCONF Call Home";

    }

    feature client-cert-auth {
      description
        "The client-cert-auth feature indicatres that the server
      supports the ClientCertificate authentication scheme.";
      reference
        "RFC ZZZZ: Client Authentication over New TLS Connection";

    }

    container restconf-server {
      description
        "Top-level container for RESTCONF server configuration.";
      uses listen-container;

      uses call-home-container;

      uses client-cert-auth-container;
    }  // container restconf-server

    grouping listen-container {
      description
        "This grouping is used only to help improve readability
       of the YANG module.";
      container listen {
        if-feature listen;
        description
          "Configures listen behavior";
        leaf max-sessions {
          type uint16 {
            range "0 .. 1024";
          }
          default '0';
          description
            "Specifies the maximum number of concurrent sessions
           that can be active at one time.  The value 0 indicates
           that no artificial session limit should be used.";
        }

        list endpoint {
          key "name";
          description
            "List of endpoints to listen for RESTCONF connections on.";
          leaf name {
            type string;
            description
              "An arbitrary name for the RESTCONF listen endpoint.";
          }

          choice transport {
            mandatory true;
            description
              "Selects between available transports.";
            container tls {
              description
                "TLS-specific listening configuration for inbound
                 connections.";
              uses address-and-port-grouping {
                refine 
              }

              uses certificates-container;
            }  // container tls
          }  // choice transport

          uses keep-alives-container {
            refine 
          }
        }  // list endpoint
      }  // container listen
    }  // grouping listen-container

    grouping call-home-container {
      description
        "This grouping is used only to help improve readability
       of the YANG module.";
      container call-home {
        if-feature call-home;
        description
          "Configures call-home behavior";
        list application {
          key "name";
          description
            "List of RESTCONF clients the RESTCONF server is to initiate
           call-home connections to.";
          leaf name {
            type string;
            description
              "An arbitrary name for the remote RESTCONF client.";
          }

          choice transport {
            mandatory true;
            description
              "Selects between TLS and any future transports augmented in.";
            case tls {
              if-feature tls;
              container tls {
                description
                  "Specifies TLS-specific call-home transport
                 configuration.";
                uses endpoints-container {
                  refine 
                }

                uses certificates-container;
              }  // container tls
            }  // case tls
          }  // choice transport

          container connection-type {
            description
              "Indicates the RESTCONF client's preference for how the
            RESTCONF server's connection is maintained.";
            choice connection-type {
              default
                'persistent-connection';
              description
                "Selects between persistent and periodic connections.";
              container persistent {
                description
                  "Maintain a persistent connection to the RESTCONF
                  client. If the connection goes down, immediately
                  start trying to reconnect to it, using the
                  reconnection strategy.

                  This connection type minimizes any RESTCONF client
                  to RESTCONF server data-transfer delay, albeit at
                  the expense of holding resources longer.";
                uses keep-alives-container {
                  refine 
                }
              }  // container persistent
              container periodic {
                description
                  "Periodically connect to RESTCONF client, using the
                  reconnection strategy, so the RESTCONF client can
                  deliver pending messages to the RESTCONF server.

                  For messages the RESTCONF server wants to send to
                  to the RESTCONF client, the RESTCONF server should
                  proactively connect to the RESTCONF client, if
                  not already, to send the messages immediately.";
                leaf timeout-mins {
                  type uint8;
                  units "minutes";
                  default '5';
                  description
                    "The maximum amount of unconnected time the RESTCONF
                    server will wait until establishing a connection to
                    the RESTCONF client again. The RESTCONF server MAY
                    establish a connection before this time if it has
                    data it needs to send to the RESTCONF client. Note:
                    this value differs from the reconnection strategy's
                    interval-secs value.";
                }

                leaf linger-secs {
                  type uint8;
                  units "seconds";
                  default '30';
                  description
                    "The amount of time the RESTCONF server should wait
                    after last receiving data from or sending data to
                    the RESTCONF client's endpoint before closing its
                    connection to it.  This is an optimization to
                    prevent unnecessary connections.";
                }
              }  // container periodic
            }  // choice connection-type
          }  // container connection-type

          container reconnect-strategy {
            description
              "The reconnection strategy guides how a RESTCONF server
            reconnects to an RESTCONF client, after losing a connection
            to it, even if due to a reboot.  The RESTCONF server starts
            with the specified endpoint and tries to connect to it
            count-max times, waiting interval-secs between each
            connection attempt, before trying the next endpoint in
            the list (round robin).";
            leaf start-with {
              type enumeration {
                enum "first-listed" {
                  value 0;
                  description
                    "Indicates that reconnections should start with
                   the first endpoint listed.";
                }
                enum "last-connected" {
                  value 1;
                  description
                    "Indicates that reconnections should start with
                   the endpoint last connected to.  RESTCONF servers
                   SHOULD support this flag across reboots.";
                }
              }
              default 'first-listed';
              description
                "Specifies which of the RESTCONF client's endpoints the
              RESTCONF server should start with when trying to connect
              to the RESTCONF client.  If no previous connection has
              ever been established, last-connected defaults to
              the first endpoint listed.";
            }

            leaf interval-secs {
              type uint8;
              units "seconds";
              default '5';
              description
                "Specifies the time delay between connection attempts
              to the same endpoint.  Note: this value differs from
              the periodic-connection's timeout-mins value.";
            }

            leaf count-max {
              type uint8;
              default '3';
              description
                "Specifies the number times the RESTCONF server tries to
              connect to a specific endpoint before moving on to the
              next endpoint in the list (round robin).";
            }
          }  // container reconnect-strategy
        }  // list application
      }  // container call-home
    }  // grouping call-home-container

    grouping client-cert-auth-container {
      description
        "This grouping is used only to help improve readability
       of the YANG module.";
      container client-cert-auth {
        if-feature client-cert-auth;
        description
          "Container for TLS client certificate authentication
         configuration.";
        container trusted-ca-certs {
          description
            "A list of Certificate Authority (CA) certificates that
           a NETCONF server can use to authenticate NETCONF client
           certificates.  A client's certificate is authenticated
           if there is a chain of trust to a configured trusted CA
           certificate.  The client certificate MAY be accompanied
           with additional certificates forming a chain of trust.
           The client's certificate is authenticated if there is
           path-validation from any of the certificates it presents
           to a configured trust anchor.";
          leaf-list trusted-ca-cert {
            nacm:default-deny-write;
            type binary;
            description
              "The binary certificate structure as specified by RFC
             5246, Section 7.4.6, i.e.,: opaque ASN.1Cert<1..2^24>;
            ";
            reference
              "RFC 5246: The Transport Layer Security (TLS)
              	  Protocol Version 1.2";

          }
        }  // container trusted-ca-certs

        container trusted-client-certs {
          description
            "A list of client certificates that a NETCONF server can
           use to authenticate a NETCONF client's certificate.  A
           client's certificate is authenticated if it is an exact
           match to a configured trusted client certificates.";
          leaf-list trusted-client-cert {
            nacm:default-deny-write;
            type binary;
            description
              "The binary certificate structure, as
             specified by RFC 5246, Section 7.4.6, i.e.,:

               opaque ASN.1Cert<1..2^24>;

            ";
            reference
              "RFC 5246: The Transport Layer Security (TLS)
              	  Protocol Version 1.2";

          }
        }  // container trusted-client-certs

        container cert-maps {
          description
            "The cert-maps container is used by a NETCONF server to
          map the NETCONF client's presented X.509 certificate to a
          NETCONF username.  If no matching and valid cert-to-name
          list entry can be found, then the NETCONF server MUST
          close the connection, and MUST NOT accept NETCONF
          messages over it.";
          uses x509c2n:cert-to-name;
        }  // container cert-maps
      }  // container client-cert-auth
    }  // grouping client-cert-auth-container

    grouping certificates-container {
      description
        "This grouping is used by both the listen and
       call-home containers";
      container certificates {
        description
          "Parent container for the list of certificates.";
        leaf-list certificate {
          type string;
          min-elements 1;
          description
            "An unordered list of certificates the TLS server can pick
           from when sending its Server Certificate message.  The value
           of the string is the unique identifier for a certificate
           configured on the system.  How valid values are discovered
           is outside the scope of this module, but they are envisioned
           to be the keys for a list of certificates provided
           by another YANG module";
          reference
            "RFC 5246: The TLS Protocol, Section 7.4.2";

        }
      }  // container certificates
    }  // grouping certificates-container

    grouping address-and-port-grouping {
      description
        "This grouping is usd by both the ssh and tls containers
       for listen configuration.";
      leaf address {
        type inet:ip-address;
        description
          "The IP address of the interface to listen on.";
      }

      leaf port {
        type inet:port-number;
        description
          "The local port number on this interface the RESTCONF server
        listens on.";
      }
    }  // grouping address-and-port-grouping

    grouping endpoints-container {
      description
        "This grouping is used by both the ssh and tls containers
       for call-home configurations.";
      container endpoints {
        description
          "Container for the list of endpoints.";
        list endpoint {
          key "name";
          min-elements 1;
          ordered-by user;
          description
            "User-ordered list of endpoints for this RESTCONF client.
           Defining more than one enables high-availability.";
          leaf name {
            type string;
            description
              "An arbitrary name for the endpoint to connect to.";
          }

          leaf address {
            type inet:host;
            mandatory true;
            description
              "The hostname or IP address or hostname of the endpoint.
            If a hostname is provided and DNS resolves to more than
            one IP address, the RESTCONF server SHOULD try all of
            the ones it can based on how its networking stack is
            configured (e.g. v4, v6, dual-stack).";
          }

          leaf port {
            type inet:port-number;
            description
              "The IP port for this endpoint. The RESTCONF server will
            use the IANA-assigned well-known port if not specified.";
          }
        }  // list endpoint
      }  // container endpoints
    }  // grouping endpoints-container

    grouping keep-alives-container {
      description
        "This grouping is use by both listen and call-home configurations.";
      container keep-alives {
        description
          "Configures the keep-alive policy, to proactively test the
         aliveness of the RESTCONF client.";
        reference
          "RFC VVVV: NETCONF Server and RESTCONF Server Configuration
          Models, Section 4";

        leaf interval-secs {
          type uint8;
          units "seconds";
          description
            "Sets a timeout interval in seconds after which if no data
          has been received from the RESTCONF client, a message will
          be sent to request a response from the RESTCONF client.  A
          value of '0' indicates that no keep-alive messages should
          be sent.";
        }

        leaf count-max {
          type uint8;
          default '3';
          description
            "Sets the number of keep-alive messages that may be sent
          without receiving any data from the RESTCONF client before
          assuming the RESTCONF client is no longer alive.  If this
          threshold is reached, the transport-level connection will
          be disconnected, which will trigger the reconnection
          strategy).  The interval timer is reset after each
          transmission, thus an unresponsive RESTCONF client will
          be dropped after approximately (count-max * interval-secs)
          seconds.";
        }
      }  // container keep-alives
    }  // grouping keep-alives-container
  }  // module ietf-restconf-server