ssh-tunnel-swarm is a powerful shell script tool for managing multiple SSH tunnels concurrently. It simplifies the process of creating and managing both forward and reverse SSH tunnels by applying a predefined set of rules for each tunnel.
The script supports the configuration of multiple SSH connections and can establish tunnels based on defined rules.
- Allows multiple SSH connections with each connection potentially handling multiple tunnels.
- Logging functionality for better visibility and debugging.
- Easily configurable rule sets for the creation of SSH tunnels.
- Supports both forward and reverse SSH tunnels.
- Tunnels are continuously maintained and re-established in case of disconnection.
This script is designed to be run in a Unix-like environment.
- bash: The script is written in
bash, so you need to havebashinstalled on your system. - ssh: The script uses
sshto establish connections and create tunnels. Make sure you havesshinstalled and properly configured on your machine.
- jq: This lightweight and flexible command-line JSON processor is used by the downloader tool to parse data fetched from GitHub. Specifically, it helps identify the most recent version of ssh-tunnel-swarm.
- wget: wget is a versatile utility designed for non-interactive downloading of files from the web. It serves a dual purpose in this case - initially downloading the downloader tool, and subsequently employed by the downloader tool itself to retrieve ssh-tunnel-swarm.
Execute the following command to download ssh-tunnel-swarm:
wget -qO- https://raw.githubusercontent.com/psyb0t/ssh-tunnel-swarm/master/tools/downloader.sh | bashAfter the download is complete, you can use ssh-tunnel-swarm from the current location by executing ./ssh-tunnel-swarm but a true installation allows you to use it from any directory.
sudo mv ssh-tunnel-swarm /usr/local/bin/mkdir -p ~/bin
mv ssh-tunnel-swarm ~/bin/In order to execute ssh-tunnel-swarm from any directory, the $HOME/bin directory needs to be added to your system's $PATH. This is because the $PATH variable tells the system which directories to search for executable files when you type a command in the terminal. By adding $HOME/bin to the $PATH, you can run the ssh-tunnel-swarm command from any directory without needing to specify the full path.
To check if $HOME/bin is already in the $PATH, you can execute the following command in your terminal:
echo $PATH | grep -q "$HOME/bin" && echo "The $HOME/bin directory is already in your PATH" || echo "The $HOME/bin directory is not in your PATH yet"This command will output a message indicating whether $HOME/bin is already in your path.
If it is not, add it to your shell profile file:
For bash:
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcFor zsh:
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc-
RULES_FILE: This can be used to specify the path to the file containing the tunnel rules. If this variable is not set, the default file path is set to
rules.txt. -
LOG_ENABLED: This acts as a master switch for the logger. If it's set to
1, logging is enabled. A value of0disables logging. Default value if not set is1. -
LOG_FILE: This determines the output destination of the log messages. If set, log messages will be written to the specified file. If not set, logs will be printed to stdout.
-
LOG_LEVEL: This determines the severity level of the messages to be logged. Messages with a severity level less than this will not be logged. For example, if
LOG_LEVELis set toINFO, thenDEBUGmessages won't be logged. Default value if not set isINFO.
The logger recognizes four levels of logging:
-
DEBUG: These are verbose-level messages and are usually useful during development or debugging sessions. They provide deep insights about what's going on.
-
INFO: These messages provide general feedback about the application processes and state. They are used to confirm that things are working as expected.
-
ERROR: These are messages that indicate a problem that prevented a function or process from completing successfully.
-
FATAL: These messages indicate a severe problem that has caused the application to stop. They require immediate attention.
ssh-tunnel-swarm reads the tunnel rules for each host from a file specified by the RULES_FILE environment variable. Each entry within the file should include the username, hostname, port, SSH private key and the tunnels to establish. For instance:
aparker@host789:34567=/home/aparker/.ssh/id_rsa
reverse host789.example.com:5432:172.16.0.5:5432
sjones@host012:67890=/path/to/ssh/private/key
reverse host012.example.com:3000:10.20.30.40:3000
forward 172.20.0.2:6060:host012.example.com:4444
reverse 10.0.0.5:5678:host789.example.com:1234
forward host789.example.com:9876:172.16.0.5:4321
Each block represents an SSH connection where:
-
The first line is the username, host, port to connect to and the private SSH key to use. The syntax is:
user@hostname:port=/path/to/private/ssh/key -
The following lines are the SSH tunnels to establish for that connection, with one tunnel per line. The syntax is:
direction local-interface:local-port:remote-interface:remote-port
Set up a reverse tunnel from your local machine to a VPS having SSH listening on port 22
user@myvps.com:22=/path/to/ssh/private/key
reverse localhost:8080:0.0.0.0:80
Now when you access http://myvps.com/ you'll access your local service.
Set up a reverse tunnel from your local machine to 2 VPSs having SSH listening on port 22
user@myvps.com:22=/path/to/ssh/private/key
reverse localhost:8080:0.0.0.0:80
user@myothervps.com:22=/path/to/ssh/private/key
reverse localhost:8080:0.0.0.0:80
Now when you access both http://myvps.com/ and http://myothervps.com/ you'll access your local service.
Set up a forward tunnel from a remote machine to your computer
user@enterprise.com:22=/path/to/ssh/private/key
forward localhost:6366:10.137.82.201:636
Now guess what happens when you try to connect to localhost:6366.
RULES_FILE=/path/to/rules.txt \
LOG_ENABLED=1 \
LOG_FILE=/path/to/log/file \
LOG_LEVEL=DEBUG \
ssh-tunnel-swarm-
ssh-tunnel-swarm does not handle SSH password authentication.
-
Always use this script responsibly make sure you have the required permissions on your local and remote systems to establish SSH connections and tunnels.
-
All SSH connections are established with
-o StrictHostKeyChecking=yes. -
With
StrictHostKeyChecking=yes, the client will refuse to connect to servers whose host key is not known or has changed since it was last recorded. This may lead to initial connection failure if the host key is not already in the known_hosts file.It is your responsibility to ensure that the
known_hostsfile is up to date with the public keys of the remote hosts you wish to connect to. You can manually add a host's public key to yourknown_hostsfile, or you can retrieve it using SSH on a trusted network before running ssh-tunnel-swarm.Note that in some cases, you might have to manually remove outdated or changed host keys from your
known_hostsfile. This situation can arise if you're connecting to a server that has had its SSH keys regenerated.
This software is licensed under the terms of the Do What The Fuck You Want To Public License (WTFPL). This license allows you to use the software for any purposes, without any conditions or restrictions unless such restrictions are required by law. You can learn more about the license at http://www.wtfpl.net/about/.
By using this software, you agree to abide by the terms of the WTFPL. If you do not agree, please do not use, modify, or distribute the software.
- refactor
- better error handling
- better testing utils