Net::SSH::Session

A wrapper on top of Net::SSH and Net::SSH::Shell to provide a set of tools for ssh sessions

Install

Install with rubygems:

gem install net-ssh-session

Install with bundler:

gem 'net-ssh-session', :github => 'sosedoff/net-ssh-session'

Usage

Basic usage:

require 'net/ssh/session'

# Initialize a new connection
session = Net::SSH::Session.new(host, user, password)

# Initialize connection on a different SSH port
session = Net::SSH::Session.new(host, user, password, :port => 5000)

# Connect to server
session.open

# If you want to set a connection timeout in seconds
# it will raise Timeout::Error 
session.open(10)

# Execute a remote command
result = session.run("free -m")

# Net::SSH::SessionCommand helpers
result.success?  # => true
result.failure?  # => false
result.exit_code # => 0
result.output    # => command output text
result.duration  # => execution time, seconds

# Capture command output
session.capture('cat /etc/lsb-release')

# File helpers
session.file_exists?('/path')
session.directory_exists?('/path')
session.symlink_exists?('/path')
session.read_file('/path')

# Process helpers
session.process_exists?(PID)
session.kill_process(PID) # => true
session.kill_process(PID, 'SIGINT') # => false
session.last_exit_code # => 1

# Environment helpers
session.env('RAILS_ENV') # => production
session.export('RAILS_ENV', 'production')
session.export_hash(
  'RAILS_ENV' => 'test',
  'RACK_ENV'  => 'test'
)

# Execute a batch of commands
session.run_multiple(
  'git clone [email protected]:project.git',
  'cd project',
  'bundle install',
  'rake test'
)

# Execute by calling a method
session.ping("-c 5", "google.com")
session.df('-h')

# Execute as sudo
session.sudo("whoami")

# Execute with time limit (10s)
begin
  session.with_timeout(10) do
    session.run('some long job')
  end
rescue Timeout::Error
  puts "Operation took too long :("
end

# Execute a long command and show ongoing process
session.run("rake test") do |str|
  puts str
end

# Get history, returns an array with Net::SSH::SessionCommand objects
session.history.each do |cmd|
  puts cmd.to_s # => I, [2012-11-08T00:10:48.229986 #51878]  INFO -- : [bundle install --path .bundle] => 10, 35 bytes
  if cmd.success?
    # do your thing
  end
end

# Close current session
session.close

Advanced Usage

Running multiple commands

By default multiple command execution will not break if one of the commands fails. If you want to break the chain on the first failure, supply :break => true option:

session.run_multiple(commands, :break => true)

To get each command result after execution, you can supply a block:

commands = ["mkdir /tmp", "echo test > /tmp/file", "rm -rf /tmp"]

session.run_multiple(commands) do |cmd|
  puts "Original command: #{cmd.command}"
  puts "Exit code: #{cmd.exit_code}"
  puts "Output: #{cmd.output}"
end

Using session logger

If you want to log command execution for the whole session you can assign a logger:

require 'logger'
require 'net/ssh/session'

s = Net::SSH::Session.new(host, user, password)
s.logger = Logger.new(STDOUT)
s.open

s.run("cd /tmp")
s.run("git clone git://github.com/sosedoff/net-ssh-session.git")
s.run("bundle install --path .bundle")

s.close

Since the logger is set to write to STDOUT you'll see something like this:

I, [2012-11-08T00:10:47.605916 #51878]  INFO -- : [cd /tmp] => 0, 0 bytes
I, [2012-11-08T00:10:48.038294 #51878]  INFO -- : [git clone git://github.com/sosedoff/net-ssh-session.git] => 0, 7795 bytes
I, [2012-11-08T00:10:48.229986 #51878]  INFO -- : [bundle install --path .bundle] => 10, 35 bytes

Execution history

By default each session command (Net::SSH::SessionCommand) will be recorded in session history. Example how to skip history tracking:

require 'net/ssh/session'

s = Net::SSH::Session.new(host, user, password)
s.open

# Run commands with no history
s.run("export RAILS_ENV=test", :history => false)
r.run("mysqlcheck --repair mysql proc -u root", :history => false)

# Rest will be recorded
s.run("git clone git://github.com/sosedoff/net-ssh-session.git")
s.run("bundler install --path .")

s.close

You can also disable history for the whole session:

Net::SSH::Session.new(host, user, password, :history => false)

Execute any command with timeout

To enable session-wide command execution timeout, pass an extra option:

session = Net::SSH::Session.new(host, user, password, :timeout => 10)

This will limit any command execution time to 10 seconds. Error Timeout::Error will be raised when timeout is exceeded.

License

The MIT License (MIT)