Class Rye::Box
In: lib/rye/box.rb
Parent: Object

Rye::Box

The Rye::Box class represents a machine. All system commands are made through this class.

    rbox = Rye::Box.new('filibuster')
    rbox.hostname   # => filibuster
    rbox.uname      # => FreeBSD
    rbox.uptime     # => 20:53  up 1 day,  1:52, 4 users

You can also run local commands through SSH

    rbox = Rye::Box.new('localhost')
    rbox.hostname   # => localhost
    rbox.uname(:a)  # => Darwin vanya 9.6.0 ...

Methods

Included Modules

Rye::Cmd InstanceExecHelper

Classes and Modules

Module Rye::Box::InstanceExecHelper

Attributes

rye_pty  [RW] 
rye_shell  [RW] 

Public Class methods

  • host The hostname to connect to. Default: localhost.
  • user The username to connect as. Default: SSH config file or current shell user.
  • opts a hash of optional arguments.

The opts hash excepts the following keys:

  • :safe => should Rye be safe? Default: true
  • :port => remote server ssh port. Default: SSH config file or 22
  • :keys => one or more private key file paths (passwordless login)
  • :via => the Rye::Hop to access this host through
  • :info => an IO object to print Rye::Box command info to. Default: nil
  • :debug => an IO object to print Rye::Box debugging info to. Default: nil
  • :error => an IO object to print Rye::Box errors to. Default: STDERR
  • :getenv => pre-fetch host environment variables? (default: true)
  • :password => the user‘s password (ignored if there‘s a valid private key)
  • :templates => the template engine to use for uploaded files. One of: :erb (default)
  • :sudo => Run all commands via sudo (default: false)

NOTE: opts can also contain any parameter supported by Net::SSH.start that is not already mentioned above.

Public Instance methods

Compares itself with the other box. If the hostnames are the same, this will return true. Otherwise false.

Change the current working directory (sort of).

I haven‘t been able to wrangle Net::SSH to do my bidding. "My bidding" in this case, is maintaining an open channel between commands. I‘m using Net::SSH::Connection::Session#exec for all commands which is like a funky helper method that opens a new channel each time it‘s called. This seems to be okay for one-off commands but changing the directory only works for the channel it‘s executed in. The next time exec is called, there‘s a new channel which is back in the default (home) directory.

Long story short, the work around is to maintain the current directory locally and send it with each command.

    rbox.pwd              # => /home/rye ($ pwd )
    rbox['/usr/bin'].pwd  # => /usr/bin  ($ cd /usr/bin && pwd)
    rbox.pwd              # => /usr/bin  ($ cd /usr/bin && pwd)
add_env(n, v)

Alias for setenv

add_key(*keys)

Alias for add_keys

Add one or more private keys to the list of key paths.

  • keys is a list of file paths to private keys

Returns the instance of Box

Execute a block in the context of an instance of Rye::Box.

    rbox = Rye::Box.new

    rbox.batch do
      ls :l
      uname :a
    end

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.

Like [] except it returns an empty Rye::Rap object to mimick a regular command method. Call with nil key (or no arg) to reset.

Open an SSH session with +@rye_host+. This called automatically when you the first comamnd is run if it‘s not already connected. Raises a Rye::NoHost exception if +@rye_host+ is not specified. Will attempt a password login up to 3 times if the initial authentication fails.

  • reconnect Disconnect first if already connected. The default

is true. When set to false, connect will do nothing if already connected.

The most recent valud for umask (or 0022)

The most recent value from Box.cd or Box.[]

Close the SSH session with +@rye_host+. This is called automatically at exit if the connection is open.

Supply a block to be called whenever there‘s an Exception. It‘s called with 1 argument: the exception class. If the exception block returns :retry, the command will be executed again.

e.g.

    rbox.exception_hook(CommandNotFound) do |ex|
      STDERR.puts "An error occurred: #{ex.class}"
      choice = Annoy.get_user_input('(S)kip  (R)etry  (A)bort: ')
      if choice == 'R'
        :retry
      elsif choice == 'S'
        # do nothing
      else
        exit  # !
      end
    end

A Hash. The keys are exception classes, the values are Procs to execute

execute(cmd, *args, &block)

Alias for method_missing

Returns the hash containing the parsed output of "env" on the remote machine. If the initialize option +:getenv+ was set to false, this will return an empty hash. This is a lazy loaded method so it fetches the remote envvars the first time this method is called.

     puts rbox.getenv['HOME']    # => "/home/gloria" (remote)

NOTE: This method should not raise an exception under normal circumstances.

Uses the output of "useradd -D" to determine the default home directory. This returns a GUESS rather than the a user‘s real home directory. Currently used only by authorize_keys_remote. Only useful before you‘ve logged in. Otherwise check $HOME

Returns the host SSH keys for this box

If STDIN.tty? is true (i.e. if we‘re connected to a terminal with a human at the helm), this will open an SSH connection via the regular SSH command (via a call to system). This requires the SSH command-line executable (ssh).

If STDIN.tty? is false or run is false, this will return the SSH command (a String) that would have been run.

NOTE: As of Rye 0.9 you can run interactive sessions with rye by calling any shell method without arguments.

e.g.

    rbox = Rye::Box.new 'somemachine'
    rbox.bash

TODO: refactor to use net_ssh_exec! in 0.9

A handler for undefined commands. Raises Rye::CommandNotFound exception.

Return the value of uname in lowercase This is a temporary fix. We can use SysInfo for this, upload it, execute it directly, parse the output.

Supply a block to be called after every command. It‘s called with one argument: an instance of Rye::Rap.

When this block is supplied, the command does not raise an exception when the exit code is greater than 0 (the typical behavior) so the block needs to check the Rye::Rap object to determine whether an exception should be raised.

Supply a block to be called before every command. It‘s called with three arguments: command name, an Array of arguments, user name, hostname e.g.

    rbox.pre_command_hook do |cmd,args,user,host|
      ...
    end

Returns the command an arguments as a String.

Like batch, except it enables quiet mode before executing the block. After executing the block, quiet mode is returned back to whichever state it was previously in. In other words, this method won‘t enable quiet mode if it was already disabled.

In quiet mode, the pre and post command hooks are not called. This is used internally when calling commands like ls to check whether a file path exists (to prevent polluting the logs).

remove_key(*keys)

Alias for remove_keys

Remove one or more private keys fromt he list of key paths.

  • keys is a list of file paths to private keys

Returns the instance of Box

See unsafely (except in reverse)

Add an environment variable. n and v are the name and value. Returns the instance of Rye::Box

Parse SSH config files for use with Net::SSH

Returns the current value of the stash +@rye_stash+

Store a value to the stash +@rye_stash+

Supply a block to be called every time a command receives STDOUT data.

e.g.

    rbox.stdout_hook do |content|
      ...
    end

Like batch, except it enables sudo mode before executing the block. If the user is already root, this has no effect. Otherwise all commands executed in the block will run via sudo.

If no block is specified then sudo is called just like a regular command.

Reconnect as another user. This is different from su= which executes subsequent commands via +su -c COMMAND USER+.

  • newuser The username to reconnect as

NOTE: if there is an open connection, it‘s disconnected but not reconnected because it‘s possible it wasn‘t connected yet in the first place (if you create the instance with default settings for example)

Returns +user@rye_host+

Change the current umask (sort of — works the same way as cd) The default umask is 0022

Like batch, except it disables safe mode before executing the block. After executing the block, safe mode is returned back to whichever state it was previously in. In other words, this method won‘t enable safe mode if it was already disabled.

  • hops Rye::Hop objects will be added directly

to the set. Hostnames will be used to create new instances of Rye::Hop h1 = Rye::Hop.new "host1" h1.via_hop "host2", :user => "service_user"

OR

h1 = Rye::Hop.new "host1" h2 = Rye::Hop.new "host2" h1.via_hop h2

wildly(*args, &block)

Alias for unsafely

[Validate]