{"id":22481753,"url":"https://github.com/riotkit-org/tunman","last_synced_at":"2025-08-02T16:30:59.226Z","repository":{"id":57477151,"uuid":"83520256","full_name":"riotkit-org/tunman","owner":"riotkit-org","description":"Comprehensive solution for SSH tunnels - respawning, healthchecking/monitoring","archived":false,"fork":false,"pushed_at":"2020-08-17T15:15:19.000Z","size":925,"stargazers_count":49,"open_issues_count":0,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-03T20:03:50.026Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riotkit-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-01T06:29:25.000Z","updated_at":"2024-10-28T15:54:02.000Z","dependencies_parsed_at":"2022-09-14T17:11:36.961Z","dependency_job_id":null,"html_url":"https://github.com/riotkit-org/tunman","commit_stats":null,"previous_names":["riotkit-org/reverse-networking"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riotkit-org%2Ftunman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riotkit-org%2Ftunman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riotkit-org%2Ftunman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riotkit-org%2Ftunman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riotkit-org","download_url":"https://codeload.github.com/riotkit-org/tunman/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228491918,"owners_count":17928719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-12-06T16:15:15.044Z","updated_at":"2024-12-06T16:15:15.820Z","avatar_url":"https://github.com/riotkit-org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"TunMan\n======\n\n[![Maintainability](https://api.codeclimate.com/v1/badges/a3df7c2e60ee90d149a0/maintainability)](https://codeclimate.com/github/riotkit-org/reverse-networking/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/a3df7c2e60ee90d149a0/test_coverage)](https://codeclimate.com/github/riotkit-org/reverse-networking/test_coverage)\n[![Build Status](https://travis-ci.org/riotkit-org/reverse-networking.svg?branch=master)](https://travis-ci.org/riotkit-org/reverse-networking)\n\nNetwork setup automation and supervising. Provides monitoring, health checking, validating the connection with custom Python methods.\nReplaces old, slow maintained `autossh`.\n\n**Super-elastic, allows for dynamic IP resolving on local and remote using Python callback functions. It means you can achieve totally everything.**\n\nAllows to create multiple tunnels from inside of NAT to the external server, and vice-versa.\n\nWorks in at least those cases:\n- #1: Can expose a NAT hidden service to the external server (or to the internet via external server)\n- #2: Can encrypt a connection with external server by adding SSH layer (eg. MySQL replication with external server with SSH encryption layer)\n- #3: Can expose local hidden service to the remote server\n- #4: Can forward remote services hidden in docker containers (eg. connecting to some_ssh_1 and forwarding some_db_1:3306 to localhost from remote)\n\n**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.\nNothing matters, it should work when you go back online!\n\n![screenshot](./docs/screenshot.png \"TunMan web gui screenshot\")\n\n![example structure](./docs/Reverse%20networking%20infrastructure.png \"Reverse networking structure\")\n\n*Note: The project was renamed from \"reverse-networking\" into TunMan from 3.0.0 release*\n\n## Requirements\n\nThose very basic packages needs to be installed:\n- Bash\n- Pipenv\n- Python 3.5+\n- autossh (optional, can be used additionally, not recommended)\n- sshpass (if you use passwords)\n- docker (optional, if you want to run TunMan in a docker container)\n\nDevelopment packages for development:\n- tox\n- unittest-data-provider\n\nWorks with GNU utils as well as with Busybox.\nTested on Arch Linux, Debian and Alpine Linux.\n\n*The preferred way of  authorization with remote is key based authorization*\n\n## Installing\n\nYou may want to use **docker** or baremetal installation.\n\n#### Baremetal installation\n\n```bash\ngit clone git@github.com:riotkit-org/reverse-networking.git -b v3.1.0-rc2 # change \"v3.1.0-rc2\" to some version\ncd reverse-networking\n\nsudo ./setup.py install\n```\n\n#### Installing from PIP\n\n```bash\nsudo pip3 install tunman\n```\n\n## Setup\n\nPut your configuration files into `conf.d` of a directory you specified as configuration directory (-c or --config param, /conf.d docker volume)\nPlease check out the [example/scenario-*](./example) directories for example configuration directories.\n\n```\n1. File must be written in Python syntax\n2. You can import any library you have in system or in docker container, including \"paramiko\" and \"subprocess\"\n3. You can use any shell commands available in the shell ex. mysql or psql in the configuration callbacks\n```\n\nSend public key to all servers described in your configuration\nso the communication could be without a password using a ssh key.\n\nConfigure and start:\n\n```bash\n# you can use command-line switches ex. \"--config\" or environment variables\nexport TUNMAN_CONFIG=\"path-to-config-directory\"   # -c / --config\nexport TUNMAN_SECRET_PREFIX=\"\"                    # -s / --secret-prefix\nexport TUNMAN_ENV=\"prod\"                          # -e / --env\n\ntunman add-to-known-hosts\ntunman send-public-key\ntunman start\n```\n\nThat's all!\nYour local services should be exposed to the remote server and be\nvisible on eg. http://localhost:1234, so you need an internal proxy or\na load balancer like nginx to forward the traffic to the internet.\n\n## Health checking and status monitoring\n\nHealth check:\n\n```bash\ncurl http://localhost:8015/health\n```\n\nHTML status page: `http://localhost:8015/`\n\n*Notice: The URL can be prefixed with (-s/--secret-prefix/TUNMAN_SECRET_PREFIX) ex. http://localhost/some-secret-prefix/health*\n\n## Using with Docker\n\n**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**\n\nPlease check out a list of available tags there: https://quay.io/repository/riotkit/reverse-networking?tab=tags\n\n```\nversion: \"2\"\nservices:\n    proxy:\n        image: quay.io/riotkit/reverse-networking:latest-dev-x86_64\n        volumes:\n            - \"./configuration:/config:ro\"   # see example directory structure in \"example/scenario-*\" directories\n            - \"./id_rsa:/id_rsa:ro\"          # a place for your private key, you may pick other one and point to it in the configuration\n            - \"./id_rsa.pub:/id_rsa.pub:ro\"\n        environment:\n            - TUNMAN_SECRET_PREFIX=\n            - TUNMAN_ENV=prod\n```\n\n### Docker container configuration reference\n\nList of all environment variables that could be used.\n\n```yaml\n\n- TUNMAN_CONFIG # (default: /config)\n\n# Environment, options: dev, prod\n- TUNMAN_ENV # (default: prod)\n\n# Secret prefix in the URL ex. https://your-app.org/super-hiper-secret-here/health\n- TUNMAN_SECRET_PREFIX # (default: )\n\n\n```\n\n## Example configuration\n\nPlease check the [example](./example) directory for examples.\n\n#### Variables table\n\nOften you do not know on which IP address is the docker container, or interface listening. TunMan allows to retrieve\ndynamic values using variables.\n\nYou can use variables instead of ex. host name\n\n| Variable  \t| Description  \t|\n|---\t|---\t|\n| \\{\\{ remote_gw }}  \t| IP address of ssh destination host |\n| \\{\\{ remote_interface_gw }} \t| IP address of a interface that is a default gateway in route table on remote SSH \t|\n| \\{\\{ remote_docker_host }} \t| Autodetected docker host IP address (local bridge) \t|\n| \\{\\{ remote_docker_container }} | If SSH server is containerized, then it will point to a IP address of a container |\n| \\{\\{ remote_interface_eth0 }} | eth0 interface ip address |\n| \\{\\{ remote_interface_eth1 }} | eth1 interface ip address |\n| \\{\\{ remote_interface_eth2 }} | eth2 interface ip address |\n\n## FAQ\n\n1. Cannot connect to SSH, invalid key or unsupported key type\n\n```\nparamiko.ssh_exception.SSHException: Invalid key\nparamiko.ssh_exception.SSHException: not a valid OPENSSH private key file\n```\n\n[It is a common problem in Paramiko library, that we use.](https://stackoverflow.com/questions/47286032/paramiko-throwing-invalid-key-in-unpad)\nGenerate the key using a different format, examples:\n```\nssh-keygen -t ed25519 -b 4096\n```\n\n## More documentation\n\nSee here: [docs/pages](./docs/pages)\n\n### Configuration reference\n\nFor list of all possible options to use in configuration file please check example configuration file.\n\nHere: [example/reference.py](./example/reference.py)\n\n## Developing\n\n- The docker container is built on quay.io and hub.docker com\n- When you start working on it locally, at first run `make dev@develop` to install git hooks\n- README.md is automatically generated from README.md.j2, do not edit the generated version!\n- Use `make` for building, pushing, etc.\n\n## Project Keywords\n\ntunneling, ssh tunnel restart, autossh, sshpass, autorestart tunnel, ssh proxy, expose service behind nat,\nrevproxy, how to tunnel mysql, tunnel manager, tunnel supervisor, tunnel monitoring, ssh monitoring, ssh automation,\nssh setup automation, access service behind nat, nginx through ssh\n\nCopyleft\n--------\n\nCreated by [**RiotKit Collective**](https://riotkit.org), a libertarian, grassroot, non-profit organization providing technical support for the non-profit Anarchist movement.\n\nCheck out those nice non-profit initiatives we are friends with:\n- International Workers Association (https://iwa-ait.org)\n- Anarchistyczne FAQ (http://anarchizm.info)\n- Federacja Anarchistyczna (http://federacja-anarchistyczna.pl)\n- Związek Syndykalistów Polski (https://zsp.net.pl) (Polish section of IWA-AIT)\n- Komitet Obrony Praw Lokatorów (https://lokatorzy.info.pl)\n- Solidarity Federation (https://solfed.org.uk)\n- Priama Akcia (https://priamaakcia.sk)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friotkit-org%2Ftunman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friotkit-org%2Ftunman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friotkit-org%2Ftunman/lists"}