@@ -4,14 +4,14 @@ == DESCRIPTION: -Net::SCP is a pure-Ruby implementation of the SCP protocol. This operates over SSH (and requires the Net::SSH library), and allows files and directory trees to copied toand from a remote server. +Net::SCP is a pure-Ruby implementation of the SCP protocol. This operates over SSH (and requires the Net::SSH library), and allows files and directory trees to copied to and from a remote server. == FEATURES/PROBLEMS: * Transfer files or entire directory trees to or from a remote host via SCP * Can preserve file attributes across transfers * Can download files in-memory, or direct-to-disk -* Support for OpenURI +* Support for SCP URI's, and OpenURI == SYNOPSIS: README.txt @@ -6,12 +6,75 @@ require 'net/scp/upload' require 'net/scp/download' module Net + + # Net::SCP implements the SCP (Secure CoPy) client protocol, allowing Ruby + # programs to securely and programmatically transfer individual files or + # entire directory trees to and from remote servers. It provides support for + # multiple simultaneous SCP copies working in parallel over the same + # connection, as well as for synchronous, serial copies. + # + # Basic usage: + # + # require 'net/scp' + # + # Net::SCP.start("remote.host", "username", :password => "passwd") do |scp| + # # synchronous (blocking) upload; call blocks until upload completes + # scp.upload! "/local/path", "/remote/path" + # + # # asynchronous upload; call returns immediately and requires SSH + # # event loop to run + # channel = scp.upload("/local/path", "/remote/path") + # channel.wait + # end + # + # Net::SCP also provides an open-uri tie-in, so you can use the Kernel#open + # method to open and read a remote file: + # + # # if you just want to parse SCP URL's: + # require 'uri/scp' + # url = URI.parse("scp://user@remote.host/path/to/file") + # + # # if you want to read from a URL voa SCP: + # require 'uri/open-scp' + # puts open("scp://user@remote.host/path/to/file").read + # + # Lastly, Net::SCP adds a method to the Net::SSH::Connection::Session class, + # allowing you to easily grab a Net::SCP reference from an existing Net::SSH + # session: + # + # require 'net/ssh' + # require 'net/scp' + # + # Net::SSH.start("remote.host", "username", :password => "passwd") do |ssh| + # ssh.scp.download! "/remote/path", "/local/path" + # end + # + # == Progress Reporting + # + # By default, uploading and downloading proceed silently, without any + # outword indication of their progress. For long running uploads or downloads + # (and especially in interactive environments) it is desirable to report + # to the user the progress of the current operation. + # + # To receive progress reports for the current operation, just pass a block + # to #upload or #download (or one of their variants): + # + # scp.upload!("/path/to/local", "/path/to/remote") do |name, sent, total| + # puts "#{name}: #{sent}/#{total}" + # end + # + # Whenever a new chunk of data is recieved for or sent to a file, the callback + # will be invoked, indicating the name of the file (local for downloads, + # remote for uploads), the number of bytes that have been sent or received + # so far for the file, and the size of the file. class SCP include Net::SSH::Loggable include Upload, Download - # When all you want is a quick SCP reference and don't particularly need - # the associated SSH session, you can use the start method. + # Starts up a new SSH connection and instantiates a new SCP session on + # top of it. If a block is given, the SCP session is yielded, and the + # SSH session is closed automatically when the block terminates. If no + # block is given, the SCP session is returned. def self.start(host, username, options={}) session = Net::SSH.start(host, username, options) scp = new(session) @@ -28,6 +91,13 @@ module Net end end + # Starts up a new SSH connection using the +host+ and +username+ parameters, + # instantiates a new SCP session on top of it, and then begins an + # upload from +local+ to +remote+. If the +options+ hash includes an + # :ssh key, the value for that will be passed to the SSH connection as + # options (e.g., to set the password, etc.). All other options are passed + # to the #upload! method. If a block is given, it will be used to report + # progress (see "Progress Reporting", under Net::SCP). def self.upload!(host, username, local, remote, options={}, &progress) options = options.dup start(host, username, options.delete(:ssh) || {}) do |scp| @@ -35,6 +105,13 @@ module Net end end + # Starts up a new SSH connection using the +host+ and +username+ parameters, + # instantiates a new SCP session on top of it, and then begins a + # download from +remote+ to +local+. If the +options+ hash includes an + # :ssh key, the value for that will be passed to the SSH connection as + # options (e.g., to set the password, etc.). All other options are passed + # to the #download! method. If a block is given, it will be used to report + # progress (see "Progress Reporting", under Net::SCP). def self.download!(host, username, remote, local=nil, options={}, &progress) options = options.dup start(host, username, options.delete(:ssh) || {}) do |scp| @@ -42,25 +119,77 @@ module Net end end + # The underlying Net::SSH session that acts as transport for the SCP + # packets. attr_reader :session + # Creates a new Net::SCP session on top of the given Net::SSH +session+ + # object. def initialize(session) @session = session self.logger = session.logger end + # Inititiate a synchronous (non-blocking) upload from +local+ to +remote+. + # The following options are recognized: + # + # * :recursive - the +local+ parameter refers to a local directory, which + # should be uploaded to a new directory named +remote+ on the remote + # server. + # * :preserve - the atime and mtime of the file should be preserved. + # * :verbose - the process should result in verbose output on the server + # end (useful for debugging). + # + # This method will return immediately, returning the Net::SSH::Connection::Channel + # object that will support the upload. To wait for the upload to finish, + # you can either call the #wait method on the channel, or otherwise run + # the Net::SSH event loop until the channel's #active? method returns false. + # + # channel = scp.upload("/local/path", "/remote/path") + # channel.wait def upload(local, remote, options={}, &progress) start_command(:upload, local, remote, options, &progress) end + # Same as #upload, but blocks until the upload finishes. Identical to + # calling #upload and then calling the #wait method on the channel object + # that is returned. The return value is not defined. def upload!(local, remote, options={}, &progress) upload(local, remote, options, &progress).wait end + # Inititiate a synchronous (non-blocking) download from +remote+ to +local+. + # The following options are recognized: + # + # * :recursive - the +remote+ parameter refers to a remote directory, which + # should be downloaded to a new directory named +local+ on the local + # machine. + # * :preserve - the atime and mtime of the file should be preserved. + # * :verbose - the process should result in verbose output on the server + # end (useful for debugging). + # + # This method will return immediately, returning the Net::SSH::Connection::Channel + # object that will support the download. To wait for the download to finish, + # you can either call the #wait method on the channel, or otherwise run + # the Net::SSH event loop until the channel's #active? method returns false. + # + # channel = scp.download("/remote/path", "/local/path") + # channel.wait def download(remote, local, options={}, &progress) start_command(:download, local, remote, options, &progress) end + # Same as #download, but blocks until the download finishes. Identical to + # calling #download and then calling the #wait method on the channel + # object that is returned. + # + # scp.download!("/remote/path", "/local/path") + # + # If +local+ is nil, and the download is not recursive (e.g., it is downloading + # only a single file), the file will be downloaded to an in-memory buffer + # and the resulting string returned. + # + # data = download!("/remote/path") def download!(remote, local=nil, options={}, &progress) destination = local ? local : StringIO.new download(remote, destination, options, &progress).wait lib/net/scp.rb @@ -8,7 +8,7 @@ module URI def buffer_open(buf, proxy, open_options) options = open_options.merge(:port => port, :password => password) progress = options.delete(:progress_proc) - buf << Net::SCP.download(host, user, path, nil, open_options, &progress) + buf << Net::SCP.download!(host, user, path, nil, open_options, &progress) buf.io.rewind end lib/uri/open-scp.rb b90295cdbd469820ab3a3815e2ed0ab11e9072cb Jamis Buck jamis@37signals.com http://github.com/jamis/net-scp/commit/415405aa5a4e8da5a249b821ef3f99ce0c73a0c4 415405aa5a4e8da5a249b821ef3f99ce0c73a0c4 2008-03-15T19:49:53-07:00 2008-03-15T19:49:53-07:00 go with bang convention for blocking calls. start adding more rdocs addd261d5b8579f55e774c87a9ede8e44702d1ab Jamis Buck jamis@37signals.com