curl as a diagnostic tool - HTTP, headers, and timing

curl is the universal HTTP/HTTPS diagnostic. It shows what the client sends, what the server returns, how long each phase took, and the TLS details. When “the website is broken” arrives, curl -v is the first command.

Basic usage

curl https://example.com             # GET, print body
curl -I https://example.com          # HEAD only (show headers)
curl -o file https://example.com     # save to file
curl -L https://example.com          # follow redirects
curl -s https://example.com          # silent (no progress)
curl -sS https://example.com         # silent but show errors

Verbose output

-v shows everything:

curl -v https://example.com

Output:

* Trying 93.184.216.34:443...
* Connected to example.com (93.184.216.34) port 443
* ALPN: offers h2,http/1.1
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (3):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, Finished (5):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLS_AES_128_GCM_SHA256
* Server certificate:
*  subject: CN=example.com
*  start date: ...
*  expire date: ...
*  subjectAltName: host "example.com" matched cert\'s "example.com"
*  SSL certificate verify ok.
* using HTTP/2
* h2h3 [:method: GET]
* h2h3 [:path: /]
* h2h3 [:scheme: https]
* h2h3 [:authority: example.com]
* h2h3 [:user-agent: curl/8.5.0]
* > GET / HTTP/2
* > host: example.com
* > user-agent: curl/8.5.0
* > accept: */*
* < HTTP/2 200
* < server: ECS (sec/...)
* < content-type: text/html
* < content-length: 1256
* < date: ...
* < ...

What to look for:

• Connection: which IP and port was reached. If wrong, DNS or routing issue.
• TLS handshake: every step. Any alert or failure is highlighted.
• SSL certificate verify ok: chain validated.
• Protocol: HTTP/2 (preferred) or HTTP/1.1.
• Request headers: what the client sent.
• Response headers and status: what the server returned.

Timing breakdown

-w writes a timing report after the request:

curl -o /dev/null -s -w "%{time_total}\n" https://example.com

Useful format string:

curl -o /dev/null -s -w '
DNS lookup:        %{time_namelookup}s
TCP connect:       %{time_connect}s
TLS handshake:     %{time_appconnect}s
Server response:   %{time_starttransfer}s
Total:             %{time_total}s
' https://example.com

Output:

DNS lookup:        0.012s
TCP connect:       0.045s
TLS handshake:     0.067s
Server response:   0.123s
Total:             0.145s

This is the way to find which phase of the request is slow. DNS slow? Time skew on the resolver. TCP connect slow? RTT to the host. TLS slow? Certificate chain. Server response slow? The server.

Common diagnostic recipes

# Just the HTTP status code
curl -s -o /dev/null -w '%{http_code}\n' https://example.com

# Follow redirects and show each step
curl -vL https://example.com

# Test a specific TLS version
curl --tlsv1.2 https://example.com
curl --tlsv1.3 https://example.com

# Test a specific cipher
curl --tls-max 1.2 --ciphers 'ECDHE-RSA-AES128-GCM-SHA256' https://example.com

# Use a specific CA bundle
curl --cacert /path/to/ca.pem https://example.com

# Skip certificate verification (testing only)
curl -k https://example.com

# Verbose TLS only
curl --tlsv1.3 -v https://example.com 2>&1 | grep -E 'TLS|SSL'

# Send a specific header
curl -H 'X-Custom-Header: value' https://example.com

# POST data
curl -X POST -d 'key=value' https://example.com/api
curl -X POST -H 'Content-Type: application/json' -d '{"key":"value"}' https://example.com/api

# Save headers to a file
curl -D - -o /dev/null https://example.com

# Save the full request and response
curl --trace-ascii /tmp/trace.txt https://example.com

Debugging TLS

# Show the certificate chain
curl -v https://example.com 2>&1 | grep -A2 'Server certificate'

# Show the negotiated TLS version and cipher
curl -v https://example.com 2>&1 | grep -E 'SSL connection|Protocol'

# Find the certificate issuer
curl -v https://example.com 2>&1 | grep -E 'issuer|subject'

If “SSL certificate verify ok” is missing, the chain did not validate. Common causes:

• Self-signed certificate (use -k to skip and confirm, or add to the trust store).
• Expired certificate (check the dates in -v output).
• Hostname mismatch (the cert is for a different name).
• Missing intermediate cert (the server is missing a chain cert).

Connection problems

# Connection refused
curl -v https://example.com
# < Connection refused

# Connection timed out
curl -v --connect-timeout 5 https://example.com
# < Connection timed out after 5000 milliseconds

• Refused: port not listening. Target is up; service is not.
• Timed out: network or firewall issue. Target didn’t reply at all.
• Name resolution failed: DNS issue. Check with dig.

Common pitfalls

• Proxy in environment: http_proxy / https_proxy may intercept requests. curl --noproxy '*' to bypass.
• IPv6 vs IPv4: curl may prefer one. Use -4 or -6 to force.
• HTTP/2 vs HTTP/1.1: some servers behave differently. Use --http1.1 to force HTTP/1.1 for testing.
• Cookie jar: use -b file -c file to load and save cookies for testing authenticated flows.

Knowledge check