= Net::SSH::Simple {<img src="https://gemnasium.com/busyloop/net-ssh-simple.png" alt="Dependency Status" />}[https://gemnasium.com/busyloop/net-ssh-simple]

Net::SSH::Simple is a simple wrapper around Net::SSH and Net::SCP.

It reduces the amount of boilerplate code that you need to write for
handling SSH-connections, thereby preventing many common mistakes related
to error-handling, threading, timeouts and keep-alive.

It also makes it very easy to talk to many hosts in parallel
synchronously or asynchronously.

== Features

* Friendly, flexible API for SSH and SCP (synchronous and asynchronous)
* All results are returned as {Net::SSH::Simple::Result}[http://busyloop.github.com/net-ssh-simple/doc/Net/SSH/Simple/Result]
* All errors are raised as {Net::SSH::Simple::Error}[http://busyloop.github.com/net-ssh-simple/doc/Net/SSH/Simple/Error]
* Efficient by default; re-uses transport connections where possible
* Maintains Keep-Alive to prevent unexpected connection timeouts
* Lots of documentation
* {100%}[http://busyloop.github.com/net-ssh-simple/coverage/] test coverage

== Installation

 gem install net-ssh-simple

== Examples

Note: If you are reading this on github then {click here}[http://busyloop.github.com/net-ssh-simple/doc/] for a more readable
version with syntax highlighting.


=== Block Syntax (synchronous)

 require 'net/ssh/simple'

 Net::SSH::Simple.sync do
   r = ssh 'example1.com', 'echo "Hello World."'
   puts r.stdout #=> "Hello World."

   scp_put 'example2.com', '/tmp/local_foo', '/tmp/remote_bar'
   scp_get 'example3.com', '/tmp/remote_foo', '/tmp/local_bar'
 end

=== Block Syntax (asynchronous)

 require 'net/ssh/simple'

 t1 = Net::SSH::Simple.async do
   scp_put 'example1.com', '/tmp/local_foo', '/tmp/remote_bar'
   ssh     'example3.com', 'echo "Hello World A."'
 end
 t2 = Net::SSH::Simple.async do
   scp_get 'example6.com', '/tmp/remote_foo', '/tmp/local_bar'
   ssh     'example7.com', 'echo "Hello World B."'
 end
 r1 = t1.value # wait for t1 to finish and grab return value
 r2 = t2.value # wait for t2 to finish and grab return value

 puts r1.stdout #=> "Hello World A."
 puts r2.stdout #=> "Hello World B."

=== Using an instance

 require 'net/ssh/simple'

 s = Net::SSH::Simple.new
 s.ssh     'example1.com', 'echo "Hello World."'
 s.scp_put 'example2.com', '/tmp/local_foo', '/tmp/remote_bar'
 s.scp_get 'example3.com', '/tmp/remote_foo', '/tmp/local_bar'
 s.close

== Thread safety

Do _not_ share a Net::SSH::Simple instance across threads.

That's the only rule to watch out for. Other than that you're
free to use Net::SSH::Simple concurrently in different Threads.
If you only use the block-syntax then you have nothing to worry about.

If you want to use the instance syntax in a threaded environment
then the following idiom will provide the best performance:

 require 'net/ssh/simple'
 
 # Create and re-use one instance per thread, with a default username.
 def ss
   Thread.current[:simplessh] ||= Net::SSH::Simple.new({:user => 'bob'})
 end

 # Strictly optional. You may use this method to close the
 # SSH connections early. Otherwise our instance will tear
 # down automatically when the enclosing thread finishes.
 def ss_close
   ss.close
   Thread.current[:simplessh] = nil
 end

 # By sharing the same Net::SSH::Simple instance across calls
 # to this method our ssh transport connections get re-used
 # when the same remote host is accessed multiple times.
 def do_something_involving_ssh
   # The connections to example1-5.com are re-used across
   # multiple calls to this method.
   ss.ssh     'example1.com', 'echo "Hello World."', {:user => 'not_bob'}
   ss.scp_put 'example2.com', '/tmp/local_foo', '/tmp/remote_bar'
   ss.scp_get 'example3.com', '/tmp/remote_foo', '/tmp/local_bar'

   t = ss.async do
     scp_put 'example4.com', '/tmp/local_foo', '/tmp/remote_bar'
   end

   ss.sync do
     scp_put 'example5.com', '/tmp/local_foo', '/tmp/remote_bar'
   end

   # wait for our async call to finish
   t.value

   # Below we explicitly do _not_ use the shared instance
   # because we want these connections to close immediately
   # after the block finishes. This is useful when you know
   # that some hosts will be connected to only once during
   # the lifetime of a thread (there's no point in keeping
   # these open).
   Net::SSH::Simple.sync do
     # opens connections to example8.com, example9.com
     ssh 'example8.com', 'echo "Hello World."'
     ssh 'example9.com', 'echo "Hello World."'

     # connections are reused
     ssh 'example8.com', 'echo "World Hello."'
     ssh 'example9.com', 'echo "World Hello."'

     # both connections close at the end of this block
   end
 end

== Documentation

See {Net::SSH::Simple}[http://busyloop.github.com/net-ssh-simple/doc/Net/SSH/Simple] for more examples and full API.

== Running the test suite

The spec-suite makes SSH-connections to localhost, thus you need to have
your own ssh-key authorized in order to run it. Please see the comment
at the top of 'spec/net-ssh-simple.rb' on how to set this up.

When your host is properly configured the following command should pass:

  $ bundle exec rake


== License (MIT)

Copyright (C) 2011 by moe@busyloop.net

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.