|
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
Redis URI (Recommended)
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)
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
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