{"id":23219334,"url":"https://github.com/markelca/ssh-tunnels","last_synced_at":"2025-09-05T23:44:16.940Z","repository":{"id":191910893,"uuid":"685641818","full_name":"MarkelCA/ssh-tunnels","owner":"MarkelCA","description":"A bash cli tool to manage ssh tunnels from a yaml configuration","archived":false,"fork":false,"pushed_at":"2024-04-21T17:23:37.000Z","size":67,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-11T11:52:24.073Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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/MarkelCA.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-31T17:19:24.000Z","updated_at":"2024-04-21T17:22:40.000Z","dependencies_parsed_at":"2023-09-01T13:35:35.142Z","dependency_job_id":"fdf3d454-5ed3-41a8-afbd-7ff21fd074a4","html_url":"https://github.com/MarkelCA/ssh-tunnels","commit_stats":null,"previous_names":["markelca/ssh-tunnels"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkelCA%2Fssh-tunnels","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkelCA%2Fssh-tunnels/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkelCA%2Fssh-tunnels/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkelCA%2Fssh-tunnels/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarkelCA","download_url":"https://codeload.github.com/MarkelCA/ssh-tunnels/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353747,"owners_count":20925329,"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":[],"created_at":"2024-12-18T21:31:37.972Z","updated_at":"2025-04-05T15:11:28.286Z","avatar_url":"https://github.com/MarkelCA.png","language":"Shell","readme":"# What is this script for?\nOne 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.\n\n```\n    ----------------------------------------------------------------------\n\n                                |\n    -------------+              |    +------------+\n        LOCAL    |              |    |  REMOTE    | :22 SSH\n        CLIENT   | \u003c== SSH ========\u003e |  DATABASE  | :3306 database\n    -------------+              |    +------------+\n                                |\n                             FIREWALL (only port 22 is open)\n\n    ----------------------------------------------------------------------\n```\n**Fig1**: How to connect to a service blocked by a firewall through SSH tunnel.\n\nIf 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). \n```\n\n    ----------------------------------------------------------------------\n\n                                |\n    -------------+              |    +----------+               +-----------+\n        LOCAL    |              |    |  REMOTE  | :22 SSH       | PRIVATE   |\n        CLIENT   | \u003c== SSH ========\u003e |  SERVER  | \u003c== local ==\u003e | DATABASE  | :3306 database\n    -------------+              |    +----------+               +-----------+\n                                |\n                             FIREWALL (only port 22 is open)\n\n    ----------------------------------------------------------------------\n```\n**Fig2**: How to connect to ``PRIVATE DATABASE`` through SSH tunnel.\n\n*Credits on this section to [pahaz/sshtunnel](https://github.com/pahaz/sshtunnel)*\n# Installation\n## Dependencies\n- [yq](https://github.com/mikefarah/yq) (YAML Query)\n- [openssh](https://www.openssh.com): The `ssh` command (Should be available in most Linux distributions).\n\n## Install\n```bash\nsudo wget https://github.com/MarkelCA/ssh-tunnels/releases/download/latest/ssht -O /usr/bin/ssht \\\n    \u0026\u0026 sudo chmod +x /usr/bin/ssht\n```\n\n# Configuration\nThe default configuration file is read from `~/.config/ssht/ssht.yml`. However, you can specify other files using the `-f` flag for every command.\n\nTo create your configuration copy the example yaml:\n```bash\nmkdir -p ~/.config/ssht/\ncp ./ssht.example.yml ~/.config/ssht/ssht.yml\n```\nNow modify the file to add your own tunnel configurations.\n\n## Example\nLet's break down the example from `ssht.example.yml`.\n\n```yml\ntunnels:\n  remote_database:\n    host_destination: 127.0.0.1\n    port_destination: 3306\n    port_forward: 3333\n    host_server: remote-server.com\n    user_server: myuser\n    ssh_key_path:  ~/.ssh/remote_server_key\n\n  private_database:\n    host_destination: private-database.com\n    port_destination: 3306\n    port_forward: 3335\n    host_server: remote-server.com\n    user_server: myuser\n    # (missing ssh_key_path) -\u003e In this case it will pick the ssh key from the ~/.ssh/config file\n```\n\nThis 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`.\n\nIf you're familiar with the openssh's tunnel management the params from the yaml file will be transformed to this command:\n`ssh -N -L \u003cport_forward\u003e:\u003chost_destination\u003e:\u003cport_destination\u003e \u003cuser_server\u003e@\u003chost_server\u003e -f -i \u003cssh_key_path\u003e`\n\nExamples:\n`ssh -N -L 3333:127.0.0.1:3306 myuser@remote-server.com -f -i ~/.ssh/remote_server_key`\n`ssh -N -L 3335:private-database.com:3306 myuser@remote-server.com -f`\n\nIf 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.\n\n\n\n# Run\nYou can type the help command to learn the usage.\n```\n➜  ~ ssht help\nManages SSH tunnels from a YAML configuration.\n\nUsage:\nssht \u003ccommand\u003e [-f|--file \u003cfile\u003e]\n\nCommands:\n    - open [query]    Opens ssh tunnels\n    - close [query]   Closes ssh tunnels\n    - status [query]  Tells if a tunnel is opened or closed.\n    - show [query]    Shows an ssht.yml configuration\n    - list            Lists the available tunnels in the configuration\n    - help [command]  Shows the help description for a command\n\nOptions:\n    - -f|--file   The configuration file. Default if none is\n                  provided: ~/.config/ssht/ssht.yml\n\nHelp with specific command:\nssht help \u003ccommand\u003e\n\nExample:\nssht help open\nssht help help\n\nFor more info visit: https://github.com/markelca/ssh-tunnels#example\n```\n## Examples\nThese are some of the most usual commands you'll run with this script:\n```bash\nssht open remote_database\nssht open remote_database -f ./other-ssht-config.yml # Passing another config file\nssht open \".*_database\" # Allows regex expressions too\nssht close \".*_database\" # Same for closing\n```\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkelca%2Fssh-tunnels","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkelca%2Fssh-tunnels","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkelca%2Fssh-tunnels/lists"}