net-ssh 1.1.4 → 2.0.0

data/CHANGELOG.rdoc

@@ -0,0 +1,37 @@
+=== 2.0.0 / 1 May 2008
+
+* Allow the :verbose argument to accept symbols (:debug, etc.) as well as Logger level constants (Logger::DEBUG, etc.) [Jamis Buck]
+
+
+=== 2.0 Preview Release 4 (1.99.3) / 19 Apr 2008
+
+* Make sure HOME is set to something sane, even on OS's that don't set it by default [Jamis Buck]
+
+* Add a :passphrase option to specify the passphrase to use with private keys [Francis Sullivan]
+
+* Open a new auth agent connection for every auth-agent channel request [Jamis Buck]
+
+
+=== 2.0 Preview Release 3 (1.99.2) / 10 Apr 2008
+
+* Session properties [Jamis Buck]
+
+* Make channel open failure work with a callback so that failures can be handled similarly to successes [Jamis Buck]
+
+
+=== 2.0 Preview Release 2 (1.99.1) / 22 Mar 2008
+
+* Partial support for ~/.ssh/config (and related) SSH configuration files [Daniel J. Berger, Jamis Buck]
+
+* Added Net::SSH::Test to facilitate testing complex SSH state machines [Jamis Buck]
+
+* Reworked Net::SSH::Prompt to use conditionally-selected modules [Jamis Buck, suggested by James Rosen]
+
+* Added Channel#eof? and Channel#eof! [Jamis Buck]
+
+* Fixed bug in strict host key verifier on cache miss [Mike Timm]
+
+
+=== 2.0 Preview Release 1 (1.99.0) / 21 Aug 2007
+
+* First preview release of Net::SSH v2

data/Manifest

@@ -0,0 +1,101 @@
+CHANGELOG.rdoc
+lib/net/ssh/authentication/agent.rb
+lib/net/ssh/authentication/constants.rb
+lib/net/ssh/authentication/key_manager.rb
+lib/net/ssh/authentication/methods/abstract.rb
+lib/net/ssh/authentication/methods/hostbased.rb
+lib/net/ssh/authentication/methods/keyboard_interactive.rb
+lib/net/ssh/authentication/methods/password.rb
+lib/net/ssh/authentication/methods/publickey.rb
+lib/net/ssh/authentication/pageant.rb
+lib/net/ssh/authentication/session.rb
+lib/net/ssh/buffer.rb
+lib/net/ssh/buffered_io.rb
+lib/net/ssh/config.rb
+lib/net/ssh/connection/channel.rb
+lib/net/ssh/connection/constants.rb
+lib/net/ssh/connection/session.rb
+lib/net/ssh/connection/term.rb
+lib/net/ssh/errors.rb
+lib/net/ssh/key_factory.rb
+lib/net/ssh/known_hosts.rb
+lib/net/ssh/loggable.rb
+lib/net/ssh/packet.rb
+lib/net/ssh/prompt.rb
+lib/net/ssh/proxy/errors.rb
+lib/net/ssh/proxy/http.rb
+lib/net/ssh/proxy/socks4.rb
+lib/net/ssh/proxy/socks5.rb
+lib/net/ssh/service/forward.rb
+lib/net/ssh/test/channel.rb
+lib/net/ssh/test/extensions.rb
+lib/net/ssh/test/kex.rb
+lib/net/ssh/test/local_packet.rb
+lib/net/ssh/test/packet.rb
+lib/net/ssh/test/remote_packet.rb
+lib/net/ssh/test/script.rb
+lib/net/ssh/test/socket.rb
+lib/net/ssh/test.rb
+lib/net/ssh/transport/algorithms.rb
+lib/net/ssh/transport/cipher_factory.rb
+lib/net/ssh/transport/constants.rb
+lib/net/ssh/transport/hmac/abstract.rb
+lib/net/ssh/transport/hmac/md5.rb
+lib/net/ssh/transport/hmac/md5_96.rb
+lib/net/ssh/transport/hmac/none.rb
+lib/net/ssh/transport/hmac/sha1.rb
+lib/net/ssh/transport/hmac/sha1_96.rb
+lib/net/ssh/transport/hmac.rb
+lib/net/ssh/transport/identity_cipher.rb
+lib/net/ssh/transport/kex/diffie_hellman_group1_sha1.rb
+lib/net/ssh/transport/kex/diffie_hellman_group_exchange_sha1.rb
+lib/net/ssh/transport/kex.rb
+lib/net/ssh/transport/openssl.rb
+lib/net/ssh/transport/packet_stream.rb
+lib/net/ssh/transport/server_version.rb
+lib/net/ssh/transport/session.rb
+lib/net/ssh/transport/state.rb
+lib/net/ssh/verifiers/lenient.rb
+lib/net/ssh/verifiers/null.rb
+lib/net/ssh/verifiers/strict.rb
+lib/net/ssh/version.rb
+lib/net/ssh.rb
+Rakefile
+README.rdoc
+setup.rb
+test/authentication/methods/common.rb
+test/authentication/methods/test_abstract.rb
+test/authentication/methods/test_hostbased.rb
+test/authentication/methods/test_keyboard_interactive.rb
+test/authentication/methods/test_password.rb
+test/authentication/methods/test_publickey.rb
+test/authentication/test_agent.rb
+test/authentication/test_key_manager.rb
+test/authentication/test_session.rb
+test/common.rb
+test/configs/exact_match
+test/configs/wild_cards
+test/connection/test_channel.rb
+test/connection/test_session.rb
+test/test_all.rb
+test/test_buffer.rb
+test/test_buffered_io.rb
+test/test_config.rb
+test/test_key_factory.rb
+test/transport/hmac/test_md5.rb
+test/transport/hmac/test_md5_96.rb
+test/transport/hmac/test_none.rb
+test/transport/hmac/test_sha1.rb
+test/transport/hmac/test_sha1_96.rb
+test/transport/kex/test_diffie_hellman_group1_sha1.rb
+test/transport/kex/test_diffie_hellman_group_exchange_sha1.rb
+test/transport/test_algorithms.rb
+test/transport/test_cipher_factory.rb
+test/transport/test_hmac.rb
+test/transport/test_identity_cipher.rb
+test/transport/test_packet_stream.rb
+test/transport/test_server_version.rb
+test/transport/test_session.rb
+test/transport/test_state.rb
+THANKS.rdoc
+Manifest

data/README.rdoc

@@ -0,0 +1,110 @@
+= Net::SSH
+
+* http://net-ssh.rubyforge.org/ssh
+
+== DESCRIPTION:
+
+Net::SSH is a pure-Ruby implementation of the SSH2 client protocol. It allows you to write programs that invoke and interact with processes on remote servers, via SSH2.
+
+== FEATURES:
+
+* Execute processes on remote servers and capture their output
+* Run multiple processes in parallel over a single SSH connection
+* Support for SSH subsystems
+* Forward local and remote ports via an SSH connection
+
+== SYNOPSIS:
+
+In a nutshell:
+
+  require 'net/ssh'
+
+  Net::SSH.start('host', 'user', :password => "password") do |ssh|
+    # capture all stderr and stdout output from a remote process
+    output = ssh.exec!("hostname")
+
+    # capture only stdout matching a particular pattern
+    stdout = ""
+    ssh.exec!("ls -l /home/jamis") do |channel, stream, data|
+      stdout << data if stream == :stdout
+    end
+    puts stdout
+
+    # run multiple processes in parallel to completion
+    ssh.exec "sed ..."
+    ssh.exec "awk ..."
+    ssh.exec "rm -rf ..."
+    ssh.loop
+
+    # open a new channel and configure a minimal set of callbacks, then run
+    # the event loop until the channel finishes (closes)
+    channel = ssh.open_channel do |ch|
+      ch.exec "/usr/local/bin/ruby /path/to/file.rb" do |ch, success|
+        raise "could not execute command" unless success
+
+        # "on_data" is called when the process writes something to stdout
+        ch.on_data do |c, data|
+          $STDOUT.print data
+        end
+
+        # "on_extended_data" is called when the process writes something to stderr
+        ch.on_extended_data do |c, type, data|
+          $STDERR.print data
+        end
+
+        ch.on_close { puts "done!" }
+      end
+    end
+
+    channel.wait
+
+    # forward connections on local port 1234 to port 80 of www.capify.org
+    ssh.forward.local(1234, "www.capify.org", 80)
+    ssh.loop { true }
+  end
+
+See Net::SSH for more documentation, and links to further information.
+
+== REQUIREMENTS:
+
+The only requirement you might be missing is the OpenSSL bindings for Ruby. These are built by default on most platforms, but you can verify that they're built and installed on your system by running the following command line:
+
+  ruby -ropenssl -e 'puts OpenSSL::OPENSSL_VERSION'
+
+If that spits out something like "OpenSSL 0.9.8g 19 Oct 2007", then you're set. If you get an error, then you'll need to see about rebuilding ruby with OpenSSL support, or (if your platform supports it) installing the OpenSSL bindings separately.
+
+Additionally: if you are going to be having Net::SSH prompt you for things like passwords or certificate passphrases, you'll want to have either the Highline (recommended) or Termios (unix systems only) gem installed, so that the passwords don't echo in clear text.
+
+Lastly, if you want to run the tests or use any of the Rake tasks, you'll need:
+
+* Echoe (for the Rakefile)
+* Mocha (for the tests)
+
+== INSTALL:
+
+* gem install net-ssh (might need sudo privileges)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Jamis Buck <jamis@37signals.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,26 @@
+require './lib/net/ssh/version'
+
+begin
+  require 'echoe'
+rescue LoadError
+  abort "You'll need to have `echoe' installed to use Net::SSH's Rakefile"
+end
+
+version = Net::SSH::Version::STRING.dup
+if ENV['SNAPSHOT'].to_i == 1
+  version << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+
+Echoe.new('net-ssh', version) do |p|
+  p.changelog        = "CHANGELOG.rdoc"
+
+  p.author           = "Jamis Buck"
+  p.email            = "jamis@jamisbuck.org"
+  p.summary          = "a pure-Ruby implementation of the SSH2 client protocol"
+  p.url              = "http://net-ssh.rubyforge.org/ssh"
+
+  p.need_zip         = true
+  p.include_rakefile = true
+
+  p.rdoc_pattern     = /^(lib|README.rdoc|CHANGELOG.rdoc|THANKS.rdoc)/
+end

data/{THANKS → THANKS.rdoc}

@@ -9,11 +9,8 @@ Guillaume Mar
   * support for communicating with the the PuTTY "pageant" process
 
 Daniel Berger <djberg96@yahoo.com>
-  * help getting unit tests to pass in Windows
+  * help getting unit tests in earlier Net::SSH versions to pass in Windows
+  * initial version of Net::SSH::Config provided inspiration and encouragement
 
 Chris Andrews <chris@nodnol.org> and Lee Jensen <lee@outerim.com>
   * support for ssh agent forwarding
-
-If you have contributed to Net::SSH and are not on the above list, please do
-not take offense! Jamis is notoriously forgetful. Instead, just let him know
-what your contribution was, and he'll be only too happy to add you.

data/lib/net/ssh.rb

@@ -1,67 +1,199 @@
-#--
-# =============================================================================
-# Copyright (c) 2004,2005 Jamis Buck (jamis@37signals.com)
-# 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
-# =============================================================================
-#++
+# Make sure HOME is set, regardless of OS, so that File.expand_path works
+# as expected with tilde characters.
+ENV['HOME'] ||= ENV['HOMEPATH'] ? "#{ENV['HOMEDRIVE']}#{ENV['HOMEPATH']}" : "."
 
-require 'net/ssh/session'
+require 'logger'
 
-#--
-# 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.
-#++
+require 'net/ssh/config'
+require 'net/ssh/errors'
+require 'net/ssh/loggable'
+require 'net/ssh/transport/session'
+require 'net/ssh/authentication/session'
+require 'net/ssh/connection/session'
 
 module Net
+
+  # Net::SSH is a library for interacting, programmatically, with remote
+  # processes via the SSH2 protocol. Sessions are always initiated via
+  # Net::SSH.start. From there, a program interacts with the new SSH session
+  # via the convenience methods on Net::SSH::Connection::Session, by opening
+  # and interacting with new channels (Net::SSH::Connection:Session#open_channel
+  # and Net::SSH::Connection::Channel), or by forwarding local and/or
+  # remote ports through the connection (Net::SSH::Service::Forward).
+  #
+  # The SSH protocol is very event-oriented. Requests are sent from the client
+  # to the server, and are answered asynchronously. This gives great flexibility
+  # (since clients can have multiple requests pending at a time), but it also
+  # adds complexity. Net::SSH tries to manage this complexity by providing
+  # some simpler methods of synchronous communication (see Net::SSH::Connection::Session#exec!).
+  #
+  # In general, though, and if you want to do anything more complicated than
+  # simply executing commands and capturing their output, you'll need to use
+  # channels (Net::SSH::Connection::Channel) to build state machines that are
+  # executed while the event loop runs (Net::SSH::Connection::Session#loop).
+  #
+  # Net::SSH::Connection::Session and Net::SSH::Connection::Channel have more
+  # information about this technique.
+  #
+  # = "Um, all I want to do is X, just show me how!"
+  #
+  # == X == "execute a command and capture the output"
+  #
+  #   Net::SSH.start("host", "user", :password => "password") do |ssh|
+  #     result = ssh.exec!("ls -l")
+  #     puts result
+  #   end
+  #
+  # == X == "forward connections on a local port to a remote host"
+  #
+  #   Net::SSH.start("host", "user", :password => "password") do |ssh|
+  #     ssh.forward.local(1234, "www.google.com", 80)
+  #     ssh.loop { true }
+  #   end
+  #
+  # == X == "forward connections on a remote port to the local host"
+  #
+  #   Net::SSH.start("host", "user", :password => "password") do |ssh|
+  #     ssh.forward.remote(80, "www.google.com", 1234)
+  #     ssh.loop { true }
+  #   end
   module SSH
+    # This is the set of options that Net::SSH.start recognizes. See
+    # Net::SSH.start for a description of each option.
+    VALID_OPTIONS = [
+      :auth_methods, :compression, :compression_level, :config, :encryption,
+      :forward_agent, :hmac, :host_key, :kex, :keys, :languages,
+      :logger, :paranoid, :password, :port, :proxy, :rekey_blocks_limit,
+      :rekey_limit, :rekey_packet_limit, :timeout, :verbose,
+      :global_known_hosts_file, :user_known_hosts_file, :host_key_alias,
+      :host_name, :user, :properties, :passphrase
+    ]
 
-    # 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
+    # The standard means of starting a new SSH connection. When used with a
+    # block, the connection will be closed when the block terminates, otherwise
+    # the connection will just be returned. The yielded (or returned) value
+    # will be an instance of Net::SSH::Connection::Session (q.v.). (See also
+    # Net::SSH::Connection::Channel and Net::SSH::Service::Forward.)
+    #
+    #   Net::SSH.start("host", "user") do |ssh|
+    #     ssh.exec! "cp /some/file /another/location"
+    #     hostname = ssh.exec!("hostname")
+    #
+    #     ssh.open_channel do |ch|
+    #       ch.exec "sudo -p 'sudo password: ' ls" do |ch, success|
+    #         abort "could not execute sudo ls" unless success
+    #
+    #         ch.on_data do |ch, data|
+    #           print data
+    #           if data =~ /sudo password: /
+    #             ch.send_data("password\n")
+    #           end
+    #         end
+    #       end
+    #     end
+    #
+    #     ssh.loop
+    #   end
+    #
+    # This method accepts the following options (all are optional):
+    #
+    # * :auth_methods => an array of authentication methods to try
+    # * :compression => the compression algorithm to use, or +true+ to use
+    #   whatever is supported.
+    # * :compression_level => the compression level to use when sending data
+    # * :config => set to +true+ to load the default OpenSSH config files
+    #   (~/.ssh/config, /etc/ssh_config), or to +false+ to not load them, or to
+    #   a file-name (or array of file-names) to load those specific configuration
+    #   files. Defaults to +true+.
+    # * :encryption => the encryption cipher (or ciphers) to use
+    # * :forward_agent => set to true if you want the SSH agent connection to
+    #   be forwarded
+    # * :global_known_hosts_file => the location of the global known hosts
+    #   file. Set to an array if you want to specify multiple global known
+    #   hosts files. Defaults to %w(/etc/ssh/known_hosts /etc/ssh/known_hosts2).
+    # * :hmac => the hmac algorithm (or algorithms) to use
+    # * :host_key => the host key algorithm (or algorithms) to use
+    # * :host_key_alias => the host name to use when looking up or adding a
+    #   host to a known_hosts dictionary file
+    # * :host_name => the real host name or IP to log into. This is used
+    #   instead of the +host+ parameter, and is primarily only useful when
+    #   specified in an SSH configuration file. It lets you specify an 
+    #   "alias", similarly to adding an entry in /etc/hosts but without needing
+    #   to modify /etc/hosts.
+    # * :kex => the key exchange algorithm (or algorithms) to use
+    # * :keys => an array of file names of private keys to use for publickey
+    #   and hostbased authentication
+    # * :logger => the logger instance to use when logging
+    # * :paranoid => either true, false, or :very, specifying how strict
+    #   host-key verification should be
+    # * :passphrase => the passphrase to use when loading a private key (default
+    #   is +nil+, for no passphrase)
+    # * :password => the password to use to login
+    # * :port => the port to use when connecting to the remote host
+    # * :properties => a hash of key/value pairs to add to the new connection's
+    #   properties (see Net::SSH::Connection::Session#properties)
+    # * :proxy => a proxy instance (see Proxy) to use when connecting
+    # * :rekey_blocks_limit => the max number of blocks to process before rekeying
+    # * :rekey_limit => the max number of bytes to process before rekeying
+    # * :rekey_packet_limit => the max number of packets to process before rekeying
+    # * :timeout => how long to wait for the initial connection to be made
+    # * :user => the user name to log in as; this overrides the +user+
+    #   parameter, and is primarily only useful when provided via an SSH
+    #   configuration file.
+    # * :user_known_hosts_file => the location of the user known hosts file.
+    #   Set to an array to specify multiple user known hosts files.
+    #   Defaults to %w(~/.ssh/known_hosts ~/.ssh/known_hosts2).
+    # * :verbose => how verbose to be (Logger verbosity constants, Logger::DEBUG
+    #   is very verbose, Logger::FATAL is all but silent). Logger::FATAL is the
+    #   default. The symbols :debug, :info, :warn, :error, and :fatal are also
+    #   supported and are translated to the corresponding Logger constant.
+    def self.start(host, user, options={}, &block)
+      invalid_options = options.keys - VALID_OPTIONS
+      if invalid_options.any?
+        raise ArgumentError, "invalid option(s): #{invalid_options.join(', ')}"
+      end
 
-    # A registry of external (i.e., third-party) services that should be made
-    # available to any SSH session.
-    EXTERNAL_SERVICES = Hash.new
+      files = case options.fetch(:config, true)
+        when true then Net::SSH::Config.default_files
+        when false, nil then []
+        else Array(options[:config])
+        end
+      
+      options = Net::SSH::Config.for(host, files).merge(options)
+      host = options.fetch(:host_name, host)
 
-    # Used by third-parties to register a service that should be made available
-    # to any SSH session when the session is constructed. The block should take
-    # a two parameters--the dependency injection container that should contain
-    # the services, and the service-point for the service being registered.
-    #
-    # The +name+ parameter should be a symbol.
-    def register_service( name, &block )
-      EXTERNAL_SERVICES[ name ] = block
-    end
-    module_function :register_service
+      if !options.key?(:logger)
+        options[:logger] = Logger.new(STDERR)
+        options[:logger].level = Logger::FATAL
+      end
 
+      if options[:verbose]
+        options[:logger].level = case options[:verbose]
+          when Fixnum then options[:verbose]
+          when :debug then Logger::DEBUG
+          when :info  then Logger::INFO
+          when :warn  then Logger::WARN
+          when :error then Logger::ERROR
+          when :fatal then Logger::FATAL
+          else raise ArgumentError, "can't convert #{options[:verbose].inspect} to any of the Logger level constants"
+        end
+      end
+
+      transport = Transport::Session.new(host, options)
+      auth = Authentication::Session.new(transport, options)
+
+      user = options.fetch(:user, user)
+      if auth.authenticate("ssh-connection", user, options[:password])
+        connection = Connection::Session.new(transport, options)
+        if block_given?
+          yield connection
+          connection.close
+        else
+          return connection
+        end
+      else
+        raise AuthenticationFailed, user
+      end
+    end
   end
-end
+end