= Net::SSH::Simple {
}[https://gemnasium.com/busyloop/net-ssh-simple] {
}[https://badge.fury.io/rb/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 simplifies advanced usage such as talking to many hosts
in parallel or performing streaming operations (stdio).
== 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
* {98.8%}[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.html] 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.