Curl Keep-Alive Example

The command

curl -v -H "Connection: close" https://httpbin.org/get

What the flags do

HTTP persistent connections

In HTTP/1.1 a connection stays open after a response unless one side says Connection: close. Curl reuses it, but only within a single invocation: give one command several URLs on the same host and the second request skips the TCP and TLS handshakes. Run curl twice and each process starts from nothing. -v shows it happening with a "Re-using existing connection" line.

# one process, two requests, one connection
curl -v -o /dev/null -o /dev/null \
  https://httpbin.org/get https://httpbin.org/headers 2>&1 | grep -i -E "re-using|connected to"

Forcing a close

Sending Connection: close tells the server you will not reuse the connection, and the server echoes the header and closes after responding. It is useful when testing how a load balancer distributes fresh connections, or when a broken server leaves a kept-alive connection hanging.

HTTP/2 and HTTP/3 have no such header. Connection-level headers are forbidden there and curl does not send them; the connection is managed by the protocol itself. Add --http1.1 if you need this behaviour against a server that would otherwise negotiate HTTP/2.

curl -sI --http1.1 -H "Connection: close" https://httpbin.org/get | grep -i "^connection"

TCP keepalive is something else

--no-keepalive, --keepalive-time and friends configure operating-system probes sent on an idle TCP socket so that firewalls and NAT devices do not silently drop it. They matter for long transfers with quiet periods, such as a slow download or a streaming response, and have nothing to do with whether the HTTP connection is reused.

curl --keepalive-time 30 -o big.iso https://example.com/big.iso

Common mistakes

• A shell loop that runs curl repeatedly never reuses connections. Pass all the URLs to one command, or use --parallel, or a config file with -K.
• The Keep-Alive: timeout=5 response header is advisory. Servers close idle connections whenever they like.
• Connection: keep-alive does not make a server keep a connection open if it is configured to close it.

Related curl examples

More under Headers

• Curl Content-Type Example
• Curl User Agent Example
• Curl Send Cookies Example
• Curl Custom Headers Example

References

• curl man page: --no-keepalive — Turning off TCP keepalive probes.
• MDN: Keep-Alive — The response header that advertises connection limits.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ