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

<pre>
  require 'net/ssh'
</pre>

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.

<pre>
  session = Net::SSH.start( 'host', 'user', 'passwd' )
  ...
  session.close
</pre>

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.

<pre>
  Net::SSH.start( 'host', 'user', 'passwd' ) do |session|
    ...
  end
</pre>

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:

<pre>
  Net::SSH.start( 'host', 1234, 'user', 'passwd' ) do |session|
    ...
  end
</pre>

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.

<pre>
  Net::SSH.start( 'host',
                  :password=>'passwd', 
                  :port=>1234,
                  :username=>'user',
                  ... ) do |session|
    ...
  end
</pre>

(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.