redsmin/proxy repository overview

⁠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⁠
    • with supervisord⁠
• 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.

⁠With Supervisord

Create a config file with these contents:

[program:redsmin]
command = /usr/bin/redsmin
autostart = true
autorestart = true
environment = REDIS_URI="redis://127.0.0.1:6379",REDSMIN_KEY="your-token-here"

Reload supervisord config by supervisorctl reread && supervisorctl update

We will happily merge into this repository any pull-request describing a configuration file for any other process runner.

⁠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.