BarkestSsh
The BarkestSsh gem is a very simple wrapper around Net::SSH. Using the BarkestSsh::SecureShell class you can execute a
shell session on a local or remote host. Primarily targeted at bash
shells, this gem may have trouble interacting
with some hardware due to some assumptions it makes.
For instance, it expects to be able to set the PS1
variable to use a custom prompt so it knows when command execution
has officially completed. A possible workaround if the device has a static shell is to set the prompt option to match
the static shell. If the device has a dynamic shell, but a static final sequence (ie - '>', '$', or '#') then setting
the prompt option to that value may also work. However, there may be an issue with false positives in this situation.
This gem was primarily developed to be added into Barker EST web applications (hence the name).
Installation
Add this line to your application's Gemfile:
gem 'barkest_ssh'
And then execute:
$ bundle
Or install it yourself as:
$ gem install barkest_ssh
Usage
All of the work is done in the BarkestSsh::SecureShell constructor. Provide a code block to BarkestSsh::SecureShell.new with the actions you want to execute remotely.
BarkestSsh::SecureShell.new(
host: '10.10.10.10',
user: 'somebody',
password: 'super-secret'
) do |shell|
shell.exec('cd /usr/local/bin')
user_bin_files = shell.exec('ls -A1').split('\n')
@app_is_installed = user_bin_files.include?('my_app')
end
The following methods are available within the code block:
exec(command, options = {}, &block)
This is the core method that will probably be used most often. The command is executed and the text sent
to STDOUT and STDERR is returned as a single string for you to process. The options parameter can set the
:on_non_zero_exit_code
option to :default, :ignore, or :raise_error. If a block is provided, the block
will be called anytime data is received. The block will receive data and type parameters. Type will indicate
if the data was sent to STDOUT or STDERR. If the block returns a value, that value will be sent to the shell.
This can be used to interact with the shell.
exec_ignore(command, &block)
Wrapper for exec
that sets :on_non_zero_exit_code to :ignore.
exec_raise(command, &block)
Wrapper for exec
that sets :on_non_zero_exit_code to :raise_error.
sudo_exec(command, options = {}, &block)
Wrapper for exec
that attempts to elevate the command to run as root. This will only work if the user
that the shell is connected with is a sudoer on the target host. Also, it requires that the target host
uses the sudo
command and bash
shell.
sudo_exec_ignore(command, &block)
Wrapper for sudo_exec
that sets :on_non_zero_exit_code to :ignore.
sudo_exec_raise(command, &block)
Wrapper for sudo_exec
that sets :on_non_zero_exit_code to :raise_error.
last_exit_code
Gets the exit code from the last command, if the shell is configured to retrieve the exit codes.
stdout
Gets the output to STDOUT for the shell session.
stderr
Gets the output to STDERR for the shell session.
combined_output
Gets the output to both STDOUT and STDERR combined together for the shell session.
upload(local_file, remote_file)
Uses a SFTP channel to upload a file to the host. The first time a SFTP method is used a second SSH connection is made to the host and a SFTP channel is created.
download(remote_file, local_file)
Uses a SFTP channel to download a file from the host. The first time a SFTP method is used a second SSH connection is made to the host and a SFTP channel is created.
read_file(remote_file)
Uses a SFTP channel to download a file from the host and returns the contents as a string. The first time a SFTP method is used a second SSH connection is made to the host and a SFTP channel is created.
write_file(remote_file, data)
Uses a SFTP channel to upload a file to the host from an in-memory string. The first time a SFTP method is used a second SSH connection is made to the host and a SFTP channel is created.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/barkerest/barkest_ssh.
License
The gem is available as open source under the terms of the MIT License.
Copyright (c) 2016 Beau Barker