Subject: [Capwap] Issue 143: Data Transfer Request is too ambiguous

From: "Pat Calhoun (pacalhou)" <[email-masked]>
Date: Mon, 7 Jul 2008 10:57:08 -0700

All,

Yong has raised a series of questions about the use of the Data Transfer
Request/Response which are pointing out that the text is simply too
ambiguous. I looked at the text again, and I agree that it needs work.
Some time ago we had agreed to clean up the Image Transfer exchanges to
allow the AC to know the size of the data being transfered, etc. We also
agreed to include figures to help provide more clarity on how the
exchange occurred. 

Clearly, we need something similar for the Data Transfer section.
Furthermore, I have found a bug that the Data Transfer Request currently
states that it cannot be sent by the AC, which is incorrect. The AC is
supposed to send this in order to request the information to begin with.

Please see the following proposed text to handle this issue. Note that
this will "sort-of" break compatibility with -10 but I doubt we will see
any issues because -10 had no way for the AC to initiate the request.

<text>
2.3.1.  CAPWAP Protocol State Transitions
[...]
   Run to Run (q):  This is the normal state of operation.

      WTP:  This is the WTP's normal state of operation.  There are many
         events that result this state transition:
[...]
         Data Transfer:  The WTP sends a Data Transfer Request or Data
            Transfer Response message to the AC (see Section 9.6).  The
            WTP receives a Data Transfer Request or Data Transfer
            Response message from the AC (see Section 9.6).  Upon
            receipt of a Data Transfer Request, the WTP transmits a Data
            Transfer Response to the AC.
[...]
      AC:  This is the AC's normal state of operation:
[...]
         Data Transfer:  The AC sends a Data Transfer Request or Data
            Transfer Response message to the WTP (see Section 9.6).  The
            AC receives a Data Transfer Request or Data Transfer
            Response message from the WTP (see Section 9.6).  Upon
            receipt of a Data Transfer Request, the AC transmits a Data
            Transfer Response to the WTP.
4.6.16.  Data Transfer Data

   The Data Transfer Data message element is used by the WTP to provide
   information to the AC for debugging purposes.

      0                   1                   2                   3
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |   Data Type   |      Data Length      |        Data ....
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Type:   16 for Data Transfer Data

   Length:   >= 3

   Data Type:   An 8-bit value representing the transfer Data Type.  The
      following enumerated values are supported:

      1 -  Transfer data is included

      2 -  Last Transfer Data Block is included (EOF)

      5 -  An error occurred.  Transfer is aborted

   Data Length:   Length of data field, with a maximum size of 65535.

   Data:   Debug information.

9.6.  Data Transfer

   This section describes the data transfer procedures used by the
   CAPWAP protocol.  The data transfer mechanism is used to upload
   information available at the WTP to the AC, such as crash or debug
   information.  The data transfer messages can only be exchanged while
   in the Run state.

   Figure 10 provides an example of an AC that requests that the WTP
   transfer its latest crash file.  Once the WTP acknowledges that it
   has information to send, via the Data Transfer Response, it transmits
   its own Data Transfer Request.  Upon receipt, the AC responds with a
   Data Transfer Response, and the exchange continues until the WTP
   transmits a Data Transfer Data message element that indicates an End
   of File (EOF).

             WTP                                               AC

           Data Transfer Request (Data Transfer Mode = Crash Data)
         <------------------------------------------------------

              Data Transfer Response (Result Code = Success)
         -------------------------------------------------------->

              Data Transfer Request (Data Transfer Data = Data)
         -------------------------------------------------------->

              Data Transfer Response (Result Code = Success)
         <------------------------------------------------------

                                  .....

                Data Transfer Request (Data Transfer Data = EOF)
         <------------------------------------------------------

              Data Transfer Response (Result Code = Success)
         -------------------------------------------------------->

                    Figure 10: WTP Data Transfer Case 1

   Figure 11 provides an example of an AC that requests that the WTP
   transfer its latest crash file.  However, in this example, the WTP
   does not have any crash information to send, and therefore sends a
   Data Transfer Response with a Result Code indicating the error.

            WTP                                               AC

          Data Transfer Request (Data Transfer Mode = Crash Data)
        <------------------------------------------------------

             Data Transfer Response (Result Code = Data Transfer
                                     Error (No Information to Transfer))
        -------------------------------------------------------->

                    Figure 11: WTP Data Transfer Case 2

9.6.1.  Data Transfer Request

   The Data Transfer Request message is used to deliver debug
   information from the WTP to the AC.

   The Data Transfer Request messages can be sent either by the AC or
   the WTP.  When sent by the AC, it is used to request that data be
   transmitted from the WTP to the AC, and includes the Data Transfer
   Mode message element, which specifies the information desired by the
   AC.  The Data Transfer Request is sent by the WTP in order to
   transfer actual data to the AC, through the Data Transfer Data
   message element.

   Given that the CAPWAP protocol minimizes the need for WTPs to be
   directly managed, the Data Transfer Request is an important
   troubleshooting tool used by the AC to retrieve information that may
   be available on the WTP.  For instance, some WTPs implementations may
   store crash information to help manufacturers identify software
   faults.  The Data Transfer Request message can be used to send such
   information from the WTP to the AC.  Another possible use would be to
   allow a remote debugger function in the WTP to use the Data Transfer
   Request message to send console output to the AC for debugging
   purposes.

   When the WTP or AC receives a Data Transfer Request message it
   responds to the WTP with a Data Transfer Response message.  The AC
   MAY log the information received through the Data Transfer Data
   message element.

   The Data Transfer Request message is sent by the WTP or AC when in
   the Run State.

   When sent by the AC, the Data Transfer Request message MUST contain
   the following message elements:

   o  Data Transfer Mode, see Section 4.6.17

   When sent by the WTP, the Data Transfer Request message MUST contain
   the following message elements:

   o  Data Transfer Data, see Section 4.6.16

   Regardless of whether the Data Transfer Request is sent by the AC or
   WTP, the following message elements MAY be included in the Data
   Transfer Request message:

   o  Vendor Specific Payload, see Section 4.6.39

9.6.2.  Data Transfer Response

   The Data Transfer Response message acknowledges the Data Transfer
   Request message.

   A Data Transfer Response message is sent in response to a received
   Data Transfer Request message.  Its purpose is to acknowledge receipt
   of the Data Transfer Request message.  When sent by the WTP, the
   Result Code message element is used to indicate whether the data
   transfer requested by the AC can be completed.  When sent by the AC,
   the Result Code message element is used to indicate receipt of the
   data transfered in the Data Transfer Request message.

   The Data Transfer Response message is sent by the WTP or AC when in
   the Run State.

   The following message element MUST be included in the Data Transfer
   Response message.

   o  Result Code, see Section 4.6.35

   The following message elements MAY be included in the Data Transfer
   Response message:

   o  Vendor Specific Payload, see Section 4.6.39

   Upon receipt of a Data Transfer Response message, the WTP transmits
   more information, if more information is available.
</text>

PatC
_________________________________________________________________
To unsubscribe or modify your subscription options, please visit:
http://lists.frascone.com/mailman/listinfo/capwap

Archives: http://lists.frascone.com/pipermail/capwap