One document matched: draft-scharf-alto-yang-00.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt'?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no"?>
<?rfc strict="no"?>
<?rfc compact="no"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-scharf-alto-yang-00" ipr="trust200902">

  <front>

    <title abbrev="ALTO Extension for YANG">ALTO Extension for YANG Modules</title>

    <author fullname="Michael Scharf" initials="M." surname="Scharf">
      <organization abbrev="Alcatel-Lucent Bell Labs">Alcatel-Lucent Bell Labs</organization>

      <address>
        <postal>
          <street>Lorenzstrasse 10</street>

          <code>70435</code>

          <city>Stuttgart</city>

          <country>Germany</country>
        </postal>

        <email>michael.scharf@alcatel-lucent.com</email>

      </address>
    </author>

    <date year="2014" />

    <area>Transport</area>

    <workgroup>ALTO WG</workgroup>

    <keyword>ALTO</keyword>

    <keyword>YANG</keyword>

    <abstract>
      <t>The Application-Layer Traffic Optimization (ALTO) protocol is
      designed to expose network topology information to
      applications. The ALTO protocol includes a well-defined set of
      base services. This document specifies an optional ALTO
      extension that enables ALTO clients to discover and query
      additional data being defined by YANG modules. This document
      describes the corresponding extensions of the ALTO Information
      Resource Directory and other required mechanisms.</t>
    </abstract>

  </front>

  <middle>

    <section title="Introduction">

       <t>The Application-Layer Traffic Optimization (ALTO) protocol
       <xref target="I-D.ietf-alto-protocol"/> is designed to expose
       network topology information to applications.  The ALTO
       Information Resource Directory (IRD) of an ALTO server
       describes the services supported by an ALTO server and
       corresponding attributes. As defined in <xref
       target="I-D.ietf-alto-protocol"/>, each information resource
       has several associated attributes, including an assigned
       identifier, a response format, capabilities, accepted input
       parameters, and other resources that it may depend on. Prior to
       obtaining ALTO guidance, ALTO client may retrieve the
       Information Resource Directory from the ALTO server to
       determine the attributes of individual information resources
       that this ALTO Server provides.</t>

       <t>The ALTO protocol is designed to be extensible, and several
       protocols extensions have been suggested, including for
       instance <xref target="I-D.roome-alto-pid-properties"/> or
       <xref target="I-D.randriamasy-alto-multi-cost"/>. In addition
       to such extensions of the ALTO protocol, an ALTO server may be
       willing to offer additional network information and guidance
       beyond the base functionality of the ALTO protocol. In this
       case, one option is to specify the offered guidance using YANG
       <xref target="RFC6020"/> as data modeling language.</t>

       <t>This document specifies an optional ALTO extension that
       enables ALTO clients to discover and query additional data
       offered by an ALTO server, being defined by YANG modules. This
       document describes the corresponding extensions of the ALTO
       Information Resource Directory and other required
       mechanisms.</t>

    </section>

    <section title="Terminology">
       
      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
      "OPTIONAL" in this document are to be interpreted as described
      in <xref target="RFC2119"/>.</t>

    </section>

    <section title="ALTO Network Topology Exposure vs. Network Configuration">
    
      <t>ALTO is designed as a protocol between clients integrated in
      applications and servers that provide network information and
      guidance (e.g., basic network location structure and preferences
      of network paths). The objective is to modify network resource
      consumption patterns at application level while maintaining or
      improving application performance. The basic information of ALTO
      is based on an abstract representation of the network as it
      matters to applications at endpoints.</t>

      <t>Given the focus on topology exposure to guidance, there are
      several differences between ALTO and other protocols used for
      network management, such as SNMP <xref target="RFC3411"></xref>
      or NETCONF <xref target="RFC6241"></xref>:</t>

      <t><list style="symbols">
        <t>Specialization: ALTO is an optimized protocol focused on
        exposing network topology data. This is different to
        general-purpose protocols.</t>

        <t>Read-only: ALTO is a query/response protocol to retrieve
        data. Neither ALTO network/cost map queries nor queries to the
        ALTO endpoint property or cost services are designed to affect
        state in the ALTO server or in the ALTO client.  Network
        management protocols are typically designed to manipulate the
        configuration of network devices.</t>

        <t>Trust model: The ALTO protocol has been designed for use
        cases where the ALTO server and client can be located in
        different organizations or trust domains. Network
        configuration will require a much stronger security model.</t>

	<t>Non-NMS applications: ALTO is designed for applications
	that perform resource selections among endpoints, e.g., in an
	application overlay. Such applications are typically not part
	of an Element Management System (EMS) or Network Management
	System (NMS).</t>

        <t>A priori knowledge: ALTO does not assume that an ALTO
        client has any a priori knowledge about the ALTO server and
        its supported features. An ALTO server can be discovered
        automatically. In network management, there is often a need
        for explicit configuration, e.g., of security credentials.</t>

        <t>Terminology: In ALTO, the application is running a client,
        while the network offers a service by means of a server. SNMP
        would use the terms manager and agent for these entities, and
        NETCONF may use the terms server and client in the opposite
        way. This reflects the different usage patterns.</t>
      </list></t>

      <t>These aspects are also detailed in <xref
      target="I-D.ietf-alto-deployments"/>.</t>

      <t>The same differences also apply to control plane protocols
      designed to configure state on network elements, such as
      components of a Path Computation Element (PCE) architecture or
      an Interface to the Routing System (I2RS).</t>

    </section>

    <section title="Benefits of Using YANG Data Models">

      <t>Despite different use cases, ALTO clients could use a limited
      set of functions originally designed for network management,
      including protocol functions for read-only retrieval of
      data. For instance, an ALTO server may use network monitoring
      data or Operations, Administration, and Maintenance (OAM)
      measurement results as data sources <xref
      target="I-D.ietf-alto-deployments"/>, and that data could
      originate from Network Management Systems (NMS). If permitted by
      privacy policies, an ALTO server could be willing to optionally
      expose such input data used by the ALTO service to ALTO
      clients.</t>
      
      <t>In that case, a straightforward solution is to transform that
      input data into a format supported by ALTO, e.g., network and
      cost maps with additional cost metrics. Yet, if the ALTO server
      already queries data specified in YANG <xref target="RFC6020"/>,
      it could optionally also expose that data to ALTO clients,
      provided that the aforementioned restrictions are taken into
      account.</t>

      <t>Support of YANG modules would be a simple way for an ALTO
      server to offer optional, additional services, e.g., to access
      monitoring data. A data model described in YANG could enable an
      ALTO client to easily determine the type of additional data
      exposed by ALTO, since a YANG module specifies the corresponding
      syntax.</t>

      <t>As a specific example, an ALTO server may have access to
      interface statistics for endpoints in the network, using the
      YANG module "ietf-interfaces" <xref target="RFC7223"/>, and it
      may use these statistics to e.g. to calculate network and cost
      maps. If an ALTO client would specifically be interested in
      counter metrics such as "out-errors", the ALTO server could
      obviously expose this by ALTO, e.g., as several cost maps or as
      an endpoint/PID property <xref
      target="I-D.roome-alto-pid-properties"/>. An alternative
      approach would be that the ALTO server natively exposes that
      data in a YANG-based format. This requires a solution to support
      YANG modules in ALTO.</t>

    </section>

    <section title="Extending ALTO to Support YANG Modules">

      <t>This section specifies how an ALTO server can announce the
      support of additional, optional services defined by YANG
      modules.</t>

      <section title="ALTO Information Resource Directory">

	<t>According <xref target="I-D.ietf-alto-protocol"/>, objects in
	the ALTO Information Resource Directory (IRD) have the following
	format:</t>

<t><figure><artwork><![CDATA[
  object {
    JSONString      uri;
    JSONString      media-type;
    [JSONString     accepts;]
    [Capabilities   capabilities;]
    [ResourceID     uses<0..*>;]
  } IRDResourceEntry;
]]></artwork></figure></t>

        <t>The extension in this document use this format and defines
        the following setting of these objects:</t>

        <t><list style="symbols">

          <t>uri: A URI at which the data is provided. This can both
          be an URI at the ALTO server, or it can delegate to another
          server (Section 9.2.4 of <xref
          target="I-D.ietf-alto-protocol"/>). This extension uses the
          URI to refer to data described in YANG modules.</t>

	  <t>media-type: The media type that is to be used by GET (or
	  POST) requests to the corresponding URI. This is further
	  detailed below.</t>

	  <t>accepts: This optional parameter can also be set if
	  required, as described in <xref
	  target="I-D.ietf-alto-protocol"/>.</t>

	  <t>capabilities: Capabilities are optional. A server MAY
	  announce the use of YANG as data modeling language for
	  certain resources as a capability ("yang" : true), if
	  this is not already implied by the media-type. Further
	  capabilities might be used to describe the YANG modules,
	  but this is TBD.</t>

	  <t>uses: The setting of this parameter is for further
	  study. According to <xref target="I-D.ietf-alto-protocol"/>,
	  this setting can be used to define other resources on which
	  this resource directly depends. As a result, it could for
	  instance be used to refer to ALTO cost maps that are related
	  to the data described in this resource refering to YANG
	  modules.</t>

        </list></t>

	<t>An example of a corresponding ALTO Information Resource
	Directory entry would be:</t>

<t><figure><artwork><![CDATA[
  ...
  "my-own-map-data" : {
    "uri" : 
      "http://alto.example.com/restconf/data/my-own-map-data",
    "media-type" : "application/yang.data+json",
    "capabilities" : {
      "yang" : true
    }
  },
  ...
]]></artwork></figure></t>

      </section>

      <section title="JSON Encoding">

	<t>The ALTO protocol uses a REST-ful design and encodes its
	requests and responses using JSON <xref target="RFC4627"/>.
	Therefore, all data returned using this specification MUST be
	encoded in JSON.</t>

	<t><xref target="I-D.ietf-netmod-yang-json"/> defines rules
	for representing data defined using YANG as JSON text.</t>

      </section>

      <section title="YANG Data Model Assumptions">

	<t>YANG can model configuration data as well as state data.
	The latter is marked by the "config false" statement <xref
	target="RFC6020"/>. State data on a system is no configuration
	data and cannot be changed, such as read-only status
	information and collected statistics. When a node in a YANG
	module is tagged with "config false", its sub-hierarchy is
	flagged as state data as well.</t>

	<t>Since ALTO only offers read-only access to information,
	this document implicitly assumes that the URI announced by an
	ALTO server only exposes read-only data. This document only
	describes how an ALTO client can discover the URI for
	additional data and learn now to retrieve data by a REST
	protocol from there; the actual communication and
	interpretation of data is outside the scope of this
	document.</t>

	<t>Read-only access can trivially be enforced if an ALTO
	server using the mechanism in this document only use YANG
	modules that contain state data only, i.e., all containers,
	lists, and leafs etc. are be covered by "config false"
	statements. Alternatively, there could be ways to ensure
	read-only access, e.g., by appropriate selection of the
	URI.</t>

	<t>Any write access by a client using the information in the
	ALTO IRD is outside the scope of this memo.</t>

	<t>This document does not cover notifications. The handling of
	"notifications" in a YANG module is therefore outside the
	scope of the document.</t>

	<t>The handling of "rpc" statements in a YANG module is for
	further study.</t>

      </section>

      <section title="Media Type">

	<t>This document does not register additional media types.  An
	ALTO client SHOULD use the media type(s) defined in the ALTO
	IRD to access the URI, as detailed in the next section.</t>

	<t>An example media type could be "application/yang.data+json"
	as defined in <xref target="I-D.ietf-netconf-restconf"/>.</t>

      </section>

      <section title="Accessing the URI">

	<t>The way to retrieve data from the URI returned by the ALTO
	IRD depends on the media type. An ALTO client can determine
	from the media type whether it supports the method and whether
	optional data from an ALTO server can be retrieved. This
	document describes an optional ALTO extension and does not
	mandate that an ALTO client supports any specific
	protocol.</t>

	<t>One approach to retrieve additional data described by a
	YANG model would be RESTCONF <xref
	target="I-D.ietf-netconf-restconf"/>. In this case, the ALTO
	IRD is basically used as a discovery mechanism for
	corresponding RESTCONF URIs. For RESTCONF, the syntax of the
	URI, as well as the protocol for data retrieval is defined in
	<xref target="I-D.ietf-netconf-restconf"/>. For instance, a
	valid URI would be
	"http://alto.example.com/restconf/data/my-own-map-data", and a
	corresponding media type could be "application/yang.api".  If
	the URI points to the RESTCONF root, the client could also use
	other APIs as defined in <xref
	target="I-D.ietf-netconf-restconf"/>, e.g., to retrieve the
	YANG module definition file. The latter would enable an ALTO
	client to dynamically learn the YANG module definitions.</t>

	<t>In a simpler variant, an ALTO server would just return the
	complete tree of state data encoded in JSON <xref
	target="I-D.ietf-netmod-yang-json"/>. This could be sufficient
	for extensions equivalent to the current ALTO network and cost
	map services without filtering, which always return all
	available data without fine-grained query access. Details of
	this mode are for further study.</t>

      </section>

    </section>

    <section title="Example">

      <t>In the following, we illustrate the mechanism described in
      this document with a simple example.</t>

      <t>The initial query of an ALTO client to an ALTO server's IRD
      could be:</t>

<t><figure><artwork><![CDATA[
  GET /directory HTTP/1.1
  Host: alto.example.com
  Accept: application/alto-directory+json,
          application/alto-error+json
]]></artwork></figure></t>

      <t>The server would then return the supported ALTO services,
      including the one specified in this document:</t>      

<t><figure><artwork><![CDATA[
  HTTP/1.1 200 OK
  Content-Length: TBD
  Content-Type: application/alto-directory+json

  {
    "meta" : {
       ...
    },
    "resources" : {
       ...
       "my-own-map-data" : {
          "uri" :
            "http://alto.example.com/restconf/data/my-own-map-data",
          "media-type" : "application/yang.data+json",
          "capabilities" : {
            "yang" : true
          }
        },
       ...
    }
  }
]]></artwork></figure></t>

      <t>Since the media type refers to <xref
      target="I-D.ietf-netconf-restconf"/>, a follow-up query of
      the ALTO client supporting this protocol could be:</t>

<t><figure><artwork><![CDATA[
  GET /restconf/data/my-own-map-data  HTTP/1.1
  Host: alto.example.com
  Accept: application/yang.data+json
]]></artwork></figure></t>

      <t>The response of the server is outside the scope of this
      document and depends on the YANG data model accessed by that
      URI. For instance, assume the following trivial model of an
      extension just giving a convenient list of the PIDs currently
      used by the ALTO server:</t>

<t><figure><artwork><![CDATA[
  module my-own-map-data {
    ...
    container my-own-map-data {
      config false;
      list pid-list {
        key pid;
        leaf pid {
          type string;
        }
      }
    }
    ...
  }
]]></artwork></figure></t>

      <t>Then, the server response could be:</t>      

<t><figure><artwork><![CDATA[
  HTTP/1.1 200 OK
  Content-Length: TBD
  Content-Type: application/yang.data+json

  {
    "my-own-map-data" : {
      "pid-list" : [
        {
          "pid" : "PID1",
        },
        {
          "pid" : "PID2",
        },
        ...
        {
          "pid" : "PID9",
        }
      ]
    }
  }
]]></artwork></figure></t>

      <t>This is a trivial example, but the same principle is
      applicable to any YANG module. Obviously, an ALTO client has to
      support processing of the corresponding YANG module (or modules)
      to make use of this extension.</t>

    </section>

    <section title="IANA Considerations">
       
      <t>TBD</t>

    </section>

    <section title="Security Considerations">
       
      <t>This document descibes read-only access to data optionally
      announced by an ALTO server. The security considerations of the
      ALTO protocol as detailed in <xref
      target="I-D.ietf-alto-protocol"/> and <xref
      target="I-D.ietf-alto-deployments"/> apply to the ALTO extension
      in this document. Specifically, the operator of an ALTO server
      has to ensure that there is no unauthorized access to sensitive
      data. This extension should not be used if there are privacy
      concerns.</t>

    </section>

    <section title="Conclusion">

      <t>TBD</t>

    </section>

  </middle>

  <back>

    <references title="Normative References">

      <?rfc include="reference.RFC.2119"?>

      <?rfc include="reference.RFC.4627"?>

      <?rfc include="reference.RFC.6020"?>

      <?rfc include="reference.I-D.ietf-alto-protocol"?>

      <?rfc include="reference.I-D.ietf-netmod-yang-json"?>

      <?rfc include="reference.I-D.ietf-netconf-restconf"?>

    </references>

    <references title="Informative References">

      <?rfc include="reference.RFC.3411"?>

      <?rfc include="reference.RFC.6241"?>

      <?rfc include="reference.RFC.7223"?>

      <?rfc include="reference.I-D.roome-alto-pid-properties"?>

      <?rfc include="reference.I-D.randriamasy-alto-multi-cost"?>

      <?rfc include="reference.I-D.ietf-alto-deployments"?>

    </references>

  </back>

</rfc>