From: Delano Mandelbaum <delano@...>
Date: 2009-07-16T11:45:07+09:00
Subject: [ANN] Rye 0.8

Rye 0.8.5 - Safely run shell commands on a bunch of machines in
parallel (from Ruby)

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: rbox.rm
('-rf', '/etc/**/*')

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.

Inspired by Rush (http://rush.heroku.com) and compatible with Ruby
1.8, 1.9, and JRuby 1.3+!


EXECUTE COMMANDS ON A REMOTE MACHINE

Execute shell commands by calling methods on a Rye::Box object.

    require 'rye'
    rbox = Rye::Box.new('hostname')
    rbox.pwd                        # => "/home/rye"
    rbox.uname :a                   # => "Darwin rye-stage 9.7.0 ..."

Method arguments are sent directly as arguments to the shell command.
Single-character Symbols are assumed to be single-character switches.
e.g. "rbox.uname :a" is equivalent to "uname -a"


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/*'

You can also execute any valid shell command.

    rbox.execute 'ps aux | grep ruby > /tmp/ruby-process-list'

See the "About Safe Mode" section in the README for more information.


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
    rset.add_boxes(rbox, 'HOST2')   # Add 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.

    rset.hostname                   # => [["HOST1"], ["HOST2"]]
    rset.uname                      # => [["Darwin"], ["Linux"]]

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 "SETNAME", :parallel => true
     OR
   rset.parallel = true


FILE TRANSFERS

    rbox = Rye::Box.new "localhost"

    rbox.file_upload "README.rdoc", "/tmp"

    applejack = StringIO.new "Some in-memory content"
    rbox.file_upload applejack, "/tmp/applejack.txt"

    rbox.ls "/tmp/"                 # => [README.rdoc, applejack.txt]
    rbox.cat "/tmp/applejack.txt"   # => "Some in-memory content"

    filecontent = StringIO.new
    rbox.file_download "/tmp/applejack.txt", filecontent

    filecontent.read                # => "Some in-memory content"


SSH KEY AUTHORIZATION

Enable passwordless logins to HOST1 and HOST2:

    $ rye authorize HOST1 HOST2

This will copy your public SSH keys to the ~/.ssh/authorized_keys and
~/.ssh/authorized_keys2 files on the remote machine(s).

See rye -h for more info


DEPENDENCIES

* OpenSSH: http://www.openssh.com/
* OpenSSL: http://www.openssl.org/
* Ruby Gems:
  * net-ssh
  * net-scp
  * highline
  * drydock
  * sysinfo
  * storable


INSTALLATION

Via Rubygems, one of:

    $ 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 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 a problem let me know!


MORE INFO

Codes: http://github.com/delano/rye
Rdocs: http://delano.github.com/rye
Issues: http://github.com/delano/rye/issues