rouster 0.53 → 0.57

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 76526d9f9fbaca98b3ea2bfad51a769f67df6647
-  data.tar.gz: 6f9bc1a95bec7be30e00eccb1cd0ca28c6d24a72
+  metadata.gz: ca887947fd8eb61d347ebb19f562d4ab6f79cf79
+  data.tar.gz: 424047f4ad62c0b279baa71d503045096416b37f
 SHA512:
-  metadata.gz: 345f5b6e4ef69a8a023e4bf3aebbb517e69a0ff7eee1f95b330bb1c373becfa1c231931f5c189099ec44acc355efe5a23b1c07cf057dc9cd6a297c7651343391
-  data.tar.gz: 92be5fcb79d74870bea301a722a539459656a89b9a7c139dba1c02e5fcbff5d12207f6dab4720952be5e58ab6606e27781885dfea29ffef1a117de757e713e56
+  metadata.gz: 90856a137433d2c34a2f2f7e3977c748bb8457f96049c0111b650ab6f5e0520380f74406b20b7a274f01bc8c8b1341b5d0c6fd345cec5960db718b76c6b9a55c
+  data.tar.gz: e6f9d8b1400e684cf89451a4ac2d46ace2f3642927a7b70cb666ed03e2475b250c45a82c68174f8ce1cebf252ec2b2ccb07546b69193ecbf2568d3cad3858e18

data/README.md

@@ -24,8 +24,11 @@ The first implementation of Rouster was in Perl, called [Salesforce::Vagrant](ht
 
 * [Ruby](http://rubylang.org), version 2.0+ (best attempt made to support 1.8.7 and 1.9.3 as well)
 * [Vagrant](http://vagrantup.com), version 1.0.5+
-
-Note: Vagrant itself requires VirtualBox or VMWare Fusion (1.0.3+)
+* Gems
+  * json
+  * log4r
+  * net-scp
+  * net-ssh
 
 Note: Rouster should work exactly the same on Windows as it does on \*nix and OSX (minus rouster/deltas.rb functionality, at least currently),
 but no real testing has been done to confirm this. Please file issues as appropriate.

data/examples/passthrough.rb

@@ -0,0 +1,71 @@
+require sprintf('%s/../%s', File.dirname(File.expand_path(__FILE__)), 'path_helper')
+
+require 'rouster'
+require 'rouster/puppet'
+require 'rouster/tests'
+
+verbosity = ENV['VERBOSE'].nil? ? 4 : 0
+
+# .inspect of this is blank for sshkey and status, looks ugly, but is ~accurate.. fix this?
+local = Rouster.new(
+  :name        => 'local',
+  :sudo        => false,
+  :passthrough => { :type => :local },
+  :verbosity   => verbosity,
+)
+
+remote = Rouster.new(
+  :name => 'remote',
+  :sudo => false,
+  :passthrough => {
+    :type => :remote,
+    :host => `hostname`.chomp, # yep, the remote is actually local.. perhaps the right :type would be 'ssh' vs 'shellout' instead..
+    :user => ENV['USER'],
+    :key  => sprintf('%s/.ssh/id_dsa', ENV['HOME']),
+  },
+  :verbosity => verbosity,
+)
+
+sudo = Rouster.new(
+  :name        => 'sudo',
+  :sudo        => true,
+  :passthrough => { :type => :local },
+  :verbosity   => verbosity,
+)
+
+vagrant = Rouster.new(
+  :name        => 'ppm',
+  :sudo        => true,
+  :verbosity   => verbosity,
+)
+
+workers = [ local, remote, vagrant ]
+
+workers = [vagrant]
+
+workers.each do |r|
+  p r
+
+  ## vagrant command testing
+  r.up()
+  r.suspend()
+  #r.destroy()
+  r.up()
+
+  p r.status() # why is this giving us nil after initial call? want to blame caching, but not sure
+
+  r.is_vagrant_running?()
+  r.sandbox_available?()
+
+  if r.sandbox_available?()
+    r.sandbox_on()
+    r.sandbox_off()
+    r.sandbox_rollback()
+    r.sandbox_commit()
+  end
+
+  p r.run('echo foo')
+
+end
+
+exit

data/lib/rouster.rb

@@ -7,11 +7,12 @@ require 'net/ssh'
 require sprintf('%s/../%s', File.dirname(File.expand_path(__FILE__)), 'path_helper')
 
 require 'rouster/tests'
+require 'rouster/vagrant'
 
 class Rouster
 
   # sporadically updated version number
-  VERSION = 0.53
+  VERSION = 0.57
 
   # custom exceptions -- what else do we want them to include/do?
   class ArgumentError        < StandardError; end # thrown by methods that take parameters from users
@@ -20,36 +21,65 @@ class Rouster
   class ExternalError        < StandardError; end # thrown when external dependencies do not respond as expected
   class LocalExecutionError  < StandardError; end # thrown by _run()
   class RemoteExecutionError < StandardError; end # thrown by run()
+  class PassthroughError     < StandardError; end # thrown by anything Passthrough related (mostly vagrant.rb)
   class SSHConnectionError   < StandardError; end # thrown by available_via_ssh() -- and potentially _run()
 
-  attr_accessor :facts, :sudo, :verbosity
-  attr_reader :cache, :cache_timeout, :deltas, :exitcode, :log, :name, :output, :passthrough, :sshkey, :unittest, :vagrantfile
+  attr_accessor :facts
+  attr_reader :cache, :cache_timeout, :deltas, :exitcode, :logger, :name, :output, :passthrough, :retries, :sshkey, :unittest, :vagrantbinary, :vagrantfile
 
   ##
   # initialize - object instantiation
   #
   # parameters
-  # * <name> - the name of the VM as specified in the Vagrantfile
-  # * [cache_timeout] - integer specifying how long Rouster should cache status() and is_available_via_ssh?() results, default is false
-  # * [passthrough] - boolean of whether this is a VM or passthrough, default is false -- passthrough is not completely implemented
-  # * [sshkey] - the full or relative path to a SSH key used to auth to VM -- defaults to location Vagrant installs to (ENV[VAGRANT_HOME} or ]~/.vagrant.d/)
-  # * [sshtunnel] - boolean of whether or not to instantiate the SSH tunnel upon upping the VM, default is true
-  # * [sudo] - boolean of whether or not to prefix commands run in VM with 'sudo', default is true
-  # * [vagrantfile] - the full or relative path to the Vagrantfile to use, if not specified, will look for one in 5 directories above current location
-  # * [verbosity] - DEBUG (0) < INFO (1) < WARN (2) < ERROR (3) < FATAL (4)
+  # * <name>                - the name of the VM as specified in the Vagrantfile
+  # * [cache_timeout]       - integer specifying how long Rouster should cache status() and is_available_via_ssh?() results, default is false
+  # * [logfile]             - allows logging to an external file, if passed true, generates a dynamic filename, otherwise uses what is passed, default is false
+  # * [passthrough]         - boolean of whether this is a VM or passthrough, default is false -- passthrough is not completely implemented
+  # * [retries]             - integer specifying number of retries Rouster should attempt when running external (currently only vagrant()) commands
+  # * [sshkey]              - the full or relative path to a SSH key used to auth to VM -- defaults to location Vagrant installs to (ENV[VAGRANT_HOME} or ]~/.vagrant.d/)
+  # * [sshtunnel]           - boolean of whether or not to instantiate the SSH tunnel upon upping the VM, default is true
+  # * [sudo]                - boolean of whether or not to prefix commands run in VM with 'sudo', default is true
+  # * [vagrantfile]         - the full or relative path to the Vagrantfile to use, if not specified, will look for one in 5 directories above current location
+  # * [vagrant_concurrency] - boolean controlling whether Rouster will attempt to run `vagrant *` if another vagrant process is already running, default is false
+  # * [verbosity]           - an integer representing console level logging, or an array of integers representing console,file level logging - DEBUG (0) < INFO (1) < WARN (2) < ERROR (3) < FATAL (4)
   def initialize(opts = nil)
-    @cache_timeout = opts[:cache_timeout].nil? ? false : opts[:cache_timeout]
-    @name          = opts[:name]
-    @passthrough   = opts[:passthrough].nil? ? false : opts[:passthrough]
-    @sshkey        = opts[:sshkey]
-    @sshtunnel     = opts[:sshtunnel].nil? ? true : opts[:sshtunnel]
-    @unittest      = opts[:unittest].nil? ? false : opts[:unittest]
-    @vagrantfile   = opts[:vagrantfile].nil? ? traverse_up(Dir.pwd, 'Vagrantfile', 5) : opts[:vagrantfile]
-    @verbosity     = opts[:verbosity].is_a?(Integer) ? opts[:verbosity] : 4
+    @cache_timeout       = opts[:cache_timeout].nil? ? false : opts[:cache_timeout]
+    @logfile             = opts[:logfile].nil? ? false : opts[:logfile]
+    @name                = opts[:name]
+    @passthrough         = opts[:passthrough].nil? ? false : opts[:passthrough]
+    @retries             = opts[:retries].nil? ? 0 : opts[:retries]
+    @sshkey              = opts[:sshkey]
+    @sshtunnel           = opts[:sshtunnel].nil? ? true : opts[:sshtunnel]
+    @unittest            = opts[:unittest].nil? ? false : opts[:unittest]
+    @vagrantfile         = opts[:vagrantfile].nil? ? traverse_up(Dir.pwd, 'Vagrantfile', 5) : opts[:vagrantfile]
+    @vagrant_concurrency = opts[:vagrant_concurrency].nil? ? false : opts[:vagrant_concurrency]
+
+    # TODO kind of want to invert this, 0 = trace, 1 = debug, 2 = info, 3 = warning, 4 = error
+    # could do `fixed_ordering = [4, 3, 2, 1, 0]` and use user input as index instead, so an input of 4 (which should be more verbose), yields 0
+    if opts[:verbosity]
+      # TODO decide how to handle this case -- currently #2 is implemented
+      # - option 1, if passed a single integer, use that level for both loggers
+      # - option 2, if passed a single integer, use that level for stdout, and a hardcoded level (probably INFO) to logfile
+
+      # kind of want to do if opts[:verbosity].respond_to?(:[]), but for 1.87 compatability, going this way..
+      if ! opts[:verbosity].is_a?(Array) or opts[:verbosity].is_a?(Integer)
+        @verbosity_console = opts[:verbosity].to_i
+        @verbosity_logfile = 2
+      elsif opts[:verbosity].is_a?(Array)
+        # TODO more error checking here when we are sure this is the right way to go
+        @verbosity_console = opts[:verbosity][0].to_i
+        @verbosity_logfile = opts[:verbosity][1].to_i
+        @logfile = true if @logfile.eql?(false) # overriding the default setting
+      end
+    else
+      @verbosity_console = 3
+      @verbosity_logfile = 2 # this is kind of arbitrary, but won't actually be created unless opts[:logfile] is also passed
+    end
 
     if opts.has_key?(:sudo)
       @sudo = opts[:sudo]
-    elsif @passthrough.eql?(true)
+    elsif @passthrough.class.eql?(Hash)
+      # TODO say something here.. or maybe check to see if our user has passwordless sudo?
       @sudo = false
     else
       @sudo = true
@@ -68,18 +98,61 @@ class Rouster
     require 'log4r/config'
     Log4r.define_levels(*Log4r::Log4rConfig::LogLevels)
 
-    @log            = Log4r::Logger.new(sprintf('rouster:%s', @name))
-    @log.outputters = Log4r::Outputter.stderr
-    @log.level      = @verbosity
+    @logger            = Log4r::Logger.new(sprintf('rouster:%s', @name))
+    @logger.outputters << Log4r::Outputter.stderr
+    #@log.outputters << Log4r::Outputter.stdout
+
+    if @logfile
+      @logfile = @logfile.eql?(true) ? sprintf('/tmp/rouster-%s.%s.%s.log', @name, Time.now.to_i, $$) : @logfile
+      @logger.outputters << Log4r::FileOutputter.new(sprintf('rouster:%s', @name), :filename => @logfile, :level => @verbosity_logfile)
+    end
+
+    @logger.outputters[0].level = @verbosity_console # can't set this when instantiating a .std* logger, and want the FileOutputter at a different level
+
+    if @passthrough
+      # TODO do better about informing of required specifications, maybe point them to an URL?
+      @vagrantbinary = 'vagrant' # hacky fix to is_vagrant_running?() grepping, doesn't need to actually be in $PATH
+      if @passthrough.class != Hash
+        raise ArgumentError.new('passthrough specification should be hash')
+      elsif @passthrough[:type].nil?
+        raise ArgumentError.new('passthrough :type must be specified, :local or :remote allowed')
+      elsif @passthrough[:type].eql?(:local)
+        @sshtunnel = false
+        @logger.debug('instantiating a local passthrough worker')
+      elsif @passthrough[:type].eql?(:remote)
+        raise ArgumentError.new('remote passthrough requires :host specification') if @passthrough[:host].nil?
+        raise ArgumentError.new('remote passthrough requires :user specification') if @passthrough[:user].nil?
+        raise ArgumentError.new('remote passthrough requires :key specification')  if @passthrough[:key].nil?
+        raise ArgumentError.new('remote passthrough requires valid :key specification, should be path to private half') unless File.file?(@passthrough[:key])
+        @sshkey = @passthrough[:key] # TODO refactor so that you don't have to do this..
+        @logger.debug('instantiating a remote passthrough worker')
+      else
+        raise ArgumentError.new(sprintf('passthrough :type [%s] unknown, allowed: :local, :remote', @passthrough[:type]))
+      end
+    else
 
-    @log.debug('Vagrantfile and VM name validation..')
-    unless File.file?(@vagrantfile)
-      raise InternalError.new(sprintf('specified Vagrantfile [%s] does not exist', @vagrantfile))
-    end
+      @logger.debug('Vagrantfile and VM name validation..')
+      unless File.file?(@vagrantfile)
+        raise ArgumentError.new(sprintf('specified Vagrantfile [%s] does not exist', @vagrantfile))
+      end
 
-    raise InternalError.new('name of Vagrant VM not specified') if @name.nil?
+      raise ArgumentError.new('name of Vagrant VM not specified') if @name.nil?
 
-    return if opts[:unittest].eql?(true) # quick return if we're a unit test
+      return if opts[:unittest].eql?(true) # quick return if we're a unit test
+
+      begin
+        @vagrantbinary = self._run('which vagrant').chomp!
+      rescue
+        raise ExternalError.new('vagrant not found in path')
+      end
+
+      @logger.debug('SSH key discovery and viability tests..')
+      if @sshkey.nil?
+        # ref the key from the vagrant home dir if it's been overridden
+        @sshkey = sprintf('%s/insecure_private_key', ENV['VAGRANT_HOME']) if ENV['VAGRANT_HOME']
+        @sshkey = sprintf('%s/.vagrant.d/insecure_private_key', ENV['HOME']) unless ENV['VAGRANT_HOME']
+      end
+    end
 
     # this is breaking test/functional/test_caching.rb test_ssh_caching (if the VM was not running when the test started)
     # it slows down object instantiation, but is a good test to ensure the machine name is valid..
@@ -89,36 +162,23 @@ class Rouster
       raise InternalError.new(sprintf('caught non-0 exitcode from status(): %s', e.message))
     end
 
-    begin
-      self._run('which vagrant')
-    rescue
-      raise ExternalError.new('vagrant not found in path')
-    end
-
-    @log.debug('SSH key discovery and viability tests..')
-    if @sshkey.nil?
-      if @passthrough.eql?(true)
-        raise InternalError.new('must specify sshkey when using a passthrough host')
-      else
-        # ref the key from the vagrant home dir if it's been overridden
-        @sshkey = sprintf('%s/insecure_private_key', ENV['VAGRANT_HOME']) if ENV['VAGRANT_HOME']
-        @sshkey = sprintf('%s/.vagrant.d/insecure_private_key', ENV['HOME']) unless ENV['VAGRANT_HOME']
-      end
-    end
-
     begin
       raise InternalError.new('ssh key not specified') if @sshkey.nil?
       raise InternalError.new('ssh key does not exist') unless File.file?(@sshkey)
       self.check_key_permissions(@sshkey)
     rescue => e
-      raise InternalError.new("specified key [#{@sshkey}] has bad permissions. Vagrant exception: [#{e.message}]")
+
+      unless self.is_passthrough? and @passthrough[:type].eql?(:local)
+        raise InternalError.new("specified key [#{@sshkey}] has bad permissions. Vagrant exception: [#{e.message}]")
+      end
+
     end
 
     if @sshtunnel
       self.up()
     end
 
-    @log.info('Rouster object successfully instantiated')
+    @logger.info('Rouster object successfully instantiated')
   end
 
 
@@ -127,86 +187,15 @@ class Rouster
   #
   # overloaded method to return useful information about Rouster objects
   def inspect
+    s = self.status()
     "name [#{@name}]:
       is_available_via_ssh?[#{self.is_available_via_ssh?}],
       passthrough[#{@passthrough}],
       sshkey[#{@sshkey}],
-      status[#{self.status()}],
+      status[#{s}],
       sudo[#{@sudo}],
       vagrantfile[#{@vagrantfile}],
-      verbosity[#{@verbosity}]\n"
-  end
-
-  ## Vagrant methods
-
-  ##
-  # up
-  # runs `vagrant up` from the Vagrantfile path
-  # if :sshtunnel is passed to the object during instantiation, the tunnel is created here as well
-  def up
-    @log.info('up()')
-    self.vagrant(sprintf('up %s', @name))
-
-    @ssh_info = nil # in case the ssh-info has changed, a la destroy/rebuild
-    self.connect_ssh_tunnel() if @sshtunnel
-  end
-
-  ##
-  # destroy
-  # runs `vagrant destroy <name>` from the Vagrantfile path
-  def destroy
-    @log.info('destroy()')
-    disconnect_ssh_tunnel
-    self.vagrant(sprintf('destroy -f %s', @name))
-  end
-
-  ##
-  # status
-  #
-  # runs `vagrant status <name>` from the Vagrantfile path
-  # parses the status and provider out of output, but only status is returned
-  def status
-    status = nil
-
-    if @cache_timeout
-      if @cache.has_key?(:status)
-        if (Time.now.to_i - @cache[:status][:time]) < @cache_timeout
-          @log.debug(sprintf('using cached status[%s] from [%s]', @cache[:status][:status], @cache[:status][:time]))
-          return @cache[:status][:status]
-        end
-      end
-    end
-
-    @log.info('status()')
-    self.vagrant(sprintf('status %s', @name))
-
-    # else case here is handled by non-0 exit code
-    if self.get_output().match(/^#{@name}\s*(.*\s?\w+)\s\((.+)\)$/)
-      # vagrant 1.2+, $1 = status, $2 = provider
-      status = $1
-    elsif self.get_output().match(/^#{@name}\s+(.+)$/)
-      # vagrant 1.2-, $1 = status
-      status = $1
-    end
-
-    if @cache_timeout
-      @cache[:status] = Hash.new unless @cache[:status].class.eql?(Hash)
-      @cache[:status][:time] = Time.now.to_i
-      @cache[:status][:status] = status
-      @log.debug(sprintf('caching status[%s] at [%s]', @cache[:status][:status], @cache[:status][:time]))
-    end
-
-    return status
-  end
-
-  ##
-  # suspend
-  #
-  # runs `vagrant suspend <name>` from the Vagrantfile path
-  def suspend
-    @log.info('suspend()')
-    disconnect_ssh_tunnel()
-    self.vagrant(sprintf('suspend %s', @name))
+      verbosity console[#{@verbosity_console}] / log[#{@verbosity_logfile} - #{@logfile}]\n"
   end
 
   ## internal methods
@@ -233,10 +222,28 @@ class Rouster
     expected_exitcode = [expected_exitcode] unless expected_exitcode.class.eql?(Array) # yuck, but 2.0 no longer coerces strings into single element arrays
 
     cmd = sprintf('%s%s; echo ec[$?]', self.uses_sudo? ? 'sudo ' : '', command)
-    @log.info(sprintf('vm running: [%s]', cmd))
+    @logger.info(sprintf('vm running: [%s]', cmd)) # TODO decide whether this should be changed in light of passthroughs.. 'remotely'?
 
-    output = @ssh.exec!(cmd)
-    if output.match(/ec\[(\d+)\]/)
+    0.upto(@retries) do |try|
+      begin
+        if self.is_passthrough? and self.passthrough[:type].eql?(:local)
+          output = `#{cmd}`
+        else
+          output = @ssh.exec!(cmd)
+        end
+
+        break
+      rescue => e
+        @logger.error(sprintf('failed to run [%s] with [%s], attempt[%s/%s]', cmd, e, try, retries)) if self.retries > 0
+        sleep 10 # TODO need to expose this as a variable
+      end
+
+    end
+
+    if output.nil?
+      output    = "error gathering output, last logged output[#{self.get_output()}]"
+      @exitcode = 256
+    elsif output.match(/ec\[(\d+)\]/)
       @exitcode = $1.to_i
       output.gsub!(/ec\[(\d+)\]\n/, '')
     else
@@ -244,9 +251,10 @@ class Rouster
     end
 
     self.output.push(output)
-    @log.debug(sprintf('output: [%s]', output))
+    @logger.debug(sprintf('output: [%s]', output))
 
     unless expected_exitcode.member?(@exitcode)
+      # TODO technically this could be a 'LocalPassthroughExecutionError' now too if local passthrough.. should we update?
       raise RemoteExecutionError.new("output[#{output}], exitcode[#{@exitcode}], expected[#{expected_exitcode}]")
     end
 
@@ -266,7 +274,7 @@ class Rouster
     if @cache_timeout
       if @cache.has_key?(:is_available_via_ssh?)
         if (Time.now.to_i - @cache[:is_available_via_ssh?][:time]) < @cache_timeout
-          @log.debug(sprintf('using cached is_available_via_ssh?[%s] from [%s]', @cache[:is_available_via_ssh?][:status], @cache[:is_available_via_ssh?][:time]))
+          @logger.debug(sprintf('using cached is_available_via_ssh?[%s] from [%s]', @cache[:is_available_via_ssh?][:status], @cache[:is_available_via_ssh?][:time]))
           return @cache[:is_available_via_ssh?][:status]
         end
       end
@@ -295,86 +303,12 @@ class Rouster
       @cache[:is_available_via_ssh?] = Hash.new unless @cache[:is_available_via_ssh?].class.eql?(Hash)
       @cache[:is_available_via_ssh?][:time] = Time.now.to_i
       @cache[:is_available_via_ssh?][:status] = res
-      @log.debug(sprintf('caching is_available_via_ssh?[%s] at [%s]', @cache[:is_available_via_ssh?][:status], @cache[:is_available_via_ssh?][:time]))
+      @logger.debug(sprintf('caching is_available_via_ssh?[%s] at [%s]', @cache[:is_available_via_ssh?][:status], @cache[:is_available_via_ssh?][:time]))
     end
 
     res
   end
 
-  ##
-  # sandbox_available?
-  #
-  # returns true or false after attempting to find out if the sandbox
-  # subcommand is available
-  def sandbox_available?
-    if @cache.has_key?(:sandbox_available?)
-      @log.debug(sprintf('using cached sandbox_available?[%s]', @cache[:sandbox_available?]))
-      return @cache[:sandbox_available?]
-    end
-
-    @log.info('sandbox_available()')
-    self._run(sprintf('cd %s; vagrant', File.dirname(@vagrantfile))) # calling 'vagrant' without parameters to determine available faces
-
-    sandbox_available = false
-    if self.get_output().match(/^\s+sandbox$/)
-      sandbox_available = true
-    end
-
-    @cache[:sandbox_available?] = sandbox_available
-    @log.debug(sprintf('caching sandbox_available?[%s]', @cache[:sandbox_available?]))
-    @log.error('sandbox support is not available, please install the "sahara" gem first, https://github.com/jedi4ever/sahara') unless sandbox_available
-
-    return sandbox_available
-  end
-
-  ##
-  # sandbox_on
-  # runs `vagrant sandbox on` from the Vagrantfile path
-  def sandbox_on
-    if self.sandbox_available?
-      return self.vagrant(sprintf('sandbox on %s', @name))
-    else
-      raise ExternalError.new('sandbox plugin not installed')
-    end
-  end
-
-  ##
-  # sandbox_off
-  # runs `vagrant sandbox off` from the Vagrantfile path
-  def sandbox_off
-    if self.sandbox_available?
-      return self.vagrant(sprintf('sandbox off %s', @name))
-    else
-      raise ExternalError.new('sandbox plugin not installed')
-    end
-  end
-
-  ##
-  # sandbox_rollback
-  # runs `vagrant sandbox rollback` from the Vagrantfile path
-  def sandbox_rollback
-    if self.sandbox_available?
-      self.disconnect_ssh_tunnel
-      self.vagrant(sprintf('sandbox rollback %s', @name))
-      self.connect_ssh_tunnel
-    else
-      raise ExternalError.new('sandbox plugin not installed')
-    end
-  end
-
-  ##
-  # sandbox_commit
-  # runs `vagrant sandbox commit` from the Vagrantfile path
-  def sandbox_commit
-    if self.sandbox_available?
-      self.disconnect_ssh_tunnel
-      self.vagrant(sprintf('sandbox commit %s', @name))
-      self.connect_ssh_tunnel
-    else
-      raise ExternalError.new('sandbox plugin not installed')
-    end
-  end
-
   ##
   # get_ssh_info
   #
@@ -386,7 +320,7 @@ class Rouster
     h = Hash.new()
 
     if @ssh_info.class.eql?(Hash)
-      @log.debug('using cached SSH info')
+      @logger.debug('using cached SSH info')
       h = @ssh_info
     else
 
@@ -404,7 +338,7 @@ class Rouster
           unless @sshkey.eql?(key)
             h[:identity_file] = key
           else
-            @log.info(sprintf('using specified key[%s] instead of discovered key[%s]', @sshkey, key))
+            @logger.info(sprintf('using specified key[%s] instead of discovered key[%s]', @sshkey, key))
             h[:identity_file] = @sshkey
           end
 
@@ -424,14 +358,37 @@ class Rouster
   #
   # raises its own InternalError if the machine isn't running, otherwise returns Net::SSH connection object
   def connect_ssh_tunnel
-    @log.debug('opening SSH tunnel..')
 
-    status = self.status()
-    if status.eql?('running')
-      self.get_ssh_info()
-      @ssh = Net::SSH.start(@ssh_info[:hostname], @ssh_info[:user], :port => @ssh_info[:ssh_port], :keys => [@sshkey], :paranoid => false)
+    if self.is_passthrough?
+      if self.passthrough[:type].eql?(:local)
+        return false
+      else
+        @logger.debug('opening remote SSH tunnel..')
+        @ssh = Net::SSH.start(
+          @passthrough[:host],
+          @passthrough[:user],
+          :port => @passthrough[:port],
+          :keys => [ @passthrough[:key] ],
+          :paranoid => false
+        )
+      end
     else
-      raise InternalError.new(sprintf('VM is not running[%s], unable open SSH tunnel', status))
+      # not a passthrough, normal connection
+      status = self.status()
+
+      if status.eql?('running')
+        self.get_ssh_info()
+        @logger.debug('opening VM SSH tunnel..')
+        @ssh = Net::SSH.start(
+          @ssh_info[:hostname],
+          @ssh_info[:user],
+          :port => @ssh_info[:ssh_port],
+          :keys => [@sshkey],
+          :paranoid => false
+        )
+      else
+        raise InternalError.new(sprintf('VM is not running[%s], unable open SSH tunnel', status))
+      end
     end
 
     @ssh
@@ -443,7 +400,7 @@ class Rouster
   # shuts down the persistent Net::SSH tunnel
   #
   def disconnect_ssh_tunnel
-    @log.debug('closing SSH tunnel..')
+    @logger.debug('closing SSH tunnel..')
 
     @ssh.shutdown! unless @ssh.nil?
     @ssh = nil
@@ -459,13 +416,19 @@ class Rouster
       return @ostype
     end
 
+    # TODO switch to file based detection
+    # Ubuntu - /etc/os-release
+    # Solaris - /etc/release
+    # RHEL/CentOS - /etc/redhat-release
+    # OSX - ?
+
     res   = nil
     uname = self.run('uname -a')
 
     case uname
       when /Darwin/i
         res = :osx
-      when /Sun|Solaris/i
+      when /SunOS|Solaris/i
         res =:solaris
       when /Ubuntu/i
         res = :ubuntu
@@ -499,7 +462,7 @@ class Rouster
     # TODO what happens when we pass a wildcard as remote_file?
 
     local_file = local_file.nil? ? File.basename(remote_file) : local_file
-    @log.debug(sprintf('scp from VM[%s] to host[%s]', remote_file, local_file))
+    @logger.debug(sprintf('scp from VM[%s] to host[%s]', remote_file, local_file))
 
     begin
       @ssh.scp.download!(remote_file, local_file)
@@ -520,7 +483,7 @@ class Rouster
   # * [remote_file] - full or relative path (based on ~vagrant) of filename to upload to
   def put(local_file, remote_file=nil)
     remote_file = remote_file.nil? ? File.basename(local_file) : remote_file
-    @log.debug(sprintf('scp from host[%s] to VM[%s]', local_file, remote_file))
+    @logger.debug(sprintf('scp from host[%s] to VM[%s]', local_file, remote_file))
 
     raise FileTransferError.new(sprintf('unable to put[%s], local file does not exist', local_file)) unless File.file?(local_file)
 
@@ -537,7 +500,7 @@ class Rouster
   #
   # convenience getter for @passthrough truthiness
   def is_passthrough?
-    self.passthrough.eql?(true)
+    @passthrough.class.eql?(Hash)
   end
 
   ##
@@ -545,7 +508,7 @@ class Rouster
   #
   # convenience getter for @sudo truthiness
   def uses_sudo?
-     self.sudo.eql?(true)
+     @sudo.eql?(true)
   end
 
   ##
@@ -553,7 +516,7 @@ class Rouster
   #
   # destroy and then up the machine in question
   def rebuild
-    @log.debug('rebuild()')
+    @logger.debug('rebuild()')
     self.destroy
     self.up
   end
@@ -566,10 +529,10 @@ class Rouster
   # parameters
   # * [wait] - number of seconds to wait until is_available_via_ssh?() returns true before assuming failure
   def restart(wait=nil)
-    @log.debug('restart()')
+    @logger.debug('restart()')
 
-    if self.is_passthrough? and self.passthrough.eql?(local)
-      @log.warn(sprintf('intercepted [restart] sent to a local passthrough, no op'))
+    if self.is_passthrough? and self.passthrough[:type].eql?(:local)
+      @logger.warn(sprintf('intercepted [restart] sent to a local passthrough, no op'))
       return nil
     end
 
@@ -589,7 +552,7 @@ class Rouster
     if wait
       inc = wait.to_i / 10
       0..wait.each do |e|
-        @log.debug(sprintf('waiting for reboot: round[%s], step[%s], total[%s]', e, inc, wait))
+        @logger.debug(sprintf('waiting for reboot: round[%s], step[%s], total[%s]', e, inc, wait))
         return true if self.is_available_via_ssh?()
         sleep inc
       end
@@ -615,38 +578,22 @@ class Rouster
     cmd      = sprintf('%s > %s 2> %s', command, tmp_file, tmp_file) # this is a holdover from Salesforce::Vagrant, can we use '2&>1' here?
     res      = `#{cmd}` # what does this actually hold?
 
-    @log.info(sprintf('host running: [%s]', cmd))
+    @logger.info(sprintf('host running: [%s]', cmd))
 
     output = File.read(tmp_file)
     File.delete(tmp_file) or raise InternalError.new(sprintf('unable to delete [%s]: %s', tmp_file, $!))
 
+    self.output.push(output)
+    @logger.debug(sprintf('output: [%s]', output))
+
     unless $?.success?
       raise LocalExecutionError.new(sprintf('command [%s] exited with code [%s], output [%s]', cmd, $?.to_i(), output))
     end
 
-    self.output.push(output)
-    @log.debug(sprintf('output: [%s]', output))
-
     @exitcode = $?.to_i()
     output
   end
 
-  ##
-  # vagrant
-  #
-  # abstraction layer to call vagrant faces
-  #
-  # parameters
-  # * <face> - vagrant face to call (include arguments)
-  def vagrant(face)
-    if self.is_passthrough?
-      @log.info(sprintf('calling [vagrant %s] on a passthrough host is a noop', face))
-      return nil
-    end
-
-    self._run(sprintf('cd %s; vagrant %s', File.dirname(@vagrantfile), face))
-  end
-
   ##
   # get_output
   #
@@ -686,7 +633,7 @@ class Rouster
   def traverse_up(startdir=Dir.pwd, filename=nil, levels=10)
     raise InternalError.new('must specify a filename') if filename.nil?
 
-    @log.debug(sprintf('traverse_up() looking for [%s] in [%s], up to [%s] levels', filename, startdir, levels)) unless @log.nil?
+    @logger.debug(sprintf('traverse_up() looking for [%s] in [%s], up to [%s] levels', filename, startdir, levels)) unless @logger.nil?
 
     dirs  = startdir.split('/')
     count = 0
@@ -715,6 +662,11 @@ class Rouster
   def check_key_permissions(key, fix=false)
     allowed_modes = ['0400', '0600']
 
+    if key.match(/\.pub$/)
+      # if this is the public half of the key, be more permissive
+      allowed_modes << '0644'
+    end
+
     raw   = self._run(sprintf('ls -l %s', key))
     perms = self.parse_ls_string(raw)