Github — mole is maintained by davrodpin.
Mole is a cli application to create ssh tunnels, forwarding a local port to a remote address through a ssh server.
<span class="nv">$ </span>mole <span class="nt">-remote</span> :3306 <span class="nt">-server</span> my-database-server
INFO[0000] listening on <span class="nb">local </span>address <span class="nv">local_address</span><span class="o">=</span><span class="s2">"127.0.0.1:51082"</span>
Highlighted Features
- Auto local address selection: find a port available and start listening to it, so the
-local
flag doesn’t need to be given every time you run the app.
- Aliases: save your tunnel settings under an alias, so it can be reused later.
- Leverage the SSH Config File: use some options (e.g. user name, identity key and port), specified in $HOME/.ssh/config whenever possible, so there is no need to have the same SSH server configuration in multiple places.
Table of Contents
- Use Cases
- Installation
- Usage
- Examples
- Provide all supported options
- Use the ssh config file to lookup a given server host
- Let mole to randomly select the local endpoint
- Connect to a remote service that is running on 127.0.0.1 by specifying only the remote port
- Create an alias, so there is no need to remember the tunnel settings afterwards
Use Cases
…or why on Earth would I need something like this?
Access a computer or service behind a firewall
Mole can help you to access computers and services outside the perimeter network that are blocked by a firewall, as long as the user has ssh access to a computer with access to the target computer or service.
+----------+ +----------+ +----------+
| | | | | |
| | | Firewall | | |
| | | | | |
| Local | tunnel +----------+ tunnel | |
| Computer |--------------------------------| Server |
| | +----------+ | |
| | | | | |
| | | Firewall | | |
| | | | | |
+----------+ +----------+ +----------+
|
|
| tunnel
|
|
+----------+
| |
| |
| |
| |
| Remote |
| Computer |
| |
| |
| |
+----------+
NOTE: Server and Remote Computer could potentially be the same machine.
Access a service that is listening only on a local address
<span class="nv">$ </span>mole <span class="se">\</span>
<span class="nt">-local</span> 127.0.0.1:3306 <span class="se">\</span>
<span class="nt">-remote</span> 127.0.0.1:3306 <span class="se">\</span>
<span class="nt">-server</span> example@172.17.0.100
+-------------------+ +--------------------+
| Local Computer | | Remote / Server |
| | | |
| | | |
| (172.17.0.10: | tunnel | |
| 50001) |-------------| (172.17.0.100:22) |
| tunnel client | | tunnel server |
| | | | | |
| | port | | | port |
| | forward | | | forward |
| | | | | |
| (127.0.0.1:3306) | | (127.0.0.1:50000) |
| local address | | | |
| | | | local |
| | | | conn. |
| | | | |
| | | (127.0.0.1:3306) |
| | | remote address |
| | | +----+ |
| | | | DB | |
| | | +----+ |
+-------------------+ +--------------------+
NOTE: Server and Remote Computer could potentially be the same machine.
Installation
bash <<span class="o">(</span>curl <span class="nt">-fsSL</span> https://raw.githubusercontent.com/davrodpin/mole/master/tools/install.sh<span class="o">)</span>
or if you prefer install it through Homebrew
brew tap davrodpin/homebrew-mole <span class="o">&&</span> brew install mole
Usage
<span class="nv">$ </span>mole <span class="nt">-help</span>
usage:
mole <span class="o">[</span><span class="nt">-v</span><span class="o">]</span> <span class="o">[</span><span class="nt">-local</span> <span class="o">[</span><host>]:<port>] <span class="nt">-remote</span> <span class="o">[</span><host>]:<port> <span class="nt">-server</span> <span class="o">[</span><user>@]<host>[:<port>] <span class="o">[</span><span class="nt">-key</span> <key_path>]
mole <span class="nt">-alias</span> <alias_name> <span class="o">[</span><span class="nt">-v</span><span class="o">]</span> <span class="o">[</span><span class="nt">-local</span> <span class="o">[</span><host>]:<port>] <span class="nt">-remote</span> <span class="o">[</span><host>]:<port> <span class="nt">-server</span> <span class="o">[</span><user>@]<host>[:<port>] <span class="o">[</span><span class="nt">-key</span> <key_path>]
mole <span class="nt">-alias</span> <alias_name> <span class="nt">-delete</span>
mole <span class="nt">-start</span> <alias_name>
mole <span class="nt">-aliases</span>
mole <span class="nt">-help</span>
mole <span class="nt">-version</span>
<span class="nt">-alias</span> string
Create a tunnel <span class="nb">alias</span>
<span class="nt">-aliases</span>
list all aliases
<span class="nt">-delete</span>
delete a tunnel <span class="nb">alias</span> <span class="o">(</span>must be used with <span class="nt">-alias</span><span class="o">)</span>
<span class="nt">-help</span>
list all options available
<span class="nt">-key</span> string
<span class="o">(</span>optional<span class="o">)</span> Set server authentication key file path
<span class="nt">-local</span> value
<span class="o">(</span>optional<span class="o">)</span> Set <span class="nb">local </span>endpoint address: <span class="o">[</span><host>]:<port>
<span class="nt">-remote</span> value
<span class="nb">set </span>remote endpoint address: <span class="o">[</span><host>]:<port>
<span class="nt">-server</span> value
<span class="nb">set </span>server address: <span class="o">[</span><user>@]<host>[:<port>]
<span class="nt">-start</span> string
Start a tunnel using a given <span class="nb">alias</span>
<span class="nt">-v</span> <span class="o">(</span>optional<span class="o">)</span> Increase log verbosity
<span class="nt">-version</span>
display the mole version
Examples
Provide all supported options
<span class="nv">$ </span>mole <span class="nt">-v</span> <span class="nt">-local</span> 127.0.0.1:8080 <span class="nt">-remote</span> 172.17.0.100:80 <span class="nt">-server</span> user@example.com:22 <span class="nt">-key</span> ~/.ssh/id_rsa
DEBU[0000] cli options <span class="nv">key</span><span class="o">=</span>/home/mole/.ssh/id_rsa <span class="nb">local</span><span class="o">=</span><span class="s2">"127.0.0.1:8080"</span> <span class="nv">remote</span><span class="o">=</span><span class="s2">"172.17.0.100:80"</span> <span class="nv">server</span><span class="o">=</span><span class="s2">"user@example.com:22"</span> <span class="nv">v</span><span class="o">=</span><span class="nb">true
</span>DEBU[0000] using ssh config file from: /home/mole/.ssh/config
DEBU[0000] server: <span class="o">[</span><span class="nv">name</span><span class="o">=</span>example.com, <span class="nv">address</span><span class="o">=</span>example.com:22, <span class="nv">user</span><span class="o">=</span>user, <span class="nv">key</span><span class="o">=</span>/home/mole/.ssh/id_rsa]
DEBU[0000] tunnel: <span class="o">[</span><span class="nb">local</span>:127.0.0.1:8080, server:example.com:22, remote:172.17.0.100:80]
INFO[0000] listening on <span class="nb">local </span>address <span class="nv">local_address</span><span class="o">=</span><span class="s2">"127.0.0.1:8080"</span>
Use the ssh config file to lookup a given server host
<span class="nv">$ </span><span class="nb">cat</span> <span class="nv">$HOME</span>/.ssh/config
Host example1
Hostname 10.0.0.12
Port 2222
User user
IdentityFile ~/.ssh/id_rsa
<span class="nv">$ </span>mole <span class="nt">-v</span> <span class="nt">-local</span> 127.0.0.1:8080 <span class="nt">-remote</span> 172.17.0.100:80 <span class="nt">-server</span> example1
DEBU[0000] cli options <span class="nv">key</span><span class="o">=</span> <span class="nb">local</span><span class="o">=</span><span class="s2">"127.0.0.1:8080"</span> <span class="nv">remote</span><span class="o">=</span><span class="s2">"172.17.0.100:80"</span> <span class="nv">server</span><span class="o">=</span>example1 <span class="nv">v</span><span class="o">=</span><span class="nb">true
</span>DEBU[0000] using ssh config file from: /home/mole/.ssh/config
DEBU[0000] server: <span class="o">[</span><span class="nv">name</span><span class="o">=</span>example1, <span class="nv">address</span><span class="o">=</span>10.0.0.12:2222, <span class="nv">user</span><span class="o">=</span>user, <span class="nv">key</span><span class="o">=</span>/home/mole/.ssh/id_rsa]
DEBU[0000] tunnel: <span class="o">[</span><span class="nb">local</span>:127.0.0.1:8080, server:10.0.0.12:2222, remote:172.17.0.100:80]
INFO[0000] listening on <span class="nb">local </span>address <span class="nv">local_address</span><span class="o">=</span><span class="s2">"127.0.0.1:8080"</span>
Let mole to randomly select the local endpoint
<span class="nv">$ </span>mole <span class="nt">-remote</span> 172.17.0.100:80 <span class="nt">-server</span> example1
INFO[0000] listening on <span class="nb">local </span>address <span class="nv">local_address</span><span class="o">=</span><span class="s2">"127.0.0.1:61305"</span>
Bind the local address to 127.0.0.1 by specifying only the local port
<span class="nv">$ </span>mole <span class="nt">-v</span> <span class="nt">-local</span> :8080 <span class="nt">-remote</span> 172.17.0.100:80 <span class="nt">-server</span> example1
DEBU[0000] cli options <span class="nv">key</span><span class="o">=</span> <span class="nb">local</span><span class="o">=</span><span class="s2">"127.0.0.1:8080"</span> <span class="nv">remote</span><span class="o">=</span><span class="s2">"172.17.0.100:80"</span> <span class="nv">server</span><span class="o">=</span>example1 <span class="nv">v</span><span class="o">=</span><span class="nb">true
</span>DEBU[0000] using ssh config file from: /home/mole/.ssh/config
DEBU[0000] server: <span class="o">[</span><span class="nv">name</span><span class="o">=</span>example1, <span class="nv">address</span><span class="o">=</span>10.0.0.12:2222, <span class="nv">user</span><span class="o">=</span>user, <span class="nv">key</span><span class="o">=</span>/home/mole/.ssh/id_rsa]
DEBU[0000] tunnel: <span class="o">[</span><span class="nb">local</span>:127.0.0.1:8080, server:10.0.0.12:2222, remote:172.17.0.100:80]
INFO[0000] listening on <span class="nb">local </span>address <span class="nv">local_address</span><span class="o">=</span><span class="s2">"127.0.0.1:8080"</span>
Connect to a remote service that is running on 127.0.0.1 by specifying only the remote port
<span class="nv">$ </span>mole <span class="nt">-v</span> <span class="nt">-local</span> 127.0.0.1:8080 <span class="nt">-remote</span> :80 <span class="nt">-server</span> example1
DEBU[0000] cli options <span class="nv">key</span><span class="o">=</span> <span class="nb">local</span><span class="o">=</span><span class="s2">"127.0.0.1:8080"</span> <span class="nv">remote</span><span class="o">=</span><span class="s2">"127.0.0.1:80"</span> <span class="nv">server</span><span class="o">=</span>example1 <span class="nv">v</span><span class="o">=</span><span class="nb">true
</span>DEBU[0000] using ssh config file from: /home/mole/.ssh/config
DEBU[0000] server: <span class="o">[</span><span class="nv">name</span><span class="o">=</span>example1, <span class="nv">address</span><span class="o">=</span>10.0.0.12:2222, <span class="nv">user</span><span class="o">=</span>user, <span class="nv">key</span><span class="o">=</span>/home/mole/.ssh/id_rsa]
DEBU[0000] tunnel: <span class="o">[</span><span class="nb">local</span>:127.0.0.1:8080, server:10.0.0.12:2222, remote:127.0.0.1:80]
INFO[0000] listening on <span class="nb">local </span>address <span class="nv">local_address</span><span class="o">=</span><span class="s2">"127.0.0.1:8080"</span>
Create an alias, so there is no need to remember the tunnel settings afterwards
<span class="nv">$ </span>mole <span class="nt">-alias</span> example1 <span class="nt">-v</span> <span class="nt">-local</span> :8443 <span class="nt">-remote</span> :443 <span class="nt">-server</span> user@example.com
<span class="nv">$ </span>mole <span class="nt">-start</span> example1
DEBU[0000] cli options <span class="nv">options</span><span class="o">=</span><span class="s2">"[local=:8443, remote=:443, server=user@example.com, key=, verbose=true, help=false, version=false]"</span>
DEBU[0000] using ssh config file from: /home/mole/.ssh/config
DEBU[0000] server: <span class="o">[</span><span class="nv">name</span><span class="o">=</span>example.com, <span class="nv">address</span><span class="o">=</span>example.com:22, <span class="nv">user</span><span class="o">=</span>user, <span class="nv">key</span><span class="o">=</span>/home/mole/.ssh/id_rsa]
DEBU[0000] tunnel: <span class="o">[</span><span class="nb">local</span>:127.0.0.1:8443, server:example.com:22, remote:127.0.0.1:443]
INFO[0000] listening on <span class="nb">local </span>address <span class="nv">local_address</span><span class="o">=</span><span class="s2">"127.0.0.1:8443"</span>