node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

redsmin

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

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.