title: Audit connection events

summary: Describes how to audit connection events.

title: Overview

text:
Starting with version 6.2.18, Redis Software lets you audit database connection and authentication events.  This helps you track and troubleshoot connection activity.

The following events are tracked:

- Database connection attempts
- Authentication requests, including requests for new and existing connections
- Database disconnects

When tracked events are triggered, notifications are sent via TCP to an address and port defined when auditing is enabled.  Notifications appear in near real time and are intended to be consumed by an external listener, such as a TCP listener, third-party service, or related utility.

Example external listeners include:

- [`ncat`](https://nmap.org/ncat/): useful for debugging but not suitable for production environments.

- Imperva Sonar: a third-party service available for purchase separately from Redis Software. See [Redis Onboarding Steps](https://docs.imperva.com/bundle/onboarding-databases-to-sonar-reference-guide/page/Redis-Onboarding-Steps_48368215.html) for more information.

For development and testing environments, notifications can be saved to a local file; however, this is neither supported nor intended for production environments.

For performance reasons, auditing is not enabled by default.  In addition, auditing occurs in the background (asynchronously) and is non-blocking by design.  That is, the action that triggered the notification continues without regard to the status of the notification or the listening tool.

title: Enable audit notifications

title: Cluster audits

text:
To enable auditing for your cluster, use:

- `rladmin`

    [code example]

    where:

    - _audit\_protocol_ indicates the protocol used to process notifications.  For production systems, _TCP_ is the only value.

    - _audit\_address_ defines the TCP/IP address where one can listen for notifications

    - _audit\_port_ defines the port where one can listen for notifications

    - _audit\_reconnect\_interval_ defines the interval (in seconds) between attempts to reconnect to the listener. Default is 1 second.

    - _audit\_reconnect\_max\_attempts_ defines the maximum number of attempts to reconnect. Default is 0. (infinite)

    Development systems can set _audit\_protocol_ to `local` for testing and training purposes; however, this setting is _not_ supported for production use.

    When `audit_protocol` is set to `local`, `<address>` should be set to a [stream socket](https://man7.org/linux/man-pages/man7/unix.7.html) defined on the machine running Redis Software and _`<port>`_ should not be specified:

    [code example]

    The socket file (and path) must be accessible by the user and group running Redis Software.

- the [REST API]()

    [code example]

    where `<address>` is a string containing the TCP/IP address, `<port>` is a numeric value representing the port, `<interval>` is a numeric value representing the interval in seconds, and `<max attempts>` is a numeric value representing the maximum number of attempts to execute.

title: Database audits

text:
Once auditing is enabled for your cluster, you can audit individual databases.  To do so, use:

- `rladmin`

    [code example]

    where the value of the _db:_ parameter is either the cluster ID of the database or the database name.

    To deactivate auditing, set `db_conns_auditing` to `disabled`.

    Use `rladmin info` to retrieve additional details:

    [code example]

- the [REST API]()

    [code example]

    To deactivate auditing, set `db_conns_auditing` to `false`.

You must enable auditing for your cluster before auditing a database; otherwise, an error appears:

>  _Error setting description: Unable to enable DB Connections Auditing before feature configurations are set.
>  Error setting error_code: db_conns_auditing_config_missing_

To resolve this error, enable the protocol for your cluster _before_ attempting to audit a database.

title: Policy defaults for new databases

text:
To audit connections for new databases by default, use:

- `rladmin`

    [code example]

    To deactivate this policy, set `db_conns_auditing` to `disabled`.

- the [REST API]()

    [code example]

    To deactivate this policy, set `db_conns_auditing` to `false`.

title: Notification examples

text: Audit event notifications are reported as JSON objects.

title: New connection

text:
This example reports a new connection for a database:

[code example]

title: Authentication request

text:
Here is a sample authentication request for a database:

[code example]

The `status` field reports the following:

- Values of 2, 7, or 8 indicate success.

- Values of 3 or 5 indicate that the client authentication is in progress and should conclude later.

- Other values indicate failures.

title: Database disconnect

text:
Here's what's reported when a database connection is closed:

[code example]

title: Notification field reference

text:
The field value that appears immediately after the timestamp describes the action that triggered the notification.  The following values may appear:

- `new_conn` indicates a new external connection
- `new_int_conn` indicates a new internal connection
- `close_conn` occurs when a connection is closed
- `"action":"auth"` indicates an authentication request and can refer to new authentication requests or authorization checks on existing connections

In addition, the following fields may also appear in audit event notifications:

| Field name | Description |
|:---------:|-------------|
| `acl-rules` | ACL rules associated with the connection, which includes a rule for the `default` user. |
| `bdb_name` | Destination database name - The name of the database being accessed. |
| `bdb_uid` | Destination database ID - The cluster ID of the database being accessed. |
| `hname` | Client hostname - The hostname of the client.  Currently empty; reserved for future use. |
| `id` | Connection ID - Unique connection ID assigned by the proxy. |
| `identity` | Identity - A unique ID the proxy assigned to the user for the current connection. |
| `srcip` | Source IP address - Source TCP/IP address of the client accessing the Redis database. |
| `srcp` | Source port - Port associated with the source IP address accessing the Redis database. Combine the port with the address to uniquely identify the socket. |
| `status` | Status result code - An integer representing the result of an authentication request. |
| `trgip` | Target IP address - The IP address of the destination being accessed by the action. |
| `trgp` | Target port - The port of the destination being accessed by the action.  Combine the port with the destination IP address to uniquely identify the database being accessed. |
| `ts`  | Timestamp - The date and time of the event, in [Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) (UTC).  Granularity is within one second. |
| `username` | Authentication username  - Username associated with the connection; can include `default` for databases that allow default access.  (Passwords are _not_ recorded). |

title: Status result codes

text:
The `status` field reports the results of an authentication request as an integer.  Here's what different values mean:

| Error value | Error code | Description |
|:-------------:|------------|-------------|
| `0` | AUTHENTICATION_FAILED | Invalid username and/or password. |
| `1` | AUTHENTICATION_FAILED_TOO_LONG | Username or password are too long. |
| `2` | AUTHENTICATION_NOT_REQUIRED | Client tried to authenticate, but authentication isn't necessary. |
| `3` | AUTHENTICATION_DIRECTORY_PENDING | Attempting to receive authentication info from the directory in async mode. |
| `4` | AUTHENTICATION_DIRECTORY_ERROR | Authentication attempt failed because there was a directory connection error. |
| `5` | AUTHENTICATION_SYNCER_IN_PROGRESS | Syncer SASL handshake. Return SASL response and wait for the next request. |
| `6` | AUTHENTICATION_SYNCER_FAILED | Syncer SASL handshake. Returned SASL response and closed the connection. |
| `7` | AUTHENTICATION_SYNCER_OK | Syncer authenticated. Returned SASL response. |
| `8` | AUTHENTICATION_OK | Client successfully authenticated. |

code:
rladmin cluster config auditing db_conns \
       audit_protocol <TCP|local> \
       audit_address <address> \
       audit_port <port> \
       audit_reconnect_interval <interval in seconds> \
       audit_reconnect_max_attempts <number of attempts>

section_id: cluster-audits

code:
rladmin cluster config auditing db_conns \
       audit_protocol local audit_address <socket-file>

code:
PUT /v1/cluster/auditing/db_conns
    {
        "audit_address": "<address>",
        "audit_port": <port>,
        "audit_protocol": "TCP",
        "audit_reconnect_interval": <interval>,
        "audit_reconnect_max_attempts": <max attempts>
    }

code: rladmin tune db db:<id|name> db_conns_auditing enabled

section_id: database-audits

code:
rladmin info db <id|name>
    rladmin info cluster

code:
PUT /v1/bdbs/1
    { "db_conns_auditing": true }

code: rladmin tune cluster db_conns_auditing enabled

section_id: policy-defaults-for-new-databases

code:
PUT /v1/cluster/policy
    { "db_conns_auditing": true }

section_id: new-connection

action: auth

section_id: authentication-request

section_id: database-disconnect


title: Certificate-based authentication

summary: Certificate-based authentication allows secure, passwordless access to the REST API and databases.

page_type: content

title: Overview

role: overview

text: You can set up certificate-based authentication for specific users to enable secure, passwordless access to the Redis Software [REST API]() and databases.

title: Certificate-based authentication for the REST API

role: content

title: Set up certificate-based authentication for the REST API

text:
To set up certificate-based authentication:

1. Add a trusted CA certificate `mtls_trusted_ca` to the cluster using an [update cluster certificates]() request:

    **Redis Software v7.22.2 and later:**

For Redis Software versions 7.22.2 and later, use:

[code example]

**Redis Software v7.22.0 and earlier:**

For Redis Software versions 7.22.0 and earlier, use:

[code example]

1. [Update cluster settings]() with mutual TLS (mTLS) configuration using one of the following options:

    **Without subject validation:**

Additional certificate validation is optional. To enable mutual TLS without subject validation, use:

[code example]

**With SAN validation:**

For certificate validation by Subject Alternative Name (SAN), use:

[code example]

Replace the placeholder value `<>` with your client certificate's Subject Common Name or SAN DNS entry.

**Example certificate and mTLS settings**

If a client certificate has:

- Subject: `CN=client.example.com`

- SAN: `DNS:app1.example.com, DNS:client.example.com, DNS:app1-prod.example.com`

You can use any of these values for the CN in `mtls_authorized_subjects`:

[code example]

**With Full Subject Name validation:**

For certificate validation by full Subject Name, use:

[code example]

Replace the placeholder values `<>` with your client certificate's subject values.

**Example certificate and mTLS settings**

If a client certificate has:

- Subject: `CN=client.example.com`

- SAN: `DNS:app1.example.com, DNS:client.example.com, DNS:app1-prod.example.com`

You can use any of these values for the CN in `mtls_authorized_subjects`:

[code example]

1. When you [create new users](), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body:

    [code example]

    Replace the placeholder values `<>` with your client certificate's subject values.

title: Authenticate REST API requests

role: security

text:
To use the REST API with certificate-based authentication, you must provide a client certificate, signed by the trusted CA `mtls_trusted_ca`, and a private key.

The following example uses [cURL](https://curl.se/) to send a [REST API request]():

[code example]

title: Certificate-based authentication for databases

title: Set up certificate-based authentication for databases

text:
To set up certificate-based authentication for databases:

1. Enable mutual TLS for the relevant databases. See [Enable TLS]() for detailed instructions.

1. When you [create new users](), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body :

    [code example]

    Replace the placeholder values `<>` with your client certificate's subject values.

title: Authenticate database connections

text:
To connect to a database with certificate-based authentication, you must provide a client certificate, signed by the trusted CA `mtls_trusted_ca`, and a private key.

The following example shows how to connect to a Redis database with [`redis-cli`]():

[code example]

title: Limitations

role: limits

text: - Certificate-based authentication is not implemented for the Cluster Manager UI.

code:
PUT /v1/cluster/certificates
{
  "certificates": [
    {
      "name": "mtls_trusted_ca",
      "certificate": "<content of certificate PEM file>"
    }
  ]
}

code:
PUT /v1/cluster/update_cert
{
  "name": "mtls_trusted_ca",
  "certificate": "<content of certificate PEM file>"
}

code:
PUT /v1/cluster
{
  "mtls_certificate_authentication": true,
  "mtls_client_cert_subject_validation_type": "disabled"
}

code:
PUT /v1/cluster
{
  "mtls_certificate_authentication": true,
  "mtls_client_cert_subject_validation_type": "san_cn",
  "mtls_authorized_subjects": [{
    "CN": "<Subject Common Name or SAN DNS entry>"
  }]
}

code:
PUT /v1/cluster
{
  "mtls_certificate_authentication": true,
  "mtls_client_cert_subject_validation_type": "san_cn",
  "mtls_authorized_subjects": [
    {"CN": "client.example.com"},   // Subject CN
    {"CN": "app1.example.com"},     // SAN DNS entry
    {"CN": "app1-prod.example.com"} // Another SAN DNS entry
  ]
}

code:
PUT /v1/cluster
{
  "mtls_certificate_authentication": true,
  "mtls_client_cert_subject_validation_type": "full_subject",
  "mtls_authorized_subjects": [{
    "CN": "<Common Name>",
    "OU": [<array of Organizational Unit strings>],
    "O": "<Organization>",
    "C": "<2-letter country code>",
    "L": "<Locality (city)>",
    "ST": "<State/Province>"
  }]
}

code:
POST /v1/users
    {
      "auth_method": "certificate",
      "certificate_subject_line": "CN=<Common Name>, OU=<Organization Unit>, O=<Organization>, L=<Locality>, ST=<State/Province>, C=<Country>"
    }

code: curl --request <METHOD> --url https://<hostname-or-IP-address>:9443/<API-version>/<API-path> --cert client.pem --key client.key

section_id: authenticate-rest-api-requests

code: redis-cli -h <hostname-or-IP-address> -p <port> --tls --cacert <redis_cert>.pem --cert redis_user.crt --key redis_user_private.key

section_id: authenticate-database-connections


title: Create certificates

summary: Create self-signed certificates to install on a Redis Software cluster.

title: Overview

text:
When you first install Redis Software, self-signed certificates are created to enable encryption for Redis Software endpoints.  These certificates expire after a year (365 days) and must be renewed.

You can renew these certificates by replacing them with new self-signed certificates or by replacing them with certificates signed by a [certificate authority](https://en.wikipedia.org/wiki/Certificate_authority) (CA).

title: Renew self-signed certificates

text:
As of [v6.2.18-70](), Redis Software includes a script to generate self-signed certificates.

By default, the `generate_self_signed_certs.sh` script is located in `/opt/redislabs/utils/`.

Here, you learn how to use this script to generate new certificates and how to install them.

title: Generate self-signed certs script options

text:
You can run the `generate_self_signed_certs.sh` script with the following options:

| Option | Description |
|----------|-------------|
| `-h`
`--help` | Displays usage instructions. (Optional) |
| `-d <days>`
`--days <days>` | Number of days the self-signed certificate is valid for. Setting this field longer than a year (365 days) is not recommended. (Optional, default: 365) |
| `-f <names>`
<nobr>`--fqdnNames <names>`</nobr> | Space-separated list of [fully qualified domain names (FQDNs)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name). Used for [storage area networks (SANs)](https://en.wikipedia.org/wiki/Storage_area_network). (Required)
Example: `-f "redis.example.com redis-1.example.com"` |
| `-t <type>`
`--type <type>` | Type of certificate to generate. (Optional, default: all)
Values:
**cm**: Cluster Manager UI certificate
**api**: REST API certificate
 **proxy**: database endpoint proxy certificate
**syncer**: syncer component certificate
**metrics**: metrics exporter certificate
**all**: generates all certificate types |

title: Step 1: Generate new certificates

text:
Sign in to the machine hosting the cluster's master node and then run the following command:

[code example]

When you run the script, it either reports success (`"Self signed cert generated successfully"`) or an error message. Use the error message to troubleshoot any issues.

The following example generates all self signed certificates for `mycluster.example.com`; these certificates expire one year after the command is run:

[code example]

Suppose you want to create a Cluster Manager UI certificate to support two clusters for a period of two years.  The following example shows how:

[code example]

Here, a certificate file and certificate key are generated to support the following domains:

[code example]

title: Step 2: Locate the new certificate files

text:
When successful, the script generates two .PEM files for each generated certificate: a certificate file and a certificate key, each named after the type of certificate generated (see earlier table for individual certificate names.)

These files can be found in the `/tmp` directory.

[code example]

title: Step 3: Set permissions

text:
We recommend setting the permissions of your new certificate files to limit read and write access to the file owner and to set group and other user permissions to read access.

[code example]

title: Step 4: Replace existing certificates {#replace-self-signed}

text:
You can use `rladmin` to replace the existing certificates with new certificates:

[code example]

The following values are supported for the _\<CertName>_ parameter:

| Value | Description |
|-------|-------------|
| `api` | The REST API |
| `cm` | The Cluster Manager UI |
| `metrics_exporter` | The metrics exporter |
| `proxy` | The database endpoint |
| `syncer` | The synchronization process |

You can also use the REST API.  To learn more, see [Update certificates]().

title: Create CA-signed certificates

text:
You can use certificates signed by a [certificate authority](https://en.wikipedia.org/wiki/Certificate_authority) (CA).

For best results, use the following guidelines to create the certificates.

title: TLS certificate guidelines

text:
When you create certificates signed by a certificate authority, you need to create server certificates and client certificates.  The following provide guidelines that apply to both certificates and guidance for each certificate type.

#### Guidelines for server and client certificates

1.  Include the full [certificate chain](https://en.wikipedia.org/wiki/X.509#Certificate_chains_and_cross-certification) when creating certificate .PEM files for either server or client certificates.

1.  List (_chain_) certificates in the .PEM file in the following order:

    [code example]

#### Server certificate guidelines

Server certificates support clusters.

In addition to the general guidelines described earlier, the following guidelines apply to server certificates:

1.  Use the cluster's fully qualified domain name (FQDN) as the certificate Common Name (CN).

1.  Set the following values according to the values specified by your security team or certificate authority:

    - Country Name (C)
    - State or Province Name (ST)
    - Locality Name (L)
    - Organization Name (O)
    - Organization Unit  (OU)

1.  The [Subject Alternative Name](https://en.wikipedia.org/wiki/Subject_Alternative_Name) (SAN) should include the following values based on the FQDN:

    [code example]

1.  The Extended Key Usage attribute should be set to `TLS Web Client Authentication` and `TLS Web Server Authentication`.

1.  We strongly recommend using a strong hash algorithm, such as <nobr>SHA-256</nobr> or <nobr>SHA-512</nobr>.

    Individual operating systems might limit access to specific algorithms.  For example, Ubuntu 20.04 [limits  access](https://manpages.ubuntu.com/manpages/focal/man7/crypto-policies.7.html) to <nobr>SHA-1</nobr>.  In such cases, Redis Software is limited to the features supported by the underlying operating system.

#### Client certificate guidelines

Client certificates support database connections.

In addition to the general guidelines described earlier, the following guidelines apply to client certificates:

1.  The Extended Key Usage attribute should be set to `TLS Web Client Authentication`.

1.  We strongly recommend using a strong hash algorithm, such as <nobr>SHA-256</nobr> or <nobr>SHA-512</nobr>.

    Individual operating systems might limit access to specific algorithms.  For example, Ubuntu 20.04 [limits  access](https://manpages.ubuntu.com/manpages/focal/man7/crypto-policies.7.html) to <nobr>SHA-1</nobr>.  In such cases, Redis Software is limited to the features supported by the underlying operating system.

title: Create certificates

text:
The actual process of creating CA-signed certificates varies according to the CA.  In addition, your security team may have custom instructions that you need to follow.

Here, we demonstrate the general process using OpenSSL.  If your CA provides alternate tools, you should use those according to their instructions.

However you choose to create the certificates, be sure to incorporate the guidelines described earlier.

1.  Create a private key.

    [code example]

1.  Create a certificate signing request.

    [code example]
    _Important: _ The .CNF file is a configuration file.  Check with your security team or certificate authority for help creating a valid configuration file for your environment.

3.  Sign the private key using your certificate authority.

    [code example]

    The signing process varies for each organization and CA vendor.  Consult your security team and certificate authority for specific instructions describing how to sign a certificate.

4.  Upload the certificate to your cluster.

    You can use [`rladmin`]() to replace the existing certificates with new certificates:

    [code example]

    For a list of values supported by the `<cert-name>` parameter, see the [earlier table](#replace-self-signed).

    You can also use the REST API.  To learn more, see [Update certificates]().

code:
% sudo -u redislabs /opt/redislabs/utils/generate_self_signed_certs.sh \
   -f "<DomainName1 DomainName2>" -d <Days> -t <Type>

code:
$ sudo -u redislabs /opt/redislabs/utils/generate_self_signed_certs.sh \
    -f "mycluster.example.com"`

code:
$ sudo -u redislabs /opt/redislabs/utils/generate_self_signed_certs.sh \
    -f "mycluster.example.com anothercluster.example.com" -d 730 -t cm

code:
mycluster.example.com
*.mycluster.example.com
anothercluster.example.com
*.anothercluster.example.com

code: $ ls -la /tmp/*.pem

code: $ sudo chmod 644 /tmp/*.pem

code:
$ rladmin cluster certificate set <CertName> certificate_file \
   <CertFilename>.pem key_file <KeyFilename>.pem

code:
-----BEGIN CERTIFICATE-----
    Domain (leaf) certificate
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    Intermediate CA certificate
    -----END CERTIFICATE----
    -----BEGIN CERTIFICATE-----
    Trusted Root CA certificate
    -----END CERTIFICATE-----

section_id: tls-certificate-guidelines

code:
dns=<cluster-fqdn>
    dns=*.<cluster-fqdn>
    dns=internal.<cluster-fqdn>
    dns=*.internal.<cluster-fqdn>

code: $ openssl genrsa -out <key-file-name>.pem 2048

section_id: create-certificates

code:
$ openssl req -new -key <key-file-name>.pem -out \
       <key-file-name>.csr -config <csr-config-file>.cnf

code: $ openssl x509 -req -in <key-file-name>.csr -signkey <key-file-name>.pem -out <cert-name>.pem

code:
$ rladmin cluster certificate set <cert-name> certificate_file \
       <cert-name>.pem key_file <key-file-name>.pem


title: Certificates

summary: An overview of certificates in Redis Software.

title: Create certificates

summary: Monitor certificates on a Redis Software cluster.

title: Monitor certificates

summary: Update certificates in a Redis Software cluster.

title: Update certificates

summary: Use OCSP stapling to verify certificates maintained by a third-party CA and authenticate connection attempts between clients and servers.

title: Enable OCSP stapling

title: Certificate-based authentication

title: Overview

text:
Redis Software uses self-signed certificates by default to ensure that the product is secure. These certificates are autogenerated on the first node of each Redis Software installation and are copied to all other nodes added to the cluster.

You can replace a self-signed certificate with one signed by a certificate authority of your choice.

title: Supported certificates

role: compatibility

text:
Here's the list of supported certificates that create secure, encrypted connections to your Redis Software cluster:

| Certificate name | Autogenerated | Description |
|------------------|:---------------:|-------------|
| `api` | ✅ | Encrypts [REST API]() requests and responses. |
| `ccs_internode_encryption` | ✅ | Control plane [internode encryption](). Encrypts internal traffic for cluster management. |
| `cm` | ✅ | Secures connections to the Redis Software Cluster Manager UI. |
| `data_internode_encryption` | ✅ | Data plane [internode encryption](). Encrypts internal data traffic between shards and the data management controller (DMC). |
| `ldap_client` | :x: | Secures connections between LDAP clients and LDAP servers. |
| `metrics_exporter` | ✅ | Sends Redis Software metrics to external [monitoring tools]() over a secure connection. |
| `mtls_trusted_ca` | :x:  | Required to enable certificate-based authentication for secure, passwordless access to the REST API. |
| `proxy` | ✅ | Creates secure, encrypted connections between clients and databases. |
| `sso_issuer` | :x: | Identity provider certificate for [single sign-on (SSO)](). |
| `sso_service` | :x: | Service provider certificate for [single sign-on (SSO)](). |
| `syncer` | ✅ | For [Active-Active]() or [Replica Of]() databases, encrypts data during the synchronization of participating clusters. |

Certificates that are not autogenerated are optional unless you want to use certain features. For example, you must provide your own `ldap_client` certificate to enable [LDAP authentication](), an `mtls_trusted_ca` certificate to enable certificate-based authentication, or `sso_issuer` and `sso_service` certificates for [single sign-on (SSO)]().

title: Accept self-signed certificates to access the Cluster Manager UI

text: When you use the default self-signed certificates and you connect to the Cluster Manager UI over a web browser, you'll see an untrusted connection notification. Depending on your browser, you can allow the connection for each session or add an exception to trust the certificate for all future sessions.


title: Monitor certificates

title: Overview

text:
Redis Software exposes the expiration time in seconds of each certificate on each node. You can use Prometheus to monitor these certificates.

To learn how to monitor Redis Software metrics using Prometheus, see [Monitoring with metrics and alerts]() and the [Prometheus integration quick start]().

title: V1 metrics

text: The [v1 metrics]() endpoint (`https://<cluster_name>:8070/`) uses `node_cert_expiration_seconds`.

title: Certificate expiration in seconds {#v1-cert-expire-seconds}

text:
[code example]

The following certificates relate to [internode communication TLS encryption]() and are automatically rotated by Redis Software:

[code example]

title: V2 metrics

text: The [v2 metrics]() endpoint (`https://<cluster_name>:8070/v2`) uses `node_cert_expires_in_seconds`.

title: Certificate expiration in seconds {#v2-cert-expire-seconds}

title: Certificate expiration in days {#v2-cert-expire-days}

code:
max by(filename) (
  max_over_time(node_cert_expires_in_seconds{cluster="$cluster", filename=~"api_cert.pem|cm_cert.pem|metrics_exporter_cert.pem|proxy_cert.pem|syncer_cert.pem|trusted_ca.pem"}[5m])
) / 86400

code:
max by(filename) (
  max_over_time(node_cert_expires_in_seconds{cluster="$cluster", filename=~"ccs_internode_encryption_cert.pem|data_internode_encryption_cert.pem|mesh_ca_signed_cert.pem|gossip_ca_signed_cert.pem"}[5m])
) / 86400


title: Enable OCSP stapling

title: Overview

text:
OCSP ([Online Certificate Status Protocol](https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol)) lets a client or server verify the status (`GOOD`, `REVOKED`, or `UNKNOWN`) of a certificate maintained by a third-party [certificate authority (CA)](https://en.wikipedia.org/wiki/Certificate_authority).

To check whether a certificate is still valid or has been revoked, a client or server can send a request to the CA's OCSP server (also called an OCSP responder). The OCSP responder checks the certificate's status in the CA's [certificate revocation list](https://en.wikipedia.org/wiki/Certificate_revocation_list) and sends the status back as a signed and timestamped response.

title: OCSP stapling overview

text:
With OCSP enabled, the Redis Software server regularly polls the CA's OCSP responder for the certificate's status. After it receives the response, the server caches this status until its next polling attempt.

 When a client tries to connect to the Redis Software server, they perform a [TLS handshake](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_handshake) to authenticate the server and create a secure, encrypted connection. During the TLS handshake, [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling) lets the Redis Software server send (or "staple") the cached certificate status to the client.

If the stapled OCSP response confirms the certificate is still valid, the TLS handshake succeeds and the client connects to the server.

The TLS handshake fails and the client blocks the connection to the server if the stapled OCSP response indicates either:

- The certificate has been revoked.

- The certificate's status is unknown. This can happen if the OCSP responder fails to send a response.

title: Set up OCSP stapling

text:
You can configure and enable OCSP stapling for your Redis Software cluster with the [Cluster Manager UI](#cluster-manager-ui-method), the [REST API](#rest-api-method), or [`rladmin`](#rladmin-method).

While OCSP is enabled, the server always staples the cached OCSP status when a client tries to connect. It is the client's responsibility to use the stapled OCSP status. Some Redis clients, such as [Jedis](https://github.com/redis/jedis) and [redis-py](https://github.com/redis/redis-py), already support OCSP stapling, but others might require additional configuration.

title: Cluster Manager UI method

text:
To set up OCSP stapling with the Redis Software Cluster Manager UI:

1. Go to **Cluster > Security > OCSP**.

1. In the **Responder URI** section, select **Replace Certificate** to update the proxy certificate.

1. Provide the key and certificate signed by your third-party CA, then select **Save**.

1. Configure query settings if you don't want to use their default values:

    | Name | Default value | Description |
    |------|---------------|-------------|
    | **Query frequency** | 1 hour | The time interval between OCSP queries to the responder URI. |
    | **Response timeout** | 1 second | The time interval in seconds to wait for a response before timing out. |
    | **Recovery frequency** | 1 minute | The time interval between retries after a failed query. |
    | **Recovery maximum tries** | 5 | The number of retries before the validation query fails and invalidates the certificate. |

1. Select **Enable** to turn on OCSP stapling.

title: REST API method

text:
To set up OCSP stapling with the [REST API]():

1. Use the REST API to [replace the proxy certificate]() with a certificate signed by your third-party CA.

1. To configure and enable OCSP, send a [`PUT` request to the `/v1/ocsp`]() endpoint and include an [OCSP JSON object]() in the request body:

    [code example]

title: `rladmin` method

text:
To set up OCSP stapling with the [`rladmin`]() command-line utility:

1. Use [`rladmin`]() to [replace the proxy certificate]() with a certificate signed by your third-party CA.

1. Update the cluster's OCSP settings with the [`rladmin cluster ocsp config`]() command if you don't want to use their default values.

    For example:

    [code example]

1. Enable OCSP:

    [code example]

section_id: rest-api-method

code: rladmin cluster ocsp config recovery_frequency set 30

section_id: rladmin-method

code: rladmin cluster ocsp config ocsp_functionality set enabled


title: Update certificates

title: Overview

text: When you update the certificates, the new certificate replaces the same certificates on all nodes in the cluster.

title: How to update certificates

text:
You can use the [`rladmin`]() command-line interface (CLI) or the [REST API]() to update certificates. The Cluster Manager UI lets you update proxy, syncer, and internode encryption certificates on the **Cluster > Security > Certificates** screen.

**Cluster Manager UI:**

To replace proxy, syncer, or internode encryption certificates using the Cluster Manager UI:

1. Go to **Cluster > Security > Certificates**.

1. Expand the section for the certificate you want to update:
    - For internode encryption certificates, expand **Internode encryption certificates**.
    - For the proxy certificate, expand **Server authentication**.
    - For the syncer certificate, expand **Replica Of and Active-Active authentication**.

1. Click **Replace Certificate** to open the dialog.

1. Upload the key file.

1. Upload the new certificate.

1. Click **Save**.

**rladmin:**

To replace certificates with the `rladmin` CLI, run the [`cluster certificate set`]() command:

[code example]

Replace the following variables with your own values:

- `<cert-name>` - The name of the certificate you want to replace. See the [certificates table]() for the list of valid certificate names.
- `<cert-file-name>` - The name of your certificate file
- `<key-file-name>` - The name of your key file

For example, to replace the Cluster Manager UI (`cm`) certificate with the private key `key.pem` and the certificate file `cluster.pem`:

[code example]

**REST API:**

To replace a certificate using the REST API, use an [update cluster certificates]() request.

For Redis Software versions 7.22.2 and later, use:

[code example]

For Redis Software versions 7.22.0 and earlier, use:

[code example]

Replace the following variables with your own values:

- `<cert_name>` - The name of the certificate to replace. See the [certificates table]() for the list of valid certificate names.
- `<key>` - The contents of the \*\_key.pem file

  The key file contains `\n` end of line characters (EOL) that you cannot paste into the API call.
  You can use `sed -z 's/\n/\\\n/g'` to escape the EOL characters.

- `<cert>` - The contents of the \*\_cert.pem file

New proxy and syncer certificates are used the next time clients connect to the database. For internode encryption certificates, the new certificates are used after they are replaced on all existing nodes in the cluster.

When you add a new node to the cluster, the certificates are automatically copied to the new node.

Don't manually overwrite the files located in `/etc/opt/redislabs`. Instead, upload new certificates to a temporary location on one of the cluster nodes, such as the `/tmp` directory.

title: Replica Of database certificates

text: This section describes how to update certificates for Replica Of databases.

title: Update proxy certificates {#update-ap-proxy-certs}

text:
To update the proxy certificate on clusters running Replica Of databases:

1. Use the Cluster Manager UI, `rladmin`, or the REST API to update the proxy certificate on the source database cluster.

1. From the Cluster Manager UI, update the destination database (_replica_) configuration with the [new certificate]().

- Perform step 2 as quickly as possible after performing step 1.  Connections using the previous certificate are rejected after applying the new certificate.  Until both steps are performed, recovery of the database sync cannot be established.

title: Active-Active database certificates

title: Update proxy certificates {#update-aa-proxy-certs}

text:
To update proxy certificate on clusters running Active-Active databases:

1. Use the Cluster Manager UI, `rladmin`, or the REST API to update proxy certificates on a single cluster, multiple clusters, or all participating clusters.

1. Use the [`crdb-cli`]() utility to update Active-Active database configuration from the command line. Run the following command once for each Active-Active database residing on the modified clusters:

    [code example]

- Perform step 2 as quickly as possible after performing step 1.  Connections using the previous certificate are rejected after applying the new certificate.  Until both steps are performed, recovery of the database sync cannot be established.<br/>
- Do not run any other `crdb-cli crdb update` operations between the two steps.

title: Update syncer certificates {#update-aa-syncer-certs}

text:
To update your syncer certificate on clusters running Active-Active databases, follow these steps:

1. Update your syncer certificate on one or more of the participating clusters using the Cluster Manager UI, `rladmin`, or the REST API. You can update a single cluster, multiple clusters, or all participating clusters.

1. Update the Active-Active database configuration from the command line with the [`crdb-cli`]() utility. Run this command once for each Active-Active database that resides on the modified clusters:

    [code example]

- Run step 2 as quickly as possible after step 1. Between the two steps, new syncer connections that use the ‘old’ certificate will get rejected by the cluster that has been updated with the new certificate (in step 1).

- Do not run any other `crdb-cli crdb update` operations between the two steps.

title: Troubleshoot RHEL 8 crypto policy and certificate key size

role: errors

text:
In RHEL 8, if the crypto policy is set to `FUTURE`, the system will not accept certificates with private key sizes smaller than 3072 bits. This affects the use of custom certificates with smaller keys (such as 2048-bit keys).

To use certificates with smaller key sizes, you need to change the crypto policy from `FUTURE` to `DEFAULT`. For more information about crypto policies, see the [Red Hat documentation on system-wide cryptographic policies](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening).

code: rladmin cluster certificate set <cert-name> certificate_file <cert-file-name>.pem key_file <key-file-name>.pem

section_id: how-to-update-certificates

code: rladmin cluster certificate set cm certificate_file cluster.pem key_file key.pem

code:
PUT https://<host>:<port>/v1/cluster/certificates
{
  "certificates": [
    {
      "name": "<cert_name>",
      "certificate": "<cert>",
      "key": "<key>"
    }
  ]
}

code:
PUT https://<host>:<port>/v1/cluster/update_cert
    '{ "name": "<cert_name>", "key": "<key>", "certificate": "<cert>" }'

code: crdb-cli crdb update --crdb-guid <CRDB-GUID> --force


title: Encryption in Redis Software

summary: Encryption in Redis Software.

summary: An overview of Transport Layer Security (TLS).

title: Transport Layer Security (TLS)

summary: Describes internode encryption which improves the security of data in transit.

title: Internode encryption

summary: Enable PEM encryption to encrypt all private keys on disk.

title: Encrypt private keys

title: Overview

text: Redis Software uses encryption to secure communications between clusters, nodes, databases, and clients and to protect [data in transit](https://en.wikipedia.org/wiki/Data_in_transit), [at rest](https://en.wikipedia.org/wiki/Data_at_rest), and [in use](https://en.wikipedia.org/wiki/Data_in_use).

title: Encrypt data in transit

title: TLS

text:
Redis Software uses [Transport Layer Security (TLS)]() to encrypt communications for the following:

- Cluster Manager UI

- Command-line utilities

- REST API

- Internode communication

You can also [enable TLS authentication]() for the following:

- Communication from clients or applications to your database

- Communication from your database to other clusters for replication using [Replica Of]()

- Communication to and from your database to other clusters for [Active-Active]() synchronization

title: Internode encryption

text:
[Internode encryption]() uses TLS to encrypt data in transit between cluster nodes.

By default, internode encryption is enabled for the control plane, which manages the cluster and databases. If you also want to encrypt replication and proxy communications between database shards on different nodes, [enable data internode encryption]().

title: Require HTTPS for REST API endpoints

text: By default, the Redis Software API supports communication over HTTP and HTTPS. However, you can [turn off HTTP support]() to ensure that API requests are encrypted.

title: Encrypt data at rest

title: File system encryption

text: To encrypt data stored on disk, use file system-based encryption capabilities available on Linux operating systems before you install Redis Software.

title: Private key encryption

text: Enable PEM encryption to [encrypt all private keys]() on disk.

title: Encrypt data in use

title: Client-side encryption

text:
Use client-side encryption to encrypt the data an application stores in a Redis database. The application decrypts the data when it retrieves it from the database.

You can add client-side encryption logic to your application or use built-in client functions.

Client-side encryption has the following limitations:

- Operations that must operate on the data, such as increments, comparisons, and searches will not function properly.

- Increases management overhead.

- Reduces performance.


title: Internode encryption

title: Overview

text:
As of v6.2.4, Redis Software supports _internode encryption_, which encrypts internal communication between nodes. This improves the security of data as it travels within a cluster.

Internode encryption is enabled for the _control plane_, which manages the cluster and its databases.

Internode encryption is supported for the _data plane_, which encrypts communication used to replicate shards between nodes and proxy communication with shards located on different nodes.

The following diagram shows how this works.

Data internode encryption is disabled by default for individual databases in order to optimize for performance.  Encryption adds latency and overhead; the impact is measurable and varies according to the database, its field types, and the details of the underlying use case.

You can enable data internode encryption for a database by changing the database configuration settings.  This lets you choose when to favor performance and when to encrypt data.

title: Prerequisites

text:
Internode encryption requires certain prerequisites.

You need to:

- Upgrade all nodes in the cluster to v6.2.4 or later.

- Open port 3342 for the TLS channel used for encrypted communication.

title: Enable data internode encryption

text:
To enable internode encryption for a database (also called _data internode encryption_), you need to enable the appropriate setting for each database you wish to encrypt.  To do so, you can:

- Use the Cluster Manager UI to enable the **Internode Encryption** setting from the database **Security** screen.

-  Use the `rladmin` command-line utility to set the [data_internode_encryption]() setting for the database:

    [code example]

- Use the Redis Software REST API to set the `data_internode_encryption` setting for the database.

    [code example]

When you change the data internode encryption setting for a database, all active remote client connections are disconnected.  This restarts the internal (DMC) proxy and disconnects all client connections.

title: Change cluster policy

text:
To enable internode encryption for new databases by default, use one of the following methods:

- Cluster Manager UI

    1. On the **Databases** screen, select  to open a list of additional actions.

    1. Select **Database defaults**.

    1. Go to **Internode Encryption** and click **Change**.

    1. Select **Enabled** to enable internode encryption for new databases by default.

    1. Click **Change**.

    1. Select **Save**.

- [rladmin tune cluster]():

    [code example]

- [Update cluster policy]() REST API request:

    [code example]

title: Self-signed certificates

text: By default, Redis Software uses self-signed certificates for internode encryption. These certificates are automatically generated, managed, and rotated by the system.

title: Encryption ciphers and settings

text:
To encrypt internode communications, Redis Software uses TLS 1.2 and the following cipher suites:

- ECDHE-RSA-AES256-GCM-SHA384
- ECDHE-RSA-AES128-GCM-SHA256

As of Redis Software v7.4, internode encryption also supports TLS 1.3 with the following cipher suites:

- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384

The TLS layer determines which TLS version to use.

No configurable settings are exposed; internode encryption is used internally within a cluster and not exposed to any outside service.

title: Certificate authority and rotation

text:
Starting with v6.2.4, internode communication is managed, in part, by two certificates: one for the control plane and one for the data plane.  These certificates are signed by a private certificate authority (CA).  The CA is not exposed outside of the cluster, so it cannot be accessed by external processes or services.  In addition, each cluster generates a unique CA that is not used anywhere else.

The private CA is generated when a cluster is created or upgraded to 6.2.4.

When nodes join the cluster, the cluster CA is used to generate certificates for the new node, one for each plane.  Certificates signed by the private CA are not shared between clusters and they're not exposed outside the cluster.

All certificates signed by the internal CA expire after ninety (90) days and automatically rotate every thirty (30) days.  Alerts also monitor certificate expiration and trigger when certificate expiration falls below 45 days.  If you receive such an alert, contact support.

You can use the Redis Software REST API to rotate certificates manually:

[code example]

title: Customer-provided certificates

text: Instead of using Redis Software's self-signed certificates for internode encryption, you can provide certificates generated by your Certificate Authority (CA).

title: Certificate requirements

text:
Customer-provided internode encryption certificates must meet the following requirements:

- Certificates must be in PEM format.

- Certificates must contain the certificate chain and the leaf certificate.

- Certificates must use an RSA key. Using other key types, such as ECDSA or EdDSA, might prevent internode encryption from working.

- Certificates must be created with the TLS Web Client Authentication attribute enabled.

title: Upload customer-provided certificates

text:
You can upload either:

- One certificate for both data plane internode encryption (DPINE) and control plane internode encryption (CPINE).

- Two separate certificates: one for DPINE and one for CPINE.

To upload internode encryption certificates, use one of the following methods:

**Cluster Manager UI:**

1. In the Cluster Manager UI, go to **Cluster > Security > Certificates**.

1. Expand the **Internode encryption certificates** section.

1. Click **Replace certificates**.

1. In the **Internode encryption certificates** panel, select one of the following options:

    - Use the same certificate for data and control plane internode encryption

    - Use separate certificates for data and control plane internode encryption

1. For each certificate and key, click **Upload** and use the file browser to select the relevant PEM file.

1. Click **Save & Rotate**.

**rladmin:**

To use the same certificate for data and control plane internode encryption, run the following [`rladmin cluster certificate`]() command:

[code example]

To use separate certificates for data and control plane internode encryption, run the following [`rladmin cluster certificate`]() command:

[code example]

**REST API:**

To use the same certificate for data and control plane internode encryption, send a [`PUT /v1/cluster/certificates`]() request:

[code example]

To use separate certificates for data and control plane internode encryption, send a [`PUT /v1/cluster/certificates`]() request:

[code example]

title: Certificate expiration and rotation

text:
Customer-provided internode encryption certificates are not rotated automatically. To prevent possible issues with cluster and database unavailability caused by expired internode encryption certificates:

- You should monitor the certificates' expiration dates and [renew them]() before they expire.

- In case you do not renew the customer-managed certificates before they expire, Redis Software automatically replaces them with self-signed certificates 5 days before expiration. You can upload new customer-provided certificates to replace these certificates anytime.

title: Performance recommendations

role: performance

text: For optimal performance with customer-provided certificates, follow the same recommendations as for self-signed certificates detailed in the [Encryption ciphers and settings](#encryption-ciphers-and-settings) section.

code: rladmin tune db <database_id> data_internode_encryption enabled

section_id: enable-data-internode-encryption

code:
put /v1/bdbs/${database_id}
    { "data_internode_encryption" : true }

code: rladmin tune cluster data_internode_encryption enabled

section_id: change-cluster-policy

code:
PUT /v1/cluster/policy
    { "data_internode_encryption": true }

code: POST /v1/cluster/certificates/rotate

section_id: certificate-authority-and-rotation

code: rladmin cluster certificate set internal dpine_certificate_file <path-to-shared-cert> dpine_key_file <path-to-shared-key> cpine_certificate_file <path-to-shared-cert> cpine_key_file <path-to-shared-key>

section_id: upload-customer-provided-certificates

code: rladmin cluster certificate set internal dpine_certificate_file <path-to-dpine-cert> dpine_key_file <path-to-dpine-key> cpine_certificate_file <path-to-cpine-cert> cpine_key_file <path-to-cpine-key>

code:
PUT https://<host>:<port>/v1/cluster/certificates
{
  "certificates": [
    {
      "name": "ccs_internode_encryption",
      "key": "<shared-private-key>",
      "certificate": "<shared-certificate-chain>"
    },
    {
      "name": "data_internode_encryption",
      "key": "<shared-private-key>",
      "certificate": "<shared-certificate-chain>"
    }
  ]
}

code:
PUT https://<host>:<port>/v1/cluster/certificates
{
  "certificates": [
    {
      "name": "ccs_internode_encryption",
      "key": "<cpine-private-key>",
      "certificate": "<cpine-certificate-chain>"
    },
    {
      "name": "data_internode_encryption",
      "key": "<dpine-private-key>",
      "certificate": "<dpine-certificate-chain>"
    }
  ]
}


title: Encrypt private keys

title: Overview

text:
Enable PEM encryption to automatically encrypt all private keys on disk. Public keys (`.cert` files) are not encrypted.

When certificates are rotated, the encrypted private keys are also rotated.

title: Enable PEM encryption

text:
To enable PEM encryption and encrypt private keys on the disk, use [`rladmin`]() or the [REST API]().

- [`rladmin cluster config`]():

    [code example]

- [Update cluster settings]() REST API request:

    [code example]

title: Deactivate PEM encryption

text:
To deactivate PEM encryption and decrypt private keys on the disk, use [`rladmin`]() or the [REST API]().

- [`rladmin cluster config`]():

    [code example]

- [Update cluster settings]() REST API request:

    [code example]

code: rladmin cluster config encrypt_pkeys enabled

section_id: enable-pem-encryption

code:
PUT /v1/cluster
    { "encrypt_pkeys": true }

code: rladmin cluster config encrypt_pkeys disabled

section_id: deactivate-pem-encryption

code:
PUT /v1/cluster
    { "encrypt_pkeys": false }


title: Configure cipher suites

summary: Shows how to configure cipher suites.

title: Overview

text: Ciphers are algorithms that help secure connections between clients and servers. You can change the ciphers to improve the security of your Redis Software cluster and databases. The default settings are in line with industry best practices, but you can customize them to match the security policy of your organization.

title: TLS 1.2 cipher suites

text:
| Name | Configurable | Description |
|------------|--------------|-------------|
| control_cipher_suites | ✅ Yes | Cipher list for TLS 1.2 communications for cluster administration (control plane) |
| data_cipher_list | ✅ Yes | Cipher list for TLS 1.2 communications between applications and databases (data plane) |
| sentinel_cipher_suites | ✅ Yes | Cipher list for [discovery service]() (Sentinel) TLS 1.2 communications |

title: TLS 1.3 cipher suites

text:
| Name | Configurable | Description |
|------------|--------------|-------------|
| control_cipher_suites_tls_1_3 | ❌ No | Cipher list for TLS 1.3 communications for cluster administration (control plane) |
| data_cipher_suites_tls_1_3 | ✅ Yes | Cipher list for TLS 1.3 communications between applications and databases (data plane) |
| sentinel_cipher_suites_tls_1_3 | ❌ No | Cipher list for [discovery service]() (Sentinel) TLS 1.3 communications |

title: Configure cipher suites

role: configuration

text:
You can configure ciphers with the [Cluster Manager UI](#edit-ciphers-ui), [`rladmin`](), or the [REST API]().

Configuring cipher suites overwrites existing ciphers rather than appending new ciphers to the list.

When you modify your cipher suites, make sure:

- The configured TLS version matches the required cipher suites.
- The certificates in use are properly signed to support the required cipher suites.

- Redis Software doesn't support static [Diffie–Hellman (`DH`) key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) ciphers.

- Support for Ephemeral Diffie–Hellman (ECDHE) key exchange ciphers depends on the operating system version and security policy.

title: Edit cipher suites in the UI {#edit-ciphers-ui}

text:
To configure cipher suites using the Cluster Manager UI:

1. Go to **Cluster > Security**, then select the **TLS** tab.

1. In the **Cipher suites lists** section, click **Configure**:

1. Edit the TLS cipher suites in the text boxes:

1. Click **Save**.

title: Control plane cipher suites {#control-plane-ciphers-tls-1-2}

text:
As of Redis Software version 6.0.12, control plane cipher suites can use the BoringSSL library format for TLS connections to the Cluster Manager UI. See the BoringSSL documentation for a full list of available [BoringSSL configurations](https://github.com/google/boringssl/blob/master/ssl/test/runner/cipher_suites.go#L99-L131).

#### Configure TLS 1.2 control plane cipher suites

To configure TLS 1.2 cipher suites for cluster communication, use the following [`rladmin`]() command syntax:

[code example]

See the example below to configure cipher suites for the control plane:

[code example]

- The deprecated 3DES and RC4 cipher suites are no longer supported.

title: Data plane cipher suites {#data-plane-ciphers-tls-1-2}

text:
Data plane cipher suites use the OpenSSL library format in Redis Software version 6.0.20 or later. For a list of available OpenSSL configurations, see [Ciphers](https://www.openssl.org/docs/man1.1.1/man1/ciphers.html) (OpenSSL).

#### Configure TLS 1.2 data plane cipher suites

To configure TLS 1.2 cipher suites for communications between applications and databases, use the following [`rladmin`]() command syntax:

[code example]

See the example below to configure cipher suites for the data plane:

[code example]

- The deprecated 3DES and RC4 cipher suites are no longer supported.

#### Configure TLS 1.3 data plane cipher suites

To configure TLS 1.3 cipher suites for communications between applications and databases, use the following [`rladmin`]() command syntax:

[code example]

The following example configures TLS 1.3 cipher suites for the data plane:

[code example]

title: Discovery service cipher suites {#discovery-service-ciphers-tls-1-2}

text:
Sentinel service cipher suites use the golang.org OpenSSL format for [discovery service]() TLS connections in Redis Software version 6.0.20 or later. See their documentation for a list of [available configurations](https://golang.org/src/crypto/tls/cipher_suites.go).

#### Configure TLS 1.2 discovery service cipher suites

To configure TLS 1.2 cipher suites for the discovery service cipher suites, use the following [`rladmin`]() command syntax:

[code example]

See the example below to configure cipher suites for the sentinel service:

[code example]

code: rladmin cluster config control_cipher_suites <BoringSSL cipher list>

code: rladmin cluster config  data_cipher_list <OpenSSL cipher list>

code: rladmin cluster config data_cipher_list AES128-SHA:AES256-SHA

code: rladmin cluster config data_cipher_suites_tls_1_3 <OpenSSL cipher list>

code: rladmin cluster config data_cipher_suites_tls_1_3 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

code: rladmin cluster config  sentinel_cipher_suites <golang cipher list>

code: rladmin cluster config sentinel_cipher_suites TLS_RSA_WITH_AES_128_CBC_SHA:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384


title: Enable TLS

summary: Shows how to enable TLS.

title: Overview

text:
You can use TLS authentication for one or more of the following types of communication:

- Communication from clients (applications) to your database
- Communication from your database to other clusters for replication using [Replica Of]()
- Communication to and from your database to other clusters for synchronization using [Active-Active]()

When you enable or turn off TLS, the change applies to new connections but does not affect existing connections. You must update TLS parameters in the client's connection configuration, then clients must close existing connections and reconnect to apply the change.

title: Enable TLS for client connections {#client}

text:
To enable TLS for client connections:

1. From your database's **Security** tab, select **Edit**.

1. Expand the **TLS - Transport Layer Security for secure connections** section, then select **On**.

1. In the **Apply TLS for** section, select **Clients and databases + Between databases**.

1. Select **Save**.

title: Enable mutual TLS

text:
Optionally, you can enable mutual TLS for client connections:

1. Select **Mutual TLS (Client authentication)**.

1. For each client certificate, select **+ Add certificate**, paste or upload the client certificate, then select **Done**.

    If your database uses Replica Of, you also need to add the syncer certificates for the participating clusters. See [Enable TLS for Replica Of cluster connections](#enable-tls-for-replica-of-cluster-connections) for instructions.

1. You can configure **Additional certificate validations** to further limit connections to clients with valid certificates.

    Additional certificate validations occur only when loading a [certificate chain](https://en.wikipedia.org/wiki/Chain_of_trust#Computer_security) that includes the [root certificate](https://en.wikipedia.org/wiki/Root_certificate) and intermediate [CA](https://en.wikipedia.org/wiki/Certificate_authority) certificate but does not include a leaf (end-entity) certificate. If you include a leaf certificate, mutual client authentication skips any additional certificate validations.

    1. Select a certificate validation option.

        | Validation option | Description |
        |-------------------|-------------|
        | _No validation_ | Authenticates clients with valid certificates. No additional validations are enforced. |
        | _By Subject Alternative Name_ | A client certificate is valid only if its Subject Alternative Name (SAN) DNS entries or Common Name (CN) match an entry in the list of valid subjects. Ignores other [`Subject`](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) attributes. |
        | _By full Subject Name_ | A client certificate is valid only if its [`Subject`](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) attributes match an entry in the list of valid subjects. |

    1. If you selected **No validation**, you can skip this step. Otherwise, select **+ Add validation** to create a new entry and then enter valid [`Subject`](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) attributes for your client certificates. All `Subject` attributes are case-sensitive.

        | Subject attribute<br />(case-sensitive) | Description |
        |-------------------|-------------|
        | _Common Name (CN)_ | Name of the client authenticated by the certificate (_required_) |
        | _Organization (O)_ | The client's organization or company name |
        | <nobr>_Organizational Unit (OU)_</nobr> | Name of the unit or department within the organization |
        | _Locality (L)_ | The organization's city |
        | _State / Province (ST)_ | The organization's state or province |
        | _Country (C)_ | 2-letter code that represents the organization's country |

        You can only enter a single value for each field, except for the _Organizational Unit (OU)_ field. If your client certificate has a `Subject` with multiple  _Organizational Unit (OU)_ values, press the `Enter` or `Return` key after entering each value to add multiple Organizational Units.

        **Breaking change:** If you use the [REST API]() instead of the Cluster Manager UI to configure additional certificate validations, note that `authorized_names` is deprecated as of Redis Software v6.4.2. Use `authorized_subjects` instead. See the [BDB object reference]() for more details.

1. Select **Save**.

title: Validate client certificate expiration

text:
By default, Redis Software validates client certificate expiration dates.  You can use [`rladmin tune db`]() to turn off this behavior.

[code example]

title: Connect over TLS

text:
To connect to a Redis Software database over TLS using [`redis-cli`]():

1. Download or copy the server (or proxy) certificate from the Cluster Manager UI (**Cluster > Security > Certificates > Server authentication**) or from a cluster node (`/etc/opt/redislabs/proxy_cert.pem`).

1. Copy the certificate to each client machine.

1. If your database doesn't require client authentication with mutual TLS, provide the server certificate when you connect:

    [code example]

1. If your database requires client authentication with mutual TLS, provide your client's private and public keys along with the Redis Software server certificate when you connect:

    [code example]

title: Enable TLS for Active-Active cluster connections

text:
You can enable TLS for Active-Active cluster connections when you create a database using the Cluster Manager UI, [`crdb-cli`](), or the [REST API]().

If you need to enable or turn off TLS after the Active-Active database is created, you must use [`crdb-cli`]() or the [REST API]().

title: Enable TLS during database creation

text:
To enable TLS for Active-Active cluster connections using the Cluster Manager UI:

1. During [database creation](), expand the **TLS** configuration section.

1. Select **On** to enable TLS.

1. Click **Create**.

If you also want to require TLS for client connections during creation, you can use the [create an Active-Active database]() REST API request to create an Active-Active database with TLS enabled for client connections.
You should configure the client certificates individually for each instance instead of using the default database configuration, even if the same certificate is used across all instances.
This allows you to rotate the certificates independently for each instance and to avoid outages in case of certificate expiration.

[code example]

title: Enable TLS after database creation

text:
You can enable TLS for an existing Active-Active database using either `crdb-cli` or the REST API.

**CLI:**

Run the following [`crdb-cli crdb update`]() command:

[code example]

Replace `<guid>` with your Active-Active database's globally unique identifier.

**REST API:**

You can use an [update database configuration]() request to enable TLS.

To enable TLS for Active-Active database communications only:

[code example]

To enable TLS for all communications:

[code example]

code: rladmin tune db < db:id | name > mtls_allow_outdated_certs { enabled | disabled }

section_id: validate-client-certificate-expiration

section_id: connect-over-tls

code:
redis-cli -h <endpoint> -p <port> --tls --cacert proxy_cert.pem \
        --cert redis_user.crt --key redis_user_private.key

code:
POST https://<host>:9443/v1/crdb
{
  "name": "crdb-mtls",
  "default_db_config": {
    "name": "crdb-mtls",
    "bigstore": false,
    "memory_size": 4294967296
  },
  "encryption": true,
  "instances": [
    {
      "cluster": {
        "name": "<cluster1_host>",
        "url": "https://<cluster1_host>:9443",
        "credentials": {
          "username": "<username>",
          "password": "<password>"
        }
      },
      "db_config": {
        "tls_mode": "enabled",
        "enforce_client_authentication": "enabled",
        "authentication_ssl_client_certs": [
          {
            "client_cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
          }
        ]
      }
    },
    {
      "cluster": {
        "name": "<cluster2_host>",
        "url": "https://<cluster2_host>:9443",
        "credentials": {
          "username": "<username>",
          "password": "<password>"
        }
      },
      "db_config": {
        "tls_mode": "enabled",
        "enforce_client_authentication": "enabled",
        "authentication_ssl_client_certs": [
          {
            "client_cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
          }
        ]
      }
    }
  ],
  "causal_consistency": false
}

section_id: enable-tls-during-database-creation

code: crdb-cli crdb update --crdb-guid <guid> --encryption true

section_id: enable-tls-after-database-creation

code:
PUT https://<host>:9443/v1/bdbs/<database-id>
{
  "enforce_client_authentication": "disabled",
  "tls_mode": "replica_ssl"
}

code:
PUT https://<host>:9443/v1/bdbs/<database-id>
{
  "enforce_client_authentication": "disabled",
  "tls_mode": "enabled"
}


title: Transport Layer Security (TLS)

summary: Shows how to enable TLS.

title: Enable TLS

title: Configure TLS protocol

summary: Shows how to configure cipher suites.

title: Configure cipher suites

title: Overview

text:
[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security), a successor to SSL, ensures the privacy of data sent between applications and Redis databases. TLS also secures connections between Redis Software nodes.

You can [use TLS authentication]() for the following types of communication:

- Communication from clients (applications) to your database
- Communication from your database to other clusters for replication using [Replica Of]()
- Communication to and from your database to other clusters for synchronization using [Active-Active]()

title: Protocols and ciphers

text:
TLS protocols and ciphers define the overall suite of algorithms that clients are able to connect to the servers with.

You can change the [TLS protocols]() and [ciphers]() to improve the security of your Redis Software cluster and databases. The default settings are in line with industry best practices, but you can customize them to match the security policy of your organization.

title: Troubleshooting

text:
For help troubleshooting TLS failures, see the following knowledge base guides:

- [Troubleshooting TLS Failures](https://support.redislabs.com/hc/en-us/articles/26867190871314-Troubleshooting-TLS-Failures)

- [Troubleshooting TLS Connection Failures Caused by Certificate Expiration](https://support.redislabs.com/hc/en-us/articles/27021922067090-Troubleshooting-TLS-Connection-Failures-Caused-by-Certificate-Expiration)


title: Configure TLS protocol

title: Overview

text: You can change TLS protocols to improve the security of your Redis Software cluster and databases. The default settings are in line with industry best practices, but you can customize them to match the security policy of your organization.

title: Configure TLS protocol

text:
The communications for which you can modify TLS protocols are:

- Control plane - The TLS configuration for cluster administration.
- Data plane - The TLS configuration for the communication between applications and databases.
- Discovery service (Sentinel) - The TLS configuration for the [discovery service]().

You can configure TLS protocols with the [Cluster Manager UI](#edit-tls-ui), [`rladmin`](), or the [REST API]().

- After you set the minimum TLS version, Redis Software does not accept communications with TLS versions older than the specified version.

- If you set TLS 1.3 as the minimum TLS version, clients must support TLS 1.3 to connect to Redis Software.

TLS support depends on the operating system. You cannot enable support for protocols or versions that aren't supported by the operating system running Redis Software.  In addition, updates to the operating system or to Redis Software can impact protocol and version support.

If you have trouble enabling specific versions of TLS, verify that they're supported by your operating system and that they're configured correctly.

TLSv1.2 is generally recommended as the minimum TLS version for encrypted communications. Check with your security team to confirm which TLS protocols meet your organization's policies.

title: Edit TLS settings in the UI {#edit-tls-ui}

text:
To configure minimum TLS versions using the Cluster Manager UI:

1. Go to **Cluster > Security**, then select the **TLS** tab.

1. Click **Edit**.

1. Select the minimum TLS version for cluster connections, database connections, and the discovery service:

    {{<image filename="images/rs/screenshots/cluster/security-tls-protocols-edit.png" alt="Cluster > Security > TLS settings in edit mode in the Cluster Manager UI." >}}

1. Select the TLS mode for the discovery service:

    - **Allowed** - Allows both TLS and non-TLS connections
    - **Required** - Allows only TLS connections
    - **Disabled** - Allows only non-TLS connections

1. Click **Save**.

title: Control plane TLS

text:
To set the minimum TLS protocol for the control plane using `rladmin`:

- Default minimum TLS protocol: TLSv1.2
- Syntax: `rladmin cluster config min_control_TLS_version <TLS_Version>`
- TLS versions available:
  - For TLSv1.2 - 1.2
  - For TLSv1.3 - 1.3

For example:

[code example]

title: Data plane TLS

text:
To set the minimum TLS protocol for the data path using `rladmin`:

- Default minimum TLS protocol: TLSv1.2
- Syntax: `rladmin cluster config min_data_TLS_version <TLS_Version>`
- TLS versions available:
  - For TLSv1.2 - 1.2
  - For TLSv1.3 - 1.3

For example:

[code example]

title: Discovery service TLS

text:
To enable TLS for the discovery service using `rladmin`:

- Default: Allows both TLS and non-TLS connections
- Syntax: `rladmin cluster config sentinel_tls_mode <ssl_policy>`
- `ssl_policy` values available:
  - `allowed` - Allows both TLS and non-TLS connections
  - `required` - Allows only TLS connections
  - `disabled` - Allows only non-TLS connections

To set the minimum TLS protocol for the discovery service using `rladmin`:

- Default minimum TLS protocol: TLSv1.2
- Syntax: `rladmin cluster config min_sentinel_TLS_version <TLS_Version>`
- TLS versions available:
  - For TLSv1.2 - 1.2
  - For TLSv1.3 - 1.3

To enforce a minimum TLS version for the discovery service, run the following commands:

1. Allow only TLS connections:

    [code example]

1. Set the minimal TLS version:

    [code example]

1. Restart the discovery service on all cluster nodes to apply your changes:

    [code example]

code: rladmin cluster config min_control_TLS_version 1.2

section_id: control-plane-tls

code: rladmin cluster config min_data_TLS_version 1.2

section_id: data-plane-tls

code: rladmin cluster config sentinel_tls_mode required

section_id: discovery-service-tls

code: rladmin cluster config min_sentinel_TLS_version 1.2

code: supervisorctl restart sentinel_service


title: Security

title: Recommended security practices

summary: An overview of access control in Redis Software.

title: Access control

title: Audit connection events

title: Certificates

summary: Encryption in Redis Software.

title: Encryption in Redis Software

title: Overview

text:
Redis Software provides various features to secure your deployment:

| Login and passwords | Users and roles | Encryption and TLS | Certificates and audit |
|---------------------|-----------------|--------------------|-----------------------|
| [Password attempts and session timeout]() | [Cluster and database access explained]() | [Enable TLS]() | [Create certificates]() |
| [Password complexity]() | [Create users]() | [Configure TLS protocols]() | [Monitor certificates]() |
| [Password expiration]() | [Create roles]() | [Configure cipher suites]() | [Update certificates]() |
| [Default database access]() | [Redis ACLs]() | [Encrypt private keys on disk]() | [Enable OCSP stapling]() |
| [Rotate user passwords]() | [Integrate with LDAP]() | [Internode encryption]() | [Audit database connections]() |
| [Single sign-on (SSO)]() | | | |

title: Recommended security practices

text: See [Recommended security practices]() to learn how to protect Redis Software.

title: Redis Trust Center

text: Visit our [Trust Center](https://trust.redis.io/) to learn more about Redis security policies. If you find a suspected security bug, you can [submit a report](https://hackerone.com/redis-vdp?type=team).


title: Recommended security practices

title: Deployment security

text:
When deploying Redis Software to production, we recommend the following practices:

- **Deploy Redis Software inside a trusted network**:  Redis Software is database software and should be deployed on a trusted network not accessible to the public internet. Deploying Redis Software in a trusted network reduces the likelihood that someone can obtain unauthorized access to your data or the ability to manage your database configuration.

- **Implement anti-virus exclusions**: To ensure that anti-virus solutions that scan files or intercept processes to protect memory do not interfere with Redis Software, you should ensure that anti-virus exclusions are implemented across all nodes in their Redis Software cluster in a consistent policy. This helps ensure that anti-virus software does not impact the availability of your Redis Software cluster.

    If you are replacing your existing antivirus solution or installing/supporting Redis Software, make sure that the below paths are excluded:

For antivirus solutions that intercept processes, binary files may have to be excluded directly depending on the requirements of your anti-virus vendor.

    | **Path** | **Description** |
    |------------|-----------------|
    | /opt/redislabs | Main installation directory for all Redis Software binaries |
    | /opt/redislabs/bin | Binaries for all the utilities for command line access and managements such as "rladmin" or "redis-cli" |
    | /opt/redislabs/config | System configuration files |
    | /opt/redislabs/lib | System library files |
    | /opt/redislabs/sbin | System binaries for tweaking provisioning |

- **Send logs to a remote logging server**: Redis Software is configured to send logs by default to syslog. To send these logs to a remote logging server, you must [configure syslog]() based on the requirements of the remote logging server vendor. Remote logging helps ensure that the logs are not deleted so that you can rotate the logs to prevent your server disk from filling up.

- **Deploy clusters with an odd number of 3 or more nodes**: Redis is an available and partition-tolerant database. We recommend that Redis Software be deployed in a cluster of an odd number of 3 or more nodes so that you are able to successfully failover in the event of a failure.

- **Reboot nodes in a sequence rather than all at once**: It is best practice to frequently maintain reboot schedules. If you reboot too many servers at once, it is possible to cause a quorum failure that results in loss of availability of the database. We recommend that rebooting be done in a phased manner so that quorum is not lost. For example, to maintain quorum in a 3 node cluster, at least 2 nodes must be up at all times. Only one server should be rebooted at any given time to maintain quorum.

- **Implement client-side encryption**: Client-side encryption, or the practice of encrypting data within an application before storing it in a database, such as Redis, is the most widely adopted method to achieve encryption in memory. Redis is an in-memory database and stores data in-memory. If you require encryption in memory, better known as encryption in use, then client side encryption may be the right solution for you. Please be aware that database functions that need to operate on data — such as simple searching functions, comparisons, and incremental operations — don’t work with client-side encryption.

title: Cluster security

text:
- **Control the level of access to your system**: Redis Software lets you decide which users can access the cluster, which users can access databases, and which users can access both. We recommend preventing database users from accessing the cluster. See [Access control]() for more information.

- **Enable LDAP authentication**: If your organization uses the Lightweight Directory Access Protocol (LDAP), we recommend enabling Redis Software support for role-based LDAP authentication.

- **Require HTTPS for API endpoints**: Redis Software comes with a REST API to help automate tasks. This API is available in both an encrypted and unencrypted endpoint for backward compatibility. You can [disable the unencrypted endpoint]() with no loss in functionality.

title: Database security

text:
Redis Software offers several database security controls to help protect your data against unauthorized access and to improve the operational security of your database. The following section details configurable security controls available for implementation.

- **Use strong Redis passwords**: A frequent recommendation in the security industry is to use strong passwords to authenticate users. This helps to prevent brute force password guessing attacks against your database. Its important to check that your password aligns with your organizations security policy.

- **Deactivate default user access**: Redis Software comes with a "default" user for backwards compatibility with applications designed with versions of Redis prior to Redis Software 6. The default user is turned on by default. This allows you to access the database without specifying a username and only using a shared secret. For applications designed to use access control lists, we recommend that you [deactivate default user access]().

- **Configure Transport Layer Security (TLS)**: Similar to the control plane, you can also [configure TLS protocols]() to help support your security and compliance needs.

- **Enable client certificate authentication**: To prevent unauthorized access to your data, Redis Software databases support the [TLS protocol](), which includes authentication and encryption. Client certificate authentication can be used to ensure only authorized hosts can access the database.

- **Install trusted certificates**: Redis implements self-signed certificates for the database proxy and replication service, but many organizations prefer to [use their own certificates]().

- **Configure and verify database backups**: Implementing a disaster recovery strategy is an important part of data security. Redis Software supports [database backups to many destinations]().


title: Troubleshooting Redis Software

summary: Resources for troubleshooting Redis Software

title: General troubleshooting

text:
For general troubleshooting, see:

- [Create a support package]() to gather information about the cluster, nodes, and databases to help debug issues

- [Logging]()

- [`rladmin status`]() command, which displays the current status of nodes, databases, database endpoints, and shards on the cluster

- [`rlcheck`]()  utility, which runs various tests to check node health and reports any discovered issues

- [Troubleshooting pocket guide]()

title: Troubleshooting by topic

text:
For troubleshooting specific issues, see:

- [Database connectivity troubleshooting]()

- [Latency troubleshooting]()

- [Replica Of repeatedly fails]()

- CRDT [INFO]() for troubleshooting Active-Active databases

title: Knowledge base

text:
The [Redis Software knowledge base](https://support.redislabs.com/hc/en-us/categories/26174244088594-Redis-Software) provides additional guides and troubleshooting resources.

- [Uploading Support Packages & Cluster Health Analysis](https://support.redislabs.com/hc/en-us/articles/26502436628370-Uploading-Support-Packages-Cluster-Health-Analysis)

- [Tools for Identifying Failures in Clusters](https://support.redislabs.com/hc/en-us/articles/26759137301394-Tools-for-Identifying-Failures-in-Clusters)

- [Troubleshooting TLS Failures](https://support.redislabs.com/hc/en-us/articles/26867190871314-Troubleshooting-TLS-Failures)

- [Troubleshooting TLS Connection Failures Caused by Certificate Expiration](https://support.redislabs.com/hc/en-us/articles/27021922067090-Troubleshooting-TLS-Connection-Failures-Caused-by-Certificate-Expiration)

- [Diagnosing and Resolving Endpoint Flapping in Redis Software](https://support.redislabs.com/hc/en-us/articles/27001052658706-Diagnosing-and-Resolving-Endpoint-Flapping-in-Redis-Software)

- See [Troubleshooting Redis Software](https://support.redislabs.com/hc/en-us/sections/26758971861778-Troubleshooting-Redis-Software) for more troubleshooting guides.

title: Contact support

text: If initial troubleshooting doesn't resolve the issue, you can [contact support](https://redis.io/support/) for additional help.