| Class | Net::SSH::Session |
| In: |
lib/net/ssh/session.rb
|
| Parent: | Object |
Encapsulates a single session (connection) to a server via SSH.
| connection | [R] | The underlying connection |
| host | [R] | The name of the host that this session is connected to. |
| options | [R] | The hash of options that were used to establish this session. |
| registry | [R] | The dependency-injection registry used by this session. |
Create a new SSH session. This method polymorphically accepts a variable number of parameters, as follows:
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):
Any additional parameters are treated as options that configure how the connection behaves.
Allowed options are:
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 93
93: def initialize( *args )
94: @open = false
95: process_arguments( *args )
96:
97: @registry.define do |b|
98: b.crypto_backend { @crypto_backend }
99: b.transport_host { @host }
100: b.transport_options { @options }
101:
102: b.userauth_keys { @keys }
103: b.userauth_host_keys { @host_keys }
104: b.userauth_method_order { @auth_methods }
105:
106: # Register myself with the registry, so that other services may
107: # access me.
108: b.session( :pipeline => [] ) { self }
109:
110: b.prompter do
111: require 'net/ssh/util/prompter'
112: Net::SSH::Util::Prompter.new
113: end
114:
115: b.require 'net/ssh/transport/services', "Net::SSH::Transport"
116: b.require 'net/ssh/connection/services', "Net::SSH::Connection"
117: b.require 'net/ssh/userauth/services', "Net::SSH::UserAuth"
118:
119: b.require 'net/ssh/service/services', "Net::SSH::Service"
120: end
121:
122: userauth = @registry[:userauth][:driver]
123: if userauth.authenticate( "ssh-connection", @username, @password )
124: @open = true
125: @connection = @registry[:connection][:driver]
126: if block_given?
127: yield self
128: close
129: end
130: else
131: @registry[:transport][:session].close
132: raise AuthenticationFailed, @username
133: end
134: end
Closes the session, if it is open. If it is not open, this does nothing.
# File lib/net/ssh/session.rb, line 138
138: def close
139: @registry[:transport][:session].close if @open
140: @open = false
141: end
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 162
162: def loop( &block )
163: sanity_check
164: @connection.loop(&block)
165: end
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 173
173: def method_missing( sym, *args, &block )
174: if args.empty? && block.nil? && @registry[:services].has_key?( sym )
175: return @registry[:services][ sym ]
176: else
177: super
178: end
179: end
Returns true if the session is currently open.
# File lib/net/ssh/session.rb, line 144
144: def open?
145: @open
146: end
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 151
151: def open_channel( type="session", data=nil, &block )
152: sanity_check
153: channel = @connection.open_channel( type, data )
154: channel.on_confirm_open(&block)
155: channel
156: end