Keepalive connections in Nginx - Commands & Configuration

Introduction

When a web server talks to a client, it can open a new connection for every request. This wastes time and resources. Keepalive connections let the server reuse the same connection for multiple requests, making websites faster and saving resources.

When your website has many small requests like images, scripts, or stylesheets loading together.

When you want to reduce the delay users feel when clicking links or loading pages.

When your server handles many users and you want to save CPU and memory by not opening new connections repeatedly.

When you want to improve performance for mobile users with slower networks.

When you want to reduce network congestion by limiting how often connections open and close.

Config File - nginx.conf

nginx.conf

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    keepalive_timeout  65;
    keepalive_requests 100;

    server {
        listen       8080;
        server_name  localhost;

        location / {
            root   html;
            index  index.html index.htm;
        }
    }
}

keepalive_timeout sets how long the server keeps the connection open waiting for new requests.

keepalive_requests limits how many requests can reuse the same connection before closing it.

The server block defines a simple web server listening on port 8080.

Commands

Check the nginx configuration file for syntax errors before starting the server.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Start the nginx server with the current configuration.

Terminal

nginx

Expected Output

No output (command runs silently)

Make a HTTP request to the server showing verbose output and using keepalive to reuse the connection.

Terminal

curl -v --keepalive-time 60 http://localhost:8080/

Expected Output

*   Trying 127.0.0.1:8080...

* Connected to localhost (127.0.0.1) port 8080 (#0)

> GET / HTTP/1.1

> Host: localhost:8080

> User-Agent: curl/7.68.0

> Accept: */*

>

< HTTP/1.1 200 OK

< Server: nginx/1.21.6

< Date: Thu, 01 Jun 2023 12:00:00 GMT

< Content-Type: text/html

< Content-Length: 612

< Last-Modified: Wed, 31 May 2023 10:00:00 GMT

< Connection: keep-alive

< ETag: "609d-5c1a3e4f"

< Accept-Ranges: bytes

<

{html content}

* Connection #0 to host localhost left intact

→

--keepalive-time - Sets the TCP keepalive time in seconds to keep the connection alive.

→

-v - Shows detailed request and response information.

Make a second HTTP request reusing the same connection to demonstrate keepalive in action.

Terminal

curl -v --keepalive-time 60 http://localhost:8080/

Expected Output

* Re-using existing connection to localhost:8080.

> GET / HTTP/1.1

> Host: localhost:8080

> User-Agent: curl/7.68.0

> Accept: */*

>

< HTTP/1.1 200 OK

< Server: nginx/1.21.6

< Date: Thu, 01 Jun 2023 12:00:05 GMT

< Content-Type: text/html

< Content-Length: 612

< Last-Modified: Wed, 31 May 2023 10:00:00 GMT

< Connection: keep-alive

< ETag: "609d-5c1a3e4f"

< Accept-Ranges: bytes

<

{html content}

* Connection #0 to host localhost left intact

→

--keepalive-time - Keeps the TCP connection alive for reuse.

→

-v - Shows detailed request and response information.

Key Concept

If you remember nothing else from this pattern, remember: keepalive connections let the server reuse the same network connection for multiple requests, making websites faster and saving resources.

Common Mistakes

Not setting keepalive_timeout or setting it too low.

The server closes connections too quickly, losing the benefit of reuse and causing delays.

Set keepalive_timeout to a reasonable value like 60 seconds to allow multiple requests on the same connection.

Not testing the configuration with 'nginx -t' before starting nginx.

Syntax errors cause nginx to fail silently or not start, leading to downtime.

Always run 'nginx -t' to verify configuration syntax before starting or reloading nginx.

Forgetting to reload or restart nginx after changing keepalive settings.

Changes do not take effect until nginx reloads the configuration, so keepalive behavior stays old.

Run 'nginx -s reload' or restart nginx after editing the config file.

Summary

Configure keepalive_timeout and keepalive_requests in nginx.conf to enable connection reuse.

Test nginx configuration syntax with 'nginx -t' before starting the server.

Use curl with verbose and keepalive flags to verify connections are reused.

Reload nginx after configuration changes to apply new keepalive settings.