Databases AWS

Apache Kvrocks on AWS User Guide

| Product: Apache Kvrocks on AWS

Apache Kvrocks on AWS User Guide

This guide covers launching an Apache Kvrocks instance from the cloudimg AWS Marketplace AMI, retrieving your per-instance password, connecting with a Redis-compatible client, running Redis-protocol commands, and confirming that the RocksDB keyspace persists on a dedicated data volume.

Apache Kvrocks is a distributed, persistent key-value NoSQL database built on RocksDB and fully compatible with the Redis protocol. Unlike Redis it keeps all data on disk rather than in RAM, so it serves working sets far larger than memory at a fraction of the cost while existing Redis clients connect without code changes. It is licensed under Apache-2.0.

What Is Included

  • Apache Kvrocks 2.16.0 built from the official Apache source release, installed at /usr/local/bin/kvrocks
  • redis-cli (from the redis-tools package) for a Redis-compatible command line
  • kvrocks.service listening on 127.0.0.1:6666 (loopback only) with requirepass authentication enforced
  • A per-instance password generated on first boot, written to /root/kvrocks-credentials.txt
  • A dedicated 30 GiB gp3 data volume at /var/lib/kvrocks holding the RocksDB keyspace, independently resizable

Security Model

Kvrocks authenticates with a single shared password (requirepass) and has no transport encryption. The cloudimg image binds the service to loopback only (127.0.0.1:6666), so it is never exposed to the internet by default — the security group opens only SSH (port 22). Reach it remotely with an SSH tunnel (shown below) or by binding Kvrocks to a private interface. Do not open port 6666 to the internet without terminating TLS in front of it.

Connecting to Your Instance

OS Variant SSH Login User
Ubuntu 24.04 ubuntu

Connect using your EC2 key pair:

ssh -i /path/to/key.pem ubuntu@<instance-public-ip>

Retrieving Your Kvrocks Password

On first boot a one-shot service generates a strong 32-character password unique to your instance and writes it to a root-only file:

sudo cat /root/kvrocks-credentials.txt

Example output (your password will differ):

# Apache Kvrocks - generated on first boot by apache-kvrocks-firstboot.service
# This password is unique to this instance. Store it somewhere safe.

KVROCKS_PASSWORD=<your-unique-password>
KVROCKS_HOST=127.0.0.1
KVROCKS_PORT=6666
KVROCKS_PUBLIC_IP=203.0.113.10

# Local connection (on the instance):
#   redis-cli -p 6666 -a '<your-unique-password>' ping        ->  PONG
# Connection string:
#   redis://default:<your-unique-password>@127.0.0.1:6666/0
#
# IMPORTANT: Kvrocks listens on LOOPBACK ONLY (127.0.0.1) on port 6666 - it is NOT exposed
# publicly. For remote access open an SSH tunnel from your workstation.

Each example below reads the password from the credentials file into a KVPASS shell variable (it is never printed on screen):

KVPASS=$(sudo grep '^KVROCKS_PASSWORD=' /root/kvrocks-credentials.txt | cut -d= -f2-)
echo "password loaded (${#KVPASS} chars)"

Verifying the Service

Confirm the installed version and that kvrocks.service is active:

/usr/local/bin/kvrocks --version
systemctl status kvrocks.service --no-pager | head -6

Example output:

kvrocks version 2.16.0

* kvrocks.service - Apache Kvrocks (Redis-compatible, RocksDB-backed key-value store)
     Loaded: loaded (/etc/systemd/system/kvrocks.service; enabled; preset: enabled)
     Active: active (running) since Tue 2026-07-21 04:21:59 UTC; 27s ago
   Main PID: 20278 (kvrocks)

Confirm the listener is bound to loopback only (never 0.0.0.0):

ss -tln | grep 6666

Example output:

LISTEN 0      511        127.0.0.1:6666      0.0.0.0:*

Connecting with redis-cli

Kvrocks speaks the Redis protocol, so the standard redis-cli connects. Test with a PING:

KVPASS=$(sudo grep '^KVROCKS_PASSWORD=' /root/kvrocks-credentials.txt | cut -d= -f2-)
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning ping

Expected output:

PONG

View server information, which reports both the Kvrocks version and the Redis protocol version it emulates:

KVPASS=$(sudo grep '^KVROCKS_PASSWORD=' /root/kvrocks-credentials.txt | cut -d= -f2-)
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning info server | grep -iE 'kvrocks_version|redis_version|kvrocks_mode|^os'

Example output:

kvrocks_version:2.16.0
redis_version:7.0.0
kvrocks_mode:standalone
os:Linux 6.17.0-1019-aws x86_64

Authentication Is Enforced

Connections without the password, or with the wrong password, are refused:

redis-cli -p 6666 ping
redis-cli -p 6666 -a wrongpassword --no-auth-warning ping

Expected output (both are rejected):

NOAUTH Authentication required.
NOAUTH Authentication required.

Basic Operations

Kvrocks supports the common Redis data types. Store and retrieve a string:

KVPASS=$(sudo grep '^KVROCKS_PASSWORD=' /root/kvrocks-credentials.txt | cut -d= -f2-)
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning set greeting "hello from kvrocks"
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning get greeting

Expected output:

OK
hello from kvrocks

Increment a counter:

KVPASS=$(sudo grep '^KVROCKS_PASSWORD=' /root/kvrocks-credentials.txt | cut -d= -f2-)
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning del visits
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning incr visits
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning incr visits

Expected output:

0
1
2

Push to a list and read it back:

KVPASS=$(sudo grep '^KVROCKS_PASSWORD=' /root/kvrocks-credentials.txt | cut -d= -f2-)
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning del tasks
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning rpush tasks build test deploy
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning lrange tasks 0 -1

Expected output:

0
3
build
test
deploy

On-Disk Persistence

Kvrocks persists to disk through RocksDB, so data survives service restarts and reboots. Write a key, restart the service, wait for it to reopen the store, and read it back:

KVPASS=$(sudo grep '^KVROCKS_PASSWORD=' /root/kvrocks-credentials.txt | cut -d= -f2-)
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning set durable "survives-restart"
sudo systemctl restart kvrocks.service
for i in $(seq 1 30); do
  redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning ping 2>/dev/null | grep -q PONG && break
  sleep 1
done
redis-cli -p 6666 -a "${KVPASS}" --no-auth-warning get durable

Expected output:

OK
survives-restart

Data Volume

The RocksDB keyspace lives on a dedicated 30 GiB gp3 volume mounted at /var/lib/kvrocks, separate from the OS disk and independently resizable:

df -h /var/lib/kvrocks
findmnt /var/lib/kvrocks

Example output:

Filesystem      Size  Used Avail Use% Mounted on
/dev/nvme1n1     30G  4.8M   28G   1% /var/lib/kvrocks

TARGET           SOURCE       FSTYPE OPTIONS
/var/lib/kvrocks /dev/nvme1n1 ext4   rw,relatime

Remote Access via an SSH Tunnel

Because Kvrocks binds to loopback only, connect a client on your workstation through an SSH tunnel. From your machine:

ssh -i /path/to/key.pem -L 6666:127.0.0.1:6666 ubuntu@<instance-public-ip>

Leave that session open and, in another terminal on your workstation, point redis-cli at localhost:

redis-cli -p 6666 -a '<your-unique-password>' ping

The tunnel forwards localhost:6666 on your machine to 127.0.0.1:6666 on the instance, so Kvrocks stays unexposed to the internet.

Configuration

The Kvrocks configuration file is /etc/kvrocks/kvrocks.conf (owned root:kvrocks, mode 640). Key directives set by cloudimg:

bind 127.0.0.1
port 6666
workers 2
dir /var/lib/kvrocks
requirepass <your-unique-password>

After editing, restart the service to apply changes:

sudo systemctl restart kvrocks.service

Changing the Password

Edit the requirepass directive and restart the service:

NEW_PASS=$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | cut -c1-32)
sudo sed -i -E "s|^[[:space:]]*requirepass[[:space:]].*|requirepass ${NEW_PASS}|" /etc/kvrocks/kvrocks.conf
sudo systemctl restart kvrocks.service

Then update /root/kvrocks-credentials.txt with the new password for future reference. Because this rotates the live password, run it only when you intend to change credentials.

Backup and Maintenance

The entire keyspace lives under /var/lib/kvrocks. For a consistent snapshot, stop the service, archive the directory, and restart:

sudo systemctl stop kvrocks.service
sudo tar -czf /tmp/kvrocks-backup-$(date +%F).tar.gz -C /var/lib/kvrocks .
sudo systemctl start kvrocks.service

For live backups and replication, consult the upstream Kvrocks documentation on the BGSAVE-style snapshotting and replica configuration it supports.

Support

24/7 technical support is available from cloudimg at www.cloudimg.co.uk. Support covers Kvrocks deployment, RocksDB and persistence tuning, Redis-protocol client compatibility, replication planning, credential management, and version upgrades.