SSHTunnel v0.1.3 SSHTunnel View Source

Module for creating SSH tunnels using :ssh.

It provides functions to create forwarded ssh channels, similair to how other channels can be created using :ssh_connection.

There are two type of channels supported

directtcp-ip - Forwards a port from the client machine to the remote machine. This is the same as ssh -nNT -L 8080:forward.example.com:9000 user@sshserver.example.com
direct-streamlocal - Forwards to a unix domain socket. This is the same as ssh -nNT -L 8080:/var/lib/mysql/mysql.sock user@sshserver.example.com

When using direct_tcpip/3 or stream_local_forward/2 directly there will not be any local port or socket bound, this can either be done using SSHTunnel.Tunnel or by manually sending data with :ssh_connection.send/3

Although connect/1 can be used to connect to the remote host, other methods are supported. One can use SSHex, :ssh.connect/3 for instance.

Tunnels

Tunnels are on-demand TCP servers and are bound listeners to either a port or a path. The tunnel will handle relaying TCP messages to the ssh connection and back.

Examples

{:ok, ssh_ref} = SSHTunnel.connect(host: "sshserver.example.com", user: "user", password: "password")
{:ok, pid} = SSHTunnel.start_tunnel(pid, {:tcpip, {8080, {"192.168.90.15", 80}}})
# Send a TCP message for instance HTTP
%HTTPoison.Response{body: body} = HTTPoison.get!("127.0.0.1:8080")
IO.puts("Received body: #{body})

Link to this section Summary

Functions

connect(opts \\ [])

Create a connetion to a remote host with the provided options. This function is mostly used as convenience wrapper around :ssh_connect/3 and does not support all options

direct_tcpip(pid, from, to)

Creates a ssh directtcp-ip forwarded channel to a remote port. The returned channel together with a ssh connection reference (returned from :ssh.connect/4) can be used to send messages with :ssh_connection.send/3

start_tunnel(pid, to)

Starts a SSHTunnel.Tunnel process, the tunnel will listen to either a local port or local path and handle passing messages between the TCP client and ssh connection

stream_local_forward(pid, socket_path)

Creates a ssh stream local-forward channel to a remote unix domain socket

Link to this section Types

location()

location() :: {String.t(), integer()}

Link to this section Functions

connect(opts \\ [])

connect(Keyword.t()) :: {:ok, pid()} | {:error, term()}

Create a connetion to a remote host with the provided options. This function is mostly used as convenience wrapper around :ssh_connect/3 and does not support all options.

returns: {:ok, connection} or {:error, reason}.

direct_tcpip(pid, from, to)

direct_tcpip(pid(), location(), location()) ::
  {:ok, integer()} | {:error, term()}

returns: {:ok, channel} or {:error, reason}.

Examples:

msg = "GET / HTTP/1.1\r\nHost: localhost:8080\r\nUser-Agent: curl/7.47.0\r\nAccept: */*\r\n\r\n"

{:ok, pid} = SSHTunnel.connect(host: "192.168.1.10", user: "user", password: "password")
{:ok, ch} = SSHTunnel.direct_tcpip(pid, {"127.0.0.1", 8080}, {"192.168.1.10", 80})
:ok = :ssh_connection.send(pid, ch, msg)
recieve do
  {:ssh_cm, _, {:data, channel, _, data}} -> IO.puts("Data: #{(data)}")
end

start_tunnel(pid, to)

start_tunnel(pid(), SSHTunnel.Tunnel.to()) :: {:ok, pid()} | {:error, term()}

Starts a SSHTunnel.Tunnel process, the tunnel will listen to either a local port or local path and handle passing messages between the TCP client and ssh connection.

Examples

{:ok, ssh_ref} = SSHTunnel.connect(host: "sshserver.example.com", user: "user", password: "password")
{:ok, pid} = SSHTunnel.start_tunnel(pid, {:tcpip, {8080, {"192.168.90.15", 80}}})
# Send a TCP message
%HTTPoison.Response{body: body} = HTTPoison.get!("127.0.0.1:8080")
IO.puts("Received body: #{body})

stream_local_forward(pid, socket_path)

stream_local_forward(pid(), String.t()) :: {:ok, integer()} | {:error, term()}

Creates a ssh stream local-forward channel to a remote unix domain socket.

The returned channel together with a ssh connection reference (returned from :ssh.connect/4) can be used to send messages with :ssh_connection.send/3.

returns: {:ok, channel} or {:error, reason}.

Ex:

msg = "GET /images/json HTTP/1.1\r\nHost: /var/run/docker.sock\r\nAccept: */*\r\n\r\n"

{:ok, pid} = SSHTunnel.connect(host: "192.168.90.15", user: "user", password: "password")
{:ok, ch} = SSHTunnel.stream_local_forward(pid, "/var/run/docker.sock")
:ok = :ssh_connection.send(pid, ch, msg)