Redsmin Proxy — Securely connect behind the firewall (or localhost) Redis servers to Redsmin

• Installation - Getting started
• Environment variables options
• Is the communication safe between my server and Redsmin? (Yes)
• How to start Redsmin proxy
  • on Docker
    • Start and connect Redsmin proxy to a local Redis server
    • Start and connect Redsmin proxy to an network-wide available Redis
    • Start and connect Redsmin proxy to a Redis container
    • Docker auto-restart
  • on Mac OS X
  • on Debian/Ubuntu, *nix
  • on Windows
  • with a password protected redis
    • Mac OS X
    • Debian/Ubuntu, *nix
    • Windows
  • with a redis listening on a unix-socket
    • Mac OS X
    • Debian/Ubuntu, *nix
    • Windows
  • reading a configuration file
• How to connect multiple Redis from the same server to Redsmin
• How to keep redsmin proxy up once I disconnect
  • with nohup
  • with screen
  • with a process manager
  • with systemd
• I'm behind a firewall, what rule should I add?
• How to uninstall Redsmin Proxy
• Throubleshooting
  • Ready check failed: NOAUTH Authentication required.
• Changelog

We announce changes on our Twitter account @redsmin, our Facebook page.

Environment variables options:

• CONFIG_FILE: configuration file to read (if any), default: /path/to/redsmin-proxy/etc/redsmin.json
• REDIS_URI: Redis URI or socket path, default redis://127.0.0.1:6379
• REDIS_AUTH: Redis authentication password, default null
• REDSMIN_KEY: your Redsmin server connection key, default ''

Advanced configuration:

• REDSMIN_PORT: where redsmin proxy should connect, default: 993
• REDSMIN_HOSTNAME: where redsmin proxy should connect, default ssl.redsmin.com
• DEBUG: debug mode, default false
• Prefix REDIS_URI with rediss:// to connect to Redis using TLS encryption

Is the communication safe between my server and Redsmin? (Yes)

Yes, Redsmin and Redsmin proxy communicate through a secure connection using the TLS 1.2 protocol so no one will be able to inspect the data looking at the traffic.

How to start Redsmin proxy

Docker

Start and connect Redsmin proxy to a local Redis server

Let say you started redis-server on your machine and then want to start redsmin-proxy from docker. If you are on MacOSX or Windows the following command won't work (if you are on Linux the following line will work):

docker run -it --rm --net=host --name redsmin-proxy -e REDSMIN_KEY=YOUR_REDSMIN_KEY -e REDIS_URI="redis://127.0.0.1:6379" redsmin/proxy

It does not work because on non-linux environment the docker daemon is running inside a VM and your redis-server is running on your host machine, thus accessing 127.0.0.1 from the docker daemon will simply hit the VM loopback.

So we simply need to specify the HOST_IP (replace it with your own local IP, you may want to use ifconfig to find it) instead of 127.0.0.1:

docker run -it --rm --name redsmin-proxy -e REDSMIN_KEY=YOUR_REDSMIN_KEY -e REDIS_URI="redis://HOST_IP:6379" redsmin/proxy

On MacOSX, this should work and let redsmin-proxy connect to a Redis container on the same host:

docker run -it --rm --name redsmin-proxy -e REDSMIN_KEY=YOUR_REDSMIN_KEY -e REDIS_URI="redis://docker.for.mac.localhost:6379" redsmin/proxy

Start and connect Redsmin proxy to an network-wide available Redis

docker run -it --rm --name redsmin-proxy -e REDSMIN_KEY=YOUR_REDSMIN_KEY -e REDIS_URI="redis://192.168.3.50:6379" redsmin/proxy

Where redis://192.168.3.50:6379 will be the ip address and port of the running Redis server and YOUR_REDSMIN_KEY is your Redsmin key.

Start and connect Redsmin proxy to a Redis container

Let first say you've started a Redis container:

docker run --name my-redis --rm redis

You can link redsmin proxy container to the redis one with `--link:

docker run -it --rm --name redsmin-proxy --link my-redis:local-redis -e REDSMIN_KEY=YOUR_KEY -e REDIS_URI="redis://local-redis:6379" redsmin/proxy

Docker auto-restart

If you want to leverage docker auto-restart docker feature, use the --restart=always command.

MacOS, Debian/Ubuntu

npm install redsmin --global
REDIS_URI="redis://127.0.0.1:6379" REDSMIN_KEY="redsmin-token" redsmin

Windows (PowerShell)

npm install redsmin --global
$env:REDIS_URI="redis://127.0.0.1:6379"
$env:REDSMIN_KEY="redsmin-token"
redsmin

Windows (CMD.exe)

npm install redsmin --global
set REDIS_URI=redis://127.0.0.1:6379
set REDSMIN_KEY=redsmin-token
redsmin

Note: don't use double quotes for values on windows (bad 🔴 : set KEY="VALUE", good ✅ : set KEY=VALUE)

How to start Redsmin proxy with a password protected redis

MacOS, Debian/Ubuntu

npm install redsmin --global
REDIS_URI="redis://127.0.0.1:6379" REDIS_AUTH="auth-pass" REDSMIN_KEY="redsmin-token" redsmin

Windows

npm install redsmin --global
set REDIS_URI=redis://127.0.0.1:6379
set REDIS_AUTH=auth-pass
set REDSMIN_KEY=redsmin-token
redsmin

Note: don't use double quotes for values on windows (bad 🔴 : set KEY="VALUE", good ✅ : set KEY=VALUE)

How to start Redsmin proxy with a redis listening on a unix-socket

MacOS, Debian/Ubuntu

npm install redsmin --global
REDIS_URI="/tmp/redis.sock" REDSMIN_KEY="5517e20046f4c7530d000357" redsmin

Windows

npm install redsmin --global
set REDIS_URI=/tmp/redis.sock
set REDSMIN_KEY=5517e20046f4c7530d000357
redsmin

Note:

• don't use double quotes for values on windows (bad 🔴 : set KEY="VALUE", good ✅ : set KEY=VALUE)
• you may need to use sudo to access to the socket.

How to start Redsmin proxy reading a configuration file

First create a json configuration file, for instance /etc/redsmin.json:

{
  "key": "redsmin-token",
  "redis": "redis://127.0.0.1:6379",
  "auth": ""
}

Then start redsmin proxy with:

MacOS, Debian/Ubuntu

CONFIG_FILE="/etc/redsmin.json" redsmin

Windows

set CONFIG_FILE="/etc/redsmin.json"
redsmin

How to connect multiple Redis from the same server to Redsmin

MacOS, Debian/Ubuntu

REDIS_URI="redis://127.0.0.1:6379" REDSMIN_KEY="redsmin-token1" redsmin &
REDIS_URI="redis://127.0.0.1:6380" REDSMIN_KEY="redsmin-token2" redsmin &
REDIS_URI="redis://127.0.0.1:6381" REDSMIN_KEY="redsmin-token3" redsmin &
REDIS_URI="redis://127.0.0.1:6382" REDSMIN_KEY="redsmin-token4" redsmin &

Windows

set REDIS_URI="redis://127.0.0.1:6379"
set REDSMIN_KEY=redsmin-token1
START /B redsmin

set REDIS_URI="redis://127.0.0.1:6380"
set REDSMIN_KEY=redsmin-token2
START /B redsmin

set REDIS_URI="redis://127.0.0.1:6381"
set REDSMIN_KEY=redsmin-token3
START /B redsmin

set REDIS_URI="redis://127.0.0.1:6382"
set REDSMIN_KEY=redsmin-token4
START /B redsmin

Note:

• of course we could have used multiple CONFIG_FILE instead of environment variables.

How to keep redsmin proxy up once I disconnect

With nohup

The easiest way is to use nohup that will keep redsmin-proxy running even once the SSH session is closed. Simply connect to the server that contains Redis, run the commands below, don't forget to replace YOUR_REDSMIN_TOKEN with the REDSMIN_TOKEN you had when creating the proxy connection from Redsmin app.

echo '#!/usr/bin/env bash' >> redsmin-proxy.sh
echo 'while true; do REDSMIN_KEY=YOUR_REDSMIN_TOKEN redsmin; sleep 1; done;' >> redsmin-proxy.sh
chmod +x redsmin-proxy.sh
nohup ./redsmin-proxy.sh &

To check that everything is alright or to debug Redsmin proxy, you can use tail -f nohup.out.

With nohup (one-liner)

nohup bash -c "while true; do REDSMIN_KEY=YOUR_REDSMIN_TOKEN redsmin; sleep 1; done" &

With screen

On MacOS, Ubuntu/Debian, the simplest way is to use screen:

# start screen
screen
# start redsmin-proxy
REDIS_URI="redis://127.0.0.1:6379" REDSMIN_KEY="redsmin-token1" redsmin
# Ctrl+A+D to detach from screen
# and then to reattach to the screen session:
screen -r

With a process manager

But you could also use Upstart, systemd, supervisord or pm2 on these system.

On Windows you will need to create a service or use pm2.

With Systemd

Create the service at /etc/systemd/system/redsmin.service

[Unit]
Description=Redsmin Proxy
After=network.target

[Service]
Type=simple
Environment=REDIS_URI=redis://127.0.0.1:6379 REDSMIN_KEY=your-token-here
ExecStart=/usr/bin/redsmin $REDIS_URI $REDSMIN_KEY
TimeoutStartSec=infinity
Restart=on-abort

[Install]
WantedBy=multi-user.target

Reload systemd by systemctl daemon-reload.

You can now start/stop/restart redsmin like any other systemd service, like systemctl start redsmin.

We will happily merge into this repository any pull-request describing a configuration file for one of the above process runner (or any other one).

I'm behind a firewall, what rule should I add?

Redsmin proxy connects to ssl.redsmin.com on port 993 with a secure TLS socket connection. For troubleshooting: What ip/port should I locally open to use Redsmin proxy.

How to uninstall Redsmin Proxy

MacOS, Debian/Ubuntu

npm uninstall redsmin -g

Throubleshooting

Ready check failed: NOAUTH Authentication required

It means that your Redis server required a password and that no password is configured in Redsmin Proxy. To fix this start Redsmin proxy with the REDIS_AUTH environment variable.