Keep-alive settings
Backend keep-alive settings control how long Fastly maintains persistent connections to your origin servers. Properly configured keep-alive settings can improve performance by reusing connections, reducing latency, and avoiding repeated connection establishment.
About keep-alive connections
Keep-alive connections allow multiple HTTP requests to be sent over a single TCP connection, rather than opening a new connection for each request. Fastly supports two types of keep-alive settings:
- TCP keep-alive: Maintains the underlying TCP connection by sending periodic probes to detect dead connections and prevent intermediate network devices from closing idle connections.
- HTTP keep-alive: Controls how long Fastly keeps a persistent HTTP connection open to your backend between requests.
By default, Fastly uses keep-alive connections when possible. You may need to adjust these settings based on your origin server's configuration, network topology, or specific performance requirements.
Keep-alive settings
The following keep-alive settings can be configured for each backend in your Fastly service:
| Setting | Type | Description |
|---|---|---|
tcp_keepalive_enable | Boolean | Whether to enable TCP keep-alive for backend connections. Fastly defaults to using keep-alive if this is unspecified. |
tcp_keepalive_time | Integer | Interval in seconds between the last data packet sent and the first keep-alive probe. |
tcp_keepalive_interval | Integer | Interval in seconds between subsequent keep-alive probes. |
tcp_keepalive_probes | Integer | Number of unacknowledged probes to send before considering the connection dead. |
keepalive_time | Integer | How long in seconds to keep a persistent connection to the backend between HTTP requests. By default, Fastly keeps connections open as long as possible. |
When to adjust keep-alive settings
You may need to modify keep-alive settings in the following scenarios:
- Your origin server has specific timeout requirements that are different than Fastly's defaults
- You're experiencing connection timeouts or connection reset errors
- Your backend uses load balancers or firewalls with aggressive connection timeout policies
For example, if your origin closes idle connections after 60 seconds but Fastly attempts to reuse connections after 65 seconds, requests may fail. Setting keepalive_time to 55 seconds ensures Fastly closes connections before your origin does.
Configuring keep-alive settings
Keep-alive settings are configured at the backend level and apply to Deliver and Compute services. You can configure these settings using the Fastly API, CLI, VCL, and Compute SDKs.
- API
- CLI
- VCL
- Compute
You can view and modify keep-alive settings using the Backend API endpoint. You can include the following keep-alive parameters in your API requests when creating or updating a backend:
{ "name": "my-backend", "address": "origin.example.com", "keepalive_time": 55, "tcp_keepalive_enable": true, "tcp_keepalive_time": 30, "tcp_keepalive_interval": 10, "tcp_keepalive_probes": 3}Use a PUT request to the /service/{service_id}/version/{version_id}/backend/{backend_name} endpoint to update an existing backend with these settings.
Troubleshooting connection issues
If you're experiencing connection timeouts or errors, consider the following:
- Origin timeout errors: If requests fail with timeout errors, your origin may be closing connections before Fastly expects. Try reducing the
keepalive_timevalue to be shorter than your origin's timeout. - Connection resets: If you see connection reset errors, verify that your origin supports keep-alive connections and that any intermediate load balancers or firewalls aren't closing idle connections.
- Performance issues: If you notice degraded performance, ensure that your
keepalive_timeis long enough to allow connection reuse for multiple requests, but not so long that stale connections accumulate.
When adjusting keep-alive settings, make small incremental changes and monitor your service's performance and error rates to find the optimal configuration for your specific use case.
