<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
     which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
     There has to be one entity for each item to be referenced. 
     An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs), 
     please see http://xml.resource.org/authoring/README.html. -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="3"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space 
     (using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="std" docName="draft-liu-netconf-multiple-replies-02"
     ipr="trust200902">
  <front>
    <title abbrev="Netconf Multi-replies">Processing Multiple Replies for One
    Request in NETCONF</title>

    <author fullname="Bing Liu" initials="B." surname="Liu">
      <organization>Huawei Technologies</organization>

      <address>
        <postal>
          <street>Q14, Huawei Campus, No.156 Beiqing Road</street>

          <city>Hai-Dian District, Beijing, 100095</city>

          <country>P.R. China</country>
        </postal>

        <email>leo.liubing@huawei.com</email>
      </address>
    </author>

    <author fullname="Guangying Zheng" initials="G." surname="Zheng">
      <organization>Huawei Technologies</organization>

      <address>
        <postal>
          <street>Huawei Nanjing R&amp;D Center</street>

          <city>101 Software Avenue, Yuhua District, Nanjing, Jiangsu,
          210012</city>

          <country>P.R. China</country>
        </postal>

        <email>zhengguangying@huawei.com</email>
      </address>
    </author>

    <author fullname="Mahesh Jethanandani" initials="M."
            surname="Jethanandani">
      <organization>Cisco Systems</organization>

      <address>
        <postal>
          <street/>

          <city/>

          <region/>

          <code/>

          <country>USA</country>
        </postal>

        <phone/>

        <facsimile/>

        <email>mjethanandani@gmail.com</email>

        <uri/>
      </address>
    </author>

    <author fullname="Kent Watsen" initials="K." surname="Watsen">
      <organization>Juniper Networks</organization>

      <address>
        <postal>
          <street/>

          <city/>

          <region/>

          <code/>

          <country/>
        </postal>

        <phone/>

        <facsimile/>

        <email>kwatsen@juniper.net</email>

        <uri/>
      </address>
    </author>

    <date day="22" month="March" year="2016"/>

    <area>OPS Area</area>

    <workgroup>netconf</workgroup>

    <keyword>netconf, multiple replies, block, persistent, long time response,
    datastore push</keyword>

    <abstract>
      <t>This document discusses several scenarios that multiple replies for a
      single request are needed, with the ability to terminate the replies at
      any time. Such scenarios are not well supported by current NETCONF
      (Network Configuration) protocol. An extention at the NETCONF messaging
      layer is needed to fulfill the requirement.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>The message procedures of NETCONF <xref target="RFC6241"/> are based
      on RPC (Remote Procedure Call) interactions. A NETCONF client/server
      sends a &lt;rpc&gt; message to the counterpart and then receives a
      replying &lt;rpc-reply&gt; message.</t>

      <t>In some situations, it might need multiple &lt;rpc-reply&gt; messages
      for a &lt;rpc&gt; request. For example, the the &lt;rpc-reply&gt;
      message might be very large that it needs to be fragmented into multiple
      small ones; or some operations (e.g. ping) need persistent replies till
      such time that a terminaing condition is encountered or when the
      operation is cancelled.</t>

      <t>This document discusses such kind of multiple replies scenarios,
      analyzes the issues of current NETCONF protocol in supporting these
      scenarios, and proposes several candidate solutions for discussion.</t>
    </section>

    <section title="Requirements Language and Terminology">
      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
      "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
      "OPTIONAL" in this document are to be interpreted as described in <xref
      target="RFC2119"/> when they appear in ALL CAPS. When these words are
      not in ALL CAPS (such as "should" or "Should"), they have their usual
      English meanings, and are not to be interpreted as <xref
      target="RFC2119"/> key words.</t>

      <t>Terminology:</t>

      <t>CLI: Command Line interface</t>

      <t>DOM: Document Object Model, which is a cross-platform and
      language-independent convention for representing and interacting with
      objects in HTML, XHTML and XML documents. Objects in the DOM tree may be
      addressed and manipulated by using methods on the objects.</t>

      <t>RPC: Remote Procedure Call</t>

      <t>SAX: Simple API for XML, which is an event sequential access parser
      API developed by the XML-DEV mailing list for XML documents. SAX
      provides a mechanism for reading data from an XML document that is an
      alternative to that provided by the DOM. Where the DOM operates on the
      document as a whole, SAX parsers operate on each piece of the XML
      document sequentially.</t>

      <t>libxml: a software library for parsing XML documents.</t>

      <t>&lt;get-block&gt;: a capability and operation defined in this
      document to handle large size &lt;rpe-reply&gt; messages.</t>
    </section>

    <section title="Scenarios and Problems">
      <t>This section discusses several scenarios where multiple replies might
      be needed, and anylizes the problems of current NETCONF protocol in
      supporting these scenarios.</t>

      <section title="Bulk &lt;rpc-reply&gt;">
        <t>The &lt;rpc-reply&gt; message might be very large in following
        situations:<list style="symbols">
            <t>retrieving a large amount of routes in a core router</t>

            <t>retrieving a large interface statistics list</t>

            <t>doing a full-synchronizing with a device</t>
          </list></t>

        <t>Current there are already some methods of processing bulk replies
        as the following. However, there are some issues as analyzed
        below.</t>

        <t>1) Stream-Oriented Handling</t>

        <t>Stream-Oriented handling mainly includes the following two
        aspects:</t>

        <t><list style="symbols">
            <t>The server encapsulates the large size replying data in a
            &lt;rpc-reply&gt; message and streams it to the client through
            transport protocol.</t>

            <t>The client parses the received &lt;rpc-reply&gt; content in a
            stream-oriented way. More specifically, the client could utilize
            SAX parsing to instantly parse the received content without
            waiting for the whole message been transported.</t>
          </list>The problems are:</t>

        <t><list style="symbols">
            <t>Stream-Oriented method lacks the capability of discontinuing
            large size processing in the server. It would cause unnecessary
            resource/performance cost in the devices if the NETCONF client has
            already got the intended portion or just canceled by the
            administrators.</t>

            <t>Another problem is the implementation of SAX parsing is more
            complex than DOM parsing in the NETCONF client. More computing
            burden will be taken to support SAX parsing.</t>
          </list>2) Requesting a Portion of Data</t>

        <t>The clients actively limit the search range of the data so that the
        servers only need to reply with a part of the large size data. Thus
        the clients could control the replies in a reasonable size. One
        example is that the clients get a list of the content, and provide a
        start offset and a max-count, to get a portion at a time.</t>

        <t>The problems are:</t>

        <t><list style="symbols">
            <t>This method has an implication that the client needs to know
            the list/index of the intended large size data in advance before
            it starting the search request. It can't fit the scenarios of
            real-time on-demand data retrieving. And there is no standard to
            specify the list/index format in a uniform way. Thus it is only
            suitable for private implementation, thus multi-vendor interaction
            is not supported.</t>

            <t>More important, it is just an indirect way to solve the
            problem. It could not fit the scenarios where the client just
            needs the whole large size data in the server.</t>
          </list></t>
      </section>

      <section title="Persistent &lt;rpc-reply&gt;">
        <t>One of the operations that CLI offers today is the ability to issue
        an operation that might result in multiple responses being returned,
        till such time that a terminaing condition is encountered or when the
        operation is cancelled. An example of such an operation is when the
        ping or a traceroute command is issued. In the former case, the
        operation can continue sending responses back till it is cancelled,
        while in the latter case there is usually a terminating condition that
        stops the responses.</t>

        <t>NETCONF protocol as defined today sends a single RPC request and
        expects a single reply to that request. The "persistent" operation
        defined above expects multiple responses for a single request, till
        such time a terminating condition is encountered.</t>
      </section>

      <section title="Long time &lt;rpc-reply&gt;">
        <t>Some operations might take a long time to perform (e.g. network
        link performance validation), so there could be multiple responses for
        the request. For example, initial responses returns handle which the
        client uses to monitor progress till the final result. The client
        should be able to cancel the request at any time.</t>
      </section>

      <section title="Datastore push updates">
        <t>In <xref target="I-D.clemm-netconf-yang-push"/> and <xref
        target="I-D.ietf-i2rs-pub-sub-requirements"/>, it describes a scenario
        where client applications need to request updates from a YANG
        datastore, without requiring additional client requests. <xref
        target="I-D.clemm-netconf-yang-push"/> proposes to extend notification
        messaging to fulfill the requirement that a comprehensive
        subsription/publication model could be well supported.</t>

        <t>The datastore sub/pub might need specific data modeling and
        operation extention. However, at the NETCONF message layer, this draft
        considers multiple replies could be an alternative solution for
        sub/pub comparing with notification messaging extention.</t>

        <t>[Open Question] Need more in-depth analysis and comparison of the
        two alternatives.</t>
      </section>
    </section>

    <section title="Requriments for NETCONF">
      <t>Given above mentioned multiple-replies scenarios and problems, the
      requriments for NETCONF protocol could be summarized as a mechanism with
      the following abilities:<list style="symbols">
          <t>be able to generate and handle multiple &lt;rpc-reply&gt;
          messages for a given &lt;rpc&gt; message</t>

          <t>be able to terminate the &lt;rpc-reply&gt; at any time</t>

          <t>be able to cancel the request in pipeline scenarios</t>
        </list></t>
    </section>

    <section title="Candidate Solutions">
      <t>(Editor notes: this section discusses possible solutions. The
      fragmentation mechanism is from the draft <xref
      target="I-D.liu-netconf-fragmentation"/>. The other one was proposed
      during mailing list discussion by Juergen Schoenwaelder. We include both
      of them for discussion and solution selection.)</t>

      <section title="Get-block Mechanism">
        <t>This section proposes a method of extending the NETCONF protocol to
        allow handling the replying data as multiple &lt;rpc-reply&gt; blocks.
        It allows the NETCONF client to terminate the block data processing
        momentarily by protocol interactions; and also allows the blocked
        messages to be instantly parsed piece by piece. Specifically, the
        mechanism is achieved by a newly defined &lt;get-block&gt; capability
        and relevant operations.</t>

        <section title="Design Requirements">
          <t>Two essential requirements of the Get-block mechanism are: <list
              style="symbols">
              <t>It needs to allow the NETCONF client to terminate the data
              processing momentarily by protocol interactions. In the proposed
              mechanisms in this draft, when the NETCONF server replies the
              client an &lt;rpc-reply&gt;, it will wait the response from the
              client that whether it needs to send the next block. So if the
              initiator has got the intended portion, it could terminate the
              process immediately.</t>

              <t>It needs to allow the NETCONF client to instantly parse the
              blocks piece by piece through the more widely supported DOM
              parsing. So in this document, it specifies that each
              &lt;rpc-reply&gt; block MUST be in a complete XML form.</t>
            </list></t>

          <t>(Editor notes: this solution was originally designed for large
          size fragmentation processing. However, the rationale of this
          solution has the potential to fulfill the other scenarios.)</t>
        </section>

        <section title="&lt;get-block&gt; extention">
          <t>o Function<list style="empty">
              <t>The devices can only use &lt;get-block&gt; operation when the
              Get-block capability was announced.</t>

              <t>The &lt;get-block&gt; rules are:<list style="letters">
                  <t>There should be a Max-Size for each block. [Open
                  Question]Should there be a clear specification of the size?
                  E.g. 64K bytes.</t>

                  <t>When the message reaches the Max-Size, it is sent to the
                  client and the next message could be created in advance.</t>

                  <t>Different records from one same table could be put into
                  different &lt;rpc-reply&gt; messages</t>

                  <t>All of the fields in one record MUST be put into one
                  &lt;rpc-reply&gt; message.</t>

                  <t>XML syntax MUST be complete in each block message, so
                  that each block could be parsed individually.</t>

                  <t>If the record(s) of the child node(s)/table(s) and the
                  parent node(s)/table(s) are replied in different blocks, the
                  child node/table block MUST include the path and index
                  information of all the ancestor node(s)/table(s) in a
                  hierarchical mode.</t>
                </list></t>
            </list></t>

          <t>o Parameters<list style="empty">
              <t>&lt;discard/&gt;: in &lt;get-block&gt; operation, if the
              &lt;discard/&gt; parameter is conveyed, it means the operation
              is terminated. Then it doesn't need to reply the remaining
              blocks.</t>
            </list></t>

          <t>o Successful Operation Reply<list style="empty">
              <t>A &lt;rpc-reply&gt; message conveying a &lt;data&gt; element
              indicates the operation is successful.</t>

              <t>If there exists a next block, then an set-id attribute MUST
              be included in the &lt;rpc-reply&gt; messge. The attribute
              set-id is used to identify different block sets.</t>
            </list></t>

          <t>o Exception Handling<list style="empty">
              <t>After the NETCONF server replies a block, if there is no
              corresponding Get-block request from the client in a reasonable
              period (the time valued to be specified in the future), then the
              server release the offset of the replying data and cannot use
              &lt;get-block&gt; operation anymore, and the remaining data
              needs to be replied.</t>
            </list></t>

          <t>Please refer to <xref target="example-frag"/> for an example.</t>
        </section>
      </section>

      <section title="Linked Replies">
        <t>Another solution is to change or augment NETCONF at some point in
        time such that an &lt;rpc&gt; can lead to a sequence of
        &lt;rpc-reply&gt; with a suitable cancel mechanism. A simple approach
        is to add a linked-replies capability. If a server announces
        "linked-replies" capablility and the client supports it as well, the
        client can add an additional parameter to an rpc to indicate the
        possible use of linked-replies.</t>

        <t>Please refer to <xref target="example-linked"/> for an example.</t>

        <t>This would address the concern of large data retrievals but would
        also allow long running asynchronous rpcs (the ping or traceroute
        example). This approach may lead to better support for asynchronous
        rpcs and rpcs that potentially return very large chunks of data than
        trying to solve this problem without enhancements of the rpc layer.
        Design details concerning data merging, error handling, how to send a
        cancel for a given link-id (e.g., by sending a new &lt;rpc-cancel&gt;
        message with a matching link-id) and whether it is necessary to
        negotiate linked rpc-reply sizes or whether it is good enough for the
        server to decide freely as it likes etc. need further study.</t>
      </section>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>TBD.</t>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This draft does not request any IANA action.</t>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>Gang Yan and Shouchuan Yang made significant contribution to form the
      draft. Valuable comments were received from Andy Bierman, Juergen
      Schoenwaelder, Balazs Lengyel, Martin Bjorklund, Chong Feng and some
      other people in Netconf working group.</t>

      <t>This document was produced using the xml2rfc tool <xref
      target="RFC2629"/>. (initiallly prepared using 2-Word-v2.0.template.dot.
      )</t>

      <t/>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include='reference.RFC.2119'?>

      <?rfc include='reference.RFC.2629'?>

      <?rfc include='reference.RFC.6241'?>
    </references>

    <references title="Informative References">
      <?rfc include='reference.I-D.clemm-netconf-yang-push'?>

      <?rfc include='reference.I-D.ietf-i2rs-pub-sub-requirements'?>

      <?rfc include='reference.I-D.liu-netconf-fragmentation'?>
    </references>

    <section title="Examples of the Candidate Solutions">
      <t/>

      <section anchor="example-frag" title="&lt;get-block&gt; Example">
        <t><figure>
            <artwork><![CDATA[Example 1: Get the next block
     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:NETCONF:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/config">
             <users/>
           </top>
         </filter>
       </get-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:NETCONF:base:1.0"
          xmlns:hw=http://example.com/NETCONF/capability/base/1.0
hw:set-id="101">
       <data>
         <top xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>root</name>
               <type>superuser</type>
               <full-name>Charlie Root</full-name>
               <company-info>
                 <dept>1</dept>
                 <id>1</id>
               </company-info>
             </user>
             <!-- additional <user> elements appear here... -->
           </users>
         </top>
       </data>
     </rpc-reply>

<rpc message-id="102"
          xmlns="urn:ietf:params:xml:ns:NETCONF:base:1.0">
       <get-block xmlns="http://example.com/NETCONF/capability/base/1.0"
set-id="1">
       </get-block>
     </rpc>
     <rpc-reply message-id="102"
          xmlns="urn:ietf:params:xml:ns:NETCONF:base:1.0" 
          xmlns:hw=http://example.com/NETCONF/capability/base/1.0
hw:set-id="101">
       <data>
         <top xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>admin</name>
               <type>commonuser</type>
               <full-name>Jim Green</full-name>
               <company-info>
                 <dept>9</dept>
                 <id>90</id>
               </company-info>
             </user>
             <!-- additional <user> elements appear here... -->
           </users>
         </top>
       </data>
     </rpc-reply>

Example 2: Abandon the remaining blocks
     <rpc message-id="103"
          xmlns="urn:ietf:params:xml:ns:NETCONF:base:1.0">
       <get-block xmlns=http://example.com/NETCONF/capability/base
        /1.0 set-id="1">
         <discard/>
       </get-block>
     </rpc>

     <rpc-reply message-id="103"
          xmlns="urn:ietf:params:xml:ns:NETCONF:base:1.0">
       <ok/>
     </rpc-reply>

Example 3: Following is an example of the rule f in Section 4.1.2. 
The child eTable is in a different message with the parents 
aTable->bTable->cTable->dTable. Then the path and index information 
of all the ancestors MUST included in the search data. 

<aTable>
  <aEntity>
  <aIndex1>
  </aEntity>
  <bTable>
    <bEntity>
<bIndex1>
</bEntity>
<eTable>
  <eEntity>
    <eIndex1>
    <ef2>
    <ef3>
  </eEntity>
</dTable>
  </bTable>
</aTable>

]]></artwork>
          </figure></t>
      </section>

      <section anchor="example-linked" title="Linked-replies Example">
        <t><figure>
            <artwork><![CDATA[Here is what a new client might do if it wants to use linked replies:

<rpc message-id="101" link-id="123" xmlns="...">
</rpc>

The server can either simply send an rpc-reply or it starts sending
linked replies, e.g.:

<rpc-reply message-id="101" next-message-id="101" link-id="123" xmlns="...">
</rpc-reply>

<rpc-reply message-id="101" next-message-id="101" link-id="124" xmlns="...">
</rpc-reply>

<rpc-reply message-id="101" link-id="125" xmlns="...">
</rpc-reply>
]]></artwork>
          </figure></t>
      </section>
    </section>
  </back>
</rfc>
