Sentinel

Boost.Redis supports Redis Sentinel deployments. Sentinel handling in connection is built-in: async_run automatically connects to Sentinels, resolves the master’s address, and connects to the master.

Configuration is done using config::sentinel:

config cfg;

// To enable Sentinel, set this field to a non-empty list
// of (hostname, port) pairs where Sentinels are listening
cfg.sentinel.addresses = {
    {"sentinel1.example.com", "26379"},
    {"sentinel2.example.com", "26379"},
    {"sentinel3.example.com", "26379"},
};

// Set master_name to the identifier that you configured
// in the "sentinel monitor" statement of your sentinel.conf file
cfg.sentinel.master_name = "mymaster";

Once set, the connection object can be used normally. See our our Sentinel example for a full program.

Connecting to replicas

By default, the library connects to the Redis master. You can connect to one of its replicas by using config::sentinel::server_role. This can be used to balance load, if all your commands read data from the server and never write to it. The particular replica will be chosen randomly.

config cfg;

// Set up Sentinel
cfg.sentinel.addresses = {
    {"sentinel1.example.com", "26379"},
    {"sentinel2.example.com", "26379"},
    {"sentinel3.example.com", "26379"},
};
cfg.sentinel.master_name = "mymaster";

// Ask the library to connect to a random replica of 'mymaster', rather than the master node
cfg.sentinel.server_role = role::replica;

Sentinel authentication

If your Sentinels require authentication, you can use config::sentinel::setup to provide credentials. This request is executed immediately after connecting to Sentinels, and before any other command:

// Set up Sentinel
config cfg;
cfg.sentinel.addresses = {
    {"sentinel1.example.com", "26379"},
    {"sentinel2.example.com", "26379"},
    {"sentinel3.example.com", "26379"},
};
cfg.sentinel.master_name = "mymaster";

// By default, setup contains a 'HELLO 3' command.
// Override it to add an AUTH clause to it with out credentials.
cfg.sentinel.setup.clear();
cfg.sentinel.setup.push("HELLO", 3, "AUTH", "sentinel_user", "sentinel_password");

// cfg.sentinel.setup applies to Sentinels, only.
// Use cfg.setup to authenticate to masters/replicas.
cfg.use_setup = true; // Required for cfg.setup to be used, for historic reasons
cfg.setup.clear();
cfg.setup.push("HELLO", 3, "AUTH", "master_user", "master_password");

Using TLS with Sentinels

You might use TLS with Sentinels only, masters/replicas only, or both by adjusting config::sentinel::use_ssl and config::use_ssl:

// Set up Sentinel
config cfg;
cfg.sentinel.addresses = {
    {"sentinel1.example.com", "26379"},
    {"sentinel2.example.com", "26379"},
    {"sentinel3.example.com", "26379"},
};
cfg.sentinel.master_name = "mymaster";

// Adjust these switches to enable/disable TLS
cfg.use_ssl = true;          // Applies to masters and replicas
cfg.sentinel.use_ssl = true; // Applies to Sentinels

Sentinel algorithm

This section details how async_run interacts with Sentinel. Most of the algorithm follows the official Sentinel client guidelines. Some of these details may vary between library versions.

  • Connections maintain an internal list of Sentinels, bootstrapped from config::sentinel::addresses.

  • The first Sentinel in the list is contacted by performing the following:

    • A physical connection is established.

    • The setup request is executed.

    • The master’s address is resolved using SENTINEL GET-MASTER-NAME-BY-ADDR.

    • If config::sentinel::server_role is role::replica, replica addresses are obtained using SENTINEL REPLICAS. One replica is chosen randomly.

    • The address of other Sentinels also monitoring this master are retrieved using SENTINEL SENTINELS.

  • If a Sentinel is unreachable, doesn’t know about the configured master, or returns an error while executing the above requests, the next Sentinel in the list is tried.

  • If all Sentinels have been tried without success, config::reconnect_wait_interval is waited, and the process starts again.

  • After a successful Sentinel response, the internal Sentinel list is updated with any newly discovered Sentinels. Sentinels in config::sentinel::addresses are always kept in the list, even if they weren’t present in the output of SENTINEL SENTINELS.

  • The retrieved address is used to establish a connection with the master or replica. A ROLE command is added at the end of the setup request. This is used to detect situations where a Sentinel returns outdated information due to a failover in process. If ROLE doesn’t output the expected role ("master" or "slave", depending on config::sentinel::server_role) config::reconnect_wait_interval is waited and Sentinel is contacted again.

  • The connection to the master/replica is run like any other connection. If network errors or timeouts happen, config::reconnect_wait_interval is waited and Sentinel is contacted again.