Encapsulates a single session (connection) to a server via SSH.

Methods
Attributes
[R] connection The underlying connection
[R] host The name of the host that this session is connected to.
[R] options The hash of options that were used to establish this session.
[R] registry The dependency-injection registry used by this session.
Public Class methods
new( *args ) {|self| ...}

Create a new SSH session. This method polymorphically accepts a variable number of parameters, as follows:

  • 1 parameter: must be the hostname to connect to.
  • 2 parameters: must be the hostname, and either the port (as an integer) or the username to connect as.
  • 3 parameters: must be the hostname, and either the port (as an integer) and username, or the username and the password.
  • 4 parameters: must be the hostname, port, username, and password.

Any scenario above that omits the username assumes that the USER environment variable is set to the user‘s name. Any scenario above that omits the password assumes that the user will log in without a password (ie, using a public key). Any scenario above that omits the port number assumes a port number of 22 (the default for SSH).

Any of the above scenarios may also accept a Hash as the last parameter, specifying a list of additional options to be used to initialize the session. (See Net::SSH::Session.add_options).

Alternatively, named parameters may be used, in which case the first parameter is positional and is always the host to connect to, following which you may specify any of the following named parameters (as symbols):

  • :port
  • :username
  • :password

Any additional parameters are treated as options that configure how the connection behaves.

Allowed options are:

  • :keys (the list of filenames identifying the user‘s keys)
  • :host_keys (the list of filenames identifying the host‘s keys)
  • :auth_methods (a list of authentication methods to use)
  • :crypto_backend (defaults to :ossl, and specifies the cryptography backend to use)
  • :registry_options (a hash of options to use when creating the registry)
  • :container (the registry to use. If not specified, a new registry will be created)
  • :verbose (how verbose the logging output should be. Defaults to :warn).
  • :log (the name of the file, or the IO object, to which messages will be logged. Defaults to STDERR.)
  • :forward_agent (true or false, whether or not to forward requests for the authentication agent. Defaults to false.)
  • :paranoid (either false, in which case server fingerprints are not verified, true, in which case they are verified and mismatches result in a warning and a prompt, or an object responding to :allow?, which will be invoked and should return true or false for whether or not to allow the connection. Defaults to true.)

Also, any options recognized by Net::SSH::Transport::Session may be given, and will be passed through to initialize the transport session.

If a block is given to this method, then it is called with the new session object. The session object is then closed when the block terminates. If a block is not given, then the session object is returned (and must be closed explicitly).

     # File lib/net/ssh/session.rb, line 100
100:       def initialize( *args )
101:         @open = false
102:         @agent_forwarded = false
103: 
104:         process_arguments( *args )
105: 
106:         @registry.define do |b|
107:           b.crypto_backend { @crypto_backend }
108:           b.transport_host { @host }
109:           b.transport_options { @options }
110: 
111:           b.userauth_keys { @keys }
112:           b.userauth_host_keys { @host_keys }
113:           b.userauth_method_order { @auth_methods }
114: 
115:           b.host_key_verifier { @host_key_verifier }
116: 
117:           # Register myself with the registry, so that other services may
118:           # access me.
119:           b.session( :pipeline => [] ) { self }
120: 
121:           b.prompter do
122:             require 'net/ssh/util/prompter'
123:             Net::SSH::Util::Prompter.new
124:           end
125: 
126:           b.require 'net/ssh/transport/services', "Net::SSH::Transport"
127:           b.require 'net/ssh/connection/services', "Net::SSH::Connection"
128:           b.require 'net/ssh/userauth/services', "Net::SSH::UserAuth"
129: 
130:           b.require 'net/ssh/service/services', "Net::SSH::Service"
131:         end
132: 
133:         userauth = @registry[:userauth][:driver]
134:         if userauth.authenticate( "ssh-connection", @username, @password )
135:           @open = true
136:           @connection = @registry[:connection][:driver]
137:           if block_given?
138:             yield self
139:             close
140:           end
141:         else
142:           @registry[:transport][:session].close
143:           raise AuthenticationFailed, @username
144:         end
145:       end
Public Instance methods
close()

Closes the session, if it is open. If it is not open, this does nothing.

     # File lib/net/ssh/session.rb, line 149
149:       def close
150:         @registry[:transport][:session].close if @open
151:         @open = false
152:       end
loop( &block )

Enters the main communication loop. This processes events occuring over the channel. If a block is given, the loop will continue for as long as the block returns true. Otherwise, the loop continues until there are no more open channels. (See Net::SSH::Connection::Driver#loop).

     # File lib/net/ssh/session.rb, line 184
184:       def loop( &block )
185:         sanity_check
186:         @connection.loop(&block)
187:       end
method_missing( sym, *args, &block )

Provides convenient access to services that have been registered with the session, such as "process" and "forward".

Usage:

  session.forward.local(...)
     # File lib/net/ssh/session.rb, line 195
195:       def method_missing( sym, *args, &block )
196:         if args.empty? && block.nil? && @registry[:services].has_key?( sym )
197:           return @registry[:services][ sym ]
198:         else
199:           super
200:         end
201:       end
open?()

Returns true if the session is currently open.

     # File lib/net/ssh/session.rb, line 155
155:       def open?
156:         @open
157:       end
open_channel( type="session", data=nil, &block )

Opens a new communication channel over the current connection. This returns immediately. The block will be invoked when then the channel has been opened. (See Net::SSH::Connection::Driver#open_channel).

     # File lib/net/ssh/session.rb, line 162
162:       def open_channel( type="session", data=nil, &block )
163:         sanity_check
164:         channel = @connection.open_channel( type, data )
165:         channel.on_confirm_open(&block)
166: 
167:         # If we have an agent, and agent-forwarding is enabled, set up
168:         # the forwarding. Do this once only, after the first channel
169:         # is opened.
170:         if @forward_agent && @registry[:userauth].agent
171:           unless @agent_forwarded
172:             agentforward.request
173:             @agent_forwarded = true
174:           end
175:         end
176: 
177:         channel
178:       end