class Net::SSH::Service::Forward

ssh.forward.local(1234, “www.capify.org”, 80)
returned by Connection::Session#forward:
directly; instead, it should be accessed via the singleton instance
Net::SSH clients. The Forward class should never need to be instantiated
This class implements various port forwarding services for use by

def active_local_sockets

is an array of Unix domain socket file paths.
Returns a list of all active locally forwarded sockets. The returned value
def active_local_sockets
  @local_forwarded_sockets.keys
end

def active_locals

forwarding port.
consisting of the local port and bind address corresponding to the
is an array of arrays, where each element is a two-element tuple
Returns a list of all active locally forwarded ports. The returned value
def active_locals
  @local_forwarded_ports.keys
end

def active_remote_destinations

to [, ].
returned value is a hash from [, ]
Returns all active remote forwarded ports and where they forward to. The
def active_remote_destinations
  @remote_forwarded_ports.each_with_object({}) do |(remote, local), result|
    result[[local.port, local.host]] = remote
  end
end

def active_remotes

remote host and the second is the bind address.
array of two-element tuples, where the first element is the port on the
Returns all active forwarded remote ports. The returned value is an
def active_remotes
  @remote_forwarded_ports.keys
end

def agent(channel)

end
ssh.loop
end
# agent will be automatically forwarded by this point
ssh.open_channel do |ch|
Net::SSH.start("remote.host", "me", :forward_agent => true) do |ssh|

:forward_agent set to true:
time a session channel is opened, when the connection was created with
never need to call this directly--it is called automatically the first
used as the transport for enabling the forwarded connection. You should
will remain active even after the channel closes--the channel is only
Enables SSH agent forwarding on the given channel. The forwarded agent
def agent(channel)
  return if @agent_forwarded
  @agent_forwarded = true
  channel.send_channel_request("auth-agent-req@openssh.com") do |achannel, success|
    if success
      debug { "authentication agent forwarding is active" }
    else
      achannel.send_channel_request("auth-agent-req") do |a2channel, success2|
        if success2
          debug { "authentication agent forwarding is active" }
        else
          error { "could not establish forwarding of authentication agent" }
        end
      end
    end
  end
end

def auth_agent_channel(session, channel, packet)

The callback used when an auth-agent channel is requested by the server.
def auth_agent_channel(session, channel, packet)
  info { "opening auth-agent channel" }
  channel[:invisible] = true
  begin
    agent = Authentication::Agent.connect(logger, session.options[:agent_socket_factory])
    if (agent.socket.is_a? ::IO)
      prepare_client(agent.socket, channel, :agent)
    else
      prepare_simple_client(agent.socket, channel, :agent)
    end
  rescue Exception => e
    error { "attempted to connect to agent but failed: #{e.class.name} (#{e.message})" }
    raise Net::SSH::ChannelOpenFailed.new(2, "could not connect to authentication agent")
  end
end

def cancel_local(port, bind_address = "127.0.0.1")

ssh.forward.cancel_local(1234, "0.0.0.0")
ssh.forward.cancel_local(1234)

Terminates an active local forwarded port.
def cancel_local(port, bind_address = "127.0.0.1")
  socket = @local_forwarded_ports.delete([port, bind_address])
  socket.shutdown rescue nil
  socket.close rescue nil
  session.stop_listening_to(socket)
end

def cancel_local_socket(local_socket_path)

ssh.forward.cancel_local_socket('/tmp/foo.sock')

Terminates an active local forwarded socket.
def cancel_local_socket(local_socket_path)
  socket = @local_forwarded_sockets.delete(local_socket_path)
  socket.shutdown rescue nil
  socket.close rescue nil
  session.stop_listening_to(socket)
end

def cancel_remote(port, host = "127.0.0.1")

ssh.loop { ssh.forward.active_remotes.include?([1234, "0.0.0.0"]) }
ssh.forward.cancel_remote(1234, "0.0.0.0")

the port is no longer active, you could do something like this:
longer be present in the #active_remotes list. If you want to block until
If you want to know when the connection has been cancelled, it will no

the port cannot be cancelled, an exception will be raised (asynchronously).
after queueing the request to be sent to the server. If for some reason
will be terminated, but not immediately. This method returns immediately
port on the remote host, bound to the given address on the remote host,
Requests that a remote forwarded port be cancelled. The remote forwarded
def cancel_remote(port, host = "127.0.0.1")
  session.send_global_request("cancel-tcpip-forward", :string, host, :long, port) do |success, response|
    if success
      @remote_forwarded_ports.delete([port, host])
    else
      raise Net::SSH::Exception, "could not cancel remote forward request on #{host}:#{port}"
    end
  end
end

def forwarded_tcpip(session, channel, packet)

when the forwarded connection was first requested.
by the server. This will open a new socket to the host/port specified
The callback used when a new "forwarded-tcpip" channel is requested
def forwarded_tcpip(session, channel, packet)
  connected_address  = packet.read_string
  connected_port     = packet.read_long
  originator_address = packet.read_string
  originator_port    = packet.read_long
  puts "REMOTE 0: #{connected_port} #{connected_address} #{originator_address} #{originator_port}"
  remote = @remote_forwarded_ports[[connected_port, connected_address]]
  if remote.nil?
    raise Net::SSH::ChannelOpenFailed.new(1, "unknown request from remote forwarded connection on #{connected_address}:#{connected_port}")
  end
  puts "REMOTE: #{remote.host} #{remote.port}"
  client = TCPSocket.new(remote.host, remote.port)
  info { "connected #{connected_address}:#{connected_port} originator #{originator_address}:#{originator_port}" }
  prepare_client(client, channel, :remote)
rescue SocketError => err
  raise Net::SSH::ChannelOpenFailed.new(2, "could not connect to remote host (#{remote.host}:#{remote.port}): #{err.message}")
end

def initialize(session)

the specialized channels that the SSH port forwarding protocols employ.
service session. This will register new channel open handlers to handle
Instantiates a new Forward service instance atop the given connection
def initialize(session)
  @session = session
  self.logger = session.logger
  @remote_forwarded_ports = {}
  @local_forwarded_ports = {}
  @agent_forwarded = false
  @local_forwarded_sockets = {}
  session.on_open_channel('forwarded-tcpip', &method(:forwarded_tcpip))
  session.on_open_channel('auth-agent', &method(:auth_agent_channel))
  session.on_open_channel('auth-agent@openssh.com', &method(:auth_agent_channel))
end

def local(*args)

assigned_port = ssh.forward.local("0.0.0.0", 0, "www.capify.org", 80)
ssh.forward.local(1234, "www.capify.org", 80)

has been assigned.
the port number. In all cases, this method will return the port that
To request an ephemeral port on the remote server, provide 0 (zero) for

"127.0.0.1", and the rest are applied as above.
If three arguments are given, it is as if the local bind address is

* the port on the remote host to connect to
* the remote host to forward connections to
* the local port to listen on
* the local address to bind to

they are:
accepts either three or four arguments. When four arguments are given,
to the specified remote host/port via the SSH connection. This method
Starts listening for connections on the local host, and forwards them
def local(*args)
  if args.length < 3 || args.length > 4
    raise ArgumentError, "expected 3 or 4 parameters, got #{args.length}"
  end
  local_port_type = :long
  socket = begin
    if defined?(UNIXServer) and args.first.class == UNIXServer
      local_port_type = :string
      args.shift
    else
      bind_address = "127.0.0.1"
      bind_address = args.shift if args.first.is_a?(String) && args.first =~ /\D/
      local_port = args.shift.to_i
      local_port_type = :long
      TCPServer.new(bind_address, local_port)
    end
  end
  local_port = socket.addr[1] if local_port == 0 # ephemeral port was requested
  remote_host = args.shift
  remote_port = args.shift.to_i
  @local_forwarded_ports[[local_port, bind_address]] = socket
  session.listen_to(socket) do |server|
    client = server.accept
    debug { "received connection on #{socket}" }
    channel = session.open_channel("direct-tcpip", :string, remote_host, :long,
                                   remote_port, :string, bind_address, local_port_type, local_port) do |achannel|
      achannel.info { "direct channel established" }
    end
    prepare_client(client, channel, :local)
    channel.on_open_failed do |ch, code, description|
      channel.error { "could not establish direct channel: #{description} (#{code})" }
      session.stop_listening_to(channel[:socket])
      channel[:socket].close
    end
  end
  local_port
end

def local_socket(local_socket_path, remote_socket_path)

ssh.forward.local_socket('/tmp/local.sock', '/tmp/remote.sock')

socket file already available.
(re)create the local socket file. The remote server needs to have the
to the specified remote socket via the SSH connection. This will
Starts listening for connections on the local host, and forwards them
def local_socket(local_socket_path, remote_socket_path)
  File.delete(local_socket_path) if File.exist?(local_socket_path)
  socket = Socket.unix_server_socket(local_socket_path)
  @local_forwarded_sockets[local_socket_path] = socket
  session.listen_to(socket) do |server|
    client = server.accept[0]
    debug { "received connection on #{socket}" }
    channel = session.open_channel("direct-streamlocal@openssh.com",
                                   :string, remote_socket_path,
                                   :string, nil,
                                   :long, 0) do |achannel|
      achannel.info { "direct channel established" }
    end
    prepare_client(client, channel, :local)
    channel.on_open_failed do |ch, code, description|
      channel.error { "could not establish direct channel: #{description} (#{code})" }
      session.stop_listening_to(channel[:socket])
      channel[:socket].close
    end
  end
  local_socket_path
end

def prepare_client(client, channel, type)

and +type+ is an arbitrary string describing the type of the channel.
+client+ is a socket, +channel+ is the channel that was just created,
Perform setup operations that are common to all forwarded channels.
def prepare_client(client, channel, type)
  client.extend(Net::SSH::BufferedIo)
  client.extend(Net::SSH::ForwardedBufferedIo)
  client.logger = logger
  session.listen_to(client)
  channel[:socket] = client
  channel.on_data do |ch, data|
    debug { "data:#{data.length} on #{type} forwarded channel" }
    ch[:socket].enqueue(data)
  end
  channel.on_eof do |ch|
    debug { "eof #{type} on #{type} forwarded channel" }
    begin
      ch[:socket].send_pending
      ch[:socket].shutdown Socket::SHUT_WR
    rescue IOError => e
      if e.message =~ /closed/ then
        debug { "epipe in on_eof => shallowing exception:#{e}" }
      else
        raise
      end
    rescue Errno::EPIPE => e
      debug { "epipe in on_eof => shallowing exception:#{e}" }
    rescue Errno::ENOTCONN => e
      debug { "enotconn in on_eof => shallowing exception:#{e}" }
    end
  end
  channel.on_close do |ch|
    debug { "closing #{type} forwarded channel" }
    ch[:socket].close if !client.closed?
    session.stop_listening_to(ch[:socket])
  end
  channel.on_process do |ch|
    if ch[:socket].closed?
      ch.info { "#{type} forwarded connection closed" }
      ch.close
    elsif ch[:socket].available > 0
      data = ch[:socket].read_available(8192)
      ch.debug { "read #{data.length} bytes from client, sending over #{type} forwarded connection" }
      ch.send_data(data)
    end
  end
end

def prepare_simple_client(client, channel, type)

not a real socket, so use a simpler behaviour
def prepare_simple_client(client, channel, type)
  channel[:socket] = client
  channel.on_data do |ch, data|
    ch.debug { "data:#{data.length} on #{type} forwarded channel" }
    ch[:socket].send(data)
  end
  channel.on_process do |ch|
    data = ch[:socket].read(8192)
    if data
      ch.debug { "read #{data.length} bytes from client, sending over #{type} forwarded connection" }
      ch.send_data(data)
    end
  end
end

def remote(port, host, remote_port, remote_host = "127.0.0.1")


end
raise Net::SSH::Exception, "remote forwarding request failed"
if got_remote_port == :error
session.loop { !got_remote_port }
end
:no_exception # will yield the exception on my own thread
got_remote_port = actual_remote_port || :error
remote(port, host, remote_port, remote_host) do |actual_remote_port|
got_remote_port = nil

like this:
If you want to block until the port is active, you could do something

returns :no_exception, the "failed binding" exception will not be thrown.
that was actually bound to, or nil if the binding failed. If the block
request receives a response. This block will be passed the remote_port
You may pass a block that will be called when the the port forward

interfaces for IPv4 and IPv6, respectively.
- "127.0.0.1" and "::1" indicate listening on the loopback
[RFC3513]).
the SSH implementation on loopback addresses only ([RFC3330] and
- "localhost" means to listen on all protocol families supported by
- "::" means to listen on all IPv6 addresses.
- "0.0.0.0" means to listen on all IPv4 addresses.
families supported by the SSH implementation.
- "" means that connections are to be accepted on all protocol

special values:
remote_host is interpreted by the server per RFC 4254, which has these

list.
the port number. The assigned port will show up in the # #active_remotes
To request an ephemeral port on the remote server, provide 0 (zero) for

listener for this request, an exception will be raised asynchronously.
forwarded immediately. If the remote server is not able to begin the
This method will return immediately, but the port will not actually be

bind address on the remote host, and defaults to 127.0.0.1.
the local host to the given port/host. The last argument describes the
Requests that all connections on the given remote-port be forwarded via
def remote(port, host, remote_port, remote_host = "127.0.0.1")
  session.send_global_request("tcpip-forward", :string, remote_host, :long, remote_port) do |success, response|
    if success
      remote_port = response.read_long if remote_port == 0
      debug { "remote forward from remote #{remote_host}:#{remote_port} to #{host}:#{port} established" }
      @remote_forwarded_ports[[remote_port, remote_host]] = Remote.new(host, port)
      yield remote_port, remote_host if block_given?
    else
      instruction = if block_given?
                      yield :error
                    end
      unless instruction == :no_exception
        error { "remote forwarding request failed" }
        raise Net::SSH::Exception, "remote forwarding request failed"
      end
    end
  end
end