delano-rye 0.8.4 → 0.8.5

data/CHANGES.txt

@@ -6,6 +6,15 @@ TODO
 * Fingerprints: ssh-keygen -l -f id_rsa_repos.pub
 
 
+#### 0.8.5 (2009-07-14) #############################
+
+* CHANGE: Rye::Box#getenv now accepts an option key name
+* CHANGE: When not in safe mode, method missing will execute a 
+  method name as a shell command
+* ADDED: Rye::Box#execute for running arbitrary commands when 
+  not in safe mode
+  
+
 #### 0.8.4 (2009-06-30) #############################
 
 * FIXED: Reference to (still) non-existent net-ssh 2.0.12 is now 2.0.11
@@ -208,7 +217,7 @@ Rye.shell and Rye::Box.run_command (SSH) commands.
 * ADDED: hostname command to Rye::Cmd
 * ADDED: Rye::Box.connect now supports multiple password attempts if STDIN.tty returns true 
 * ADDED: Rye::Box.interactive_ssh for opening an SSH session to the given box.
-* CHANGE: Using OpenSSL's ssh-agent but also let's Net::SSH handle the ssh keys. 
+* CHANGE: Using OpenSSH's ssh-agent but also let's Net::SSH handle the ssh keys. 
 
 
 #### 0.4.1 (2009-04-06) #############################

data/README.rdoc

@@ -1,89 +1,125 @@
 = Rye - v0.8
 
-Safely run SSH commands on a bunch of machines at the same time (from Ruby).
+<strong>Safely run SSH commands on a bunch of machines at the same time (from Ruby).</strong>
 
-Rye is similar to Rush[http://rush.heroku.com] but everything happens over SSH (no HTTP daemon) and the default settings are less powerful (for safety). For example, file globs and the "rm" command are disabled so unless otherwise specified, you can't do this: <tt>rbox.rm('-rf', '/etc/**/*')</tt>.
+Inspired by Rush[http://rush.heroku.com] and compatible with Ruby 1.8, 1.9, and JRuby 1.3+!
 
 
-== Installation
-
-One of:
+== Overview
 
-    $ sudo gem install rye
-    $ sudo gem install delano-rye --source http://gems.github.com/
-    $ git clone git://github.com/delano/rye.git
+Rye is a Ruby abstraction for executing shell commands via SSH. By default, Rye errs on the side of caution by running in "safe-mode" which specifies a default whitelist of commands and aggressively escapes all command arguments. For example, file globs and the "rm" command are not available in safe-mode, so you can't do this: <tt>rbox.rm('-rf', '/etc/**/*')</tt>.
 
+Rye does not require anything to be installed on the server side (other than an SSH daemon) so it can be run from any machine with Ruby, OpenSSL, and OpenSSH.
 
-See bin/try for examples!
+    
+== Example 1 -- Execute commands on a remote machine
 
+Shell commands are executed by calling methods on a Rye::Box object. 
+    
+    rbox = Rye::Box.new('hostname')
+    rbox.pwd                               # => "/home/rye"
+    rbox.uname :a                          # => "Darwin rye-stage 9.7.0 ..."
 
-== EXAMPLE 1 -- SSH Authorization
+Method arguments are sent directly as arguments to the shell command. Single-character Symbols are assumed to be single-character switches. <em>e.g. <tt>rbox.uname :a</tt> becomes <tt>uname -a</tt>.</em>
+    
+The return value for a command is a modified Array containing the contents of STDOUT split by line. It also gives access to STDERR and the exit code
 
-Does it annoy you to manually authorize remote SSH accounts? Rye can help!
+    ret = rbox.uptime                      # => "11:02  up 16:01, 3 users"
+    ret.stderr                             # => []
+    ret.exit_code                          # => 0
+    ret.stdout                             # => "11:02  up 16:01, 3 users"
+    ret.stdout.class                       # => Array
+    ret.class                              # => Rye::Rap
 
-Enable passwordless logins to HOST1 and HOST2:
 
-    $ rye authorize HOST1 HOST2    
+== Example 2 -- Paths and environment variables
 
-This will copy your public SSH keys to the <tt>~/.ssh/authorized_keys</tt> and <tt>~/.ssh/authorized_keys2</tt> files on the remote machine(s). 
+You can change directories.
 
-See <tt>rye -h</tt> for more info
-    
-    
-== EXAMPLE 2 -- Basic Usage
+    rbox.cd '/tmp'
+    rbox.pwd                               # => '/tmp'
+    rbox['/etc'].ls                        # => ['apache', 'init.d', ...]
+    rbox.pwd                               # => '/etc'
+    rbox.cd                                # => '/home/rye'
     
-    rbox = Rye::Box.new('localhost')
-    rbox.uptime                            # => 11:02  up 16:01, 3 users
-    rbox['/usr/bin'].pwd                   # => /usr/bin
-    
-You can specify environment variables
+You can specify environment variables.
 
-    rbox.setenv(:RYE, "Forty Creek")
-    rbox.env             # => ['HOME=/home/rye', 'RYE=Forty Creek', ...]
+    rbox.setenv('TIPPLE', "Forty Creek")
+    rbox.getenv 'TIPPLE'                   # => "Forty Creek"    
     
+
+== Example 3 -- Adding and removing commands
+
+You can add and remove commands to the whitelist.
+
+    rbox.add_command :anything, '/path/2/anything'
+    rbox.anything                       
+    rbox.remove_command :anything
+    rbox.anything                          # => Rye::CommandNotFound exception
+
+
+== Example 4 -- Disabling Safe Mode
+
+Safe mode can be disabled on one of the following ways.
+
+    rbox = Rye::Box.new 'HOST', :safe => false
+      OR
+    rbox.disable_safe_mode
+  
+When safe-mode is disabled, you can run any command (regardless of what is defined in the whitelist) with any valid arguments (fileglobs, tildas, etc...).
+
+    rbox.kill '-SIGHUP', 1928111
+    rbox.rm 'path/2/*'
     
-== EXAMPLE 3a -- Accessing Multiple Machines
+You can also execute any valid shell command.
+
+    rbox.execute 'ps aux | grep ruby > /tmp/ruby-process-list'
 
+See the "About Safe Mode" section below for more information.
+ 
+
+== Example 5a -- Accessing Multiple Machines
+
+Shell commands can be executed on multiple machines using a Rye::Set object. Create a "set" of machines.
+
+    rbox = Rye::Box.new 'HOST1
     rset = Rye::Set.new
-    rbox = Rye::Box.new
+    rset.add_boxes(rbox, 'HOST2')          # Add boxes as hostnames or objects
     
-    rset.add_boxes(rbox, 'localhost')      # Add boxes as hostnames or objects
+Then call methods just like with Rye::Box, except now the return value is an Array of Arrays. The order of return values matches the order the machines were added to the set.
     
-Calling methods on Rye::Set objects is very similar to calling them on Rye::Box objects. In fact, it's identical:
-
-    p rset.uptime        # => [[14:19:02 up 32 days, 19:35 ...], [14:19:02 up 30 days, 01:35]]
-    p rset['/etc'].ls    # => [['file1', 'file2', ...], ['life1', 'life2', ...]]
+    rset.hostname                          # => [["HOST1"], ["HOST2"]]
+    rset.uname                             # => [["Darwin"], ["Linux"]]
+    rset.
     
-== EXAMPLE 3b -- Accessing Multiple Machines -- In Parallel
+== Example 5b -- Accessing Multiple Machines in Parallel
    
-By default, Rye:Set connects to each machine sequentially in the order they were added to the set. Commands can also be run in parallel:
+By default, Rye::Set connects to each machine sequentially in the order they were added to the set. Commands can also be run in parallel.
 
-   rset = Rye::Set.new('set-name', :parallel => true)
-     OR
-   rset.parallel = true
+    rset = Rye::Set.new "SETNAME", :parallel => true
+      OR
+    rset.parallel = true
    
    
-== EXAMPLE 4 -- File Transfers
+== Example 6 -- File Transfers
 
-    rbox = Rye::Box.new("localhost", :info => true)
+    rbox = Rye::Box.new "localhost"
 
-    dir_upload = "#{Rye.sysinfo.tmpdir}/rye-upload/"
-    dir_download = "#{Rye.sysinfo.tmpdir}/rye-download/"
-    
-    rbox.file_upload("#{RYE_HOME}/README.rdoc", "#{RYE_HOME}/LICENSE.txt", dir_upload)
+    rbox.file_upload "README.rdoc", "/tmp" 
 
-    applejack = StringIO.new("Some in-memory content")
-    rbox.file_upload(applejack, "#{dir_upload}/applejack.txt")
+    applejack = StringIO.new "Some in-memory content"
+    rbox.file_upload applejack, "/tmp/applejack.txt"
 
-    p rbox.ls(dir_upload)      # => [README.rdoc, LICENSE.txt, applejack.txt]
-    p rbox.cat("#{dir_upload}/applejack.txt")   # => "Some in-memory content"
+    rbox.ls "/tmp/"                 # => [README.rdoc, applejack.txt]
+    rbox.cat "/tmp/applejack.txt"   # => "Some in-memory content"
 
     filecontent = StringIO.new
-    rbox.file_download("#{dir_upload}/applejack.txt", filecontent)
+    rbox.file_download "/tmp/applejack.txt", filecontent
+
+    filecontent.read                # => "Some in-memory content"
 
-    p filecontent.read
 
-== EXAMPLE 5 -- Local processes
+== Example 7 -- Local processes
 
 For local processes, you can bypass <tt>Rye::Box</tt> and execute commands directly with <tt>Rye.shell</tt>:
 
@@ -104,6 +140,18 @@ The return value is a Rye::Rap object (just like with Rye::Box) so you have acce
     ret.class            # => Rye::Rap
 
 
+== Example 8 -- SSH Authorization
+
+Does it annoy you to manually authorize remote SSH accounts? Rye can help!
+
+Enable passwordless logins to HOST1 and HOST2:
+
+    $ rye authorize HOST1 HOST2    
+
+This will copy your public SSH keys to the <tt>~/.ssh/authorized_keys</tt> and <tt>~/.ssh/authorized_keys2</tt> files on the remote machine(s). 
+
+See <tt>rye -h</tt> for more info.
+
 
 == About Safe-Mode
 
@@ -125,6 +173,7 @@ Rye permits only a limited number of system commands to be run. This default whi
 
 == Dependencies
 
+* OpenSSH[http://www.openssh.com/]
 * OpenSSL[http://www.openssl.org] (The C library)
 * Ruby Gems:
   * net-ssh
@@ -135,34 +184,54 @@ Rye permits only a limited number of system commands to be run. This default whi
   * storable
 
 
-== Known Issues
+== Installation
+
+Via Rubygems, one of:
 
-This list will grow. If you find one let me know!
+    $ gem install rye
+    $ gem install delano-rye --source http://gems.github.com/
+
+or via download:
+
+* rye-latest.tar.gz[http://github.com/delano/rye/tarball/latest]
+* rye-latest.zip[http://github.com/delano/rye/zipball/latest]
+
+
+== Known Issues
 
 * Rye doesn't read the ~/.ssh/config file yet
-* Rye uses OpenSSL's ssh-agent (if it exists). Rye starts it up as a child process and shuts it down using at_exit. If you have code in an at_exit that rely's on Rye, make sure your code runs before Rye's at_exit block is called. For example, Drydock uses at_exit too which is why in bin/rye you can see that Drydock is called explicitly so that Rye's at_exit is executed after Drydock executes a command. 
+* Rye uses OpenSSH's ssh-agent (if it exists). Rye starts it up as a child process and shuts it down using at_exit. If you have code in an at_exit that rely's on Rye, make sure your code runs before Rye's at_exit block is called. For example, Drydock uses at_exit too which is why in bin/rye you can see that Drydock is called explicitly so that Rye's at_exit is executed after Drydock executes a command. 
+* No support for STDIN. 
+
+If you find one let me know!
 
 
 == Thanks
 
-* Solutious Incorporated (http://solutious.com) for all the orange juice.
 * Kalin Harvey (http://rely.ca)
-* Rush[http://github.com/adamwiggins/rush]
-* Capistrano[http://github.com/jamis/capistrano/blob/master/lib/capistrano/shell.rb]
+* Rush[http://github.com/adamwiggins/rush] and Capistrano[http://github.com/jamis/capistrano/blob/master/lib/capistrano/shell.rb] for the inspiration.
+* Mike Cline for giving the okay to use the Rye name. 
 
 
 == More Info
 
-* GitHub[http://github.com/delano/rye]
+* Codes[http://github.com/delano/rye]
 * Rdocs[http://delano.github.com/rye]
 * Inspiration[http://www.youtube.com/watch?v=_StUVh6ENuw]
 
+
+== Related Projects
+
+* Rush[http://github.com/adamwiggins/rush]
+
+
 == Credits
 
-* Delano Mandelbaum (delano@solutious.com)
+* Delano (@solutious.com)
 * Escape, Copyright (C) 2006,2007 Tanaka Akira <akr@fsij.org>
 * Rye::Box#instance_exec (for Ruby 1.8) Mauricio Fernandez
 
+
 == License
 
 See: LICENSE.txt

data/lib/rye.rb

@@ -43,7 +43,7 @@ module Rye
   extend self
 
   unless defined?(SYSINFO)
-    VERSION = "0.8.4".freeze
+    VERSION = "0.8.5".freeze
     SYSINFO = SysInfo.new.freeze
   end
   
@@ -277,8 +277,7 @@ module Rye
   #     $ SSH_AUTH_SOCK=/tmp/ssh-tGvaOXIXSr/agent.12951; export SSH_AUTH_SOCK;
   #     $ SSH_AGENT_PID=12952; export SSH_AGENT_PID;
   #
-  # NOTE: The OpenSSL library (The C one, not the Ruby one) 
-  # must be installed for this to work.
+  # NOTE: The OpenSSH library must be installed for this to work.
   # 
   def start_sshagent_environment
     return if @@agent_env["SSH_AGENT_PID"]
@@ -322,7 +321,7 @@ module Rye
     }
     
   rescue => ex
-    STDERR.puts "Error initializing the SSH Agent (is OpenSSL installed?):"
+    STDERR.puts "Error initializing the SSH Agent (is OpenSSH installed?):"
     STDERR.puts ex.message
     STDERR.puts ex.backtrace
     exit 1

data/lib/rye/box.rb

@@ -48,6 +48,7 @@ module Rye
     
     def enable_safe_mode;  @rye_safe = true; end
     def disable_safe_mode; @rye_safe = false; end
+    def safe?; @rye_safe == true; end
     
     def enable_quiet_mode;  @rye_quiet = true; end
     def disable_quiet_mode; @rye_quiet = false; end
@@ -253,7 +254,7 @@ module Rye
     # NOTE: This method should not raise an exception under normal
     # circumstances. 
     #
-    def getenv
+    def getenv(key=nil)
       if @rye_getenv && @rye_getenv.empty? && self.can?(:env)
         vars = self.quietly { env } rescue []
         vars.each do |nvpair| 
@@ -263,7 +264,7 @@ module Rye
           @rye_getenv[n] = v
         end
       end
-      @rye_getenv
+      key.nil? ? @rye_getenv : @rye_getenv[key.to_s]
     end
     
     # Add an environment variable. +n+ and +v+ are the name and value.
@@ -429,12 +430,22 @@ module Rye
     
     # A handler for undefined commands. 
     # Raises Rye::CommandNotFound exception.
-    def method_missing(meth, *args, &block)
-      ex = Rye::CommandNotFound.new(meth.to_s)
-      raise ex unless @rye_exception_hook.has_key? ex.class
-      @rye_exception_hook[Rye::CommandNotFound].call ex
+    def method_missing(cmd, *args, &block)
+      if @rye_safe
+        ex = Rye::CommandNotFound.new(cmd.to_s)
+        raise ex unless @rye_exception_hook.has_key? ex.class
+        @rye_exception_hook[Rye::CommandNotFound].call ex
+      else
+        if block.nil?
+          run_command cmd, *args
+        else
+          ex = Rye::CommandNotFound.new(cmd.to_s)
+          raise ex unless @rye_exception_hook.has_key? ex.class
+        end
+      end
     end
-    
+    alias :execute :method_missing
+
     # Returns the command an arguments as a String. 
     def preview_command(*args)
       prep_args(*args).join(' ')
@@ -484,6 +495,13 @@ module Rye
     # OR
     #     rbox.batch(&block)
     #
+    # The batch can also accept arguments.
+    #
+    #     rbox.batch('path/2/file') do |file|
+    #       ls :l file
+    #     end
+    #
+    # Returns the return value of the block. 
     #
     def batch(*args, &block)
       self.instance_exec *args, &block
@@ -736,7 +754,7 @@ module Rye
         elsif choice == :skip
           # do nothing
         else
-          raise ex
+          raise ex, ex.message
         end
       end
       

data/rye.gemspec

@@ -1,7 +1,7 @@
 @spec = Gem::Specification.new do |s|
   s.name = "rye"
   s.rubyforge_project = "rye"
-  s.version = "0.8.4"
+  s.version = "0.8.5"
   s.summary = "Rye: Safely run SSH commands on a bunch of machines at the same time (from Ruby)."
   s.description = s.summary
   s.author = "Delano Mandelbaum"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: delano-rye
 version: !ruby/object:Gem::Version 
-  version: 0.8.4
+  version: 0.8.5
 platform: ruby
 authors: 
 - Delano Mandelbaum