net-ssh 0.5.0

data/examples/port-forward.rb

@@ -0,0 +1,51 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+
+require 'net/ssh'
+
+# This assumes three things:
+#
+# 1) That you have an SSH server running on your local machine,
+# 2) That the USER environment variable is set to your user name, and
+# 3) That you have public and private keys conigured so that you can log into
+#    your machine via SSH without being prompted for a password.
+#
+# If #2 or #3 are not true, you can add your user-name and password as the
+# second and third parameters (respectively) to Net::SSH.start.
+
+Net::SSH.start( 'localhost' ) do |session|
+  session.forward.local( 12345, 'www.yahoo.com', 80 )
+  session.forward.local( 12346, 'www.google.com', 80 )
+
+  trap("SIGINT") do
+    puts "direct channels open  : #{session.forward.open_direct_channel_count}"
+    puts "direct channels opened: #{session.forward.direct_channel_count}"
+    puts "active local forwards : #{session.forward.active_locals.length} " +
+      "(#{session.forward.active_locals.inspect})"
+    session.close
+  end
+
+  begin
+    puts "forwarding ports..."
+    session.loop { true }
+  rescue Exception => e
+    unless e.message =~ /connection closed by remote host/
+      raise
+    end
+  end
+end

data/examples/process-demo.rb

@@ -0,0 +1,91 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+require 'net/ssh'
+
+# This assumes three things:
+#
+# 1) That you have an SSH server running on your local machine,
+# 2) That the USER environment variable is set to your user name, and
+# 3) That you have public and private keys conigured so that you can log into
+#    your machine via SSH without being prompted for a password.
+#
+# If #2 or #3 are not true, you can add your user-name and password as the
+# second and third parameters (respectively) to Net::SSH.start.
+
+Net::SSH.start( 'localhost' ) do |session|
+
+  # ===========================================================================
+
+  session.process.open( "bc" ) do |bc|
+    dialog = [ "5+5", "7*12", "sqrt(2.000000)" ]
+
+    bc.on_success do |p|
+      puts "process started successfully. starting interactive session."
+      puts "requesting result of #{dialog.first}"
+      p.puts dialog.shift
+    end
+
+    bc.on_failure do |p, status|
+      puts "process failed to start (#{status})"
+    end
+
+    bc.on_stdout do |p,data|
+      puts "--> #{data}"
+      unless dialog.empty?
+        puts "requesting result of #{dialog.first}"
+        p.puts dialog.shift
+      else
+        p.close_input
+      end
+    end
+
+    bc.on_stderr do |p,data|
+      puts "got stuff from stderr: #{data}"
+    end
+
+    bc.on_exit do |p, status|
+      puts "process finished with exit status: #{status}"
+    end
+  end
+
+  puts "done!"
+
+  # ===========================================================================
+
+  puts "now, trying 'bc' with popen3..."
+
+  input, output, error = session.process.popen3( "bc" )
+  input.puts "5+5"
+  puts "5+5=#{output.read}"
+  input.puts "10*2"
+  puts "10*2=#{output.read}"
+  input.puts "quit"
+
+  # ===========================================================================
+
+  puts "trying 'cat' with popen3"
+  session.process.popen3( "cat" ) do |input,output,error|
+    input.puts "hello"
+    puts output.read
+    input.puts "world"
+    puts output.read
+  end
+
+  puts "done!"
+
+end

data/examples/remote-net-port-forward.rb

@@ -0,0 +1,45 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+
+require 'net/ssh'
+
+# This assumes four things:
+#
+# 1) That you have an SSH server running on your local machine,
+# 2) That the USER environment variable is set to your user name, and
+# 3) That you have public and private keys conigured so that you can log into
+#    your machine via SSH without being prompted for a password.
+# 4) That you have a web server running on your local machine on port 80.
+#
+# If #2 or #3 are not true, you can add your user-name and password as the
+# second and third parameters (respectively) to Net::SSH.start.
+
+Net::SSH.start( 'localhost' ) do |session|
+  session.forward.remote_to( 80, "localhost", 12345 )
+
+  trap("SIGINT") { session.close }
+
+  begin
+    puts "forwarding remote port via localhost..."
+    session.loop { true }
+  rescue Exception => e
+    unless e.message =~ /connection closed by remote host/
+      raise
+    end
+  end
+end

data/examples/remote-port-forward.rb

@@ -0,0 +1,80 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+
+require 'net/ssh'
+
+# This assumes three things:
+#
+# 1) That you have an SSH server running on your local machine,
+# 2) That the USER environment variable is set to your user name, and
+# 3) That you have public and private keys conigured so that you can log into
+#    your machine via SSH without being prompted for a password.
+#
+# If #2 or #3 are not true, you can add your user-name and password as the
+# second and third parameters (respectively) to Net::SSH.start.
+
+class RemoteForwardListener
+  def error( msg )
+    raise "[#{self.class}] An error occurred: #{msg}"
+  end
+
+  def setup( remote_port )
+    puts "[#{self.class}] forwarding enabled from remote port #{remote_port}"
+  end
+
+  def on_open( channel, c_addr, c_port, o_addr, o_port )
+    puts "[#{self.class}] channel opened from remote server:"
+    puts "   - connected address: #{c_addr}:#{c_port}"
+    puts "   - originator address: #{o_addr}:#{o_port}"
+  end
+
+  def on_receive( channel, data )
+    puts "data recevied from remote machine: #{data.inspect}"
+    msg = "It worked! You just connected over a remote forwarded SSH " +
+            "connection!\n\n" +
+          "------\n" +
+          data
+    channel.send_data "HTTP/1.0 200 OK\r\n" +
+                      "Content-Type: text/plain\r\n" +
+                      "Content-Length: #{msg.length}\r\n" +
+                      "\r\n" +
+                      msg
+  end
+
+  def on_close( channel )
+    puts "remote channel closed"
+  end
+
+  def on_eof( channel )
+    puts "remote end of channel promised not to send any more data"
+  end
+end
+
+Net::SSH.start( 'localhost' ) do |session|
+  session.forward.remote( RemoteForwardListener.new, 12345 )
+
+  trap("SIGINT") { session.close }
+
+  begin
+    session.loop { true }
+  rescue Exception => e
+    unless e.message =~ /connection closed by remote host/
+      raise
+    end
+  end
+end

data/examples/tail-demo.rb

@@ -0,0 +1,49 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+require 'net/ssh'
+
+# This assumes three things:
+#
+# 1) That you have an SSH server running on your local machine,
+# 2) That the USER environment variable is set to your user name, and
+# 3) That you have public and private keys conigured so that you can log into
+#    your machine via SSH without being prompted for a password.
+#
+# If #2 or #3 are not true, you can add your user-name and password as the
+# second and third parameters (respectively) to Net::SSH.start.
+
+Net::SSH.start( 'localhost' ) do |session|
+
+  # Note: two things here,
+  #
+  # 1) open_channel does not immediately invoke the associated block. It only
+  #    calls the block after the server has confirmed that the channel is valid.
+  # 2) channel.exec does not block--it just sends the request to the server and
+  #    returns.
+  #
+  # For these two reasons, you MUST call session.loop, so that packets get
+  # processed and dispatched to the appropriate channel for handling.
+
+  session.open_channel do |channel|
+    channel.on_data { |chan,data| puts "--> #{data.inspect}" }
+    channel.on_extended_data { |chan,type,data| print data }
+    channel.exec "tail -f /tmp/mylog"
+  end
+
+  session.loop
+end

data/lib/net/ssh.rb

@@ -0,0 +1,52 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+require 'net/ssh/session'
+
+#--
+# Documentation Roadmap:
+#
+#   1. Start with net/ssh/session.rb (Net::SSH::Session). This creates a new
+#      Needle registry and registers all the services.
+#
+#   2. Look at net/ssh/transport/services.rb to see how the transport services
+#      are defined, and what classes implement each of them.
+#
+#   3. Look at net/ssh/transport/session.rb (Net::SSH::Transport::Session). This
+#      implements the driver for the transport layer.
+#
+#   4. Look at net/ssh/userauth/services.rb to see how the services for the
+#      user authentication layer are defined, and implemented.
+#
+#   5. Look at net/ssh/connection/services.rb to see how the services for the
+#      connection layer are defined and implemented.
+#
+#   6. Look at net/ssh/service/services.rb to see how the auxiliary services
+#      (process and forward) are defined.
+#++
+
+module Net
+  module SSH
+
+    # A convenience method for starting a new SSH session. See
+    # Net::SSH::Session.
+    def start( *args, &block )
+      Net::SSH::Session.new( *args, &block )
+    end
+    module_function :start
+
+  end
+end

data/lib/net/ssh/connection/channel.rb

@@ -0,0 +1,411 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+require 'net/ssh/connection/constants'
+
+module Net
+  module SSH
+    module Connection
+
+      class Channel
+        include Constants
+
+        #--
+        # ====================================================================
+        # ATTRIBUTES
+        # ====================================================================
+        #++
+
+        # The channel's local id (assigned by the connection)
+        attr_reader :local_id
+
+        # The channel's remote id (assigned by the remote server)
+        attr_reader :remote_id
+
+        # The connection driver instance that owns this channel
+        attr_reader :connection
+
+        # The type of this channel
+        attr_reader :type
+        
+        # The maximum packet size that may be sent over this channel
+        attr_reader :maximum_packet_size
+
+        # The maximum data window size for this channel
+        attr_reader :window_size
+
+        #--
+        # ====================================================================
+        # FACTORY METHODS
+        # ====================================================================
+        #++
+
+        # Requests that a new channel be opened on the remote host.
+        # This will return immediately, but the +on_confirm_open+ callback
+        # will be invoked when the remote host confirms that the channel has
+        # been successfully opened.
+        def self.open( connection, log, buffers, type, data=nil )
+          channel = new( connection, log, buffers, type )
+
+          msg = buffers.writer
+
+          msg.write_byte CHANNEL_OPEN
+          msg.write_string type
+          msg.write_long channel.local_id
+          msg.write_long 0x7FFFFFFF, 0x7FFFFFFF
+          msg.write data.to_s if data
+
+          connection.send_message msg
+
+          channel
+        end
+
+        # Creates a new channel object with the given internal
+        # information. The channel is assumed to already be
+        # connected to a remote host.
+        def self.create( connection, log, buffers, type, remote_id,
+          window_size, packet_size )
+        # begin
+          channel = new( connection, log, buffers, type )
+          channel.do_confirm_open remote_id, window_size, packet_size
+          channel
+        end
+
+        private_class_method :new
+
+        #--
+        # ====================================================================
+        # CONSTRUCTOR
+        # ====================================================================
+        #++
+
+        # Create a new channel object on the given connection, and of the given
+        # type.
+        def initialize( connection, log, buffers, type )
+          @connection = connection
+          @log = log
+          @buffers = buffers
+          @type = type
+          @local_id = @connection.allocate_channel_id
+        end
+
+        #--
+        # ====================================================================
+        # CALLBACK HOOKS
+        # ====================================================================
+        #++
+
+        # Set the callback to use when the channel has been confirmed
+        # to be open.
+        def on_confirm_open( &block )
+          @on_confirm_open = block
+        end
+
+        # Set the callback to use when the channel could not be opened
+        # for some reason.
+        def on_confirm_failed( &block )
+          @on_confirm_failed = block
+        end
+
+        # Set the callback to be invoked when the server requests
+        # that the window size be adjusted.
+        def on_window_adjust( &block )
+          @on_window_adjust = block
+        end
+
+        # Set the callback to be invoked when the server sends a
+        # data packet over the channel.
+        def on_data( &block )
+          @on_data = block
+        end
+
+        # Set the callback to be invoked when the server sends an
+        # extended data packet over the channel.
+        def on_extended_data( &block )
+          @on_extended_data = block
+        end
+
+        # Set the callback to be invoked when the server sends an EOF
+        # packet.
+        def on_eof( &block )
+          @on_eof = block
+        end
+
+        # Set the callback to be invoked when the server sends a
+        # request packet.
+        def on_request( &block )
+          @on_request = block
+        end
+
+        # Set the callback to invoked when the server sends
+        # confirmation of a successful operation.
+        def on_success( &block )
+          @on_success = block
+        end
+
+        # Set the callback to invoked when the server sends
+        # notification of a failed operation.
+        def on_failure( &block )
+          @on_failure = block
+        end
+
+        # Set the callback to be invoked when the channel is closed.
+        def on_close( &block )
+          @on_close = block
+        end
+
+        #--
+        # ====================================================================
+        # CHANNEL STATE ACCESSORS
+        # ====================================================================
+        #++
+
+        def valid?
+          not @local_id.nil?
+        end
+
+        # Retrieved a named property of the channel.
+        def property( name )
+          ( @properties ||= Hash.new )[ name ]
+        end
+
+        # Set a named property on the channel.
+        def set_property( name, value )
+          ( @properties ||= Hash.new )[ name ] = value
+        end
+
+        alias :[]  :property
+        alias :[]= :set_property
+
+        #--
+        # ====================================================================
+        # CHANNEL AFFECTORS
+        # ====================================================================
+        #++
+
+        # Closes the channel.
+        def close( client_initiated=true )
+          unless defined?(@already_closed) && @already_closed
+            msg = @buffers.writer
+            msg.write_byte CHANNEL_CLOSE
+            msg.write_long @remote_id
+            @connection.send_message msg
+            @already_closed = true
+          end
+
+          unless client_initiated
+            @connection.remove_channel( self )
+            callback :close, self
+          end
+
+          self
+        end
+
+        # Send an EOF across the channel. No data should be sent from the client
+        # to the server over this channel after this, although packets may still
+        # be received from the server.
+        def send_eof
+          msg = @buffers.writer
+          msg.write_byte CHANNEL_EOF
+          msg.write_long @remote_id
+          @connection.send_message msg
+          self
+        end
+
+        # Send the given signal to process on the other side of the channel. The
+        # parameter should be one of the Channel::SIGxxx constants.
+        def send_signal( sig, want_reply=false )
+          send_request_string "signal", sig, want_reply
+          self
+        end
+
+        # Send a channel request with the given name. It will have one data
+        # item, which will be interpreted as a string.
+        def send_request_string( request_name, data, want_reply=false )
+          msg = @buffers.writer
+          msg.write_string data.to_s
+          send_request request_name, msg, want_reply
+        end
+
+        # Send a generic channel request with the given name. The data item will
+        # be written directly into the request (after converting it to a string,
+        # as necessary).
+        def send_request( request_name, data, want_reply=false )
+          msg = @buffers.writer
+          msg.write_byte CHANNEL_REQUEST
+          msg.write_long @remote_id
+          msg.write_string request_name
+          msg.write_bool want_reply
+          msg.write data.to_s
+          @connection.send_message msg
+          self
+        end
+
+        # Send a data packet to the server, over the channel.
+        def send_data( data )
+          msg = @buffers.writer
+          msg.write_byte CHANNEL_DATA
+          msg.write_long @remote_id
+          msg.write_string data.to_s
+          @connection.send_message msg
+        end
+
+        # Send an extended data packet to the server, over the channel.
+        # Extended data always has a numeric type associated with it. The
+        # only predefined type is 1, whic corresponds to +stderr+ data.
+        def send_extended_data( type, data )
+          msg = @buffers.writer
+          msg.write_byte CHANNEL_EXTENDED_DATA
+          msg.write_long @remote_id
+          msg.write_long type
+          msg.write_string data.to_s
+          @connection.send_message msg
+        end
+
+        VALID_PTY_OPTIONS = { :term=>"xterm",
+                              :chars_wide=>80,
+                              :chars_high=>24,
+                              :pixels_wide=>640,
+                              :pixels_high=>480,
+                              :modes=>{},
+                              :want_reply=>false }
+
+        # Request that a pty be opened for this channel. Valid options are
+        # :term, :chars_wide, :chars_high, :pixels_wide, :pixels_high, :modes,
+        # and :want_reply. :modes is a Hash, where the keys are constants from
+        # Net::SSH::Service::Term, and values are integers describing the
+        # corresponding key.
+        def request_pty( opts = {} )
+          invalid_opts = opts.keys - VALID_PTY_OPTIONS.keys
+          unless invalid_opts.empty?
+            raise ArgumentError,
+              "invalid option(s) to request_pty: #{invalid_opts.inspect}"
+          end
+
+          VALID_PTY_OPTIONS.keys.each do |opt|
+            opts[ opt ] ||= VALID_PTY_OPTIONS[ opt ]
+          end
+
+          msg = @buffers.writer
+          msg.write_string opts[ :term ]
+          msg.write_long opts[ :chars_wide ]
+          msg.write_long opts[ :chars_high ]
+          msg.write_long opts[ :pixels_wide ]
+          msg.write_long opts[ :pixels_high ]
+
+          modes = @buffers.writer
+          opts[ :modes ].each do |mode, data|
+            modes.write_byte mode
+            modes.write_long data
+          end
+          modes.write_byte Term::TTY_OP_END
+
+          msg.write_string modes.to_s
+
+          send_request "pty-req", msg, opts[:want_reply]
+        end
+
+        # Execute the given remote command over the channel. This should be
+        # invoked in the "on_confirm" callback of a channel. This method will
+        # return immediately.
+        def exec( command, want_reply=false )
+          send_request_string "exec", command, want_reply
+        end
+
+        # Request the given subsystem. This method will return immediately.
+        def subsystem( subsystem, want_reply=true )
+          send_request_string "subsystem", subsystem, want_reply
+        end
+
+        #--
+        # ====================================================================
+        # CHANNEL EVENTS
+        # ====================================================================
+        #++
+
+        # A convenience method for defining new event callbacks.
+        def self.event( event, *parameters )
+          define_method "do_#{event}" do |*args|
+            callback event, self, *args
+            self
+          end
+        end
+
+        # Invoked when the server confirms the opening of a channel.
+        def do_confirm_open( remote_id, window_size, packet_size )
+          @remote_id = remote_id
+          @window_size = window_size
+          @maximum_packet_size = packet_size
+          callback :confirm_open, self
+        end
+
+        # Invoked when the server failed to confirm the opening of a channel.
+        def do_confirm_failed( reason_code, description, language )
+          @local_id = nil
+          @connection = nil
+          callback :confirm_failed, self, reason_code, description, language
+        end
+
+        # Invoked when the server asks to adjust the window size. This in turn
+        # calls the "on_window_adjust" callback.
+        def do_window_adjust( bytes_to_add )
+          @window_size += bytes_to_add
+          callback :window_adjust, self, bytes_to_add
+        end
+
+        # Invoked when the server sends a data packet. This in turn calls the
+        # "on_data" callback.
+        event :data, :data
+
+        # Invoked when the server sends an extended data packet. This in turn
+        # calls the "on_extended_data" callback.
+        event :extended_data, :type, :data
+
+        # Invoked when the server sends an EOF packet. This in turn calls the
+        # "on_eof" callback.
+        event :eof
+
+        # Invoked when the server sends a request packet. This in turn calls
+        # the "on_request" callback.
+        event :request, :want_reply, :data
+
+        # Invoked when the server sends confirmation of a successful operation.
+        # This in turn invokes the "on_success" callback, if set.
+        event :success
+
+        # Invoked when the server sends notification of a failed operation.
+        # This in turn invokes the "on_failure" callback, if set.
+        event :failure
+
+        #--
+        # ====================================================================
+        # PRIVATE UTILITIES
+        # ====================================================================
+        #++
+
+        # A convenience utility method for invoking a named callback with a
+        # set of arguments.
+        def callback( which, *args )
+          block = instance_variable_get( "@on_#{which.to_s}" )
+          block.call( *args ) if block
+        end
+        private :callback
+
+      end
+
+    end
+  end
+end