General
Some general configuration options
Allowed methods
The Varnish CDN will reject requests with a method which is not selected here, by sending the error code 405.
We recommend disabling any methods which are not in use by your site to increase the chance that malicious or incorrect requests make it to your origin servers.
The following table of common HTTP methods contains information on how Varnish CDN handles them, when enabled.
| Method | Description |
|---|---|
| GET | The main method to retrieve data, supported by VCDN |
| HEAD | A method for retreiving information about a resource, without the payload date. VCDN will issue a GET request to the origin server, cache it (unless caching is disabled) and deliver the response to the client without the response body. |
| POST | A method for submitting a request which includes a request body. The purpose of the POST request is typically to upload a file, change the state of the origin in some way, or carry out a complex search that does not have side effects, but where using query parameters would produce a very long URL, or an URL which contains private information. Varnish CDN supports POST, but caching is always disabled with POST requests. |
| PUT | A method for uploading a file to replace the existing file or create a new file. Varnish CDN can forward PUT requests, but there is no caching |
| DELETE | This method is used to delete files, and DELETE requests will be forwarded to the origin. |
| CONNECT | A method to establishe a tunnel to a server. This is not supported by Varnish CDN |
| OPTIONS | A method to receive information the communication options for the target resource. Most importantly, OPTIONS is used to query the allowed methods and CORS preflight requests. Varnish CDN forwards OPTIONS requests to the origin server. Note: The Varnish CDN can also be configured to handle OPTION requests without involving the backend. This is described somewhere else (TODO: Make link!) |
| TRACE | This method is not supported by Varnish CDN, but enabling it will simply forward the request to the origin server. |
| PATCH | The PATCH method applies partial modifications to a resource. If enabled, requests with this method will be forwarded to the origin server, as is. |
Note: For most sites, enabling just HEAD, GET and OPTIONS are sufficient, with POST being necessary for some API calls. It makes sense to only enable POST for URLs where it is necessary, as caching will be disabled for POST requests.
Read more about request methods on MDN.
Disable cache
When this is enabled, requests will not be cached at all.
A common mistake is to enable this for content that changes often. It is almost always better to cache such content for a short while, for example one second or even 100 milliseconds.
Time to live of objects (TTL)
Set static TTL
When the origin server does not specify a duration, often referred to as Time To Live (TTL) for cacheable objects through headers, or the Time to Live sent from the origin server is bad, this option can be used to override it.
The Varnish CDN supports the Cache-Control header, which is the preferred way to manage object expiry, but if the TTL needs to be less than a second, this setting can be used to do this.
Uncacheable TTL
When an object is deemed uncacheable based on the headers received from the origin server, but caching was not explicitly disabled through the Disable cache setting, this settings controls how long the CDN node will remember this fact.
First byte timeout
This setting controls how long the CDN will wait for the first byte of response data from the origin server before giving up. The default is 10 seconds.
If your origin server needs more time to process requests (for example, complex database queries or heavy computation), you may need to increase this timeout. If set too low, requests to slow endpoints will fail prematurely.
WebSocket
WebSocket is a protocol that enables persistent, bidirectional communication between a client and server. The CDN can be configured to handle WebSocket connections in two ways:
- Enable: WebSocket connections are allowed when the client sends an Upgrade header. The connection is passed through (piped) directly to the origin server.
- Exclusive: The URL is exclusively for WebSocket traffic. Non-WebSocket requests to this URL will be rejected with a 400 error.
It is recommended to use a specific path or a small number of specific pahts, for WebSocket traffic, and use the Exclusive setting for these paths, while disabling WebSocket for all other paths.
Reserved Character URL Decoding
By default, the CDN normalizes URLs by decoding unnecessarily encoded reserved characters. For example, %65 (which is just the letter "e") will be decoded to e before the request is processed.
This normalization improves cache efficiency by ensuring that URLs like /path and /p%61th (both the same) are treated as the same resource. This setting can be disabled if your application requires strict preservation of URL encoding.
Max body size
This setting limits the size of request bodies (for POST, PUT, etc.) that will be accepted. If a request includes a Content-Length header exceeding this limit, it will be rejected with a 413 Payload Too Large response.
Setting a reasonable limit helps protect both the CDN and your origin server from excessive upload attempts that could consume resources or be part of an attack.
Big uploads
For very large uploads, HTTP supports chunked transfer encoding, where the request body is sent in chunks rather than with a pre-determined Content-Length. By default, chunked uploads are not allowed for security reasons.
When enabled, you can configure how chunked uploads are handled:
- Deny: Reject chunked uploads (default behavior for security)
- Allow: Forward chunked uploads directly to the origin without buffering
- Cache: Buffer the chunked upload up to the configured max body size, which allows the request to be cached
Note: The CDN will reject any request that includes both Content-Length and Transfer-Encoding: chunked headers, as this is a common attack vector.
Sharding
Sharding distributes requests across multiple origin servers based on a hash of the request URL. When enabled, the same URL will always be routed to the same origin server, which is useful when:
- Your origin servers have local, non-shared caches that benefit from request affinity
- You want to distribute load predictably across multiple backends
- Different origin servers contain different subsets of your content
Without sharding, the CDN uses random selection when distributing requests to multiple origin servers. For APIs where processing is required, and there is nothing to gain to select an origin server consistently, you should probably keep sharding off.
Backend retry
When enabled, if an origin server returns a 5xx error (500-599 range), the CDN will automatically retry the request with a different origin server if multiple backends are available.
The retry happens only on the first attempt (not on subsequent retries) and only for server errors, helping to work around temporary issues with individual origin servers. Even with a single origin server, the retry can help recover from transient network or server issues.