Skip to content

Commit

Permalink
support user-defined ssh private keys for hosts
Browse files Browse the repository at this point in the history
  • Loading branch information
@psyb0t
psyb0t committed Jun 14, 2023
1 parent a882427 commit 2600141
Show file tree
Hide file tree
Showing 9 changed files with 216 additions and 212 deletions.
3 changes: 3 additions & 0 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,8 @@ build:
clean:
@rm -rf build

run:
@bash main.sh

test:
@./test.sh
201 changes: 55 additions & 146 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,27 @@
# SSH Tunnel Swarm
# ssh-tunnel-swarm

![ssh-tunnel-swarm](https://raw.githubusercontent.com/psyb0t/ssh-tunnel-swarm/master/assets/ssh-tunnel-swarm.png)

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

## Table of Contents

- [SSH Tunnel Swarm](#ssh-tunnel-swarm)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Installing for the current user](#installing-for-the-current-user)
- [Installing for all users](#installing-for-all-users)
- [Configuration](#configuration)
- [Environment Variables](#environment-variables)
- [Tunnel Rules](#tunnel-rules)
- [Usage](#usage)
- [Logging](#logging)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Installing for all users](#installing-for-all-users)
- [Installing for the current user](#installing-for-the-current-user)
- [Configuration](#configuration)
- [Environment Variables](#environment-variables)
- [Supported Log Levels](#supported-log-levels)
- [Important Notes](#important-notes)
- [Contributing](#contributing)
- [License](#license)
- [TODO](#todo)
- [Glossary](#glossary)
- [Tunnel Rules](#tunnel-rules)
- [Example](#example)
- [Usage](#usage)
- [Important Notes](#important-notes)
- [License](#license)
- [TODO](#todo)

## Features

Expand All @@ -45,76 +42,24 @@ This script is designed to be run in a Unix-like environment.

## Installation

To install `ssh-tunnel-swarm`, the first step is to check if `wget` is installed on your system by running `wget --version`.
Execute the following command to download `ssh-tunnel-swarm`:

If it is installed, the output should be similar to this:

```
GNU Wget 1.21.2 built on linux-gnu.
-cares +digest -gpgme +https +ipv6 +iri +large-file -metalink +nls
+ntlm +opie +psl +ssl/openssl
Wgetrc:
/etc/wgetrc (system)
Locale:
/usr/share/locale
Compile:
gcc -DHAVE_CONFIG_H -DSYSTEM_WGETRC="/etc/wgetrc"
-DLOCALEDIR="/usr/share/locale" -I. -I../../src -I../lib
-I../../lib -Wdate-time -D_FORTIFY_SOURCE=2 -DHAVE_LIBSSL -DNDEBUG
-g -O2 -ffile-prefix-map=/build/wget-8g5eYO/wget-1.21.2=.
-flto=auto -ffat-lto-objects -flto=auto -ffat-lto-objects
-fstack-protector-strong -Wformat -Werror=format-security
-DNO_SSLv2 -D_FILE_OFFSET_BITS=64 -g -Wall
Link:
gcc -DHAVE_LIBSSL -DNDEBUG -g -O2
-ffile-prefix-map=/build/wget-8g5eYO/wget-1.21.2=. -flto=auto
-ffat-lto-objects -flto=auto -ffat-lto-objects
-fstack-protector-strong -Wformat -Werror=format-security
-DNO_SSLv2 -D_FILE_OFFSET_BITS=64 -g -Wall -Wl,-Bsymbolic-functions
-flto=auto -ffat-lto-objects -flto=auto -Wl,-z,relro -Wl,-z,now
-lpcre2-8 -luuid -lidn2 -lssl -lcrypto -lz -lpsl ftp-opie.o
openssl.o http-ntlm.o ../lib/libgnu.a
Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later
<http://www.gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Originally written by Hrvoje Niksic <hniksic@xemacs.org>.
Please send bug reports and questions to <bug-wget@gnu.org>.
```shell
wget -qO- https://raw.githubusercontent.com/psyb0t/ssh-tunnel-swarm/master/tools/downloader.sh | bash
```

If `wget` is not installed, you can easily install it using the package manager for your operating system. Here are the installation commands for some known operating systems:

- Debian/Ubuntu-based systems: `sudo apt-get install wget`
- Arch Linux-based systems: `sudo pacman -S wget`
- Fedora-based systems: `sudo dnf install wget`
- CentOS/RHEL-based systems: `sudo yum install wget`
- openSUSE-based systems: `sudo zypper install wget`
- Alpine Linux-based systems: `sudo apk add wget`
- FreeBSD-based systems: `sudo pkg install wget`
- NetBSD-based systems: `sudo pkgin install wget`
- OpenBSD-based systems: `sudo pkg_add wget`
- macOS with Homebrew installed: `brew install wget`
- Tiny Core Linux: `tce-load -wi wget`

If your operating system is not listed above, you can visit the `wget` website at https://www.gnu.org/software/wget/ and download it from there.
After 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.

Once `wget` is installed, execute the following command to download `ssh-tunnel-swarm`:
### Installing for all users

```shell
wget -qO- https://raw.githubusercontent.com/psyb0t/ssh-tunnel-swarm/master/tools/downloader.sh | bash
sudo mv ssh-tunnel-swarm /usr/bin/
```

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

### Installing for the current user

```shell
mkdir ~/bin
mkdir -p ~/bin
mv ssh-tunnel-swarm ~/bin/
```

Expand All @@ -128,7 +73,7 @@ echo $PATH | grep -q "$HOME/bin" && echo "The $HOME/bin directory is already in

This command will output a message indicating whether `$HOME/bin` is already in your path.

If it is not, execute the following command for either `bash` or `zsh`:
If it is not, add it to your shell profile file:

For `bash`:

Expand All @@ -144,12 +89,6 @@ echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

## Installing for all users

```shell
sudo mv ssh-tunnel-swarm /usr/bin/
```

## Configuration

### Environment Variables
Expand All @@ -160,17 +99,29 @@ sudo mv ssh-tunnel-swarm /usr/bin/

- **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_LEVEL` is set to `INFO`, then `DEBUG` messages won't be logged. Default value if not set is `DEBUG`. You can find all of the [supported log levels here](#supported-log-levels).
- **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_LEVEL` is set to `INFO`, then `DEBUG` messages won't be logged. Default value if not set is `INFO`.

#### Supported Log Levels

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.

### Tunnel Rules

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, and the tunnels to establish. For instance:
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
aparker@host789:34567=/home/aparker/.ssh/id_rsa
reverse host789.example.com:5432:172.16.0.5:5432
sjones@host012:67890
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
Expand All @@ -179,7 +130,9 @@ forward host789.example.com:9876:172.16.0.5:4321

Each block represents an SSH connection where:

- The first line is the username, host, and port to connect to.
- 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`

Expand All @@ -188,7 +141,7 @@ Each block represents an SSH connection where:
**Set up a reverse tunnel from your local machine to a VPS having SSH listening on port 22**

```
user@myvps.com:22
user@myvps.com:22=/path/to/ssh/private/key
reverse localhost:8080:0.0.0.0:80
```

Expand All @@ -197,10 +150,10 @@ 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
user@myvps.com:22=/path/to/ssh/private/key
reverse localhost:8080:0.0.0.0:80
user@myothervps.com:22
user@myothervps.com:22=/path/to/ssh/private/key
reverse localhost:8080:0.0.0.0:80
```

Expand All @@ -209,7 +162,7 @@ Now when you access both http://myvps.com/ and http://myothervps.com/ you'll acc
**Set up a forward tunnel from a remote machine to your computer**

```
user@enterprise.com:22
user@enterprise.com:22=/path/to/ssh/private/key
forward localhost:6366:10.137.82.201:636
```

Expand All @@ -225,49 +178,19 @@ LOG_LEVEL=DEBUG \
ssh-tunnel-swarm
```

## Logging

SSH Tunnel Swarm includes a logging functionality that provides visibility into the operations and state of your SSH connections.

It is designed to enable configurable log levels and output destinations and provides different levels of logging based on the severity of the log message. This is particularly useful in complex scripts or systems where detailed logging is beneficial for development, debugging, or ongoing system maintenance.

### Supported Log Levels

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.

## Important Notes

- SSH Tunnel Swarm does not handle SSH authentication(yet). Please ensure that the necessary SSH key is available(currently only the default one is used).
- ssh-tunnel-swarm does not handle SSH password authentication.

- Make sure you have the required permissions on your local and remote systems to establish SSH connections and tunnels.
- 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=no for convenience. However, this option may expose you to potential security risks.
- All SSH connections are established with `-o StrictHostKeyChecking=yes`.

- Always use this script responsibly and ensure you have the permissions to establish tunnels with your target hosts.

## Contributing

I welcome your contributions. Please submit a pull request with your improvements. Make sure to adhere to the existing coding style and ensure all tests pass before submitting your PR.

### Clone the repository:

```shell
git clone https://github.com/psyb0t/ssh-tunnel-swarm.git
cd ssh-tunnel-swarm
make test
```
- 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.

If all tests run you're ready do go
It is your responsibility to ensure that the `known_hosts` file 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 your `known_hosts` file, or you can retrieve it using SSH on a trusted network before running ssh-tunnel-swarm.

To execute the script in development you can either just run `bash main.sh` or execute `make build` and run the compiled script `./build/ssh-tunnel-swarm`
Note that in some cases, you might have to manually remove outdated or changed host keys from your `known_hosts` file. This situation can arise if you're connecting to a server that has had its SSH keys regenerated.

## License

Expand All @@ -277,20 +200,6 @@ By using this software, you agree to abide by the terms of the **WTFPL**. If you

## TODO

- add support for specifying keys for each host
- add more tests

## Glossary

- **SSH**: Secure Shell is a protocol used to securely connect to a remote server/system.
- **Tunnel**: In the context of SSH, a tunnel is a route through which the entirety of your data is going to pass.
- **Forward Tunnel (Local Port Forwarding)**: Forwarding calls for a specific IP and port from the client system to an IP and port on the server system.
- **Reverse Tunnel (Remote Port Forwarding)**: Allows the server to receive a connection as a client from the client system.
- **SSH Key**: A way of logging into an SSH/SFTP account using a cryptographic pair of keys, hence providing an alternative way to password-based logins.
- **Bash**: A shell, or command language interpreter, for the GNU operating system.
- **Shell Script**: A computer program designed to be run by the Unix shell, a command-line interpreter.
- **wget**: A free utility for non-interactive download of files from the web. It supports HTTP, HTTPS, and FTP protocols and can retrieve files through HTTP proxies.
- **PATH**: An environment variable on Unix-like operating systems, DOS, OS/2, and Microsoft Windows, specifying a set of directories where executable programs are located.
- **$HOME**: An environment variable that displays the path of the home directory of the current user.
- **WTFPL**: Do What The Fuck You Want To Public License, a very permissive license for software and other scientific or artistic works that offers a huge degree of freedom.
- **GNU**: Stands for GNU's Not Unix, an extensive collection of free software, which includes the GNU Project, the GNU Operating System, and the GNU General Public License.
- refactor
- better error handling
- better testing utils
28 changes: 15 additions & 13 deletions common_test.sh
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
#!/bin/bash
# Function to print a failure message
print_failure() {
local message="$1"
local expected="$2"
local actual="$3"
local is_error_check="$4"
local function_name="$1"
local message="$2"
local expected="$3"
local actual="$4"
local is_error_check="$5"

local check_type
if [[ "$is_error_check" -eq 1 ]]; then
Expand All @@ -13,15 +14,16 @@ print_failure() {
check_type="Equality check"
fi

echo "FAIL - Test failed: $message. $check_type. Expected '$expected', but got '$actual'"
echo "FAIL - ${function_name}: assert failed: $message. $check_type. Expected '$expected', but got '$actual'"
exit 1
}

# Function to print a success message
print_success() {
local message="$1"
local function_name="$1"
local message="$2"

echo "OK - Test passed: $message"
echo "OK - ${function_name}: assert passed: $message"
}

# Assert function to check if actual and expected values are the same
Expand All @@ -31,9 +33,9 @@ assert_equals() {
local message="$3"

if [[ "$actual" == "$expected" ]]; then
print_success "$message"
print_success "${FUNCNAME[0]}" "$message"
else
print_failure "$message" "$expected" "$actual" 0
print_failure "${FUNCNAME[0]}" "$message" "$expected" "$actual" 0
fi
}

Expand All @@ -44,9 +46,9 @@ assert_is_error() {
local message="$3"

if [[ "$actual" -eq "$expected" ]]; then
print_success "$message"
print_success "${FUNCNAME[0]}" "$message"
else
print_failure "$message" "$expected" "$actual" 1
print_failure "${FUNCNAME[0]}" "$message" "$expected" "$actual" 1
fi
}

Expand All @@ -56,8 +58,8 @@ assert_no_error() {
local message="$2"

if [[ "$actual" -eq 0 ]]; then
print_success "$message"
print_success "${FUNCNAME[0]}" "$message"
else
print_failure "$message" "no error" "$actual" 1
print_failure "${FUNCNAME[0]}" "$message" "no error" "$actual" 1
fi
}
4 changes: 2 additions & 2 deletions logger.sh
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/bin/bash
# Set default log level to DEBUG if it's not already set
: "${LOG_LEVEL:=DEBUG}"
# Set default log level to INFO if it's not already set
: "${LOG_LEVEL:=INFO}"
# Set default log enabled flag only if it's not been set before
: "${LOG_ENABLED:=1}"
# Set default log file if it's not already set
Expand Down
Loading

0 comments on commit 2600141

Please sign in to comment.