Contents

Before you can do anything with Net::SSH, you need to require the @net/ssh@ module:

[!figure lang=ruby,caption=Requiring Net::SSH
require 'net/ssh'
!]

Once you have required the @net/ssh@ module, you can begin an SSH session by calling @Net::SSH.start@.  This may be used in one of two ways. If called without a block, it will return a reference to the new session as an instance of a @Net::SSH::Session@. Used this way, you must explicitly close the session when you are finished with it.

[!figure lang=ruby,number=true,caption=Opening an SSH session
session = Net::SSH.start( 'host', 'user', 'passwd' )
...
session.close
!]

The other approach involves attaching a block to the start method. When used this way, the new session is passed to the block, and the session is automatically closed when the block exits.

[!figure lang=ruby,number=true,caption=Opening a transactional SSH session
Net::SSH.start( 'host', 'user', 'passwd' ) do |session|
  ...
end
!]

If you need to specify a different port on the host to connect to (the default is 22), you can specify it immediately after the @host@ parameter, like so:

[!figure lang=ruby,number=true,caption=Specifying the SSH port
Net::SSH.start( 'host', 1234, 'user', 'passwd' ) do |session|
  ...
end
!]

h3. Using Keyword Arguments

Some people prefer using keyword arguments for functions with more than a couple of parameters. The @start@ method supports this approach as well, although the @host@ parameter is always positional and always comes first.

[!figure lang=ruby,number=true,caption=Using keyword arguments
Net::SSH.start( 'host',
                :password=>'passwd', 
                :port=>1234,
                :username=>'user',
                ... ) do |session|
  ...
end
!]

(More about the "@...@" stuff, later.)

h3. Failed Authentication

If the username and/or password given to @start@ are incorrect, authentication will fail. If authentication fails, a @Net::SSH::AuthenticationFailed@ exception will be raised.

Version data entries

2 entries across 2 versions & 1 rubygems

Version	Path
net-ssh-1.0.0	doc/manual/parts/session_start.txt
net-ssh-0.9.0	doc/manual/parts/session_start.txt