search

riotkit-org / tunman

Comprehensive solution for SSH tunnels - respawning, healthchecking/monitoring
49 stars 4 forks source link
docker firewall firewall-bypass monitoring nat port-forwarding private-network proxy remote-machine reverse-proxy routing ssh ssh-tunnel tunnel tunneling tunneling-proxies tunnels tunnels-to-localhost vpc vpn

readme

TunMan

Maintainability Test Coverage Build Status

Network setup automation and supervising. Provides monitoring, health checking, validating the connection with custom Python methods. Replaces old, slow maintained autossh.

Super-elastic, allows for dynamic IP resolving on local and remote using Python callback functions. It means you can achieve totally everything.

Allows to create multiple tunnels from inside of NAT to the external server, and vice-versa.

Works in at least those cases:

TunMan's motto is: Be bulletproof! Switch to VPN, switch from WiFi to LTE, hibernate computer in Poland - wake up in Spain, cut off the internet for a few hours. Nothing matters, it should work when you go back online!

screenshot

example structure

Note: The project was renamed from "reverse-networking" into TunMan from 3.0.0 release

Requirements

Those very basic packages needs to be installed:

Development packages for development:

Works with GNU utils as well as with Busybox. Tested on Arch Linux, Debian and Alpine Linux.

The preferred way of authorization with remote is key based authorization

Installing

You may want to use docker or baremetal installation.

Baremetal installation

git clone git@github.com:riotkit-org/reverse-networking.git -b v3.1.0-rc2 # change "v3.1.0-rc2" to some version
cd reverse-networking

sudo ./setup.py install

Installing from PIP

sudo pip3 install tunman

Setup

Put your configuration files into conf.d of a directory you specified as configuration directory (-c or --config param, /conf.d docker volume) Please check out the example/scenario-* directories for example configuration directories.

1. File must be written in Python syntax
2. You can import any library you have in system or in docker container, including "paramiko" and "subprocess"
3. You can use any shell commands available in the shell ex. mysql or psql in the configuration callbacks

Send public key to all servers described in your configuration so the communication could be without a password using a ssh key.

Configure and start:

# you can use command-line switches ex. "--config" or environment variables
export TUNMAN_CONFIG="path-to-config-directory"   # -c / --config
export TUNMAN_SECRET_PREFIX=""                    # -s / --secret-prefix
export TUNMAN_ENV="prod"                          # -e / --env

tunman add-to-known-hosts
tunman send-public-key
tunman start

That's all! Your local services should be exposed to the remote server and be visible on eg. http://localhost:1234, so you need an internal proxy or a load balancer like nginx to forward the traffic to the internet.

Health checking and status monitoring

Health check:

curl http://localhost:8015/health

HTML status page: http://localhost:8015/

Notice: The URL can be prefixed with (-s/--secret-prefix/TUNMAN_SECRET_PREFIX) ex. http://localhost/some-secret-prefix/health

Using with Docker

Notice: It's recommended to use a stable version ex. v3.1.0-x86_64 instead of latest-dev-x86_64. For demo reasons you may want to check out latest-dev-x86_64

Please check out a list of available tags there: https://quay.io/repository/riotkit/reverse-networking?tab=tags

version: "2"
services:
    proxy:
        image: quay.io/riotkit/reverse-networking:latest-dev-x86_64
        volumes:
            - "./configuration:/config:ro"   # see example directory structure in "example/scenario-*" directories
            - "./id_rsa:/id_rsa:ro"          # a place for your private key, you may pick other one and point to it in the configuration
            - "./id_rsa.pub:/id_rsa.pub:ro"
        environment:
            - TUNMAN_SECRET_PREFIX=
            - TUNMAN_ENV=prod

Docker container configuration reference

List of all environment variables that could be used.


- TUNMAN_CONFIG # (default: /config)

# Environment, options: dev, prod
- TUNMAN_ENV # (default: prod)

# Secret prefix in the URL ex. https://your-app.org/super-hiper-secret-here/health
- TUNMAN_SECRET_PREFIX # (default: )

Example configuration

Please check the example directory for examples.

Variables table

Often you do not know on which IP address is the docker container, or interface listening. TunMan allows to retrieve dynamic values using variables.

You can use variables instead of ex. host name

Variable Description
{{ remote_gw }} IP address of ssh destination host
{{ remote_interface_gw }} IP address of a interface that is a default gateway in route table on remote SSH
{{ remote_docker_host }} Autodetected docker host IP address (local bridge)
{{ remote_docker_container }} If SSH server is containerized, then it will point to a IP address of a container
{{ remote_interface_eth0 }} eth0 interface ip address
{{ remote_interface_eth1 }} eth1 interface ip address
{{ remote_interface_eth2 }} eth2 interface ip address

FAQ

  1. Cannot connect to SSH, invalid key or unsupported key type
paramiko.ssh_exception.SSHException: Invalid key
paramiko.ssh_exception.SSHException: not a valid OPENSSH private key file

It is a common problem in Paramiko library, that we use. Generate the key using a different format, examples:

ssh-keygen -t ed25519 -b 4096

More documentation

See here: docs/pages

Configuration reference

For list of all possible options to use in configuration file please check example configuration file.

Here: example/reference.py

Developing

Project Keywords

tunneling, ssh tunnel restart, autossh, sshpass, autorestart tunnel, ssh proxy, expose service behind nat, revproxy, how to tunnel mysql, tunnel manager, tunnel supervisor, tunnel monitoring, ssh monitoring, ssh automation, ssh setup automation, access service behind nat, nginx through ssh

Copyleft

Created by RiotKit Collective, a libertarian, grassroot, non-profit organization providing technical support for the non-profit Anarchist movement.

Check out those nice non-profit initiatives we are friends with: