Subject: [Capwap] Issue 165: Image Download inconsistencies

From: "Pat Calhoun (pacalhou)" <[email-masked]>
Date: Tue, 29 Jul 2008 13:24:41 -0700

Pasi's comment was:

   Section 4.6.30 (Initiate Download): there's no message element named
   "Image Download"
and
   Section 4.6.28 (Image Identifier) says this message element is sent
by
   the AC to the WTP; but according to Section 9.1, it can also be sent
by
   the WTP?
and
   Section 9.1.2: should say that "Image Information" and "Initiate
   Download" elements are included only when this message is sent by the
AC.

This is another area that Pasi fortunately caught that is has some bugs.
I just went through the text, and there were some inconsistencies, not
to mention exchanges that made no sense. For instance, the AC would send
the Initiate Download, but it is really the WTP's decision to initiate
the download so that needed to be fixed. Further, as Pasi found out,
there was a reference to a message element that did not exist (Image
Download), inconsistencies on whom should send what, etc. In fact, even
in the four scenarios that are described in section 9.1, use case four
was inconsistent with use case three.

So I have cleaned up the text, and we have, what I now believe is good
text. Of course, I would appreciate a review.

Unfortunately, a diff only of section 9.1 would be too hard to follow,
so I will include the whole section with the use cases.

<new text>
4.6.28.  Image Identifier

   The Image Identifier message element is sent by the AC to the WTP to
   indicate the expected active software version that is to be run on
   the WTP.  The WTP sends the Image Identifier message element in order
   to request a specific software version from the AC.  The actual
   download process is defined in Section 9.1.  The value is a variable
   length UTF-8 encoded string [RFC3629], which is NOT zero terminated.
[...]

4.6.29.  Image Information

   The Image Information message element is present in the Image Data
   Response message sent by the AC to the WTP and contains the following
   fields.
[...]

4.6.30.  Initiate Download

   The Initiate Download message element is used by the WTP to inform
   the AC that the AC SHOULD initiate a firmware upgrade.  The AC
   subsequently transmits an Image Data Request message which includes
   the Image Data message element.  This message element does not
   contain any data.
[...]

6.2.  Join Response
[...]
   The AC includes the Image Identifier message element to indicate the
   software version it expects the WTP to run.  This information is used
   to determine whether the WTP MUST either change its currently running
   firmware image, or download a new version (see Section 9.1.1).

8.4.  Configuration Update Request
[...]
   The AC includes the Image Identifier message element (see
   Section 4.6.28) to force the WTP to update its firmware while in the
   Run state.  The WTP MAY proceed to download the requested firmware if
   it determines the version specified in the Image Identifier message
   element is not in its non-volatile storage by transmitting an Image
   Data Request (see Section 9.1.1) that includes the Initiate Download
   message element (see Section 4.6.30).

9.1.  Firmware Management

   This section describes the firmware download procedures used by the
   CAPWAP protocol.  Firmware download can occur during the Image Data
   or Run state.

   Figure 6 provides an example of a WTP that performs a firmware
   upgrade while in the Image Data state.  In this example, the WTP does
   not already have the requested firmware (Image Identifier = x), and
   downloads the image from the AC.

             WTP                                               AC

                                Join Request
         -------------------------------------------------------->

                     Join Response (Image Identifier = x)
         <------------------------------------------------------

              Image Data Request (Image Identifier = x,
                                  Initiate Download)
         -------------------------------------------------------->

           Image Data Response (Result Code = Success,
                                Image Information = {size,hash})
         <------------------------------------------------------

                Image Data Request (Image Data = Data)
         <------------------------------------------------------

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

                                  .....

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

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

                     (WTP enters the Reset State)

                  Figure 6: WTP Firmware Download Case 1

   Figure 7 provides an example in which the WTP has the image specified
   by the AC in its non-volative storage, but is not its current running
   image.  In this case, the WTP opts to NOT download the firmware and
   immediately reset to the requested image.

             WTP                                               AC

                                Join Request
         -------------------------------------------------------->

                     Join Response (Image Identifier = x)
         <------------------------------------------------------

                     (WTP enters the Reset State)

                  Figure 7: WTP Firmware Download Case 2

   Figure 8 provides an example of a WTP that performs a firmware
   upgrade while in the Run state.  This mode of firmware upgrade allows
   the WTP to download its image while continuing to provide service.
   The WTP will not automatically reset until it is notified by the AC,
   with a Reset Request message.

             WTP                                               AC

                Configuration Update Request (Image Identifier = x)
         <------------------------------------------------------

            Configuration Update Response (Result Code = Success)
         -------------------------------------------------------->

              Image Data Request (Image Identifier = x,
                                  Initiate Download)
         -------------------------------------------------------->

              Image Data Response (Result Code = Success,
                                   Image Information = {size,hash})
         <------------------------------------------------------

                Image Data Request (Image Data = Data)
         <------------------------------------------------------

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

                                  .....

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

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

                                  .....

                (administratively requested reboot request)
                   Reset Request (Image Identifier = x)
         <------------------------------------------------------

                  Reset Response (Result Code = Success)
         -------------------------------------------------------->

                  Figure 8: WTP Firmware Download Case 3

   Figure 9 provides another example of the firmware download while in
   the Run state.  In this example, the WTP already has the image
   specified by the AC in its non-volative storage.  The WTP opts to NOT
   download the firmware.  The WTP resets upon receipt of a Reset
   Request message from the AC.

             WTP                                               AC

             Configuration Update Request (Image Identifier = x)
         <------------------------------------------------------

      Configuration Update Response (Result Code = Already Have Image)
         -------------------------------------------------------->

                                  .....

                (administratively requested reboot request)
                   Reset Request (Image Identifier = x)
         <------------------------------------------------------

                  Reset Response (Result Code = Success)
         -------------------------------------------------------->

                  Figure 9: WTP Firmware Download Case 4

9.1.1.  Image Data Request
[...]
   The decision that new firmware is to be downloaded to the WTP can
   occur in one of two ways:

      When the WTP joins the AC, the Join Response message includes the
      Image Identifier message element, which informs the WTP of the
      firmware it is expected to run. if the WTP does not currently have
      the requested firmware version, it transmits an Image Data Request
      message, with the appropriate Image Identifier message element.
      If the WTP already has the requested firmware in its non-volatile
      flash, but is not its currently running image, it simply resets to
      run the proper firmware.

      Once the WTP is in the Run state, it is possible for the AC to
      cause the WTP to initiate a firmware download by sending an
      Configuration Update Request message with the Image Identifier
      message elements.  This will cause the WTP to transmit an Image
      Data Request with the Image Identifier and the Initiate Download
      message elements.  Note that when the firmware is downloaded in
      this way, the WTP does not automatically reset after the download
      is complete.  The WTP will only reset when it receives a Reset
      Request message from the AC.  If the WTP already had the requested
      firmware version in its non-volatile storage, the WTP does not
      transmit the Image Data Request message and responds with a
      Configuration Update Response message with the Result Code set to
      Image Already Present.

   Regardless of how the download was initiated, once the AC receives an
   Image Data Request message with the Image Identifier message element,
   it begins the transfer process by transmitting an Image Data Request
   message that includes the Image Data message element.  This continues
   until the firmware image has been transferred.
[...]
   The following message elements MAY be included in the Image Data
   Request message when sent by the WTP.

   o  Image Identifier, see Section 4.6.28

   o  Initiate Download, see Section 4.6.30

9.1.2.  Image Data Response
[...]
   The following message elements MAY be included in the Image Data
   Response message when sent by the AC.

   o  Image Information, see Section 4.6.29

9.2.  Reset Request
[...]
   A Reset Request message is sent by an AC to cause a WTP to
   reinitialize its operation.  If the AC includes the Image Identifier
   message element (see Section 4.6.28), it indicates to the WTP that it
   SHOULD use that version of software upon reboot.
</new 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