Net::SSH::Simple <img src=“https://badge.fury.io/rb/net-ssh-simple.svg” alt=“Gem Version” />¶ ↑

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
All errors are raised as 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% test coverage

Installation¶ ↑

gem install net-ssh-simple

Examples¶ ↑

Note: If you are reading this on github then click here 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 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)¶ ↑

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.

busyloop/net-ssh-simple