For the latest stable version, please use RIOT-X 2.0!

Redis Connections

RIOT-X supports multiple ways to connect to both source and target Redis databases, including various authentication methods and security configurations.

Connection Methods

The simplest way to specify Redis connections is using Redis URIs:

riotx replicate redis://source:6379 redis://target:6379

For secure connections:

riotx replicate rediss://source:6380 rediss://target:6380
To replicate a Redis logical database other than the default (0), specify the database in the source Redis URI. For example riotx replicate redis://source:6379/1 redis://target:6379 replicates database 1.

Individual Connection Parameters

You can also specify connection details using individual options:

Source database options:

riotx replicate \
  --source-host source.example.com \
  --source-port 6379 \
  --source-user myuser \
  --source-pass mypassword \
  --target-uri rediss://target:6380

Target database options:

riotx replicate redis://source:6379 \
  --target-host target.example.com \
  --target-port 6380 \
  --target-tls \
  --target-user myuser \
  --target-pass mypassword

Authentication

RIOT-X supports multiple authentication methods for connecting to Redis databases.

Username/Password Authentication

For Redis ACL (Redis 6+) or basic AUTH:

Via URI:

riotx replicate redis://user:pass@source:6379 redis://user:pass@target:6379

Via options:

riotx replicate redis://source:6379 redis://target:6379 \
  --source-user myuser --source-pass mypass \
  --target-user myuser --target-pass mypass

Entra ID Authentication (Azure)

For Azure Cache for Redis Enterprise with Entra ID authentication:

Basic Entra ID (Managed Identity):

riotx replicate redis://source.redis.cache.windows.net:10000 \
                redis://target.redis.cache.windows.net:10000 \
  --source-entra \
  --target-entra

Entra ID with Client Credentials:

riotx replicate redis://source.redis.cache.windows.net:10000 \
                redis://target.redis.cache.windows.net:10000 \
  --source-entra \
  --source-entra-id "client-id" \
  --source-entra-secret "client-secret" \
  --target-entra \
  --target-entra-id "client-id" \
  --target-entra-secret "client-secret"

Advanced Entra ID Configuration:

riotx replicate redis://source.redis.cache.windows.net:10000 \
                redis://target.redis.cache.windows.net:10000 \
  --source-entra \
  --source-entra-auth "https://login.microsoftonline.com/tenant-id" \
  --source-entra-scope "https://redis.azure.com/.default" \
  --source-entra-refresh 0.75 \
  --target-entra

Environment Variables for Entra ID: You can also configure Entra ID authentication using environment variables:

export RIOT_SOURCE_ENTRA=true
export RIOT_SOURCE_ENTRA_ID=your-client-id
export RIOT_SOURCE_ENTRA_SECRET=your-client-secret
export RIOT_TARGET_ENTRA=true

riotx replicate redis://source.redis.cache.windows.net:10000 \
                redis://target.redis.cache.windows.net:10000

Certificate-Based Authentication

Client Certificate Authentication:

riotx replicate rediss://source:6380 rediss://target:6380 \
  --source-cert /path/to/client.crt \
  --source-key /path/to/client.key \
  --target-cert /path/to/client.crt \
  --target-key /path/to/client.key

Custom CA Certificate:

riotx replicate rediss://source:6380 rediss://target:6380 \
  --source-cacert /path/to/ca.crt \
  --target-cacert /path/to/ca.crt

TLS/SSL Configuration

Basic TLS

Enable TLS:

riotx replicate redis://source:6379 redis://target:6379 \
  --source-tls --target-tls

Or use TLS URIs:

riotx replicate rediss://source:6380 rediss://target:6380

TLS Verification Modes

Control how TLS certificates are verified:

riotx replicate rediss://source:6380 rediss://target:6380 \
  --source-verify FULL \
  --target-verify NONE

Available verification modes: * FULL - Verify hostname and certificate chain (default, most secure) * CA - Verify certificate chain only * NONE - No certificate verification (insecure)

Insecure TLS (Development Only)

Only use this in development environments.
riotx replicate rediss://source:6380 rediss://target:6380 \
  --source-insecure --target-insecure

Cluster Configuration

For Redis Cluster deployments:

riotx replicate redis://source-node1:7000,source-node2:7000,source-node3:7000 \
                redis://target-node1:7000,target-node2:7000,target-node3:7000 \
  --source-cluster --target-cluster

Or using individual options:

riotx replicate redis://source:7000 redis://target:7000 \
  --source-cluster --target-cluster

Connection Tuning

Connection Pool Size

Configure the number of connections in the pool:

riotx replicate redis://source:6379 redis://target:6379 \
  --source-pool 16 --target-pool 16

Read Preference (Cluster Mode)

For source clusters, specify where to read from:

riotx replicate redis://source:7000 redis://target:6379 \
  --source-cluster \
  --source-read-from REPLICA_PREFERRED

Available read preferences: * UPSTREAM - Read from master nodes (default) * UPSTREAM_PREFERRED - Prefer master, fallback to replica * REPLICA - Read from replica nodes only * REPLICA_PREFERRED - Prefer replica, fallback to master * LOWEST_LATENCY - Read from node with lowest latency * ANY - Read from any available node

Command Timeout

Set timeout for Redis commands:

riotx replicate redis://source:6379 redis://target:6379 \
  --source-timeout 30s --target-timeout 30s

Linux transport and replication stalls

The riotx launch scripts disable Lettuce’s io_uring transport by default with -Dio.lettuce.core.iouring=false. This also applies to standalone distributions with a bundled JVM and Gradle’s run tasks. Lettuce can use another available transport, such as epoll or Java NIO. The setting applies to both source and target connections and all commands.

For older releases, including RIOT-X 1.15.1, set the property before starting replication:

JAVA_OPTS="${JAVA_OPTS:+$JAVA_OPTS }-Dio.lettuce.core.iouring=false" \
  ./bin/riotx replicate "$OLD_URI" "$NEW_URI" --mode live --struct

Use the same environment setting with sync2. When launching Java directly, pass -Dio.lettuce.core.iouring=false before the main class or -jar; JAVA_OPTS is interpreted by the launch scripts, not by Java itself.

A user reported intermittent scan stalls with both replicate --mode live --struct and sync2 --mode LIVE --struct on Debian 12, kernel 6.1.0-54-cloud-amd64, using RIOT-X 1.15.1 and its bundled Java 25.0.1. The source socket retained unread data, target connections were idle, and Lettuce’s io_uring event-loop threads waited in ioUringEnter. Disabling io_uring selected NIO and allowed the reported 12.27-million-key scan to complete. Increasing command timeouts had not resolved the stalls.

These symptoms suggest a transport read stall; waiting in ioUringEnter or Mono.block alone does not establish a fault. Netty #17049 describes similar unread responses and a read-cancellation race, fixed by #17087 in 4.2.17.Final. RIOT-X 1.15.1 pins Netty 4.2.13.Final. The reported RIOT-X case has not been reproduced to confirm that it is the same defect, and no specific kernel bug has been established. Keep io_uring disabled for affected migration runs until a fix is verified in that environment.

To explicitly allow io_uring again, set JAVA_OPTS="-Dio.lettuce.core.iouring=true" before invoking the launcher. This permits Lettuce to select io_uring when available; it does not force it over other native transports. Transport properties must be set at JVM startup, before Lettuce initializes.

When reporting a stall, include the RIOT-X, Lettuce, Netty and Java versions, uname -a, a thread dump, source socket queues (ss -tnpi), target CLIENT LIST, and whether disabling io_uring changes the result. Remove credentials and sensitive endpoints before sharing diagnostics.

Connection Examples

Redis Cloud to Redis Cloud

riotx replicate \
  redis://default:source-password@source-endpoint.c1.cloud.redislabs.com:12000 \
  redis://default:target-password@target-endpoint.c1.cloud.redislabs.com:12001

AWS ElastiCache to Azure Cache for Redis

riotx replicate \
  rediss://source.abc123.cache.amazonaws.com:6380 \
  redis://target.redis.cache.windows.net:10000 \
  --source-pass elasticache-auth-token \
  --target-entra

Self-hosted Redis to Redis Enterprise Cloud

riotx replicate \
  redis://localhost:6379 \
  rediss://redis-endpoint.c1.cloud.redislabs.com:12000 \
  --source-user myuser --source-pass mypass \
  --target-user default --target-pass cloud-password