VALKEY-ENCRYPTION(7)

✨ VALKEY-ENCRYPTION(7) ✨

okay bestie, buckle up, because this is the Valkey Manual page about TLS and it's genuinely so good 🫶 (the manual name is valkey-encryption, and the whole thing lives in section 7 of the Valkey manual, iykyk)

---

💖 NAME 💖

valkey-encryption — TLS, babes. that's it, that's the name.

---

🌸 DESCRIPTION 🌸

SSL/TLS is supported by Valkey as an optional feature — meaning it's not just vibing there by default, it needs to be enabled at compile time. no cap. you gotta opt in 💅

🎀 Getting Started 🎀

🔧 Building

to build with TLS support you'll need OpenSSL development libraries (like libssl-dev on Debian/Ubuntu, that's the one).

Build Valkey with this exact command, don't freestyle it:

make BUILD_TLS=yes

🧪 Tests

to run the Valkey test suite with TLS, you'll need TLS support for TCL (i.e. the tcl-tls package on Debian/Ubuntu). lowkey essential, fr fr.

1. Run ./utils/gen-test-certs.sh to generate a root CA and a server certificate.
2. Run ./runtest --tls or ./runtest-cluster --tls to run Valkey and Valkey Cluster tests in TLS mode.

🚀 Running manually

to manually run a Valkey server in TLS mode (assuming gen-test-certs.sh was invoked so sample certificates/keys are available, bestie — that part matters):

./src/valkey-server --tls-port 6379 --port 0 \
    --tls-cert-file ./tests/tls/valkey.crt \
    --tls-key-file ./tests/tls/valkey.key \
    --tls-ca-cert-file ./tests/tls/ca.crt

and to connect to this Valkey server with valkey-cli:

./src/valkey-cli --tls \
    --cert ./tests/tls/valkey.crt \
    --key ./tests/tls/valkey.key \
    --cacert ./tests/tls/ca.crt

slay. look at you go 💅✨

📜 Certificate configuration 📜

so, in order to support TLS, Valkey must be configured with a X.509 certificate and a private key. and that's not all — you also need to specify a CA certificate bundle file or path, to be used as a trusted root when validating certificates. and if you want to support DH based ciphers, a DH params file can also be configured. here's the whole look:

tls-cert-file /path/to/valkey.crt
tls-key-file /path/to/valkey.key
tls-ca-cert-file /path/to/ca.crt
tls-dh-params-file /path/to/valkey.dh

🔌 TLS listening port 🔌

the tls-port configuration directive enables accepting SSL/TLS connections on the specified port. and the way that this is in addition to listening on a port for TCP connections — so yes, you can access Valkey on different ports using TLS and non-TLS connections simultaneously. iconic behaviour, honestly.

you may specify port 0 to disable the non-TLS port completely. to enable only TLS on the default Valkey port, use:

port 0
tls-port 6379

🪪 Client certificate authentication 🪪

by default, Valkey uses mutual TLS and requires clients to authenticate with a valid certificate (authenticated against trusted root CAs specified by ca-cert-file or ca-cert-dir). yes, everyone shows ID at the door 💅

you may use tls-auth-clients no to disable client authentication. your call, bestie.

🔁 Replication 🔁

a Valkey primary server handles connecting clients and replica servers in the same way, so the above tls-port and tls-auth-clients directives apply to replication links as well.

on the replica server side, it is necessary to specify tls-replication yes to use TLS for outgoing connections to the primary. don't forget it, or your replica is just yelling into the void 🙈

🕸️ Cluster 🕸️

when Valkey Cluster is used, use tls-cluster yes in order to enable TLS for the cluster bus and cross-node connections.

👑 Sentinel 👑

Sentinel inherits its networking configuration from the common Valkey configuration, so all of the above applies to Sentinel as well.

when connecting to primary servers, Sentinel will use the tls-replication directive to determine if a TLS or non-TLS connection is required.

in addition, the very same tls-replication directive will determine whether Sentinel's port — the one that accepts connections from other Sentinels — will support TLS as well. that is, Sentinel will be configured with tls-port if and only if tls-replication is enabled. main character energy, honestly 👑

⚙️ Additional configuration ⚙️

additional TLS configuration is available to control the choice of TLS protocol versions, ciphers and cipher suites, etc. please consult the self documented valkey.conf for more information. it's self documented, so it will explain itself, unlike some people 😭

🏎️ Performance considerations 🏎️

TLS adds a layer to the communication stack with overheads due to writing/reading to/from an SSL connection, encryption/decryption and integrity checks. consequently, using TLS results in a decrease of the achievable throughput per Valkey instance.

so like… secure? yes. free? absolutely not. that's just the tax, bestie 💀

---

and that's the whole page!! this one is from version 9.0.0, dated 2025-10-21 — go forth and encrypt everything, you gorgeous nerd 🦋💖