open4ssh 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 78635fba401d382c7a6cf79897cb94e89ec54175
+  data.tar.gz: 3a33cebef1a16d8071d4dc2c7aefa849a6f60888
+SHA512:
+  metadata.gz: 0f380979bfca37db680e5bf1e0f7ba1c4966279ee5e879caafbc73216d261a48ebab5905f8641ca1c8c9acf09029d5a42420a35f55b90ff975551482f18aa5ed
+  data.tar.gz: 0e11987f6bcdb82f4dd1c3586dade177189dfc8a6495fa89913afb8f72868ed62676c75d0f7129afb577b4b14c85b4238042da2e5d698b19d987c6e60e9f90cb

data/.gitignore

@@ -0,0 +1,10 @@
+/.idea/
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.0
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in open4ssh.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Nane Kratzke
+
+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.

data/README.md

@@ -0,0 +1,230 @@
+# Open4ssh
+
+[Open4ssh](https://github.com/nkratzke/open4ssh) is a small convenience wrapper for [net-ssh](https://rubygems.org/gems/net-ssh). 
+Its intended and primary purpose is to provide pragmatic
+execution of shell commands on a remote host via SSH.
+
+It is mainly inspired by [Open3](http://ruby-doc.org/stdlib-2.3.1/libdoc/open3/rdoc/Open3.html) standard library 
+which provides access to exit codes, 
+standard output and standard error messages of executed commands on local host.
+Open4ssh does the same but in a SSH remote context. 
+Astonishingly, there seems no pragmatic way to figure out exit codes or standard error messages of executed commands 
+with the net-ssh library.
+Additionally, Open4ssh is able to execute a 
+sequence of commands and returns their exit codes, standard out and standard error messages in a command related list.
+
+Open4ssh is most useful in remote automation scenarios which are triggered from Ruby environments.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'open4ssh'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install open4ssh
+
+## Usage
+
+### Remote execution of a single command via SSH
+
+All parameters of the _exec_ command are explained [here](Open4ssh.html#exec-class_method).
+
+However, the following snippets explain how to use Open4ssh. 
+To execute simply one single command on a remote host, we can do the following:
+
+```ruby
+require 'open4ssh'
+
+stdout = Open4ssh.exec(
+     host: 'remote.host.io',
+     user: 'nane',
+     pwd: 'secret',
+     cmd: 'ls -la'
+)
+puts stdout
+```
+
+This will execute the bash command 'ls -la' on host _remote.host.io_ as user _nane_.
+
+For a lot of cloud scenarios it is more appropriate to support a keybased login. This can be done like that 
+(simply use the key parameter instead of the pwd parameter):
+
+```ruby
+require 'open4ssh'
+
+stdout = Open4ssh.exec(
+     host: 'remote.host.io',
+     user: 'nane',
+     key: '/path/to/your/sshkey.pem',
+     cmd: 'ls -la'
+)
+puts stdout
+```
+
+### Remote execution of a sequence of commands via SSH
+
+All parameters of the _exec4_ command are explained [here](Open4ssh.html#exec4-class_method).
+The following snippets will explain how to use Open4ssh to execute a (sequence) of commands.
+
+This snippet here will execute five shell commands sequentially
+
+```ruby
+require 'open4ssh'
+require 'pp'
+
+returns = Open4ssh.exec4(
+     host: 'remote.host.io',
+     user: 'nane',
+     key: '/path/to/your/sshkey.pem',
+     cmd: [
+       "touch helloworld.txt",
+       "cat helloworld.txt",
+       "echo 'Hello World' >> helloworld.txt",
+       "cat helloworld.txt",
+       "rm helloworld.txt"
+     ]
+)
+pp(returns)
+```
+
+and will generate this output.
+
+    [[0, "", "", "touch helloworld.txt"],
+     [0, "", "", "cat helloworld.txt"],
+     [0, "", "", "echo 'Hello World' >> helloworld.txt"],
+     [0, "Hello World\n", "", "cat helloworld.txt"],
+     [0, "", "", "rm helloworld.txt"]]
+
+So, for each command a list of return values is returned.
+
+1. exit code of the executed command
+2. standard out message (might be empty)
+3. standard error message (might be empty)
+4. executed command (as passed by the _cmd_ parameter in _exec4_ call.
+
+However, if we launch a sequence of commands exiting with exit codes not equal 0, this sequence is only executed as long as 
+each command could be successfully processed (exit code 0). So this snippet here
+
+```ruby
+require 'open4ssh'
+require 'pp'
+
+returns = Open4ssh.exec4(
+     host: 'remote.host.io',
+     user: 'nane',
+     key: '/path/to/your/sshkey.pem',
+     cmd: [
+       "touch helloworld.txt",
+       "cat helloworld.txt",
+       "this will not work",
+       "cat helloworld.txt",
+       "rm helloworld.txt"
+     ]
+)
+pp(returns)
+```
+
+would produce the following output
+
+    [[0, "", "", "touch helloworld.txt"],
+     [0, "", "", "cat helloworld.txt"],
+     [127, "", "bash: this: command not found\n", "this will not work"]]
+     
+and the last two commands would not been executed on the remote host, because the third command failed.
+
+### How to check whether a sequence of commands was successful?
+
+Because Open4ssh only executes commands as long as they are returning a exit code of 0, we can check 
+pragmatically whether all commands of a sequence have been executed successfully:
+
+```ruby
+exit_code, stderr, stdout, command = Open4ssh.exec4(
+     host: 'remote.host.io',
+     user: 'nane',
+     key: '/path/to/your/sshkey.pem',
+     cmd: [
+       "touch helloworld.txt",
+       "cat helloworld.txt",
+       "echo 'Hello World' >> helloworld.txt",
+       "cat helloworld.txt",
+       "rm helloworld.txt"
+     ]
+).last
+
+if (exit_code == 0 && command == "rm helloworld.txt")
+    puts "Everything worked fine"
+end
+```
+
+### What is this good for?
+
+Just a small example. Assuming your remote host is a Ubuntu 14.04 system we could do something like that:
+
+```ruby
+exit_code, stdout, stderr, command = Open4ssh.exec4(
+     host: 'remote.host.io',
+     user: 'nane',
+     key: '/path/to/your/sshkey.pem',
+     cmd: [
+       "curl -fsSL https://test.docker.com/ | sh",
+       "sudo docker swarm init"
+     ]
+).last
+
+if (command == "sudo docker swarm init" && exit_code == 0)
+    puts "You started successfully a new Docker Swarm cluster."
+end
+```
+
+This would fire up an initial master for a [Docker Swarm cluster](https://docs.docker.com/engine/swarm/) 
+in a few lines of Ruby code. Be patient. This can take several minutes. 
+Of course, you can do any other tasks as well. This was only one example ;-)
+
+### Verbose mode
+
+If you want to know what is happening there you can turn on the verbose mode (mostly useful for debugging).
+
+```ruby
+exit_code, stdout, stderr, command = Open4ssh.exec4(
+     host: 'remote.host.io',
+     user: 'nane',
+     key: '/path/to/your/sshkey.pem',
+     cmd: [
+       "curl -fsSL https://test.docker.com/ | sh",
+       "sudo docker swarm init"
+     ],
+     verbose: true
+).last
+
+if (command == "sudo docker swarm init" && exit_code == 0)
+    puts "You started successfully a new Docker Swarm cluster."
+end
+```
+
+This will perform the same install like above but will print all messages of the Docker install script on your console.
+
+## Development
+
+To install this gem onto your local machine, run `bundle exec rake install`. 
+To release a new version, update the version number in `version.rb`, 
+and then run `bundle exec rake release`, 
+which will create a git tag for the version, 
+push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on Github at https://github.com/nkratzke/open4ssh.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', '-', 'README.md', 'LICENSE.txt']
+  # t.options = ['--any', '--extra', '--opts']
+  t.stats_options = ['--list-undoc']
+end

data/lib/open4ssh/version.rb

@@ -0,0 +1,3 @@
+module Open4ssh
+  VERSION = "0.1.0"
+end

data/lib/open4ssh.rb

@@ -0,0 +1,82 @@
+require "open4ssh/version"
+require "net/ssh"
+
+module Open4ssh
+
+  # Executes a shell command on a remote host via SSH and returns the console output.
+  #
+  # @param host [String] DNS name or IP address of the remote host (required)
+  # @param port [Integer] Port (defaults to 22)
+  # @param user [String] User name (required)
+  # @param key [Path] Path to a key file (.pem) if user logs in via keyfile (not required if password is provided)
+  # @param pwd [String] Password of user (not required if key is provided)
+  # @param cmd [String] valid shell command string to be executed on host (required)
+  #
+  # @return [String] console output of executed command (output includes stdout and stderr)
+  #
+  def self.exec(host: '', user: '', port: 22, key: '', pwd: '', cmd: '')
+    stdout = ""
+    keys = [key]
+
+    Net::SSH.start(host, user, port: 22, password: pwd, keys: keys) do |ssh|
+      result = ssh.exec!(cmd)
+      stdout = result
+    end
+
+    return stdout
+  end
+
+  # Executes a list of shell commands on a remote host via SSH and returns their exit codes, stdouts and stderrs.
+  # The commands are executed sequentially until a command terminates with an exit code not equal 0 (no success).
+  #
+  # @param host [String] DNS name or IP address of the remote host (required)
+  # @param port [Integer] Port (defaults to 22)
+  # @param user [String] User name (required)
+  # @param key [Path] Path to a key file (.pem) if user logs in via keyfile (not required if password is provided)
+  # @param pwd [String] Password of user (not required if key is provided)
+  # @param cmd [Array<String>] List of valid shell command strings to be executed on host (required)
+  # @param verbose [Bool] console outputs are plotted to stdout/stderr if set (defaults to false)
+  #
+  # @return [Array<exit_code, stdout, stderr, command>] List of exit_code, stdout, stderr and executed commands
+  #
+  def self.exec4(host: '', user: '', port: 22, key: '', pwd: '', cmd: [], verbose: false)
+    keys    = [key]
+    results = []
+
+    Net::SSH.start(host, user, port: port, password: pwd, keys: keys) do |ssh|
+      # Execute command by command
+      for command in cmd
+        stdout   = ""
+        stderr   = ""
+        code     = nil
+        channel = ssh.open_channel do |ch|
+          ch.exec(command) do |c, success|
+            c.close unless success
+
+            c.on_data do |_, data|
+              stdout += data
+              $stdout.puts(data) if verbose
+            end
+
+            c.on_extended_data do |_, _, data|
+              stderr += data
+              $stderr.puts(data) if verbose
+            end
+
+            c.on_request('exit-status') { |_, data| code = data.read_long }
+          end
+        end
+        channel.wait
+        results << [code, stdout, stderr, command]
+
+        # If last command was not successful stop execution
+        if code != 0
+          ssh.close
+          return results
+        end
+      end
+    end
+
+    return results
+  end
+end

data/open4ssh.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'open4ssh/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "open4ssh"
+  spec.version       = Open4ssh::VERSION
+  spec.authors       = ["Nane Kratzke"]
+  spec.email         = ["nane.kratzke@fh-luebeck.de"]
+
+  spec.summary       = %q{Wrapper around net-ssh for plain execution of remote shell commands.}
+  spec.description   = %q{Wrapper around net-ssh for plain execution of remote shell commands and painless collection of exit codes, stdout, stderr messages.}
+  spec.homepage      = "https://rubygems.org/gems/open4ssh"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "yard", "~> 0.8"
+
+  spec.add_runtime_dependency "net-ssh", "~> 3.2"
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: open4ssh
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nane Kratzke
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-07-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: net-ssh
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: Wrapper around net-ssh for plain execution of remote shell commands and
+  painless collection of exit codes, stdout, stderr messages.
+email:
+- nane.kratzke@fh-luebeck.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/open4ssh.rb
+- lib/open4ssh/version.rb
+- open4ssh.gemspec
+homepage: https://rubygems.org/gems/open4ssh
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Wrapper around net-ssh for plain execution of remote shell commands.
+test_files: []
+has_rdoc: