RFC 5415
Control And Provisioning of Wireless Access Points (CAPWAP) Protocol Specification
Pages: 155
Proposed Standard
→ Errata
Obsoletes: 5414
Updated by: 8553 8996
Proposed Standard
→ Errata
Obsoletes: 5414
Updated by: 8553 8996
Part 5 of 6 – Pages 103 to 131
5. CAPWAP Discovery Operations
The Discovery messages are used by a WTP to determine which ACs are available to provide service, and the capabilities and load of the ACs.5.1. Discovery Request Message
The Discovery Request message is used by the WTP to automatically discover potential ACs available in the network. The Discovery Request message provides ACs with the primary capabilities of the
WTP. A WTP must exchange this information to ensure subsequent exchanges with the ACs are consistent with the WTP's functional characteristics. Discovery Request messages MUST be sent by a WTP in the Discover state after waiting for a random delay less than MaxDiscoveryInterval, after a WTP first comes up or is (re)initialized. A WTP MUST send no more than the maximum of MaxDiscoveries Discovery Request messages, waiting for a random delay less than MaxDiscoveryInterval between each successive message. This is to prevent an explosion of WTP Discovery Request messages. An example of this occurring is when many WTPs are powered on at the same time. If a Discovery Response message is not received after sending the maximum number of Discovery Request messages, the WTP enters the Sulking state and MUST wait for an interval equal to SilentInterval before sending further Discovery Request messages. Upon receiving a Discovery Request message, the AC will respond with a Discovery Response message sent to the address in the source address of the received Discovery Request message. Once a Discovery Response has been received, if the WTP decides to establish a session with the responding AC, it SHOULD perform an MTU discovery, using the process described in Section 3.5. It is possible for the AC to receive a clear text Discovery Request message while a DTLS session is already active with the WTP. This is most likely the case if the WTP has rebooted, perhaps due to a software or power failure, but could also be caused by a DoS attack. In such cases, any WTP state, including the state machine instance, MUST NOT be cleared until another DTLS session has been successfully established, communicated via the DTLSSessionEstablished DTLS notification (see Section 2.3.2.2). The binding specific WTP Radio Information message element (see Section 2.1) is included in the Discovery Request message to advertise WTP support for one or more CAPWAP bindings. The Discovery Request message is sent by the WTP when in the Discovery state. The AC does not transmit this message. The following message elements MUST be included in the Discovery Request message: o Discovery Type, see Section 4.6.21
o WTP Board Data, see Section 4.6.40 o WTP Descriptor, see Section 4.6.41 o WTP Frame Tunnel Mode, see Section 4.6.43 o WTP MAC Type, see Section 4.6.44 o WTP Radio Information message element(s) that the WTP supports; These are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1). The following message elements MAY be included in the Discovery Request message: o MTU Discovery Padding, see Section 4.6.32 o Vendor Specific Payload, see Section 4.6.395.2. Discovery Response Message
The Discovery Response message provides a mechanism for an AC to advertise its services to requesting WTPs. When a WTP receives a Discovery Response message, it MUST wait for an interval not less than DiscoveryInterval for receipt of additional Discovery Response messages. After the DiscoveryInterval elapses, the WTP enters the DTLS-Init state and selects one of the ACs that sent a Discovery Response message and send a DTLS Handshake to that AC. One or more binding-specific WTP Radio Information message elements (see Section 2.1) are included in the Discovery Request message to advertise AC support for the CAPWAP bindings. The AC MAY include only the bindings it shares in common with the WTP, known through the WTP Radio Information message elements received in the Discovery Request message, or it MAY include all of the bindings supported. The WTP MAY use the supported bindings in its AC decision process. Note that if the WTP joins an AC that does not support a specific CAPWAP binding, service for that binding MUST NOT be provided by the WTP. The Discovery Response message is sent by the AC when in the Idle state. The WTP does not transmit this message. The following message elements MUST be included in the Discovery Response Message:
o AC Descriptor, see Section 4.6.1 o AC Name, see Section 4.6.4 o WTP Radio Information message element(s) that the AC supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1 for more information). o One of the following message elements MUST be included in the Discovery Response Message: * CAPWAP Control IPv4 Address, see Section 4.6.9 * CAPWAP Control IPv6 Address, see Section 4.6.10 The following message elements MAY be included in the Discovery Response message: o Vendor Specific Payload, see Section 4.6.395.3. Primary Discovery Request Message
The Primary Discovery Request message is sent by the WTP to: o determine whether its preferred (or primary) AC is available, or o perform a Path MTU Discovery (see Section 3.5). A Primary Discovery Request message is sent by a WTP when it has a primary AC configured, and is connected to another AC. This generally occurs as a result of a failover, and is used by the WTP as a means to discover when its primary AC becomes available. Since the WTP only has a single instance of the CAPWAP state machine, the Primary Discovery Request is sent by the WTP when in the Run state. The AC does not transmit this message. The frequency of the Primary Discovery Request messages should be no more often than the sending of the Echo Request message. Upon receipt of a Primary Discovery Request message, the AC responds with a Primary Discovery Response message sent to the address in the source address of the received Primary Discovery Request message. The following message elements MUST be included in the Primary Discovery Request message. o Discovery Type, see Section 4.6.21
o WTP Board Data, see Section 4.6.40 o WTP Descriptor, see Section 4.6.41 o WTP Frame Tunnel Mode, see Section 4.6.43 o WTP MAC Type, see Section 4.6.44 o WTP Radio Information message element(s) that the WTP supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1 for more information). The following message elements MAY be included in the Primary Discovery Request message: o MTU Discovery Padding, see Section 4.6.32 o Vendor Specific Payload, see Section 4.6.395.4. Primary Discovery Response
The Primary Discovery Response message enables an AC to advertise its availability and services to requesting WTPs that are configured to have the AC as its primary AC. The Primary Discovery Response message is sent by an AC after receiving a Primary Discovery Request message. When a WTP receives a Primary Discovery Response message, it may establish a CAPWAP protocol connection to its primary AC, based on the configuration of the WTP Fallback Status message element on the WTP. The Primary Discovery Response message is sent by the AC when in the Idle state. The WTP does not transmit this message. The following message elements MUST be included in the Primary Discovery Response message. o AC Descriptor, see Section 4.6.1 o AC Name, see Section 4.6.4 o WTP Radio Information message element(s) that the AC supports; These are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1 for more information).
One of the following message elements MUST be included in the Discovery Response Message: o CAPWAP Control IPv4 Address, see Section 4.6.9 o CAPWAP Control IPv6 Address, see Section 4.6.10 The following message elements MAY be included in the Primary Discovery Response message: o Vendor Specific Payload, see Section 4.6.396. CAPWAP Join Operations
The Join Request message is used by a WTP to request service from an AC after a DTLS connection is established to that AC. The Join Response message is used by the AC to indicate that it will or will not provide service.6.1. Join Request
The Join Request message is used by a WTP to request service through the AC. If the WTP is performing the optional AC Discovery process (see Section 3.3), the join process occurs after the WTP has received one or more Discovery Response messages. During the Discovery process, an AC MAY return more than one CAPWAP Control IPv4 Address or CAPWAP Control IPv6 Address message elements. When more than one such message element is returned, the WTP SHOULD perform "load balancing" by choosing the interface that is servicing the least number of WTPs (known through the WTP Count field of the message element). Note, however, that other load balancing algorithms are also permitted. Once the WTP has determined its preferred AC, and its associated interface, to which to connect, it establishes the DTLS session, and transmits the Join Request over the secured control channel. When an AC receives a Join Request message it responds with a Join Response message. Upon completion of the DTLS handshake and receipt of the DTLSEstablished notification, the WTP sends the Join Request message to the AC. When the AC is notified of the DTLS session establishment, it does not clear the WaitDTLS timer until it has received the Join Request message, at which time it sends a Join Response message to the WTP, indicating success or failure. One or more WTP Radio Information message elements (see Section 2.1) are included in the Join Request to request service for the CAPWAP bindings by the AC. Including a binding that is unsupported by the AC will result in a failed Join Response.
If the AC rejects the Join Request, it sends a Join Response message with a failure indication and initiates an abort of the DTLS session via the DTLSAbort command. If an invalid (i.e., malformed) Join Request message is received, the message MUST be silently discarded by the AC. No response is sent to the WTP. The AC SHOULD log this event. The Join Request is sent by the WTP when in the Join State. The AC does not transmit this message. The following message elements MUST be included in the Join Request message. o Location Data, see Section 4.6.30 o WTP Board Data, see Section 4.6.40 o WTP Descriptor, see Section 4.6.41 o WTP Name, see Section 4.6.45 o Session ID, see Section 4.6.37 o WTP Frame Tunnel Mode, see Section 4.6.43 o WTP MAC Type, see Section 4.6.44 o WTP Radio Information message element(s) that the WTP supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1 for more information). o ECN Support, see Section 4.6.25 At least one of the following message element MUST be included in the Join Request message. o CAPWAP Local IPv4 Address, see Section 4.6.11 o CAPWAP Local IPv6 Address, see Section 4.6.12 The following message element MAY be included in the Join Request message. o CAPWAP Transport Protocol, see Section 4.6.14 o Maximum Message Length, see Section 4.6.31
o WTP Reboot Statistics, see Section 4.6.47 o Vendor Specific Payload, see Section 4.6.396.2. Join Response
The Join Response message is sent by the AC to indicate to a WTP that it is capable and willing to provide service to the WTP. The WTP, receiving a Join Response message, checks for success or failure. If the message indicates success, the WTP clears the WaitDTLS timer for the session and proceeds to the Configure state. If the WaitDTLS Timer expires prior to reception of the Join Response message, the WTP MUST terminate the handshake, deallocate session state and initiate the DTLSAbort command. If an invalid (malformed) Join Response message is received, the WTP SHOULD log an informative message detailing the error. This error MUST be treated in the same manner as AC non-responsiveness. The WaitDTLS timer will eventually expire, and the WTP MAY (if it is so configured) attempt to join a new AC. If one of the WTP Radio Information message elements (see Section 2.1) in the Join Request message requested support for a CAPWAP binding that the AC does not support, the AC sets the Result Code message element to "Binding Not Supported". 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 change its currently running firmware image or download a new version (see Section 9.1.1). The Join Response message is sent by the AC when in the Join State. The WTP does not transmit this message. The following message elements MUST be included in the Join Response message. o Result Code, see Section 4.6.35 o AC Descriptor, see Section 4.6.1 o AC Name, see Section 4.6.4 o WTP Radio Information message element(s) that the AC supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1).
o ECN Support, see Section 4.6.25 One of the following message elements MUST be included in the Join Response Message: o CAPWAP Control IPv4 Address, see Section 4.6.9 o CAPWAP Control IPv6 Address, see Section 4.6.10 One of the following message elements MUST be included in the Join Response Message: o CAPWAP Local IPv4 Address, see Section 4.6.11 o CAPWAP Local IPv6 Address, see Section 4.6.12 The following message elements MAY be included in the Join Response message. o AC IPv4 List, see Section 4.6.2 o AC IPv6 List, see Section 4.6.3 o CAPWAP Transport Protocol, see Section 4.6.14 o Image Identifier, see Section 4.6.27 o Maximum Message Length, see Section 4.6.31 o Vendor Specific Payload, see Section 4.6.397. Control Channel Management
The Control Channel Management messages are used by the WTP and AC to maintain a control communication channel. CAPWAP Control messages, such as the WTP Event Request message sent from the WTP to the AC indicate to the AC that the WTP is operational. When such control messages are not being sent, the Echo Request and Echo Response messages are used to maintain the control communication channel.7.1. Echo Request
The Echo Request message is a keep-alive mechanism for CAPWAP control messages.
Echo Request messages are sent periodically by a WTP in the Image Data or Run state (see Section 2.3) to determine the state of the control connection between the WTP and the AC. The Echo Request message is sent by the WTP when the EchoInterval timer expires. The Echo Request message is sent by the WTP when in the Run state. The AC does not transmit this message. The following message elements MAY be included in the Echo Request message: o Vendor Specific Payload, see Section 4.6.39 When an AC receives an Echo Request message it responds with an Echo Response message.7.2. Echo Response
The Echo Response message acknowledges the Echo Request message. An Echo Response message is sent by an AC after receiving an Echo Request message. After transmitting the Echo Response message, the AC SHOULD reset its EchoInterval timer (see Section 4.7.7). If another Echo Request message or other control message is not received by the AC when the timer expires, the AC SHOULD consider the WTP to be no longer reachable. The Echo Response message is sent by the AC when in the Run state. The WTP does not transmit this message. The following message elements MAY be included in the Echo Response message: o Vendor Specific Payload, see Section 4.6.39 When a WTP receives an Echo Response message it initializes the EchoInterval to the configured value.8. WTP Configuration Management
WTP Configuration messages are used to exchange configuration information between the AC and the WTP.8.1. Configuration Consistency
The CAPWAP protocol provides flexibility in how WTP configuration is managed. A WTP can behave in one of two ways, which is implementation specific:
1. The WTP retains no configuration and accepts the configuration
provided by the AC.
2. The WTP saves the configuration of parameters provided by the AC
that are non-default values into local non-volatile memory, and
are enforced during the WTP's power up initialization phase.
If the WTP opts to save configuration locally, the CAPWAP protocol
state machine defines the Configure state, which allows for
configuration exchange. In the Configure state, the WTP sends its
current configuration overrides to the AC via the Configuration
Status Request message. A configuration override is a non-default
parameter. As an example, in the CAPWAP protocol, the default
antenna configuration is internal omni antenna. A WTP that either
has no internal antennas, or has been explicitly configured by the AC
to use external antennas, sends its antenna configuration during the
configure phase, allowing the AC to become aware of the WTP's current
configuration.
Once the WTP has provided its configuration to the AC, the AC sends
its configuration to the WTP. This allows the WTP to receive
configuration and policies from the AC.
The AC maintains a copy of each active WTP configuration. There is
no need for versioning or other means to identify configuration
changes. If a WTP becomes inactive, the AC MAY delete the inactive
WTP configuration. If a WTP fails, and connects to a new AC, the WTP
provides its overridden configuration parameters, allowing the new AC
to be aware of the WTP configuration.
This model allows for resiliency in case of an AC failure, ensuring
another AC can provide service to the WTP. A new AC would be
automatically updated with WTP configuration changes, eliminating the
need for inter-AC communication and the need for all ACs to be aware
of the configuration of all WTPs in the network.
Once the CAPWAP protocol enters the Run state, the WTPs begin to
provide service. It is common for administrators to require that
configuration changes be made while the network is operational.
Therefore, the Configuration Update Request is sent by the AC to the
WTP to make these changes at run-time.
8.1.1. Configuration Flexibility
The CAPWAP protocol provides the flexibility to configure and manage
WTPs of varying design and functional characteristics. When a WTP
first discovers an AC, it provides primary functional information
relating to its type of MAC and to the nature of frames to be exchanged. The AC configures the WTP appropriately. The AC also establishes corresponding internal state for the WTP.8.2. Configuration Status Request
The Configuration Status Request message is sent by a WTP to deliver its current configuration to the AC. The Configuration Status Request message carries binding-specific message elements. Refer to the appropriate binding for the definition of this structure. When an AC receives a Configuration Status Request message, it acts upon the content of the message and responds to the WTP with a Configuration Status Response message. The Configuration Status Request message includes multiple Radio Administrative State message elements, one for the WTP, and one for each radio in the WTP. The Configuration Status Request message is sent by the WTP when in the Configure State. The AC does not transmit this message. The following message elements MUST be included in the Configuration Status Request message. o AC Name, see Section 4.6.4 o Radio Administrative State, see Section 4.6.33 o Statistics Timer, see Section 4.6.38 o WTP Reboot Statistics, see Section 4.6.47 The following message elements MAY be included in the Configuration Status Request message. o AC Name with Priority, see Section 4.6.5 o CAPWAP Transport Protocol, see Section 4.6.14 o WTP Static IP Address Information, see Section 4.6.48 o Vendor Specific Payload, see Section 4.6.39
8.3. Configuration Status Response
The Configuration Status Response message is sent by an AC and provides a mechanism for the AC to override a WTP's requested configuration. A Configuration Status Response message is sent by an AC after receiving a Configuration Status Request message. The Configuration Status Response message carries binding-specific message elements. Refer to the appropriate binding for the definition of this structure. When a WTP receives a Configuration Status Response message, it acts upon the content of the message, as appropriate. If the Configuration Status Response message includes a Radio Operational State message element that causes a change in the operational state of one of the radios, the WTP transmits a Change State Event to the AC, as an acknowledgement of the change in state. The Configuration Status Response message is sent by the AC when in the Configure state. The WTP does not transmit this message. The following message elements MUST be included in the Configuration Status Response message. o CAPWAP Timers, see Section 4.6.13 o Decryption Error Report Period, see Section 4.6.18 o Idle Timeout, see Section 4.6.24 o WTP Fallback, see Section 4.6.42 One or both of the following message elements MUST be included in the Configuration Status Response message: o AC IPv4 List, see Section 4.6.2 o AC IPv6 List, see Section 4.6.3 The following message element MAY be included in the Configuration Status Response message. o WTP Static IP Address Information, see Section 4.6.48 o Vendor Specific Payload, see Section 4.6.39
8.4. Configuration Update Request
Configuration Update Request messages are sent by the AC to provision the WTP while in the Run state. This is used to modify the configuration of the WTP while it is operational. When a WTP receives a Configuration Update Request message, it responds with a Configuration Update Response message, with a Result Code message element indicating the result of the configuration request. The AC includes the Image Identifier message element (see Section 4.6.27) 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.29). The Configuration Update Request is sent by the AC when in the Run state. The WTP does not transmit this message. One or more of the following message elements MAY be included in the Configuration Update message: o AC Name with Priority, see Section 4.6.5 o AC Timestamp, see Section 4.6.6 o Add MAC ACL Entry, see Section 4.6.7 o CAPWAP Timers, see Section 4.6.13 o Decryption Error Report Period, see Section 4.6.18 o Delete MAC ACL Entry, see Section 4.6.19 o Idle Timeout, see Section 4.6.24 o Location Data, see Section 4.6.30 o Radio Administrative State, see Section 4.6.33 o Statistics Timer, see Section 4.6.38 o WTP Fallback, see Section 4.6.42 o WTP Name, see Section 4.6.45
o WTP Static IP Address Information, see Section 4.6.48 o Image Identifier, see Section 4.6.27 o Vendor Specific Payload, see Section 4.6.398.5. Configuration Update Response
The Configuration Update Response message is the acknowledgement message for the Configuration Update Request message. The Configuration Update Response message is sent by a WTP after receiving a Configuration Update Request message. When an AC receives a Configuration Update Response message, the result code indicates if the WTP successfully accepted the configuration. The Configuration Update Response message is sent by the WTP when in the Run state. The AC does not transmit this message. The following message element MUST be present in the Configuration Update message. Result Code, see Section 4.6.35 The following message elements MAY be present in the Configuration Update Response message. o Radio Operational State, see Section 4.6.34 o Vendor Specific Payload, see Section 4.6.398.6. Change State Event Request
The Change State Event Request message is used by the WTP for two main purposes: o When sent by the WTP following the reception of a Configuration Status Response message from the AC, the WTP uses the Change State Event Request message to provide an update on the WTP radio's operational state and to confirm that the configuration provided by the AC was successfully applied. o When sent during the Run state, the WTP uses the Change State Event Request message to notify the AC of an unexpected change in the WTP's radio operational state.
When an AC receives a Change State Event Request message it responds with a Change State Event Response message and modifies its data structures for the WTP as needed. The AC MAY decide not to provide service to the WTP if it receives an error, based on local policy, and to transition to the Reset state. The Change State Event Request message is sent by a WTP to acknowledge or report an error condition to the AC for a requested configuration in the Configuration Status Response message. The Change State Event Request message includes the Result Code message element, which indicates whether the configuration was successfully applied. If the WTP is unable to apply a specific configuration request, it indicates the failure by including one or more Returned Message Element message elements (see Section 4.6.36). The Change State Event Request message is sent by the WTP in the Configure or Run state. The AC does not transmit this message. The WTP MAY save its configuration to persistent storage prior to transmitting the response. However, this is implementation specific and is not required. The following message elements MUST be present in the Change State Event Request message. o Radio Operational State, see Section 4.6.34 o Result Code, see Section 4.6.35 One or more of the following message elements MAY be present in the Change State Event Request message: o Returned Message Element(s), see Section 4.6.36 o Vendor Specific Payload, see Section 4.6.398.7. Change State Event Response
The Change State Event Response message acknowledges the Change State Event Request message. A Change State Event Response message is sent by an AC in response to a Change State Event Request message. The Change State Event Response message is sent by the AC when in the Configure or Run state. The WTP does not transmit this message.
The following message element MAY be included in the Change State Event Response message: o Vendor Specific Payload, see Section 4.6.39 The WTP does not take any action upon receipt of the Change State Event Response message.8.8. Clear Configuration Request
The Clear Configuration Request message is used to reset the WTP configuration. The Clear Configuration Request message is sent by an AC to request that a WTP reset its configuration to the manufacturing default configuration. The Clear Config Request message is sent while in the Run state. The Clear Configuration Request is sent by the AC when in the Run state. The WTP does not transmit this message. The following message element MAY be included in the Clear Configuration Request message: o Vendor Specific Payload, see Section 4.6.39 When a WTP receives a Clear Configuration Request message, it resets its configuration to the manufacturing default configuration.8.9. Clear Configuration Response
The Clear Configuration Response message is sent by the WTP after receiving a Clear Configuration Request message and resetting its configuration parameters to the manufacturing default values. The Clear Configuration Response is sent by the WTP when in the Run state. The AC does not transmit this message. The Clear Configuration Response message MUST include the following message element: o Result Code, see Section 4.6.35 The following message element MAY be included in the Clear Configuration Request message: o Vendor Specific Payload, see Section 4.6.39
9. Device Management Operations
This section defines CAPWAP operations responsible for debugging, gathering statistics, logging, and firmware management. The management operations defined in this section are used by the AC to either push/pull information to/from the WTP, or request that the WTP reboot. This section does not deal with the management of the AC per se, and assumes that the AC is operational and configured.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. The former allows the download to occur at boot time, while the latter is used to trigger the download while an active CAPWAP session exists. It is important to note that the CAPWAP protocol does not provide the ability for the AC to identify whether the firmware information provided by the WTP is correct or whether the WTP is properly storing the firmware (see Section 12.10 for more information). 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-volatile 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-volatile 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 49.1.1. Image Data Request
The Image Data Request message is used to update firmware on the WTP. This message and its companion Response message are used by the AC to ensure that the image being run on each WTP is appropriate. Image Data Request messages are exchanged between the WTP and the AC to download a new firmware image to the WTP. When a WTP or AC receives an Image Data Request message, it responds with an Image Data Response message. The message elements contained within the Image Data Request message are required to determine the intent of the 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 a 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 Image Data Request message is sent by the WTP or the AC when in
the Image Data or Run state.
The following message elements MAY be included in the Image Data
Request message:
o CAPWAP Transport Protocol, see Section 4.6.14
o Image Data, see Section 4.6.26
o Vendor Specific Payload, see Section 4.6.39
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.27
o Initiate Download, see Section 4.6.29
9.1.2. Image Data Response
The Image Data Response message acknowledges the Image Data Request
message.
An Image Data Response message is sent in response to a received
Image Data Request message. Its purpose is to acknowledge the
receipt of the Image Data Request message. The Result Code is
included to indicate whether a previously sent Image Data Request
message was invalid.
The Image Data Response message is sent by the WTP or the AC when in
the Image Data or Run state.
The following message element MUST be included in the Image Data Response message: o Result Code, see Section 4.6.35 The following message element MAY be included in the Image Data Response message: o Vendor Specific Payload, see Section 4.6.39 The following message element MAY be included in the Image Data Response message when sent by the AC: o Image Information, see Section 4.6.28 Upon receiving an Image Data Response message indicating an error, the WTP MAY retransmit a previous Image Data Request message, or abandon the firmware download to the WTP by transitioning to the Reset state.9.2. Reset Request
The Reset Request message is used to cause a WTP to reboot. 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.27), it indicates to the WTP that it SHOULD use that version of software upon reboot. The Reset Request is sent by the AC when in the Run state. The WTP does not transmit this message. The following message element MUST be included in the Reset Request message: o Image Identifier, see Section 4.6.27 The following message element MAY be included in the Reset Request message: o Vendor Specific Payload, see Section 4.6.39 When a WTP receives a Reset Request message, it responds with a Reset Response message indicating success and then reinitializes itself. If the WTP is unable to write to its non-volatile storage, to ensure that it runs the requested software version indicated in the Image Identifier message element, it MAY send the appropriate Result Code message element, but MUST reboot. If the WTP is unable to reset,
including a hardware reset, it sends a Reset Response message to the AC with a Result Code message element indicating failure. The AC no longer provides service to the WTP.9.3. Reset Response
The Reset Response message acknowledges the Reset Request message. A Reset Response message is sent by the WTP after receiving a Reset Request message. The Reset Response is sent by the WTP when in the Run state. The AC does not transmit this message. The following message elements MAY be included in the Reset Response message. o Result Code, see Section 4.6.35 o Vendor Specific Payload, see Section 4.6.39 When an AC receives a successful Reset Response message, it is notified that the WTP will reinitialize its operation. An AC that receives a Reset Response message indicating failure may opt to no longer provide service to the WTP.9.4. WTP Event Request
The WTP Event Request message is used by a WTP to send information to its AC. The WTP Event Request message MAY be sent periodically, or sent in response to an asynchronous event on the WTP. For example, a WTP MAY collect statistics and use the WTP Event Request message to transmit the statistics to the AC. When an AC receives a WTP Event Request message it will respond with a WTP Event Response message. The presence of the Delete Station message element is used by the WTP to inform the AC that it is no longer providing service to the station. This could be the result of an Idle Timeout (see Section 4.6.24), due to resource shortages, or some other reason. The WTP Event Request message is sent by the WTP when in the Run state. The AC does not transmit this message.
The WTP Event Request message MUST contain one of the message elements listed below, or a message element that is defined for a specific wireless technology. More than one of each message element listed MAY be included in the WTP Event Request message. o Decryption Error Report, see Section 4.6.17 o Duplicate IPv4 Address, see Section 4.6.22 o Duplicate IPv6 Address, see Section 4.6.23 o WTP Radio Statistics, see Section 4.6.46 o WTP Reboot Statistics, see Section 4.6.47 o Delete Station, see Section 4.6.20 o Vendor Specific Payload, see Section 4.6.399.5. WTP Event Response
The WTP Event Response message acknowledges receipt of the WTP Event Request message. A WTP Event Response message is sent by an AC after receiving a WTP Event Request message. The WTP Event Response message is sent by the AC when in the Run state. The WTP does not transmit this message. The following message element MAY be included in the WTP Event Response message: o Vendor Specific Payload, see Section 4.6.399.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 WTP 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 element: o Data Transfer Mode, see Section 4.6.16 When sent by the WTP, the Data Transfer Request message MUST contain the following message element: o Data Transfer Data, see Section 4.6.15 Regardless of whether the Data Transfer Request is sent by the AC or WTP, the following message element 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 transferred 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 element 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.
(page 131 continued on part 6)