How to Set Up Twemproxy (Nutcracker) for Scalable Redis Caching

twemproxy Introduction

twemproxy (also called nutcracker) is a lightweight high‑performance Redis/Memcached proxy contributed by Twitter.

client → twemproxy → redis/memcached …

Its main purpose is to reduce the number of connections to backend cache servers and, through pipelining and sharding, enable horizontally scalable distributed cache architectures.

Features

Fast and lightweight

Maintains persistent connections, keeping backend connections low

Pipelined command requests and responses improve performance

Automatic cross‑server sharding

Simple configuration

Supports various hash modes such as consistent hash

Can disable failed nodes

State can be monitored via a monitoring port

Limitations

Only commands supported by twemproxy can be used; new Redis commands require twemproxy updates.

Installation and Configuration

Below we install and run twemproxy to proxy two Redis instances.

Installation

(1) Redis

Download http://redis.io Extract and install

tar xvf redis-3.2.7.tar.gz
cd redis-3.2.7
make && make install

(2) autoconf

Download ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz Extract and install

tar xvf autoconf-2.69.tar.gz
cd autoconf-2.69
./configure
make && make install

(3) twemproxy

git clone https://github.com/twitter/twemproxy.git
cd twemproxy
autoreconf -fvi
./configure
make && make install
src/nutcracker -h

Configuration

(1) Run two Redis instances

Copy two configuration files

cp redis.conf redis1.conf
cp redis.conf redis2.conf

redis1.conf uses the default port 6379.

Modify redis2.conf to use port 6380:

port 6380
pidfile /var/run/redis_6380.pid

Start the instances

src/redis-server redis1.conf &
src/redis-server redis2.conf &

(2) Configure twemproxy

Create a configuration file conf/my.yml:

alpha:
  listen: 127.0.0.1:22121
  hash: fnv1a_64
  distribution: ketama
  auto_eject_hosts: true
  redis: true
  server_retry_timeout: 2000
  server_failure_limit: 1
  servers:
    - 127.0.0.1:6379:1 server1
    - 127.0.0.1:6380:1 server2

Main parameters: listen – address and port of twemproxy hash – hash method name distribution – distribution mode redis – whether the backend is Redis servers – list of Redis instances

Start twemproxy src/nutcracker -d -c conf/my.yml Check status

ps -ef | grep nutcracker | grep -v grep
netstat -nltp | grep nutcracker

Testing

Connect to twemproxy with a Redis client and run commands:

redis-cli -p 22121
127.0.0.1:22121> set test 'hi'
OK
127.0.0.1:22121> get test
"hi"
127.0.0.1:22121> set hello 'world'
OK
127.0.0.1:22121> get hello
"world"

Verify that the keys are stored in the respective Redis instances:

Redis 1

redis-cli -p 6379
127.0.0.1:6379> keys *
1) "test"

Redis 2

redis-cli -p 6380
127.0.0.1:6380> keys *
1) "hello"

This shows that the two keys are sharded across redis1 and redis2.

High‑Availability Considerations

In a distributed environment, high availability must be addressed.

The architecture raises two single‑point‑of‑failure concerns:

twemproxy itself

Redis instances

For the twemproxy single point, deploy multiple twemproxy instances behind HAProxy for load balancing.

For Redis, add slaves and use Sentinel for automatic failover.

Sentinel monitors Redis; upon failure it promotes a slave to master. After failover, update twemproxy configuration either via a script triggered by Sentinel or by using a virtual IP for twemproxy.