Manage request and response behaviors for Lightsail distributions

In this guide, we describe the way your Amazon Lightsail distribution behaves when processing and forwarding requests to your origin, and processing responses from your origin. For more information about distributions, see Content delivery network distributions.

Topics

How your distribution processes and forwards requests to your origin

This section contains information about how your distribution processes viewer requests and forwards the requests to your origin.

Contents

Authentication

For DELETE, GET, HEAD, PATCH, POST, and PUT requests, if you configure your distribution to forward the Authorization header to your origin, you can configure your origin server to request client authentication.

For OPTIONS requests, you can configure your origin server to request client authentication only if you use the following distribution settings:

You can configure your distribution to forward requests to your origin using either HTTP or HTTPS.

Caching duration

To control how long your objects stay in your distribution's cache before your distribution forwards another request to your origin, you can:

For more information, see distribution advanced settings.

Client IP addresses

If a viewer sends a request to your distribution and does not include an X-Forwarded-For request header, your distribution gets the IP address of the viewer from the TCP connection, adds an X-Forwarded-For header that includes the IP address, and forwards the request to the origin. For example, if your distribution gets the IP address 192.0.2.2 from the TCP connection, it forwards the following header to the origin:

X-Forwarded-For: 192.0.2.2

If a viewer sends a request to your distribution and includes an X-Forwarded-For request header, your distribution gets the IP address of the viewer from the TCP connection, appends it to the end of the X-Forwarded-For header, and forwards the request to the origin. For example, if the viewer request includes X-Forwarded-For: 192.0.2.4,192.0.2.3 and your distribution gets the IP address 192.0.2.2 from the TCP connection, it forwards the following header to the origin:

X-Forwarded-For: 192.0.2.4,192.0.2.3,192.0.2.2

Some applications, such as load balancers, web application firewalls, reverse proxies, intrusion prevention systems, and API Gateway, append the IP address of the distribution edge server that forwarded the request onto the end of the X-Forwarded-For header. For example, if your distribution includes X-Forwarded-For: 192.0.2.2 in a request that it forwards to ELB and if the IP address of the distribution edge server is 192.0.2.199, the request that your instance receives contains the following header:

X-Forwarded-For: 192.0.2.2,192.0.2.199

Client-side SSL authentication

Lightsail distributions don't support client authentication with client-side SSL certificates. If an origin requests a client-side certificate, your distribution drops the request.

Compression

Lightsail distributions forward requests that have the Accept-Encoding field values "identity" and "gzip".

Conditional requests

When your distribution receives a request for an object that has expired from an edge cache, it forwards the request to your origin either to get the latest version of the object or to get confirmation from the origin that the distribution edge cache already has the latest version. Typically, when the origin last sent the object to your distribution, it included an ETag value, a LastModified value, or both values in the response. In the new request that your distribution forwards to your origin, your distribution adds one or both of the following:

The origin uses this information to determine whether the object has been updated and, therefore, whether to return the entire object to your distribution or to return only an HTTP 304 status code (not modified).

Cookies

You can configure your distribution to forward cookies to your origin. For more information, see distribution advanced settings.

Cross-origin resource sharing (CORS)

If you want your distribution to respect cross-origin resource sharing settings, configure your origin to forward the Origin header to your origin.

Encryption

You can require viewers to connect to your distribution using HTTPS and require your distribution to forward requests to your origin by using HTTP or HTTPS.

Your distribution forwards HTTPS requests to your origin using the SSLv3, TLSv1.0, TLSv1.1, and TLSv1.2 protocols. Other versions of SSL and TLS are not supported.

GET requests that include a body

If a viewer GET request includes a body, your distribution returns an HTTP status code 403 (Forbidden) to the viewer.

HTTP methods

If you configure your distribution to allow all of the HTTP methods that it supports, your distribution accepts the following requests from viewers and forwards them to your origin:

Your distribution always caches responses to GET and HEAD requests. You can also configure your distribution to cache responses to OPTIONS requests. Your distribution does not cache responses to requests that use the other methods.

For information about configuring whether your origin processes these methods, see the documentation for your origin.

HTTP request headers and distribution behavior

The following list contains the HTTP request headers that you can forward to your origin (with the exceptions that are noted). For each header, the list includes information about the following:

HTTP version

Your distribution forwards requests to your origin using HTTP/1.1.

Maximum length of a request and maximum length of a URL

The maximum length of a request, including the path, the query string (if any), and headers, is 20,480 bytes.

Your distribution constructs a URL from the request. The maximum length of this URL is 8192 bytes.

If a request or a URL exceeds these maximums, your distribution returns HTTP status code 413, Request Entity Too Large, to the viewer, and then terminates the TCP connection to the viewer.

OCSP stapling

When a viewer submits an HTTPS request for an object, either your distribution or the viewer must confirm with the certificate authority (CA) that the SSL certificate for the domain has not been revoked. OCSP stapling speeds up certificate validation by allowing your distribution to validate the certificate and to cache the response from the CA, so the client doesn't need to validate the certificate directly with the CA.

The performance improvement of OCSP stapling is more pronounced when your distribution receives numerous HTTPS requests for objects in the same domain. Each server in a distribution edge location must submit a separate validation request. When your distribution receives a lot of HTTPS requests for the same domain, every server in the edge location soon has a response from the CA that it can "staple" to a packet in the SSL handshake; when the viewer is satisfied that the certificate is valid, your distribution can serve the requested object. If your distribution doesn't get much traffic in an edge location, new requests are more likely to be directed to a server that hasn't validated the certificate with the CA yet. In that case, the viewer separately performs the validation step and the distribution server serves the object. That distribution server also submits a validation request to the CA, so the next time it receives a request that includes the same domain name, it has a validation response from the CA.

Persistent connections

When your distribution gets a response from your origin, it tries to maintain the connection for several seconds in case another request arrives during that period. Maintaining a persistent connection saves the time required to re-establish the TCP connection and perform another TLS handshake for subsequent requests.

Protocols

Your distribution forwards HTTP or HTTPS requests to the origin server based on value of the Origin protocol policy field in the Lightsail console . In the Lightsail console, the options are HTTP only, and HTTPS only.

If you specify HTTP Only or HTTPS Only, your distribution forwards requests to your origin using the specified protocol, regardless of the protocol in the viewer request.

Query strings

You can configure whether your distribution forwards query string parameters to your origin.

Origin connection timeout and attempts

By default, your distribution waits as long as 30 seconds (3 attempts of 10 seconds each) before returning an error response to the viewer.

Origin response timeout

The origin response timeout, also known as the origin read timeout or origin request timeout, applies to both of the following:

Your distribution's behavior depends on the HTTP method of the viewer request:

Simultaneous requests for the same object (traffic spikes)

When a distribution edge location receives a request for an object and either the object isn't currently in the cache or the object has expired, your distribution immediately sends the request to your origin. If there's a traffic spike—if additional requests for the same object arrive at the edge location before your origin responds to the first request—your distribution pauses briefly before forwarding additional requests for the object to your origin. Typically, the response to the first request will arrive at the distribution edge location before the response to subsequent requests. This brief pause helps to reduce unnecessary load on your origin server. If additional requests are not identical because, for example, you configured your distribution to cache based on request headers or cookies, your distribution forwards all of the unique requests to your origin.

User-agent header

If you want your distribution to cache different versions of your objects based on the device that a user is using to view your content, we recommend that you configure your distribution to forward one or more of the following headers to your origin:

Based on the value of the User-Agent header, your distribution sets the value of these headers to true or false before forwarding the request to your origin. If a device falls into more than one category, more than one value might be true. For example, for some tablet devices, your distribution might set both CloudFront-Is-Mobile-Viewer and CloudFront-Is-Tablet-Viewer to true.

You can configure your distribution to cache objects based on values in the User-Agent header, but we don't recommend it. The User-Agent header has many possible values, and caching based on those values would cause your distribution to forward significantly more requests to your origin.

If you do not configure your distribution to cache objects based on values in the User-Agent header, your distribution adds a User-Agent header with the following value before it forwards a request to your origin:

User-Agent = Amazon CloudFront

Your distribution adds this header regardless of whether the request from the viewer includes a User-Agent header. If the request from the viewer includes a User-Agent header, your distribution removes it.

How your distribution processes responses from your origin

This section contains information about how your distribution processes responses from your origin.

Contents

100-Continue responses

Your origin cannot send more than one 100-Continue response to your distribution. After the first 100-Continue response, your distribution expects an HTTP 200 OK response. If your origin sends another 100-Continue response after the first one, your distribution returns an error.

Caching

Canceled requests

If an object is not in the edge cache, and if a viewer terminates a session (for example, closes a browser) after your distribution gets the object from your origin but before it can deliver the requested object, your distribution does not cache the object in the edge location.

Content negotiation

If your origin returns Vary:* in the response, and if the value of Minimum TTL for the corresponding cache behavior is 0, your distribution caches the object but still forwards every subsequent request for the object to the origin to confirm that the cache contains the latest version of the object. Your distribution doesn't include any conditional headers, such as If-None-Match or If-Modified-Since. As a result, your origin returns the object to your distribution in response to every request.

If your origin returns Vary:* in the response, and if the value of Minimum TTL for the corresponding cache behavior is any other value, CloudFront processes the Vary header as described in HTTP response headers that your distribution removes or replaces.

Cookies

If you enable cookies for a cache behavior, and if the origin returns cookies with an object, your distribution caches both the object and the cookies. Note that this reduces cache-ability for an object.

Dropped TCP connections

If the TCP connection between your distribution and your origin drops while your origin is returning an object to your distribution, your distribution's behavior depends on whether your origin included a Content-Length header in the response:

We recommend that you configure your HTTP server to add a Content-Length header to prevent your distribution from caching partial objects.

HTTP response headers that your distribution removes or replaces

Your distribution removes or updates the following header fields before forwarding the response from your origin to the viewer:

Maximum file size

The maximum size of a response body that your distribution will return to the viewer is 20 GB. This includes chunked transfer responses that don't specify the Content-Length header value.

Origin unavailable

If your origin server is unavailable and your distribution gets a request for an object that is in the edge cache but that has expired (for example, because the period of time specified in the Cache-Control max-age directive has passed), your distribution either serves the expired version of the object or serves a custom error page.

In some cases, an object that is seldom requested is evicted and is no longer available in the edge cache. Your distribution can't serve an object that has been evicted.

Redirects

If you change the location of an object on your origin server, you can configure your web server to redirect requests to the new location. After you configure the redirect, the first time a viewer submits a request for the object, your distribution sends the request to the origin, and the origin responds with a redirect (for example, 302 Moved Temporarily). Your distribution caches the redirect and returns it to the viewer. Your distribution does not follow the redirect.

You can configure your web server to redirect requests to one of the following locations:

Transfer encoding

Lightsail distributions support only the chunked value of the Transfer-Encoding header. If your origin returns Transfer-Encoding: chunked, your distribution returns the object to the client as the object is received at the edge location, and caches the object in chunked format for subsequent requests.

If the viewer makes a Range GET request and the origin returns Transfer-Encoding: chunked, your distribution returns the entire object to the viewer instead of the requested range.

We recommend that you use chunked encoding if the content length of your response cannot be predetermined. For more information, see Dropped TCP Connections.