Installation and Setup
In this installation and setup guide we walk you through the process of planning your deployment, installing RS, setting up a multi-node cluster, and creating your database—soup to nuts. So, grab a cup of coffee and let’s get started.
Planning your RS deployment
To install Redis Enterprise Software (RS) on each node in the cluster, you must first:
Set up your hardware according to the hardware requirements.What hardware do I need?
The hardware requirements for Redis Enterprise Software (RS) are different for development and production environments.
In a development environment you can test your application with a live RS database.
If you want to test your application under production conditions, use the production environment requirements.
In a production environment you must have enough resources to handle the load on the database and recover from failures.
You can build your development environment with non-production hardware, such as a laptop, desktop, or small VM or instance, and with these hardware requirements:
Item Description Minimum Requirements Recommended Nodes per cluster You can install on one node but many features require at least two nodes. 1 node >= 2 nodes RAM per node The amount of RAM for each node. 4GB >= 8GB Storage per node The amount of storage space for each node. 10GB >= 20GB
We recommend these hardware requirements for production systems or for development systems that are designed to demonstrate production use cases:
Item Description Minimum Requirements Recommended Nodes per cluster At least 3 nodes are required to support a reliable, highly available deployment that handles process failure, node failure, and network split events in a consistent manner. 3 nodes >= 3 nodes (Must be an odd number of nodes) Cores* per node RS is based on a multi-tenant architecture and can run multiple Redis processes (or shards) on the same core without significant performance degradation. 4 cores >=8 cores RAM* per node Defining your RAM size must be part of the capacity planning for your Redis usage. 15GB >=30GB Ephemeral Storage Used for storing replication files (RDB format) and cluster log files. RAM x 2 >= RAM x 4 Persistent Storage Used for storing snapshot (RDB format) and AOF files over a persistent storage media, such as AWS Elastic Block Storage (EBS) or Azure Data Disk. RAM x 3 In-memory >= RAM x 6 (except for extreme ‘write’ scenarios); Redis on Flash >= (RAM + Flash) x 5. Network We recommend using multiple NICs per node where each NIC is >100Kbps, but RS can also run over a single 1Gbps interface network used for processing application requests, inter-cluster communication, and storage access. 1G >=10G
- When the CPU load reaches a certain level, RS tries to migrate “noisy” shards to a different node in the cluster and sends an alert to the operator.
- If your application is designed to put a lot of load on your Redis database, make sure that you have at least one available core for each shard of your database.
- If some of the cluster nodes are utilizing more than 80% of the CPU, consider migrating busy resources to less busy nodes.
- If all the cluster nodes are utilizing over 80% of the CPU, consider scaling out the cluster by adding a node.
- Since Redis uses a relatively large amount of buffers (such as for slave communication, client communication, and pub/sub commands) make sure that at least 30% of the RAM is “unused” on each node.
- If some of the cluster nodes are utilizing more than 65% of the RAM, you should look at migrating busy resources to less busy nodes.
- If all the cluster nodes are utilizing over 70% of the RAM, you should look to scale out the cluster by adding a node.
- Do not run other memory-consuming systems on the RS node.
Choose the platform that you want to deploy on.What platforms are supported?
Redis Enterprise Software (RS) is supported on several operating systems, cloud environments, and virtual environments.Note -
Make sure your system meets these requirements:
- Only 64-bit operating systems are supported.
- You must install Redis Enterprise Software directly on the host, not through system cloning.
- You must install on a clean host with no other applications running so that all RAM is allocated to the OS and RS only.
- Linux distributions must be installed with at least “Minimal Install” configuration.
Platform Versions/Information Ubuntu 14.04 (Support ends on November 30, 2020)
Server version is recommended for production installations. Desktop version is only recommended for development deployments.
RHEL/CentOS 6 6.7, 6.8, 6.9 (Support ends on November 30, 2020) RHEL/CentOS 7 7.0, 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7, 7.8
Requires OpenSSL 1.0.2 and firewall configuration
Oracle Linux 6 Based on the corresponding RHEL version Oracle Linux 7 Based on the corresponding RHEL version Amazon Linux Version 1 Docker Docker images of Redis Enterprise Software are certified for Development and Testing only. Kubernetes, Pivotal Platform (PCF) and other orchestration and cloud environments See the Platform documentation
Redis Enterprise is compatible with VMware, but make sure that you:
- Configure your memory, CPU, network, and storage settings to allow for optimal Redis Enterprise performance.
- Pin each Redis Enterprise shard to a specific ESX/ESXi host by setting the appropriate affinity rules.
- If you must manually migrate a virtual machine to another host, follow the best practices for shard maintenance and contact support if you have questions.
- Disable VMware VMotion because Redis Enterprise is not compatible with VMotion.
- Don’t use VMware snapshots because Redis Enterprise cluster manages state dynamically, so a snapshot might not have the correct node and cluster state.
In addition to Linux operating systems (Ubuntu, RHEL/CentOS, Oracle Linux), you can also deploy RS with:
Open network ports in the firewall to allow connections to the nodes.What network ports does RS use?
To make sure that Redis Enterprise Software (RS) servers can pass necessary communications between them, we recommend that all RS servers have all of the ports listed here open between them.
By default, the cluster assigns ports in the range of 10,000 - 19,999 to database endpoints. If you assign a specific port for a database when you create it, even outside of this range, the cluster only verifies that the assigned port is not already in use. You must manually update your firewall with the port for that new database endpoint.
Ports and port ranges used by Redis Enterprise Software
Protocol Port Connection Source Description ICMP * Internal For connectivity checking between nodes TCP 1968 Internal Proxy traffic TCP 3333, 3334, 3335, 3336, 3337, 3338, 3339, 36379, 36380 Internal Cluster traffic TCP 8001 Internal, External Traffic from application to RS Discovery Service TCP 8002, 8004 Internal System health monitoring TCP 8443 Internal, External Secure (HTTPS) access to the management web UI TCP 8444, 9080 Internal For nginx <-> cnm_http/cm traffic TCP 9081 Internal, Active-Active For Active-Active management TCP 8070, 8071 Internal, External For metrics exported and managed by nginx TCP 9443 (Recommended), 8080 Internal, External, Active-Active REST API traffic, including cluster management and node bootstrap TCP 10000-19999 Internal, External, Active-Active Database traffic TCP 20000-29999 Internal Database shard traffic UDP 53, 5353 Internal, External DNS/mDNS traffic
Connection sources are:
- Internal - The traffic is from other cluster nodes
- External - The traffic is from client applications or external monitoring resources
- Active-Active - The traffic is from clusters that host Active-Active databases
Changing the management web UI port
If for any reason you want to use a custom port for the RS Web UI instead of the default port (8443), you can change the port. Before you change the RS Web UI port, make sure that the new port is not in use by another process.Note -
After you change the RS Web UI port, when you add a new node to the cluster you must connect to the web UI with the custom port number:
To change the default port for the RS Web UI, on any node in the cluster run:
rladmin cluster config cm_port <new-port>
Disabling HTTP support for API endpoints
To harden deployments, you can disable the HTTP support for API endpoints that is supported by default. Before you disable HTTP support, make sure that you migrate any scripts or proxy configurations that use HTTP to the encrypted API endpoint to prevent broken connections. After you disable HTTP support, traffic sent to the unencrypted API endpoint is blocked.
To disable HTTP support for API endpoints, run:
rladmin cluster config http_support disabled
Configure cluster DNS so that cluster nodes can reach each other by DNS names.How do I configure DNS for my cluster?
DNS is critical to the default operation of Redis Enterprise Software (RS) deployments. This can be altered, but instead using the Discovery Service, which utilizes pure IP-based connectivity as it is compliant with the Redis Sentinel API.
As part of the high availability capabilities in RS, each node includes a small DNS server for managing various internal cluster functionalities, such as automatic failover or automatic migration. Therefore, the node on which you are provisioning RS should not run any other DNS server except for the one included with the RS installation. The existence of another DNS server on the same machine can cause unexpected behavior in RS.
Cluster name (FQDN) and connection management
When connecting to the cluster for administration or connecting to databases for data access, there are 2 options:
- URL-based Connections - URL-based connections require DNS setup for resolution of the cluster name (FQDN) when connecting to the cluster for administration or connecting to databases for data access. As the topology of the cluster changes and new nodes are added or existing nodes are removed from the cluster, DNS records may need to be modified. However, with URL-based connections, applications simply have to remember the URL for the cluster or the database.
- IP-based Connections - IP-based connections do not require DNS setup and instead use IP addresses of the nodes in the cluster for connecting to the cluster for administration or data access. As the topology of the cluster changes and new nodes are added or existing nodes are removed from the cluster, no DNS records need to be modified. However, administrators and applications connecting to the cluster and to the databases need to maintain the IP address of at least one node in the cluster to discover and access the cluster topology.
URL-based connections and how to set up cluster name (FQDN)
The Fully Qualified Domain Name (FQDN) is the unique cluster identifier that enables clients to connect to the different components that are part of the Redis Enterprise Software. The FQDN is a crucial component of the high-availability mechanism in RS because it is used by the internal DNS to enable the automatic and transparent failover of nodes, databases shards, and endpoints, by automatically updating their IP addresses.Note -Setting the cluster’s FQDN is a one-time operation. After the FQDN is set it cannot be updated.
Naming the cluster FQDN
You have two options for naming the cluster FQDN:
Use this option if you already have your own domain, would like to make the cluster part of your domain and are able to update the DNS.
Make sure that the cluster and at least one node (preferably all nodes) in the cluster are correctly configured in the DNS with the appropriate NS entries.
- Your domain is: mydomain.com - You would like to name the Redis Enterprise Software cluster: redislabscluster - You have three nodes in the cluster: - node1 with IP 184.108.40.206 - node2 with IP 220.127.116.11 - node3 with IP 18.104.22.168
In the FQDN field, enter the value
redislabscluster.mydomain.comand add the following records in the DNS for mydomain.com:
redislabscluster.mydomain.com NS node1.redislabscluster.mydomain.com node2.redislabscluster.mydomain.com node3.redislabscluster.mydomain.com
node1.redislabscluster.mydomain.com A 22.214.171.124
node2.redislabscluster.mydomain.com A 126.96.36.199
node3.redislabscluster.mydomain.com A 188.8.131.52
Zero-configuration using mDNS (Development option only)Note -mDNS is not supported for use with production environments and should only be used in development or test environments.
mDNS (Multicast DNS) is a standard protocol that provides DNS-like name resolution and service discovery capabilities to machines on local networks with minimal to no configuration. Because not all clients support mDNS, ensure first that the clients that are connecting to the cluster actually have mDNS support, and that the network infrastructure permits mDNS/multi-casting between them and the cluster nodes.
Configuring the cluster to support mDNS requires you to assign the cluster a
For example, if you want to name the Redis Enterprise Software cluster
redislabscluster.localin the FQDN field.
When using the DNS or mDNS option, failover can be done transparently and the DNS is updated automatically to point to the IP of the new master.
When you use the IP-based connection option, the FQDN does not need to have any special format because clients use IP addresses instead of hostnames to access the databases so you are free to choose whatever name you want. Using the IP-based connection option does not require any DNS configuration either.
To administer the cluster you do need to know the IP address of at least one of the nodes in the cluster. Once you have the IP address, you can simply connect to port number 8443 (for example: https://10.0.0.12:8443). However, as the topology of the cluster changes and node with the given IP address is removed, you need to remember the IP address of another node participating in this cluster to connect to the admin console and manage the cluster.
Applications connecting to RS databases for data access have the same constraints. When using the IP-based connection method, you can use the Discovery Service to discover the database endpoint for a given database name as long as you have an IP address for at least one of the nodes in the cluster. The API used for discovery service is compliant with the Redis Sentinel API.
You can find a simple example of URL and IP-based connection in the “Testing Connectivity to your Database” section of Creating a new database.
Downloading the installation package
To download the installation package for any of the supported platforms:
- Go to the Redis Labs download page.
- Log in with your Redis Labs credentials or sign up for a new account.
- In the Downloads section for Redis Enterprise Software, select the installation package for your platform and click Go.
Installing RS on Linux
After you download the .tar file installation package, you are ready to install the package on the nodes in the cluster. Here we walk you through the process for installing the RS installation package for Linux.
Before you install RS, review these notes:
If you want to use Redis on Flash (RoF) for your databases, review the prerequisites, storage requirements, and other considerations for RoF databases and prepare and format the flash memory.To prepare and format the flash memory:
This command finds all of the unformatted disks and mounts them as RAID partitions in
To verify the disk configuration, run:
Disable Linux swap on all cluster nodes.
Make sure that you have root-level access to each node, either directly or with sudo.
If you require the
redislabsUID (user ID) and GID (group ID) numbers to be the same on all the nodes, create the
redislabsuser and group with the required numbers on each node.
When port 53 is in use, the installation fails. This is known to happen in default Ubuntu 18.04 installations in which systemd-resolved (DNS server) is running. To work around this issue, change the system configuration to make this port available before running the RS installation.Example steps to resolve the port 53 conflict:
sudo vi /etc/systemd/resolved.conf
DNSStubListener=noas the last line in the file and save the file.
sudo mv /etc/resolv.conf /etc/resolv.conf.orig
sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo service systemd-resolved restart
Make sure that the OS is not using ports in the range that Redis assigns to databases. We recommend that you restrict the OS from using Redis ports range in
net.ipv4.ip_local_port_range = 40000 65535.
The main directories that RS is installed in are:
How can I specify the directories where RS is installed?
During the installation you can specify the directories for the RS files to be installed in. The files are installed in the
redislabsdirectory in the path that you specify.Note -
- Custom installation directories are supported on RedHat Enterprise Linux versions 6 and 7.
- When you install with custom directories, the installation does not run as an RPM file.
- If a
redislabsdirectory already exists in the path that you specify, the installation fails.
- All nodes in a cluster must be installed with the same file locations.
You can specify any or all of these file locations:
Files Installer flag Example parameter Example file location Binaries files –install-dir /opt /opt/redislabs Configuration files –config-dir /etc/opt /etc/opt/redislabs Data and log files –var-dir /var/opt /var/opt/redislabs
These files are not in the custom directories:
Installation reference files
To install RS in specified file directories, run:
sudo ./install.sh --install-dir <path> --config-dir <path> --var-dir <path>
RS is installed with the system user and group
redislabs:redislabsHow can I install RS with a specific system user and group?
By default, RS is installed with the user:group
redislabs:redislabs. During the installation you can specify the OS user and group that RS is installed with and that owns all of the RS processes. If you specify the user only, then installation is run with the primary group that the user belongs to.Note -
- Custom installation user is supported on RedHat Enterprise Linux versions 6 and 7.
- When you install with custom directories, the installation does not run as an RPM file.
- You must create the user and group that you want to install with before you install RS.
- You can specify an LDAP user as the RS installation user.
To install RS with a specified user and group, run:
sudo ./install.sh --os-user <user> --os-group <group>
To install RS on Linux from the CLI:
Copy the installation package to the node.
scp redislabs-X.Y.Z-32-bionic-amd64.tar <username>@<ip_address>:/home
On the node, change to the directory where the installation package is and extract the installation files:
tar vxf <tarfile name>
To install RS, run:Note -
- The RS files are installed in the default file locations. You can also specify other directories for these files during the installation.
- RS is installed and run under the redislabs user and redislabs group. You can also specify a different user during the installation.
- You must either be logged in as the root user or use sudo to run the install process.
Answer the installation questions when shown to complete the installation process, and run
rlcheckto verify the installation.What are the installation questions?
The questions that the installation process asks are:
How can I do a silent install of RS?
Linux swap file -
Swap is enabled. Do you want to proceed? [Y/N]?
We recommend that you disable Linux swap in the operating system configuration to give RS control of the memory allocation.
Automatic OS tuning -
Do you want to automatically tune the system for best performance [Y/N]?
To let the RS installation optimize the OS for Redis Enterprise, answer
Y. The installation process prompts you for additional information.
/opt/redislabs/sbin/systune.shfile contains details about the tuning process.
Network time -
Do you want to set up NTP time synchronization now [Y/N]?
Redis Enterprise requires that all cluster nodes have synchronized time. You can either let the installation process configure NTP or you can configure NTP manually.
Firewall ports -
Would you like to open RedisLabs cluster ports on the default firewall zone [Y/N]?
RS requires the node to have specific network ports open. You can either:
Yto let the installation process open these ports.
Nand configure the firewall manually for RHEL/CentOS firewall.
Nand configure the firewall on the node manually for your OS.
Installation verification (rlcheck) -
Would you like to run rlcheck to verify proper configuration? [Y/N]?
We recommend that you run the
rlckeckinstallation verification to make sure that the installation completed successfully. If you want to run this verification at a later time, you can run:
To install RS without answering the installation questions, either:
./install.sh -yto answer yes to all of the questions.
- Prepare an answer file and use it to do a silent installation.
To install RS with an answer file:
Prepare the answer file with the answers to the installation questions.
The answer file can contain any of the parameters for the installation questions and indicate the answer for the question with
ignore_swap=no systune=yes ntp=no firewall=no rlcheck=yes
If you use
systune=yes, the installation answers yes to all of the system tuning questions.
Run the install script with
-cand the path to the answer file.
./install.sh -c /home/user/answers
After RS is successfully installed, the IP address of the RS web UI is shown:
Summary: ------- ALL TESTS PASSED. 2017-04-24 10:54:15 [!] Please logout and login again to make sure all environment changes are applied. 2017-04-24 10:54:15 [!] Point your browser at the following URL to continue: 2017-04-24 10:54:15 [!] https://<your_ip_here>:8443
RS is now installed on the node. Repeat this process for each node in the cluster.
For geo-distributed Active-Active replication, create an Active-Active database.
Set up the new cluster
A Redis Enterprise Software (RS) cluster typically consists of several nodes. For production deployments, Redis Labs recommends an uneven number of nodes, with a minimum of three.
To set up a new cluster, you must first install the Redis Enterprise Software package and then set up the cluster as described below. After the cluster is created you can add multiple nodes to the cluster.
To create a cluster:
In a browser, navigate to
https://<name or IP address of the machine with RS installed>:8443. For example, if you installed RS on a machine with IP address 10.0.1.34, then navigate to https://10.0.1.34:8443.Note -
- The RS management UI uses a self-signed SSL/TLS encryption.
- If the machine has both an internal IP address and an external IP address, use the external IP address to access the setup UI.
In the Node Configuration page that appears:
Enter a path for Persistent storage, or leave the default path.
Enter a path for Ephemeral storage, or leave the default path.
If you want to enable Redis on Flash, select the Enable flash storage support checkbox and enter the path to the Flash storage.
If your machine is configured to have multiple IP addresses, the section IP Addresses Usage is shown. Use the IP Addresses Usage section to assign a single IPv4 type address for internal traffic and multiple IPv4/IPv6 type addresses for external traffic.
In Cluster configuration, select Create new cluster.
In Cluster name (FQDN), enter a unique name for the cluster. Also, make sure that you look at the [instructions for setting up DNS](/rs/installing-upgrading/configuring/cluster-dns/ to make sure your cluster is reachable by name.
Choose whether to Enable private & public endpoints support.
Choose whether to Enable rack-zone awareness. Enabling rack-zone awareness requires setting the Rack-zone ID for the node.
If you purchased a cluster key, use the Cluster authentication page to enter the key. Otherwise, you get the trial license by default. Read the product Terms and Conditions and click Next.
Click OK to confirm that you are aware of the replacement of the HTTPS SSL/TLS certificate on the node, and proceed through the browser warning.
In the Set admin credentials fields, enter the credentials of the cluster administrator.
After a short wait, your cluster is created and you can log in to the RS admin console.
Add more nodes to the cluster
When you install Redis Enterprise Software (RS) on the first node of a cluster, you create the new cluster. After you install the first node, you can add more nodes to the cluster.
Before you add a node to the cluster:
The clocks on all nodes must always be synchronized.
If the clock in the node you are trying to join to the cluster is not synchronized with the nodes already in the cluster, the action fails and an error message is shown indicating that you must synchronize the clocks first.
You must update the DNS records each time a node is added or replaced.
We recommend that you add nodes one after the other rather than in parallel to avoid errors that occur because the connection to the other nodes in the cluster cannot be verified.
To add a node in RS:
To connect to the RS management UI of the new RS installation, go to: <https://URL or IP address:8443>
For example, if you installed RS on a machine with IP address 10.0.1.34, go to
https://10.0.1.34:8443.Tip -The RS management UI uses SSL encryption with a default certificate. You can also replace the TLS certificate with a custom certificate.
To start configuring RS, click Setup.
Configure the RS network and storage settings:
- You can enter a path for Persistent storage, or leave the default path.
- You can enter a path for Ephemeral storage, or leave the default path.
- If you want to enable Redis on Flash, select Enable flash storage support and enter the path to the Flash storage to use as RAM extension.
- If your machine has multiple IP addresses, in IP Addresses Usage assign a single IPv4 type address for internal traffic and multiple IPv4/IPv6 type addresses for external traffic.
Join the new RS node to the cluster:
In Cluster configuration, select Join cluster.
Enter the internal IP address or DNS name of a node that is a cluster member.
If the node only has one IP address, enter that IP address.
Enter the credentials of the cluster administrator.
The cluster administrator is the user account that you create when you configure the first node in the cluster.
If the cluster is configured to support rack-zone awareness, you are redirected to a page in which you must set the Rack-zone ID for the new node.
The node is added to the cluster. You can see it in the list of nodes in the cluster.
If you see an error when you add the node, try adding the node again.
Now that your cluster is set up with nodes, you can: