📡 Redsmin proxy deamon - Access local redis instance from Redsmin
JavaScript Shell
Latest commit 2c0bfd1 Dec 19, 2016 @FGRibreau FGRibreau committed on GitHub Update README.md

README.md

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

Build Status Coverage Status Deps Support Follow

Docker Hub Docker hub NPM version Downloads

We announce changes on our Twitter account @redsmin, our Facebook page and Redis Weekly Newsletter.


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 authenticat 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

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

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

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

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

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.