aks: added ssh-utils; some cosmetic updates to cmd-utils

Author: aks

Gemspec

@@ -1,13 +1,13 @@
 Gem::Specification.new do |s|
   s.name        = 'cmd-utils'
-  s.version     = '1.0.12'
-  s.date        = '2013-09-11'
+  s.version     = '1.1.0'
+  s.date        = '2014-02-27'
   s.summary     = "Utilities for ruby command line scripts"
   s.description = "Some handy utilities for writing command line scripts in ruby."
   s.author      = "Alan K. Stebbens"
   s.email       = '[email protected]'
-  s.files       = ["lib/cmd-utils.rb", "lib/lookup.rb"]
+  s.files       = ["lib/cmd-utils.rb", "lib/lookup.rb", "lib/ssh-utils.rb"]
   s.test_files  = ['tests/test-cmd-utils.rb', 'tests/test-lookup.rb']
-  s.homepage    = 'http://gitlab.com/as/cmd-utils'
+  s.homepage    = 'http://bitbucket.org/aks_/cmd-utils'
   s.license     = 'GPL-2'
 end

README.md

@@ -10,13 +10,15 @@ Installation:
 Usage:
 
     require 'cmd-utils'
+    require 'ssh-utils'
     require 'lookup'
 
 This gem provides:
 
 * routines for output on `$stderr`, controlled by several global variables
 * error-reporting-and-exit
 * system call handling, with verbose or debug output, error and "ok" message handling
+* remote system command invocation (based on ssh)
 * ambiguous, case-insensitive string lookups in arrays or hashs, with error handling
 
 talk, dtalk, qtalk, vtalk, nrtalk, nvtalk
@@ -92,7 +94,8 @@ Error output:
 The `error` routine take an optional numeric first argument which is used to
 set the exit code.  If not given, the exit code is 1.
 
-`cmd_run` ========
+`cmd_run` 
+--------
 
     cmd_run     cmd 
     cmd_run   { cmd }
@@ -111,8 +114,8 @@ and the method returns without invoking `cmd`.
 When `$norun` is false, and if `$verbose` is set, the `cmd` is displayed with
 a prefix of `">> "` before executing it.
 
-If result of invoking `system(cmd)` is an error (non-zero exit code), then an
-error is printed on `$stderr`, possibly preceded by the command itself if it
+If the result of invoking `system(cmd)` is an error (non-zero exit code), then
+an error is printed on `$stderr`, possibly preceded by the command itself if it
 was not already printed.
 
 Note that when using the block forms of run (e.g., `run { cmd }`), the result
@@ -131,6 +134,89 @@ command evaluation with the `$verbose` treatment.
     safe_run { cmd } 
     safe_run {[cmd, errmsg, okmsg]} 
 
+ssh-utils
+=========
+
+A module to define some routines for running commands across many systems using
+ssh.  Environment variables can be specified (PATH is used by default).
+
+Usage:
+
+    require 'ssh-utils'
+
+    on serverlist, :debug = true do |server|
+      as user do
+        with PATH
+          remote_run :whoami
+        end
+      end
+    end
+
+Method Descriptions
+-------------------
+
+    on SERVERLIST, OPTIONSHASH |server|
+      BLOCK-TO-EXECUTE-FOR-EACH-SERVER
+    end
+
+The `on` method specifies a list of servers, with an optional hash of
+options.  The supported options are: `:debug`, `:verbose`, `:with`, 
+`:without`, and `:as`
+
+    :with => ENVARS
+
+`ENVARS` is an array of environment symbol names (or strings) that will
+be included on the `ssh` command that is used to run remote commands.
+
+    :without => ENVARS
+
+`ENVARS` is an array of environment symbol names (or strings) that will *not*
+be included on the `ssh` command that is used to run remote commands.  This
+option is useful when overriding the default inclusion of `PATH`.  For example:
+
+    on backupserver, :without => :PATH
+      remote_run "/bin/tar", "-cf", source_path, dest_path
+    end
+
+    :as => USER
+
+Specifies the user to be used for the subsequent invocations.  By default, 
+the current user is used implicitly.
+
+    :debug => [true | false]
+
+Sets the `:debug` flag for use within the associated block.  The `$debug` flag
+is globally available, but the `:debug` option is a block-local specification.
+
+    :verbose => [true | false]
+
+Sets the `:verbose` flag for use within the associated block.  The `$verbose` flag
+is globally available, but the `:verbose` option is a block-local specification.
+
+
+    as USERLIST, OPTIONSHASH
+      BLOCK-TO-EXECUTE-FOR-EACH-USER
+    end
+
+The `as` method is optional, and if absent causes the current user to
+be used by default (unless overridden by the `~/.ssh/config` file).
+
+The `as` method allows the embedded block to be repeated for each given user.
+If there only one user, it can be specified on the `on` method with an `:as`
+option.  For example, the following two sections are equivalent:
+
+    on someserver
+      as root
+        remote_run :whoami
+      end
+    end
+
+    on someserver, :as => 'root'
+      remote_run :whoami
+    end
+
+
+
 lookup
 ======
 

lib/cmd-utils.rb

@@ -4,7 +4,7 @@
 #
 #
 #    require 'cmd-utils'
-# 
+#
 # Utilities for option-controlled output, and running commands.
 #
 # The output and run methods rely on some external variables:
@@ -14,11 +14,12 @@
 #    $quiet   -- enables qtalk(f) output, and disables talk(f) output
 #    $debug   -- enables dtalk(f) output
 #
-# These routines provide conditional output.  The arguments can be given as part of the
-# the function calls, or, can be provided as the return value of a block.  The advantage
-# of using a block is that the block is not evaluated unless the conditions requiring
-# output are met.  So, if the expression to compute a value that _might_ be printed is
-# expensive, do the computation inside a block.
+# These routines provide conditional output.  The arguments can be given as
+# part of the the function calls, or, can be provided as the return value of a
+# block.  The advantage of using a block is that the block is not evaluated
+# unless the conditions requiring output are met.  So, if the expression to
+# compute a value that _might_ be printed is expensive, do the computation
+# inside a block.
 #
 ##
 # talk - Print msg on STDERR unless `$quiet` is set
@@ -62,7 +63,7 @@ def _fmtargs args, flag
 end
 
 ##
-# dtalk - "debug talk" 
+# dtalk - "debug talk"
 # Print msg on STDERR only if `$debug` is set
 #
 # :call-seq:
@@ -77,9 +78,9 @@ def dtalk *args
   end
 end
 
-def dtalkf *args 
+def dtalkf *args
   if $debug && (args.size> 0 || block_given?)
-    $stderr.printf(*_fmtargs(args, block_given?) { yield }) 
+    $stderr.printf(*_fmtargs(args, block_given?) { yield })
   end
 end
 
@@ -99,7 +100,7 @@ def qtalk *args
   end
 end
 
-def qtalkf *args 
+def qtalkf *args
   if $quiet && (args.size > 0 || block_given?)
     $stderr.printf(*_fmtargs(args, block_given?) { yield } )
   end
@@ -222,6 +223,7 @@ def errorf *args
 #     run      { [cmd, errmsg] }
 #     run      { [cmd, errmsg, okmg] }
 #     run         cmd, errmsg, okmsg
+#
 #     safe_run    cmd
 #     safe_run    cmd, errmsg
 #     safe_run    cmd, errmsg, okmsg
@@ -238,18 +240,18 @@ def errorf *args
 #
 # If there is an error, show the command (preceded by `>> `) if `$verbose` is
 # not set, then show the error code, followed by the given `errmsg` or the
-# default error message.  
+# default error message.
 #
 # The `cmd` can be given either as an argument, or as the returned value from a
-# block.  Important: the block should return a string value to be passed to 
+# block.  Important: the block should return a string value to be passed to
 # the system call.
 
 def cmd_run *args
   args = _msgargs(args, block_given?) { yield }
   if $norun
     nrtalk(args.first)
   elsif args.size > 0
-    safe_run(*args)
+    safe_run *args
   end
 end
 
@@ -259,8 +261,8 @@ def safe_run *args
   args = _msgargs(args, block_given?) { yield }
   cmd, errmsg, okmsg = args
   vtalkf ">> %s\n", cmd
-  if cmd 
-    if system(cmd)              # invoke the command
+  if cmd
+    if system cmd              # invoke the command
       $stderr.puts okmsg if okmsg
       return true
     else                        # an error occured

lib/ssh-utils.rb

@@ -11,7 +11,9 @@
 #
 #    on serverlist, :debug = true do |server|
 #      as user do
-#        remote_run :whoami
+#        with PATH
+#          remote_run :whoami
+#        end
 #      end
 #    end
 
@@ -25,53 +27,101 @@ module SSH_Utils
 
   @opts = {}
   @opts.default = nil
+  @@default_envars = %w(PATH)			# default envarlist
 
   def merge_opts opts = {}
     @opts ||= {}
     @opts.merge!(opts) unless opts.empty?
   end
 
+  # merge_env opts
+  #
+  # merge envars.  :with => ENVARS_TO_ADD, :without => ENVARS_TO_EXCLUDE
+  #   :with => %w(PATH RUBYLIB)
+  #   :without => %w(PATH)
+  # Removes the :with and :without keys from the opts hash
+
+  def merge_env opts
+    @envars = @@default_envars
+    if opts.key?(:with)
+      @envars.concat(opts[:with]).uniq!
+      opts.delete(:with)
+    end
+    if opts.key?(:without)
+      @envars -= opts[:without]
+      opts.delete(:without)
+    end
+  end
+
+  # on SERVERLIST, :with => %w(PATH RUBYLIB), :debug => [true|false], :norun => [true|false]
 
   def on servers, opts = {}
+    merge_env (opts = opts.dup)
     merge_opts opts
     (@servers = servers).each do |server|
       @server = server
-      talk("--> Running block for server #{server}..") if @opts[:debug]
+      talk("--> Running block for server #{server}..") if @opts[:debug] || $debug
       yield server
     end
   end
 
+  # as USER, :with => ENVARLIST, :debug => [true|false], :norun => [true|false]
 
   def as user, opts = {}
     @user = user
+    merge_env (opts = opts.dup)
     merge_opts opts
     yield if block_given?
   end
 
+  # with ENVARLIST, :VAR1 => value, :debug => ...
 
-  def _ssh_command cmd
+  def with env, opts = {}
+    merge_env (opts = opts.dup)
+    merge_opts opts
+  end
+
+  def ssh_command cmd
     ssh = "ssh -A"
     ssh += " -u #{@user}" unless @user.nil?
     ssh += " #{@server}"
+    @envars.each do |env|
+      # explicit values in the options list override the environment values
+      val = @opts.key?(env) ? @opts[env] : ENV[env]
+      if !(val.nil? || val.empty?)
+        ssh += sprintf(" %s='%s'", env, val.gsub("'", "\'"))
+      end
+    end
     ssh += " " + cmd.to_s
     ssh
   end
 
+  def _show_cmd cmd
+    if @opts[:norun] || $norun
+      talkf "(norun) %s\n", cmd
+    elsif @opts[:debug] || $debug || @opts[:verbose] || $verbose
+      talkf "--> %s\n", cmd
+    end
+  end
+
+  # remote_run COMMAND
+  # run the remote command
 
   def remote_run cmd
-    ssh = _ssh_command(cmd)
-    talk("--> " + ssh) if @opts[:debug]
-    system ssh
+    ssh = ssh_command(cmd)
+    _show_cmd ssh
+    system(ssh) unless @opts[:norun] || $norun
   end
   alias :run_remotely :remote_run
 
 
   def remote_run_with_output cmd, opts = {}
+    merge_env (opts = opts.dup)
     merge_opts opts
-    ssh = _ssh_command cmd
-    talk("--> " + ssh) if @opts[:debug]
+    ssh = ssh_command cmd
+    _show_cmd ssh
     out = nil
-    IO.popen(ssh) {|f| out = f.readlines }
+    IO.popen(ssh) {|f| out = f.read }
     out
   end
   alias :capture :remote_run_with_output