Connect to a Managed Redis Instance over TLS with Stunnel and redis-cli

A managed Redis instance can provide benefits like high availability, automated updates, and operator-managed patching. Any time you connect to a remote database over a network, though, unencrypted traffic can be exposed to packet sniffing and other interception risks. Transport Layer Security (TLS) encrypts that traffic so credentials, keys, and command data are not sent in plaintext.

Since Redis 6, redis-cli can connect directly over TLS using the --tls flag when the client binary is compiled with TLS support. That native support is the simplest approach on modern systems. When you need to support an older client, wrap a local TCP port with stunnel, an open-source TLS proxy that terminates encryption on your behalf.

In this guide, you will install redis-cli and stunnel on Ubuntu 24.04 LTS, connect to a managed Redis instance using native TLS, configure stunnel as an alternative tunnel, understand how CA certificate verification works, compare secure connection options, and troubleshoot common TLS, authentication, DNS, and connection errors.

To complete this guide, you will need:

• Access to an Ubuntu 24.04 server with a non-root user that has sudo privileges and a firewall configured with ufw. If you have not prepared a server yet, follow our initial server setup guide for Ubuntu.
• A managed Redis database instance that requires TLS. The steps in this tutorial were written for a DigitalOcean Managed Redis Database, though the connection patterns apply to other cloud providers that expose a TLS-enabled Redis endpoint. To provision a DigitalOcean database, see the Managed Databases documentation.

Before you run any commands, gather your database hostname, TLS port, and password from your managed Redis provider’s control panel or API. Having those values ready avoids hunting for credentials mid-setup. On DigitalOcean, open Databases in the control panel, select your cluster, and review the Connection Details section.

Managed Redis providers typically expose a TLS listener (often on a dedicated port such as 25061) and reject plaintext connections. You have several ways to reach that endpoint securely from an Ubuntu client.

Native TLS is the recommended default. It has fewer moving parts, avoids an extra daemon, and lets redis-cli validate server certificates directly, as described in the Redis encryption documentation and redis-cli documentation linked above.

Stunnel remains valuable when your redis-cli binary was built without TLS support (redis-cli --help shows no --tls option) or when another local application expects a plaintext TCP socket. The rest of this guide covers both native TLS and stunnel in detail.

SSH port forwarding does not add Redis-specific TLS on its own; it encrypts traffic between your machine and the SSH server. It is a good operational choice when access to the Redis network is only available through a jump host, but it is outside the scope of the step-by-step configuration below.

TLS does more than encrypt bytes. It also lets your client verify that it reached the intended server, not an impostor on the network.

When redis-cli connects with --tls, it uses OpenSSL (or the platform TLS library) to perform a handshake. Part of that handshake is certificate verification: the server presents an X.509 certificate, and the client checks that:

1. The certificate chains to a trusted root Certificate Authority (CA).
2. The certificate is not expired and, when explicitly configured, can also be checked for revocation.
3. The certificate’s identity matches the hostname you connected to (hostname verification).

You control which CAs are trusted with:

• --cacert: path to a single PEM file containing one or more trusted CA certificates (or the provider’s CA bundle).
• --cacertdir: path to a directory of hashed CA certificates, similar to the system store layout described in the Redis TLS documentation.

If your managed Redis provider signs certificates with a public CA that is already in your system’s trust store (for example, Let’s Encrypt), you may only need --tls without a custom --cacert file. At the time of writing, DigitalOcean managed databases use Let’s Encrypt, so clients on an up-to-date Ubuntu system can often connect with --tls alone.

If verification fails, redis-cli reports certificate errors rather than connecting. For debugging only, Redis provides --insecure, which skips certificate validation. Do not use --insecure in production; it exposes you to man-in-the-middle attacks. The flag exists for lab environments and was added to Redis command-line tools for that limited purpose (see the redis/redis pull request discussion).

Some providers require mutual TLS (mTLS), where the client must present its own certificate. In that case, pass --cert and --key alongside --cacert, following the manual TLS connection examples in the Redis TLS documentation.

When you use stunnel instead of native TLS, stunnel performs verification on the outbound TLS connection. You can enable chain verification in stunnel.conf with verifyChain = yes and CApath = /etc/ssl/certs, following the stunnel Unix configuration examples.

When you install a Redis server package, it usually includes redis-cli. On Ubuntu 24.04 you can install only the client tools and stunnel from the default repositories, which keeps the server footprint small if you only need administrative access to a remote database.

Start by refreshing your local package index so APT sees the latest package versions:

sudo apt update

Next, install redis-tools (which provides redis-cli) and stunnel4:

sudo apt install redis-tools stunnel4

Press ENTER when APT asks you to confirm the installation.

Once the packages are installed, confirm you received the expected versions:

redis-cli --version
stunnel4 -version

At the time of writing, Ubuntu 24.04 ships a Redis 7.x version of redis-tools, which includes native TLS support. Your output should list a 7.x version for redis-cli and a 5.x version for stunnel.

Before you choose a connection method, verify that your redis-cli binary was built with TLS support:

redis-cli --help 2>&1 | grep -E '\-\-tls|\-\-cacert'

If you see --tls and --cacert in the help output, you can use the native TLS workflow in Step 2. If those options are missing, plan on using the stunnel workflow in Steps 3 and 4.

Finally, check that the stunnel service unit is available on your system:

sudo systemctl status stunnel4

A fresh install often shows active (exited) and a log line such as TLS tunnels disabled, see /etc/default/stunnel4. That is normal. The service is installed, but no tunnel is active yet until you enable and configure one in Step 3.

This step connects redis-cli directly to your managed Redis TLS endpoint. Replace the placeholders with your managed Redis provider’s hostname, port, and password before you run each command.

Connect when the system trust store is sufficient

Use this approach when your managed Redis provider signs certificates with a public CA that Ubuntu already trusts. DigitalOcean managed Redis with Let’s Encrypt is a common example.

Run redis-cli with the --tls flag and your database hostname and TLS port:

redis-cli -h managed_redis_hostname -p managed_redis_tls_port --tls

If your database requires a password, set the REDISCLI_AUTH environment variable first. That keeps the secret out of your shell history and process list, which is preferable on shared systems:

export REDISCLI_AUTH=your_redis_password
redis-cli -h managed_redis_hostname -p managed_redis_tls_port --tls

Alternatively, you can pass the password on the command line with -a, though that is less ideal when other users can inspect running processes:

redis-cli -h managed_redis_hostname -p managed_redis_tls_port --tls -a your_redis_password

To confirm the connection without entering interactive mode, send a single PING command:

redis-cli -h managed_redis_hostname -p managed_redis_tls_port --tls ping

A successful connection returns:

Output
PONG

If you see PONG, TLS negotiation succeeded and the server accepted your connection. You can proceed to interactive commands or continue to the stunnel sections only if you also need a local plaintext port.

Connect with a provider CA certificate file

Some operators issue certificates signed by a private CA. When Ubuntu does not already trust that CA, download the provider’s CA bundle (for example, ca.pem from the control panel) and pass it explicitly:

redis-cli -h managed_redis_hostname -p managed_redis_tls_port \
  --tls --cacert /path/to/ca.pem

Restrict permissions on the PEM file so only your user can read it:

chmod 600 /path/to/ca.pem

Connect with mutual TLS

When the server requires a client certificate, add your client public and private keys to the command:

redis-cli -h managed_redis_hostname -p managed_redis_tls_port \
  --tls \
  --cacert /path/to/ca.pem \
  --cert /path/to/client.crt \
  --key /path/to/client.key

URI syntax

redis-cli also accepts a connection URI. For TLS, use the rediss:// scheme described in the redis-cli documentation:

redis-cli -u rediss://default:your_redis_password@managed_redis_hostname:managed_redis_tls_port

If native TLS works for your environment, you can use redis-cli for day-to-day administration without stunnel. The following steps configure stunnel for cases where you still need a local plaintext port.

Stunnel acts as a local proxy: redis-cli connects to 127.0.0.1:8000 in plaintext TCP, and stunnel handles TLS to your managed Redis endpoint. On Debian and Ubuntu, stunnel integrates with systemd and uses /etc/default/stunnel4 for service enablement.

Enable automatic startup

Open the defaults file in your preferred editor:

sudo nano /etc/default/stunnel4

Set ENABLED to 1 so stunnel starts at boot and when you restart the service:

# Change to one to enable stunnel automatic startup
ENABLED=1

Save and close the file.

Create the tunnel configuration

Create or edit the main stunnel configuration file:

sudo nano /etc/stunnel/stunnel.conf

Add the following content, adjusting placeholders for your environment:

fips = no
setuid = nobody
setgid = nogroup
pid = /tmp/stunnel-redis.pid
debug = 5
delay = yes

[redis-cli]
client = yes
accept = 127.0.0.1:8000
connect = managed_redis_hostname_or_ip:managed_redis_tls_port
verifyChain = yes
CApath = /etc/ssl/certs

Global options apply to every service in the file:

• fips: When set to yes, stunnel enforces FIPS 140-3 mode. Setting no keeps the default cipher behavior without extra FIPS configuration.
• setuid / setgid: After initialization, stunnel drops privileges to nobody and nogroup, as recommended in the stunnel documentation.
• pid: Writes the process ID to /tmp/stunnel-redis.pid, which is writable after privilege drop. Using /tmp avoids permission errors with /var/run/stunnel4/ when running as nobody.
• debug: Logging verbosity from 0 (quiet) to 7 (verbose). Level 5 is the default and is usually enough for production; raise it temporarily when diagnosing handshake failures.
• delay: Delays the DNS lookup for connect and avoids caching resolved addresses, which helps tunnels recover when a managed endpoint changes during maintenance or failover.

Service options under [redis-cli] define the tunnel:

• client = yes: Run stunnel in client mode toward the remote TLS server.
• accept: Local address and port where stunnel listens (127.0.0.1:8000). Only processes on this server can use the tunnel, which is appropriate for administrative access.
• connect: Remote managed Redis hostname and TLS port.
• verifyChain / CApath: Validate the server certificate against the system CA store in /etc/ssl/certs, matching the pattern in stunnel’s official client examples.

Save and close the file, then restart stunnel so it loads the new configuration:

sudo systemctl restart stunnel4

To confirm the tunnel is listening on the local port, check for port 8000:

sudo ss -tlnp | grep 8000

Expected output resembles:

Output
LISTEN 0      128        127.0.0.1:8000      0.0.0.0:*    users:(("stunnel4",pid=12345,fd=7))

You can also confirm that stunnel dropped privileges after startup:

ps aux | grep '[s]tunnel'

You should see nobody owning the stunnel4 process.

If stunnel fails to start, inspect the most recent service logs for configuration syntax errors or TLS handshake problems:

sudo journalctl -u stunnel4 -n 50 --no-pager

With stunnel listening on 127.0.0.1:8000, you connect redis-cli over plaintext TCP to the local forwarder. Stunnel encrypts the traffic and forwards it to the remote Redis TLS port. Think of it as a two-hop path: plaintext on the loopback interface, TLS on the wide-area network.

Connect to the local listener:

redis-cli -h 127.0.0.1 -p 8000

You can also use the hostname localhost if you prefer:

redis-cli -h localhost -p 8000

Do not pass --tls to redis-cli for this path. TLS termination happens inside stunnel, and adding --tls here would make redis-cli try to negotiate TLS twice.

If your database requires authentication, export the password before connecting:

export REDISCLI_AUTH=your_redis_password
redis-cli -h 127.0.0.1 -p 8000

Your prompt should reflect the local endpoint:

Once connected, test the tunnel with PING:

ping

Output
PONG

A PONG response means stunnel forwarded your command and the remote Redis server replied. If stunnel cannot reach the remote host or TLS negotiation fails, redis-cli may print:

Output
Could not connect to Redis at 127.0.0.1:8000: Connection refused

or, after connecting briefly:

Output
Error: Server closed the connection

See the troubleshooting section for structured steps to resolve these errors.

When you finish, exit interactive mode:

exit

If you change stunnel’s configuration later, reload the service so it picks up the new settings:

sudo systemctl reload stunnel4

You can stop or start the tunnel when needed:

sudo systemctl stop stunnel4
sudo systemctl start stunnel4

Despite following all the setup instructions, connection or authentication problems can still occasionally arise when connecting to your managed Redis instance through stunnel. These issues are typically caused by configuration mismatches, permission errors, or incorrect connection parameters. Below are the most common errors you might encounter, explanations for their causes, and steps you can take to resolve them effectively.

Error: Server closed the connection

This error occurs when redis-cli is able to connect to the local stunnel port, but stunnel itself cannot create or maintain a secure connection with the remote Redis server. The complete output often looks like:

Error: Server closed the connection

This is most often caused by an incorrect hostname or port specified in the /etc/stunnel/stunnel.conf file. To address this, open your stunnel configuration and carefully verify that the connect directive exactly reflects the Redis server’s hostname and TLS port as provided by your cloud provider:

connect = your_redis_host:your_redis_port

Also double-check that the accept directive’s port number matches both what you configured in stunnel and what you specify to redis-cli. For instance, if you are using port 8000 for the local tunnel, your command should be:

redis-cli -h 127.0.0.1 -p 8000

If your managed Redis cluster was recently restarted or scaled, this can also cause connection resets. Usually, reconnecting and reauthenticating will restore normal operation.

Connection refused When Running redis-cli

If you try to connect with redis-cli and see a message such as:

Could not connect to Redis at 127.0.0.1:8000: Connection refused

it usually means that the stunnel service is not running or is not listening on the expected port.

Begin by checking the status of the stunnel4 service:

sudo systemctl status stunnel4

If the service is stopped or has failed, try starting or restarting it:

sudo systemctl restart stunnel4

To be certain that stunnel is actively listening on your desired port, run:

sudo ss -tlnp | grep stunnel

If you do not see any output indicating a listening port, stunnel likely failed to start up properly. In that case, review your configuration file for mistakes, and check the service logs to identify the root cause:

sudo journalctl -u stunnel4 -n 50 --no-pager

Carefully review the output to determine if the problem is due to a misconfiguration, DNS failure, or permissions issue.

Authentication required or NOAUTH Authentication required

Many managed Redis databases require password authentication before allowing command execution. If you attempt to run commands without first authenticating, Redis will respond with an error similar to:

(error) NOAUTH Authentication required.

To authenticate, use the -a option when you connect:

redis-cli -h 127.0.0.1 -p 8000 -a your_password

Alternatively, after entering the CLI, you can manually authenticate with:

auth your_password

Double-check the password against the precise value found in your cloud provider’s dashboard, as even minor formatting mistakes or trailing spaces will prevent successful authentication.

stunnel4 Starts but Immediately Exits

Right after installation or configuration changes, you may notice with systemctl status stunnel4 that the service is marked as active (exited). If, after updating your configs, stunnel still exits immediately upon startup, it is often due to the tunnel not being properly enabled.

Open /etc/default/stunnel4 and confirm:

ENABLED=1

If ENABLED is 0, stunnel will not stay running. After you change it, restart the service:

sudo systemctl restart stunnel4

Verify the process is listening with sudo systemctl status stunnel4 or sudo ss -tlnp | grep stunnel.

Permission Errors Related to the PID File

After stunnel drops privileges to nobody, it must still write its PID file. A path under /var/run that nobody cannot access will prevent startup.

This guide uses a PID file under /tmp, which matches Step 3:

pid = /tmp/stunnel-redis.pid

If you changed the pid path, ensure the directory exists and is writable by nobody:

sudo touch /tmp/stunnel-redis.pid
sudo chown nobody:nogroup /tmp/stunnel-redis.pid

Update stunnel.conf if needed, then restart:

sudo systemctl restart stunnel4

If the directory path is incorrect, or if the service account lacks permissions, correct this before attempting to restart the service.

DNS Resolution Failures

If stunnel cannot resolve your managed Redis hostname (for example, after a DNS change by your managed Redis provider, or if there is a network misconfiguration), outbound connections fail. Logs often mention DNS lookups or timeouts.

You can test DNS resolution on your machine with:

nslookup your_redis_host

or:

ping your_redis_host

If your server cannot resolve the name, verify that you have correct and current host/port details from your managed Redis provider and confirm that your server’s outbound network access is functional.

To avoid issues with stale DNS entries (especially if your managed Redis provider frequently changes host IPs), add the following option to your stunnel.conf file:

delay = yes

The delay directive tells stunnel to perform a new DNS lookup every time it initiates a connection, reducing the risk of problems during infrastructure changes at your managed Redis provider.

How do I connect to Redis with TLS using stunnel?

Start by installing stunnel and redis-tools, then define a client tunnel in /etc/stunnel/stunnel.conf as described in Step 3. Set client = yes, point connect at your managed Redis hostname and TLS port, and bind a local listener with accept (for example, 127.0.0.1:8000). For certificate validation, enable chain verification with verifyChain = yes and trust system CAs with CApath = /etc/ssl/certs. If you are not using the system store, supply a provider bundle with CAfile instead.

Once you enable stunnel in /etc/default/stunnel4 and restart the service, connect through the local port without --tls:

export REDISCLI_AUTH=your_redis_password
redis-cli -h 127.0.0.1 -p 8000

In this setup, redis-cli speaks plaintext TCP to stunnel on the loopback interface, and stunnel handles encryption before forwarding traffic to the remote TLS endpoint. See Step 4 for the full connection workflow.

How do I connect to Redis through redis-cli directly?

Most managed Redis services require TLS. With Redis 6 and later, redis-cli supports native TLS connections using the --tls flag:

redis-cli -h managed_redis_hostname -p managed_redis_tls_port --tls

If your provider uses a private Certificate Authority (CA), specify the CA bundle explicitly:

redis-cli -h managed_redis_hostname -p managed_redis_tls_port \
  --tls --cacert /path/to/ca.pem

You can also authenticate by exporting the password beforehand:

export REDISCLI_AUTH=your_redis_password
redis-cli -h managed_redis_hostname -p managed_redis_tls_port --tls

Before relying on TLS flags, confirm that your redis-cli binary was compiled with TLS support:

redis-cli --help 2>&1 | grep -E '\-\-tls|\-\-cacert'

If --tls does not appear in the help output, your client was built without TLS support. In that case, use the stunnel workflow described earlier in this guide.

Some self-managed Redis deployments may still expose a plaintext endpoint. In those environments, you can connect without TLS:

redis-cli -h managed_redis_hostname -p managed_redis_port -a your_redis_password

Only use plaintext connections when your provider or environment explicitly supports them.

Why does redis-cli return Could not connect to Redis at 127.0.0.1:6379: Connection refused?

That message means nothing is listening on the host and port redis-cli targeted. Because the default port is 6379, you often see this error when you omit -p while stunnel is bound to a different local port (such as 8000).

In a stunnel setup, connection refused usually means stunnel is stopped, failed to start, or is listening on a different address or port than you passed to redis-cli. Start by checking the service:

sudo systemctl status stunnel4

Next, confirm a stunnel process is running and note which port it owns:

ps aux | grep '[s]tunnel'
sudo ss -tlnp | grep stunnel

The accept value in /etc/stunnel/stunnel.conf must match the port in your redis-cli command. If the service is down or misconfigured, inspect recent logs:

sudo journalctl -u stunnel4 -n 50 --no-pager

See the troubleshooting section for additional steps when the tunnel refuses connections or closes immediately.

What is the purpose of the CAfile directive in stunnel.conf?

The CAfile directive tells stunnel where to find a PEM file containing one or more trusted Certificate Authority certificates. It uses that bundle when validating the managed Redis server’s TLS certificate.

This guide’s example tunnel uses CApath = /etc/ssl/certs instead, which loads hashed CA certificates from the system store, following the same pattern in the stunnel Unix configuration examples. Reach for CAfile when your managed Redis provider ships a private CA bundle that is not already in /etc/ssl/certs.

Whichever option you choose, pair it with chain verification:

verifyChain = yes

With verification enabled, stunnel checks that the server certificate chains to a trusted root, which helps prevent man-in-the-middle attacks on the outbound TLS connection.

Can I use stunnel to connect to DigitalOcean Managed Redis on Windows?

Yes. stunnel provides a Windows installer and supports the same configuration directives as on Linux, including client, accept, connect, verifyChain, CAfile, and pid.

Install stunnel from the official site, create a stunnel.conf with your DigitalOcean connection hostname and TLS port, and use Windows-style paths for CAfile and pid. After you start the stunnel service, point redis-cli at the local accept port, the same two-hop pattern as Step 4, without passing --tls to the client.

What is the difference between stunnel client mode and server mode?

In client mode (client = yes), stunnel listens for plaintext connections locally and initiates TLS toward a remote server. That is the mode you use when redis-cli or another tool expects a plaintext TCP socket but your managed Redis endpoint speaks TLS.

Server mode works the other way around: stunnel terminates incoming TLS from remote clients and forwards decrypted traffic to a local service. Managed Redis providers already expose a TLS listener, so you connect as a TLS client (either with redis-cli --tls or with stunnel in client mode), rather than by running stunnel as a TLS server in front of Redis.

Is stunnel still necessary if I have Redis 6 or later?

For most new deployments, no. Redis 6 added native TLS, and current redis-cli builds on Ubuntu 24.04 can use --tls directly, which is the approach recommended in the introduction and Step 2.

Stunnel still earns its place when redis-cli lacks TLS at compile time, when a legacy application only supports plaintext TCP, or when you cannot change an application’s connection settings. For day-to-day administration on a modern client, prefer native TLS and keep stunnel as a compatibility layer when those constraints apply.

How do I run stunnel automatically on system startup?

On Ubuntu and Debian, enable the packaged service after you set ENABLED=1 in /etc/default/stunnel4 and place your tunnel in /etc/stunnel/stunnel.conf, as shown in Step 3:

sudo systemctl enable stunnel4

Confirm systemd will start the unit at boot:

systemctl is-enabled stunnel4

After a reboot, verify the tunnel is still active:

sudo systemctl status stunnel4
sudo ss -tlnp | grep 8000

On CentOS, RHEL, and similar distributions, the unit is often named stunnel rather than stunnel4; use sudo systemctl enable stunnel on those platforms. Your configuration still lives under /etc/stunnel/.

You can administer a managed Redis instance over TLS in two dependable ways. Native redis-cli TLS (Redis 6 and later) is the preferred path: fewer components, direct certificate control with --cacert, and alignment with the Redis TLS documentation referenced at the start of this guide. Stunnel remains a solid fallback when you need a local plaintext port or must support clients without TLS.

Understanding CA certificate verification keeps both approaches secure. Trust the right roots, protect PEM files on disk, and reserve --insecure for non-production testing only.

When something fails, treat connection refused as a routing or listener problem: confirm the process is listening, the port and TLS settings match your managed Redis provider, and your client’s IP is allowed through the managed firewall.

From here, you can explore data management and application integration. If you are new to Redis administration, check out the following tutorials:

• Install and Secure Redis on Ubuntu: Guide
• How To Change Redis’s Configuration from the Command Line
• How To Connect to a Redis Database
• How To Manage Redis Databases and Keys