Redis tcp-keepalive Explained: Maintaining Reliable Client Connections

Introduction

The tcp-keepalive directive controls how Redis uses the operating system's TCP keepalive mechanism to detect inactive or disconnected client connections.

Unlike the timeout directive, which disconnects idle clients after a specified period, tcp-keepalive periodically sends low-level TCP keepalive packets. These packets help detect broken connections caused by network failures, client crashes, or unexpected disconnections.

This guide explains how tcp-keepalive works, how to configure it, and recommended settings for production servers.

Default Value

The default value depends on the Redis version and operating system.

A common default is:

tcp-keepalive 300

This means Redis asks the operating system to send TCP keepalive probes after approximately 300 seconds of inactivity.

Syntax

tcp-keepalive

Examples:

tcp-keepalive 60
tcp-keepalive 300
tcp-keepalive 600

How tcp-keepalive Works

When a client remains idle, Redis relies on the operating system to send periodic TCP keepalive packets.

If the client is still reachable:

The connection remains open.

If the client has disappeared due to:

a system crash,

network failure,

cable disconnection,

firewall timeout,

the operating system eventually detects the failure and closes the connection.

This prevents Redis from keeping dead connections open indefinitely.

timeout vs tcp-keepalive

Although both settings relate to client connections, they serve different purposes.

| Directive     | Purpose                                                |
| ------------- | ------------------------------------------------------ |
| timeout       | Disconnects idle clients after a specified period.     |
| tcp-keepalive | Detects broken TCP connections using keepalive probes. |

The two settings complement each other rather than replace one another.

Configure tcp-keepalive

Open the Redis configuration file.

sudo nano /etc/redis.conf

Locate:

tcp-keepalive 300

Modify it if necessary.

Example:

tcp-keepalive 120

Restart Redis.

sudo systemctl restart redis

Verify the Configuration

Run:

redis-cli CONFIG GET tcp-keepalive

Example output:

1) "tcp-keepalive"

2) "120"

Change the Setting Without Restarting

redis-cli CONFIG SET tcp-keepalive 300

Remember to update the configuration file if the change should persist after a restart.

Choosing the Right Value

The best value depends on your network environment.

| Environment       | Suggested Value |
| ----------------- | --------------- |
| Development       | 300             |
| Internal LAN      | 300             |
| Cloud servers     | 60–300          |
| Load balancers    | 60–120          |
| Unstable networks | 60              |

Lower values detect broken connections more quickly but generate slightly more network traffic.

Higher values reduce network overhead but may delay detection of disconnected clients.

Common Mistakes

Setting the Value Too Low

Using values such as:

tcp-keepalive 5

creates unnecessary keepalive traffic without significant benefits.

Disabling Keepalive

tcp-keepalive 0

may delay detection of dead connections, especially on unreliable networks.

Confusing It with timeout

Many administrators assume tcp-keepalive disconnects idle clients.

It does not.

Its purpose is to detect broken network connections, not inactive users.

Best Practices

Leave the default value unless your network requires different behavior.

Use lower values when Redis is behind load balancers or NAT devices that aggressively close idle connections.

Combine tcp-keepalive with an appropriate timeout setting.

Monitor client connections using the CLIENT LIST command.

Test configuration changes before deploying them to production.

Related Articles

Redis Explained

Redis timeout Explained

Redis bind Explained

Redis requirepass Explained

Redis maxclients Explained

Conclusion

The tcp-keepalive directive improves the reliability of Redis client connections by allowing the operating system to detect broken TCP sessions automatically. Unlike the timeout directive, it does not disconnect idle clients but instead helps clean up connections that have been lost due to crashes or network failures.

For most production environments, the default value of 300 seconds provides a good balance between timely failure detection and minimal network overhead.