https://github.com/markelca/ssh-tunnels
A bash cli tool to manage ssh tunnels from a yaml configuration
https://github.com/markelca/ssh-tunnels
Last synced: about 1 month ago
JSON representation
A bash cli tool to manage ssh tunnels from a yaml configuration
- Host: GitHub
- URL: https://github.com/markelca/ssh-tunnels
- Owner: MarkelCA
- Created: 2023-08-31T17:19:24.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-04-21T17:23:37.000Z (about 1 year ago)
- Last Synced: 2025-02-11T11:52:24.073Z (3 months ago)
- Language: Shell
- Homepage:
- Size: 65.4 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# What is this script for?
One of the typical scenarios where ``ssht`` is helpful is depicted in the figure below. User may need to connect a port of a remote database (i.e. 3306) where only SSH port (usually port 22) is reachable.
```
----------------------------------------------------------------------
|
-------------+ | +------------+
LOCAL | | | REMOTE | :22 SSH
CLIENT | <== SSH ========> | DATABASE | :3306 database
-------------+ | +------------+
|
FIREWALL (only port 22 is open)
----------------------------------------------------------------------
```
**Fig1**: How to connect to a service blocked by a firewall through SSH tunnel.
If allowed by the SSH server, it is also possible to reach a private database (from the perspective of ``REMOTE SERVER``) not directly visible from the outside (``LOCAL CLIENT``'s perspective).
```
----------------------------------------------------------------------
|
-------------+ | +----------+ +-----------+
LOCAL | | | REMOTE | :22 SSH | PRIVATE |
CLIENT | <== SSH ========> | SERVER | <== local ==> | DATABASE | :3306 database
-------------+ | +----------+ +-----------+
|
FIREWALL (only port 22 is open)
----------------------------------------------------------------------
```
**Fig2**: How to connect to ``PRIVATE DATABASE`` through SSH tunnel.
*Credits on this section to [pahaz/sshtunnel](https://github.com/pahaz/sshtunnel)*
# Installation
## Dependencies
- [yq](https://github.com/mikefarah/yq) (YAML Query)
- [openssh](https://www.openssh.com): The `ssh` command (Should be available in most Linux distributions).
## Install
```bash
sudo wget https://github.com/MarkelCA/ssh-tunnels/releases/download/latest/ssht -O /usr/bin/ssht \
&& sudo chmod +x /usr/bin/ssht
```
# Configuration
The default configuration file is read from `~/.config/ssht/ssht.yml`. However, you can specify other files using the `-f` flag for every command.
To create your configuration copy the example yaml:
```bash
mkdir -p ~/.config/ssht/
cp ./ssht.example.yml ~/.config/ssht/ssht.yml
```
Now modify the file to add your own tunnel configurations.
## Example
Let's break down the example from `ssht.example.yml`.
```yml
tunnels:
remote_database:
host_destination: 127.0.0.1
port_destination: 3306
port_forward: 3333
host_server: remote-server.com
user_server: myuser
ssh_key_path: ~/.ssh/remote_server_key
private_database:
host_destination: private-database.com
port_destination: 3306
port_forward: 3335
host_server: remote-server.com
user_server: myuser
# (missing ssh_key_path) -> In this case it will pick the ssh key from the ~/.ssh/config file
```
This example config file complements the [first section's explanation](https://github.com/MarkelCA/ssh-tunnels/tree/master#what-is-this-script-for). The `remote_database` would represent the first picture, where the `host_destination` and the `host_server` is the same, while the `private_database` example does likewise with the second picture, where the database lies in the same network but not the same machine as the `host_server`.
If you're familiar with the openssh's tunnel management the params from the yaml file will be transformed to this command:
`ssh -N -L :: @ -f -i `
Examples:
`ssh -N -L 3333:127.0.0.1:3306 [email protected] -f -i ~/.ssh/remote_server_key`
`ssh -N -L 3335:private-database.com:3306 [email protected] -f`
If no `ssh_key_path` if provided the `ssh`'s command `-f` option will be ommited and the command will be tried with the default key specified at the `~/.ssh/config` file.
# Run
You can type the help command to learn the usage.
```
➜ ~ ssht help
Manages SSH tunnels from a YAML configuration.
Usage:
ssht [-f|--file ]
Commands:
- open [query] Opens ssh tunnels
- close [query] Closes ssh tunnels
- status [query] Tells if a tunnel is opened or closed.
- show [query] Shows an ssht.yml configuration
- list Lists the available tunnels in the configuration
- help [command] Shows the help description for a command
Options:
- -f|--file The configuration file. Default if none is
provided: ~/.config/ssht/ssht.yml
Help with specific command:
ssht help
Example:
ssht help open
ssht help help
For more info visit: https://github.com/markelca/ssh-tunnels#example
```
## Examples
These are some of the most usual commands you'll run with this script:
```bash
ssht open remote_database
ssht open remote_database -f ./other-ssht-config.yml # Passing another config file
ssht open ".*_database" # Allows regex expressions too
ssht close ".*_database" # Same for closing
```