Parent

Included Modules

Class Index [+]

Quicksearch

Net::SSH::Service::Forward

This class implements various port forwarding services for use by Net::SSH clients. The Forward class should never need to be instantiated directly; instead, it should be accessed via the singleton instance returned by Connection::Session#forward:

  ssh.forward.local(1234, "www.capify.org", 80)

Attributes

session[R]

The underlying connection service instance that the port-forwarding services employ.

Public Class Methods

new(session) click to toggle source

Instantiates a new Forward service instance atop the given connection service session. This will register new channel open handlers to handle the specialized channels that the SSH port forwarding protocols employ.

    # File lib/net/ssh/service/forward.rb, line 25
25:     def initialize(session)
26:       @session = session
27:       self.logger = session.logger
28:       @remote_forwarded_ports = {}
29:       @local_forwarded_ports = {}
30:       @agent_forwarded = false
31: 
32:       session.on_open_channel('forwarded-tcpip', &method(:forwarded_tcpip))
33:       session.on_open_channel('auth-agent', &method(:auth_agent_channel))
34:       session.on_open_channel('auth-agent@openssh.com', &method(:auth_agent_channel))
35:     end

Public Instance Methods

active_locals() click to toggle source

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

     # File lib/net/ssh/service/forward.rb, line 111
111:     def active_locals
112:       @local_forwarded_ports.keys
113:     end
active_remotes() click to toggle source

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

     # File lib/net/ssh/service/forward.rb, line 169
169:     def active_remotes
170:       @remote_forwarded_ports.keys
171:     end
agent(channel) click to toggle source

Enables SSH agent forwarding on the given channel. The forwarded agent will remain active even after the channel closes—the channel is only used as the transport for enabling the forwarded connection. You should never need to call this directly—it is called automatically the first time a session channel is opened, when the connection was created with :forward_agent set to true:

   Net::SSH.start("remote.host", "me", :forwrd_agent => true) do |ssh|
     ssh.open_channel do |ch|
       # agent will be automatically forwarded by this point
     end
     ssh.loop
   end
     # File lib/net/ssh/service/forward.rb, line 186
186:     def agent(channel)
187:       return if @agent_forwarded
188:       @agent_forwarded = true
189: 
190:       channel.send_channel_request("auth-agent-req@openssh.com") do |achannel, success|
191:         if success
192:           debug { "authentication agent forwarding is active" }
193:         else
194:           achannel.send_channel_request("auth-agent-req") do |a2channel, success2|
195:             if success2
196:               debug { "authentication agent forwarding is active" }
197:             else
198:               error { "could not establish forwarding of authentication agent" }
199:             end
200:           end
201:         end
202:       end
203:     end
cancel_local(port, bind_address="127.0.0.1") click to toggle source

Terminates an active local forwarded port. If no such forwarded port exists, this will raise an exception. Otherwise, the forwarded connection is terminated.

  ssh.forward.cancel_local(1234)
  ssh.forward.cancel_local(1234, "0.0.0.0")
     # File lib/net/ssh/service/forward.rb, line 100
100:     def cancel_local(port, bind_address="127.0.0.1")
101:       socket = @local_forwarded_ports.delete([port, bind_address])
102:       socket.shutdown rescue nil
103:       socket.close rescue nil
104:       session.stop_listening_to(socket)
105:     end
cancel_remote(port, host="127.0.0.1") click to toggle source

Requests that a remote forwarded port be cancelled. The remote forwarded port on the remote host, bound to the given address on the remote host, will be terminated, but not immediately. This method returns immediately after queueing the request to be sent to the server. If for some reason the port cannot be cancelled, an exception will be raised (asynchronously).

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

  ssh.forward.cancel_remote(1234, "0.0.0.0")
  ssh.loop { ssh.forward.active_remotes.include?([1234, "0.0.0.0"]) }
     # File lib/net/ssh/service/forward.rb, line 156
156:     def cancel_remote(port, host="127.0.0.1")
157:       session.send_global_request("cancel-tcpip-forward", :string, host, :long, port) do |success, response|
158:         if success
159:           @remote_forwarded_ports.delete([port, host])
160:         else
161:           raise Net::SSH::Exception, "could not cancel remote forward request on #{host}:#{port}"
162:         end
163:       end
164:     end
local(*args) click to toggle source

Starts listening for connections on the local host, and forwards them to the specified remote host/port via the SSH connection. This method accepts either three or four arguments. When four arguments are given, they are:

  • the local address to bind to

  • the local port to listen on

  • the remote host to forward connections to

  • the port on the remote host to connect to

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

  ssh.forward.local(1234, "www.capify.org", 80)
  ssh.forward.local("0.0.0.0", 1234, "www.capify.org", 80)
    # File lib/net/ssh/service/forward.rb, line 52
52:     def local(*args)
53:       if args.length < 3 || args.length > 4
54:         raise ArgumentError, "expected 3 or 4 parameters, got #{args.length}"
55:       end
56: 
57:       local_port_type = :long
58: 
59:       socket = begin
60:         if args.first.class == UNIXServer
61:           local_port_type = :string
62:           args.shift
63:         else
64:           bind_address = "127.0.0.1"
65:           bind_address = args.shift if args.first.is_a?(String) && args.first =~ /\D/
66:           local_port = args.shift.to_i
67:           local_port_type = :long
68:           TCPServer.new(bind_address, local_port)
69:         end
70:       end
71: 
72:       remote_host = args.shift
73:       remote_port = args.shift.to_i
74: 
75:       @local_forwarded_ports[[local_port, bind_address]] = socket
76: 
77:       session.listen_to(socket) do |server|
78:         client = server.accept
79:         debug { "received connection on #{socket}" }
80: 
81:         channel = session.open_channel("direct-tcpip", :string, remote_host, :long, remote_port, :string, bind_address, local_port_type, local_port) do |achannel|
82:           achannel.info { "direct channel established" }
83:         end
84: 
85:         prepare_client(client, channel, :local)
86:   
87:         channel.on_open_failed do |ch, code, description|
88:           channel.error { "could not establish direct channel: #{description} (#{code})" }
89:           channel[:socket].close
90:         end
91:       end
92:     end
remote(port, host, remote_port, remote_host="127.0.0.1") click to toggle source

Requests that all connections on the given remote-port be forwarded via the local host to the given port/host. The last argument describes the bind address on the remote host, and defaults to 127.0.0.1.

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

If you want to know when the connection is active, it will show up in the # list. If you want to block until the port is active, you could do something like this:

  ssh.forward.remote(80, "www.google.com", 1234, "0.0.0.0")
  ssh.loop { !ssh.forward.active_remotes.include?([1234, "0.0.0.0"]) }
     # File lib/net/ssh/service/forward.rb, line 129
129:     def remote(port, host, remote_port, remote_host="127.0.0.1")
130:       session.send_global_request("tcpip-forward", :string, remote_host, :long, remote_port) do |success, response|
131:         if success
132:           debug { "remote forward from remote #{remote_host}:#{remote_port} to #{host}:#{port} established" }
133:           @remote_forwarded_ports[[remote_port, remote_host]] = Remote.new(host, port)
134:         else
135:           error { "remote forwarding request failed" }
136:           raise Net::SSH::Exception, "remote forwarding request failed"
137:         end
138:       end
139:     end
Also aliased as: remote_to
remote_to(port, host, remote_port, remote_host="127.0.0.1") click to toggle source

an alias, for token backwards compatibility with the 1.x API

Alias for: remote

Private Instance Methods

auth_agent_channel(session, channel, packet) click to toggle source

The callback used when an auth-agent channel is requested by the server.

     # File lib/net/ssh/service/forward.rb, line 284
284:       def auth_agent_channel(session, channel, packet)
285:         info { "opening auth-agent channel" }
286:         channel[:invisible] = true
287: 
288:         begin
289:           agent = Authentication::Agent.connect(logger)
290:           prepare_client(agent.socket, channel, :agent)
291:         rescue Exception => e
292:           error { "attempted to connect to agent but failed: #{e.class.name} (#{e.message})" }
293:           raise Net::SSH::ChannelOpenFailed.new(2, "could not connect to authentication agent")
294:         end
295:       end
forwarded_tcpip(session, channel, packet) click to toggle source

The callback used when a new “forwarded-tcpip” channel is requested by the server. This will open a new socket to the host/port specified when the forwarded connection was first requested.

     # File lib/net/ssh/service/forward.rb, line 263
263:       def forwarded_tcpip(session, channel, packet)
264:         connected_address  = packet.read_string
265:         connected_port     = packet.read_long
266:         originator_address = packet.read_string
267:         originator_port    = packet.read_long
268: 
269:         remote = @remote_forwarded_ports[[connected_port, connected_address]]
270: 
271:         if remote.nil?
272:           raise Net::SSH::ChannelOpenFailed.new(1, "unknown request from remote forwarded connection on #{connected_address}:#{connected_port}")
273:         end
274: 
275:         client = TCPSocket.new(remote.host, remote.port)
276:         info { "connected #{connected_address}:#{connected_port} originator #{originator_address}:#{originator_port}" }
277: 
278:         prepare_client(client, channel, :remote)
279:       rescue SocketError => err
280:         raise Net::SSH::ChannelOpenFailed.new(2, "could not connect to remote host (#{remote.host}:#{remote.port}): #{err.message}")
281:       end
prepare_client(client, channel, type) click to toggle source

Perform setup operations that are common to all forwarded channels. client is a socket, channel is the channel that was just created, and type is an arbitrary string describing the type of the channel.

     # File lib/net/ssh/service/forward.rb, line 210
210:       def prepare_client(client, channel, type)
211:         client.extend(Net::SSH::BufferedIo)
212:         client.extend(Net::SSH::ForwardedBufferedIo)
213:         client.logger = logger
214: 
215:         session.listen_to(client)
216:         channel[:socket] = client
217: 
218:         channel.on_data do |ch, data|  
219:           debug { "data:#{data.length} on #{type} forwarded channel" }
220:           ch[:socket].enqueue(data)
221:         end
222:         
223:         # Handles server close on the sending side by Miklós Fazekas
224:         channel.on_eof do |ch|
225:           debug { "eof #{type} on #{type} forwarded channel" }
226:           begin
227:             ch[:socket].send_pending
228:             ch[:socket].shutdown Socket::SHUT_WR
229:           rescue IOError => e
230:             if e.message =~ /closed/ then
231:               debug { "epipe in on_eof => shallowing exception:#{e}" }
232:             else
233:               raise
234:             end
235:           rescue Errno::EPIPE => e
236:             debug { "epipe in on_eof => shallowing exception:#{e}" }
237:           rescue Errno::ENOTCONN => e
238:             debug { "enotconn in on_eof => shallowing exception:#{e}" }
239:           end
240:         end
241:         
242:         channel.on_close do |ch|
243:           debug { "closing #{type} forwarded channel" }
244:           ch[:socket].close if !client.closed?
245:           session.stop_listening_to(ch[:socket])
246:         end
247: 
248:         channel.on_process do |ch|
249:           if ch[:socket].closed?
250:             ch.info { "#{type} forwarded connection closed" }
251:             ch.close
252:           elsif ch[:socket].available > 0
253:             data = ch[:socket].read_available(8192)
254:             ch.debug { "read #{data.length} bytes from client, sending over #{type} forwarded connection" }
255:             ch.send_data(data)
256:           end
257:         end
258:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.