Configuring an HTTP handler

How to configure an HTTP handler to manage HTTP protocol communications with DataPower® services.

About this task

You can configure a handler to support the WebSocket or HTTP version 2 (HTTP/2) protocol. A client cannot have both a WebSocket and an HTTP/2 session. WebSocket cannot use an HTTP/2 session. The establishment of an HTTP/2 session disables the WebSocket upgrade.
  • For a WebSocket upgrade, the request is to switch the existing connection to use the WebSocket protocol. WebSocket upgrade requests require that the handler allows GET methods in requests. When the handler switches to the WebSocket protocol, you can control the idle timeout. This timer monitors the idle time in the data transfer process. When the specified idle time is exceeded, the connection is torn down.
    Attention: Not all DataPower services support WebSocket upgrade. If you assign a handler that supports WebSocket upgrade to a DataPower service that does not, the DataPower service cannot start because of an invalid configuration.
  • For HTTP/2, the handler must allow the HTTP/2 feature. When the handler uses the HTTP/2 protocol, you can control the following settings.
    • The maximum number of outstanding concurrent streams.
    • The maximum frame size in octets.
    • Whether to enable the inclusion of the HTTP/2 stream header in the request or response. When enabled, the HTTP/2 stream identifier is included in the x-dp-http2-stream header. With this header, you can correlate the HTTP/2 stream.
    However, you cannot control the following settings.
    • The HTTP version to client.
    • The negotiation and reuse of persistent connections.
    • Upgrade to WebSocket.

For more information about the HTTP/2 protocol, see RFC 7540 and RFC 7541.

Procedure

  1. In the search field, enter HTTP.
  2. From the search results, click HTTP Handler.
  3. Click Add or New.
  4. Define the basic properties: Name, administrative state, and descriptive summary.
  5. Define the connection from clients to the DataPower Gateway.
    1. In the Local IP address field, enter the IP address or host alias that the service listens.

      To use a local host alias instead of a static IP address, click Select Alias. A host alias resolves a locally configured alias to a static IP address. Aliasing can help when you move configurations among DataPower Gateway instances.

    2. In the Port field, enter the listening port.
  6. From the HTTP version to client list, select the version for client-side connections.
  7. From the Allowed methods and versions list, select the methods and versions to allow for incoming requests.
  8. Set Negotiate persistent connections to control the negotiation of persistent connections.
  9. In the Maximum persistent reuse field, enter the maximum number of times a persistent connection is reused.
  10. Set Enable compression to control the negotiation of GZIP compression.
  11. Define use of the WebSocket protocol.
    1. Set Allow WebSocket upgrade to control whether to allow requests with WebSocket Upgrade headers.
    2. In the WebSocket idle timeout field, enter the maximum idle time for client connections.
  12. Define HTTP header and URL limits.
    1. In the Maximum URL length field, enter the length of the longest incoming URL to accept.
      The length includes any query string or fragment identifier.
    2. In the Maximum total header length field, enter the maximum aggregate size of incoming HTTP headers.
    3. In the Maximum number of headers field, enter the maximum number of headers to allow in requests.
    4. In Maximum header name length field, enter the maximum length of the name part of a header.
      Each HTTP header is expressed as a name-value pair.
    5. In Maximum header value length field, enter the maximum length of the value part of a header.
      Each HTTP header is expressed as a name-value pair.
    6. In Maximum query string length field, enter the maximum length of the query string.
      The query string is the portion of the URL after the ? character.
  13. From the Access control list list, select the ACL to apply.
  14. From the Credential character set list, select the character encoding of the original basic authentication values.
  15. Optional: Define limits for HTTP/2 protocol upgrades.
    1. In the HTTP/2 maximum streams field, enter the maximum number of outstanding concurrent streams that the client can have.
    2. In the HTTP/2 maximum frame size field, enter the maximum frame size in octets that the client can send.
    3. Set Enable HTTP/2 stream header to include the HTTP/2 stream identifier header in the request or response.
  16. Optional: Set Enable chunked encoding responses to use the Transfer-Encoding: chunked header in responses to clients.
  17. Optional: In the Request headers processing timeout field, enter the maximum duration in milliseconds to allow for request headers processing. When the value is greater than 0, request header processing must complete before the duration elapses. Enter a value in the range 0 - 3600000, where a value of 0 disables the timer. The default value is 30000.
  18. Click Apply to save the changes to the running configuration.
  19. Click Save Configuration or Save changes to save the changes to the persisted configuration.